Skip to main content
Glama
Sign In
codesafe-audit-mcp

codesafe-audit-mcp

by windhxy
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

CodeSafe 代码审计 MCP

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

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

核心能力

  • 查询扫描任务及任务概要。

  • 汇总整份报告的审计进度和缺陷严重级别。

  • 按规则查看缺陷分布，分页读取缺陷。

  • 获取单条缺陷详情、源码上下文和污点传播路径。

  • 为大模型生成单条或批量审计上下文。

  • 将“确认问题、误报、遗留”结论写回 CodeSafe。

  • 写回默认关闭，并带有 dry-run、显式确认和写后回读三层保护。

Related MCP server: Code-Oracle

快速安装

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

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

文档目录

验证情况

  • 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 锁定依赖解析结果。发布前请执行完整的 部署与验收检查清单。

Available Tools

10 tools
codesafe_audit_bugA

Assemble a judgment-ready audit context for one defect.

Pulls the rule definition + taint dataflow trace + sink code context in one call, reconstructs the source→sink path, and returns it together with the judging criteria and output schema. The verdict itself is produced by the calling LLM (design §8 option A) — nothing is written to the platform.

Respond with a judgment following instructions.output_schema, grounded in context_text.

Inputs: bug_id (required), task_id (required), context_lines. Returns: object

codesafe_audit_by_ruleA

Batch-assemble audit contexts for up to max_n defects of one rule.

Resolves the rule's bugIds via codesafe_bug_summary, then builds an audit_bug context for each (capped at max_n and CODESAFE_AUDIT_BATCH_LIMIT). Returns contexts + a summary table skeleton the calling LLM can fill with verdicts. Read-only.

Inputs: task_id (required), rule_code (required), max_n. Returns: object

codesafe_audit_statusB

Summarize a report's audit progress from the platform auditState field.

Inputs: task_id (required). Returns: object

codesafe_bug_codeA

Fetch a range of source lines (1-based, inclusive) for the file behind a bug.

The platform ignores the line range and returns the whole file, so we slice the requested [begin_line, end_line] window client-side with line numbers.

Inputs: bug_id (required), task_id (required), end_line (required), begin_line (required). Returns: object

codesafe_bug_detailA

Get full defect detail: rule definition (desc/solution/CWE), the taint dataflow trace (bugTraces), exact location, and existing audit state.

Inputs: bug_id (required), task_id (required). Returns: object

codesafe_bug_summaryA

Aggregate defects by rule (from bugType). Use this to pick a rule to audit.

Returns per-rule: ruleCode, ruleName, category, severity level, and total. IDs are omitted by default; set include_ids=true to include a bounded sample.

Inputs: task_id (required), id_limit, include_ids. Returns: object

codesafe_list_bugsA

Page through defect instances.

NOTE: the server endpoint ignores level/ruleCode filtering, so when those are supplied the filter is applied client-side to this single page only (returned count may be < page_size). For a complete filtered set, use codesafe_bug_summary + codesafe_audit_by_rule.

Inputs: task_id (required), level, page_size, rule_code, +1 more. Returns: object

codesafe_list_tasksA

List quick-check scan tasks.

Returns totalCount and quickVOS (each carries taskVO.pkTask / taskName / taskStatus / language, plus owner and time). Use a pkTask as taskId below.

Inputs: page_size, page_index. Returns: object

codesafe_submit_auditA

Write audit verdicts back to the platform (POST /codesafeapi/result/audit), so the Web UI shows 误报/确认 markers and PDF exports include them.

audits: list of {bugId OR pkResbug, auditResult OR verdict, auditMemo?}.

  • bugId: the 32-char hash (from codesafe_list_bugs). A numeric pkResbug may be passed as bugId — it is auto-routed to the pkResbug field.

  • pkResbug: the numeric defect id (alternative to bugId).

  • auditResult: platform code directly (5=是问题, 6=不是问题/误报, 9=遗留).

  • verdict: real/false_positive/needs_review (mapped to 5/6/9). dry_run (default true): preview the payload without writing. To commit, CODESAFE_ENABLE_WRITE must be true and confirm_write must be explicitly true.

⚠️ This is the only tool that mutates the platform. Prefer dry_run first, and write in small batches. Each write is verified — if the bug's auditState does not actually change (e.g. ID not resolved), the tool raises instead of silently leaving only a comment.

Inputs: audits (required), task_id (required), dry_run, confirm_write. Returns: object

codesafe_task_summaryA

Get a task's metadata and code statistics (file/line counts, template, times).

Inputs: task_id (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.9/5.0

    Scored across 10 tools

    Disambiguation4/5

    Most tools have clear, distinct purposes: listing tasks vs summarizing tasks, listing bugs vs summarizing bugs. However, codesafe_bug_detail and codesafe_audit_bug overlap in providing rule definitions and taint traces, differing mainly in whether sink code and judging criteria are included. This overlap could cause an agent to select the wrong one when a raw detail view is needed versus a judgment-ready context.

    Naming Consistency3/5

    All tool names share the codesafe_ prefix and use snake_case, but the internal convention is mixed. Several use verb_noun (list_tasks, list_bugs, submit_audit), while others use noun_noun (task_summary, bug_summary, bug_detail) or verb_preposition (audit_by_rule). This lack of a uniform pattern, while still readable, reduces predictability.

    Tool Count5/5

    With 10 tools, the server is well-scoped for a code audit domain. It covers task discovery, defect exploration, audit context preparation, and verdict submission without excessive redundancy or trivial tools. The count fits comfortably within the ideal 3-15 range.

    Completeness5/5

    The tool set provides a complete workflow: list tasks, get task summaries, aggregate defects by rule, page through individual bugs, fetch detailed defect data, retrieve source code, prepare audit contexts (single and batch), check audit status, and submit verdicts. No critical operations are missing for the stated purpose of auditing code security defects.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers