secretguard-mcp

secretguard-mcp

一个 MCP（Model Context Protocol）服务，用于扫描代码字符串中的硬编码密钥——AWS 密钥、Stripe 密钥、GitHub 令牌、Google API 密钥和 OAuth 客户端密钥、Slack 令牌和传入的 webhook URL、Shopify 访问令牌、Telegram 机器人令牌、DigitalOcean 令牌、Hugging Face 令牌、Notion API 令牌、Mailchimp API 密钥、Postman API 令牌、Linear API 密钥、Readme API 密钥、Clojars API 令牌、Pulumi API 令牌、OpenAI 密钥、Anthropic 密钥、npm 访问令牌、SendGrid 密钥、Twilio API 密钥、Azure Storage 帐户密钥、包含密码的数据库连接字符串、私钥块、JWT，以及通用高熵凭据——让 AI 编码 Agent（Claude Code、Cursor、Windsurf 等）能在写入文件或提交代码之前发现密钥，而不是等到 CI/PR 审查时才发现。它只提供一个工具 scan_for_secrets，完全在本地通过 stdio 运行，无需 API 密钥，且绝不会返回原始密钥值——每条发现都会经过脱敏处理。

为什么要开发这个项目

secret-scan-action 已经能在 CI 中捕获这些密钥，并在每个 PR 上运行。这固然必要，但为时已晚——等它运行时，密钥已经写入、提交并推送。此项目复用同一套检测引擎（相同的规则、熵检测和脱敏处理），但将其作为工具调用提供给 Agent，让检测可以在生成内容时进行，在密钥接触磁盘或历史记录之前将其发现。

功能说明

调用 scan_for_secrets 时：

1. 将输入的 code 字符串拆分成多行。
2. 运行与 secret-scan-action 相同的两层规则集：
   • 模式规则（高置信度） — 匹配后几乎可以确定是密钥的独特格式：AWS 访问密钥 ID（AKIA...）和带上下文的密钥、Stripe 实时密钥（sk_live_、rk_live_）、GitHub 令牌（ghp_、gho_、github_pat_ 等）、Google API 密钥（AIza...）、Google OAuth 客户端密钥（GOCSPX-...）、Slack 令牌（xox[baprs]-...）、Slack 传入 Webhook URL（hooks.slack.com/services/...）、Shopify 访问令牌（shpat_...、shpca_...、shpss_...、shppa_...、shpua_...）、Telegram 机器人令牌（<bot_id>:A...，35 个字符的密钥）、DigitalOcean 令牌（dop_v1_...、doo_v1_...、dor_v1_...，64 位十六进制）、Hugging Face 令牌（hf_...、api_org_...，34 个字母字符）、Notion API 令牌（ntn_...，11 位数字 + 35 位字母数字字符）、OpenAI 密钥（sk-...、sk-proj-...、sk-svcacct-...）、Anthropic 密钥（sk-ant-...）、npm 访问令牌（npm_...）、SendGrid 密钥（SG....）、Twilio API 密钥（SK...）、Azure Storage 帐户密钥（带上下文的 AccountKey=...）、私钥块（-----BEGIN ... PRIVATE KEY-----）和 JWT。数据库连接字符串中嵌入密码的模式规则（postgres://、mysql://、mongodb(+srv)://、redis(s)://、amqp(s)://）是个例外：即使排除了已知占位密码（user、password、changeit 等）和 ${...} 格式的环境变量引用，也不会将其视为几乎可以确定的密钥，因为真实值仍可能是低风险教程示例，而非有效凭据；这类结果的置信度为通用，与下方的熵规则相同。另一个例外是 Mailchimp API 密钥（32 位十六进制值，后接 -usNN 数据中心后缀），其置信度也为通用：只有值前面紧邻以 mailchimp 开头的变量名或密钥名时才会触发，但这个关键词限制仍无法排除恰好以相同后缀格式结尾的无关十六进制值。Postman API 令牌（PMAK-...，24 位十六进制 + - + 34 位十六进制）、Linear API 密钥（lin_api_...，40 位字母数字字符）、Readme API 密钥（rdme_...，70 位小写字母数字字符）、Clojars API 令牌（CLOJARS_...，不区分大小写，60 位字母数字字符）和 Pulumi API 令牌（pul-...，40 位小写十六进制）均为高置信度——固定前缀和精确长度，与其他服务提供商令牌规则相同。
   • 通用熵规则 — 赋给名为 secret、token、password/credential 的变量，或赋给常用于真实密钥材料的 *key 组合名称（如 apiKey、sessionKey、signingKey、clientKey、webhookKey 等）的值，同时具有较高的 Shannon 熵（看起来随机，而不像占位符或环境变量引用）。特意不匹配单独的 *Key，否则也会匹配 partitionKey、cacheKey、queryKey 等普通代码中常见的非密钥标识符。
3. 返回每个发现项的 filename、line、ruleId、description、confidence（"high" | "generic"）以及已脱敏的代码行——原始密钥值绝不会离开进程。如果未发现任何内容，则返回纯文本结果“No secrets detected.”。

输出示例

使用以下内容调用 scan_for_secrets：

{
  "code": "const key = \"AKIAIOSFODNN7EXAMPLE\";\nconst greeting = \"hello\";",
  "filename": "src/config.ts"
}

返回：

{
  "findings": [
    {
      "filename": "src/config.ts",
      "line": 1,
      "ruleId": "aws-access-key-id",
      "description": "AWS Access Key ID",
      "confidence": "high",
      "redactedLine": "const key = \"AKIA************MPLE\";"
    }
  ],
  "summary": "Found 1 potential secret (1 high-confidence, 0 needs-review).\n\n- [high] src/config.ts:1 — AWS Access Key ID (aws-access-key-id)\n  const key = \"AKIA************MPLE\";"
}

（上面的 AWS 密钥是 AWS 自己的公开文档占位符，并非有效凭据。）如果扫描结果干净，例如 { "code": "const greeting = \"hello world\";" }，则返回 { "findings": [], "summary": "No secrets detected." }。

设置

尚未发布到 npm registry——通过 npx 直接从 GitHub 安装。通过 Git 源运行 npm install 时，会自动运行此软件包的 prepare 脚本，并即时构建 dist/，因此无需单独构建。

Claude Code

将以下内容添加到项目的 .mcp.json（或运行 claude mcp add）：

{
  "mcpServers": {
    "secretguard": {
      "command": "npx",
      "args": ["-y", "github:vladimirbakalov/secretguard-mcp"]
    }
  }
}

Claude Desktop

将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "secretguard": {
      "command": "npx",
      "args": ["-y", "github:vladimirbakalov/secretguard-mcp"]
    }
  }
}

无需 API 密钥、账号或配置选项——重启 Claude Code / Claude Desktop 后，即可使用 scan_for_secrets。工具描述会告知 Agent 在编写可能包含凭据的代码之前，以及提交或创建 PR 之前调用它；大多数时候，你不必明确要求它执行。

Cursor / Windsurf

两者都可以从各自的 MCP 设置界面或配置文件中读取相同格式的 command/args——像这样将它们指向 npx -y github:vladimirbakalov/secretguard-mcp 即可。

此软件包发布到 npm 后，args 可以改为 ["-y", "secretguard-mcp"]——这是后续事项，不会阻碍当前使用。

一键安装（.mcpb）

预构建的 MCP Bundle 附在 v0.1.4-mcpb 发布版本中—— 下载 secretguard-mcp-0.1.4.mcpb 并在 Claude Desktop（或任何其他兼容 MCPB 的客户端）中打开，即可一键本地安装；客户端无需设置 npx/Node。你也可以使用 npm run package:mcpb 自行重新构建（参见 scripts/build-mcpb.sh）。

仓库根目录中的 server.json 指向的正是这个 .mcpb 发布资源，用于官方 MCP Registry——secretguard-mcp 已发布并列为 io.github.vladimirbakalov/secretguard-mcp，因此，除了上述 npx/.mcpb 安装方式外，能够浏览官方 Registry 的 MCP 客户端也可以发现并直接安装它。发布流程会在 CI 中无人值守运行（.github/workflows/publish-mcp.yml），每次推送 v*-mcpb 标签时都会执行 mcp-publisher login github-oidc——无需交互式登录。

安全说明

• 规则匹配到的原始密钥值仅在单次 scan_for_secrets 调用期间保存在内存中，并且会在构建工具结果之前进行脱敏（redactLine/redactSecret）——它绝不会出现在返回的 content、structuredContent 或任何日志行中。
• 服务不会进行任何类型的网络调用。它读取 stdin、写入 stdout（MCP stdio 传输），除此之外不做任何事情。
• 通用级别的检测结果本质上存在歧义（配置占位符、哈希和 UUID 都可能触发熵检查）——这是预期行为。请将 confidence: "generic" 视为“值得再检查一下”，而非“已确认”。

开发

npm install
npm run typecheck   # tsc --noEmit
npm test            # vitest run
npm run build       # tsc -p tsconfig.build.json -> dist/

dist/ 不会提交到仓库——它通过 prepare 脚本从 src/ 构建；该脚本会在基于 Git 的 npx/npm install 安装过程中以及将来每次 npm publish 之前运行。

范围（v1）

一个工具，只做一件事：扫描代码字符串并返回脱敏后的检测结果。不提供允许列表文件、AI 分类步骤、配置选项或持久状态。如果以后确实需要其中任何功能，等实际使用证明有必要后再添加——不会提前添加。

与 secret-scan-action 的关系

secretguard-mcp 与 secret-scan-action 共用同一套检测引擎（rules.ts、redact.ts 以及 scan.ts 的核心部分），但它们是相互独立、分别分发的软件包：一个是用于在 CI 中扫描 PR 差异的 GitHub Action，另一个是用于在提交创建之前于本地扫描任意代码字符串的 MCP 服务。修复规则集中的误报或漏报时，需要同时更新两者。

许可证

MIT。