aiconnai/agentshield

# AgentShield **在 MCP 和 AI agent 扩展发布前，发现其中的高风险行为。** [](https://github.com/limaronaldo/agentshield/actions/workflows/ci.yml) [](LICENSE-MIT) [](https://crates.io/crates/agent-shield) [](https://docs.rs/agent-shield) AgentShield 是一款离线的 Rust 扫描工具，专为跨当前 agent 技术栈交付支持工具调用的 agent 的团队设计。原生适配器覆盖了 MCP 服务器、OpenClaw 技能、Hermes Agent 配置、CrewAI、LangChain/LangGraph、GPT Actions 和 Cursor Rules；相同的检查机制也有助于加固基于 OpenAI Agents SDK、Claude Code、Claude Desktop MCP 设置、Browser Use、FastMCP、GitHub MCP Server、Playwright MCP 以及其他重度依赖 MCP 的工作流构建的代码库。它能够在 agent 实际调用这些工具之前，捕获命令注入、凭证泄露、SSRF、不安全的文件访问、运行时包安装、prompt 注入面以及依赖项卫生问题。 它可以作为 CLI、GitHub Action 或库运行，将源代码保留在本地机器上，并输出控制台、JSON、用于 GitHub Code Scanning 的 SARIF 以及独立的 HTML 报告。当前的发布版本号为 `0.8.7`。 ## 概览 | 领域 | AgentShield 的作用 | |------|------------------------| | 扫描面 | 将七个框架/客户端系列标准化为一种 IR：MCP、OpenClaw、Hermes Agent、CrewAI、LangChain/LangGraph、GPT Actions 和 Cursor Rules。 | | 检测 | 运行 18 条内置规则，检测命令执行、凭证泄露、SSRF、文件系统风险、运行时安装、prompt 面、依赖项卫生、不安全的反序列化、机密泄漏等。 | | 工作流适配 | 在本地、CI 以及 GitHub Code Scanning 中均可运行，且无需将源代码发送至托管服务。 | | 边界 | AgentShield 不是托管监控服务、运行时沙箱或白名单市场。实验性的 runtime guard 入口在选择性启用的 feature flag 之后提供；稳定的契约是静态扫描与策略评估。 | 有关 runtime guard 的范围和路线图，请参见 [docs/RUNTIME_GUARD.md](docs/RUNTIME_GUARD.md)。 ## 适用范围 只要 agent 可以调用本地工具、远程 API、浏览器自动化、文件操作、shell 命令或 MCP 服务器，AgentShield 就能发挥重要作用。 | 生态系统 | AgentShield 如何提供帮助 | |-----------|-----------------------| | Claude Desktop 和 Claude Code | 在将 MCP 服务器和工具仓库添加到 Claude MCP 配置或编程 agent 工作流之前，对其进行扫描。 | | Cursor 和 Cursor Rules | 检测可能触及文件、命令或网络的高风险 agent 指令、MCP 服务器定义和工具代码。 | | OpenAI Agents SDK | 扫描 OpenAI agent 应用程序使用的工具实现、OpenAPI/GPT Actions 接口以及连接 MCP 的代码仓库。 | | LangGraph 和 LangChain | 在 agent 执行工具之前，分析 Python/TypeScript 工具代码及其依赖项暴露面。 | | CrewAI | 检查 Python CrewAI 工具项目是否存在命令执行、凭证泄露、SSRF 以及不安全的文件访问。 | | FastMCP、GitHub MCP Server 和 Playwright MCP | 在发布或安装之前，扫描 MCP 服务器代码、清单、schema、依赖项和来源。 | | Browser Use 和浏览器自动化 agent | 在启用工具的自动化代码仓库中，捕获高风险的命令、网络、文件和依赖项模式。 | 可运行的示例位于 [examples/](examples/README.md) 目录下，并提供了针对 [Claude MCP 安全](docs/claude-mcp-security.md)、[MCP 安全扫描](docs/mcp-security-scanner.md) 和 [OpenAI Agents 安全](docs/openai-agents-security.md) 的专题指南。 ## 为什么选择 AgentShield？ AI agent 正被连接到各种工具上，这些工具能够执行命令、读写文件、发起 HTTP 请求、安装包以及调用外部服务。一个恶意的或编写不当的扩展可能会导致： - **泄露凭证**：通过读取环境变量或本地机密文件，并将其发送到攻击者控制的 endpoint。 - **执行任意命令**：将用户可控的输入传递给 shell 或进程 API。 - **在运行时安装后门**：在工具处理程序内部通过包管理器调用来实现。 - **代理 SSRF 请求**：通过获取源自工具参数的 URL。 - **向模型上下文泄漏敏感数据**：通过不受保护的 prompt、工具结果或规则文件。 AgentShield 通过静态分析、框架适配器、策略评估、抑制、基线、egress 策略生成、证明以及用于 GitHub Code Scanning 的 SARIF 输出来捕获这些模式。 ### 功能对比 | 功能 | AgentShield | mcp-scan | Invariant Labs | |---------|:-----------:|:--------:|:--------------:| | Rust 单一二进制文件 | 是 | 否 | 否 | | 离线 / 本地优先 | 是 | 部分 | 否 | | 多框架适配器 | 是 | 专注于 MCP | 专注于 MCP | | 静态分析 | tree-sitter + 定向解析器 | 基于正则表达式 | 基于运行时/云端 | | 跨文件净化器分析 | 是 | 否 | 否 | | SARIF 输出 | 是 | 否 | 否 | | GitHub Action | 是 | 否 | 否 | ## 快速开始 ### GitHub Action 添加至 `.github/workflows/security.yml`： ``` name: Agent Security on: [push, pull_request] jobs: scan: runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 - uses: aiconnai/agentshield@main with: path: '.' fail-on: 'high' ignore-tests: true upload-sarif: true ``` 当启用 SARIF 上传时，扫描结果将显示为 PR 注释，并位于代码仓库的 **Security > Code scanning** 标签页下。 ### CLI ``` # 从 GitHub 安装包含完整功能集的当前版本 cargo install --git https://github.com/limaronaldo/agentshield --tag v0.8.7 --features full --force # 首次运行设置：配置 + 首次扫描说明 agentshield quickstart # 了解 gate、coverage、confidence 和后续操作 agentshield scan . --ignore-tests --fail-on high --explain # 添加 GitHub Actions workflow agentshield ci install # 在现有 repo 中采用，而不阻塞已知的 findings agentshield scan --write-baseline .agentshield-baseline.json agentshield ci install --baseline .agentshield-baseline.json # 生成独立的 HTML 报告 agentshield scan ./my-agent-extension --format html --output report.html # 列出所有 rules agentshield list-rules # 创建初始 config agentshield init ``` 如果您只需要在已发布的 crates.io 版本中进行静态扫描，同样支持使用 `cargo install agent-shield`。当您需要在 crates.io 更新之前使用最新的发布版本时，请使用上文提到的 GitHub tag 命令。 ### 预构建二进制文件 从 [最新发布版本](https://github.com/limaronaldo/agentshield/releases/latest) 下载适用于 Linux、macOS 和 Windows 目标平台的文件。 对于容器用户，发布镜像标签为： ``` ghcr.io/aiconnai/agentshield:0.8.7 ``` ### Docker GHCR 镜像使用 `full` feature 集进行构建，包括运行时 `wrap` 支持和实验性的 runtime guard 命令。该镜像针对 `linux/amd64` 和 `linux/arm64` 平台发布。 ``` docker pull ghcr.io/aiconnai/agentshield:0.8.7 docker run --rm -v "$PWD:/scan" ghcr.io/aiconnai/agentshield:0.8.7 scan . docker run --rm ghcr.io/aiconnai/agentshield:0.8.7 --version ``` 如果 GHCR 包在您的组织中是私有的，请先进行身份验证： ``` gh auth refresh -h github.com -s read:packages gh auth token | docker login ghcr.io -u "$(gh api user --jq .login)" --password-stdin ``` ### 从源码构建 ``` git clone https://github.com/limaronaldo/agentshield.git cd agentshield cargo build --release ./target/release/agentshield scan /path/to/agent-extension ``` ## 使用 RTK 进行 Token 优化的本地检查 AgentShield 在本地开发过程中可能会产生冗余的命令输出，特别是来自 `cargo test`、`cargo clippy` 以及输出 JSON 或 SARIF 的扫描任务。如果已安装 `rtk`，可以使用可选的包装器来减少展示给人类和编程 agent 的输出内容： ``` scripts/rtk-check.sh quick scripts/rtk-check.sh test scripts/rtk-check.sh clippy scripts/rtk-check.sh scan-fixture ``` 该包装器专用于本地。RTK 仅过滤本地命令输出。它绝不能更改被用户、客户端、CI 或 GitHub Code Scanning 使用的 AgentShield JSON、SARIF、HTML 或控制台输出契约。 在进行调试、审计和安全决策时，请使用原始输出： ``` scripts/rtk-check.sh raw -- cargo test scripts/rtk-check.sh raw -- cargo run -- scan tests/fixtures/mcp_servers/safe_calculator --format sarif --output target/agentshield/scan.sarif ``` 策略： - 使用过滤后的输出以获得快速的本地反馈。 - 在排查测试失败、解析器错误、检测器行为或安全敏感的扫描结果时，使用原始输出。 - 当客户端或 CI 需要消费报告时，务必将完整的 `json` 和 `sarif` 报告写入文件中。 ## 支持的框架 AgentShield 会在代码仓库中运行所有匹配的适配器，而不是在匹配到第一个时即停止。 | 框架 | 状态 | 适配器覆盖范围 | |-----------|--------|------------------| | MCP (Model Context Protocol) | 支持 | MCP 服务器清单、Python/TypeScript/JavaScript 源码、工具 schema、依赖项、出处 | | OpenClaw | 支持 | `SKILL.md` 技能文件及相关源码/依赖项暴露面 | | Hermes Agent | 支持 | Hermes 配置/配置文件、`mcp_servers`、`.hermes.md`、技能树、可选的 MCP 清单 | | CrewAI | 支持 | 通过依赖项元数据或 import 检测到的 Python 项目 | | LangChain / LangGraph | 支持 | LangChain/LangGraph 依赖项元数据、import 以及 `langgraph.json` | | GPT Actions | 支持 | 用于自定义 GPT 集成的 Action/OpenAPI 风格接口 | | Cursor Rules | 支持 | Cursor 规则文件及相关 agent 指令暴露面 | ## CLI 命令 | 命令 | 用途 | |---------|---------| | `agentshield scan [path]` | 扫描 agent 扩展目录并输出控制台、JSON、SARIF 或 HTML 格式的结果。 | | `agentshield scan [path] --explain` | 打印仅供控制台显示的门禁、覆盖率、置信度、分组扫描结果、后续操作和限制摘要。 | | `agentshield quickstart [path]` | 创建首次运行配置，建议 CI 设置，运行首次扫描并解释结果。 | | `agentshield ci install` | 为 AgentShield 生成 GitHub Actions 工作流。 | | `agentshield ci install --baseline ` | 生成通过基线文件过滤已知扫描结果的工作流。 | | `agentshield list-rules` | 以表格或 JSON 格式列出可用的检测规则。 | | `agentshield doctor [path]` | 打印环境、配置、编译特性和适配器的诊断信息。 | | `agentshield init` | 生成初始的 `.agentshield.toml` 配置文件。 | | `agentshield suppress ` | 添加抑制条目（需提供原因，可选过期时间）。 | | `agentshield list-suppressions` | 显示在 `.agentshield.toml` 中配置的抑制项。 | | `agentshield certify [path]` | 为扫描结果生成 DSSE 证明信封。 | | `agentshield wrap --policy -- ` | 在使用 `runtime` feature 构建时，通过本地 HTTP 代理实施 egress 策略。 | | `agentshield guard --stdin` | 在使用 `runtime-guard` feature 构建时，评估单个 runtime 事件的 JSON 文档。 | | `agentshield guard --mcp-proxy [-- ]` | 实验性功能：在使用 `runtime-guard` feature 构建时，评估换行符分隔的 MCP JSON-RPC `tools/call` 消息，阻止不安全的调用，并发出转发标记，或者将 stdio 桥接到生成的下游 MCP 服务器。 | 实用的 `scan` 选项包括 `--config`、`--format`、`--fail-on`、`--output`、`--ignore-tests`、`--explain`、`--baseline`、`--write-baseline` 和 `--emit-egress-policy`。 配置的 `[scan] include` 和 `[scan] exclude` 过滤器会在检测器运行前，界定源码和基于元数据生成的扫描结果的范围。 对于已有扫描结果的成熟代码库，请先写入基线，然后在 CI 中使用它： ``` agentshield scan --write-baseline .agentshield-baseline.json agentshield scan --baseline .agentshield-baseline.json --explain agentshield ci install --baseline .agentshield-baseline.json ``` `--explain` 是特意设计为仅供控制台显示的。它不会将文本追加到 JSON、SARIF 或 HTML 输出中。Explain 输出包含扫描根目录（如不同则包含元数据根目录），以及针对集中阻断性扫描结果的热点摘要。 ## 检测规则 AgentShield 内置了针对命令执行、凭证泄露、SSRF、任意文件访问、运行时包安装、自我修改、prompt 注入面、过度权限、依赖项卫生、动态代码执行、元数据服务访问、下载并执行流程、过宽的文件系统能力、不安全的反序列化、归档文件目录穿越以及机密泄漏的规则。 请使用 CLI 获取您所安装版本的权威规则列表： ``` agentshield list-rules agentshield list-rules --format json ``` ## 输出格式 | 格式 | 标志 | 用例 | |--------|------|----------| | 控制台 | `--format console` | 本地开发默认值 | | JSON | `--format json` | 程序化消费与指纹提取 | | SARIF | `--format sarif` | GitHub Code Scanning 及兼容工具 | | HTML | `--format html` | 可分享的独立报告 | ## 配置 ### 信任工作流 AgentShield 包含关于基线、抑制、认证证明和 egress 执行的信任工作流文档： - `docs/BASELINES.md`：为已知扫描结果编写并使用 `.agentshield-baseline.json`。 - `docs/SUPPRESSIONS.md`：通过指纹抑制单个扫描结果，需提供原因并可选过期时间。 - `docs/CERTIFICATION`：生成未签名或 Ed25519 签名的 DSSE 证明。 - `docs/EGRESS.md`：发出 `agentshield.egress.toml` 并使用 `agentshield wrap` 执行该策略。 发布的二进制文件使用 `full` feature 集构建，包括 Python 解析、TypeScript 解析、运行时 `wrap` 支持以及实验性的 runtime guard 命令。如果从源码构建，请使用 `cargo build --features full --release` 以包含 `agentshield wrap` 和 `agentshield guard`。 在项目根目录创建 `.agentshield.toml` 或运行 `agentshield init`： ``` [policy] # 使扫描失败的最低严重级别：info、low、medium、high、critical fail_on = "high" # 完全跳过的 rules ignore_rules = ["SHIELD-008"] # 降级特定的 rules [policy.overrides] "SHIELD-012" = "info" [scan] # 在解析前跳过测试文件 ignore_tests = true # 可选的路径过滤器相对于扫描根目录。 # 空的 include 意味着所有支持扫描的文件都符合条件。 # 使用 ** 匹配递归目录；* 和 ? 保持在单个路径段内。 include = ["src/**", "tools/**"] exclude = ["legacy/**", "**/generated/**", "vendor/**"] [runtime.proxy] # 运行时 MCP 代理 guard 阻塞阈值：block、warn 或 never。 fail_on = "block" [[runtime.proxy.tool]] name = "calculator.add" fail_on = "never" ``` 在从 JSON 输出中获取扫描结果指纹后，可以通过 `agentshield suppress --reason "..."` 添加抑制项。 当 `include` 和 `exclude` 同时匹配同一个文件时，`exclude` 优先生效。请使用 `agentshield scan . --explain` 来确认当前生效的路径过滤器及解析到的源文件数量，然后再在 CI 中依赖于聚焦范围的扫描。 路径过滤匹配区分大小写，在所有平台上均接受 `/`，会将开头的 `./` 或 `/` 视为相对于扫描根目录，并将诸如 `legacy/` 这样的末尾斜杠视为匹配该目录的内容。 ## 退出代码 | 代码 | 含义 | |------|---------| | 0 | 扫描通过，没有超过阈值的扫描结果 | | 1 | 扫描失败，存在超过阈值的扫描结果 | | 2 | 扫描错误，例如配置无效或未找到支持的适配器 | | 3 | Runtime guard 阻止了操作，或在遇到无效的 runtime 输入时安全关闭（failed closed） | ## 语言支持 | 语言 | 解析器 | 特性标志 | |----------|--------|--------------| | Python | tree-sitter AST 结合正则表达式源/汇模式 | `python` (默认) | | TypeScript/TSX | tree-sitter AST 结合回退模式 | `typescript` (默认) | | JavaScript/JSX | 通过 TypeScript 语法支持使用 tree-sitter AST | `typescript` (默认) | | Shell | 正则表达式解析器 | 始终开启 | | JSON Schema / OpenAPI 风格的 schema | Schema 解析器 | 始终开启 | 两个 tree-sitter 解析器都受特性控制： ``` cargo build --no-default-features cargo build --features python cargo build --features full ``` `full` feature 启用了语言解析器，以及被 `agentshield wrap` 和实验性 runtime guard 命令所使用的运行时代理。 ## 架构 ``` CLI / GitHub Action / Library API | v Scan Engine -> ScanReport | v Adapters -> Parsers -> Cross-file analysis -> Unified IR (ScanTarget) | v Rule Engine -> Policy / Suppressions / Baseline filtering | v Console / JSON / SARIF / HTML / DSSE attestation ``` 适配器将特定于框架的文件转换为统一的中间表示。检测器仅消费该 IR，因此无需重写每一条规则即可添加新框架。策略、抑制和基线独立于检测机制，从而确保扫描结果保持可解释和可重复。 ## 开发 ``` cargo test cargo clippy -- -D warnings cargo fmt --check cargo run -- scan tests/fixtures/mcp_servers/vuln_cmd_inject cargo run -- list-rules ``` 有关特定版本的说明，请参阅 `docs/releases/0.8.6.md`、 `docs/releases/0.8.7.md` 和 `docs/RELEASE_CHECKLIST.md`。

标签：AI Agent安全, CISA项目, GitHub Action, MCP, Rust, SAST, 可视化界面, 安全合规, 盲注攻击, 网络代理, 网络流量审计, 请求拦截, 通知系统, 静态代码扫描