audit-mcp

audit-mcp 这是一个有史以来最伟大的源代码审计工具。 目前市场上所有的安全扫描工具都做同样的它们像扫描一堆文本文件一样扫描你的代码，抛出200个发现结果，然后就离开了。就像在你的桌子上扔下一座信息山，然后走开，留下你去处理。仿佛在说：“祝你好运，找出哪些是真正重要的，笨蛋。” 这几乎是所有现有SAST工具的现状。 audit-mcp 不会这样做。它首先为你的整个代码库构建一个完整的功能调用图——每个函数、每个调用、每个入口点、每个信任边界——然后再进行扫描。所以当 semgrep 说“第 42 行存在 SQL 注入漏洞”时，这个工具会实际检查：第 42 行是否可以从网络访问？还是它在某个测试辅助函数中，而没有人调用它？因为这两种情况是截然不同的。 audit-mcp 建立在 [Trail of Bits Trailmark](https://github.com/trailofbits/trailmark) 的基础上。支持 21 种语言。可选地通过 NVIDIA CUDA 实现 GPU 加速。不是 semgrep 包装器。不是供应商锁定的云订阅，费用甚至房租。 ## 安装 ```bash pip install -e . ``` 就这样。Python 3.12+。它会拉取 `trailmark`、`fastmcp`、`fastapi`、`uvicorn`、`scipy` 和 `numpy`。如果你可以安装一个 pip 包，那么你就可以安装这个。门槛简直是地板。 ### GPU 加速（可选） 如果你拥有 NVIDIA GPU，并希望死代码分析运行速度快 1,474 倍，而不是像某种动物一样等待 72 秒： ```bash pip install -e ".[gpu]" ``` 这会安装具有 CUDA 11.x 支持的 CuPy。GPU 引擎在检测到具有 CUDA 能力的 GPU 和图具有超过 50K 边时自动激活。如果你没有 GPU，一切仍然可以在 CPU 上通过 scipy 运行。结果相同，只是大型图上速度较慢。 需要：NVIDIA GPU（GTX 1060+），安装 CUDA 工具包 11.x，~400MB 磁盘用于 CuPy。 ## 运行此工具 ### MCP 模式（stdio — 适用于 Claude Desktop、Cursor 等） ```bash audit-mcp ``` 只需输入即可启动。它开始工作了。令人难以置信。 ```bash python -m audit_mcp ``` 对于不信任控制台脚本的人来说，同样有效。 ### HTTP 模式（当你想像正常人一样使用 curl 访问它时） ```bash audit-mcp --mode http --port 18822 ``` API 文档显示在 `http://127.0.0.1:18822/docs` 上。FastAPI 交互式文档。美丽。 ## 将其连接到 Claude Desktop 在 `claude_desktop_config.json` 中添加以下内容： ```json { "mcpServers": { "audit-mcp": { "command": "audit-mcp", "args": [] } } } ``` 如果你没有全局安装 `pip`，而是像这样的人： ```json { "mcpServers": { "audit-mcp": { "command": "python", "args": ["-m", "audit_mcp"], "cwd/to/audit-mcp" } } } ``` ## 将其连接到 Cursor 在 `.cursor/mcp.json` 中添加以下内容： ```json { "mcpServers": { "audit-mcp": { "command": "cp", "args": [] } } } ``` ## 它实际执行的操作 让我带你了解游戏循环，因为它确实令人难以置信。 ### 1：索引代码库 你指向一个目录。它解析所有内容。21 种语言。构建完整的功能调用图。如果你有 GPU，它还会构建 CSR 稀疏邻接将其传输到 VRAM 以供后续查询。并在后台完成工作，像一个负责任的成年人index_codebase(path="/path/to/project") index_id: "a1b2c3", "indexing"} poll_index(index_id="a1c3") status: "ready", summary: {functions: 4812, call_edges: 18234, entrypoints47}} ``` 4,812 个函数。18,234 个调用边。47 个入口点。它刚刚在几秒钟内映射了你的整个攻击面。那真是太棒了。 ### 步骤：查看危险所在 ``` attack_surface(index_id1b2c3") -> entrypoints with trust levels, blast radius, framework detection preanalysis(index_id1b2c3") -> blast radius top, privilege boundaries, taint propagation ``` 它告诉函数暴露在互联网上。哪些函数的爆炸半径最大。哪些函数跨越权限边界。这是其他工具根本不提供的信息。绝对令人惊叹。 ### 步骤 3：运行扫描器并关联 这就是魔术发生的地方。你运行 semgrep 或 bandit 或任何你想要的扫描器，然后这个工具获取原始发现结果并将它们叠加到图上。结果是根据实际可利用性排序的发现结果，而不是按字母顺序排列。 ``` scan_and_correlate(index_id="a1b2c3", scanner="semgrep") -> {task_id4e5f6", status: "running"} poll_task(task_id="d4e5f6") -> findings sorted by risk_score (tainted + reachable + high blast radius = highest priority) ``` "Semgrep 发现了 47 个 SQL 注入漏洞。在这些漏洞中，12 个来自入口点的污点数据。 在这些漏洞中，3 个具有超过 50 的爆炸半径。从这里开始。" 这就是输出。 这就是价值主张。 欢迎。 ### 步骤 4：询问安全问题 这是绝对疯狂的部分。 ``` taint_paths_to(index_id="a1b2c3", sink_name="eval") -> all entrypoint-to-eval call paths callers_of(index_id="a1b2c3", name="parse_input", exclude_hubs=true) -> direct callers, minus the logging/utility noise dead_code(index_id="a1b2c3") -> {task_id: ..., status: "running"} # runs async, 49ms on GPU, 72 seconds without paths_between(index_id="a1b2c3", source="handle_request", target="execute_query") -> top 5 paths between two functions ``` "`eval()` 是否可以从网络访问？” 一条命令。答案。完毕。 不需要在 50,000 个文件中像原始人一样 grep。 ### 步骤 版本差异 ``` diff_codebases(index_id_a="v1", index_id_b="v2") -> added/removed/changed functions, attack surface delta attack_surface_diff(index_id_a="v1", index_id_b="v2") -> new entrypoints, removed validation, blast radius changes ``` “此 PR 新增了 3 个入口点并删除了一个验证检查。攻击面增加了 8%。” 这就是让安全审查真正有用的那种说法，而不是仅仅走过场。 ## 全部武器库（51 种工具） | 类别 | 工具 | 功能 | | --- | --- | --- | | **索引生命周期** | `index_codebase`, `poll_index`, `list_indexes` | 解析 + 分析代码库 | | **图形查询** | `callers_of`, `callees_of`, `ancestors_of`, `reachable_from`, `paths_between`, `search_functions` | 导航调用图（GPU 加速，有界） | | **安全分析** | `attack_surface`, `preanalysis`, `complexity_hotspots`, `entrypoint_paths_to`, `taint_paths_to` | 映射攻击面 + 污点 | | **深度审计** | `dead_code`, `unreachable_from_entrypoints`, `fuzzing_targets` | 图形感知安全分析（GPU 加速，异步） | | **源代码搜索** | `search_constants`, `search_types`, `search_assertions`, `search_bitfields`, `search_macros`, `search_source`, `search_narrowing_casts` | 查找常量、类型、断言、位域、宏 — 调用图之外的构造 | | **代码读取** | `extract_class`, `read_function` | 从源代码中提取完整的类/函数体 | | **变体搜索** | `cross_reference_bitfields`, `children_of`, `includers_of` | 交叉引用位域宽度与容量检查，跟踪继承，映射包含图 | | **扫描器** | `list_scanners`, `run_scanner`, `scan_and_correlate`, `augment_sarif` | 运行 SAST 工具 + 与图关联 | | **注释** | `annotate_function`, `annotations_of`, `findings`, `clear_annotations`, `nodes_with_annotation`, `functions_that_raise` | 查询发现结果 | | **差异** | `diff_codebases`, `attack_surface_diff` | 版本比较 | | **扩展** | `plan_partitions`, `export_graph`, `cache_stats`, `clear_cache`, `memory_usage` | 大型代码库支持 + LRU 逐出 | | **异步** | `poll_task`, `list_tasks` | 后台任务管理 | | **实用工具** | `supported_languages`, `detect_languages` | 语言检测 | 51 种工具。每种工具都返回结构化的 JSON。 不像 2003 年那样解析 stdout。 ## GPU 加速 图形引擎mark 的调用图转换为 CSR 稀疏邻接矩阵，并通过稀疏矩阵-向量乘法运行可达性。在 NVIDIA GPU 上，这通过 CuPy 运行在 CUDA 上。没有 GPU 时，相同的代码通过 scipy 运行在 CPU 上。无论哪种方式，API 都相同 — 你永远不会考虑它。 ### GPU 上运行的内容 | 操作 | CPU（trailmark） | GPU（RTX 3080 加速比 | 方式 | | --- | --- | --- | --- | --- | | **死代码**（Chromium，35K 节点） | 72,148ms | 49ms | **1,474x** | 预计算入度数组 vs 每个节点的 callers_of | | **中心检测**（Chromium，455K 边） | 82,000ms | 0.3ms | **~270,000x** | 来自 CSR 的入度 vs 每个节点的 callers_of | | **SpMV 单个 BFS**（1M 边） | 12.3ms | 0.22ms | **56x** | cuSPARSE vs scipy | | **批量 50 BFS**（1M 边） | 560ms | 85ms | **7x** | 一个批量 SpMV vs 50 个串行遍历 | ### 保留在 CPU 上（以及原因） | 操作 | 时间 | 不使用 GPU 的原因 | | --- | --- | --- | | **解析**（tree-sitter） | 91% 索引时间 | 每个文件的顺序。本地 C 代码。GPU 无法帮助。 | | **图形合并 2.3% | Python 字典操作。GPU 无法运行 CPython。 | | **入口点检测** | 2.7% | 注释模式匹配。已经很快了。 | | **正则表达式搜索** | <100ms | 分支繁重。GPU 讨厌分支发散。 | GPU 不会触及 trailmark。Trailmark 进行解析和建模（它擅长的内容）。我们的 `GpuGraphEngine` 进行遍历和分析（GPU 擅长的内容）。 清洁的边界，没有耦合。 ### 激活 GPU 引擎在以下情况下自动激活： 1. 安装了 CuPy（`pip install -e ".[gpu]"`） 2. 检测到具有 CUDA 能力的 GPU 3. 图有超过 50,000 条边 在 50K 边以下，CPU 更快，因为 GPU 内存传输开销超过计算增益。阈值是自适应的 — 你永远不会配置它。 ### 在 RTX 3080 上基准测试 原始 SpMV 数字（CuPy 13.6，CUDA 11.8，8704 CUDA 核心，10GB VRAM）： | 规模 | 节点 | 边 | CPU SpMV | GPU SpMV | 加速比 | | --- | --- | --- | --- | --- | --- | | 小型 | 10K | 100K | 0.10ms | 0.06ms | 1.7x | | 中型 | 100K | 1M | 0.95ms | 0.06ms | **16x** | | 大型 | 500K | 5M | 5.84ms | 0.12ms | **49x** | | 超大型 | 1M | 10M | 12.3ms | 0.22ms | **56x** | ## 扫描器 这些是可选的。安装涵盖您技术栈的扫描器。`list_scanners()` 会告诉您在您的机器上有哪些可用的扫描器。 | 扫描器 | 语言 | 获取方式 | | --- | --- | --- | | [semgrep](https://semgrep.dev) | 13 种语言 | `pip install semgrep` | | [bandit](https://bandit.readthedocs.io) | Python | `pip install bandit` | | [trivy](https://trivy.dev) | 10 种语言 | [安装指南](https://aquasecurity.github.io/trivy/latest/getting-started/installation/) | | [bearer](https://bearer.com) | 6 种语言 | [安装指南](https://docs.bearer.com/reference/installation/) | | [gosec](https://securego.io) | Go | `go install github.com/securego/gosec/v2/cmd/gosec@latest` | | [phpstan](https://phpstan.org) | PHP | `composer require --dev phpstan/php | 您不需要全部安装。您也不需要其中任何图形分析独立工作。扫描器只是当您想要对代码库进行绝对彻底的分析时额外的火力。 ## 大型代码库支持 针对真实代码库进行测试。这些是实际基准测试数字，而不是估计值： | 项目 | 文件 | 函数 | 调用边 | 冷索引 | 暖 | 搜索 | 中心检测 | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | ** | 405 | 3,183 | 22,820 | 4.1s | 290ms | 3ms | 7ms | 114 MB | | **redis** | 570 | 10,350 | 75,981 | 8.1s | 640ms | 7ms | 21ms | 281 MB | curl** | 495 | 5,40,487 | 7.5s | 580ms | 4ms | 12ms | 269 MB | | **CPython** | 2,157 | 82,327 | 564,225 | 47s | 3.8s | 69ms | 166ms | 1.6 GB | | **Chromium**（base+net+url+crypto） | 5,519 | 35,178 | 454,616 | 50s | 3.5s | 24ms | 0.3ms | 1.5 GB | 冷索引 = 首次解析。暖重索引 =更改，从图形缓存加载。搜索 = `search_functions("parse")`。中心检测 = 从所有边构建入度索引 = 完整索引 + 查询后的 RSS。 在 Chromium 上实际时间.5 秒流水线）： | 时间 | % GPU | --- | --- || 解析itter） |.7s | 91% | 否 — 每个文件顺序 | | 合并 + 入口点 | 1s | 5% | 否 — | | 预分析 | 0.52.4% | 被 GPU 引擎| GPU 引擎构建 | 1.3s | — | CSR CUDA 传输 | 使之奏效的原因： - **GPU 图形 将调用图转换为 CSR 矩阵。BFS、可达性和爆炸半径都通过 GPU 上的 SpMV 运行。死代码分析：Chromium 上 49ms，CPU 为 72 秒。 - **有界查询** — 每个图形遍历都有深度限制、结果上限、分页和中心排除。estors_of("main")` 不会使您的机器内存溢出。它返回 100 个结果，并显示“可用 49,900 个结果，请细化查询。” 负责的行为。 - **图形缓存** — 合并后的图形被序列化到磁盘。热重索引时无文件更改：nginx 为 290ms，Chromium 为 3.5s。哈希 — 如果没有任何更改，则不会重新计算。 - **延迟预分析** — 爆炸半径按需通过批量 GPU SpMV 计算，而不是在启动时为每个函数预计算。因为在启动时计算整个代码库的传递闭包是一种精神病行为。 - **O(1) 中心检测** — 来自 CSR 矩阵的预计算入度数组。Chromium 455K 边上的 531 个中心节点，0.3ms。非 GPU 版本调用 `callers_of()` 每个函数，耗时 82 秒。 - **异步重工具** — 扫描器和完整代码库分析返回任务 ID。轮询获取结果。不要阻塞服务器等待 semgrep 完成。 LRU 逐出** — 可配置的引擎预算。加载 8 个代码库，当加载第 9 个时逐出最老的。引擎在需要时从磁盘重新加载。内存保持有界。 - **分区索引** — `plan_partitions()` 将大型代码库分割成可索引的块，按目录划分。每个块独立索引。跨分区查询尚未连接。 **未经测试的内容：** 完整的 Chromium 检出（350K 文件）。上述稀疏检出涵盖 base/、net/、url/、crypto/ — 5.5K 文件，35K 函数。完整树大 60 倍。如果在此规模下出现问题，请提交问题。 ## 环境变量 | 变量 | 默认值 | 控制内容 | | --- | --- | --- | | `AUDIT_MCP_INDEX_DIR` | `~/.cache/audit-mcp/indexes` | 索引存储在磁盘上的位置 | | `AUDIT_MCP_MAX_ENGINES` | `8` | 内存中引擎的最大数量，超过后 LRU 逐出机制启动 | | `AUDIT_MCP_HTTP_HOST` | `127.0.0.1` | HTTP 服务器绑定地址 | | `AUDIT_MCP_HTTP_PORT` | `18822` | HTTP 服务器端口 | ## 架构 ``` 源代码（21 种语言） | v [trailmark] -- tree-sitter 解析 --> 代码图（Python 字典） | | | v | [gpu_graph.py] -- CSR 稀疏矩阵 | | | +------+------+ | | | | [CuPy] [scipy] | GPU SpMV CPU SpMV | | | +------+------+ | | v [server.py] -- 51 工具 -------------> 结果 | +-- callers_of, ancestors_of, reachable_from --> BFS +-- dead_code, unreachable_from_entrypoints --> gpu批量 BFS +--_top_n --> gpu_graph 批量 SpMV +-- hub_names --> gpu_graph 入度数组 +-- search_constants, search_bitfields, ... --> source_search（正则表达式搜索源代码） +-- extract_class, read_function --> source_search（括号匹配提取） +-- cross_reference_bitfields --> source_search（自动变体检测） +-- children_of, includers_of --> type_resolver（继承 + 包含图 +-- scan_and_correlate, augment_sarif --> trailmark 引擎 +-- annotate_function, findings --> trailmark 引擎 +-- search_functions, paths_between --> query_bounds（有界） ``` Trailmark 负责解析和建模。GPU 引擎负责遍历。源代码搜索负责常量/类型/断言。类型解析器负责跨文件 C++ 解析。服务器负责 MCP 工具接口。 清洁的边界，无耦合。 ## 开发 ```bash pip install -e ".[dev]" # 开发依赖（pytest，ruff） pip install -e ".[gpu]" # GPU 支持（cupy-cuda11x） pip install -e ".[dev,gpu]" # 两者 python -m pytest tests/ -v # 28 个测试，<1 秒 python -m ruff check src/audit_mcp/ ``` ## 许可证 AGPL-3.0-or-later。因为如果你要基于安全工具构建，你应该回馈。这就是社会契约。