在 CI 流水线里配置 SCA 门禁：从阈值设计到分级阻断

开发团队普遍面临一个两难困境：把 SCA 扫描接入 CI 流水线之后，要么扫出一堆告警没人处理，要么直接阻断导致流水线天天红灯、工程师绕路提交。两种结果都指向同一个失败——门禁形同虚设，或者门禁成为团队的对立面。

问题不在于"要不要扫"，而在于"怎么设计门禁策略"。

门禁的本质：风险分级，而非全量阻断

很多团队初次接入 SCA 时犯的第一个错误，是把"发现漏洞"直接等同于"阻断构建"。这种做法在初期会制造大量噪音：历史依赖积压的已知漏洞、开发环境专用组件中的低危问题、以及工具本身的误报，都会触发阻断，最终让工程师养成忽略告警的习惯，或者绕过流水线。

更合理的设计是三档分级：

• 阻断（Block）：高危及以上漏洞（CVSS ≥ 9.0）、存在已知公开利用链的严重漏洞、许可证冲突会影响产品发布合规性的组件。这一档必须在合并前解决，不允许例外。
• 告警（Warn）：中危漏洞、EOL 组件（如仍在使用 Log4j 1.x 这类 早在 2015 年就已停止维护 的版本）、许可证存在潜在冲突但尚未确认影响范围的情况。告警进入工单系统，纳入下一个迭代处理，不阻断当前构建。
• 放行（Pass）：低危漏洞、仅出现在测试依赖中的问题、已有缓解措施并经安全团队确认的已知风险。记录在 SBOM 中，定期复查。

这一分级逻辑与 CleanSource SCA 的内置策略引擎基本对齐——它支持按 CVSS 评分、漏洞可达性、许可证类型、组件所在环境（生产/测试/构建）等多个维度组合配置门禁规则，避免一刀切带来的误伤。

阈值设计：让数字有意义

"CVSS 评分多少才阻断"是最常被问到的问题，但真正决定阈值的不是某个通用标准，而是你的业务场景。

以下几个维度值得在阈值设计阶段认真回答：

• 组件是否直接暴露在攻击面上？ 一个 CVSS 7.5 的漏洞，如果存在于仅用于内部批处理的后台服务，和存在于对外提供 API 的核心服务，处置优先级应该完全不同。
• 是否存在公开 PoC 或已知在野利用？ Log4Shell（CVE-2021-44228）在 2021 年 12 月披露时 CVSS 仅为 10 分，但其在野利用速度之快让打分本身的参考意义大打折扣——有时候漏洞的"热度"比分数更值得关注。
• 修复版本是否可用？ 如果上游没有补丁，阻断只会制造压力，不会产生解法。这种情况下告警加缓解措施记录更务实。
• 许可证风险边界在哪里？ GPL 系许可证在商业闭源产品中的引入，和在内部工具中的引入，法律影响截然不同。许可证冲突检测 需要结合产品形态单独配置规则，不应与漏洞门禁混用同一套阈值。

一个可操作的起点：新增组件（增量部分）使用严格阈值，存量组件使用宽松阈值，并为存量设置消减计划。这样既不放任历史债务无限扩张，又不因历史问题每天阻断正常开发。

增量扫描：速度是门禁能否坚持下去的关键

全量扫描对于大型项目来说耗时可能以分钟甚至十几分钟计。如果每次 MR 都触发全量扫描，流水线的等待成本会很快让工程师产生抵触。

增量扫描的核心思路是：只扫本次变更引入或升级的组件，以及与之存在依赖关系的直接上下游。对于未变更的组件，沿用上一次扫描缓存的结果，只在定时任务中做全量复查（例如每天凌晨跑一次完整扫描，更新漏洞情报匹配结果）。

CleanSource SCA 的增量扫描模式可以将单次 MR 触发的扫描时间控制在 60 秒以内，这对于希望在 Pre-Merge 阶段配置门禁的团队来说是一个可接受的延迟区间。配合其覆盖 600+ 包管理生态、沉淀 3.2 亿组件指纹的数据基础，增量扫描的覆盖度不会因为"只扫变更部分"而出现漏洞盲区。

值得注意的是，片段级检测（即对源代码片段的成分溯源）与 manifest 级检测的结合使用，能够发现那些"隐藏在代码里而不是声明在依赖文件里"的组件引入。关于两者的覆盖边界，可以参考 片段级 SCA 与 manifest 级 SCA 的对比分析。

误报处理：没有机制的门禁会自我崩溃

误报是所有安全工具的固有问题。如果团队没有建立系统性的误报处理流程，最终的结果要么是告警被集体忽略，要么是有人直接修改配置把规则关掉。CleanSource SCA 的误报率控制在 15% 以内，但即便如此，在规模较大的项目中，误报的绝对数量也足以制造认知负担。

一套可运转的误报处理流程应当包含以下环节：

• 提报入口：工程师在 CI 界面直接标记"疑似误报"，附上判断依据（例如漏洞影响的代码路径在当前项目中不可达）。
• 审核责任人：由安全团队或指定的 Security Champion 在固定 SLA 内（例如 2 个工作日）给出确认或否定。
• 豁免记录：确认误报后，生成带有有效期的豁免条目，写入项目级配置文件并纳入版本控制。豁免条目到期后自动重新触发审核，不允许永久豁免。
• 反馈上游：对于工具侧的系统性误报，建立向工具提供商的反馈通道，追踪修复进度。

这个流程的关键在于"有期限的豁免"而非"永久例外"——它让门禁保持弹性，同时避免豁免列表无限膨胀变成另一种形式的规则失效。

接入 Jenkins 与 GitLab CI 的实操要点

Jenkins 接入

Jenkins 通常通过 Pipeline 脚本（Jenkinsfile）集成 SCA 扫描。推荐的位置是在单元测试之后、制品构建之前插入扫描步骤。CleanSource SCA 提供 CLI 工具和 REST API 两种调用方式，可以通过 sh 步骤直接调用，扫描结果以 JSON 或 SARIF 格式输出，便于后续解析。

门禁逻辑建议在 Jenkinsfile 中显式编写，而不是依赖工具默认行为。例如：读取扫描结果中的严重漏洞数量，若大于零则调用 error() 终止流水线；中危漏洞数量写入环境变量，通过 unstable() 标记构建为不稳定而非直接失败。这样的显式控制让策略调整不依赖工具升级，版本可追溯。

GitLab CI 接入

GitLab CI 的 .gitlab-ci.yml 支持将 SCA 扫描配置为独立 stage，并通过 allow_failure: true/false 控制是否阻断后续 stage。推荐配置方式：

• 在 scan stage 中运行 CleanSource SCA，输出结果文件。
• 在 gate stage 中运行策略评估脚本，根据分级规则决定是否 exit 1。
• 将扫描报告通过 artifacts 保存，供 MR 界面展示和后续审计使用。

GitLab 的 Merge Request Approval Rules 可以配置为：当 gate stage 失败时，必须由安全团队成员手动审批才能合并。这比直接阻断更灵活，适合需要快速迭代的业务线。

对于同时需要 SAST 能力的团队，CleanCode Security Agent 可以与 CleanSource SCA 在同一流水线中并行运行，共用扫描触发器，避免重复配置带来的维护负担。如果涉及二进制交付或固件场景，CleanBinary 可以在制品发布阶段补充成分分析覆盖。

---

配置 SCA 门禁不是一次性的工程任务，而是一个需要持续校准的过程。漏洞情报在更新，组件生态在演变，业务风险偏好在变化——门禁策略也应当随之迭代。从分级阻断开始，把增量扫描的速度做到可接受，把误报处理的流程跑通，门禁才能真正成为开发流程的一部分，而不是工程师需要绕过的障碍。

想了解如何在不同行业场景下设计差异化的 SCA 策略，可以参考 金融行业开源治理实践 和 医疗器械 SBOM 合规 中的具体案例拆解。