★ FEATURED ARTICLE Harbor 镜像推送自动扫描Scan on Push实战指南基于 Trivy 的漏洞检测配置与原理解析【免费下载链接】harborAn open source trusted cloud native registry project that stores, signs, and scans content.项目地址: https://gitcode.com/GitHub_Trending/ha/harbor导读本文围绕 Harbor 的推送时自动扫描Scan Image on Push / Auto Scan能力展开以官方测试用例 Test-10-12-Scan-image-on-push.md 为主线完整复现创建项目 → 开启自动扫描 → 推送镜像 → 触发 Trivy 漏洞扫描的端到端流程并结合仓库源码剖析其事件驱动实现原理。读完本文你将掌握在 Harbor 中配置按需自动扫描的完整操作步骤、验证方法以及该功能从镜像推送事件到扫描任务落地的底层调用链。一、功能背景为什么需要推送即扫描容器镜像在进入运行时环境之前完成漏洞扫描是云原生安全左移Shift Left的关键一环。Harbor 作为开源可信云原生制品仓库内置了与 Trivy 扫描器的深度集成当项目开启自动扫描策略后任何新推送到该项目的镜像都会在不依赖人工触发的情况下自动发起漏洞扫描扫描结果会展示在制品详情与漏洞列表中。该用例属于 Group10-Vulnerability 测试组专门用于验证以下行为事实当镜像被推送时Trivy 能够自动对镜像进行扫描。对应实现上Harbor 通过auto_scan项目元数据Project Metadata来控制这一策略项目级开关默认关闭需要显式开启。二、环境准备Prerequisites依据原测试用例的 Environment 章节在复现前需要满足以下条件条件说明运行中的 Harbor 实例测试要求 Harbor 实例正在运行且可访问Trivy 扫描器已启用Harbor 需以启用 Trivy 的方式安装部署Docker CLI 客户端一台装有 Docker CLI 的 Linux 主机用于执行docker login/docker pushTrivy 适配器确保扫描器组件可用并保持最新保证漏洞库与扫描能力正常在仓库中Trivy 适配器位于 make/photon/trivy-adapter其构建与部署由 make/photon/Makefile 驱动。若尚未启用 Trivy需要在安装 Harbor 时在 harbor.yml.tmpl 中配置trivy相关参数并重启相关服务。提示本用例仅验证自动扫描功能本身未涉及漏洞库更新频率、代理配置等周边选项生产环境中建议同时关注 Trivy 离线/在线漏洞库同步策略。三、测试步骤全解从登录到推送原用例的 Test Steps 只有 5 个步骤下面逐一展开为可直接执行的完整操作流程。步骤 1以 admin 身份登录 Harbor通过 Web 控制台访问 Harbor 地址使用管理员账号登录在命令行侧同时用 Docker CLI 完成 registry 登录docker login harbor-host:port # 输入 admin 用户名与密码步骤 2创建一个新项目进入 Harbor Web UI点击New Project创建项目。项目创建后会立即生成对应的项目元数据记录其中就包括后续要修改的auto_scan键。步骤 3进入项目配置页面在项目列表中点击进入刚创建的项目找到Configuration项目配置标签页。此处展示的正是 project-policy-config.component.html 所渲染的策略配置界面。步骤 4开启自动扫描Automatically Scan Images On Push在项目配置页的Vulnerability漏洞区域勾选Automatically scan images on push复选框并保存。该复选框对应前端模型中projectPolicy.ScanImgOnPush字段其 HTML 实现位于 project-policy-config.component.htmlidscan-image-on-push-wrapper保存时通过项目元数据接口将开关写入后端。步骤 5推送一个此前未扫描过的镜像在装有 Docker CLI 的 Linux 主机上执行# 1. 为本机镜像打上 Harbor 项目标签 docker tag local-image:tag harbor-host:port/project-name/image:tag # 2. 推送镜像 docker push harbor-host:port/project-name/image:tag推送成功后Harbor 会捕获到制品推送事件并自动触发扫描无需在界面上手动点击Scan。四、预期结果与验证方式原用例的 Expected Outcome 明确要求步骤 5 中推送的镜像应被自动扫描。实际验证时可以从两个维度确认Web 界面在项目的仓库列表中查看该镜像的状态扫描完成后状态从Not scanned变为已扫描并展示漏洞总数Critical / High / Medium / Low / Unknown 分级点击镜像可进入漏洞详情页。后台任务通过项目页的Scan任务记录或审计日志可以看到由推送事件自动发起的扫描执行记录区别于人工点击触发的记录。五、原理纵深自动扫描的底层实现调用链自动扫描并非简单的推送后立即扫描而是基于 Harbor 的事件总线与扫描控制器协同完成。以下全部依据来自当前仓库源码。5.1 开关的存储auto_scan项目元数据自动扫描开关以项目元数据形式持久化键名定义为auto_scan键定义见 src/pkg/project/models/pro_meta.goProMetaAutoScan auto_scan。读取逻辑见 src/pkg/project/models/project.go 中的AutoScan()方法从项目元数据中取出auto_scan的值未设置时默认返回false即自动扫描默认不开启。该元数据键同时被列入可更新的项目元数据白名单见 src/server/v2.0/handler/project_metadata.go因此 Web UI 与 API 都能安全地读写该开关。5.2 事件驱动推送事件如何被捕获镜像推送完成后Harbor 会发布制品推送事件。事件元数据的组装位于 src/controller/event/metadata/artifact.goPushArtifactEventMetadata.Resolve()将制品信息封装为PushArtifactEvent并设置事件 Topic 为TopicPushArtifact同时记录操作者Operator与触发时的标签。事件最终被分发到 src/controller/event/handler/internal/artifact.go 中的ArtifactEventHandler.Handle()该方法按事件类型分派——*event.PushArtifactEvent进入onPushPullArtifactEvent进入onPullDeleteArtifactEvent进入onDelete。5.3 自动扫描的核心onPush→autoScanonPush在后台 goroutine 中执行自动扫描与 SBOM 生成逻辑src/controller/event/handler/internal/artifact.go将操作者写入上下文后续审计需要调用autoScan(ctx, artifact, tags...)随后调用autoGenSBOM自动生成 SBOM属于 2.x 新增能力。autoScan的实现位于 src/controller/event/handler/internal/util.go关键逻辑为通过project.Ctl.Get获取制品所属项目调用proj.AutoScan()判断项目是否开启自动扫描未开启则直接返回 nil不扫描在orm.WithTransaction事务中调用scan.DefaultController.Scan(ctx, a, options...)若推送带有标签则追加scan.WithTag(tags[0])与scan.WithFromEvent(true)两个选项——前者指定扫描锚点标签后者标记本次扫描由事件触发便于后续状态追踪。对应单元测试见 src/controller/event/handler/internal/artifact_test.go 的TestOnPush其中构造了PushArtifactEvent并断言onPush返回 nil验证了推送事件处理入口的稳定性。5.4 扫描执行扫描控制器与 Trivy 适配scan.DefaultController.Scan是扫描任务调度的统一入口对应 src/controller/scan 与 src/pkg/scan 包。它会基于项目配置的扫描器默认 Trivy创建扫描任务由 jobservice 异步执行最终结果写入扫描报告Scan Report供 UI 与 API 查询。从依赖结构可以推断完整的链路为docker push → PushArtifactEventMetadata.Resolve() // 组装推送事件 → ArtifactEventHandler.Handle() // 事件分发 → onPush() // 异步处理 → autoScan() // 校验 auto_scan 元数据 → scan.DefaultController.Scan() // 提交扫描任务 → Trivy 适配器执行漏洞检测 // make/photon/trivy-adapter → 扫描报告入库UI 展示结果六、与其他漏洞策略的配合auto_scan通常与以下项目元数据配合形成完整的安全闭环定义均见 src/pkg/project/models/pro_meta.go元数据键常量名作用auto_scanProMetaAutoScan推送时自动扫描prevent_vulProMetaPreventVul禁止拉取存在漏洞的镜像结合severity阈值severityProMetaSeverity触发阻断的最低漏洞严重级别reuse_sys_cve_allowlistProMetaReuseSysCVEAllowlist是否复用系统级 CVE 白名单默认开启auto_sbom_generationProMetaAutoSBOMGen推送时自动生成 SBOM在实际生产环境中推荐组合配置自动扫描 严重级别阻断 CVE 白名单使得高危漏洞镜像在进入运行时前即被拦截将自动扫描从发现环节延伸到治理环节。同时可结合 Harbor 的 Webhook 能力在扫描完成后将结果推送到 CI/CD 或安全平台相关事件处理器见 src/controller/event/handler 下的 webhook 与 p2p 目录。七、小结与排障提示本文以官方测试用例 Test-10-12-Scan-image-on-push.md 为骨架完整复现了 Harbor 自动扫描的配置与验证流程并从源码角度梳理了其事件驱动实现配置入口项目 → Configuration → 勾选Automatically scan images on push存储机制auto_scan项目元数据默认关闭触发链路推送事件 →onPush→autoScan→ 扫描控制器 → Trivy验证方式镜像状态由Not scanned变为已扫描并展示漏洞分级结果。若推送后镜像长时间停留在Not scanned可按下述顺序排查确认项目配置页中自动扫描开关确实已保存对应auto_scantrue检查扫描器状态Harbor → Administration → Interrogation Services确认 Trivy 状态为 Healthy查看任务执行记录与日志确认扫描任务是否因扫描器不可用、漏洞库过期等原因失败检查是否误配置了 CVE 白名单或扫描超时策略导致结果未更新。【免费下载链接】harborAn open source trusted cloud native registry project that stores, signs, and scans content.项目地址: https://gitcode.com/GitHub_Trending/ha/harbor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
