Skip to content

Harbor 2.16 接 Trivy:装上扫描器,再让高危镜像拉不下来 ​

结论先行: 镜像扫描的价值不在「能看到 CVE 列表」,而在拉取被拦住的那一刻。Harbor 自带 Trivy 集成,装的时候加一个 --with-trivy 就有了扫描器,但默认它只是「能扫」,不会拦;真正形成闸门的是项目配置里的 Prevent vulnerable images from running 加上一个严重度阈值。本文按「装 → 开闸 → 验证 → 排障」走一遍,全部以官方 2.16.0 文档为准。

本文只覆盖 Harbor 单机 + 内置 Trivy 适配器 这条路径。接外部扫描器(Clair、自建 Trivy server)走的是另一套注册流程,不在这里。

1. 装之前,先把 harbor.yml 里三处定死 ​

Harbor 的安装包解开后是 harbor.yml.tmpl,复制成 harbor.yml 再改。必改项只有三个,但每一个都有坑:

yaml
hostname: harbor.example.com        # FQDN,不能写 localhost / 127.0.0.1 / 0.0.0.0
https:
  port: 443
  certificate: /data/cert/harbor.crt
  private_key: /data/cert/harbor.key
harbor_admin_password: <初始密码>    # 只在首次启动生效,之后改了也不认
data_volume: /data

hostname 是 registry 服务对外宣告的地址,写成 localhost 客户端会连不上;Harbor 不自带证书,生产环境必须自备(自签也行,但每台 Docker 客户端都要装 CA),HTTP 只适合断网测试环境。

另有一处可选项是 trivy 块,默认就有,但值得逐项确认:

yaml
trivy:
  ignore_unfixed: false             # true = 只显示有修复版本的漏洞
  security_check: vuln              # vuln / config / secret,逗号分隔可多选
  skip_update: false                # true = 不自动更新 DB,改用离线库
  insecure: false                   # true = 扫描时不校验仓库证书
  db_repository: ghcr.io/aquasecurity/trivy-db   # 漏洞库以 OCI 镜像形式发布

ignore_unfixed 建议保持 false。设为 true 会让「上游还没出补丁」的漏洞整条消失,报表好看,但风险敞口也一起消失了——这类项恰恰是临时缓解措施的输入。security_check 默认只查 vuln,加上 config、secret 才会顺带检查镜像里的配置问题和硬编码凭据,代价是扫描时间变长。

db_repository 这一项值得留意:现代 Trivy 的漏洞库是以 OCI 镜像发布的,Harbor 按这个地址拉库,默认还会先尝试 mirror.gcr.io 再回落到 ghcr.io。这决定了后面排障时该放行哪个域名——不是 GitHub 的网页域名。

2. --with-trivy 要跟着每一次 install.sh ​

官方文档写得很直白:默认安装不包含 Trivy 服务。启用方式是安装时带参数:

bash
sudo ./install.sh --with-trivy

这个参数不是「一次性开关」,而是每次生成配置的输入。install.sh 内部会调用 prepare 按当前参数重新渲染 docker-compose.yml;改完 harbor.yml(比如换证书、改端口)重跑时如果漏掉 --with-trivy,新生成的 compose 文件里就没有 trivy-adapter 服务,扫描器直接消失,UI 上表现为「没有可用的扫描器」。升级、改配置、迁移,重跑命令都要带上它。

装完先做两件确认:

bash
cd /opt/harbor            # 换成实际安装目录
docker compose ps | grep -i trivy        # 应看到 trivy 服务 / trivy-adapter 容器为 running

再登录 UI,进 Administration → Interrogation Services,确认默认扫描器是 Trivy 且状态正常。这一步比 docker ps 更有意义——容器起来但适配器没注册成功的情况是存在的。

3. 项目级三道闸:自动扫、定阈值、拦拉取 ​

扫描器装好只是能力,策略在项目里配。进入 Projects → 选中项目 → Configuration 标签,三个开关按顺序打开:

  1. Automatically scan images on push —— 推送即扫,否则要人工点扫描。
  2. Prevent vulnerable images from running —— 名字说的是 running,实际拦的是 pull,这一点官方在 deployment security 文档里明说了:开启后可以阻止带有漏洞的 artifact 被拉取。所以在 K8s 集群里表现为 ImagePullBackOff,不是启动失败。
  3. 严重度阈值 —— 下拉选项对应漏洞等级,规则是「等级等于或高于所选等级就拦」。

两个必须知道的行为细节,都是官方原文:

  • negligible 等级永不拦截。 即使阈值选到最低,Harbor 也不会因为 negligible 级别的漏洞阻止镜像运行。别指望这一档兜底。
  • OCI image index 不判自身。 多架构镜像(index/manifest list)的策略检查会跳过 index 本身,只对被引用的每个平台 artifact 单独判。所以可能出现「amd64 能拉、arm64 被拦」的情况,这是设计如此,不是 bug。

例外处理靠 CVE 允许列表(项目级或系统级)。用它的前提是写清楚「为什么这个 CVE 在我们的场景下不可达」,否则允许列表半年后就会变成一张没人敢动的白名单。

4. 验证与排障:先看队列,再看 DB ​

验证不要只看 UI 上的数字,用 API 拿结构化结果更可靠。官方给出的导出端点是:

bash
curl -u admin:'<密码>' -s \
  "https://harbor.example.com/api/v2.0/projects/<项目>/repositories/<仓库>/artifacts/<tag>/additions/vulnerabilities" \
  | jq '.vulnerabilities[] | {id, severity, package, version, fixed_version}'

重点看 fixed_version 是否为空:为空说明上游还没补丁,只能靠缓解;不为空说明是升级就能解决的事。

排障按这个顺序走:

  • 扫描一直排队不结束。 先看 Job Service Dashboard 的队列长度,再确认 trivy 服务 / trivy-adapter 容器是否在 running。Trivy 常驻内存不低,小规格机器上适配器反复重启,表现就是任务一直 pending。
  • DB 更新失败。 前面说过漏洞库走 OCI 镜像,默认目标 ghcr.io/aquasecurity/trivy-db(可能先试 mirror.gcr.io)。走代理的环境要按 db_repository 的实际地址放行 ghcr.io 与 pkg-containers.githubusercontent.com;Harbor 文档 proxy 段里列的 github.com、github-releases.githubusercontent.com、*.s3.amazonaws.com 是早期「从 GitHub Release 下载」时代的清单,按现行机制单独放行这三个域名并不够。遇到 429 是镜像仓库侧的限流,和 GitHub REST API 的匿名额度不是一回事。
  • 完全离线。 只设 skip_update: true 不够:skip_java_db_update 默认是 false,Trivy 仍会联网拉 Java 依赖库;要扫 JAR/pom 里的依赖还得再开 offline_scan: true。手工投放时 trivy.db 与 metadata.json 要一起放到容器的 /home/scanner/.cache/trivy/db/(映射到宿主机对应数据目录),缺 metadata.json 会导致库校验失败;Java 库则落在 /home/scanner/.cache/trivy/java-db/trivy-java.db。
  • insecure: true 不是万灵药。 它只跳过扫描时对仓库证书的校验,解决不了拉 DB 出网时的证书问题;后者要单独配自定义 CA。

装完这一套,一个镜像从「推上来」到「能不能被拉下去」就有了明确判据:先自动扫,再按阈值判,最后在 pull 时拦住。剩下的工作是把阈值定在团队能承受的位置——定太严,业务天天提例外;定太松,等于没开。


参考来源

  • Harbor 官方文档 2.16.0:Configure the Harbor YML File、Run the Installer Script、Project Configuration、Vulnerability Scanning、Deployment security
  • Harbor 官方文档:Import Vulnerability Data to an Offline Harbor instance、Configure System-Wide CVE Allowlists
  • Harbor release-2.16.0 仓库中的 make/harbor.yml.tmpl(trivy 块的键名与默认值)
  • Aqua Security, Trivy 文档:DB 配置与 air-gap 离线部署说明

合规提示:本文仅用于授权环境下的私有仓库建设与防御加固,所有配置与命令均面向自有基础设施。

最近更新