Synvoya/codeinspectus

# CodeInspectus，由 Synvoya 提供 [](LICENSE) [](package.json)    [](https://glama.ai/mcp/servers/Synvoya/codeinspectus) **一个本地优先、注重隐私的安全 MCP server。** 任何 AI 编码代理 (Claude Code、Cursor、Codex、Windsurf、Cline、Aider) 都可以调用 CodeInspectus 来 扫描 AI 生成的 / “凭感觉写 (vibe-coded)” 的代码以查找真实漏洞，将发现的结果映射到 合规框架作为诚实的代码级覆盖率，并驱动一个 **扫描 → 修复 → 重新扫描** 的循环 —— 完全在你的机器上运行，**无需账户**，且在扫描时 **零网络出站流量**。  CodeInspectus 在一个标准化的、以 CWE 为键的 schema 背后协调了三个顶级的 OSS 引擎，并添加了其自有的通用扫描器会漏掉的 **针对 AI 代码的特定检查**： - **Opengrep** — SAST / OWASP Top 10 (SARIF) - **Gitleaks** — 密钥 - **Trivy** — 依赖项 CVE (SCA)、IaC 错误配置、密钥、许可证、SBOM - **CodeInspectus AI 检查** — 客户端密钥/bundle 泄露、Supabase RLS / 反向认证 (CVE-2025-48757 类)、prompt-injection sinks、 客户端可写的 `user_metadata` 授权，以及未经清理的通过 `dangerouslySetInnerHTML` 渲染的模型/用户输出 (XSS / LLM05) ## 为什么选择 CodeInspectus？ AI 生成的应用在发布时通常带有通用扫描器无法发现的错误：暴露的 客户端密钥、薄弱的 Supabase 认证模式、不安全的 HTML 渲染、prompt-injection sinks，以及不安全的代理/工具集成。 CodeInspectus 将经过验证的本地扫描程序与特定于 AI 应用的规则相结合，然后通过 MCP server 公开工作流，以便编码代理可以在发布前 扫描、解释并帮助修复问题。 ## 安装 **前提条件：** **Node.js ≥18**，并且 `PATH` 中需要有 [**cosign**](https://github.com/sigstore/cosign) 以供 `install-engines` 使用。签名验证是**故障关闭 (fail-closed)** 的：如果没有 cosign，**Opengrep** 和 **Trivy** 将**不会**被锁定 —— `install-engines` 对它们返回非零退出状态 —— 因此请先安装它 (`brew install cosign`)。**Gitleaks** 通过校验和进行验证，不需要 cosign。 ``` # 每台机器使用你的 agent 注册一次（参见 "Client registration"），然后： npx codeinspectus install-engines ``` `install-engines` 是**唯一**接触网络的步骤。它从验证过的 GitHub 发布 URL 下载 引擎二进制文件，检查发布者 签名/校验和，计算每个二进制文件的 SHA256，并将其记录在 `engines.lock.json` 中。它还会将离线的 Trivy vulnerability-DB 快照获取 到 `~/.codeinspectus/` 中。在此之后，**扫描执行零网络 I/O。** 随时重新验证你锁定的二进制文件： ``` npx codeinspectus verify-engines ``` MCP server 是**每台机器安装一次**的，并在你所有的 项目中共享 —— 它**不是**每个 repo 的 `npm install` 依赖项。 ## 客户端注册 各地的 JSON 结构相同；只是位置不同。 ``` { "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 config 中 | 可选：放入现成的 [`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` | 活动的检测器、引擎版本、检测-DB + Trivy-DB 的新鲜度。 | CodeInspectus **绝不会编辑或删除你的源代码或代码库** —— 它只读取和 报告；由你的代理应用修复。它将引擎数据和扫描历史记录存储在 `~/.codeinspectus` 下；它写入的唯一文件是可选的 SBOM —— 默认情况下写入托管目录，或你选择的路径（参见 `codeinspectus_generate_sbom`）。 每次扫描还会报告一个只读的 **git-safety** 状态：如果没有 git repo 或 未提交的更改，它会建议在修复前创建一个检查点 —— 你的代理 只有在你的批准下才会运行 git；该工具从不这样做。 ## 诚实声明（请阅读） - **“无网络出站”是准确的：在 _扫描时_ 零网络出站。** 引擎二进制文件和 初始 Trivy DB 是在 _安装时_ 从经过验证的来源获取的，并带有 SHA256 验证。扫描程序可以在断网的情况下运行。**永远没有任何 telemetry。** - **强制进行供应链锁定。** Trivy 在 2026 年初曾两次遭到供应链攻击；每个引擎二进制文件都在 `engines.lock.json` 中进行了 SHA 锁定，并且 在执行前会验证其哈希值。CodeInspectus 拒绝运行未锁定或不匹配的二进制文件。 - **在所有输出中，密钥的值都会被隐去** —— 仅显示类型 + 位置 + 隐去后的预览。 - **合规性 = 代码级控制覆盖率，绝不是认证。** CodeInspectus 报告“N 个 **代码可见的** 控制中有 X 个具有发现结果”，其中代码可见的子集作为明确的分母，并带有固定的免责声明。它从不会输出 “你的合规度为 X%”或“你通过了 [框架]”。基于严重性加权的安全态势 得分是一个单独的视图，不是合规度百分比。**Essential Eight** 尤其如此：只有约 8 个缓解措施中的 1 个（Patch Applications）具有代码证据 —— 这 **不是** Essential Eight 评估。 - **Prompt-injection 检测是启发式的且不够成熟** —— 这些发现 被表述为“潜在的 …”并被标记为中等置信度。 - **信任 `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` endpoint)，因此任何人都可以自行分配 `role: 'admin'`；**请改为在服务器控制的 `app_metadata.role` 上控制特权逻辑。** 检测是文件内的 （内联 + 分离变量/解构）；它**尚未**追踪跨文件或整个对象别名的 流程（已规划） —— 参见 [good-first-issue](docs/good-first-issues/user-metadata-authz-rule.md)。 它还会捕获相关的错误做法：在客户端可访问的代码中包含 Supabase **`service_role` key 值**（**严重**），以及在一个**暴露给客户端的 env 前缀**（如 `NEXT_PUBLIC_…`）背后的 `service_role` key（**高**）。 - **未经清理的作为原始 HTML 渲染的模型或用户输出会被标记** (`ci-ai-llm-output-dangerous-html`)。 CodeInspectus 检测未经清理就流入 `dangerouslySetInnerHTML` 的不受信任的 **request 输入** 或 **LLM/模型输出** —— 这是一个直接的 XSS sink (CWE-79/116; OWASP **LLM05** 在 模型输出路径上)，严重性为 **高**，置信度为 **中**；将该值包裹在 `DOMPurify.sanitize(...)` 中可消除警告。它**尚未**追踪通过 **组件 props、数据库行或模板数据** 到达的不可信值 （已规划）。 ## 语言支持 简而言之，什么能在什么上运行。通用引擎覆盖面很广；**CodeInspectus AI 代码检查（护城河）目前专注于 JavaScript/TypeScript** —— 计划支持更多 语言。因此，在 Python/Go/Rust 等 repo 上，你仍然可以获得完整的密钥、依赖项、 IaC 和 SBOM 覆盖（以及 Python SAST），但 AI 代码特定的检查不会触发。 此处声明这一点是为了避免你推断出不存在的覆盖率。 | 层 | 覆盖内容 | 语言 / 生态系统范围 | |-------|----------------|----------------------------| | **密钥** — Gitleaks + CodeInspectus 客户端密钥检查 | 硬编码凭证、泄露的密钥 | **任何语言。** 检测是基于值/模式的，而不是由语言解析的。 | | **依赖项 (CVE/SCA)、IaC 错误配置、SBOM、许可证** — Trivy | 易受攻击的依赖项、基础设施错误配置、物料清单 | **许多语言和包生态系统以及 IaC 格式** —— 参见 [Trivy 文档](https://trivy.dev)。 | | **SAST** — Opengrep + CodeInspectus `security-baseline` | injection、XSS、SSRF、弱加密、不安全的反序列化 | **JavaScript、TypeScript、Python。** CodeInspectus 附带了自己的 MIT 规则集，并在**没有网络 registry 包** 的情况下运行 Opengrep，因此 SAST 覆盖范围恰好是这些语言 —— 故意比 Opengrep 的完整引擎要窄。 | | **AI 代码检查（护城河）** — 客户端密钥/bundle 泄露、Supabase RLS、prompt-injection sinks、客户端可写的 `user_metadata` 授权、未清理输出的 XSS | 引擎遗漏的 AI 代码 / 凭感觉写代码的失败模式 | **仅限 JavaScript / TypeScript**（包括 `.jsx/.tsx/.mjs/.cjs`；客户端密钥检查还会读取 JS 框架文件 `.vue/.svelte/.astro/.html`）。Supabase RLS 分析 `.sql`（以及 `.ts/.js` Edge Functions）。**计划支持更多语言。** | ## 合规框架（代码可见的子集） NIST CSF 2.0 · ISO/IEC 27001:2022 · SOC 2 · CIS Controls v8.1 · Essential Eight （仅限 Patch Applications） · OWASP Top 10 (2021) · OWASP LLM Top 10 (2025)。 MITRE ATT&CK 技术仅作为相关的对手上下文显示，绝不能作为 覆盖率得分。 ## 工作原理 ``` agent → codeinspectus_scan → [Opengrep | Gitleaks | Trivy] + AI checks → SARIF normalize → dedup (incl. Trivy⨯Gitleaks secret overlap) → CWE-keyed findings → compliance map → compact JSON + summary ALL LOCAL. NO NETWORK EGRESS AT SCAN TIME. ``` ## 示例报告 - [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” 是拥挤命名空间中的一个描述性短语； registry 可用性并不代表商标许可，并且该名称**不主张作为 商标**。 ## 开发 ``` npm install npm run build # tsc --noEmit && tsup (must compile clean) npm run eval # ≥10 evals against fixtures/vulnerable-app npm run inspector # npx @modelcontextprotocol/inspector node dist/index.js ``` 此存储库是如何生成的（一个可审计的、allow-list seed）以及端到端构建的： [`docs/BUILD.md`]()。 ## 更新日志 每个版本的发布说明位于 [`CHANGELOG.md`](CHANGELOG.md) 中。当前：**v0.3.0**。 ## 许可证 CodeInspectus：MIT。捆绑的引擎：Opengrep (LGPL-2.1)、Gitleaks (MIT，仅限 CLI)、Trivy (Apache-2.0) —— 对于捆绑编译后的二进制文件而言，所有这些都属于宽松许可。

标签：AI安全, Chat Copilot, LLM防护, MCP服务, MITM代理, SAST, 安全合规, 暗色界面, 盲注攻击, 秘密扫描, 网络代理, 自动化攻击, 静态代码扫描