代码提交敏感信息扫描实践,极狐GitLab密钥检测配置详解
代码提交敏感信息扫描实践,极狐GitLab密钥检测配置详解
密钥检测:对提交内容中意外混入的令牌、私钥、连接字符串等静态凭据进行自动扫描,在推送、流水线、评论等多个环节拦截或告警的安全能力。
一条密钥入库,全公司买单
一个真实的常见剧本:开发者为本地调试方便,把数据库连接串或云服务令牌硬编码进配置文件,随手一次 git push,凭据就永久留在了仓库历史里。官方文档对此的表述很直白:敏感值被推送到远程代码仓库后,任何有权访问该代码仓库的人都可以使用该密钥来冒充已授权用户。更麻烦的是,Git 的设计决定了"删掉再提交"毫无用处——历史里它还在。
极狐GitLab 官方对密钥检测的定义是两个目标:帮助防止密钥被泄露,以及帮助你在密钥泄露时做出响应。同时官方明确建议采用多层防护,启用所有可用方式。三层检测各管一段:
检测方式 | 拦截时机 | 工作位置 | 可用版本 |
|---|---|---|---|
密钥推送保护 | 推送时直接阻止 | 预接收(pre-receive)钩子 | 旗舰版 |
流水线密钥检测 | 合并前流水线告警 | CI/CD | 基础/专业/旗舰版 |
客户端密钥检测 | 描述/评论保存前 | 议题与合并请求的描述、评论 | 旗舰版 |
官方语义边界提醒一句:流水线密钥检测默认只扫当前状态,不扫 Git 历史,历史里的存量泄露要靠单独触发一次历史扫描;推送保护只扫描差异中新引入的变更,密钥早已在文件里且本次未改动时不会被检测。两层互补,缺一不可。
配置第一层:流水线密钥检测
前提条件:基于 Linux 的 Runner(Docker 或 Kubernetes 执行器),不支持 Windows Runner、仅支持 amd64 架构;.gitlab-ci.yml 中需包含 test 阶段。启用只需一行 include:
include:
- template: Jobs/Secret-Detection.gitlab-ci.yml不想手写 YAML,也可以走页面配置:项目左侧边栏选择安全 > 安全配置,在"流水线密钥检测"行点使用合并请求配置,合并自动生成的 MR 即可。扫描以 secret_detection 作业运行,产物为 gl-secret-detection-report.json 报告文件;旗舰版中结果还会进入合并请求报告、漏洞报告和安全仪表板,并可接入审批策略。
首次启用后应立即跑一次历史扫描,检查仓库全部提交和分支中的存量密钥。操作路径:构建 > 流水线 > 新建流水线,添加 CI/CD 变量 SECRET_DETECTION_HISTORIC_SCAN = true 再触发。注意历史扫描耗时较长,官方明确只应运行一次,之后回归常规流水线扫描。
配置第二层:密钥推送保护,把门装在推送前
流水线检测是"事后告警",推送保护才是"当场拦截"。它在预接收钩子中检查每次推送的差异,默认检测到密钥即阻止推送,并返回提交 ID、文件名行号和密钥类型,例如 -- test.txt:2 GitLab Personal Access Token。为了控制延迟与误报,推送保护只选用高置信度模式,因此使用自定义前缀的个人访问令牌默认不在检测范围。
私有化部署需两步启用,缺一步都不生效:
实例管理员在管理员 > 设置 > 安全与合规的"密钥检测"下,勾选允许密钥推送保护;
项目具有安全管理员、维护者或所有者角色的成员,在项目安全 > 安全配置中打开密钥推送保护开关,也可通过群组安全设置 API 为群组内所有项目批量启用。
以下推送边界不在检查范围,排查"为什么没拦住"时先对这清单:
文件是二进制,或文件、差异补丁大于 1 MiB;
密钥存在于仓库初始推送中,或本次仅重命名/删除/移动且内容未变;
单次推送变更超过 3,150 个路径或 350,000 行,扫描整体跳过。
确有需要绕过时(如提交占位符测试密钥),Git CLI 使用 git push -o secret_push_protection.skip_all,其他客户端则在提交消息中加入 [skip secret push protection]。跳过行为会记录审计事件,包含账号、时间、项目和分支——绕行有痕,这就是审计闭环。
密钥已入库怎么办:响应与降噪
检测到密钥后,第一动作永远是轮换撤销,而不是删代码。官方文档强调:从仓库历史中清除密钥并不能完全解决泄露,因为任何既有复刻或克隆中仍保留着原始密钥。极狐GitLab 会尝试自动撤销某些类型的已泄露密钥,其余需按漏洞报告中的修复指引手动处理。误报治理上,购买了 Duo 附加组件的旗舰版客户可启用 Duo 误报检测,自动分析每项发现并给出置信度分数与说明,让安全团队聚焦真凭据。
FAQ
Q1:流水线密钥检测和密钥推送保护,开一个就够了吗?
不够。官方建议多层防护:推送保护在入口拦截新泄露(旗舰版),流水线检测兜底扫描已入库内容,且基础版即可用。只开后者,密钥已经进了仓库才被发现;只开前者,则覆盖不到推送保护的高置信度模式之外的类型。
Q2:为什么开启后历史里的密钥没被报出来?
流水线密钥检测默认只扫描仓库当前状态和未来提交。需要手动以 SECRET_DETECTION_HISTORIC_SCAN=true 变量触发一次历史扫描,且官方建议仅运行一次,避免长时间占用 Runner。
Q3:推送被拦截后,开发者怎么继续工作?
正确做法是移除密钥、改用外部密钥管理后重新推送;确需绕过时可用 git push -o secret_push_protection.skip_all 或在提交消息中加 [skip secret push protection],该操作会记录审计事件,便于事后追溯。
凭据泄露是成本最低的防线就能挡住的事故,前提是防线真的在跑。极狐GitLab 密钥检测三层能力已内建于平台,无需额外采购扫描器。想评估自己仓库的历史存量风险,或了解推送保护在私有化环境的落地路径,可预约演示或前往极狐GitLab 文档中心查阅完整配置说明,也可先免费试用在试点项目中实测扫描效果。

