MohammedAlsabih/ai-code-auditor

# AI 代码审计工具 [](https://github.com/MohammedAlsabih/ai-code-auditor/actions/workflows/ci.yml) [](https://github.com/MohammedAlsabih/ai-code-auditor/releases) [](LICENSE) 一款针对包含 AI 生成或 AI 修改代码的代码仓库的确定性静态分析工具。 它专门检测生成代码中常见的两类缺陷：不存在的依赖项（幻觉包）和 高风险代码模式。该工具在运行时不使用任何 LLM —— 相同的输入始终 产生相同的结果，且绝不会执行被扫描代码仓库中的任何内容。 该工具并不试图证明一段代码是*谁*编写的； 它只检查生成代码中容易出现的错误。 ## 检查内容 **引擎 1 — 幻觉依赖。** 每个 import 和声明的 依赖项都会与公共仓库（PyPI、npm、Maven Central、NuGet）进行比对。声明但在其仓库中不存在的包被判定为 可能的幻觉包以及可被抢注的名称。下载量接近于零的极新包 会被标记为供应链警告。查询仅发送包*名称*；`--offline` 会禁用所有网络访问，并 将依赖仓库的规则标记为未验证，而不是进行猜测。 **引擎 2 — 高风险模式。** 通过 tree-sitter 实现的 AST 规则，按语言划分： | 家族 | 语言 | 示例 | |---|---|---| | P | 全部 | 硬编码密钥（输出时脱敏）、字符串拼接的 SQL、空的 catch 块、圈复杂度、相对于 `requires-python` 的标准库偏移 | | R | React | Rules-of-Hooks 违规、effect 依赖问题、`key={index}`、非字面量的 `dangerouslySetInnerHTML` | | N | Next.js | 基于真实模块导入图解析的服务器/客户端边界违规、`NEXT_PUBLIC_` 密钥（值不回显） | | J / D | Java / .NET | 字符串使用 `==` 比较、缺失 try-with-resources、`async void`、阻塞式的 `.Result`/`.Wait()`、原始 SQL 插值 | | S | 多种 | 可选的 Semgrep/OpenGrep 层；默认仅运行捆绑的 MIT 许可规则 | 支持的语言：Python、TypeScript/JavaScript (React、Next.js)、Java、 C#。运行该工具本身需要 Python 3.11 或 3.12；Windows 和 Linux 已由 CI 覆盖。 ## 发现级别与精度 发现结果带有兼容 SARIF 的 `level`： - `error` — 高置信度缺陷（例如：幻觉的 npm import、 密钥形状的字面量、被拼接到执行 sink 的 SQL） - `warning` — 需要审查（例如：未验证的未声明 import、 在客户端代码中读取的私有环境变量） - `note` — 信息性提示（例如：AI 风格的不完整注释） 每个发现结果还会声明其 `precision`：当规则的前提条件在机制上确定时为 `exact`；当其依赖于某种约定时为 `heuristic`（例如 Python 的 import 名称等同于包名称的约定，或 Java/.NET 的 前缀映射）。 ## 门控策略与判定 判定结果衍生自每个发现结果的 `gate_action`，而不是 仅凭级别或数量： | 级别 | 精度 | gate_action | |---|---|---| | error | exact | **block** | | error | heuristic | review | | warning | exact / heuristic | review | | note | exact / heuristic | informational | 精度为 `exact` 的 error 会阻断门控 (block)。精度为 `heuristic` 的 error 是一个强烈信号，而非 确凿证明 —— 默认情况下它要求进行审查而不是阻断（项目可以 在其配置中将其提升为 `block`，见下文）。note 永远不会触发门控。 `report.json` 中的 `summary.gate_counts` 准确显示了驱动判定结果的因素。 `code_health` 分数仅作为严重性排序指标，绝非 安全声明。 ## 分析置信度 vs. 仓库验证 这是报告摘要中两个独立的维度： - `analysis_confidence` — 文件/清单/规则分析 的*完整*程度（跳过的文件、未解析的清单、规则失败）。它不包含 任何仓库因素。 - `registry_status` — 依赖验证是否运行： `complete`、`partial`（部分查询失败 → 判定结果不能为 `pass`）、`unavailable`（预期的 `--offline`）或 `not_applicable`，仅当查询实际运行时才会提供 数字形式的 `registry_confidence`。 由于预期的 `--offline` 运行不属于分析缺陷，一次干净且完整的 离线扫描可以以 `PASS` 结束并返回退出代码 0 —— 包括在 `--strict` 模式下。依赖仓库的规则仍会作为未验证的 note 显示。 ## 执行证据 `report.json` 不仅记录发现结果，还记录每条规则是否实际运行： `analysis_manifest.execution` 保存了每个项目、每条规则的事实（符合条件 的输入、尝试、失败、被阻止或部分解析的输入、结构化 原因）以及推导出的状态：`executed`、`partial`、`failed`、`blocked`、 `unavailable`、`skipped`、`not_applicable`、`not_recorded` 或 `inconsistent`。一条运行且未发现任何问题的规则状态为 `executed` —— 这是 刻意设计的，不存在“passed”状态。报告浏览器的 **Rules** 标签页按 规则和项目可视化展示了此区块。 ## 安装 ``` python -m venv .venv .venv/Scripts/pip install -e . # core scanner .venv/Scripts/pip install -e ".[web]" # + local report explorer auditor --version # ai-code-auditor 0.1.0a1 ``` 或者安装随 [最新发布版本](https://github.com/MohammedAlsabih/ai-code-auditor/releases)附带的 wheel 包。 尚未在 PyPI 上发布。 ## 扫描 ``` auditor scan https://github.com/org/repo # clone + scan a public repo auditor scan path/to/project --output my-report auditor scan . --offline # no network at all auditor scan . --strict # REVIEW also fails (for CI) auditor scan . --no-semgrep # builtin rules only auditor scan . --semgrep-bin opengrep --semgrep-config my.yml auditor scan . --sarif # also write report.sarif auditor scan . --baseline old/report.json # mark findings new/unchanged auditor scan . --baseline old/report.json --new-only # gate on new findings only auditor scan . --config path/to/.auditor.toml # explicit project config ``` 退出代码：`0` 通过 · `1` 判定 BLOCK（或在 `--strict` 下为 REVIEW）· `2` 致命错误。输出结果保存在 `--output` 中（默认为 `auditor-report/`）： `report.md` 供人类阅读，`report.json` 供机器读取（完整的诊断账本、 `analysis_confidence`、`registry_status`、门控计数），当提供 `--sarif` 参数时还会生成 `report.sarif` （SARIF 2.1.0）—— 可导入到 GitHub 代码 扫描及其他 SARIF 消费者中。SARIF 文件包含规则元数据、 相对于代码库的路径、与行号无关的指纹以及基线状态； 它绝不包含源码片段、审查备注或机器路径。 ## 基线 `--baseline` 接收来自先前扫描的 `report.json`。每个当前的 发现结果都会通过内容指纹（项目、文件、规则、 引擎以及标准化后的匹配文本 —— 刻意去除了行号， 因此移动代码不会产生“新”的发现结果）与其进行匹配，并 标记为 `baseline_state: new | unchanged`。使用 `--new-only` 时，仅 *新*发现结果会影响判定 —— 报告依然包含所有内容，且摘要 会统计已解决的基线发现数量。典型的 CI 形态：在修复回归问题时阻断门控， 同时单独处理继承的历史遗留问题。 ## 项目配置 位于代码仓库根目录的 `.auditor.toml`（或使用 `--config PATH`）可调整 扫描行为。Schema v1 涵盖范围界定；schema v2 增加了门控策略： ``` schema_version = 2 exclude_paths = ["fixtures", "legacy/generated"] dependency_exclude_paths = ["docs"] # code rules still run there npm_roots = ["tools/scripts"] # manifestless dirs that are npm-owned [policy] heuristic_errors = "block" # promote heuristic errors from review to block [rule_levels] # per-rule level overrides, catalog-validated R007 = "warning" P005 = "error" ``` 规则级别的覆盖会透明地更改发现结果的有效级别： 报告会将原始级别保留为 `default_level`，并标记 `level_source = "project_policy"`。格式错误的配置会明确报错，且 应用的策略会被记录在 `analysis_manifest.policy` 中。 ## 报告浏览器 ``` auditor serve auditor-report/report.json --repo path/to/project --port 8765 ``` 需要安装 `[web]` 扩展。这是一个仅限本地回环、用于查看单个报告的 Web UI： 包含搜索、级别/规则/路径过滤器、只读源码查看器、规则覆盖 标签页（目录 × 执行证据）、覆盖面板，以及审查工作流 （已确认 / 误报 / 接受风险 / 备注），存储在 报告旁边的 `*.reviews.json` 辅助文件中。使用 `--baseline` 扫描的报告会获得 New/Existing 徽章以及 All/New/Existing 过滤器。 报告文件本身绝不会被修改。 ## 隐私 - 扫描和报告均在本地进行；该工具不会上传任何内容。 - 报告可能包含源码片段 —— 请以与代码本身相同的 保密级别对待 `report.json`/`report.md`。 - 在线模式仅使用包名称查询公共仓库。绝不联系 私有仓库；其背后的包将被报告为 无法验证，而不是进行查询。 - 报告文本会经过脱敏层处理（auth header、token、 密码形状的值），且绝对机器路径不会写入 报告中。脱敏是基于启发式算法的 —— 分享前请进行审查。 ## 局限性 - Java/.NET 的 import 到构件映射使用精选的前缀映射；未映射的 import 将作为未解析的警告报告，绝不会作为猜测的错误。 - Maven Central 不公开下载量，因此新包的启发式判断 在此处较弱。 - Next.js 模块图排除了 middleware、instrumentation 和 metadata 路由；由字符串构建的动态 import 路径将被报告为 未解析的边，而不是进行猜测。 - 不会分析普通 `.js` 文件中的 JSX（会分析 `.jsx`/`.tsx`）。 - Semgrep Registry 包可通过 `--semgrep-config` 选择性开启，并在 您自己的许可责任下运行；默认仅运行捆绑的 MIT 规则。 有关测试夹具的 真实输出，请参见 [`examples/report.md`](examples/report.md) 和 [`examples/report.json`](examples/report.json)；有关安全策略，请参见 [SECURITY.md](SECURITY.md)。 ## AI 提供商（仅用于连接测试） `auditor ai` 层负责管理与 LLM 提供商的连接，用于计划中的 AI 辅助审查。在现阶段，它只做两件事：列出 提供商的模型，并使用固定的探针 （`Reply with OK only.`，输出限制为 8 个 token）测试连接。**在此阶段，不会向任何模型发送任何源代码、任何 发现结果或任何报告内容。** 外部服务会收取 API 使用费，并 应用其各自的数据保留策略；Ollama 是本地选项， 不会向机器外发送任何内容。 支持的提供商：`openai` (OpenAI)、`anthropic` (Anthropic Claude)、 `xai` (xAI Grok)、`ollama` (本地 Ollama) 以及 `openai_compatible`（任何 使用 OpenAI chat API 的服务器）。无需额外安装 —— 该层 使用扫描器现有的 HTTP 协议栈。 ``` auditor ai providers # local state, no network auditor ai models --provider anthropic # explicit network call auditor ai test --provider ollama --model llama3.2 ``` 配置仅通过环境变量进行；密钥绝不会写入配置文件、 报告、SARIF、审查辅助文件或浏览器存储中： | 变量 | 含义 | |---|---| | `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` / `XAI_API_KEY` | 提供商密钥 | | `AUDITOR_OPENAI_COMPAT_BASE_URL` | OpenAI 兼容服务器的基础 URL | | `AUDITOR_OPENAI_COMPAT_API_KEY` | 该服务器的可选密钥 | | `OLLAMA_HOST` | Ollama 地址（默认 `http://127.0.0.1:11434`） | | `AUDITOR_AI_PROVIDER` / `AUDITOR_AI_MODEL` | 用于后续阶段的默认值 | OpenAI、Anthropic 和 xAI 的端点固定为官方主机； 自定义基础 URL 仅适用于 Ollama 和 OpenAI 兼容服务器，且 只能从服务器环境中获取 —— 绝不能从浏览器获取。报告 浏览器会获得一个功能相同的 **AI Providers** 标签页；打开 该标签页不会执行任何出站请求，只有明确的“刷新/测试” 按钮才会执行。 ## 开发 ``` pip install -e ".[web,dev]" # pinned pytest/mypy/ruff/type stubs python -m pytest -q # offline by design; registries are mocked python -m ruff check src python -m mypy src # config lives in [tool.mypy] cd web && npm ci && npm run typecheck && node --test tests/*.mjs && npm run build ``` 前端构建输出（`src/auditor/web/static/`）已被提交，因此 wheel 包和普通的检出无需 Node 即可工作。CI 在 Ubuntu 和 Windows、Python 3.11 和 3.12 上运行完整的测试矩阵。 ## 许可证 MIT — 请参见 [LICENSE](LICENSE)。

标签：AI代码审计, 威胁情报, 开发者工具, 逆向工具, 错误基检测, 静态代码分析