修复仓库中泄露的密钥

简介

机密（如 API 密钥、令牌和凭证）如果在代码库中意外泄露或存储不当，可能对您的团队和组织构成重大安全风险。

您应视任何泄露的机密为已被立即泄露，必须采取适当的修复步骤，例如撤销机密。仅仅从代码库中删除机密、推送新提交，或删除并重新创建仓库，都不足以防止机密被利用。

本教程将指导您在意外将机密提交到仓库，或收到仓库机密泄露警报时该如何处理。

先决条件

• 您至少拥有该仓库的写权限。
• 可选：已为仓库启用机密扫描。

  注意

  机密扫描对公共仓库是免费的。对私有仓库，作为GitHub 机密保护的一部分，在 GitHub Team 与 GitHub Enterprise Cloud 计划中提供。

步骤 1. 确认机密并收集上下文

尽可能多地收集关于泄露机密的信息。这将帮助您评估风险并确定最佳的修复措施。

1. 确定机密的类型及其提供方。
   • 例如，该机密是 GitHub 个人访问令牌（PAT）、OpenAI API 密钥，还是 SSH 私钥？
2. 定位包含泄露机密的仓库、文件及行号。
3. 确认机密所有者。即该机密的创建者或负责团队。
   • 检查仓库中的 CODEOWNERS 文件，以确定负责的团队。
   • 使用 git log -S 搜索仓库的提交历史，找出是谁提交了该机密。

步骤 2. 评估风险

您采取的修复方法将取决于该机密泄露所涉及的风险因素。

机密扫描可以帮助评估警报的风险，但即使尚未启用机密扫描，您仍可依据现有信息进行风险评估。

选项 1. 已启用机密扫描

审查与泄露相关的机密扫描警报，查看警报标签及任何可用的元数据。

1. 检查机密的有效性状态，以判断机密是否仍然可用。警报会显示机密是“活动的”“非活动的”还是“未知”。

   注意

   • 有效性检查仅适用于某些机密类型。要了解您的机密类型是否受支持，请参阅受支持的机密扫描模式。
   • 机密提供方始终是判断机密是否有效的最可靠依据。
2. 检查public exposure标签，以判断机密是否泄露在公共仓库中。
3. 检查multiple leaks标签，以判断机密是否在多个位置出现。
4. 如果机密是 GitHub PAT，请查看警报元数据，获取最近一次使用时间和访问范围等信息。
5. 评估哪些服务或应用依赖该机密，并考虑若立即撤销机密可能导致的停机或中断风险。

选项 2. 未启用机密扫描

如果尚未为仓库启用机密扫描，请依据下列因素进行风险评估：

1. 检查仓库的可见性。该仓库是公共的还是私有的？
2. 寻找机密近期是否被使用的迹象。最近的提交或 PR 是否引用了该机密？是否有日志或审计轨迹显示机密被使用？
3. 评估包含机密的文件及其周边上下文。机密是用于生产部署脚本（风险较高）还是测试文件（风险较低）？机密是数据库凭证还是管理员密钥（风险较高）？
4. 评估哪些服务或应用依赖该机密，并考虑若立即撤销机密可能导致的停机或中断风险。

步骤 3. 制定修复策略

下一步取决于您在上一步进行的风险评估结果。

对高风险机密要快速行动

自动化扫描器可以在几分钟内定位公开泄露的机密。恶意行为者可能在数小时内利用它们。机密暴露时间越长，导致严重泄露的可能性越大。

如果该机密属于高风险（即仍然活动、泄露在公共仓库或为生产凭证），我们建议您：

1. 优先立即撤销机密。参见步骤 4。

   注意

   如果担心服务停机，可先生成具有相同权限的新机密，让应用切换使用新令牌，然后撤销旧机密。

2. 在撤销期间或之后，及时与机密所有者（步骤 1 中已识别）、仓库管理员及安全负责人沟通。

对中低风险机密制定计划

如果该机密属于中低风险（即已不再活动、泄露在私有仓库，或为测试/开发凭证），可以相应制定修复方案：

1. 利用步骤 1 收集的信息，定位机密的负责团队并告知其泄露情况。
2. 说明泄露了什么、何时泄露。告知需要撤销机密、生成新机密以及受影响的服务需要更新。
3. 通知仓库管理员和安全负责人泄露情况，说明已采取或需采取的修复措施。
4. 与相关团队一起安排撤销和轮换的时间，以协调平稳过渡。

即使是中低风险机密，也必须修复，因为若仍然暴露会对安全和合规产生风险。

步骤 4. 撤销机密

仅仅从代码库中删除机密不足以解决问题。最关键的修复步骤是向机密的提供方撤销该机密。撤销后，可显著降低机密被利用的可能性。

1. 使用步骤 1 收集的信息，定位机密提供方的官网或文档。

2. 按照提供方的指引撤销机密。通常需要登录提供方的门户，进入机密管理页面进行操作。

   如果您无法访问提供方门户，请联系机密所有者或相应的仓库管理员，获取撤销帮助。

3. 如有必要，生成新机密以替代已撤销的机密，这通常是恢复依赖该机密的服务功能所必需的。

步骤 5: 确认并更新受影响的服务

接下来，需要协调更新所有使用泄露机密的受影响服务，并使用新机密替换。

确认

1. 使用 GitHub 代码搜索检查所有代码、议题和 Pull Request 中是否出现该机密。
   • 在组织范围内搜索，例如 org:YOUR-ORG "SECRET-STRING"。
   • 在单个仓库内搜索，例如 repo:YOUR-REPO "SECRET-STRING"。
2. 检查仓库存储的部署密钥、机密和变量。
   • 点击“Settings”，在“Security”下点击Secrets and variables或Deploy keys。
3. 检查是否有已安装的 GitHub Apps 或集成可能使用该机密。

协调

1. 指示 Copilot 为更新受影响服务的每项任务创建 Issue（及子 Issue）。参见使用 GitHub Copilot 创建或更新 Issue。
2. 若涉及多个利益相关者，可创建项目看板来跟踪 Issue 进度并促进沟通。

更新并验证

1. 使用新机密更新您的应用，确保应用正确使用新的凭证。

   提示

   向应用提供敏感凭证的安全方式是通过金库。例如，您可以在仓库设置页面的“Secrets and variables”存储中向 GitHub Actions 与工作流提供敏感凭证。

2. 测试受影响的服务，确保在使用新机密后能够正常运行。

步骤 6. 检查是否有未授权访问

服务恢复后，需要检查在机密暴露期间是否发生了未授权访问。

1. 审查 GitHub 的审计日志，查看与该机密及其使用相关的事件。

   • 个人账户的安全日志。参见审阅您的安全日志。
   • 组织的审计日志。参见审阅组织的审计日志。
   • 企业的审计日志。参见企业审计日志事件。

   对于组织和企业级审计日志，您可以专门搜索与访问令牌相关的事件。参见识别由访问令牌执行的审计日志事件（组织）和识别由访问令牌执行的审计日志事件（企业）。

   访问 GitHub 审计日志取决于您的角色，如果您没有相应权限，可能需要联系组织所有者或企业管理员。

2. 审查机密提供方的审计日志。

   • 例如，对于 Amazon Web Services（AWS）机密，您可以查看 CloudTrail 日志，寻找使用泄露机密的未授权访问尝试。参见What Is AWS CloudTrail?（AWS CloudTrail 文档）。

步骤 7. 清理仓库

虽然您已经撤销并在代码库中更新了机密，但该机密可能仍然存在于提交历史中。理想情况下，您应在仓库中搜索并删除所有机密实例。

然而，清理 Git 历史是一项具有破坏性且可能导致中断的操作，因为它可能需要强制推送更改。

请与仓库的安全负责人一起，仔细权衡清理历史对合规或安全义务的影响。参见从仓库中移除敏感数据。

步骤 8. 解决警报

1. 在仓库中关闭机密扫描警报，选择Close as并将警报标记为“已撤销”。
2. 在团队的知识库或事故管理系统中记录该事件，包含已采取的修复步骤以及所汲取的经验教训。

步骤 9. 防止进一步泄露

机密泄露的处理往往会带来干扰、复杂性和耗时。机密处理的核心始终应是不惜代价防止泄露。

1. 确保已为仓库启用推送保护（GitHub 机密保护的一部分），如果尚未启用，请尽快开启。考虑实施严格的绕过控制，仅允许受信任用户绕过推送保护。参见关于推送保护。
2. 在个人账户上启用“Push protection for users”，该功能可防止您不小心将受支持的机密推送到任何公共仓库。
3. 在团队或组织内部倡导或实施机密管理最佳实践。
   • 使用环境变量存储机密，而非在代码库中硬编码。
   • 使用机密管理工具，例如仓库设置页面下的 GitHub “Secrets and variables” 存储，以安全地存储和管理机密。
   • 定期轮换机密，以降低潜在泄露的影响。
4. 记录事件和修复步骤，帮助团队从过去的错误中学习并改进未来的实践。
5. 倡导并开展定期的学习与安全培训。例如，可参考GitHub Advanced Security（Microsoft Learn）课程。

延伸阅读

• 关于机密扫描
• 关于推送保护
• 支持的秘密扫描模式
• 关于 GitHub 高级安全