ai-code-scanner

@guardbee/mcp-ai-code-scanner

🇬🇧 English | 🇹🇷 Türkçe | 🇨🇳 中文 | 🇯🇵 日本語 | 🇰🇷 한국어 | 🇧🇷 Português | 🇪🇸 Español | 🇩🇪 Deutsch

一个 MCP（Model Context Protocol）服务，用于扫描代码库中常见于 LLM/AI 集成的安全模式。

secret-scanner 会查找泄露的密钥/API 密钥，而此软件包查找的是模式：模型输出受到多大程度的信任、它可以调用的工具权限有多高、发送给第三方 LLM 的数据有哪些——这些都是静态凭证扫描无法发现的风险。

默认关闭遥测。设置 GUARDBEE_TELEMETRY=1 后，服务会发送服务、工具、成功状态、耗时和文件路径等简短参数值；较长的字符串以及 content、token 或 password 等字段会替换为占位符。请参阅 @guardbee/mcp-telemetry。

Claude ──► ai-code-scanner ──► Your codebase
              │
              ├─ Client-exposure    (dangerouslyAllowBrowser: true)
              ├─ Output handling    (eval(llmOutput), unvalidated JSON.parse)
              ├─ Excessive agency   (an agent tool named execute_command)
              ├─ Data privacy       (email/national ID interpolated directly into a prompt)
              └─ Prompt injection   (raw request data mixed into a system prompt)

---

功能

• 10 种模式，5 个类别——客户端暴露、输出处理、权限过度、数据隐私、提示词注入
• 每条发现都包含风险原因及应对方法（recommendation），而不仅仅是“发现了问题”
• SARIF 2.1.0 输出——支持 CI/CD 集成（GitHub Code Scanning 等）
• 支持通过 guardbee.yml 配置文件进行配置
• 自定义规则包——通过 JSON 文件使用组织专属模式（KVKK/GDPR 字段名、内部工具名）扩展检测，无需分叉项目
• 36 项单元测试——每种内置模式均有一个阳性场景和一个阴性（误报）场景，另有自定义规则加载/验证测试

---

快速开始

Claude Desktop / MCP 客户端

{
  "mcpServers": {
    "guardbee-ai-code-scanner": {
      "command": "npx",
      "args": ["-y", "@guardbee/mcp-ai-code-scanner"]
    }
  }
}

CLI（CI/CD）

npx @guardbee/mcp-ai-code-scanner scan ./src --fail-on=high --format=sarif > results.sarif

---

MCP 工具

工具	描述
scan_text	扫描给定的文本/代码片段
scan_file	扫描单个文件
scan_directory	递归扫描目录（自动跳过 node_modules、.git、dist）
list_patterns	按类别列出所有受支持的模式

---

检测到的模式

类别	模式	严重性	含义
客户端暴露	openai_dangerously_allow_browser	严重	OpenAI 密钥泄露到浏览器
客户端暴露	client_bundled_ai_api_key	严重	AI 密钥通过 NEXT_PUBLIC_/VITE_/REACT_APP_ 进入客户端包
输出处理	eval_llm_output	严重	通过 eval()/Function() 将模型输出作为代码执行
输出处理	exec_llm_output	严重	将模型输出传递给 shell 命令（命令注入）
输出处理	llm_output_dangerously_set_inner_html	高	将模型输出作为原始 HTML 渲染（XSS）
输出处理	llm_json_no_validation	中	对模型输出执行 JSON.parse，但未进行架构验证
过度授权	excessive_agency_tool_name	高	授予 Agent shell/代码执行能力的工具
过度授权	unbounded_agent_loop	中	没有迭代次数上限的 Agent 循环（成本/DoS）
数据隐私	pii_field_in_llm_prompt	高	电子邮件、国民身份证号或银行卡号等数据直接进入提示词
提示词注入	unsanitized_input_in_system_prompt	中	将原始请求/用户数据混入系统提示词

这些是启发式检测结果——基于静态文本模式扫描，而非完整的 AST 分析。此设计旨在降低误报率，但仍应手动审查每条检测结果。

---

配置（guardbee.yml）

ai-code-scanner:
  fail-on: high       # any | critical | high | medium | low | none
  max-files: 5000
  rules-dir: .guardbee/rules   # custom rule packs, see below
  exclude:
    - ".test.ts"
    - "fixtures/"

---

自定义规则

内置模式涵盖常见的 AI/大模型集成错误，但字段名称和内部约定（例如哪些 prop 名称承载受 KVKK 监管的数据）因项目而异。将一个或多个 JSON 文件放入 .guardbee/rules/（可通过 rules-dir 配置），扫描时这些规则会与内置规则合并——CLI 和 MCP 服务均适用（list_patterns 会将其标记为 (custom)）。

一个文件包含单个规则对象或规则对象数组：

{
  "id": "kvkk_musteri_tc_no",
  "name": "musteriTcNo interpolated into a prompt",
  "category": "data-privacy",
  "pattern": "musteriTcNo",
  "flags": "gi",
  "severity": "high",
  "recommendation": "Mask the national ID before it enters the prompt."
}

category 可选值为 client-exposure | output-handling | excessive-agency | data-privacy | prompt-injection | cost-control；severity 可选值为 critical | high | medium | low。pattern 是 JS 正则表达式源字符串 （flags 默认为 "g"）。如果规则 ID 与内置规则或其他自定义规则冲突，该规则将被拒绝——扫描器会继续运行，但会向 stderr 报告问题并跳过该条规则。

---

开发

npm run build
npm test             # 36 unit tests

---

许可证

MIT — GuardBee

反馈

有问题、想法或发现误报？请在 GitHub Discussions 中发起讨论，或提交问题。如果 GuardBee 对你有帮助，请在仓库点一个 ⭐，帮助其他人发现它。