企业官网建设流程全解析

Harbor 中 0 依赖包镜像的 Trivy 扫描：为何结果是 Severity: Unknown

【免费下载链接】harborAn open source trusted cloud native registry project that stores, signs, and scans content.项目地址: https://gitcode.com/GitHub_Trending/ha/harbor

导读

本文围绕 Harbor 漏洞扫描测试用例 10-03-Clair-scan-0-package-image.md 展开，讲解在启用 Trivy 的 Harbor 实例中，对一个"零软件包"（0 package）镜像执行漏洞扫描的完整流程、预期结果及其背后的判定原理。读者将掌握如何手动触发单镜像扫描、如何正确解读Severity: Unknown这一结果，以及 Harbor 漏洞严重性分级与聚合规则在源码层面的实现依据。

说明：虽然测试用例文件名沿用了历史命名中的 "Clair" 字样，但用例正文（Purpose 与 Environment 部分）明确写明本用例验证的是Trivy扫描器对 0 package 镜像的扫描结果，本文以 Trivy 为准展开论述。

一、用例定位：为什么要专门测试 0 package 镜像

在 Harbor 的漏洞扫描功能中，并非所有镜像都包含可被扫描器识别的软件包。以hello-world、busybox为代表的一类镜像，其文件系统内不包含任何包管理器（如dpkg、rpm、apk）可识别的软件依赖，Trivy 扫描后得到的是"零个包、零个漏洞"的报告。

本用例 10-03-Clair-scan-0-package-image.md 的目的正是验证这类极端输入下的扫描行为：

• Purpose：验证 Trivy 对一个 0 package 镜像的扫描结果。
• Expected Outcome：扫描结果的总体严重性应为Severity: Unknown。
• Possible Problems：无（该场景不会引发报错或异常）。

从测试设计角度看，该用例属于漏洞扫描测试组 Group10-Vulnerability 中的"边界与异常形态"覆盖，与 10-02-Clair-scan-a-image-with-vulnerability.md（含漏洞镜像）、10-04-Clair-data-not-ready-hint.md（数据未就绪提示）等用例共同构成完整的扫描行为矩阵。

二、环境要求

按照用例 Environment 一节，复现本场景需要以下前提：

其中"Trivy 已启用"对应的配置文件位于 make/harbor.yml.tmpl，其trivy小节给出了完整的可调参数，安装时按需启用即可：

trivy: # ignoreUnfixed The flag to display only fixed vulnerabilities ignore_unfixed: false # skipUpdate The flag to enable or disable Trivy DB downloads from GitHub skip_update: false # skipJavaDBUpdate The flag to enable or disable Trivy Java DB update skip_java_db_update: false # OCI repository to retrieve the trivy vulnerability database from db_repository: ghcr.io/aquasecurity/trivy-db # OCI repository to retrieve the Java trivy vulnerability database from java_db_repository: ghcr.io/aquasecurity/trivy-java-db # The offline_scan option prevents Trivy from sending API requests to identify dependencies. offline_scan: false # Comma-separated list of what security issues to detect. Possible values are `vuln`, `config` and `secret`. Defaults to `vuln`. security_check: vuln # insecure The flag to skip verifying registry certificate insecure: false # timeout The duration to wait for scan completion. timeout: 5m0s # github_token The GitHub access token to download Trivy DB # github_token: xxx

几点关键说明（对应 make/harbor.yml.tmpl 中的注释）：

• timeout默认5m0s，但扫描任务内部存在 30 分钟的上限，因此该值即便大于30m0s也会在 30 分钟处超时；
• skip_update适合测试或 CI/CD 环境，启用后需手动下载trivy-offline.tar.gz，解压出trivy.db与metadata.json并挂载到/home/scanner/.cache/trivy/db；
• 匿名从 GitHub 下载 Trivy DB 受 60 次/小时 的速率限制，生产环境若不够用可配置github_token提升至 5000 次/小时；
• offline_scan只影响依赖识别（例如不联网解析pom.xml的传递依赖），不影响 DB 下载，离线环境需同时配置skip_update与offline_scan。

三、完整测试步骤

步骤 1：以 admin 登录 Harbor

在 Docker CLI 所在主机执行：

docker login <harbor_host>

输入 admin 账号与密码完成登录。Harbor 会将凭据保存在 Docker 的凭据存储中，供后续 push 使用。

步骤 2：创建项目

通过 Harbor Web 控制台（项目 → 新建项目）创建测试项目。项目命名需符合 Harbor 项目名规范，创建后记录项目全名（例如test/zero-pkg中的test即项目名）。

步骤 3：推送 0 package 镜像

选择一个不含软件包的镜像（用例推荐helloworld或busybox）并推送到刚创建的项目：

docker pull busybox:latest docker tag busybox:latest <harbor_host>/<project>/busybox:latest docker push <harbor_host>/<project>/busybox:latest

busybox是典型的 0 package 镜像——其镜像内容不包含dpkg/rpm/apk可枚举的软件包，因此非常适合复现本用例。

步骤 4：扫描该镜像

在 Harbor Web 控制台进入对应项目的仓库页面，选中刚推送的busybox镜像，点击**扫描（Scan）**按钮触发一次手动扫描。扫描以异步任务方式执行，可在任务/日志中观察进度。

四、预期结果与源码级解读：为何是 Severity: Unknown

4.1 用例的预期断言

用例 Expected Outcome 明确要求：步骤 4 的扫描结果应为Severity: Unknown，且整个过程中不应出现任何报错（Possible Problems 为 None）。

4.2 Harbor 的严重性分级体系

Harbor 在 src/pkg/scan/vuln/severity.go 中定义了完整的严重性等级常量：

None Severity = "None" // 无漏洞 Unknown Severity = "Unknown" // 未分配优先级或扫描器无法识别的安全等级 Negligible Severity = "Negligible" // 理论性安全问题 Low Severity = "Low" Medium Severity = "Medium" High Severity = "High" Critical Severity = "Critical" // 默认安装下几乎人人可被利用

其比较逻辑Code()（severity.go）将None与Unknown都映射为0，Negligible为1，依序递增到Critical的5；无法识别的严重性字符串则被赋予99，以确保"未知即从严"的安全保护策略。

4.3 总体严重性的聚合规则

扫描完成后，Harbor 依据漏洞条目列表计算总体严重性，核心实现在 src/pkg/scan/vuln/report.go 的GetSeveritySummary：

• 初始severity设为None；
• 遍历所有VulnerabilityItem，逐一统计各严重性级别的计数；
• 每当某个漏洞条目的Code()大于当前聚合值时，将总体严重性提升为该级别（取最大值）；
• 同时统计可修复数量（Fixable，依据FixVersion是否非空）。

因此：当镜像一个漏洞都没有时，循环体不执行，聚合值停留在初始值None——这是"空报告"时总体严重性的第一重含义。

4.4 为何最终落到 Unknown

从源码结构看，Unknown的出现有两类典型路径，结合本用例可以推断：

1. 扫描器未返回可识别的严重性取值：Trivy 对 0 package 镜像返回的报告不含任何漏洞条目，而 Harbor 在汇总/转换报告时，对无法归入标准等级的字段会以Unknown兜底。例如 src/pkg/scan/postprocessors/report_converters.go 中record.PackageType = "Unknown"这类兜底赋值，体现了"识别不到即 Unknown"的通用处理惯例。
2. ParseSeverityVersion3的归一化（severity.go）：CVSS v3.0 标准等级中不存在Negligible，该函数会将其映射为None，而所有无法归入None/Low/Medium/High/Critical的取值统一返回Unknown。也就是说，任何不在标准集合内的严重性字符串最终都会表现为Unknown。

结合两者，对 0 package 镜像而言，扫描结果"没有可枚举的漏洞条目、也没有可识别的严重性等级"，Harbor 的聚合逻辑最终输出Severity: Unknown是符合设计预期的正常行为，而非扫描失败或数据异常。

五、验证与延伸：如何确认扫描行为正确

• 查看漏洞计数：扫描完成后，镜像详情页应展示Critical / High / Medium / Low / None / Unknown / Fixable等分项计数。对 0 package 镜像，漏洞条目相关计数应为 0，而聚合严重性显示Unknown。这些计数字段正是 report_converters.go 中逐一统计并回写数据库（CriticalCnt、HighCnt、MediumCnt、LowCnt、NoneCnt、UnknownCnt、FixableCnt）的产物。
• 对照同组用例：可进一步阅读 10-01-Cliar-can-not-scan-some-images.md（某些镜像无法扫描）、10-02-Clair-scan-a-image-with-vulnerability.md（含漏洞镜像的扫描）与 10-04-Clair-data-not-ready-hint.md（数据未就绪提示），形成对"扫描结果形态"的完整认知。
• 扫描任务的底层入口：手动扫描最终调用 src/controller/scan/base_controller.go 中的Scan方法，该方法负责校验扫描器注册信息、收集待扫描制品并启动扫描任务（launchScanJob，见 base_controller.go），扫描器通过 src/pkg/scan/rest/v1/models.go 中定义的ScanRequest结构体接收制品信息（仓库、Tag、Digest、MIME 类型等）并发起扫描。

六、结论

本用例验证了 Harbor 漏洞扫描对"无软件包镜像"这一边界形态的稳健性：流程上可正常完成登录、建项目、推送与扫描，结果上以Severity: Unknown呈现，且不产生任何报错。通过阅读 severity.go 与 report.go 可以确认，Unknown是 Harbor 对"无可识别漏洞条目/严重性"场景的既定兜底语义，属于设计内行为。实际使用中，若希望进一步减少误报干扰，可结合 make/harbor.yml.tmpl 中 Trivy 的ignore_unfixed、security_check等参数调整扫描口径。

【免费下载链接】harborAn open source trusted cloud native registry project that stores, signs, and scans content.项目地址: https://gitcode.com/GitHub_Trending/ha/harbor