HeadyZhang/agent-audit

# [Agent Audit](https://headyzhang.github.io/agent-audit/) **在 AI Agent 代码到达生产环境之前发现安全漏洞。** [](https://pypi.org/project/agent-audit/) [](https://pypi.org/project/agent-audit/) [](https://opensource.org/licenses/MIT) [](https://github.com/HeadyZhang/agent-audit/actions/workflows/ci.yml) [](https://codecov.io/gh/HeadyZhang/agent-audit?branch=master) []() [](https://headyzhang.github.io/agent-audit/) ## 为什么 Agent 安全在生产环境中会失效 AI Agent 不仅仅是聊天机器人。它们执行代码、调用工具并触及真实系统，因此一条不安全的输入路径就可能演变成生产事故。 - Prompt injection（提示词注入）通过用户控制的上下文重写 Agent 意图 - 不安全的工具输入可能触及 `subprocess`/`eval` 并演变为命令执行 - MCP 配置错误可能泄露凭据并无意中扩大访问权限 如果您的团队发布 Agent 功能、负责 CI 安全门控，或运营 MCP 服务器和工具集成，这是一个高概率的风险面，而不是边缘情况。 如果 Agent 代码可以触发工具、命令或外部系统，您可能需要在每次合并前进行此项检查。 **Agent Audit** 在部署前通过专为当今 Agent 工作流设计的分析核心捕捉这些问题：工具边界污点追踪、MCP 配置审计和语义密钥检测，并具备扩展至学习辅助检测的空间。 可以将其视为 **AI Agent 的安全 Linting**，包含 40 多条映射到 [OWASP Agentic Top 10 (2026)](https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/) 的规则。 ## 6 行快速开始 1. 安装 ``` pip install agent-audit ``` 2. 扫描您的项目 ``` agent-audit scan ./your-agent-project ``` 3. 在 CI 中解读并设置门控 ``` # 仅显示 high+ 级别的 findings agent-audit scan . --severity high # 当存在 high+ 级别的 findings 时 CI 失败 agent-audit scan . --fail-on high ``` `--severity` 控制报告的内容。`--fail-on` 控制命令何时以代码 `1` 退出。 示例报告输出： ``` ╭──────────────────────────────────────────────────────────────────────────────╮ │ Agent Audit Security Report │ │ Scanned: ./your-agent-project │ │ Files analyzed: 2 │ │ Risk Score: 8.4/10 (HIGH) │ ╰──────────────────────────────────────────────────────────────────────────────╯ BLOCK -- Tier 1 (Confidence >= 90%) -- 16 findings AGENT-001: Command Injection via Unsanitized Input Location: agent.py:21 Code: result = subprocess.run(command, shell=True, capture_output=True, text=True) AGENT-010: System Prompt Injection Vector in User Input Path Location: agent.py:13 Code: system_prompt = f"You are a helpful {user_role} assistant..." AGENT-041: SQL Injection via String Interpolation Location: agent.py:31 Code: cursor.execute(f"SELECT * FROM users WHERE name = '{query}'") AGENT-031: Mcp Sensitive Env Exposure Location: mcp_config.json:1 Code: env: {"API_KEY": "sk-a***"} ... and 15 more Summary: BLOCK: 16 | WARN: 2 | INFO: 1 Risk Score: =========================----- 8.4/10 (HIGH) ``` 验证快照（截至 **2026-02-19**，v0.16 基准集）：**94.6% 召回率**，**87.5% 准确率**，**0.91 F1**，在 **9 个开源目标** 中覆盖 **10/10 OWASP Agentic Top 10**。 详情：[Benchmark Results](docs/BENCHMARK-RESULTS.md) | [Competitive Comparison](docs/COMPETITIVE-COMPARISON.md) ## 它能检测什么 | 类别 | 出错原因 | 示例规则 | |----------|----------------|--------------| | **注入攻击** | 用户输入流向 `exec()`、`subprocess`、SQL | AGENT-001, AGENT-041 | | **Prompt injection** | 用户输入被拼接到系统提示词中 | AGENT-010 | | **泄露的密钥** | API 密钥硬编码在源代码或 MCP 配置中 | AGENT-004, AGENT-031 | | **缺少输入验证** | `@tool` 函数接受未经检查的原始字符串 | AGENT-034 | | **不安全的 MCP 服务器** | 无身份验证、无版本固定、权限过宽 | AGENT-005, AGENT-029, AGENT-030, AGENT-033 | | **无防护措施** | Agent 运行时没有迭代限制或人工审批 | AGENT-028, AGENT-037 | | **不受限制的代码执行** | 工具在没有沙箱的情况下运行 `eval()` 或 `shell=True` | AGENT-035 | 完全覆盖所有 10 个 OWASP Agentic Security 类别。针对 **LangChain**、**CrewAI**、**AutoGen** 和 **AgentScope** 的框架特定检测。[查看所有规则 ->](docs/RULES.md) ## 适用人群 - 使用 LangChain、CrewAI、AutoGen、OpenAI Agents SDK 或原始 function-calling 的 **Agent 开发者** —— 每次部署前运行 - 审查 Agent 代码库的 **安全工程师** —— 获取用于 GitHub Security tab 的 SARIF 结构化报告 - 发布 **MCP 服务器** 的团队 —— 验证您的 `mcp.json` / `claude_desktop_config.json` 中的密钥、身份验证缺口和供应链风险 ## 使用方法 ``` # 扫描项目 agent-audit scan ./my-agent # 用于脚本编写的 JSON 输出 agent-audit scan ./my-agent --format json # 用于 GitHub Code Scanning 的 SARIF 输出 agent-audit scan . --format sarif --output results.sarif # 仅在 critical findings 时 CI 失败 agent-audit scan . --fail-on critical # 检查实时 MCP 服务器（只读，从不调用 tools） agent-audit inspect stdio -- npx -y @modelcontextprotocol/server-filesystem /tmp ``` ### 基线扫描 仅跨提交追踪 *新发现*： ``` # 保存当前状态为 baseline agent-audit scan . --save-baseline baseline.json # 仅报告 baseline 中不存在的新 findings agent-audit scan . --baseline baseline.json --fail-on-new ``` ### GitHub Actions

显示 GitHub Action 示例和输入

``` name: Agent Security Scan on: [push, pull_request] jobs: audit: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: HeadyZhang/agent-audit@v1 with: path: '.' fail-on: 'high' upload-sarif: 'true' ``` | Input | Description | Default | |-------|-------------|---------| | `path` | 要扫描的路径 | `.` | | `format` | 输出格式：`terminal`、`json`、`sarif`、`markdown` | `sarif` | | `severity` | 报告的最低严重级别 | `low` | | `fail-on` | 达到此严重级别时报错退出 | `high` | | `baseline` | 用于增量扫描的基线文件 | - | | `upload-sarif` | 将 SARIF 上传到 GitHub Security tab | `true` |

## 评估结果

显示评估详情

在 [**Agent-Vuln-Bench**](tests/benchmark/agent-vuln-bench/)（涵盖 3 个漏洞类别的 19 个样本）上进行了评估，与 Bandit 和 Semgrep 对比： | Tool | Recall | Precision | F1 | |------|-------:|----------:|---:| | **agent-audit** | **94.6%** | **87.5%** | **0.91** | | Bandit 1.8 | 29.7% | 100% | 0.46 | | Semgrep 1.x | 27.0% | 100% | 0.43 | | Category | agent-audit | Bandit | Semgrep | |----------|:-----------:|:-----:|:-------:| | Set A -- Injection / RCE | **100%** | 68.8% | 56.2% | | Set B -- MCP Configuration | **100%** | 0% | 0% | | Set C -- Data / Auth | **84.6%** | 0% | 7.7% | 完整评估详情：[Benchmark Results](docs/BENCHMARK-RESULTS.md) | [Competitive Comparison](docs/COMPETITIVE-COMPARISON.md)

## 工作原理

显示架构和技术说明

``` Source Files (.py, .json, .yaml, .env, ...) | +-- PythonScanner ---- AST Analysis ---- Dangerous Patterns | | Tool Metadata | +-- TaintTracker --------------- Source->Sink Reachability | +-- DangerousOperationAnalyzer - Tool Boundary Detection | +-- SecretScanner ---- Regex Candidates | +-- SemanticAnalyzer ----------- 3-Stage Filtering | (Known Formats -> Entropy/Placeholder -> Context) | +-- MCPConfigScanner -- Server Provenance / Path Permissions / Auth | +-- PrivilegeScanner -- Daemon / Sudoers / Sandbox / Credential Store | v RuleEngine -- 40+ Rules x OWASP Agentic Top 10 -- Findings ``` **关键技术贡献：** - **工具边界感知污点分析** —— 追踪从 `@tool` 函数参数到危险接收器（`eval`、`subprocess.run`、`cursor.execute`）的数据流，并包含净化检测。仅在确认的工具入口点具有未净化的参数流向危险操作时触发。 - **MCP 配置审计** —— 解析 `claude_desktop_config.json` 和 MCP 网关配置，以检测未验证的服务器来源、过宽的文件系统权限、缺失的身份验证以及未固定的包版本 —— 这是一个被现有 SAST 工具完全忽略的类别。 - **三阶段语义凭据检测** —— (1) 基于优先级的正则候选发现，(2) 包含已知格式匹配、熵评分和占位符/UUID 排除的值分析，(3) 基于文件类型、测试模式和框架 Schema 检测的上下文调整。

## 威胁覆盖 40 多条检测规则，涵盖 [OWASP Agentic Top 10 (2026)](https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/) 的所有 10 个类别： | OWASP Category | Rules | Example Detections | |----------------|------:|-------------------| | ASI-01 Agent Goal Hijack | 4 | 通过 `SystemMessage` 中的 f-string 进行的 Prompt injection | | ASI-02 Tool Misuse | 9 | `@tool` 输入未经验证直接传入 `subprocess` | | ASI-03 Identity & Privilege | 4 | Daemon 权限提升，>10 个 MCP 服务器 | | ASI-04 Supply Chain | 5 | 未验证的 MCP 来源，未固定的 `npx` 包 | | ASI-05 Code Execution | 3 | 工具中无沙箱的 `eval`/`exec` | | ASI-06 Memory Poisoning | 6 | 未经净化的输入传入向量存储 `upsert` | | ASI-07 Inter-Agent Comm | 1 | 多 Agent 通过 HTTP 通信但未使用 TLS | | ASI-08 Cascading Failures | 3 | `AgentExecutor` 无 `max_iterations` 限制 | | ASI-09 Trust Exploitation | 6 | 关键操作无 `human_in_the_loop` | | ASI-10 Rogue Agents | 3 | 无切断开关，无行为监控 | ## 真实世界验证

显示真实世界目标结果

扫描了 9 个开源项目以验证检测质量： | Target | Project | Findings | OWASP Categories | |--------|---------|----------|------------------| | T1 | [damn-vulnerable-llm-agent](https://github.com/WithSecureLabs/damn-vulnerable-llm-agent) | 4 | ASI-01, ASI-02, ASI-06 | | T2 | [DamnVulnerableLLMProject](https://github.com/harishsg993010/DamnVulnerableLLMProject) | 41 | ASI-01, ASI-02, ASI-04 | | T3 | [langchain-core](https://github.com/langchain-ai/langchain) | 3 | ASI-01, ASI-02 | | T6 | [openai-agents-python](https://github.com/openai/openai-agents-python) | 25 | ASI-01, ASI-02 | | T7 | [adk-python](https://github.com/google/adk-python) | 40 | ASI-02, ASI-04, ASI-10 | | T8 | [agentscope](https://github.com/modelscope/agentscope) | 10 | ASI-02 | | T9 | [crewAI](https://github.com/crewAIInc/crewAI) | 155 | ASI-01, ASI-02, ASI-04, ASI-07, ASI-08, ASI-10 | | T10 | MCP Config (100-tool server) | 8 | ASI-02, ASI-03, ASI-04, ASI-05, ASI-09 | | T11 | [streamlit-agent](https://github.com/langchain-ai/streamlit-agent) | 6 | ASI-01, ASI-04, ASI-08 | 在各目标中检测到 **10/10 OWASP Agentic Top 10 类别**。质量门控：**PASS**。

## 与现有工具的对比 | Capability | agent-audit | Bandit | Semgrep | |-----------|:-----------:|:-----:|:-------:| | Agent 特定威胁模型 (OWASP Agentic Top 10) | Yes | No | No | | MCP 配置审计 | Yes | No | No | | 工具边界污点分析 | Yes | No | No | | `@tool` 装饰器感知 | Yes | No | No | | 语义凭据检测 | Yes | Basic | Basic | | 通用 Python 安全 | Partial | Yes | Yes | | 多语言支持 | 专注于 Python | Python | Multi | agent-audit 是通用 SAST 工具的 **补充**。它针对现有工具无法解决的 AI Agent 应用程序特有的安全缺口。 ## 配置 ``` # .agent-audit.yaml scan: exclude: ["tests/**", "venv/**"] min_severity: low fail_on: high ignore: - rule_id: AGENT-003 paths: ["auth/**"] reason: "Auth module legitimately communicates externally" allowed_hosts: - "api.openai.com" ``` ## 当前范围

显示当前限制和范围

- **当前核心是静态分析**：不执行代码，可能会遗漏仅限运行时的逻辑漏洞。 - **过程内污点分析**：追踪函数内的数据流；尚无跨函数或跨模块追踪。 - **专注于 Python**：主要支持 Python 源代码和 MCP JSON 配置。对其他语言的支持有限，仅进行模式匹配。 - **框架覆盖**：深入支持 LangChain、CrewAI、AutoGen、AgentScope。其他框架使用通用的 `@tool` 检测规则。 - **误报**：通过语义分析、框架检测和白名单进行缓解；持续优化中（v0.16 中误报减少了 79%）。

## 文档 - [Technical Specification](docs/SECURITY-ANALYSIS-SPECIFICATION.md) —— 检测方法和分析流程 - [Benchmark Results](docs/BENCHMARK-RESULTS.md) —— 详细的 Agent-Vuln-Bench 评估 - [Competitive Comparison](docs/COMPETITIVE-COMPARISON.md) —— 与 Bandit 和 Semgrep 的三工具分析对比 - [Rule Reference](docs/RULES.md) —— 完整的规则目录，包含 CWE 映射和修复建议 - [Architecture](docs/ARCHITECTURE.md) —— 内部设计和扩展点 - [CI/CD Integration](docs/CI-INTEGRATION.md) —— GitHub Actions、GitLab CI、J、Azure DevOps ## 开发 ``` git clone https://github.com/HeadyZhang/agent-audit cd agent-audit/packages/audit poetry install poetry run pytest ../../tests/ -v # 1142 tests ``` 完整的开发设置和 PR 指南请参见 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 引用 如果您在研究中使用 agent-audit，请引用： ``` @software{agent_audit_2026, author = {Zhang, Haiyue}, title = {Agent Audit: Static Security Analysis for AI Agent Applications}, year = {2026}, url = {https://github.com/HeadyZhang/agent-audit}, note = {Based on OWASP Agentic Top 10 (2026) threat model} } ``` ## 致谢 - [OWASP Agentic Top 10 for 2026](https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/) - [CWE Top 25](https://cwe.mitre.org/top25/) ## 许可证 MIT —— 详见 [LICENSE](LICENSE)。

标签：AI 安全, AutoGen, CrewAI, DevSecOps, DNS 反向解析, DNS 解析, DOE合作, LangChain, LLM Agent 安全, MCP 配置审计, OWASP Top 10, Prompt 注入检测, Python 安全工具, SAST, 上游代理, 加密, 命令注入防护, 图数据库, 密钥泄露检测, 漏洞扫描器, 盲注攻击, 自动化payload嵌入, 轻量级, 逆向工具, 静态代码扫描