ThreatMapper CI/CD 集成实战:在 CircleCI、GitLab、Jenkins、GitHub Actions 与 HashiCorp Packer 中接入镜像安全扫描

原创2026-10-12 19:48:192,173 阅读
文章标签:网络安全云原生漏洞扫描SBOM供应链安全可观测性合规审计容器编排后端

ThreatMapper CI/CD 集成实战:在 CircleCI、GitLab、Jenkins、GitHub Actions 与 HashiCorp Packer 中接入镜像安全扫描

ThreatMapper(Deepfence)在仓库 ci-cd-integrations 目录下提供了完整的 CI/CD 插件体系,支持将镜像**漏洞扫描(Vulnerability Scan)、密钥扫描(Secret Scan)与恶意软件扫描(Malware Scan)**直接嵌入 CircleCI、GitLab、Jenkins、GitHub Actions 和 HashiCorp Packer 五种主流交付流水线。读完本文,你将掌握如何在各自平台的流水线中配置扫描器容器、通过 fail-on-* 系列参数实现"漏洞超阈值即中断构建"的门禁机制,并理解这些扫描器与 ThreatMapper 管理控制台(Deepfence Console)之间的数据上报与联动关系。

一、CI/CD 集成整体架构

ci-cd-integrations 目录按 CI/CD 平台划分为五个子目录,每个子目录都包含一套可独立运行的示例工程:

ci-cd-integrations/
├── circleci/          # CircleCI 2.0 + AWS ECS/ECR 部署示例
├── github-actions/    # GitHub Actions 最小示例
├── gitlab/            # GitLab CI/CD 构建部署示例
├── hashicorp-packer/  # Packer 镜像构建 + 三类扫描(malwares/secrets/vulnerabilities)
└── jenkins/           # Jenkins 漏洞/密钥/恶意软件扫描流水线

从源码结构看,这套集成方案的核心思路是:在流水线的"构建镜像"阶段之后、"推送/部署"阶段之前,插入一个扫描器容器。扫描器以独立 Docker 镜像的形式运行(如 deepfence_package_scanner_cli、deepfence_secret_scanner、deepfence_malware_scanner),通过挂载宿主机 Docker socket(-v /var/run/docker.sock:/var/run/docker.sock:rw)对刚构建的镜像执行分析;扫描结果既会上报到管理控制台,也会通过扫描器进程的退出码决定流水线是否继续,从而形成**"构建 → 扫描 → 门禁 → 部署"**的安全交付闭环。

这些扫描器镜像与仓库的构建体系是连通的:根目录 Makefile 中可以看到 deepfence_secret_scanner_ce 与 deepfence_malware_scanner_ce 镜像的构建定义(分别基于 deepfence_agent/plugins 与 malware scanner 目录),docs/docs/developers/build.md 也将二者列为可构建产物。也就是说,除直接拉取 quay.io/deepfenceio 上的发布镜像外,你也可以从本仓库源码自行构建 CE 版本扫描器使用。

二、统一的安全门禁参数:fail-on-* 系列

所有 CI/CD 集成共享同一套"失败门禁"参数语义。核心规则是:

当扫描结果满足 >= 阈值时,构建失败;将该值设为 -1 则忽略对应维度的门禁,始终放行。

以漏洞扫描为例,各平台均可配置以下参数:

参数 含义 设为 -1 的效果
fail-on-count / FAIL_CVE_COUNT 漏洞总数 ≥ 该值时构建失败 忽略总数门禁
fail-on-critical-count / FAIL_CRITICAL_CVE_COUNT 严重(Critical)漏洞数 ≥ 该值时失败 忽略 Critical 门禁
fail-on-high-count / FAIL_HIGH_CVE_COUNT 高危(High)漏洞数 ≥ 该值时失败 忽略 High 门禁
fail-on-medium-count / FAIL_MEDIUM_CVE_COUNT 中危(Medium)漏洞数 ≥ 该值时失败 忽略 Medium 门禁
fail-on-low-count / FAIL_LOW_CVE_COUNT 低危(Low)漏洞数 ≥ 该值时失败 忽略 Low 门禁
fail-on-score / FAIL_CVE_SCORE 累计 CVE 评分 ≥ 该值时失败 忽略评分门禁

密钥扫描与恶意软件扫描使用同样的模式,仅将参数替换为 fail-on-count、fail-on-high-count、fail-on-medium-count、fail-on-low-count(分别对应总数、High、Medium、Low 四个维度)。这种分级门禁允许团队按风险承受能力差异化设限,例如"允许低危存在但绝不允许一个 Critical 流出流水线"。

三、CircleCI:构建 Go 服务并推送 AWS ECS/ECR

circleci/README.md 给出了一个基于 CircleCI 2.0 的完整示例:构建并测试一个 Docker 化的 "Hello World" Go Web 应用,推送到 Amazon ECR,并部署到 AWS ECS(Fargate 启动类型)。示例应用本体位于 circleci/src/main.go,是一个监听 :8080 返回 Hello World! 的最小 HTTP 服务;其运行镜像由 circleci/Dockerfile 定义(基于 ubuntu:18.04,将编译产物复制到 /opt/demo-app)。

3.1 必配环境变量

在 CircleCI 项目设置页(Project Settings → Environment Variables)中,必须配置以下变量才能成功构建:

变量 说明
AWS_ACCESS_KEY_ID AWS CLI 使用的访问密钥 ID
AWS_SECRET_ACCESS_KEY AWS CLI 使用的访问密钥
AWS_DEFAULT_REGION AWS CLI 默认区域,示例值 us-east-1;需确保该区域支持 Fargate 启动类型
AWS_ACCOUNT_ID AWS 账户 ID,部署阶段必需
AWS_RESOURCE_NAME_PREFIX 部分 AWS 资源名称的前缀,应与 ECR 仓库名或 terraform_setup/terraform.tfvars 中的 aws_resource_prefix 值对应
DEEPFENCE_CONSOLE_URL Deepfence 管理控制台(Deepfence Console)地址
FAIL_CVE_COUNT 漏洞总数 ≥ 该值时构建失败,-1 表示忽略
FAIL_CRITICAL_CVE_COUNT Critical 漏洞数 ≥ 该值时失败,-1 表示忽略
FAIL_HIGH_CVE_COUNT High 漏洞数 ≥ 该值时失败,-1 表示忽略
FAIL_MEDIUM_CVE_COUNT Medium 漏洞数 ≥ 该值时失败,-1 表示忽略
FAIL_LOW_CVE_COUNT Low 漏洞数 ≥ 该值时失败,-1 表示忽略
FAIL_CVE_SCORE 累计 CVE 评分 ≥ 该值时失败,-1 表示忽略

其中前五个变量服务于 AWS 侧的构建与部署,后七个变量(DEEPFENCE_CONSOLE_URL 与 FAIL_* 系列)服务于镜像漏洞扫描门禁。CircleCI 构建环境中还需安装 AWS CLI,circleci/requirements.txt 中给出的依赖约束为 awscli>=1.25.19。

四、GitLab CI/CD:构建 Go 服务并推送任意镜像仓库

gitlab/README.md 对应一个名为 simple_go_server 的示例工程:构建并测试 Docker 化的 Go Web 应用,之后可将镜像推送到任意远端镜像仓库。示例应用位于 gitlab/src/main.go,同样是监听 :8080 返回 Hello World! 的最小服务,gitlab/Dockerfile 将其打包为 ubuntu:18.04 基础镜像。

4.1 必配 CI/CD 变量

在 GitLab 项目设置页(Project > Settings > CI/CD > Variables)中配置以下变量:

变量 说明
DEEPFENCE_CONSOLE_URL Deepfence 管理控制台地址
FAIL_CVE_COUNT 漏洞总数 ≥ 该值时构建失败,-1 表示忽略
FAIL_CRITICAL_CVE_COUNT Critical 漏洞数 ≥ 该值时失败,-1 表示忽略
FAIL_HIGH_CVE_COUNT High 漏洞数 ≥ 该值时失败,-1 表示忽略
FAIL_MEDIUM_CVE_COUNT Medium 漏洞数 ≥ 该值时失败,-1 表示忽略
FAIL_LOW_CVE_COUNT Low 漏洞数 ≥ 该值时失败,-1 表示忽略
FAIL_CVE_SCORE 累计 CVE 评分 ≥ 该值时失败,-1 表示忽略

与 CircleCI 版本相比,GitLab 版本无需 AWS 相关变量——它只负责构建与扫描,镜像推送目标由你自己的 Runner 配置决定(GitLab 官方推荐使用 Docker executor 并在流水线内使用 Docker 镜像构建)。在 GitLab Runner 上运行 Docker 构建与 Docker 镜像需要额外配置,相关前置要求可参考 GitLab 官方文档中关于 Docker 构建与 Docker 镜像使用的章节。

五、Jenkins:漏洞、密钥与恶意软件三类流水线

ci-cd-integrations/jenkins 是集成内容最丰富的平台,jenkins/README.md 明确列出四份可直接使用的流水线文件:

文件 扫描类型 说明
vulnerabilities_scripted_pipeline.Jenkinsfile 漏洞 脚本式(Scripted)流水线
vulnerabilities_declarative_pipeline.Jenkinsfile 漏洞 声明式(Declarative)流水线
secrets.Jenkinsfile 密钥 密钥泄露扫描
malwares.Jenkinsfile 恶意软件 恶意软件扫描

示例工程镜像名为 deepfenceio/jenkins-example:latest,由 jenkins/Dockerfile(基于 python:3.6-slim-stretch,用 python3 -m http.server 8000 托管一个静态页面)构建。

5.1 漏洞扫描:脚本式与声明式流水线

两份漏洞扫描流水线的主体逻辑完全一致,差异仅在语法包装(脚本式用 node {},声明式在 stage 内用 steps { script {} })。以 vulnerabilities_scripted_pipeline.Jenkinsfile 为例,流水线分三个阶段:

  1. Clone repository:checkout scm 拉取代码;
  2. Build image:docker.build("${full_image_name}", "-f ci-cd-integrations/jenkins/Dockerfile .") 构建镜像;
  3. Run Deepfence Vulnerability Mapper:拉取扫描器镜像并以容器方式执行扫描。

扫描器执行的核心命令(声明式版本见 vulnerabilities_declarative_pipeline.Jenkinsfile):

def deepfence_mgmt_console_url = '127.0.0.1' // 管理控制台地址,注意不要带端口
def fail_cve_count = 100                     // 漏洞总数 >= 该值时失败;-1 表示忽略
def fail_critical_cve_count = 1
def fail_high_cve_count = 5
def fail_medium_cve_count = 10
def fail_low_cve_count = 20
def fail_cve_score = 8                       // 累计 CVE 评分 >= 该值时失败
def mask_cve_ids = ""                        // 逗号分隔,如 "CVE-2019-9168,CVE-2019-9169"
def deepfence_key = ""                       // API key,可在 Deepfence 设置页获取
def deepfence_license = ""                   // ThreatMapper 或 ThreatStryker 的 license key
def deepfence_product = ""                   // 产品名:ThreatMapper 或 ThreatStryker

DeepfenceAgent = docker.image("quay.io/deepfenceio/deepfence_package_scanner_cli:2.5.2")
c = DeepfenceAgent.run(
    "-it --net=host --privileged -v /var/run/docker.sock:/var/run/docker.sock:rw",
    "-deepfence-key=${deepfence_key} -console-url=${deepfence_mgmt_console_url} " +
    "-product=${deepfence_product} -license=${deepfence_license} -source=${full_image_name} " +
    "-fail-on-count=${fail_cve_count} -fail-on-critical-count=${fail_critical_cve_count} " +
    "-fail-on-high-count=${fail_high_cve_count} -fail-on-medium-count=${fail_medium_cve_count} " +
    "-fail-on-low-count=${fail_low_cve_count} -fail-on-score=${fail_cve_score} " +
    "-mask-cve-ids='${mask_cve_ids}'")

随后通过 docker logs -f ${c.id} 实时跟踪扫描日志,并用 docker inspect ${c.id} --format='{{.State.ExitCode}}' 读取扫描器退出码后 sh "exit ${out}" 将退出码透传给 Jenkins 流水线——扫描器非零退出即导致构建失败。finally 块保证无论扫描结果如何都会停止容器,避免资源泄漏。

注意漏洞扫描的容器参数与另外两类不同:它需要 --privileged 特权模式,并使用 -source 指定待扫描镜像、-console-url 指定控制台地址、-deepfence-key 传入 API Key、-mask-cve-ids 屏蔽无需阻断的 CVE 列表。

5.2 密钥扫描

secrets.Jenkinsfile 使用 deepfence_secret_scanner:2.5.2 镜像,扫描镜像中是否残留硬编码密钥(如 API Token、密码、私钥等):

def fail_secret_count = 10    // 密钥总数 >= 该值时失败;-1 表示忽略
def fail_high_secret_count = 5
def fail_medium_secret_count = 10
def fail_low_secret_count = 20

c = DeepfenceAgent.run(
    "-it --net=host -v /var/run/docker.sock:/var/run/docker.sock:rw",
    "-product=${deepfence_product} -license=${deepfence_license} -image-name $full_image_name " +
    "-fail-on-count=${fail_secret_count} -fail-on-high-count=${fail_high_secret_count} " +
    "-fail-on-medium-count=${fail_medium_secret_count} -fail-on-low-count=${fail_low_secret_count}")

与漏洞扫描不同,密钥扫描不需要 --privileged,不需要 -console-url / -deepfence-key(本地输出扫描结论并按门禁参数决策),镜像参数使用 -image-name。

5.3 恶意软件扫描

malwares.Jenkinsfile 使用 deepfence_malware_scanner:2.5.2 镜像,检测镜像内是否携带恶意文件:

def fail_malware_count = 10
def fail_high_malware_count = 5
def fail_medium_malware_count = 10
def fail_low_malware_count = 20

c = DeepfenceAgent.run(
    "-it --net=host -v /var/run/docker.sock:/var/run/docker.sock:rw",
    "-product=${deepfence_product} -license=${deepfence_license} -image-name $full_image_name " +
    "-fail-on-count=${fail_malware_count} -fail-on-high-count=${fail_high_malware_count} " +
    "-fail-on-medium-count=${fail_medium_malware_count} -fail-on-low-count=${fail_low_malware_count}")

参数形态与密钥扫描完全一致,仅镜像与阈值变量名不同。两份文件中对 fail_*_count 的注释均说明:当命中数 ≥ 阈值时构建失败,设为 -1 则始终放行。

六、GitHub Actions:最小示例

github-actions 目前提供的是一个最小示例:Dockerfile 基于 python:3.6-slim-stretch 将 index.html 复制到容器内,并执行 python3 -m http.server 8000 提供静态页面服务。仓库中尚未包含完整的 .github/workflows YAML 定义,因此这一子目录更应被理解为"接入 GitHub Actions 的脚手架/参考起点"——你可以参照上文 Jenkins 或 Packer 中的扫描器容器调用方式,在 Actions workflow 的 build 步骤之后、push 步骤之前插入同样的 docker run 扫描步骤,并沿用 fail-on-* 参数实现门禁。从源码结构看,该目录目前只验证了"最小可构建镜像"这一环节。

七、HashiCorp Packer:构建镜像即扫描

hashicorp-packer 将扫描集成进了 Packer 的镜像构建流程,按扫描类型分为三个子目录:malwares/、secrets/、vulnerabilities/,每套都包含一份 docker.pkr.hcl 构建定义与一份 variables.pkr.hcl 变量声明。

7.1 Packer 构建定义(以 vulnerabilities 为例)

vulnerabilities/docker.pkr.hcl 的流程是:基于 debian:latest 启动 Docker 构建器,用 shell provisioner 安装 nginx,通过 docker-tag post-processor 打上 image_name:image_tag 标签,最后用 shell-local post-processor 在宿主机上拉取并运行扫描器:

packer {
  required_plugins {
    docker = {
      version = ">= 0.0.7"
      source  = "github.com/hashicorp/docker"
    }
  }
}

source "docker" "nginx" {
  image  = "debian:latest"
  commit = true
  changes = [
    "ENTRYPOINT nginx -g 'daemon off;'"
  ]
}

build {
  sources = ["source.docker.nginx"]

  provisioner "shell" {
    inline = [
      "apt update && apt install -y nginx",
    ]
  }

  post-processor "docker-tag" {
    repository = "${var.image_name}"
    tags       = ["${var.image_tag}"]
  }

  post-processor "shell-local" {
    inline = [
      "docker pull quay.io/deepfenceio/deepfence_package_scanner_cli:2.5.2",
      "docker run -i --rm --net=host --privileged=true -v /var/run/docker.sock:/var/run/docker.sock:rw " +
      "quay.io/deepfenceio/deepfence_package_scanner_cli:2.5.2 " +
      "-product=${var.deepfence_product} -license=${var.deepfence_license} " +
      "-source ${var.image_name}:${var.image_tag} -console-url=${var.DEEPFENCE_CONSOLE_URL} " +
      "-deepfence-key=${var.DEEPFENCE_KEY} -fail-on-count=${var.FAIL_CVE_COUNT} " +
      "-fail-on-score=${var.FAIL_CVE_SCORE} -fail-on-critical-count ${var.FAIL_CRITICAL_CVE_COUNT} " +
      "-scan-type=\"base,java,python,ruby,php,nodejs,js,dotnet\""
    ]
  }
}

其中 -scan-type="base,java,python,ruby,php,nodejs,js,dotnet" 显式指定了要启用的漏洞扫描语言/组件类型集合,可按镜像实际技术栈裁剪。shell-local 中任意一条命令失败(包括扫描器因门禁阈值返回非零退出码)都会导致整个 Packer 构建失败,从而在镜像交付链路的最前端拦截问题。

恶意软件与密钥扫描的 docker.pkr.hcl 结构相同,区别仅在于镜像与参数:

  • malwares/docker.pkr.hcl:使用 deepfence_malware_scanner_ce:2.5.2,参数为 -image-name + FAIL_MALWARE_COUNT / FAIL_HIGH_MALWARE_COUNT / FAIL_MEDIUM_MALWARE_COUNT / FAIL_LOW_MALWARE_COUNT,并额外加了 --cpus="0.3" 限制 CPU 占用;
  • secrets/docker.pkr.hcl:使用 deepfence_secret_scanner_ce:2.5.2,参数为 -image-name + FAIL_SECRET_COUNT / FAIL_HIGH_SECRET_COUNT / FAIL_MEDIUM_SECRET_COUNT / FAIL_LOW_SECRET_COUNT,同样带 --cpus="0.3"。

7.2 Packer 变量声明与默认值

三份 variables.pkr.hcl 的变量命名与默认值各不相同,整理如下:

vulnerabilities 通用变量(vulnerabilities/variables.pkr.hcl):

变量 默认值 说明
DEEPFENCE_CONSOLE_URL "" 控制台地址,可在 variables.pkrvars.hcl 中覆盖
DEEPFENCE_KEY "" API Key,声明为 sensitive = true
FAIL_CVE_COUNT "100" 漏洞总数门禁
FAIL_CRITICAL_CVE_COUNT "1" Critical 门禁
FAIL_HIGH_CVE_COUNT "5" High 门禁
FAIL_MEDIUM_CVE_COUNT "10" Medium 门禁
FAIL_LOW_CVE_COUNT "20" Low 门禁
FAIL_CVE_SCORE "9" 累计评分门禁
image_name "packer-nginx" 镜像名
image_tag "1.0" 镜像标签
deepfence_license 无默认值 License Key,sensitive = true,必须提供
deepfence_product 无默认值 产品名(ThreatMapper / ThreatStryker),必须提供

malwares 与 secrets 的变量(malwares/variables.pkr.hcl、secrets/variables.pkr.hcl): 与上表结构一致,但以 FAIL_MALWARE_* / FAIL_SECRET_* 替换 FAIL_CVE_* 系列,且不包含 FAIL_CVE_SCORE;FAIL_*_COUNT 默认值均为 "100"(总数)、"5"(High)、"10"(Medium)、"20"(Low)。DEEPFENCE_CONSOLE_URL 与 DEEPFENCE_KEY 仅被漏洞扫描使用,密钥/恶意软件扫描未使用这两个变量。

运行时,可在 variables.pkrvars.hcl 中覆盖上述默认值,敏感变量(DEEPFENCE_KEY、deepfence_license)建议通过环境变量或 CI 系统的 Secret 注入,避免明文落盘。

八、扫描器容器参数速查与运行前提

综合五类集成,扫描器容器的通用运行前提与参数约定如下:

运行前提(三类扫描器通用):

  • 需要访问 Docker socket:-v /var/run/docker.sock:/var/run/docker.sock:rw(宿主机 Docker 守护进程);
  • 网络模式:漏洞扫描使用 --net=host + --privileged;密钥/恶意软件扫描使用 --net=host,无需特权模式(Packer 版本统一加了 --privileged=true,恶意软件与密钥扫描另加 --cpus="0.3");
  • -product(ThreatMapper / ThreatStryker)与 -license(对应 license key)为必填身份参数;
  • 漏洞扫描额外需要 -console-url(管理控制台地址,不带端口)与 -deepfence-key(设置页获取的 API Key),用于将漏洞结果上报控制台;密钥/恶意软件扫描直接输出结论并按门禁参数决策。

参数语义速查:

参数 适用扫描 语义
-source / -image-name 漏洞 / 密钥、恶意软件 指定待扫描镜像(名称:标签)
-fail-on-count 三类 命中总数门禁
-fail-on-critical-count 漏洞 Critical 数量门禁
-fail-on-high-count 三类 High 数量门禁
-fail-on-medium-count 三类 Medium 数量门禁
-fail-on-low-count 三类 Low 数量门禁
-fail-on-score 漏洞 累计 CVE 评分门禁
-mask-cve-ids 漏洞 逗号分隔的 CVE 列表,扫描时屏蔽,不参与门禁
-scan-type 漏洞(Packer 版) 指定扫描组件类型:base,java,python,ruby,php,nodejs,js,dotnet
-console-url / -deepfence-key 漏洞 管理控制台地址 / API Key

所有 fail-on-* 门禁的语义统一为"命中数 ≥ 阈值即失败,-1 表示忽略该维度",这在各平台的 README 与 Jenkinsfile、Packer HCL 注释中均有明确说明。

九、落地实践建议

  1. 门禁阈值分环境:开发/测试流水线可放宽(如 FAIL_CRITICAL_CVE_COUNT=1、FAIL_HIGH_CVE_COUNT=5),生产发布流水线应收紧(Critical/High 设为 0),利用 -1 在试点阶段先观察不阻断;
  2. 密钥与恶意软件扫描优先启用:这两类扫描无需控制台地址与 API Key、无需特权模式,接入成本最低,适合作为第一道防线;
  3. 扫描时机前置:在"构建镜像后、推送 registry 前"扫描,避免不安全镜像流出仓库;Packer 集成则进一步把扫描前置到"镜像生成"本身;
  4. 身份与密钥管理:DEEPFENCE_KEY、deepfence_license 等敏感变量在 CircleCI/GitLab/Jenkins 中一律使用平台 Secret 机制注入,在 Packer 中通过 variables.pkrvars.hcl 覆盖并标记 sensitive = true;
  5. 镜像版本固定:仓库示例统一使用 2.5.2 版本的扫描器镜像,生产环境建议固定 tag(而非 latest)以保证扫描结果可复现,并可依据 Makefile 从源码构建 CE 镜像。

通过上述配置,你可以把 ThreatMapper 的镜像漏洞、密钥与恶意软件检测能力无缝嵌入日常交付流水线,让每一次镜像发布都经过"构建 → 扫描 → 门禁"的强制校验,从源头降低不安全镜像进入运行环境的概率。

登录后查看全文
ThreatMapper