密钥扫描

此技能提供了配置 GitHub 密钥扫描的程序性指导——检测泄露的凭证、阻止密钥推送、定义自定义模式以及管理警报。

何时使用此技能

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

• 为仓库或组织启用或配置密钥扫描
• 设置推送保护以在密钥到达仓库之前阻止它们
• 使用正则表达式定义自定义密钥模式
• 解决命令行中阻止的推送
• 分类、关闭或修复密钥扫描警报
• 为推送保护配置委托绕过
• 通过 secret_scanning.yml 从密钥扫描中排除目录
• 了解警报类型（用户、合作伙伴、推送保护）
• 启用有效性检查或扩展元数据检查

密钥扫描的工作原理

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

• 所有分支上的整个 Git 历史记录
• 议题描述、评论和标题（包括已关闭的议题）
• 拉取请求标题、描述和评论
• GitHub Discussions 的标题、描述和评论
• 维基和秘密 Gist

可用性

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

步骤 1：启用密钥保护

1. 导航到仓库 设置 → 高级安全
2. 点击“Secret Protection”旁边的 启用
3. 点击 启用 Secret Protection 确认

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

• 设置 → 高级安全 → 全局设置 → 安全配置

步骤 2：启用推送保护

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

1. 导航到仓库 设置 → 高级安全
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 密钥：

• 设置 → 高级安全 → 启用“Scan for non-provider patterns”

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

• 设置 → 高级安全 → 启用“Use AI detection”

有效性检查 — 验证检测到的密钥是否仍处于活动状态：

• 设置 → 高级安全 → 启用“Validity checks”
• GitHub 会定期针对提供商 API 测试检测到的凭证
• 警报中显示的状态：active、inactive 或 unknown

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

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

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

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

选项 A：移除密钥

如果密钥在最新提交中：

# 从文件中移除密钥
# 然后修改提交
git commit --amend --all
git push

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

# 找到包含密钥的最早提交
git log

# 在该提交之前开始交互式变基
git rebase -i <COMMIT-ID>~1

# 将有问题的提交从 'pick' 改为 'edit'
# 移除密钥，然后：
git add .
git commit --amend
git rebase --continue
git push

选项 B：绕过推送保护

1. 访问推送错误消息中返回的 URL（使用同一用户）
2. 选择绕过原因：
   • 用于测试 — 创建警报并自动关闭
   • 误报 — 创建警报并自动关闭
   • 稍后修复 — 创建开放警报
3. 点击 允许我推送此密钥
4. 在 3 小时内重新推送

选项 C：请求绕过权限

如果启用了委托绕过且您没有绕过权限：

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

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

自定义模式

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

快速设置

1. 设置 → 高级安全 → 自定义模式 → 新建模式
2. 输入模式名称和密钥格式的正则表达式
3. 添加一个示例测试字符串
4. 点击 保存并试运行 进行测试（最多 1,000 个结果）
5. 审查结果以检查误报
6. 点击 发布模式
7. 可选择为该模式启用推送保护

作用域

自定义模式可以在以下级别定义：

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

Copilot 辅助模式生成

使用 Copilot 密钥扫描，通过密钥类型的文本描述（包括可选的示例字符串）生成正则表达式。

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

警报管理

警报类型

警报列表

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

修复优先级

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

关闭警报

使用记录的原因关闭警报：

• 误报 — 检测到的字符串不是真正的密钥
• 已撤销 — 凭证已被撤销
• 用于测试 — 密钥仅在测试代码中

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

参考文件

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

• 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