secret-scanning

密钥扫描技能

概述

此技能使用 GitHub MCP Server 的 run_secret_scanning 工具，检测内容、文件或 git 更改中的密钥。它有助于识别 API 密钥、密码和凭据等敏感材料，这些内容一旦泄露可能带来安全风险。

什么算作密钥？

在此上下文中，通常将可用于获取访问权限、冒充用户或服务、签署请求或解密受保护数据的值视为密钥。

以下内容属于可信度较高的密钥材料：

• 访问令牌、API 密钥和承载凭据
• 密码、包含内嵌凭据的数据库 DSN，以及 SMTP 身份验证值
• 私钥、签名密钥、包含私钥块的证书，以及 SSH 密钥
• OAuth 客户端密钥、刷新令牌和 Webhook 密钥
• 云凭据（AWS/GCP/Azure）和 CI/CD 部署凭据

判断时应优先考虑上下文，而不只是使用正则表达式：

• password、token、secret、client_secret、private_key 或 authorization 等名称附近的值风险更高
• 配置文件、脚本和测试夹具中的高熵长字符串，即使没有标签，也值得检查
• 对无法确定的发现项，在核实前应视为敏感内容

看起来随机的内容不一定都是密钥。例如，YOUR_API_KEY_HERE 这类占位符、明显的测试样例和文档中的示例值都可能是误报。

为什么这很重要

此技能会扫描可能在泄露后危及安全的密钥。已提交的密钥可能会留存在 git 历史记录中、触发事件响应，并在推送保护检查中阻止部署。

重要提示：仅在用户明确要求扫描内容或检查密钥时使用此技能。不要在未收到提示时运行密钥扫描，也不要将其作为常规工作流的一部分。

常见场景

用户目标	响应方式	所需工具
检查配置片段或粘贴的代码	作为内容扫描	MCP
检查仓库中的特定文件	读取文件，然后扫描	Read + MCP
提交前检查所有暂存更改	获取差异，然后扫描	Bash(git:*) + MCP

安装

前置条件和输入

GitHub MCP Server：此技能需要启用 secret_protection 工具集的 GitHub MCP Server。此仓库包含一个默认的 .mcp.json，已配置为使用 GitHub MCP Server，因此此技能开箱即用即可与其通信。

在 MCP 设置中进行配置：

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}

注意： Cursor 使用 servers 而不是 mcpServers 作为顶层键。

扫描所需信息：

• 仓库所有者：通常可通过 git remote get-url origin 获取，也可以询问用户
• 仓库名称：通常可通过 git remote get-url origin 获取，也可以询问用户
• 要扫描的内容：用户提供的代码片段、文件内容（使用 Read 工具读取）或 git diff 输出（来自 git diff）

如果用户未提供仓库所有者和仓库名称，请先询问，再运行扫描。

不应扫描的内容：默认情况下，避免扫描大型生成内容或供应商内容（例如：node_modules/、构建产物、编译后的资源或其他机器生成的文件），以提升性能并减少噪声。.gitignore 中列出的文件仍可能包含密钥（例如 .env 或本地配置），因此只有在用户同意时才跳过；如果用户明确要求扫描这些文件，则应将其纳入扫描范围。

扫描内容

适用情况：用户提供了希望检查是否包含密钥的文本或代码片段。

操作方法：使用 run_secret_scanning 工具，将内容作为输入（单项数组）传入。

示例

You: Check if this config snippet has secrets
User provides:
DB_PASSWORD=MyP@ssw0rd123
API_KEY=abc123xyz

Agent: I'll scan that for secrets.

     ⚠️ Found 2 potential secret(s):
     1. DB_PASSWORD value looks like a password
     2. API_KEY value looks like an API key

     Consider replacing hardcoded values with environment variables.

扫描文件

适用场景：用户要求检查仓库中的特定文件是否包含密钥。

方法：使用 Read 工具获取文件内容，然后将其传递给 run_secret_scanning。

示例（发现密钥）

You: Check if config.py has secrets
Agent: I'll read and scan that file.

     ⚠️ Found 1 potential secret:
     - Line 10: database_password value looks like a password

     Suggestion: Move to environment variable or .env file.

示例（未发现密钥）

You: Check if utils.js has any secrets
Agent: I'll read and scan that file.

     ✅ No secrets detected in utils.js

扫描暂存的更改

适用场景：用户希望在提交前检查 Git 暂存的更改是否包含密钥。

方法：使用 git diff --cached 获取暂存的内容，然后将其传递给 run_secret_scanning。

示例（未发现问题）

You: Check my staged changes for secrets before I commit
Agent: I'll scan your staged changes.

     ✅ No secrets found in staged changes. Safe to commit.

示例（检测到密钥）

You: Scan my staged changes
Agent: I'll check your staged changes.

     ⚠️ Found 1 potential secret in staged changes:
     - database.js line 5: password value looks like a credential

     Suggestion: Unstage that change, move the credential to env vars, and restage.

扫描工作原理

调用 run_secret_scanning 时：

• 输入：要扫描的文件内容（以字符串数组形式传递），以及仓库所有者和名称
• 处理：GitHub 的密钥检测会扫描与已知密钥类型相匹配的模式和上下文
• 输出：发现的潜在密钥列表，包含位置和置信度指标

该工具会处理你提供的内容。它不需要推送权限或特殊的 GitHub 权限。

扫描透明度

内容的处理方式

请求扫描时，文件内容会发送到 GitHub 的密钥检测基础设施。扫描会在服务端针对 GitHub 已知的密钥模式进行。扫描结果返回后，GitHub 服务器不会在扫描请求之外保留这些内容。

如何处理结果

如果发现密钥：

• 明显的硬编码值：将其移至环境变量或 .env 文件
• 配置文件：检查是否存在 example.env 或相关文档，以了解预期结构
• 已提交的密钥：如果密钥已经推送，可能需要轮换凭据（不在此技能的范围内）

如果未发现密钥：

• 扫描已成功完成
• 检查扫描结果中的输出格式，确保覆盖范围完整

了解更多

有关密钥扫描、凭据管理和 GitHub 安全功能的更多详情：

• GitHub 密钥扫描文档：如何在仓库中启用和使用密钥扫描
• 凭据管理最佳实践：安全处理凭据的指南
• GitHub 推送保护：防止密钥进入仓库