如何在 CI/CD 流程中落地 OWASP 静态代码扫描基准 V2.0（2023）

2023 年 5 月 30 日发布的《静态源代码安全扫描工具测评基准》V2.0，适合被当作 SAST 工具选型和落地检查的参考框架。真正把它接入 CI/CD，关键不在于把一份文档直接塞进流水线，而在于确认工具、规则包、构建过程和合规报告之间能够稳定衔接。

对于 DevSecOps 团队来说，比较稳妥的做法是先建立“规则来源可追溯、扫描结果可复现、阻断策略可调整”的最小闭环，再逐步扩大扫描范围。这样可以避免首次接入时误报过多，导致开发团队绕开检测或直接关闭安全门禁。

先明确 V2.0 在流水线中的作用

OWASP 中国发布的 V2.0 是静态源代码安全扫描工具的测评基准，资料摘要显示其关注部署环境、安全扫描和漏洞检测等方面，并服务于 SDL 与 DevSecOps 的落地。它可以帮助团队判断一款工具是否适合当前研发流程，但不能简单理解为一个能被所有扫描器直接加载的通用规则文件。

因此，接入前要区分三个对象：

• 测评基准：用于定义选型和评估维度。
• 工具规则集：由具体 SAST 工具提供，格式和加载方式取决于工具。
• 流水线门禁：由 Maven、Gradle、GitHub Actions 或 Jenkins 负责调用扫描，并根据结果执行后续动作。

如果工具供应方声称支持 OWASP 基准，应要求其说明支持的版本、覆盖方式、规则映射关系以及报告中如何标识对应规则。不要只根据产品页面上的“支持 OWASP”字样判断合规性。

选择工具并固定规则来源

选型时，先从项目实际使用的语言、构建方式和代码托管平台出发。对于 Maven 或 Gradle 项目，重点确认扫描器能否在非交互环境运行，能否读取构建生成的源代码或中间结果，以及能否输出适合 CI 判断的机器可读报告。

规则来源建议固定为以下链路：

1. 从 OWASP 中国或工具供应方的正式发布渠道确认 V2.0 资料和版本信息。
2. 从所选工具的官方渠道获取对应规则包或规则映射说明。
3. 将规则包放入受控的内部制品库、代码仓库或其他经过权限管理的存储位置。
4. 在流水线中固定规则来源和版本，避免每次构建自动获取不明变化的规则。
5. 在项目文档中记录规则包版本、启用范围、排除范围和最近一次调整原因。

这里有一个容易被忽略的风险：资料页面、下载地址或工具文档可能发生变化。当前资料中给出的 V2.0 PDF 地址已经出现页面不存在的情况，因此不应把某个历史下载链接硬编码为唯一来源。接入前应重新确认官方发布页面，并保存团队实际采用的版本副本。

规则包不宜一开始就全量启用。可以先选择与项目技术栈和安全目标直接相关的规则，完成一轮基线扫描后，再逐步增加覆盖范围。规则名称、严重级别和报告字段应通过工具官方文档确认，不要凭经验自行猜测。

在 Maven 和 Gradle 项目中接入规则

Maven 项目的配置思路

Maven 项目通常通过扫描工具提供的 Maven 插件、构建扩展或外部扫描程序接入。无论采用哪种方式，配置都应明确以下关系：

• 扫描发生在编译前、编译后，还是独立的验证阶段；
• 扫描器读取源代码，还是读取构建产物；
• 规则文件从哪个固定路径加载；
• 报告输出到哪个目录；
• 扫描发现问题时，是否让 Maven 构建失败；
• 本地开发和 CI 执行时是否使用同一套规则。

配置文件中不要把规则路径、报告路径和门禁阈值散落在多个位置。更适合的做法是统一使用项目变量或 CI 环境变量，由流水线在执行时传入。

配置结构可以先按下面的逻辑设计，具体插件名称和参数必须以所选工具的官方文档为准：

<!-- 结构示意，不是任意扫描器都可以直接执行的配置 -->
<security-scan>
  <rules>${security.rules.path}</rules>
  <source>${project.source.directory}</source>
  <report>${security.report.path}</report>
  <fail-build>${security.fail.build}</fail-build>
</security-scan>

不要把示意字段直接复制到生产项目。不同工具可能要求使用插件配置、命令行参数或独立配置文件，字段名称也不会统一。真正需要固定的是“规则、扫描范围、报告和失败策略”这四类信息。

Gradle 项目的配置思路

Gradle 项目应把安全扫描视为一个独立任务，或者绑定到已有的验证流程中。这样既可以在开发者本地单独执行，也可以在 CI 中明确调用，不必让扫描逻辑隐藏在普通编译任务内部。

建议先定义任务之间的依赖关系：

// 结构示意，不代表具体扫描工具的 Gradle 配置
tasks.register("securityScan") {
    // 加载固定规则文件
    // 扫描指定源码目录
    // 输出机器可读报告
    // 按门禁策略返回成功或失败
}

在实际配置中，需要确认扫描任务是否会自动触发编译、是否需要依赖生成源码、是否会扫描测试代码，以及失败时返回的状态是否能被 CI 正确识别。若项目包含多个模块，还要明确是每个模块分别出报告，还是合并成一份项目级报告。

规则文件最好不要直接复制到每个模块。多模块项目可以统一引用同一个受控规则目录，再对确实存在差异的模块设置局部例外。局部例外必须记录原因和负责人，否则时间一长，项目中会出现大量没人敢删除的历史排除项。

在 GitHub Actions 或 Jenkins 中编排扫描

流水线步骤可以拆成四个阶段：准备规则、执行构建、运行扫描、保存报告。扫描本身不应依赖开发者机器上的本地路径，也不应依赖交互式登录状态。

GitHub Actions 的作业结构可以按照下面的顺序设计：

# 结构示意，扫描器命令、参数和动作版本需替换为官方配置
steps:
  - name: 获取源代码
    uses: <官方代码检出步骤>

  - name: 准备规则文件
    run: <从受控来源获取并校验规则>

  - name: 构建项目
    run: <执行项目既有的 Maven 或 Gradle 构建>

  - name: 执行静态扫描
    run: <调用扫描器并指定规则、源码和报告路径>

  - name: 保存合规报告
    if: always()
    uses: <官方报告归档步骤>

这里的重点不是照抄某个模板，而是保证扫描失败时报告仍然能够保存。否则作业一旦被门禁中断，开发人员只能看到“构建失败”，却无法查看具体问题。

Jenkins 中可以使用同样的阶段划分：

pipeline {
    stages {
        stage('Build') {
            steps {
                sh '<执行 Maven 或 Gradle 构建>'
            }
        }
        stage('SAST') {
            steps {
                sh '<调用扫描器并加载固定规则>'
            }
        }
        stage('Report') {
            steps {
                archiveArtifacts artifacts: '<报告路径>'
            }
        }
    }
}

扫描步骤应使用流水线凭据或受控变量传递私密信息，不能把访问令牌、规则仓库凭据或内部地址直接写进仓库。报告归档也要注意权限，安全问题详情可能包含源代码片段、路径和业务上下文，不宜对所有构建参与者无差别开放。

合规报告至少要能回答四个问题

一份能用于 CI/CD 的报告，不只是把问题列表导出来，还要能支持后续判断：

• 使用了哪一版规则，规则来源是什么；
• 扫描了哪些目录、模块和文件；
• 每个问题对应的规则、严重程度、代码位置和证据是什么；
• 本次扫描是否达到项目设定的门禁条件。

报告格式可以同时保留机器可读版本和供开发人员阅读的版本。前者用于流水线判断和趋势处理，后者用于定位代码。若工具支持将问题映射到 OWASP 基准中的类别或规则，应在报告中保留该映射；如果不支持，则不要自行生成看似官方的对应关系，可以在项目文档中记录内部映射依据。

首次上线时，不建议直接阻断所有历史问题。更稳妥的方式是先建立当前分支的基线，只阻断新增问题或达到明确严重程度的问题。等团队完成一轮误报清理和历史问题分流后，再逐步收紧门禁。

常见误报与规则冲突怎么排查

误报排查不要从“关闭这条规则”开始，而应先确认问题是否真的属于误报。可以按以下顺序检查：

1. 查看规则说明、触发条件和代码位置，确认扫描器理解的调用链是否完整。
2. 检查该代码是否由框架、依赖库或构建过程自动生成。
3. 对照实际数据流，确认输入是否经过项目已有的校验、编码或安全封装。
4. 在最小范围内复现扫描，判断是单文件问题、模块问题还是规则之间的组合问题。
5. 记录判断依据，再决定修复代码、调整规则范围还是添加局部例外。

规则冲突通常表现为同一段代码同时触发多个问题，或者一条规则要求的写法与另一条规则的判断条件相互矛盾。此时不要简单按数量最多的结果处理，而应先确认规则优先级和业务安全目标。能够通过改进代码同时消除多个问题时，应优先修代码；只有确认规则不适用于当前框架或场景，才考虑局部抑制。

每个例外至少应保留规则标识、代码范围、排除原因、审核人和复查时间。避免使用覆盖整个目录的宽泛排除，也不要把生成代码、测试代码和生产代码全部一并忽略。例外范围越大，后续越难判断扫描结果是否仍然可信。

让安全扫描真正成为合并前检查

落地 OWASP 静态代码扫描基准 V2.0，最重要的不是在 CI 里增加一个扫描命令，而是建立可持续维护的流程：规则来源有记录，工具版本可追踪，Maven 或 Gradle 的执行方式稳定，GitHub Actions 或 Jenkins 能保存报告，误报和例外可以复查。

建议先在一个代表性项目中完成试运行，确认规则加载、报告归档和失败策略都符合预期，再推广到其他仓库。对于开发人员而言，扫描结果应尽量在合并前出现，并能直接定位到文件和代码位置；对于运维和安全人员而言，流水线应保留足够的历史报告，便于判断问题是新增、修复还是被错误排除。这样，静态分析才不只是一次性的安全审计，而能成为日常研发流程中的固定检查。