Trivy GitLab CI 组件

一个面向 Trivy 的 GitLab CI 组件——Trivy 是一款全功能安全扫描器，涵盖容器镜像、文件系统、仓库、Kubernetes 集群、SBOM 以及许可证合规性。将这些模板直接插入你的流水线，即可获得可重复的扫描、GitLab 原生报告以及便携式工件，几乎无需编写 Shell 脚本。

功能特性

• 完整覆盖面：容器、文件系统、根文件系统、Git 仓库、虚拟机、SBOM、Kubernetes 集群等。
• 多扫描器：漏洞、错误配置/IaC、密钥和许可证扫描，每个作业均可控制。
• GitLab 报告：输出容器扫描、JUnit、SARIF 和 JSON 工件，可直接用于合并请求洞察。
• 可定制的输入参数：每个模板都暴露了严重级别、扫描器、超时、包类型和工件的调节选项。
• 可组合的模板：在同一个组件命名空间下，混合使用远程或本地扫描、SBOM 工作流、Rekor 证明和 IaC 检查。

使用方法

基本用法

include:
  - component: $CI_SERVER_FQDN/niclas-zone/ci/trivy/main@latest

stages:
  - test

远程镜像，自定义严重级别

include:
  - component: $CI_SERVER_FQDN/niclas-zone/ci/trivy/main@latest
    inputs:
      job_name: "security:remote"
      TRIVY_SCAN_REMOTE_IMAGE: "registry.gitlab.com/group/app:latest"
      severity: "CRITICAL,HIGH,MEDIUM"
      exit_on_vulnerability: true

stages:
  - test

本地 tar / OCI 布局扫描

include:
  - component: $CI_SERVER_FQDN/niclas-zone/ci/trivy/main@latest
    inputs:
      job_name: "security:local"
      TRIVY_SCAN_LOCAL_IMAGES: "dist/"
      TRIVY_SCANNERS: "vuln,secret"
      exit_on_vulnerability: false

stages:
  - test

组件输入与模板

以下每个模板都列出了组件规范中定义的可用输入及其默认值，随后是一个最小工作示例。

组件：templates/main.yml

输入	描述	默认值
job_name	CI 作业名称	"trivy scanning"
stage	流水线阶段	"test"
image	运行 Trivy 的容器镜像	"ghcr.io/aquasecurity/trivy:0.68.1"
TRIVY_NEEDED_STAGE	在 Trivy 运行前必须完成的阶段	"build"
TRIVY_SCAN_REMOTE_IMAGE	要扫描的远程镜像	""
TRIVY_SCAN_LOCAL_IMAGES	tar/OCI 输入的路径（为空时搜索 .）	""
TRIVY_SCANNERS	逗号分隔的扫描器列表	"vuln,secret,misconfig"
severity	包含的严重级别	"CRITICAL,HIGH"
exit_on_vulnerability	发现问题时作业失败	true
TRIVY_EXTRA_ARGS	额外的 CLI 参数	""
allow_failure	允许作业失败而不导致流水线失败	false

示例

include:
  - component: $CI_SERVER_FQDN/niclas-zone/ci/trivy/main@latest
    inputs:
      job_name: "trivy:basic"
      TRIVY_SCAN_REMOTE_IMAGE: "nginx:latest"

组件：templates/target_container.yml

输入	描述	默认值
job_name	CI 作业名称	"trivy:scan:containers"
stage	流水线阶段	"test"
image	Trivy 容器镜像	"ghcr.io/aquasecurity/trivy:0.68.1"
TRIVY_SCAN_REMOTE_IMAGE	远程镜像引用	""
TRIVY_SCAN_LOCAL_IMAGES	本地扫描的目录/tar	""
TRIVY_SCANNERS	已启用的扫描器	"vuln,secret,misconfig"
TRIVY_IMAGE_SRC	镜像源后端（remote/docker/...）	""
severity	严重级别	"CRITICAL,HIGH"
exit_on_vulnerability	严重级别匹配时失败	true
TRIVY_IGNORE_UNFIXED	忽略无修复的问题	true
TRIVY_PKG_TYPES	包类型	"os,library"
TRIVY_VULN_TYPE	已弃用的包类型别名	""
TRIVY_TIMEOUT	命令超时	"10m"
TRIVY_EXTRA_ARGS	额外的 CLI 参数	""
TRIVY_DB_REPOSITORY	自定义数据库镜像	""
TRIVY_JAVA_DB_REPOSITORY	自定义 Java 数据库镜像	""
TRIVY_SKIP_FILES	文件通配排除	""
TRIVY_SKIP_DIRS	目录排除	""
allow_failure	允许失败而不导致流水线失败	false

示例

include:
  - component: $CI_SERVER_FQDN/niclas-zone/ci/trivy/target_container@latest
    inputs:
      job_name: "trivy:containers"
      TRIVY_SCAN_REMOTE_IMAGE: "registry.gitlab.com/group/service:latest"
      TRIVY_SCANNERS: "vuln,secret"
      exit_on_vulnerability: true

组件：templates/target_filesystem.yml

输入	描述	默认值
job_name	CI 作业名称	"trivy:scan:filesystem"
stage	流水线阶段	"test"
image	Trivy 镜像	"ghcr.io/aquasecurity/trivy:0.68.1"
TRIVY_FS_PATH	要扫描的文件或目录	"."
TRIVY_SCANNERS	已启用的扫描器	"vuln,secret"
severity	严重级别	"CRITICAL,HIGH"
exit_on_vulnerability	严重级别匹配时失败	true
TRIVY_IGNORE_UNFIXED	忽略无修复的问题	true
TRIVY_PKG_TYPES	包类型	"os,library"
TRIVY_TIMEOUT	超时	"10m"
TRIVY_SKIP_FILES	要跳过的文件通配	""
TRIVY_SKIP_DIRS	要跳过的目录	""
TRIVY_EXTRA_ARGS	额外的 CLI 参数	""
TRIVY_REPORT_BASENAME	工件基础名称	"filesystem-scan"
allow_failure	允许作业失败	false

示例

include:
  - component: $CI_SERVER_FQDN/niclas-zone/ci/trivy/target_filesystem@latest
    inputs:
      TRIVY_FS_PATH: "services/api"
      TRIVY_SCANNERS: "vuln,misconfig,secret"

组件：templates/target_rootfs.yml

输入	描述	默认值
job_name	作业名称	"trivy:scan:rootfs"
stage	阶段	"test"
image	Trivy 镜像	"ghcr.io/aquasecurity/trivy:0.68.1"
TRIVY_ROOTFS_PATH	根文件系统路径	"/"
TRIVY_SCANNERS	扫描器	"vuln,secret"
severity	严重级别	"CRITICAL,HIGH"
exit_on_vulnerability	发现结果时作业失败	true
TRIVY_IGNORE_UNFIXED	忽略无修复	true
TRIVY_PKG_TYPES	包类型	"os,library"
TRIVY_TIMEOUT	超时	"10m"
TRIVY_SKIP_FILES	要跳过的文件	""
TRIVY_SKIP_DIRS	要跳过的目录	""
TRIVY_EXTRA_ARGS	额外参数	""
TRIVY_REPORT_BASENAME	工件基础名称	"rootfs-scan"
allow_failure	允许失败	false

示例

include:
  - component: $CI_SERVER_FQDN/niclas-zone/ci/trivy/target_rootfs@latest
    inputs:
      TRIVY_ROOTFS_PATH: "/mnt/root"
      TRIVY_SCANNERS: "vuln"

组件：templates/target_repository.yml

输入	描述	默认值
job_name	作业名称	"trivy:scan:repo"
stage	阶段	"test"
image	Trivy 镜像	"ghcr.io/aquasecurity/trivy:0.68.1"
TRIVY_REPO_TARGET	本地路径或 Git URL	"."
TRIVY_REPO_BRANCH	远程分支	""
TRIVY_REPO_COMMIT	提交哈希	""
TRIVY_REPO_TAG	标签名	""
TRIVY_SCANNERS	扫描器	"vuln,secret"
severity	严重级别	"CRITICAL,HIGH"
exit_on_vulnerability	发现结果时作业失败	true
TRIVY_IGNORE_UNFIXED	忽略无修复	true
TRIVY_TIMEOUT	超时	"10m"
TRIVY_SKIP_FILES	要跳过的文件	""
TRIVY_SKIP_DIRS	要跳过的目录	""
TRIVY_EXTRA_ARGS	额外参数	""
TRIVY_REPORT_BASENAME	工件基础名称	"repo-scan"
allow_failure	允许失败	false

示例

include:
  - component: $CI_SERVER_FQDN/niclas-zone/ci/trivy/target_repository@latest
    inputs:
      TRIVY_REPO_TARGET: "https://github.com/aquasecurity/trivy"
      TRIVY_REPO_BRANCH: "main"

组件：templates/target_vm.yml

输入	描述	默认值
job_name	作业名称	"trivy:scan:vm"
stage	阶段	"test"
image	Trivy 镜像	"ghcr.io/aquasecurity/trivy:0.68.1"
TRIVY_VM_TARGET	本地路径或 ami:/ebs: 标识符	""
TRIVY_AWS_REGION	AMI/EBS 扫描的 AWS 区域	""
TRIVY_SCANNERS	扫描器	"vuln"
severity	严重级别	"CRITICAL,HIGH"
exit_on_vulnerability	发现结果时作业失败	true
TRIVY_IGNORE_UNFIXED	忽略无修复	true
TRIVY_TIMEOUT	超时	"20m"
TRIVY_EXTRA_ARGS	额外参数	""
TRIVY_REPORT_BASENAME	工件基础名称	"vm-scan"
allow_failure	允许失败	false

示例

include:
  - component: $CI_SERVER_FQDN/niclas-zone/ci/trivy/target_vm@latest
    inputs:
      TRIVY_VM_TARGET: "ami-0123456789abcdef0"
      TRIVY_AWS_REGION: "us-east-1"

组件：templates/target_kubernetes.yml