AppSec Toolbox MCP

appsec-toolbox-mcp

让 AI Agent 审计你不信任的代码，而无需给它 Shell、让它选择路径，或运行仓库中的代码。

在一个经过强化的容器中，通过八个无参数 MCP 工具运行十种固定版本的安全扫描器。被审计的仓库被视为攻击者。Agent 只会收集证据。

演示录制自 examples/agent_demo.py，针对 examples/vulnerable-sample 运行。等待时间已缩短；实际扫描时间见最后一行。

30 秒了解

• 这是什么。 Semgrep、Gitleaks、OSV-Scanner、Trivy、Checkov、Syft 以及语言专用工具（Bandit、FindSecBugs、njsscan、gosec）以固定功能的形式提供给任意 MCP 客户端：security.sast、security.secrets、security.dependencies 等。
• 威胁模型。 被审计的仓库具有恶意：它控制扫描器解析的每个文件，以及 Agent 读回的每个字符串。因此，Agent 无法操控任何东西：没有参数、没有目标路径、没有 Shell，也无法运行仓库的构建流程或代码。
• 你将获得什么。 原生扫描器报告；一份运行清单，将每份报告的 SHA-256 与可重新计算的已扫描树指纹关联起来；以及记录每次工具调用的审计日志。

工程亮点

每项主张都链接到能证明它的代码或测试。

问题	方法	证明
拥有 shell 的提示词注入 Agent 可以为所欲为。	Agent 的全部接口只有八个无参数任务，由 Makefile MCP 管控。虽然存在维护目标，但这些目标会被拒绝。	.makefile-mcp.yaml、演示
扫描不可信代码通常会运行代码：setup.py、postinstall、Gradle 插件、Go 工具链下载、扫描器插件。	严格被动分析：不构建、不安装、不解析依赖；Go 在 GOPROXY=off 和 GOTOOLCHAIN=local 下运行。一次对抗性审查发现，植入的 .checkov.yaml 可让 Checkov 导入仓库中的 Python 代码；该路径现已封堵，并通过回归测试验证。	examples/hostile-sample、tests/image.sh
恶意仓库可以通过 .semgrepignore、.gitleaksignore、# nosec、# nosemgrep……屏蔽自身的问题。	每个扫描器都使用工具箱拥有的配置运行。在扫描器允许的情况下，会禁用内联抑制；无论是否禁用，都会清点发现的每个标记，供审查者查看。	设置表、output/suppressions.json
证据只有与扫描对象绑定才有价值。	清单对目录树计算指纹，方式与 find . -type f -print0 | LC_ALL=C sort -z | xargs -0 sha256sum | sha256sum 完全相同，包括非 UTF-8 文件名或会被 sha256sum 转义的文件名，并记录每份报告的摘要、工具版本和数据源。	scripts/write-manifest.py、tests/unit/test_manifest.py
单个格式错误的文件不应导致目标停止审计。	如果扫描器因目标本身的问题而无法读取输入（例如无法加载的 Go 包、损坏的锁文件），就会将其记录为覆盖范围限制：这既不算扫描包失败，也不会伪装成扫描结果干净。	scripts/run-language-profiles.py、scripts/run-osv.sh
结果应可复现，遭到入侵的扫描器也不应有机会发送代码。	离线模式：先获取一次规则和公告数据，再在 --network none 下扫描。清单会记录数据的时效和摘要。	离线模式
安全工具本身就是供应链攻击目标。	每个下载的二进制文件都会按架构与其发布的 SHA-256 值校验；基础镜像按摘要固定；Actions 按提交固定；运行项目代码的发布任务不持有写入令牌；镜像带有签名的构建来源证明。	Dockerfile、release.yml

分层验证。 单元测试覆盖脚本。冒烟测试通过 Makefile MCP 驱动 Makefile，并使用模拟扫描器；只要缺少任何加固标志，扫描器桩就会失败。镜像测试会在文档规定的资源限制下，使用真实扫描器扫描已知存在漏洞的样本、尝试上述所有攻击的恶意样本，以及离线模式。独立的对抗性审查对镜像进行了攻击；每个确认的问题都已修复并添加回归测试，剩余风险则记录在威胁模型中。

快速开始

IMAGE=ghcr.io/ai-ronin-systems/appsec-toolbox-mcp:0.3.0
docker pull "$IMAGE"
gh attestation verify "oci://$IMAGE" --owner ai-ronin-systems

离线模式、资源限制和目标设置加固已合并到 main，并将在下一版本中发布。现在即可使用：docker build -t appsec-toolbox-mcp:dev . 和 IMAGE=appsec-toolbox-mcp:dev。

将其作为 MCP stdio 服务，对单个仓库运行：

docker run --rm -i \
  --read-only --cap-drop=ALL --security-opt=no-new-privileges:true \
  --tmpfs /tmp:rw,nosuid,nodev,size=3g --memory=6g --pids-limit=512 \
  --user "$(id -u):$(id -g)" \
  -v "$PWD/my-project:/runner/target:ro" \
  -v "$PWD/appsec-output:/runner/output:rw" \
  "$IMAGE"

在任意 MCP 客户端中，将相同命令注册为 stdio 服务：

{
  "mcpServers": {
    "appsec-toolbox": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--read-only", "--cap-drop=ALL",
               "--security-opt=no-new-privileges:true",
               "--tmpfs", "/tmp:rw,nosuid,nodev,size=3g", "--memory=6g", "--pids-limit=512",
               "-v", "/abs/path/my-project:/runner/target:ro",
               "-v", "/abs/path/appsec-output:/runner/output:rw",
               "ghcr.io/ai-ronin-systems/appsec-toolbox-mcp:0.3.0"]
    }
  }
}

Compose、离线模式、语言选择和所有证据文件的说明见使用指南。

工作原理

untrusted repository (read-only)
          |
          v
   /runner/target
          |
          v
 trusted Makefile + Makefile MCP
    |       |       |       |       |       |
 Semgrep Gitleaks   OSV    Trivy  Checkov   Syft
          |
          +---- language profile selection ----+
                 |       |        |        |
               Bandit FindSecBugs njsscan  gosec
               Python    Java     Node/JS   Go
          |
          v
    /runner/output   reports, run-manifest.json, suppressions.json, audit log

操作人员会将且只将一个代码仓库挂载到 /runner/target，并将一个可写目录挂载到 /runner/output。被审计的路径绝不会作为 MCP 参数传入，因此 Agent 无法访问宿主机路径。受信任的 Makefile 包含所有扫描器命令；Makefile MCP 决定 Agent 可以调用其中哪些目标。语言专项工具由检测结果（APPSEC_LANGS=auto）或操作人员选择，而非 Agent 选择。

能力	工具	证据
security.audit	以下所有工具	完整套件
security.sast	Semgrep + 抑制项清单	semgrep.json、suppressions.json
security.secrets	Gitleaks	gitleaks.json
security.dependencies	OSV-Scanner	osv.json
security.repository	Trivy	trivy.json
security.iac	Checkov	checkov.json
security.language	适用时使用 Bandit、FindSecBugs、njsscan、gosec	language-profile.json + 报告
supply_chain.sbom	Syft	sbom.cdx.json（CycloneDX）

威胁模型

被审计的代码仓库就是攻击者，读取其报告的 Agent 可能受其误导。请阅读威胁模型：攻击者目标、包含控制措施和剩余风险的 16 项威胁、保证与不保证的事项，以及操作人员检查清单。

受保护	不受保护
目标代码仓库的构建、安装、钩子和 Makefile 永远不会运行。	扫描器解析器漏洞；容器是安全边界。
目标代码仓库所有的扫描器设置文件无法抑制发现项或加载代码。	行内 trivy:ignore 和 njsscan-ignore 注释；Checkov 会将其行内跳过项列为 skipped_checks。所有这些都会被列入清单。
Agent 无法选择目标，也无法运行这 8 种扫描以外的任何操作。	Agent 谎报报告内容。
容器中没有凭据；容器只读、权限受限、以非 root 用户运行，并设有资源上限。	在线模式下受攻击者控制的扫描器可能泄露数据。离线模式不使用网络。
每次运行的清单都会将报告摘要与已扫描树的指纹关联起来。	任何有权写入 output/ 的人都可能篡改数据；清单未签名。

设计选择

• 提供证据，而非结论。 报告保留各扫描器的原生格式。工具箱不会为发现项评级、去重或规范化；使用者可根据完整证据自行处理。
• 扫描器种类固定。 提供 4 种语言配置，不设插件框架，也不支持用户定义流水线。通用 SCA 由 OSV 和 Trivy 负责；专项工具会增加不同的分析引擎，而非重复分析。
• 如实记录覆盖缺口，绝不掩盖。 仅包含源代码的 Java 项目不会运行 FindSecBugs，因为工具箱不会编译不受信任的代码；清单会注明这一点。
• 所有内容均固定版本。 扫描器版本均已固定，并逐一针对已知阳性和恶意测试样本进行更新（更新策略）。

它不是自主审计器、LLM Agent、DAST 引擎、凭据管理器、报告规范化工具或 shell 服务。

更大系统的一部分

appsec-audit-hound (planned)    decides why to scan, correlates evidence, writes findings
        | MCP
appsec-toolbox-mcp              collects governed, passive evidence   <- this repository
        | built on
makefile-mcp                    exposes trusted Make targets to agents, deny-by-default

Makefile MCP 已发布到 PyPI 和官方 MCP Registry，并有自己的威胁模型。

文档

文档	涵盖内容
威胁模型	攻击者目标、威胁与控制措施、保证、限制、运营者检查清单
使用指南	运行、工具与证据文件、语言配置、离线模式、扫描器行为、网络使用、版本、开发
架构	信任边界、所有权、设计规则
工具	固定版本、每个扫描器忽略的设置、更新策略
安全政策	支持的版本与私密漏洞报告
更新日志	已发布和未发布的更改
贡献指南	如何在不扩大边界的情况下添加扫描器

开发

pipx install pytest==8.4.2 && pipx install ruff==0.14.0
make test         # ruff, unit tests, smoke test
make image
make test-image   # the real image: known positives, hostile sample, offline mode

更多内容请参阅使用指南。

许可证

Apache-2.0。