内容
# CodeInspectus，由 Synvoya 提供
[](LICENSE)
[](package.json)
**本地优先，保护隐私的安全 MCP 服务器。** 任何 AI 编码代理（Claude Code、Cursor、Codex、Windsurf、Cline、Aider）都可以调用 CodeInspectus，扫描 AI 生成的 / “vibe-coded” 代码中的实际漏洞，映射发现结果到合规框架中，以诚实的代码级别覆盖率驱动 **扫描 → 修复 → 重新扫描** 循环 — 完全在您的机器上运行，**无需账户** 和 **扫描时零网络出口**。
CodeInspectus 在一个标准化的、基于 CWE 的模式下，协调了三个最佳开源安全引擎，并添加了自己的 **AI 代码特定检查**，这些检查是通用扫描器无法检测到的：
- **Opengrep** — SAST / OWASP Top 10 （SARIF）
- **Gitleaks** — 机密泄露
- **Trivy** — 依赖项 CVEs （SCA）、IaC 错误配置、机密泄露、许可证、SBOM
- **CodeInspectus AI 检查** — 客户端机密/包暴露、Supabase RLS / 反向身份验证（CVE-2025-48757 类）、注入提示接收点、客户端可写 `user_metadata` 授权和未经净化的模型/用户输出通过 `dangerouslySetInnerHTML` 渲染（XSS / LLM05）
> CodeInspectus 捆绑了官方的、**SHA 固定的** 引擎二进制文件，并将它们作为本地子进程调用。它**不**分叉它们。
## 为什么选择 CodeInspectus？
AI 生成的应用程序通常存在安全错误，这些错误是通用扫描器无法检测到的：暴露的客户端机密、弱的 Supabase 身份验证模式、不安全的 HTML 渲染、注入提示接收点和不安全的代理/工具集成。
CodeInspectus 将成熟的本地扫描器与 AI 应用程序特定的规则相结合，然后通过 MCP 服务器公开工作流，以便编码代理可以扫描、解释并帮助修复问题，然后再发布。
## 安装
```bash
# 在您的机器上注册一次客户端（参见“客户端注册”），然后：
npx codeinspectus install-engines
```
`install-engines` 是**唯一**涉及网络的步骤。它从经过验证的 GitHub 发布 URL 下载引擎二进制文件，检查发布者签名/校验和，计算每个二进制文件的 SHA256，并将其记录在 `engines.lock.json` 中。它还将离线的 Trivy 漏洞数据库快照获取到 `~/.codeinspectus/` 中。在此之后，**扫描执行零网络 I/O**。
在任何时候重新验证您固定的二进制文件：
```bash
npx codeinspectus verify-engines
```
MCP 服务器在**每台机器上安装一次**，并在所有项目中共享 — 它**不是**每个仓库的 `npm install` 依赖项。
## 客户端注册
所有客户端使用相同的 JSON 结构；位置不同而已。
```jsonc
{
"mcpServers": {
"codeinspectus": { "command": "npx", "args": ["-y", "codeinspectus"] }
}
}
```
| 客户端 | 操作方法 |
|--------|-----|
| **Claude Code** | `claude mcp add-json codeinspectus '{"command":"npx","args":["-y","codeinspectus"]}'` |
| **Cursor** | 添加到 `~/.cursor/mcp.json` （或项目 `.cursor/mcp.json`） |
| **VS Code** | `code --add-mcp '{"name":"codeinspectus","command":"npx","args":["-y","codeinspectus"]}'` |
| **Codex / Windsurf / Cline / Aider** | 将相同的块添加到该客户端的 MCP 配置中 |
可选：放入准备好的 [`agent-rules/`](agent-rules/) 中，以便您的代理自动运行扫描 → 修复 → 重新扫描循环。
## 工具
| 工具 | 用途 |
|------|---------|
| `codeinspectus_scan` | 对路径进行完整的本地扫描（引擎 + AI 检查）。返回基于 CWE 的发现结果、补救措施和框架标签。 |
| `codeinspectus_rescan` | 在修复后重新扫描；与之前的扫描结果进行差异对比 → 已解决 / 仍存在 / 新增。 |
| `codeinspectus_compliance_report` | 每个框架的**代码级别控制覆盖率**（不是认证）。 |
| `codeinspectus_explain_finding` | 对单个发现结果进行深入解释 + 完整的补救措施。 |
| `codeinspectus_generate_sbom` | CycloneDX/SPDX SBOM （默认写入到托管目录）。 |
| `codeinspectus_list_rules` | 活动检测器、引擎版本、检测数据库 + Trivy 数据库的更新情况。 |
CodeInspectus **从不写入或删除您的代码或仓库** — 它读取并报告；您的代理应用修复程序。（可选的 SBOM 默认写入到项目外部的托管目录 — 参见 `codeinspectus_generate_sbom`。）
每次扫描还会报告一个只读的 **git 安全** 状态：如果没有 git 仓库或未提交的更改，它建议在修复前创建检查点 — 您的代理仅在您批准的情况下运行 git；该工具从不运行。
## 诚实的声明（请阅读）
- **“无出口” 是精确的：扫描时零出口。** 引擎二进制文件和初始 Trivy 数据库在**安装时**从经过验证的源下载，并带有 SHA256 验证。扫描器在断网情况下也能正常工作。**没有遥测数据。**
- **供应链固定是强制性的。** Trivy 曾在 2026 年初被两次供应链破坏；每个引擎二进制文件都在 `engines.lock.json` 中固定了 SHA 值，并在执行前验证其哈希值。CodeInspectus 拒绝运行未固定的或不匹配的二进制文件。
- **机密值在所有输出中都被遮蔽** — 类型 + 位置 + 遮蔽的预览信息。
- **合规性 = 代码级别控制覆盖率，而非认证。** CodeInspectus 报告“X 个代码可见的控件存在发现结果”，其中代码可见的子集作为明确的分母，并附有声明。它从不发出“您是 X% 合规的”或“您通过 [框架]”。基于严重性的姿态得分是单独的视图，不是百分比合规数字。**基本八项** 尤其如此：只有大约 1 个缓解措施（补丁应用程序）是代码证据 — 这**不是**基本八项评估。
- **注入提示检测是启发式的且不成熟的** — 这些发现结果的措辞为“潜在 …”，并标记为中等置信度。
- **客户端授权信任 `user_metadata` 被标记** （`ci-ai-client-metadata-authz`）。 CodeInspectus 检测到一个授权决策，该决策读取客户端可写的 Supabase `user_metadata` — 例如 `if (user.user_metadata.role === 'admin')` — 严重性为 **高**，置信度为 **中等** （CWE-639）。`user_metadata` 可由签入用户自行编辑（Supabase 的 `/auth/v1/user` 端点），因此任何人都可以自行分配 `role: 'admin'`；**在服务器控制的 `app_metadata.role` 上设置权限逻辑**。检测是文件内的（内联 + 分割变量/解构）；它**尚未**跟踪跨文件或整个对象别名流程（计划中）— 参见 [good-first-issue](docs/good-first-issues/user-metadata-authz-rule.md)。
- **未经净化的模型或用户输出以原始 HTML 渲染会被标记** （`ci-ai-llm-output-dangerous-html`）。 CodeInspectus 检测到不受信任的**请求输入**或**LLM/模型输出**流入 `dangerouslySetInnerHTML` 而没有净化 — 直接 XSS 接收点（CWE-79/116；OWASP **LLM05** 在模型输出路径上），严重性为 **高**，置信度为 **中等**；用 `DOMPurify.sanitize(...)` 包装该值可以消除警告。它**尚未**跟踪通过**组件道具、数据库行或模板数据**到达的不受信任的值（计划中）。
## 语言支持
简单来说，什么运行在什么上。商品引擎很广泛；**CodeInspectus AI 代码检查（护城河）今天专注于 JavaScript/TypeScript** — 计划支持更多语言。因此，在 Python/Go/Rust/等仓库中，您仍然可以获得完整的机密、依赖项、IaC 和 SBOM 覆盖（以及 Python SAST），但 AI 代码特定检查不会触发。这是声明的，以便您不会推断出不存在的覆盖。
| 层 | 涵盖内容 | 语言/生态系统范围 |
|-------|----------------|----------------------------|
| **机密** — Gitleaks + CodeInspectus 客户端机密检查 | 硬编码凭证、泄露密钥 | **任何语言。** 检测基于值/模式，而非语言解析。 |
| **依赖项（CVEs/SCA）、IaC 错误配置、SBOM、许可证** — Trivy | 漏洞依赖项、基础设施错误配置、物料清单 | **许多语言和包生态系统以及 IaC 格式** — 参见 [Trivy 文档](https://trivy.dev)。 |
| **SAST** — Opengrep + CodeInspectus `security-baseline` | 注入、XSS、SSRF、弱加密、不安全反序列化 | **JavaScript、TypeScript、Python。** CodeInspectus 提供了自己的 MIT 规则集，并使用 **无网络注册包** 运行 Opengrep，因此 SAST 覆盖范围恰好是这些语言 — 故意比 Opengrep 的完整引擎更窄。 |
| **AI 代码检查（护城河）** — 客户端机密/包暴露、Supabase RLS、注入提示接收点、客户端可写 `user_metadata` 授权、未经净化的输出 XSS | AI 代码 / vibe 编码失败模式，引擎无法检测到 | **仅限 JavaScript / TypeScript** （包括 `.jsx/.tsx/.mjs/.cjs`；客户端机密检查还读取 JS 框架文件 `.vue/.svelte/.astro/.html`）。Supabase RLS 分析 `.sql` （以及 `.ts/.js` 边缘函数）。**计划支持更多语言**。 |
## 合规框架（代码可见子集）
NIST CSF 2.0 · ISO/IEC 27001:2022 · SOC 2 · CIS Controls v8.1 · 基本八项（仅补丁应用程序）· OWASP Top 10 （2021）· OWASP LLM Top 10 （2025）。
MITRE ATT&CK 技术仅作为相关对手上下文显示，而非作为覆盖率分数。
> **合规性映射由 AI 起草，经网络安全从业者（Synvoya）审查** — 仅限代码级别覆盖率，而非审计或认证。欢迎社区审查。** CWE→控制映射由 AI 起草，政策审查员（维护者）审查，社区验证通过 — 参见 [`docs/COMPLIANCE-RATIONALE.md`](docs/COMPLIANCE-RATIONALE.md) 和 [`CONTRIBUTING.md`](CONTRIBUTING.md)。 基本八项 **不是** 覆盖视图：只有补丁应用程序是代码证据（~1 of 8）— 这**不是**基本八项评估。
## 工作原理
```
代理 → codeinspectus_scan → [Opengrep | Gitleaks | Trivy] + AI 检查
→ SARIF 标准化 → 去重（包括 Trivy⨯Gitleaks 机密重叠）
→ 基于 CWE 的发现结果 → 合规性映射 → 紧凑的 JSON + 摘要
ALL LOCAL. 扫描时无网络出口。
```
## 示例报告
- [Next.js + Supabase SaaS 应用](examples/reports/nextjs-supabase.md)
- [AI 聊天机器人 / RAG 应用](examples/reports/ai-chatbot-rag.md)
- [Node/React 应用](examples/reports/node-react.md)
## 商标
“CodeInspectus”是该免费、开源项目（npm `codeinspectus`，`codeinspectus.com`）的名称。“Code Inspect”是一个描述性短语，在一个拥挤的命名空间中；注册可用性不是商标清除，名称**不被声称为商标**。
## 开发
```bash
npm install
npm run build # tsc --noEmit && tsup (必须编译干净)
npm run eval # ≥10 次评估针对 fixtures/vulnerable-app
npm run inspector # npx @modelcontextprotocol/inspector node dist/index.js
```
此仓库的生成方式（一个可审计的、允许列表种子）和端到端构建： [`docs/BUILD.md`](docs/BUILD.md).
## 贡献
CodeInspectus 是一个 **单独的、免费的、开源** 项目，由一名网络安全从业者 **Synvoya** 构建和维护。背后没有公司，也没有产品可供销售 — 这就是为什么外部审查很重要。
**独立审查是真正需要的**，不是礼貌用语。如果您从事安全工作，您的审查就是贡献。
两个审查帮助最大的领域：
- **合规性 CWE→控制映射。** 这些由 **AI 起草，然后由维护者审查政策** — 它们 **未经独立验证。** 每个映射都经过三个明确的状态：**AI 起草 → 维护者政策审查 → 社区验证。** 今天几乎所有内容都处于前两个状态；社区验证计数为 **0 of 96**，并且诚实地报告，而不是隐藏。 将映射移至 *社区验证* 需要证据（控制主要来源的引用 + 您的依据）— 参见 [`CONTRIBUTING.md`](CONTRIBUTING.md) 中的标准和流程；每个映射的理由和置信度都记录在 [`docs/COMPLIANCE-RATIONALE.md`](docs/COMPLIANCE-RATIONALE.md) 中。
- **检测规则** (`detection-db/**`, `src/ai-checks/**`)。欢迎新的规则、精度修复和假阳性报告。合并标准是 **精度**：一个证明真实阳性的固定装置，和一个近似装置证明规则 **不** 过度触发。详细信息参见 [`CONTRIBUTING.md`](CONTRIBUTING.md)。
CodeInspectus 声称 — 以及它故意 **不** 声称 — 的内容都写在文档中，以便您在信任某个数字之前进行检查：诚实声明（[合规框架](#合规框架代码可见子集) 部分上方和 [`docs/COMPLIANCE-RATIONALE.md`](docs/COMPLIANCE-RATIONALE.md) 中）和三态诚实度指标。如果某些内容听起来过于自信，那是一个错误 — 请打开一个问题。
工作流：**fork → branch → PR**；维护者审查和合并（外部贡献者不直接推送）。 — *Synvoya（维护者，网络安全从业者）*
## 好的第一个贡献
- 为不安全的原始内部 HTML 接收点 (`ci-ai-llm-output-dangerous-html`) 添加一个固定装置。
- 改进 Supabase `user_metadata.role` 授权检查的检测。
- 添加对暴露的 `NEXT_PUBLIC_OPENAI_API_KEY` 和类似客户端 AI 密钥的检测。
- 添加一个规则，用于检查传递给服务器端 `fetch()` 的用户控制 URL。
- 添加一个规则，用于检查模型输出传递给 `eval`、`Function`、shell 命令或不安全的工具调用。
- 为 Next.js `/api/admin/*` 路由添加缺少的身份验证保护检查。
- 验证一个 CWE 到 OWASP Top 10 的映射。
- 验证一个 CWE 到 SOC 2 / ISO 27001 的映射。
- 为现有规则添加一个易受攻击的固定装置和预期发现结果快照。
## 变更日志
每个版本的发布说明都记录在 [`CHANGELOG.md`](CHANGELOG.md) 中。当前：**v0.2.0**。
## 许可证
CodeInspectus：MIT。捆绑引擎：Opengrep（LGPL-2.1），Gitleaks（MIT，仅 CLI），Trivy（Apache-2.0）— 捆绑编译二进制文件的所有许可。
