secret-scanning

密钥扫描

本技能为配置 GitHub 密钥扫描提供流程指导——检测泄露的凭据、阻止密钥推送、定义自定义模式以及管理告警。

何时使用本技能

当请求涉及以下内容时，请使用本技能：

• 为仓库或组织启用或配置密钥扫描
• 设置推送保护，在密钥进入仓库之前将其阻止
• 使用正则表达式定义自定义密钥模式
• 从命令行解决被阻止的推送
• 对密钥扫描告警进行分诊、忽略或修复
• 为推送保护配置委托绕过
• 通过 secret_scanning.yml 将目录从密钥扫描中排除
• 了解告警类型（用户、合作伙伴、推送保护）
• 启用有效性检查或扩展元数据检查
• 在提交前扫描本地代码更改中的密钥（通过 MCP / AI 编码 Agent）——有关推荐的插件，请参阅下方的 通过 AI 编码 Agent 进行提交前扫描 部分

密钥扫描的工作原理

密钥扫描会自动检测以下位置中暴露的凭据：

• 所有分支上的完整 Git 历史记录
• Issue 的描述、评论和标题（开放和已关闭）
• Pull Request 的标题、描述和评论
• GitHub Discussions 的标题、描述和评论
• Wiki 和私密 gist

可用性

仓库类型	可用性
公开仓库	自动启用，免费
私有/内部（组织拥有）	需要在 Team/Enterprise Cloud 上启用 GitHub Secret Protection
用户拥有	使用 Enterprise Managed Users 的 Enterprise Cloud

核心工作流——启用密钥扫描

第 1 步：启用 Secret Protection

1. 导航到仓库 Settings → Advanced Security
2. 点击 "Secret Protection" 旁边的 Enable
3. 点击 Enable Secret Protection 进行确认

对于组织，可使用安全配置大规模启用：

• Settings → Advanced Security → Global settings → Security configurations

第 2 步：启用推送保护

推送保护会在推送过程中阻止密钥——在它们进入仓库之前。

1. 导航到仓库 Settings → Advanced Security
2. 在 Secret Protection 下启用 "Push protection"

推送保护会在以下场景中阻止密钥：

• 命令行推送
• GitHub UI 提交
• 文件上传
• REST API 请求
• REST API 内容创建端点

第 3 步：配置排除项（可选）

创建 .github/secret_scanning.yml 以自动关闭特定目录的告警：

paths-ignore:
  - "docs/**"
  - "test/fixtures/**"
  - "**/*.example"

限制：

• paths-ignore 中最多 1,000 个条目
• 文件必须小于 1 MB
• 被排除的路径也会跳过推送保护检查

最佳实践：

• 排除路径尽可能具体
• 添加注释说明每个路径被排除的原因
• 定期审查排除项——移除过时条目
• 将排除项告知安全团队

第 4 步：启用附加功能（可选）

非提供商模式——检测私钥、连接字符串、通用 API 密钥：

• Settings → Advanced Security → 启用 "Scan for non-provider patterns"

AI 驱动的通用密钥检测——使用 Copilot 检测密码等非结构化密钥：

• Settings → Advanced Security → 启用 "Use AI detection"

有效性检查——验证检测到的密钥是否仍然有效：

• Settings → Advanced Security → 启用 "Validity checks"
• GitHub 会定期针对提供商 API 测试检测到的凭据
• 状态显示在告警中：active、inactive 或 unknown

扩展元数据检查——有关密钥归属者的额外上下文：

• 需要先启用有效性检查
• 有助于确定修复优先级并识别责任团队

核心工作流——解决被阻止的推送

当推送保护从命令行阻止推送时：

选项 A：移除密钥

如果密钥在最新提交中：

# Remove the secret from the file
# Then amend the commit
git commit --amend --all
git push

如果密钥在更早的提交中：

# Find the earliest commit containing the secret
git log

# Start interactive rebase before that commit
git rebase -i <COMMIT-ID>~1

# Change 'pick' to 'edit' for the offending commit
# Remove the secret, then:
git add .
git commit --amend
git rebase --continue
git push

方案 B：绕过推送保护

1. 以同一用户身份访问推送错误消息中返回的 URL
2. 选择绕过原因：
   • 用于测试 — 创建警报并自动关闭
   • 误报 — 创建警报并自动关闭
   • 稍后修复 — 创建未关闭的警报
3. 点击 Allow me to push this secret
4. 在 3 小时内重新推送

方案 C：申请绕过权限

如果启用了委派绕过而你缺少绕过权限：

1. 访问推送错误中的 URL
2. 添加评论说明该密钥为何安全
3. 点击 Submit request
4. 等待批准/拒绝的邮件通知
5. 如获批准，推送该提交；如被拒绝，移除该密钥

有关绕过和委派绕过工作流的详细信息，请搜索 references/push-protection.md。

自定义模式

使用正则表达式定义组织专属的密钥模式。

快速设置

1. Settings → Advanced Security → Custom patterns → New pattern
2. 输入模式名称和密钥格式的正则表达式
3. 添加示例测试字符串
4. 点击 Save and dry run 进行测试（最多 1,000 条结果）
5. 检查结果中的误报
6. 点击 Publish pattern
7. 可选：为该模式启用推送保护

作用范围

自定义模式可定义于：

• 仓库级别 — 仅适用于该仓库
• 组织级别 — 适用于所有启用了密钥扫描的仓库
• 企业级别 — 适用于所有组织

Copilot 辅助生成模式

使用 Copilot 密钥扫描，根据密钥类型的文本描述生成正则表达式，可附带示例字符串。

有关自定义模式配置的详细信息，请搜索 references/custom-patterns.md。

警报管理

警报类型

类型	描述	可见性
用户警报	在仓库中发现的密钥	Security 选项卡
推送保护警报	通过绕过方式推送的密钥	Security 选项卡（筛选：bypassed: true）
合作伙伴警报	报告给提供商的密钥	不在仓库中显示（仅提供商可见）

警报列表

• 默认警报 — 受支持的提供商模式和自定义模式
• 通用警报 — 非提供商模式和 AI 检测到的密钥（每个仓库最多 5,000 条）

修复优先级

1. 立即轮换凭据 — 这是关键操作
2. 查看警报以了解上下文（位置、提交、作者）
3. 检查有效性状态：active（紧急）、inactive（较低优先级）、unknown
4. 如有需要，从 Git 历史中移除（耗时较长，轮换后通常不必要）

关闭警报

以记录在案的原因关闭：

• 误报 — 检测到的字符串并非真实密钥
• 已吊销 — 凭据已被吊销
• 用于测试 — 密钥仅存在于测试代码中

有关警报类型、有效性检查和 REST API 的详细信息，请搜索 references/alerts-and-remediation.md。

通过 AI 编码 Agent 进行提交前扫描

如需在提交前通过 AI 编码 Agent 扫描代码变更中的密钥，请安装 Advanced Security 插件，它提供 run_secret_scanning MCP 工具和专用的扫描技能。

GitHub Copilot CLI：

/plugin install advanced-security@copilot-plugins

Visual Studio Code：

• 在 Copilot Chat 中，打开 Chat: Plugins（或使用 @agentPlugins）并安装 advanced-security 插件
• 然后在 Copilot Chat 中运行 /secret-scanning

参见：Advanced Security Plugin — Secret Scanning Skill

发布于 Secret scanning in AI coding agents via the GitHub MCP Server（2026 年 3 月）

参考文件

如需详细文档，请按需加载以下参考文件：

• references/push-protection.md — 推送保护机制、绕过工作流、委派绕过、用户推送保护
  • 搜索模式：bypass、delegated、bypass request、command line、REST API、user push protection
• references/custom-patterns.md — 自定义模式创建、正则表达式语法、试运行、Copilot 正则表达式生成、作用域
  • 搜索模式：custom pattern、regex、dry run、publish、organization、enterprise、Copilot
• references/alerts-and-remediation.md — 警报类型、有效性检查、扩展元数据、通用警报、密钥移除、REST API
  • 搜索模式：user alert、partner alert、validity、metadata、generic、remediation、git history、REST API