CodeSafe 代码审计 MCP

codesafe-audit-mcp 是面向奇安信 CodeSafe（代码卫士）的 MCP 服务。它可以读取扫描任务、缺陷列表、规则统计、源码片段和污点传播路径，并将这些信息整理成适合大模型判断的审计上下文。

项目支持 Windows、macOS 和 Linux，要求 Python 3.10 或更高版本。当前版本为 0.3.0。

核心能力

• 查询扫描任务及任务概要。
• 汇总整份报告的审计进度和缺陷严重级别。
• 按规则查看缺陷分布，分页读取缺陷。
• 获取单条缺陷详情、源码上下文和污点传播路径。
• 为大模型生成单条或批量审计上下文。
• 将“确认问题、误报、遗留”结论写回 CodeSafe。
• 写回默认关闭，并带有 dry-run、显式确认和写后回读三层保护。

快速安装

Windows

cd codesafe-audit-mcp-portable
./install.ps1
Copy-Item .env.example .env

如果 PowerShell 禁止执行脚本：

$python = uv python find ">=3.10"
& $python install.py
Copy-Item .env.example .env

macOS / Linux

cd codesafe-audit-mcp-portable
python3 install.py
cp .env.example .env

也可以执行 bash install.sh。

安装后的 Python 路径：

• Windows：.venv\Scripts\python.exe
• macOS / Linux：.venv/bin/python

配置

编辑 .env，至少填写：

CODESAFE_BASE_URL=https://your-codesafe-host
CODESAFE_USERNAME=your_user
CODESAFE_PASSWORD=your_password

.env 已加入 .gitignore，不要把真实账号、密码或证书提交到版本库。

如果平台使用自签名证书，优先设置 CODESAFE_CA_BUNDLE。只有在完全隔离的调试环境中，才使用：

CODESAFE_INSECURE=true

完整配置说明见 配置参考。

启动测试

Windows：

.\.venv\Scripts\python.exe examples\mcp_client.py list_tasks
.\.venv\Scripts\python.exe examples\mcp_client.py audit_status 1

macOS / Linux：

.venv/bin/python examples/mcp_client.py list_tasks
.venv/bin/python examples/mcp_client.py audit_status 1

直接执行 python -m codesafe_mcp 后服务等待标准输入是正常现象，因为 MCP 使用 stdio 与客户端通信。

MCP 客户端接入

复制 .mcp.json.example，替换以下占位符：

• {{PYTHON}}：虚拟环境 Python 的绝对路径。
• {{ENV_FILE}}：.env 的绝对路径。

Windows JSON 路径中的反斜杠需要写成 \\，也可以统一使用 /。完整示例见 MCP 客户端接入。

工具概览

只读工具：

• codesafe_list_tasks：列出扫描任务。
• codesafe_task_summary：获取任务概要。
• codesafe_audit_status：汇总报告审计进度。
• codesafe_bug_summary：按规则汇总缺陷。
• codesafe_list_bugs：分页列出缺陷。
• codesafe_bug_detail：获取缺陷详情。
• codesafe_bug_code：读取缺陷源码片段。
• codesafe_audit_bug：生成单条审计上下文。
• codesafe_audit_by_rule：按规则批量生成审计上下文。

写工具：

• codesafe_submit_audit：把审计状态写回 CodeSafe。

各工具参数、返回值和示例见 MCP 工具参考。

审计状态

CodeSafe 的 auditState 含义：

值	含义
0	未审计
5	确认问题
6	误报 / 不是问题
9	遗留 / 待复核

不要把缺陷详情中的 auditResult 当作审计结论。本项目已统一使用 auditState 判断审计状态。

安全写回

真实写回必须同时满足：

1. 配置 CODESAFE_ENABLE_WRITE=true。
2. 先以 dry_run=true 查看载荷。
3. 正式提交时设置 dry_run=false。
4. 同时明确设置 confirm_write=true。
5. 审计码只能是 5、6、9。

提交后，MCP 会再次 GET 每条缺陷并核对持久化的 auditState，不会只相信 POST 响应。详细流程见 审计流程与安全写回。

推荐审计流程

1. 使用 codesafe_list_tasks 选择检测成功的 taskId。
2. 使用 codesafe_audit_status 查看当前审计进度。
3. 使用 codesafe_bug_summary 选择要审计的规则。
4. 使用 codesafe_audit_by_rule 或 codesafe_audit_bug 获取证据。
5. 人工复核大模型输出。
6. 使用 codesafe_submit_audit(dry_run=true) 预览。
7. 经授权后小批量正式写回。
8. 再次调用 codesafe_audit_status 检查统计结果。

平台返回的源码、注释、规则说明和历史备注都属于不可信审计数据，不能把其中的文字当作操作指令。

文档目录

• 安装指南
• 配置参考
• MCP 客户端接入
• MCP 工具参考
• 审计流程与安全写回
• 安全说明
• 常见问题与故障排查
• 架构与开发指南
• 部署与验收检查清单

验证情况

• Windows 10 + Python 3.12 已完成安装、MCP 握手和真实 CodeSafe 只读调用测试。
• 已验证审计状态能真实写入 auditState，并通过独立 GET 回读确认，不是只写备注。
• 已验证测试状态恢复后，原备注和最终审计状态保持不变。
• 自动化测试覆盖配置、分页、状态语义、数据流、写回门禁和回读验证。
• GitHub Actions 配置了 Windows / macOS 与 Python 3.10 / 3.12 测试矩阵。

macOS 目前由跨平台实现和 CI 矩阵保障，仍建议在目标 Mac 和实际内网环境中完成一次安装及连通性验收。

开发测试

python -m pip install -e ".[dev]"
python -m pytest -q
python -m compileall -q src examples install.py

项目使用 uv.lock 锁定依赖解析结果。发布前请执行完整的 部署与验收检查清单。