# CodeSafe 代码审计 MCP

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

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

## 核心能力

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

## 快速安装

### Windows

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

如果 PowerShell 禁止执行脚本：

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

### macOS / Linux

```bash
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`，至少填写：

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

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

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

```dotenv
CODESAFE_INSECURE=true
```

完整配置说明见 [配置参考](docs/configuration.md)。

## 启动测试

Windows：

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

macOS / Linux：

```bash
.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 客户端接入](docs/mcp-client.md)。

## 工具概览

只读工具：

- `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 工具参考](docs/tools.md)。

## 审计状态

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 响应。详细流程见 [审计流程与安全写回](docs/audit-writeback.md)。

## 推荐审计流程

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` 检查统计结果。

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

## 文档目录

- [安装指南](docs/installation.md)
- [配置参考](docs/configuration.md)
- [MCP 客户端接入](docs/mcp-client.md)
- [MCP 工具参考](docs/tools.md)
- [审计流程与安全写回](docs/audit-writeback.md)
- [安全说明](docs/security.md)
- [常见问题与故障排查](docs/troubleshooting.md)
- [架构与开发指南](docs/architecture-development.md)
- [部署与验收检查清单](docs/release-checklist.md)

## 验证情况

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

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

## 开发测试

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

项目使用 `uv.lock` 锁定依赖解析结果。发布前请执行完整的 [部署与验收检查清单](docs/release-checklist.md)。