内容
# AgentGuard
**自主AI代理的安全防护栏。策略强制执行、防篡改审计日志和LLM API过滤 - 代理甚至不知道它正在被防护。**
[](https://github.com/Roboter-Schlafen-Nicht/agentguard/actions/workflows/ci.yml)
[](https://www.gnu.org/licenses/agpl-3.0)
[](https://www.python.org/downloads/)
---
## 问题
AI编码代理运行shell命令、读取您的密钥并写入生产文件。今天，在LLM和您的系统之间**没有任何东西**，除了信任。
这种信任是被误置的：
- 提示注入可以使代理`rm -rf /`或`git push --force`
- 一个幻觉模型可以覆盖`.env`为垃圾
- 机密和PII泄漏到LLM提示中 - 发送到第三方API
- LLM响应可以包含注入的指令或渗出尝试
- 没有代理实际执行的操作的审计轨迹
- 合规团队没有证据证明AI操作受到监督
## 解决方案
AgentGuard在**两个层面**保护AI代理：
1. **MCP服务器** - 位于代理和您的操作系统之间。拦截`shellexecute`、`fileread`、`filewrite`、`fileedit`、`fileglob`、`filegrep`和`filelist`调用。在执行前强制执行策略。与任何MCP客户端配合使用（参见下面的执行级别）。
2. **LLM API代理** - 位于代理和LLM API之间。扫描 outbound 提示中的机密/PII，然后再发送到LLM。实时扫描 inbound 响应中的提示注入和渗出模式，包括流式传输（SSE）。在流式传输过程中终止危险流。针对简单任务，将请求路由到更便宜的模型（模型路由）。通过上下文压缩，压缩冗长的对话，然后再转发，节省每个请求的代币和费用。
<p align="center">
<img src="docs/architecture.svg" alt="AgentGuard architecture diagram" width="800">
</p>
**代理不知道它正在被防护。** 零提示工程。LLM无需配合。
## 快速入门
### MCP服务器 - 防护工具调用
安装并将您的MCP客户端指向AgentGuard：
```bash
pip install agentguard[mcp]
```
```json
{
"mcpServers": {
"agentguard": {
"command": "python",
"args": ["-m", "agentguard", "serve", "--preset", "balanced", "--audit-dir", "audit/"]
}
}
}
```
现在，每个`shellexecute`、`fileread`、`filewrite`、`fileedit`、`fileglob`、`filegrep`和`filelist`调用都通过AgentGuard。被拒绝的操作永远不会执行。所有操作都会被记录。
### MCP客户端强制执行
AgentGuard的MCP服务器提供8种操作工具和4种辅助工具。强制执行范围取决于MCP客户端是否具有绕过MCP服务器的原生工具：
| 客户端 | 原生工具？ | 完全强制执行？ | 备注 |
|--------|:---:|:---:|---|
| **Claude Desktop** | 否 | ✅ 是 | 所有工具都来自MCP - 完全覆盖 |
| **OpenCode** | 是 | ✅ 是 | 在配置中拒绝原生工具（参见下文） |
| **Cursor** | 是 | ⚠️ 部分 | 原生工具绕过AgentGuard |
| **Windsurf** | 是 | ⚠️ 部分 | 原生工具绕过AgentGuard |
| **VS Code Copilot** | 是 | ⚠️ 部分 | 原生工具绕过AgentGuard |
| **Cline** | 是 | ⚠️ 部分 | 原生工具绕过AgentGuard |
| **Zed** | 是 | ⚠️ 部分 | 原生工具绕过AgentGuard |
对于无法禁用的原生工具，AgentGuard仍然会对通过MCP服务器的所有调用强制执行策略 - 但代理也可以使用完全绕过强制执行的原生工具。
**OpenCode完全强制执行：** 在您的`opencode.json`中添加权限拒绝，以将所有操作路由到AgentGuard：
```json
{
"permission": {
"bash": "deny",
"read": "deny",
"edit": "deny",
"write": "deny",
"glob": "deny",
"grep": "deny"
}
}
```
### LLM API代理 - 防护提示和响应
```bash
pip install agentguard[proxy]
```
```bash
agentguard proxy https://api.openai.com \
--builtins \
--scan-responses \
--audit-dir audit/ \
--port 8080
```
将代理的API基准URL指向`http://localhost:8080`而不是`https://api.openai.com`。AgentGuard透明地转发请求，同时扫描双向的策略违规：
- ** outbound ** - 阻止机密、API密钥、PII和内部路径泄漏到提示中
- ** inbound ** - 扫描流式响应中的提示注入、角色劫持和数据渗出模式。如果检测到违规，终止SSE流并注入警告。
与OpenAI、Azure OpenAI、GitHub Copilot和任何OpenAI兼容的API（LiteLLM、vLLM、Ollama等）兼容，通过内置的提供商适配器。
## 功能
### 策略引擎
基于正则表达式的YAML策略，拒绝模式。针对工具调用（`shellexecute`、`fileread`、`filewrite`、`fileedit`、`fileglob`、`filegrep`、`filelist`）和LLM流量（`llmrequest`、`llmresponse`）分别执行操作种类。可选的`scan`字段针对LLM消息的特定部分（`messages`、`system`、`content`、`all`）。
```yaml
# policies/safety.yaml
name: prevent-disasters
description: Block destructive operations
rules:
- action: shell_execute
deny:
- pattern: "git push.*--force"
- pattern: "git reset --hard"
- pattern: "rm -rf /"
severity: critical
- action: file_write
deny:
- pattern: '\.env$'
- pattern: 'credentials'
severity: critical
```
```python
from agentguard import Guard
guard = Guard()
guard.load_policy_file("policies/safety.yaml")
result = guard.check("shell_execute", command="git push --force origin main")
assert result.denied
# "Blocked by policy: prevent-disasters"
```
### 11种内置策略
配备有合理的默认值 - 使用`--builtins`加载：
| 策略 | 层 | 它阻止的内容 |
|--------|-------|----------------|
| `no-force-push` | 工具 | `git push --force`，`git reset --hard` |
| `no-data-deletion` | 工具 | `rm -rf /`，`DROP TABLE`，`DELETE FROM` |
| `no-secret-exposure` | 工具 | 读取`.env`，凭证，密钥文件 |
| `no-env-commit` | 工具 | 提交`.env`或凭证文件 |
| `no-hook-bypass` | 工具 | `--no-verify`， `--no-gpg-sign` |
| `no-secret-in-prompt` | 代理 | 提示中的API密钥，令牌，密码 |
| `no-pii-leak` | 代理 | 提示中的电子邮件地址，SSN，电话号码 |
| `no-internal-paths` | 代理 | 内部主机名，IP，基础设施路径 |
| `no-prompt-injection` | 代理 | “忽略以前的指令”和变体 |
| `no-persona-jailbreak` | 代理 | DAN，角色覆盖，系统提示注入 |
| `detect-drift-triggers` | 代理 | 元反射提示，情感操纵，宏伟的响应 |
### 防篡改审计日志
每个操作都记录在一个哈希链接的JSONL日志中。每个条目都通过SHA-256链接到前一个条目 - 如果有人篡改单个条目，链条就会断裂：
```python
from agentguard.audit import AuditLog
log = AuditLog("session-001")
log.record(action="shell_execute", actor="agent-001", target="ls -la", result="allowed")
log.save("audit/session-001.jsonl")
assert log.verify() # True - 链完整
```
### 运行时防护栏
`Guardrail`类将策略检查、执行和审计日志记录组合成单个调用：
```python
from agentguard import Guardrail, Guard
from agentguard.audit import AuditLog
from agentguard.guardrails import ActionResult
guard = Guard()
audit = AuditLog("session")
def my_interceptor(action_kind: str, **params: str) -> ActionResult:
return ActionResult(action_kind=action_kind, params=params, executed=True, output="ok")
guardrail = Guardrail(guard=guard, interceptor=my_interceptor, audit_log=audit)
result = guardrail.execute("shell_execute", command="echo hello")
```
### 欧盟AI法合规报告
从审计数据生成结构化合规报告，映射到第9条（风险管理）、第12条（记录保存）、第13条（透明度）和第14条（人工监督）：
```python
from agentguard.compliance import EUAIActReportGenerator, render_json
generator = EUAIActReportGenerator()
report = generator.generate(audit)
render_json(report, output="compliance-report.json")
```
```bash
agentguard report eu-ai-act audit/session.jsonl --format json --output report.json
```
### 外发扫描器
独立于策略引擎的文本中敏感内容的程序化检测。 18个正则表达式模式，涵盖3类：
```python
from agentguard.proxy.outbound import scan_text, FindingCategory
findings = scan_text("My API key is sk-abc123xyz")
# [Finding(category=SECRET, name="openai_api_key", ...)]
```
### 入侵扫描器（流式）
具有滑动窗口的流感知响应扫描器。 增量馈送SSE块，针对累积内容运行策略检查，并在检测到违规时发出信号：
```python
from agentguard.proxy.inbound import InboundScanner
scanner = InboundScanner(guard)
for chunk in sse_stream:
result = scanner.feed(chunk)
if result is not None:
# 检测到策略违规 - 终止流
break
summary = scanner.finalize()
```
### 提供者适配器
不同LLM API的可插拔格式适配器。 `Provider`协议定义请求/响应解析和流内容提取。 配备OpenAI适配器； 自动检测或显式设置：
```python
from agentguard.proxy.providers import get_provider, list_providers
provider = get_provider("openai")
params = provider.extract_request_params(body)
content = provider.extract_stream_content(sse_data)
```
### 上下文压缩
长期运行的代理会话会产生大量的对话历史 - 100K +个代币的过时工具输出，重复的文件读取和冗长的命令结果。 代理在转发到上游LLM之前压缩这些内容，从而节省每个请求的代币：
**阶段1 - 基于规则的截断**（确定性，零延迟）：
- 将旧工具输出截断为第一行和最后一行N行
- 完全跳过非常旧的工具结果（`[compacted: ran bash]`）
- 重复的文件读取只保留最新的
**第2阶段 - 本地模型总结** （当第1阶段不够用时）：
- 通过本地推理服务器总结旧的对话片段
- 保留最近的回合原文以保持上下文连续性
- 如果本地模型不可用，则优雅地回退
```bash
agentguard proxy https://api.openai.com \
--compaction \
--compaction-budget 30000 \
--compaction-model qwen2.5-coder:3b \
--compaction-url http://localhost:11434 \
--compaction-log-dir /var/log/agentguard \
--audit-dir audit/
```
压缩指标（使用的阶段，之前/之后的代币）记录在每个审计日志条目中，因此您可以随着时间的推移衡量节省的代币。
### 模型路由
根据任务复杂性将请求路由到不同的LLM模型。 简单查询发送到快速、便宜的模型（Haiku，成本为0.33倍）；复杂推理发送到高级模型（Opus，成本为3倍）。 DistilBERT分类器实时评估查询难度：
```bash
agentguard proxy https://api.openai.com \
--routing-config routing.yaml \
--classifier-url http://localhost:11435 \
--routing-log-dir /var/log/agentguard \
--audit-dir audit/
```
```yaml
# routing.yaml
routing:
enabled: true
tiers:
- name: fast
model: claude-haiku-4.5
max_difficulty: 2 # 简单 + 中等查询
- name: premium
model: claude-opus-4.5
# 没有最大难度 = 复杂时的默认路由
```
分类器提取最后一个用户消息（跳过工具结果）并返回难度分数（1=简单，2=中等，3=复杂）。 失败-开放：如果分类器不可用，请求将传递给原始模型。
路由决策记录结构化指标（层、模型、原因、难度）以进行成本分析。
### 增量扫描
默认情况下，代理在每个请求上扫描整个对话。 使用`--delta-scanning`，它跟踪哪些消息已经扫描并且只检查新的消息 - 消除了冗余工作并防止旧对话内容中出现与旧内容中的模式类似的误报：
```bash
agentguard proxy https://api.openai.com \
--delta-scanning \
--builtins \
--audit-dir audit/
```
### 策略沙盒
在部署到生产环境之前测试策略。 沙盒运行场景驱动的验证针对您的策略集，检测反馈循环（触发彼此的策略），并在配置的阈值上控制部署：
```bash
# 运行所有沙盒场景
agentguard sandbox run --policy-dir policies/ --scenarios scenarios/
# 部署门控：TPR >= 95%，FPR <= 5%
agentguard sandbox gate --policy-dir policies/ --scenarios scenarios/
# 生成验证报告
agentguard sandbox report --policy-dir policies/ --scenarios scenarios/
```
### 审计日志轮换和保留
审计日志在超过大小或年龄阈值时会自动轮换。 旧的旋转文件会根据文件数量、年龄或总大小限制进行清理：
```bash
agentguard proxy https://api.openai.com \
--audit-dir audit/ \
--max-log-bytes 10485760 \
--max-log-age 86400 \
--max-log-files 10 \
--retain-max-age 604800
```
```python
from agentguard.audit.rotation import RotationConfig
from agentguard.audit.retention import RetentionConfig
rotation = RotationConfig(max_bytes=10_485_760, max_age_seconds=86400)
retention = RetentionConfig(max_files=10, max_age_seconds=604800)
```
### 网络抓取工具
MCP服务器包括`web_fetch_js` - 一个无头浏览器支持的网络抓取器，它在返回内容之前渲染JavaScript。 返回干净的markdown、HTML或适合LLM消费的纯文本：
```python
# 可作为MCP工具使用：agentguard_web_fetch_js
# 支持：markdown，html，text输出格式
# 可配置超时和robots.txt合规性
```
### MCP侧工具
MCP服务器公开`agentguard_status`（加载的策略和会话信息），`agentguard_audit_query`（按操作、结果或执行者搜索审计），`agentguard_trust_query`（查找服务器信任级别）和`agentguard_scan_package`（扫描MCP服务器的安全风险）- 因此您可以询问代理“当前激活的策略是什么？”，“显示我所有被拒绝的操作”，或“扫描此MCP服务器在我安装它之前。”
### MCP操作工具
除了`shellexecute`、`fileread`和`filewrite`之外，MCP服务器提供：
| 工具 | 描述 |
|------|-------------|
| `file_edit` | 文件中的精确字符串替换 |
| `file_glob` | 基于模式的文件搜索（按mtime排序） |
| `file_grep` | 带有文件过滤的正则表达式内容搜索 |
| `file_list` | 目录列表，忽略模式 |
| `web_fetch_js` | JS渲染的网络抓取器（无头浏览器） |
所有8种操作工具都强制执行策略并记录到审计轨迹中。
### 保护级别预设
用于快速设置的命名策略包。 三个级别在安全性方面进行权衡：
| 预设 | 策略 | 用例 |
|--------|:---:|---|
| `permissive` | 3 | 开发 - 仅阻止灾难性操作 |
| `balanced` | 8 | 默认 - 涵盖工具和基本LLM过滤 |
| `strict` | 11 | 生产 - 包括漂移检测的所有策略 |
```bash
# CLI - 与--builtins互斥
agentguard serve --preset balanced --audit-dir audit/#
# MCP配置
{
"args": ["-m", "agentguard", "serve", "--preset", "strict", "--audit-dir", "audit/"]
}
```
```python
from agentguard import Preset, load_preset
policies = load_preset(Preset.BALANCED)
# 返回8个Policy对象准备加载到Guard中```
### 信任注册表
具有基于哈希完整性验证的持久信任级别。 跟踪哪些服务器是受信任的、受限制的或不信任的，并验证包完整性后再执行。
```bash
# 注册服务器并设置信任级别
agentguard trust add my-server --level trusted \
--package-path /path/to/server --command "python -m my_server"
# 验证包完整性
agentguard trust verify my-server --package-path /path/to/server
# 列出所有注册的服务器
agentguard trust list --format json
```
```python
from agentguard import TrustRegistry, TrustLevel
registry = TrustRegistry()
registry.add("my-server", TrustLevel.TRUSTED,
package_path="/path/to/server",
command="python -m my_server")
entry = registry.get("my-server")
assert entry.verify_hash("/path/to/server") # True - 包未更改
```
信任数据保存在`~/.agentguard/trust-registry.yaml`中。MCP服务器公开`agentguard_trust_query`以便代理访问查询。
### 包扫描器
按需对MCP服务器源代码进行静态分析。基于正则表达式的逐行检测，涵盖6大风险类别，内置22+规则：
| 类别 | 示例 |
|----------|---------|
| 数据外泄 | HTTP请求、WebSockets、DNS、SMTP、base64编码 |
| 文件系统访问 | 敏感路径（`/etc/passwd`、`.ssh/`）、递归遍历、`.env` |
| 代码执行 | `eval`/`exec`、子进程、ctypes、动态导入 |
| 凭证访问 | 硬编码密钥、环境变量查找、密钥环访问 |
| 持久化 | Cron作业、启动文件、systemd、运行时pip安装 |
| 混淆 | 十六进制解码、逐字符构造、marshal |
```bash
agentguard scan /path/to/mcp-server-package
agentguard scan /path/to/package --format json --min-severity high
```
```python
from agentguard import Scanner
scanner = Scanner()
result = scanner.scan("/path/to/mcp-server-package")
print(result.finding_count, result.max_severity)
for finding in result.findings:
print(f"[{finding.severity.value}] {finding.rule_id}: {finding.message}")
print(f" at {finding.file_path}:{finding.line_number}")
```
> **注意：** 扫描器是一个**初步排查的安全网**，而非安全边界。基于正则表达式的检测可以通过字符串拼接、编码或间接方式被对抗性代码绕过。它可以捕获意外风险和低复杂度威胁，但不应作为对抗恶意包的唯一防御手段。
## 命令行界面
```
agentguard version 打印版本
agentguard policies [--dir DIR] [--builtins] 列出已加载的策略
agentguard check ACTION [--params K=V ...] 测试策略
agentguard audit verify FILE 验证审计日志完整性
agentguard audit query FILE [--action ...] 查询审计记录
agentguard report FRAMEWORK FILE 生成合规报告
agentguard serve [--builtins|--preset LEVEL] 启动MCP服务器
agentguard proxy URL [--scan-responses] 启动LLM API代理
agentguard scan PATH [--format FMT] 扫描包的安全风险
agentguard sandbox run [--policy-dir DIR] 运行策略沙盒场景
agentguard sandbox gate [--policy-dir DIR] 根据TPR/FPR阈值控制部署
agentguard sandbox report [--policy-dir DIR] 生成沙盒验证报告
agentguard trust add NAME [--level LEVEL] 注册信任服务器
agentguard trust remove NAME 删除服务器
agentguard trust list [--level LEVEL] 列出已注册服务器
agentguard trust show NAME 显示服务器详情
agentguard trust verify NAME --package-path 验证包完整性
agentguard trust update-hash NAME 重新计算存储的哈希值
```
## 安装
```bash
# 核心策略引擎 + 审计（无网络依赖）
pip install agentguard
# 包含MCP服务器
pip install agentguard[mcp]
# 包含LLM API代理
pip install agentguard[proxy]
# 所有功能
pip install agentguard[mcp,proxy]
```
需要Python 3.10+。已在3.10、3.11、3.12和3.13上测试。
## 架构
```
src/agentguard/
policies/ 策略引擎：规则、守卫、YAML加载器、11个内置策略、预设
audit/ 审计日志：哈希链式JSONL、旋转、保留
guardrails/ 运行时拦截器：守卫、钩子、操作结果
compliance/ 报告生成器：欧盟AI法案、JSON/文本渲染器
mcp/ MCP服务器：透明工具代理，策略强制执行
proxy/ LLM API代理：中间件、出站/入站扫描器
compaction/ 上下文压缩：截断、汇总、指标
routing/ 模型路由：难度分类器、分级模型选择
providers/ 格式适配器：提供者协议、OpenAI适配器
scanner/ 包扫描器：基于正则表达式的源代码分析、6大风险类别
trust/ 信任注册表：信任级别、哈希验证、YAML持久性
sandbox/ 策略沙盒：场景运行器、TPR/FPR控制
cli.py 命令行界面
```
### 设计原则
1. **透明** — 代理不感知被保护
2. **零信任** — 不依赖LLM合作或提示遵守
3. **可审计** — 每个操作都经过哈希链式验证
4. **两层** — 保护工具调用（MCP）和LLM流量（代理）
5. **流感知** — 实时扫描SSE响应，违规时终止
6. **可扩展** — YAML策略、可插拔提供者、可插拔拦截器
7. **类型安全** — 完全mypy严格合规，py.typed标记
8. **已测试** — 1850+测试，TDD，CI支持Python 3.10–3.13
## 路线图
- [x] 核心策略引擎（YAML + Python策略，11个内置策略）
- [x] 带有SHA-256哈希链和完整性验证的审计日志
- [x] 带有预/后钩子的运行时防护栏拦截器
- [x] 欧盟AI法案合规报告生成器（JSON + 文本）
- [x] 带有透明策略强制执行的MCP服务器和边车工具
- [x] 扩展的MCP工具（file_edit, file_glob, file_grep, file_list）
- [x] CLI工具（`check`, `audit`, `policies`, `report`, `serve`, `proxy`）
- [x] 带有出站扫描器（密钥、PII、内部路径）的LLM API代理
- [x] 流入扫描器（SSE滑动窗口，流中终止）
- [x] 内置提示/响应策略（4个代理策略）
- [x] 兼容OpenAI的提供者适配器，自动检测
- [x] 保护级别预设（`strict` / `balanced` / `permissive`）
- [x] MCP服务器信任注册表（信任级别，哈希验证）
- [x] MCP服务器包扫描器（按需源代码审计）
- [ ] Anthropic提供者适配器
- [x] 审计日志轮换和保留（大小/年龄阈值，文件数量限制）
- [x] 上下文压缩（基于规则的截断 + 本地模型汇总）
- [x] 模型路由（难度分类器 + 分级模型选择）
- [x] 增量扫描（增量消息扫描）
- [x] 策略沙盒（场景驱动验证，部署控制）
- [x] Web获取工具（JS渲染无头浏览器）
- [ ] 跨会话审计聚合
- [ ] ISO 42001和NIST AI RMF合规报告
- [ ] SOC 2审计证据映射
- [ ] 实时拒绝通知和仪表板集成
- [ ] 条件策略（时间、分支、环境规则）
- [x] 角色安全策略（越界检测，偏移监控）
## 适用对象
- **工程团队** 部署AI编码代理（Copilot，Cursor，Claude）需要在代理接触生产环境前设置防护栏
- **安全团队** 需要审计 trails和策略强制执行，用于AI辅助工作流，包括LLM API流量过滤
- **合规团队** 需要证据证明AI操作受到监督和记录，符合欧盟AI法案要求
- **任何** 运行自主代理的人，希望能安心工作
## 贡献
参见 [CONTRIBUTING.md](CONTRIBUTING.md) 获取指南。
## 许可证
AGPL-3.0-or-later。参见 [LICENSE](LICENSE) 获取详情。
---
由 [Roboter Schlafen Nicht](https://github.com/Roboter-Schlafen-Nicht) 构建 —
自主工程咨询公司。我们为生产环境构建AI代理并需要此工具。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器