# 🛡️ AgentShield
AgentShield 是一款强大、企业级的 AI 代理安全防火墙，旨在实时拦截、分析和消除安全漏洞、越狱尝试和提示注入攻击。通过利用多层安全架构，AgentShield 在不改变现有业务逻辑的前提下保护您的 AI 系统。
## ✨ 功能
- **🛡️ 多层提示注入防御**：采用高级启发式匹配已知的越狱模式、对抗性模板、Base64/十六进制编码逃逸以及零宽空格。
- **🔤 同形文字标准化**：通过 NFKC Unicode 标准化，将视觉模仿攻击（例如，西里尔字母或希腊字母相似字符，如 `ιgnοrε ρrενιους`）解析为标准拉丁表示。
- **🤖 机器学习分类器**：采用 TF-IDF 向量化器 + 逻辑回归流水线，旨在动态检测新颖、未见过的注入向量。
- **📈 基于时间的异常跟踪器**：分析每个客户端/用户身份在滚动窗口内的威胁，以标记暴力探索或扫描尝试。
- **🛠️ 工具调用防护**：验证工具参数并防止未经授权的操作系统命令执行（例如，`subprocess.run`、`eval`、`shutil.rmtree`）。
- **🔒 身份验证与加密隔离**：集成需要安全问题的身份验证层。成功验证身份后，通过 PBKDF2（100,000 轮）派生一个 32 字节主密钥，用于加密和隔离本地存储。
- **💾 加密本地内存**：采用 AES-256（Fernet）的客户端内存层，确保敏感凭据或对话历史记录零明文泄露。
- **🔌 自动保护中间件**：通过明确的单行猴子补丁（`import agentshield; agentshield.init()`）自动保护 `openai` 资源和对 AI 模型端点的传出 `requests`。
- **🏷️ 数据脱敏与泄露阻断**：自动编辑敏感模式（如 Bearer 令牌/API 密钥）并剥离 Markdown 数据外泄链接。
## 🚀 快速入门
### 1. 安装
直接从 PyPI 安装 AgentShield：
```
pip install agentshield-firewall
```
或在本地安装：
```
pip install .
```
### 2. 配置身份验证配置文件
设置您的安全问题、答案并检索恢复代码：
```
python setup_auth.py
```
### 3. 在代码中集成
在您的应用程序中通过单行初始化全局启用 AgentShield：
```
import agentshield
agentshield.init()
# 大功告成！您的 OpenAI 调用和外部请求现已受到保护。
```
或者，使用 `@secure_agent` 装饰器保护特定的代理函数：
```
from agentshield import secure_agent
@secure_agent()
def run_my_agent(user_prompt: str) -> str:
# Your LLM logic here
return response
```
## 🎨 交互式演示与仪表盘
AgentShield 包含一个网络安全仪表盘，用于测试不同的 LLM 安全逃逸向量：
1. 启动本地服务器：
python -m http.server 8000 --directory docs
2. 在您的网页浏览器中打开 [http://localhost:8000](http://localhost:8000)。
3. 选择攻击预设，如**同形文字逃逸**或**JSON 注入**，并观察 AgentShield 实时阻止它们。
## 🧪 测试
运行完整的防火墙安全套件：
```
python test_shield.py
```
运行身份验证和加密隔离测试套件：
```
python test_auth.py
```
运行自动化库拦截和补丁测试：
```
python test_auto_protect.py
```
## 📁 仓库结构
```
agentshield/
├── auth.py # Identity management & Master Key derivation
├── encrypted_memory.py # AES-256 encrypted database client-storage
├── firewall.py # Main AgentShieldFirewall orchestration
├── rules.py # Pattern matchers, split-token & structured parser
├── config.py # Security thresholds and redaction configurations
├── ml_classifier.py # Fallback-safe TF-IDF Machine Learning model
├── anomaly.py # Threat scoring statistics and rolling window tracking
├── auto_protect.py # Monkey patching hooks for OpenAI and network requests
├── sitecustomize_injector.py # Global bootstrap register tool
├── wrappers.py # Client decorators (@secure_agent, @rate_limit)
├── setup.py # Setuptools installer
├── requirements.txt # Optional machine learning dependencies
└── test_shield.py # Comprehensive unit tests
```
## 🛡️ 许可证
本项目采用 Apache 2.0 许可证授权。