摘要

GitHub 披露其密钥扫描背后的上下文感知分类器。官方称，新方案采用两阶段流水线：先由正则过滤器高召回地扫描出潜在密钥候选，再由微调后的 ModernBERT 分类器结合文件路径、变量名、周边代码等上下文判断其是否为真密钥。官方口径的三项提升为：owner 加权告警接受率提升 11.5%（误报减少）、post-push 扫描中位执行时间降低 86%、相较原 LLM 方案成本节省超过 98%。效率提升使通用密钥检测得以扩展到推送前拦截（push protection），而非仅在提交后告警。模型导出为 ONNX 格式并做 8 位量化以加速推理；训练数据结合产品派生样本、高召回正则候选（含人工标注与弱标签）与针对稀疏困难场景的合成样本，并在切分前按仓库、候选值或样例分组，避免近重复同时出现在训练集与评估集。官方强调，模型不替代确定性扫描，而是对其加以补充。

正文（译文）

当开发者对扫描结果有信心时，密钥扫描才能发挥最大价值。抓得太少，真实的凭据可能就留在了仓库里；告警太频繁，开发者又可能把时间花在调查那些根本不是密钥的字符串上。

通用密钥让这种平衡尤其困难。同一个字符串可能是真实凭据，也可能只是文档里的占位符，因此要判断它就需要理解周围的代码和文本。

为应对这一挑战，我们专门为 GitHub 的产品需求训练了一个密钥分类器：在区分真实凭据与「看起来像」的字符串的同时，满足大规模扫描对速度和效率的要求。

密钥保护必须与软件一同扩展

我们此前曾解释过为什么密钥保护必须跟上 AI 加速开发的步伐。在本文中，我们将深入幕后，介绍支撑这项工作的上下文感知分类器：我们如何设计、训练和评估它，从而以更少的噪声找到更多真实密钥。

GitHub 密钥扫描在两个关键时点运作：

推送保护（push protection）通过在推送被接受之前扫描变更，帮助阻止密钥进入仓库，给开发者处理该发现的机会。 提交后扫描（post-push scanning）在代码提交之后持续扫描仓库内容，并在检测到潜在密钥时创建告警，供开发者和安全团队调查与修复。

我们开发了一个快速分类器，相较此前基于 LLM 的流水线，把 post-push 扫描的中位执行时间降低了 86%。这一效率提升让通用密钥检测得以扩展到推送保护——在开发者推送变更之前就返回结果，而不仅仅是在代码提交之后。

为什么密钥难以检测

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

生产数据库 URL 旁赋值的一个密码 测试 fixture 中同样形状的一个密码值 部署配置中的一个连接字符串 安装指南中的一个 localhost 连接字符串 绑定到 API 凭据的一个高熵值 一个高熵的校验和、构建 ID 或资源哈希

这些都属于「难负例」（hard negatives）：匹配凭据模式但并非可用凭据的字符串。增加更多规则可以抑制其中一部分，但每一条例外都有隐藏真实密钥的风险。而一个学习出来的分类器，则可以改用文件路径、密钥类型、变量名以及邻近代码或文本等信号。

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

生成候选（Generate candidates）：正则过滤器以高召回率扫描内容中的潜在密钥。这一阶段针对快速、确定性地捕捉大类「类凭据」模式而优化。 分类（Classify）：一个微调后的 ModernBERT 分类器评估每个候选及其周围上下文。它被训练用于识别区分真实密钥与误报的信号，包括占位符值、示例、文档片段、生成内容和非敏感标识符。由于该模型体积小、在我们的推理基础设施上运行高效，它的服务成本远低于基于 LLM 的流水线，也更易于扩展。

11.5% 的用户接受率提升，减少误报。 86% 更快的提交后密钥检测执行时间。 相较 LLM 流水线超过 98% 的成本节省。

在内容被扫描时，正则模式先广撒网，标记任何看起来像凭据的东西，确保真实密钥从一开始就不会被漏掉。随后，每个候选被送进微调后的 ModernBERT 分类器，它会把该值与文件路径、变量名和周边代码一起阅读。分类器估计它是真实密钥的可能性。高置信度的发现成为告警，而占位符、测试 fixture、校验和这类「看起来像」的字符串则在触达开发者之前被过滤掉。

先广后精

仓库内容、提交、拉取请求以及其他被扫描面。 正则模式识别可能的 token、密钥和类凭据字符串。 微调后的 ModernBERT 评估「候选 + 上下文」，给出其为真实密钥的可能性。 高置信度发现继续推进；可能的误报被过滤。

一个关键的设计选择是：模型并不取代确定性扫描，而是对其加以补充。正则仍然是快速找出候选字符串的正确工具。分类器则被用在机器学习最能发挥杠杆作用的地方：区分「看起来像密钥」与「很可能是真密钥」。

分类器模型会尽最大努力区分「看起来像密钥」与「很可能是真密钥」。

一个难负例问题：几乎以假乱真的密钥

多数误报并非随机的，而是难负例：匹配凭据模式但并非可用凭据的字符串。例子包括文档占位符、测试中的玩具示例、已脱敏的值、非敏感 ID 和生成的 fixture。这些情况对正则来说很容易匹配，而对纯规则系统来说，要在不误杀真实密钥的前提下抑制它们却很困难。

ModernBERT 的价值在于，它能把候选与邻近的代码和文本一起阅读，提供可与 LLM 媲美的上下文理解，却没有生成自然语言输出所带来的延迟与计算开销。例如，一个被「example」「dummy」「fake」或「replace-me」之类词语包围的候选，其风险可能低于一个被赋值给部署文件中某个环境变量的候选。分类器从带标注的样本中学习这些上下文差异，而不需要工程师把每一条例外都编码成又一条规则。

我们选择 ModernBERT，是因为它非常契合这一工作负载：紧凑、高效，且非常适合对代码相邻文本做分类。对密钥扫描而言，模型需要在高吞吐、低延迟下，对较短的候选窗口做出经过校准的判断。

这使得微调后的编码器分类器在这一流水线阶段，是比通用 LLM 更好的服务形态。模型可以直接在我们的决策边界上训练，并用与密钥扫描质量真正相关的召回率和精确率指标来评估。

挑战在于为「仅凭语法会产生误导」的那些场景找到有代表性的数据。我们的训练与评估策略结合了三个来源：

来自 GitHub 仓库的产品派生样本，结合密钥检测体验的反馈以及额外的人工验证。 来自 GitHub 仓库数据的高召回正则候选，包括人工标注样本和用于扩展覆盖面的弱标签。 针对稀疏与困难场景的合成样本，例如文档密钥、测试 fixture、公钥、校验和、结构化「看起来像」的字符串，以及近似错配的成对样本。

合成样本在纳入前需通过确定性校验和基于模型的质量审核。训练强调真实密钥、现实中的误报，以及那些经常让纯正则方案困惑的难负例。每个模型输入包含候选值、文件路径、密钥类型和一定数量的有界上下文。我们通过离线评估选择阈值，然后在更广泛放量前，在类生产流量上验证行为。

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

训练聚焦在对告警质量最重要的那些场景：真实密钥、现实的误报，以及正则频繁命中的难负例。输入表示包括候选密钥字符串、文件路径、类型和一定数量的有界上下文。输出是一个分类分数，供扫描器判断该候选是否应继续推进。

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

最重要的训练原则是让模型看到那些令人困惑的样本。我们纳入了与真实密钥语法相似但语义不同的候选，这样模型学到的就不仅是「密钥长什么样」，还包括「上下文中的误报长什么样」。

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