Metadata-Version: 2.4
Name: agentshield-security
Version: 1.0.0
Summary: AI Agent Runtime Security Sandbox - 面向AI Agent的运行时安全防护沙箱
Home-page: https://github.com/agent-shield/agentshield
Author: AgentShield Team
Author-email: agent-shield@example.com
Project-URL: Bug Reports, https://github.com/agent-shield/agentshield/issues
Project-URL: Source, https://github.com/agent-shield/agentshield
Project-URL: Documentation, https://agent-shield.readthedocs.io/
Keywords: ai agent security sandbox prompt-injection detection
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: pyyaml>=6.0
Provides-Extra: bert
Requires-Dist: transformers>=4.38.0; extra == "bert"
Requires-Dist: torch>=2.0.0; extra == "bert"
Provides-Extra: langchain
Requires-Dist: langchain>=0.1.0; extra == "langchain"
Provides-Extra: all
Requires-Dist: transformers>=4.38.0; extra == "all"
Requires-Dist: torch>=2.0.0; extra == "all"
Requires-Dist: langchain>=0.1.0; extra == "all"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# AgentShield — 面向AI Agent的运行时安全防护沙箱

全国大学生信息安全竞赛（作品赛）参赛作品

## 项目简介

AgentShield 是首个针对 **AI Agent** 的**运行时安全防护沙箱**。随着LangChain、CrewAI、AutoGen等Agent框架的爆发式增长，Agent安全已成为最紧迫的AI安全问题——Agent可以被诱导执行恶意操作、泄露敏感数据、甚至被完全劫持。

与现有工具（Lakera Guard、Rebuff等"输入/输出过滤器"）不同，AgentShield 提供**操作系统级别的安全防护**：

```
现有工具：用户输入 → [过滤器] → LLM → [过滤器] → 输出
AgentShield：Agent操作 → [安全策略] → [沙箱] → [行为监控] → [审计]
```

### 六大创新模块

| 模块 | 全称 | 功能 |
|------|------|------|
| **TSPE** | 工具安全策略引擎 | 为每个工具定义细粒度安全策略 |
| **TOS** | 工具输出净化器 | 检测工具返回数据中的间接注入 |
| **ABS** | 行为沙箱 | 限制Agent的文件/网络/代码执行权限 |
| **OSA** | 操作序列分析 | 分析多步操作序列，检测"单步合法、多步恶意"的攻击 |
| **DPC** | 动态权限控制 | 根据任务上下文动态授予权限，最小权限原则 |
| **审计报告** | 可解释审计 | 攻击路径还原、注入位置定位、修复建议 |

## 快速开始

```bash
# 1. 安装依赖
pip install -r requirements.txt

# 2. 启动（Windows）
start.bat

# 或手动启动
cd src
set PYTHONPATH=%cd%
python -m uvicorn backend.main:app --host 0.0.0.0 --port 8000
```

访问地址：

| 页面 | 地址 |
|------|------|
| 主页 | http://localhost:8000 |
| 实时防护演示 | http://localhost:8000/static/chat.html |
| Agent安全运营中心 | http://localhost:8000/static/agent.html |
| API文档 | http://localhost:8000/docs |

## 真实检测能力

AgentShield 使用多层检测引擎：

1. **规则引擎**（<1ms）：正则表达式快速筛选已知攻击模式
2. **BERT模型**（~10ms）：预训练深度学习模型检测未知攻击
3. **Canary Token**：隐藏标记检测系统提示词泄露

### 使用 BERT 检测

```python
from backend.core.tool_output_sanitizer import ToolOutputSanitizer

# 启用BERT检测
tos = ToolOutputSanitizer(use_bert=True)

result = tos.sanitize("Ignore all previous instructions...")
if not result.is_safe:
    print(f"检测到攻击: {result.explanation}")
```

### 使用 Canary Token

```python
from backend.core.canary_token import CanaryToken

token = CanaryToken()
safe_prompt = token.inject("You are a helpful assistant.")
# ... 将 safe_prompt 传给 LLM ...
if token.check(llm_output):
    print("警告：系统提示词可能被泄露！")
```

### LangChain 集成

```python
from integrations.langchain_callback import AgentShieldCallback
from backend.core.agent_shield import AgentShield

shield = AgentShield()
callback = AgentShieldCallback(shield, use_bert=True)

# 在 Agent 执行时传入回调
result = agent_executor.invoke(
    {"input": "用户消息"},
    config={"callbacks": [callback]}
)
```

## 运行测试

```bash
PYTHONPATH=src python tests/test_tspe.py        # 7个测试
PYTHONPATH=src python tests/test_tos.py         # 9个测试
PYTHONPATH=src python tests/test_sandbox.py     # 11个测试
PYTHONPATH=src python tests/test_osa.py         # 6个测试
PYTHONPATH=src python tests/test_dpc.py         # 8个测试
PYTHONPATH=src python tests/test_audit.py       # 6个测试
PYTHONPATH=src python tests/test_shield.py      # 10个测试
PYTHONPATH=src python tests/test_api.py         # 86个测试
PYTHONPATH=src python tests/test_integration.py # 44个测试
PYTHONPATH=src python tests/test_performance.py # 性能基准
PYTHONPATH=src python tests/test_bert_detector.py  # BERT检测
PYTHONPATH=src python tests/test_canary_token.py   # Canary Token
PYTHONPATH=src python tests/test_langchain_callback.py # LangChain集成
PYTHONPATH=src python tests/test_e2e_detection.py  # 端到端测试
```

共 **200+个测试**，全部通过。

## 技术栈

| 层次 | 技术 |
|------|------|
| 前端 | Vue 3 CDN + ECharts |
| 后端 | Python 3.10+ + FastAPI |
| Agent框架 | LangChain（Demo Agent） |
| 规则引擎 | 正则表达式 + YAML策略定义 |
| 数据库 | SQLite |

## 目录结构

```
agent-shield/
├── configs/                # 配置文件
│   ├── config.yaml        # 主配置
│   └── policies/          # 工具安全策略
├── src/                    # 源代码
│   ├── backend/           # 后端服务
│   │   ├── api/           # API路由 (agents/events/policies/stats/chat)
│   │   ├── core/          # 6大安全模块
│   │   ├── models/        # 数据模型
│   │   └── database/      # 数据库
│   ├── demo/              # Demo Agent
│   │   ├── tools/         # 5个Demo工具
│   │   └── attack_scenarios/ # 10个攻击场景
│   ├── frontend/          # 前端 (index/chat/agent)
│   └── integrations/      # 框架集成
├── data/                   # 测试数据 + 投毒样本
├── tests/                  # 187个测试
├── scripts/                # 演示脚本
├── Dockerfile              # Docker部署
├── start.bat               # Windows一键启动
└── docs/                   # 文档

## 攻击场景演示

| # | 场景 | 攻击手法 | AgentShield防护 |
|---|------|---------|----------------|
| 1 | 订单查询间接注入 | 数据投毒 | TOS检测指令性内容 |
| 2 | 代码执行恶意注入 | 代码注入 | ABS阻止危险导入 |
| 3 | 邮件参数注入 | 参数注入 | TSPE检测非白名单域名 |
| 4 | 多步操作链劫持 | 操作链劫持 | OSA检测目标偏离 |
| 5 | 权限提升攻击 | 权限提升 | DPC+ABS+OSA多层防护 |
| 6 | 记忆投毒攻击 | 长期记忆污染 | TOS检测隐藏指令 |
| 7 | 同形字攻击 | Unicode混淆 | TOS异常Unicode检测 |
| 8 | SQL注入攻击 | 参数注入 | TSPE禁止关键词检测 |
| 9 | 路径遍历攻击 | 路径穿越 | ABS黑名单+路径检测 |
| 10 | SSRF攻击 | 内网访问 | ABS内网地址拦截 |

## 参考文献

1. Greshake et al., "Not what you've signed up for: Compromising Real-World LLM-Integrated Applications with Indirect Prompt Injection", AISec 2023
2. Debenedetti et al., "AgentDojo: A Dynamic Environment to Evaluate Attacks and Defenses for LLM Agents", 2024
3. Zhan et al., "InjecAgent: Benchmarking Indirect Prompt Injections in Tool-Integrated LLM Agents", 2024
4. Ruan et al., "Identifying the Risks of LM Agents with an LM-Emulated Sandbox", 2024
5. Wallace et al., "Defending Against Prompt Injection With Instruction Hierarchy", OpenAI 2024
6. OWASP, "Agentic Top 10", 2025
