secret-scanner

@guardbee/mcp-secret-scanner

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

一个 MCP 服务，可扫描源文件、目录和环境配置，查找暴露的 API 密钥、密码、令牌及其他机密。直接询问 Claude，了解你的项目是否泄露了机密。

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

---

功能

• 76 种密钥模式 — AWS、Azure、GCP、GitHub、GitLab、Stripe、OpenAI、Anthropic、OpenRouter、Groq、Hugging Face、Slack、Twilio、SendGrid、DigitalOcean、Cloudflare、Supabase、Vault、PyPI、Shopify、Linear、Notion、Atlassian 等；还包括土耳其服务商 iyzico、PayTR、Netgsm 和 İleti Merkezi，它们的密钥没有前缀，因此按变量名匹配。规则位于 @guardbee/guard-core，因此 @guardbee/mcp-security-proxy 会在运行时对工具结果中的相同格式进行掩码处理
• 文件和目录扫描 — 扫描单个文件或整个项目目录树
• Git 历史和暂存区扫描 — --history 会扫描每个提交新增的所有行，因此，即使密钥已从文件中删除，只要仍留在仓库中，就能被发现，并在添加该密钥的提交处报告一次（包含作者和日期）；--staged 仅扫描即将提交的内容
• 基线 — --write-baseline 会将今天发现的问题记录为哈希值（绝不保存密钥，可安全提交）；之后，--baseline 只会报告新发现的问题，因此现有仓库无需先修复所有问题，就能在 CI 中启用扫描器。SARIF 结果带有稳定的 partialFingerprints 值
• 高熵值 — 即使没有服务商规则能识别其格式，分配给类似密钥名称的随机值（例如 .env 中的 WEBHOOK_SIGNING_SECRET=…、YAML 中的 client_secret:、JSON 中的 "internalApiKey"）也会被报告。随机性按香农熵衡量（十六进制值需至少 32 个字符；不含数字的值需要更多位，因此驼峰式密码短语不算）；public/publishable、*_hash、*_id 和 *_url 名称、占位符及 ${VAR} 引用会被忽略，已由服务商规则报告的值不会重复报告。严重级别为中等，在测试文件中为低；--no-entropy（或 MCP 工具中的 entropy: false）可关闭此功能
• Agent 对话记录 — scan --agent-history（MCP：scan_agent_history）会扫描编码 Agent 保存在你计算机上的内容：Claude Code（~/.claude/projects、~/.claude.json）、Codex（~/.codex）、Gemini CLI（~/.gemini/tmp）和 Continue（~/.continue/sessions）。粘贴到聊天中的密钥，或 Agent 运行的命令打印出的密钥，都会留在这些记录中——而且此前已发送给模型服务商，因此应轮换密钥。每个密钥会按 Agent 报告一次，并注明出现次数；除非指定 --entropy，否则此处会关闭熵检查，因为对话记录中充满了 Agent 读取过的代码
• 超大行文件 — 大于 1 MB 的 .jsonl、.ndjson、.ipynb 和 .log 文件（对话记录、含输出的笔记本、日志）会逐行读取，而非跳过
• 实时验证（仅限 CLI） — --verify 会通过只读身份验证端点询问各服务商，检查发现的密钥是否仍然有效（GitHub /user、OpenAI /models、Slack auth.test 等）：GitHub、GitLab、OpenAI、Anthropic、Slack、Stripe、Hugging Face、npm、SendGrid、Groq、OpenRouter 和 DigitalOcean。每个密钥只会发送给对应的服务商一次，且绝不会出现在输出中；发现结果会标记为 live / invalid / unknown，有效密钥会优先列出。--fail-on=live 仅在仍然有效的密钥存在时让 CI 失败。MCP 工具绝不会进行验证，因此 Agent 无法自行将你的密钥发送到任何地方
• 智能跳过 — 自动跳过 node_modules、.git、dist、build、.next 等目录
• 安全脱敏 — 匹配内容显示为前 4 个字符 + 星号 + 后 4 个字符
• 允许列表支持 — 可将已知的测试值或假值加入允许列表
• 71 项单元测试 — 测试套件 100% 通过

---

快速开始

npm install -g @guardbee/mcp-secret-scanner

添加到 claude_desktop_config.json：

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

---

MCP 工具

工具	描述
scan_text	扫描给定文本中的密钥
scan_file	扫描单个文件
scan_directory	递归扫描目录及其子目录
scan_git	扫描 git 仓库暂存的更改，或每次提交新增的行（历史记录）
scan_agent_history	扫描此机器上编码 Agent 的对话记录（Claude Code、Codex、Gemini CLI、Continue）
list_patterns	列出所有启用的密钥模式

使用示例

你可以向 Claude 提问：

“扫描我的项目，查找密钥：/Users/me/my-app”

“这个 .env 文件中有密钥吗？”

“这段文本安全吗：export API_KEY=sk-abc123...”

---

检测到的密钥类型

类别	示例
云服务	AWS 访问密钥、AWS 密钥、GCP API 密钥
源代码管理	GitHub PAT、GitLab Token
支付	Stripe 密钥/可发布密钥
AI	OpenAI API 密钥、Anthropic API 密钥、HuggingFace Token
通信	Slack Bot Token、Twilio Auth Token、SendGrid 密钥
数据库	PostgreSQL URL、MySQL URL、MongoDB URI、Redis URL
密码学	RSA 私钥、EC 私钥、OpenSSH 密钥、PGP 密钥
Web	JWT Token、Bearer Token
软件包/平台	npm Token、Docker Hub Token、Vercel Token
通用	SECRET=、PASSWORD=、API_KEY= 模式

---

安全说明

此工具会对扫描结果中匹配到的值进行部分脱敏（例如 sk_live_abc1...xyz9）。完整值绝不会被记录或导出。

---

CLI — CI/CD 集成

除了 MCP 服务模式外，也可以直接将其用作 CLI：

# Scan a project directory
npx @guardbee/mcp-secret-scanner scan ./my-project

# Scan a single file
npx @guardbee/mcp-secret-scanner scan .env

# Fail only on critical/high
npx @guardbee/mcp-secret-scanner scan . --fail-on=high

# JSON output (for CI reporting)
npx @guardbee/mcp-secret-scanner scan . --format=json
# Secrets pasted into Claude Code / Codex / Gemini CLI / Continue sessions on this machine
npx @guardbee/mcp-secret-scanner scan --agent-history
# Which of the found keys still work? (sends each key to its own provider)
npx @guardbee/mcp-secret-scanner scan . --history --verify --fail-on=live
# Pre-commit: only the lines you are about to commit
npx @guardbee/mcp-secret-scanner scan --staged

# Every commit on every branch (finds keys deleted from the files)
npx @guardbee/mcp-secret-scanner scan . --history
npx @guardbee/mcp-secret-scanner scan . --history=main..HEAD   # just this branch

# Adopt an existing repo: record known findings once, then fail only on new ones
npx @guardbee/mcp-secret-scanner scan . --history --write-baseline=.guardbee-secrets-baseline.json
npx @guardbee/mcp-secret-scanner scan . --history --baseline=.guardbee-secrets-baseline.json

退出代码： 0 = 未发现密钥 · 1 = 发现密钥 · 2 = 出错

GitHub Actions

name: Secret Scan
on: [push, pull_request]

jobs:
  secret-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0   # full history for --history
      - name: Scan for exposed secrets
        run: npx @guardbee/mcp-secret-scanner scan . --history --baseline=.guardbee-secrets-baseline.json --fail-on=high

GitLab CI

secret-scan:
  image: node:20
  script:
    - npx @guardbee/mcp-secret-scanner scan . --fail-on=high
  only:
    - merge_requests
    - main

Pre-commit Hook

# .git/hooks/pre-commit
npx @guardbee/mcp-secret-scanner scan --staged --fail-on=high || exit 1

---

开发

npm install
npm test          # 71 unit tests
npm run build     # TypeScript compile

---

许可证

MIT — GuardBee

反馈

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