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 再改。必改项只有三个,但每一个都有坑:
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: /datahostname 是 registry 服务对外宣告的地址,写成 localhost 客户端会连不上;Harbor 不自带证书,生产环境必须自备(自签也行,但每台 Docker 客户端都要装 CA),HTTP 只适合断网测试环境。
另有一处可选项是 trivy 块,默认就有,但值得逐项确认:
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 服务。启用方式是安装时带参数:
sudo ./install.sh --with-trivy这个参数不是「一次性开关」,而是每次生成配置的输入。install.sh 内部会调用 prepare 按当前参数重新渲染 docker-compose.yml;改完 harbor.yml(比如换证书、改端口)重跑时如果漏掉 --with-trivy,新生成的 compose 文件里就没有 trivy-adapter 服务,扫描器直接消失,UI 上表现为「没有可用的扫描器」。升级、改配置、迁移,重跑命令都要带上它。
装完先做两件确认:
cd /opt/harbor # 换成实际安装目录
docker compose ps | grep -i trivy # 应看到 trivy 服务 / trivy-adapter 容器为 running再登录 UI,进 Administration → Interrogation Services,确认默认扫描器是 Trivy 且状态正常。这一步比 docker ps 更有意义——容器起来但适配器没注册成功的情况是存在的。
3. 项目级三道闸:自动扫、定阈值、拦拉取
扫描器装好只是能力,策略在项目里配。进入 Projects → 选中项目 → Configuration 标签,三个开关按顺序打开:
Automatically scan images on push—— 推送即扫,否则要人工点扫描。Prevent vulnerable images from running—— 名字说的是 running,实际拦的是 pull,这一点官方在 deployment security 文档里明说了:开启后可以阻止带有漏洞的 artifact 被拉取。所以在 K8s 集群里表现为ImagePullBackOff,不是启动失败。- 严重度阈值 —— 下拉选项对应漏洞等级,规则是「等级等于或高于所选等级就拦」。
两个必须知道的行为细节,都是官方原文:
negligible等级永不拦截。 即使阈值选到最低,Harbor 也不会因为 negligible 级别的漏洞阻止镜像运行。别指望这一档兜底。- OCI image index 不判自身。 多架构镜像(index/manifest list)的策略检查会跳过 index 本身,只对被引用的每个平台 artifact 单独判。所以可能出现「amd64 能拉、arm64 被拦」的情况,这是设计如此,不是 bug。
例外处理靠 CVE 允许列表(项目级或系统级)。用它的前提是写清楚「为什么这个 CVE 在我们的场景下不可达」,否则允许列表半年后就会变成一张没人敢动的白名单。
4. 验证与排障:先看队列,再看 DB
验证不要只看 UI 上的数字,用 API 拿结构化结果更可靠。官方给出的导出端点是:
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 离线部署说明
合规提示:本文仅用于授权环境下的私有仓库建设与防御加固,所有配置与命令均面向自有基础设施。