Sonatype for GitLab CI

Sonatype for GitLab CI 是一个 Docker 镜像，允许在 GitLab CI/CD 管道运行期间对一个或多个构建制品执行策略评估。还可通过 Sonatype Container Security 集成扫描 Docker 容器。

对于 GitLab Ultimate 客户，Sonatype for GitLab CI 可填充 漏洞报告 和 依赖列表（GitLab Ultimate 安全功能的一部分）。

管道环境变量

建议在组或项目级别通过 <项目/组> → 设置 → CI/CD → 变量 配置以下环境变量：

• NEXUS_IQ_URL - Sonatype IQ Server 的 URL
• NEXUS_IQ_USERNAME - Sonatype IQ Server 的用户名
• NEXUS_IQ_PASSWORD - Sonatype IQ Server 的密码（确保隐藏密码）
• NEXUS_IQ_REPORT_FORMAT - 策略评估报告格式。接受值：summary（摘要）和 enhanced（增强）。

特定于容器扫描，连接远程仓库时还需定义以下变量（Docker 仓库凭据）：

• NEXUS_CONTAINER_IMAGE_REGISTRY_USER - Docker 仓库用户名
• NEXUS_CONTAINER_IMAGE_REGISTRY_PASSWORD - Docker 仓库密码

Sonatype IQ 策略评估

适用于所有 GitLab 版本

/sonatype/evaluate 操作允许在 GitLab CI/CD 管道中对一个或多个构建制品执行策略评估。

用法

myJob:
  stage: <GitLab 管道阶段>
  image: sonatype/gitlab-nexus-iq-pipeline:latest  
  script:
    /sonatype/evaluate [选项] <要扫描的归档文件或目录>

示例

policyEval:
  stage: test
  image: sonatype/gitlab-nexus-iq-pipeline:latest
  script:
    /sonatype/evaluate -i SomeWebApp target/our-web-app.war 

可用选项

-s, --server-url <iq-server-url> IQ Server URL。若未提供，必须设置环境变量 NEXUS_IQ_URL。必填项

-a, --authentication <username:password> IQ Server 凭据。若未提供，必须设置环境变量 NEXUS_IQ_USERNAME 和 NEXUS_IQ_PASSWORD。必填项

-i, --application-id <iq-application-id> IQ Server 上的应用 ID。必填项

-t, --stage <stage> 运行分析的 IQ Server 阶段。接受值：develop、source、build、stage-release、release、operate。默认值：build

-O, --organization-id <iq-organization-id> IQ Server 上的组织 ID。若应用不存在且启用自动应用创建配置，将在此组织下创建应用。默认值：none

-f, --report-format <format> 控制策略评估 HTML 报告的详细程度。接受值：summary、enhanced。若未提供且设置了 NEXUS_IQ_REPORT_FORMAT，则使用环境变量值。默认值：enhanced

-rn, --report-name <policy-evaluation-report.html> 策略评估 HTML 报告的名称。默认值：{application-name}-policy-eval.html

-r, --result-file <result-file.json> 存储策略评估结果的 JSON 文件名称（机器可读格式）。默认值：none

-w, --fail-on-policy-warnings 策略评估警告时失败。默认值：false

-e, --ignore-system-errors 忽略系统错误（IO、网络、服务器等）。默认值：false

-E, --ignore-scanning-errors 忽略扫描错误（损坏文件或格式错误文件等）。默认值：false

-p, --proxy <host[:port]> 使用的代理，格式 host[:port]。默认值：none

-U, --proxy-user <username:password> 代理凭据，格式 username:password。默认值：none

-ra, --reachability-analysis 启用可达性分析。默认值：false

-ran, --reachability-analysis-namespaces 仅对指定命名空间运行可达性分析。可多次指定，例如：-ran namespace1 -ran namespace2。可选

-X, --debug 启用调试日志。警告：可能在日志中暴露敏感信息。默认值：false

-h, --help 显示帮助信息

-D<key=value> 设置 Java 系统属性（键值对）。可多次指定，例如：-Dkey1=value1 -Dkey2=value2。可选

评估报告

evaluate 操作生成的 HTML 报告包含以下内容之一：

• 简要摘要信息和指向 IQ Server 上详细报告的链接；
• 上述所有内容 plus 触发策略操作的组件详情，包括策略违规细节。

报告存储在构建目录中，默认名称为 -policy-eval-report.html。可使用 --report-name 更改名称。

若要将报告保存为 pipeline 制品，可在 .gitlab-ci.yml 的评估步骤中添加 artifacts 部分：

  artifacts:
    paths:
      - <application-id>-policy-eval-report.html

其他示例

多个构建制品，相同 IQ 应用 ID

可指定多个扫描目标（目录或文件，空格分隔）：

policyEval:
  stage: test
  image: sonatype/gitlab-nexus-iq-pipeline:latest 
  script:
    /sonatype/evaluate -i SomeSystem web-module/target/our-web-app.war lib-module/target/our-shared-lib.jar 

多个构建制品，不同 IQ 应用 ID

可对每个制品执行单独评估，示例如下（同一任务）：

policyEval:
  stage: test
  image: sonatype/gitlab-nexus-iq-pipeline:latest 
  script:
    /sonatype/evaluate -i SomeWebApp web-module/target/our-web-app.war
    /sonatype/evaluate -i SomeSharedLib lib-module/target/our-shared-lib.jar 

高级管道（多阶段多策略评估）

以下示例为 Maven 项目设置三个阶段（build、test、release），包含测试和发布阶段的策略评估：

.nexus_iq_policy_eval: &nexus_iq_policy_eval
  image: sonatype/gitlab-nexus-iq-pipeline:latest
  script:
    - /sonatype/evaluate -i SomeWebApp -t $IQ_STAGE target/*.war
  artifacts:
    paths:
      - ./SomeWebApp-policy-eval-report.html

# 主分支评估（build 阶段）
iq_policy_main:
  <<: *nexus_iq_policy_eval
stage: test
variables:
  IQ_STAGE: "build"
only:
  - main

# 其他分支评估（develop 阶段）
iq_policy_branch:
  <<: *nexus_iq_policy_eval
stage: test
variables:
  IQ_STAGE: "develop"
except:
  - main

# 发布阶段评估（手动触发）
iq_policy_release:
  <<: *nexus_iq_policy_eval
stage: release
variables:
  IQ_STAGE: "release"
only:
  - main
when: manual

容器扫描 via Sonatype Container Security

扫描容器需使用 Docker in Docker 镜像。示例配置如下：

image: docker:docker:24.0.5

services:
  - docker:24.0.5-dind

build:
  stage: build
  script:
    - docker run -v $CI_PROJECT_DIR:/sonatype/reports -v /var/run/docker.sock:/var/run/docker.sock -e NEXUS_IQ_URL -e NEXUS_IQ_USERNAME -e NEXUS_IQ_PASSWORD -e NEXUS_CONTAINER_IMAGE_REGISTRY_USER -e NEXUS_CONTAINER_IMAGE_REGISTRY_PASSWORD sonatype/gitlab-nexus-iq-pipeline:latest /sonatype/evaluate -i SomeContainerApp container:[***]
  artifacts:
    paths:
      - $CI_PROJECT_DIR/$CI_PROJECT_NAME-policy-eval-report.html

• 扫描私有镜像需 NEXUS_CONTAINER_IMAGE_REGISTRY_USER 和 NEXUS_CONTAINER_IMAGE_REGISTRY_PASSWORD；公共镜像无需凭据。
• 1.183.0 及更早版本需添加 -v /tmp:/tmp 挂载。

漏洞报告更新

适用于 GitLab Ultimate

/sonatype/create-vulnerability-report 操作可基于策略评估结果填充 GitLab 的 漏洞报告。需在 evaluate 步骤中生成结果文件并作为制品传递。

用法

dependency_scanning:
  needs: [ <evaluate-step-name> ]
  stage: <GitLab 管道阶段>
  when: always
  image: sonatype/gitlab-nexus-iq-pipeline:latest
  script:
    - /sonatype/create-vulnerability-report [选项]
  artifacts:
    reports:
      dependency_scanning: <vulnerability-report.json>

示例

iq_policy_evaluation:
  stage: test
  image: sonatype/gitlab-nexus-iq-pipeline:latest
  script:
    - /sonatype/evaluate -i testapp -r scan-result.json *.jar
  artifacts:
    when: always
    paths:
      - scan-result.json

dependency_scanning:
  needs: ["iq_policy_evaluation"]
  stage: test
  when: always
  image: sonatype/gitlab-nexus-iq-pipeline:latest
  script:
    - /sonatype/create-vulnerability-report -r scan-result.json --report-file vulnerability-report.json -x 15.1.4
  artifacts:
    reports:
      dependency_scanning: vulnerability-report.json 

可用选项

-r, --result-file <result-file.json> - 策略评估结果 JSON 文件名称。必填项 -f, --report-file <vulnerability-report.json> - 生成的依赖扫描报告名称。必填项 -x, --schema-version <15.1.4> - 报告 schema 版本。接受值：15.0.7、15.1.4、15.2.1。默认值：15.2.1

获取和存储 SBOM 文件

适用于所有 GitLab 版本

/sonatype/fetch-sbom 操作可从 IQ Server 下载与扫描 ID 关联的 SBOM 文件，并存储为 pipeline 制品。GitLab Ultimate 客户可使用符合 CycloneDX 标准的 SBOM 填充 依赖列表（需 --update-dependency-list 标志）。

用法示例

iq_policy_evaluation:
  stage: test
  image: sonatype/gitlab-nexus-iq-pipeline:latest
  script:
    - /sonatype/evaluate -i testapp -r scan-result.json *.jar
  artifacts:
    when: always
    reports:
      dotenv: evaluate.env
    paths:
      - scan-result.json

download_sbom:
  needs: ["iq_policy_evaluation"]
  when: always
  stage: deploy
  image: sonatype/gitlab-nexus-iq-pipeline:latest
  script:
    - /sonatype/fetch-sbom -i testapp -si ${NEXUS_IQ_SCAN_ID} -ss cycloneDx -sv 1.5 -sf json -n sbom.cdx.json -udl
  artifacts:
    reports:
      cyclonedx: sbom.cdx.json

发布说明

发布说明可在 此处 查看。