GitHub 的密钥检测模型：以更少噪声发现更多密钥

我们的流水线对比先前的 LLM 流水线

更智能的机密扫描，成本仅占一小部分

11.5%

更高的接受率

按所有者加权的警报精确率

86%

更低的扫描执行时间中位数

推送后扫描

98%

更低的服务成本

紧凑模型对比远程 LLM 调用

机密扫描在开发者对检测结果有信心时效果最好。检出过少，真实凭据就可能留在仓库中。警报过于频繁，开发者则可能把时间花在调查并非机密的字符串上。

通用机密使这种平衡尤为困难。同一个字符串既可能是真实凭据，也可能是文档占位符，因此检测它需要理解周围的代码和文本。

为应对这一挑战，我们专门针对 GitHub 的产品需求训练了一个机密分类器：在满足大规模扫描的速度与效率要求的同时，区分真实凭据与形似项。

在我们的配套文章机密保护必须与软件同步扩展中，我们解释了机密保护为何必须跟上 AI 加速的开发。在这里，我们深入介绍为这项工作提供支持的上下文感知分类器的幕后细节：我们如何设计、训练并评估它，从而以更少的噪声发现更多真实机密。

我们实现了什么

GitHub 机密扫描在两个关键时刻运行：

• 推送保护会在推送被接受之前扫描更改，帮助防止机密进入仓库，使开发者有机会处理该发现。
• 推送后扫描在代码提交之后运行，持续扫描仓库内容，并在检测到潜在机密时创建警报，以便开发者和安全团队调查并修复。

我们开发了一个快速分类器，与先前基于 LLM 的流水线相比，将推送后扫描执行时间的中位数降低了 86%。这种效率使得将通用机密检测扩展到推送保护变得切实可行，从而在开发者推送更改之前返回结果，而不仅仅是在代码提交之后。

机密为何难以检测

结构化凭据通常包含独特的前缀、长度、字符集或校验和。通用机密则未必如此。它们的语法与构建标识符、校验和、资源哈希、示例值以及其他非敏感字符串相重叠。上下文才是决定性信号。

这些情况属于困难负样本：字符串符合凭据模式，但并非可用凭据。增加更多规则可以抑制其中一部分，但每一条例外都有隐藏真实机密的风险。学习得到的分类器则可以使用文件路径、机密类型、变量名以及附近代码或文本等信号。

正因如此，我们发布了采用两阶段流水线的新扫描器：

1. 候选生成：正则表达式过滤器以高召回率扫描内容，查找潜在机密。该阶段经过优化，能够快速且确定性地捕获广泛的类凭据模式族。
2. 上下文感知分类：经过微调的 ModernBERT 分类器会评估每个候选项及其周围上下文。它经过训练，能够识别区分真实密钥与误报的信号，包括占位符值、示例、文档片段、生成内容和非敏感标识符。由于该模型小巧，在我们的推理基础设施上运行高效，因此其服务成本远低于基于 LLM 的流水线，扩展也更简单。

影响：

• 用户接受度提升 11.5%，减少误报。
• 推送后密钥检测执行时间加快 86%。
• 与基于 LLM 的流水线相比，成本节省超过 98%。

我们的流水线如何工作

扫描内容时，正则表达式模式会广撒网，标记任何看起来像凭据的内容，以免一开始就漏掉真实密钥。随后，每个候选项都会送入经过微调的 ModernBERT 分类器；分类器会将该值与其文件路径、变量名及周围代码一并读取。分类器会估计它是真实密钥的可能性。高置信度的发现会变成告警，而占位符、测试夹具和校验和等形似项会在送达开发者之前被过滤掉。

我们的流水线如何工作

先广泛，后谨慎

步骤 1

扫描

仓库内容、提交、拉取请求以及其他被扫描的范围。

步骤 2

生成候选项

正则表达式模式会识别可能的令牌、密钥以及类似凭据的字符串。

步骤 3

分类

经过微调的 ModernBERT 会评估候选项 + 上下文，并给出其为真实密钥的可能性。

步骤 4

告警或抑制

高置信度的发现继续推进；可能的误报会被过滤。

重要的设计选择是，模型并不取代确定性扫描，而是对其进行补充。正则表达式仍然是快速查找候选字符串的合适工具。分类器用在机器学习最能发挥杠杆作用的地方：区分“看起来像密钥”与“很可能是真实密钥”。

一个难负样本问题：几乎看起来真实的密钥

大多数误报并非随机产生。它们是难负样本：匹配凭据模式但并非可用凭据的字符串。例子包括文档占位符、测试中的玩具示例、已脱敏的值、非敏感 ID 以及生成的夹具。这些情况很容易被正则表达式匹配到，但对于纯粹基于规则的系统而言，很难在不意外丢失真实密钥的情况下将其抑制。

ModernBERT 之所以有帮助，是因为它可以将候选项与附近的代码和文本一起读取，提供与 LLM 相当的上下文理解，同时没有生成自然语言输出所带来的延迟和计算开销。例如，周围出现“example”、“dummy”、“fake”或“replace-me”等词语的候选项，其风险可能低于在部署文件中被赋值给环境变量的候选项。分类器从带标签的示例中学习这些上下文差异，而无需工程师将每个例外都编码成另一条规则。

我们选择 ModernBERT，是因为它非常契合这项工作负载：它紧凑、高效，并且很适合对代码邻近文本进行分类。对于密钥扫描而言，模型需要在较短的候选窗口上做出经过校准的决策，同时具备高吞吐量和低延迟。

这使得经过微调的编码器分类器在流水线的这一阶段比通用 LLM 更适合作为服务形态。该模型可以直接针对我们的决策边界进行训练，并使用对密钥扫描质量至关重要的相同召回率和精确率指标进行评估。

我们如何训练

难点在于为仅凭语法就会产生误导的情况找到有代表性的数据。训练与评估策略结合了三个来源： 

• 来自 GitHub 仓库的产品衍生示例，利用密钥检测体验的反馈以及额外的人工验证。
• 来自 GitHub 仓库数据的高召回率正则表达式候选，包括人工标注示例以及用于扩大覆盖范围的弱标签。
• 针对稀疏和困难情况的合成示例，例如文档中的密钥、测试夹具、公钥、校验和、结构化相似项以及近似配对。

合成数据行在纳入之前会通过确定性验证和基于模型的质量审查。训练重点关注真实密钥、现实中的误报，以及经常让仅依赖正则表达式的方法产生混淆的困难负例。 每个模型输入都包含候选值、文件路径、密钥类型以及有限数量的周围上下文。我们通过离线评估选择阈值，然后在更广泛推出之前，在类似生产环境的流量上验证其行为。

在拆分数据之前，我们将共享同一仓库、候选值或示例的行分组，以免近似重复项同时出现在训练集和评估集中。

训练聚焦于对告警质量最为重要的情况：真实密钥、现实中的误报，以及正则表达式经常匹配到的困难负例。输入表示包括候选密钥字符串、文件路径、类型以及有限数量的周围上下文。输出是一个分类分数，扫描器据此决定该候选是否应继续处理。

我们针对产品层面的权衡进行了优化：在降低误报和服务成本的同时保持或提高召回率。在实践中，这意味着分类器阈值通过离线评估选定，然后在推出之前对照类似生产环境的流量进行验证。

最重要的训练原则是让模型看到那些容易混淆的示例。我们纳入了在语法上与真实密钥相似但语义不同的候选，使模型不仅学会密钥长什么样，也学会误报在上下文中长什么样。

训练好的模型以 8-bit 量化导出为 ONNX 格式，从而实现快速推理。

评估结果

我们分两个阶段评估了新流水线在生产环境中的影响：首先在相同的公开流量上对照生产基线，然后通过客户 A/B 实验。 

• 离线评估：在推送后扫描中，新流水线在相同的公开流量上评估时，比先前的 LLM 流水线实现了高出 13% 的精确率和高出 19% 的召回率。 
• 在线评估：随后，我们通过与先前 LLM 流水线的 A/B 实验，验证这些质量改进是否转化为客户成果。按仓库所有者加权的接受率提高了 11.5%。我们按仓库所有者对接受率加权，以降低一次性批量处理大量警报的客户所带来的影响，否则这类行为可能会扭曲简单平均值。 

请带走这些要点

最好的安全工具，是开发者足够信任并愿意使用的那一个。更高的精确率意味着更少的干扰性警报。更高的召回率意味着能捕获更多真实密钥。更低的成本意味着我们可以持续改进覆盖范围，而不会让扫描变得过于昂贵。

对开发者和安全团队而言，这应转化为更少的误报，以及在密钥最可能被引入的地方获得更快的反馈：提交、拉取请求和日常开发工作流。

混合系统很强大。正则表达式为我们提供速度、透明度和广泛的候选覆盖。ModernBERT 为我们提供习得的上下文理解以及误报减少。在这一产品约束下，二者结合的表现优于单独使用任一方法。

我们还认识到，模型规模并不等同于模型实用性。当任务范围较窄、决策边界可衡量且服务效率至关重要时，更小的微调分类器可能才是正确选择。

这是让密钥扫描更准确、更具可扩展性且更易用的一步。展望未来，我们聚焦于两个方面：

• 构建持续改进飞轮。我们将利用生产反馈循环来识别新的假阴性和假阳性，把真实世界的信号转化为更高质量的训练与评估数据。
• 探索新的模型架构。我们正在研究能够在单一步骤中完成密钥检测与提取的方法，在保持准确性和规模的同时降低流水线复杂度。

致谢

衷心感谢 GitHub 和 Microsoft 的工程、科学与产品团队，他们帮助构建了这一新密钥扫描器的训练数据、评估套件、服务栈和发布计划。

文章 GitHub 的密钥检测模型：以更少的噪声发现更多密钥 最初发布于 The GitHub Blog。