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 是因为它非常适合这一工作负载：它紧凑、高效，并且非常适合对代码相邻文本进行分类。对于密钥扫描，模型需要在短候选窗口上以高吞吐量和低延迟做出校准决策。

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

我们如何训练

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

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

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

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

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

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

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

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

评估结果

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

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

带走这些

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

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

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

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

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

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

致谢

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

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