
Harbor 集成 Trivy 漏洞扫描实战扫描带漏洞镜像、查看 CVE 详情与重新扫描全流程【免费下载链接】harborAn open source trusted cloud native registry project that stores, signs, and scans content.项目地址: https://gitcode.com/GitHub_Trending/ha/harbor本篇文章以 Harbor 仓库中 Group10-Vulnerability 测试用例 10-02 为骨架完整讲解在启用 Trivy 扫描器的 Harbor 实例上推送带漏洞镜像 → 触发扫描 → 核对 CVE 摘要与详情 → 重新扫描的标准验证流程并结合make/harbor.yml.tmpl、make/photon/trivy-adapter/等源码文件深入解析 Trivy 适配器组件的配置项与底层实现。读完本文你将掌握 Harbor 漏洞扫描功能从环境搭建、镜像扫描到结果核验、重扫的完整实操路径并能读懂 Trivy 相关配置在 Harbor 中的真实作用。一、测试用例背景为什么是 Trivy该测试用例标题为 Trivy scan a image with vulnerability核心目的是验证 Trivy 扫描器能够扫描出镜像中存在的漏洞CVE属于 Harbor 仓库tests/testcases/Group10-Vulnerability/目录下漏洞管理测试组的一部分。它的用途定位是 Harbor 的验收级回归用例只要 Harbor 实例启用了 Trivy任何人都可以按此步骤手动复现漏洞扫描的完整链路从而验证扫描功能是否健康。Trivy 是 Harbor 当前主推的开源镜像漏洞扫描器。从仓库配置可以确认这一点在 make/harbor.yml.tmpl 中Trivy 拥有独立的trivy:配置段且make/photon/prepare/templates/docker_compose/docker-compose.yml.jinja中编排了trivy-adapter服务在 src/common/const.go 中定义了WithTrivy with_trivy与TrivyAdapterURL trivy_adapter_url等常量说明 Harbor 通过配置开关决定是否携带 Trivy 适配器并通过内部 URL 与它通信。需要说明的是用例文件名沿用了早期 Clair 时代的命名10-02-Clair-scan-a-image-with-vulnerability.md但正文与当前 Harbor 版本均以 Trivy 为扫描器主体这是 Harbor 从 Clair 迁移到 Trivy 的历史遗留命名不影响测试语义。二、环境前提跑通扫描链路的最小条件测试用例在 Environment 一节明确列出了 4 项前置条件这也是任何人复现该流程的最低要求Harbor 实例正在运行且可用This test requires that a Harbor instance is running and availableHarbor 以启用 Trivy 的方式安装Harbor is installed with trivy enable一台装有 Docker CLI 的 Linux 主机用于登录 Harbor 并推送镜像Trivy 已更新到最新版本Trivy has been updated to the latest即 Trivy 漏洞数据库可正常拉取更新。关于第 2 点启用 Trivy 有两种典型方式在线安装在harbor.yml中保留默认的trivy:配置段安装脚本make/install.sh与prepare命令会根据配置自动生成 trivy-adapter 容器首次扫描时 Trivy 会自动从默认 OCI 仓库ghcr.io/aquasecurity/trivy-db下载漏洞数据库见 make/harbor.yml.tmpl离线安装在断网环境中需设置skip_update: true并手动将trivy-offline.tar.gz解压出的trivy.db与metadata.json挂载到容器内/home/scanner/.cache/trivy/db路径见 make/harbor.yml.tmpl 的注释说明。三、标准验证流程5 步走通漏洞扫描测试用例给出了 5 个核心步骤下面结合 Harbor 的实际操作界面逐一展开并补充每一步的关键细节。步骤 1以 admin 身份登录 Harbor使用管理员账号登录 Harbor 的 Web 控制台。这是后续创建/使用项目、触发扫描、查看报告的前提。若使用脚本化方式也可通过 Harbor API 登录获取会话。步骤 2推送一个带有漏洞的镜像在装有 Docker CLI 的 Linux 主机上先登录 Harbor再推送一个已知包含历史 CVE 的镜像例如旧版本的基础镜像或刻意保留漏洞的测试镜像docker login harbor_host docker tag vulnerable-image harbor_host/project/image:tag docker push harbor_host/project/image:tag推送完成后在 Harbor Web 控制台进入对应项目即可在仓库 / 制品Repository / Artifact列表中看到该镜像及其标签。镜像是否包含漏洞并不影响推送成功——漏洞检测是推送之后的扫描环节完成的这正体现了 Harbor存储与安全检测解耦的设计。步骤 3触发扫描并观察结果汇总在制品列表页对刚推送的镜像标签执行扫描Scan。扫描完成后列表页与制品详情页会展示结果汇总图表result summary chart通常按漏洞严重级别Critical / High / Medium / Low / Unknown分类统计数量。这是用例 Expected Outcome 中第一条明确要求验证的内容Step3 应存在结果汇总图表result summary chart。该汇总图表的数据来源是 Harbor 的扫描控制器调用 trivy-adapter 完成扫描后写入的扫描报告。在源码层面Harbor 的扫描能力由src/controller/scan/与src/pkg/scan/两个包承载见 src/pkg/scan 目录下的job_test.go、util_test.go等测试扫描任务以 Job 形式下发执行报告结果再回写并展示在前端。步骤 4点击标签进入详情页核对 CVE 链接用例的核心验证点在此步点击镜像标签tag链接进入详情页然后核对详情页展示的漏洞CVE列表应与步骤 3 的汇总图表一致cve link and detail is match with summary in step3每条 CVE 的链接应当可点击cve link should clickable点击后可查看该漏洞的编号、描述、CVSS 评分、受影响的组件版本及修复建议等详细信息。详情页的漏洞明细由 Harbor 前端组件渲染相关界面代码位于 src/portal/src/app/base/project/repository/artifact/artifact-additions 目录下如漏洞详情、SBOM、License 等附加信息视图。这一步同时验证了前端展示与后端报告数据的链路一致性是扫描结果可信度的直接体现。步骤 5重新扫描Rescan在详情页对同一镜像再次触发重新扫描Rescan。用例要求重新扫描必须成功rescan should successful。重新扫描会生成一份新的扫描报告并刷新漏洞结果可用于验证扫描任务能够重复、可靠地执行在 Trivy 漏洞数据库更新后重新扫描可以捕获新披露的 CVE扫描状态与结果的刷新机制正常。四、预期结果清单判定测试是否通过测试用例的 Expected Outcome 部分给出了明确的验收标准归纳如下步骤预期结果验证要点步骤 3存在结果汇总图表扫描完成后界面正常渲染漏洞分级统计步骤 4CVE 链接与步骤 3 汇总一致详情页数据与汇总图表数据吻合步骤 4CVE 链接可点击点击后能查看完整漏洞信息步骤 5重新扫描成功重复扫描任务正常完成并更新结果当以上四点全部满足时即可判定Trivy 扫描带漏洞镜像这一功能验收通过。该用例同时也间接验证了 Harbor 从镜像推送 → 扫描调度 → Trivy 检测 → 报告回写 → 前端展示的整条链路。五、配置深入读懂 harbor.yml 中的 trivy 段要让上述流程稳定跑通理解trivy:配置段是基础。仓库中的 make/harbor.yml.tmpl 提供了带完整注释的模板核心参数如下配置项默认值作用trivy.ignore_unfixedfalse是否只显示已提供修复方案的漏洞设为true时过滤掉未修复unfixed漏洞trivy.skip_updatefalse是否跳过 Trivy DB 下载测试/CI 环境可开启以避免 GitHub 限流开启后需手动挂载离线数据库trivy.skip_java_db_updatefalse是否跳过 Java 数据库trivy-java-db更新trivy.db_repositoryghcr.io/aquasecurity/trivy-db漏洞数据库的 OCI 仓库地址可改为内网镜像仓库trivy.java_db_repositoryghcr.io/aquasecurity/trivy-java-dbJava 漏洞数据库的 OCI 仓库地址trivy.offline_scanfalse离线扫描模式阻止 Trivy 发送 API 请求识别依赖注意它不影响 DB 下载离线环境需同时配合skip_updatetrivy.security_checkvuln检测的安全问题类型可选vuln漏洞、config配置、secret密钥的组合trivy.insecurefalse是否跳过对 registry 证书的校验trivy.timeout5m0s扫描等待时长扫描任务存在 30 分钟上限超过 30m0s 也会在 30 分钟时超时trivy.github_token空GitHub 访问令牌匿名下载限 60 次/小时配置后可将限流提升至 5000 次/小时注模板注释中明确说明 Trivy DB 聚合了 NVD、Red Hat 等上游漏洞库的信息数据库约每 12 小时更新一次并发布新版本Trivy 通过比对数据库内的更新时间戳决定是下载新库还是使用本地缓存。这些harbor.yml参数在运行prepare时会被渲染进 trivy-adapter 的环境变量。渲染模板见 make/photon/prepare/templates/trivy-adapter/env.jinja其中关键映射关系包括SCANNER_TRIVY_VULN_TYPEos,library扫描操作系统与编程语言库两类依赖SCANNER_TRIVY_SEVERITYUNKNOWN,LOW,MEDIUM,HIGH,CRITICAL汇总全部五个严重级别SCANNER_TRIVY_IGNORE_UNFIXED、SCANNER_TRIVY_SKIP_UPDATE、SCANNER_TRIVY_DB_REPOSITORY等均直接对应harbor.yml中的同名配置SCANNER_REDIS_URL/SCANNER_STORE_REDIS_URL/SCANNER_JOB_QUEUE_REDIS_URL适配器通过 Redis 完成扫描任务的存储与队列调度当启用内部 TLS 时internal_tls.enabled还会追加SCANNER_API_SERVER_ADDR:8443及证书路径等 HTTPS 监听配置。六、实现原理trivy-adapter 组件如何工作从源码结构看Trivy 扫描链路由以下部分组成理解它们有助于排查扫描失败问题适配器镜像构建make/photon/trivy-adapter/Dockerfile 将scanner-trivy适配器二进制与trivy二进制一并装入镜像并声明健康检查curl http://localhost:8080/probe/healthyHarbor 据此判断适配器是否存活入口脚本make/photon/trivy-adapter/entrypoint.sh 启动时先执行install_cert.sh安装 Harbor 内部 CA 证书保证与 Harbor Core 之间 TLS 通信可信随后以exec方式启动scanner-trivy二进制来源make/photon/trivy-adapter/builder.sh 展示了适配器二进制的构建方式——从官方 harbor-scanner-trivy 源码仓库克隆指定版本后编译说明 trivy-adapter 实质上是 Harbor 生态中独立的扫描适配器项目Harbor 通过容器化方式集成prepare 生成逻辑make/photon/prepare/utils/trivy_adapter.py 在安装阶段负责创建config/trivy-adapter与data/trivy-adapter/{trivy,reports}目录持久化 Trivy 缓存与扫描报告并渲染 env 配置文件同时 make/photon/prepare/models.py 显示当with_trivy开启时prepare 会要求提供trivy_adapter.crt/trivy_adapter.key证书文件用于内部 TLS。由此可以推断完整调用链用户在 Harbor 前端点击扫描 → Harbor Core 的扫描控制器src/controller/scan创建扫描 Job → Job 通过内部网络调用 trivy-adapter 的 API → 适配器驱动 Trivy 引擎执行漏洞检测 → 报告结果回写数据库 → 前端从报告数据渲染汇总图表与 CVE 列表。测试用例步骤 3、4 所验证的汇总图表与CVE 详情一致正是这条链路的最终输出。七、常见问题与排查建议基于配置与实现以下问题在复现该测试流程时最为常见首次扫描极慢或卡住多为 Trivy 首次下载漏洞数据库所致约数百 MB。可稍候重试生产环境建议预热缓存data/trivy-adapter/trivy目录或配置db_repository指向内网镜像仓库GitHub 限流导致 DB 下载失败匿名下载限 60 次/小时可配置trivy.github_token提升额度离线环境则应启用skip_update并手动挂载trivy.db扫描结果为空但推送正常检查trivy.security_check是否保留了vuln类型确认ignore_unfixed设置是否符合预期重新扫描不生效确认扫描 Job 正常完成且无超时——注意timeout配置与 30 分钟扫描任务上限的关系adapter 健康检查失败可查看trivy-adapter容器日志及/probe/healthy探针结果同时确认 Harbor 内部 CA 证书已正确安装对应install_cert.sh的执行。八、延伸阅读本测试用例原文10-02-Clair-scan-a-image-with-vulnerability.md同目录下更多漏洞管理场景用例tests/testcases/Group10-Vulnerability共 12 个用例覆盖扫描配置、豁免、结果导出等Trivy 配置模板带完整注释make/harbor.yml.tmpltrivy-adapter 构建与运行相关源码make/photon/trivy-adapter/Dockerfile、make/photon/prepare/templates/trivy-adapter/env.jinja、make/photon/prepare/utils/trivy_adapter.py扫描控制器与数据层实现src/controller/scan、src/pkg/scan。【免费下载链接】harborAn open source trusted cloud native registry project that stores, signs, and scans content.项目地址: https://gitcode.com/GitHub_Trending/ha/harbor创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考