GitHub 如何用 ModernBERT 分类器减少密钥扫描误报

我们的流水线与之前的 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 是更好的服务形态。模型可以直接在我们的决策边界上训练，并使用对 secret scanning 质量至关重要的相同召回率和精确率指标进行评估。

我们如何训练

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

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

合成行在纳入前需通过确定性验证和基于模型的质量审查。训练侧重于真实 secret、现实中的误报，以及经常让仅靠正则的方法混淆的困难负样本。每个模型输入包括候选值、文件路径、secret 类型以及有限数量的上下文。我们通过离线评估选择阈值，然后在更广泛推广之前在生产类似流量上验证行为。

在拆分数据之前，我们按共享仓库、候选值或示例对行进行分组，这样近重复项就不会同时出现在训练和评估中。

训练聚焦于对告警质量最重要的案例：真实 secret、现实中的误报，以及正则经常匹配到的困难负样本。输入表示包括候选 secret 字符串、文件路径、类型以及有限数量的上下文。输出是分类分数，扫描器用它来决定候选是否应继续处理。

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

最重要的训练原则是让模型看到令人困惑的示例。我们纳入了语法上与真实 secret 相似但语义不同的候选，这样模型不仅学习 secret 长什么样，还学习误报在上下文中长什么样。

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

评估结果

我们分两个阶段评估了新流水线在生产中的影响：首先在同一公共流量上与生产基线对比，然后通过客户 A/B 实验进行验证。 

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

带走这些要点

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

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

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

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

这是让密钥扫描更准确、更可扩展、更易使用的一步。展望未来，我们专注于两个领域：

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

致谢

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

文章 GitHub 的密钥检测模型：以更少噪声发现更多密钥 首次发表于 The GitHub Blog。