Trivy VEX Repository基于 VEX 仓库的漏洞影响判定与抑制实战指南【免费下载链接】trivyFind vulnerabilities, misconfigurations, secrets, SBOM in containers, Kubernetes, code repositories, clouds and more项目地址: https://gitcode.com/GitHub_Trending/tr/trivyVEXVulnerability Exploitability eXchange漏洞可利用性交换Repository 是 Trivy 提供的一种集中式漏洞抑制机制Trivy 在扫描时为每个发现的软件包生成 PURL并到符合 VEX Repository 规范的仓库中检索匹配的 VEX 文档从而自动判定该漏洞在目标环境中是否真正“受影响”。本文基于 Trivy 当前仓库中的官方文档docs/guide/supply-chain/vex/repo.md展开结合pkg/vex/repo与pkg/commands下的源码实现完整讲解 VEX Repository 的启用、配置、认证、更新、发布与自建托管流程。读完本文你将掌握如何用默认的 VEX Hub 消除扫描噪音、如何配置多仓库优先级、如何为 OSS 或私有项目发布 VEX 文档以及如何搭建企业内部的自定义 VEX 仓库。注意该功能在文档与源码中均被明确标注为EXPERIMENTAL实验性未来可能在不保持向后兼容的情况下变更请在生产环境中谨慎评估。VEX Repository 的核心工作机制VEX Repository 的核心思路是把 VEX 文档从“扫描时手动指定的单个文件”升级为“可集中托管、自动更新、按优先级检索的仓库”。在扫描过程中Trivy 为发现的每一个软件包生成 PURLPackage URL并在 VEX 仓库中检索匹配的 PURL。一旦找到匹配项对应的 VEX 文档就会被采用用于判断该漏洞是否对该包“不受影响”not affected从而决定是否将其从扫描结果中过滤掉。从源码看这一逻辑由 pkg/vex/repo.go 中的RepositorySet.NotAffected实现先从组件标识中取出 PURL然后剔除版本、限定符qualifiers与子路径subpath——因为仓库索引按“包级”而非“版本级”组织对应 VEX Repository 规范中index.json的约定特例是 OCI 制品此时会把repository_url限定符保留下来视作名称的一部分参与匹配随后按配置顺序遍历仓库索引rs.indexes注释明确写着 “In precedence order”命中后打开对应 VEX 文档调用doc.NotAffected判定一旦某个仓库给出了判定就break停止搜索——这印证了后文将要讲到的“仓库优先级”语义。另外OpenDocument在打开文档时使用了os.OpenInRoot(dir, entry.Location)见 pkg/vex/repo.go确保location指向仓库缓存目录之外时不会被打开从实现层面杜绝了外部输入导致的路径穿越风险。启用 VEX Repository--vex repo尽管 VEX Repository 未来计划默认启用但当前版本必须显式指定--vex repo才会激活$ trivy image ghcr.io/aquasecurity/trivy:0.52.0 --vex repo 2024-07-20T11:22:5804:00 INFO [vex] The default repository config has been created file_path/Users/teppei/.trivy/vex/repository.yaml 2024-07-20T11:23:2304:00 INFO [vex] Updating repository... repodefault urlhttps://github.com/aquasecurity/vexhub从标志定义看pkg/flag/vulnerability_flags.go--vex是字符串列表参数可接受三种来源repo本篇文章的仓库模式、oci从 OCI 镜像拉取 VEX以及一个本地文件路径对应 pkg/vex/vex.go 中NewSource的解析逻辑repository与repo互为别名。因此--vex可以多次出现或逗号分隔同时启用多种来源。在配置文件中该参数对应键vulnerability.vex相关的--skip-vex-repo-update则对应vulnerability.skip-vex-repo-update。从扫描调度看pkg/commands/operation/operation.goDownloadVEXRepositories会先检查SkipVEXRepoUpdate再确认--vex repo确实被传入即 VEX 来源中包含TypeRepository之后才会执行仓库下载也就是说不传--vex repo时不会产生任何 VEX 仓库网络请求。配置文件详解默认配置首次执行--vex repo时Trivy 会在$HOME/.trivy/vex/repository.yaml生成默认配置文件home 目录可通过环境变量$XDG_DATA_HOME调整。从实现看pkg/vex/repo/manager.go配置路径实际由fsutils.TrivyHomeDir()决定再拼接vex/repository.yaml。你也可以先用trivy vex repo init提前生成配置文件再手工编辑。默认内容如下repositories: - name: default url: https://github.com/aquasecurity/vexhub enabled: true username: password: token: 默认使用由 Aqua Security 维护的VEX Hubpkg/vex/repo/manager.go 中的常量defaultVEXHubURL即指向它。VEX Hub 主要信任各软件包维护者官方发布的 VEX 文档因此它天然适合“上游已经确认不受影响”的漏洞。需要留意的是配置文件并非一次生成后就不变了Manager.Configpkg/vex/repo/manager.go每次读取时都会校验仓库名filepath.IsLocal(repo.Name)会拒绝../foo、/foo等非本地相对路径的名字——这是为了防止仓库名被拼接到缓存目录后产生路径穿越。查看配置trivy vex repo listtrivy vex repo list可以查看配置文件的路径与已配置的仓库$ trivy vex repo list VEX Repositories (config: /home/username/.trivy/vex/repository.yaml) - Name: default URL: https://github.com/aquasecurity/vexhub Status: Enabled对应的输出逻辑在 pkg/vex/repo/manager.go逐条输出Name、URL、StatusEnabled / Disabled若仓库设置了insecure: true还会追加一行TLS Verify: No。若配置中没有仓库则输出 “No repositories configured.”。自定义仓库如果你想信任其他组织发布的 VEX 文档或使用自己的 VEX 仓库可以添加一个符合 VEX Repository 规范的自定义仓库- name: custom url: https://example.com/custom-repo enabled: trueenabled字段控制该仓库是否参与扫描检索。源码中Config.EnabledRepositories()pkg/vex/repo/manager.go只返回Enabled true的仓库而NewRepositorySetpkg/vex/repo.go也仅加载启用项本地尚未下载的仓库会被跳过并给出 Warn 日志若全部仓库都不可用则返回errNoRepositoryVEX 过滤自动降级为禁用。私有仓库认证对于私有仓库支持两种认证方式username/password用于 Basic 认证token用于 Bearer 认证。- name: custom url: https://example.com/custom-repo enabled: true token: my-token从下载实现看pkg/vex/repo/repo.go这些凭据被封装进downloader.Auth随 manifest 与数据下载请求一起发送。跳过 TLS 验证某些场景如自签名证书的内网仓库需要针对单个仓库跳过 TLS 校验- name: custom url: https://example.com/custom-repo enabled: true insecure: true实现上采用“全局与单仓库取或”的语义Insecure: opts.Insecure || r.Insecure见 pkg/vex/repo/repo.go即命令行全局--insecure或该仓库的insecure: true任一为真即跳过 TLS 校验。仓库优先级VEX 仓库的优先级由配置文件中的出现顺序决定。你可以把自定义仓库放在默认仓库之前以提升优先级也可以直接删掉默认的 VEX Hub- name: repo1 url: https://example.com/repo1 - name: repo2 url: https://example.com/repo2检索流程如下Trivy 先在repo1中查找与软件包 PURL 匹配的 VEX 文档若repo1中没有匹配项再搜索repo2依此类推直到某个仓库命中为止。一旦在任何仓库如repo1找到匹配的 VEX 文档搜索立即停止后续仓库如repo2不会再被检查。最终漏洞状态由第一个命中的 VEX 文档决定例如repo1声明该包“受影响”Affected即使repo2声明同一漏洞“不受影响”Not Affected也会采用repo1的“受影响”结论——高优先级仓库的判定优先。这一行为与源码完全一致pkg/vex/repo.go 中命中索引后立即break且RepositorySet的构造顺序即配置文件顺序。因此在规划多仓库时务必把“最权威、最想优先采信”的仓库放在最前面。仓库更新与缓存管理扫描时自动更新VEX 仓库在扫描期间自动更新更新频率由仓库自身在 manifest 中声明的update_interval决定。具体实现pkg/vex/repo/repo.go仓库缓存根目录下的cache.json记录UpdatedAt上次更新时间与每个 URL 的ETagneedUpdate比较now与UpdatedAt update_interval未到周期则输出 “No need to check repository updates” 并跳过下载时携带上次的 ETag若服务器返回“未变更”则保留旧 ETag 并刷新UpdatedAt避免短期内反复拉取。跳过自动更新在离线或对数据新鲜度不敏感的场景可传--skip-vex-repo-update关闭自动更新$ trivy image ghcr.io/aquasecurity/trivy:0.50.0 --vex repo --skip-vex-repo-update该标志在 pkg/commands/operation/operation.go 中被优先检查命中即直接返回、不发起任何下载。预下载trivy vex repo download想要在扫描前手动拉取仓库例如 CI 预热缓存使用$ trivy vex repo download该子命令还支持按名称定向下载源码见 pkg/commands/app.go 的download [REPO_NAMES]用法过滤逻辑在 pkg/vex/repo/manager.go 的DownloadRepositories中$ trivy vex repo download default若指定的名称不存在或全部为禁用状态会输出 Warn 提示 “No enabled repositories found in config” 并直接返回。清理缓存trivy clean --vex-repo仓库缓存可用以下命令清除对应 pkg/commands/clean/run.go 中的cleanVEXRepositories其底层调用Manager.Clear()删除整个vex缓存目录$ trivy clean --vex-repo清除后下次扫描会重新下载仓库数据。查看被过滤的漏洞--show-suppressed被 VEX 过滤掉的漏洞默认不展示。若想了解“过滤了哪些、为什么”使用--show-suppressed$ trivy image ghcr.io/aquasecurity/trivy:0.50.0 --vex repo --show-suppressed ... Suppressed Vulnerabilities (Total: 4) ┌───────────────┬────────────────┬──────────┬──────────────┬───────────────────────────────────────────────────┬──────────────────────────────────────────┐ │ Library │ Vulnerability │ Severity │ Status │ Statement │ Source │ ├───────────────┼────────────────┼──────────┼──────────────┼───────────────────────────────────────────────────┼──────────────────────────────────────────┤ │ busybox │ CVE-2023-42364 │ MEDIUM │ not_affected │ vulnerable_code_cannot_be_controlled_by_adversary │ VEX Repository: default │ │ │ │ │ │ │ (https://github.com/aquasecurity/vexhub) │ │ ├────────────────┤ │ │ │ │ │ │ CVE-2023-42365 │ │ │ │ │ │ │ │ │ │ │ │ ├───────────────┼────────────────┤ │ │ │ │ │ busybox-binsh │ CVE-2023-42364 │ │ │ │ │ │ │ │ │ │ │ │ │ ├────────────────┤ │ │ │ │ │ │ CVE-2023-42365 │ │ │ │ │ │ │ │ │ │ │ │ └───────────────┴────────────────┴──────────┴──────────────┴───────────────────────────────────────────────────┴──────────────────────────────────────────┘输出中的Source列形如 “VEX Repository: default (仓库 URL)”其拼接逻辑在 pkg/vex/repo.go便于审计某条抑制结论究竟来自哪个仓库。被抑制的漏洞会以ModifiedFindings的形式记录见 pkg/vex/vex.go 中filterVulnerabilities的实现。发布 VEX 文档从源头消除扫描噪音Trivy 尽力减少误报但不做代码图code graph分析因此无法在代码层面评估可利用性。这导致以下两类场景仍可能被报告为漏洞依赖中的漏洞函数在你的项目中从未被调用在你的项目上下文中漏洞代码无法被攻击者控制。如果你确信某个依赖漏洞对你的 OSS 项目或容器镜像没有实际影响可以发布 VEX 文档来降低 Trivy 扫描噪音。可利用性评估有两种方式人工评估作为维护者阅读源码判断漏洞在你的项目上下文中是否可利用自动化评估借助 SAST静态应用安全测试等工具分析代码的可利用性。面向 OSS 项目的发布流程将 VEX 文档发布到源码仓库后Trivy 可以通过 VEX Hub 自动使用它们。主要步骤生成一份 VEX 文档将 VEX 文档提交到源码仓库的.vex/目录Trivy 项目自身即采用此做法其.vex/目录下存放着trivy.openvex.json在 VEX Hub 中注册你项目的 PURL。第 3 步只需执行一次。之后你仓库中 VEX 文件的更新会被 VEX Hub 自动抓取并被 Trivy 自动采用。更详细的操作请参考 VEX Hub 仓库的说明。如果你要为一个不归你维护的 OSS 项目签发 VEX建议先把 VEX 发布提案提交给原仓库——多数 OSS 维护者欢迎这类能改善项目安全态势的贡献。若提案未被接受或你想发布与维护者判断不同的声明则可以自行创建自定义仓库。面向私有项目的方案对于私有软件或个人项目可以按需选择本地 VEX 文件见 本地 VEX 文件创建本地 VEX 文件扫描时让 Trivy 直接读取。适合个人或小团队.trivyignore更简单的场景用.trivyignore文件即可抑制特定漏洞自定义仓库适合需要跨部门共享内部软件 VEX 信息的大型组织见下文。托管自定义仓库原则是“把 OSS 包的 VEX 文档放进源码仓库”但若难以实现也可以自建符合 VEX Repository 规范的自定义仓库。典型使用场景包括向上游提交 VEX 文档的 Pull Request 未被合并汇总 SAST 工具产出的 VEX 文档发布与 OSS 维护者声明不同的厂商特定 VEX建立公司私有的 VEX 仓库统一发布内部软件的共同 VEX。此时你需要创建一个符合 VEX Repository 规范的仓库使其可用于 Trivy。从源码看Trivy 对一个合规仓库的期待是一个 manifest 文件Trivy 从{repo_url}/vex-repository.jsonGitHub 托管时或{repo_url}/.well-known/vex-repository.json非 GitHub 时拉取见 pkg/vex/repo/repo.go 的 URL 拼接逻辑manifest 中声明支持的 spec 版本、数据下载位置与update_interval一个index.json位于缓存目录的0.1/即SchemaVersion子目录下包含updated_at与packages列表每个条目含idPURL、location文档相对路径、format如openvex或csafVEX 文档本身OpenDocument当前支持 OpenVEX 与 CSAF 两种格式其他格式会报 “unsupported VEX format”。版本选择上selectSupportedVersion要求 manifest 中声明的spec_version与 Trivy 的SchemaVersion当前为0.1精确匹配规范到达 1.0 后才会放开为大版本兼容匹配见 pkg/vex/repo/repo.go。小结VEX Repository 把漏洞抑制从“逐文件指定”升级为“集中托管 自动更新 优先级检索”的体系使用侧--vex repo一行启用默认接入 VEX Hubtrivy vex repo init / list / download与trivy clean --vex-repo覆盖配置、预下载与缓存清理全生命周期配置侧通过repository.yaml支持自定义仓库、Basic/Bearer 认证、单仓库跳过 TLS、以及“顺序即优先级”的多仓库裁决规则发布侧OSS 项目走“.vex/目录 VEX Hub 注册 PURL”私有项目可选本地 VEX 文件、.trivyignore或自建合规仓库。由于该特性仍处于实验阶段建议在 CI 或生产链路中先行小范围验证并借助--show-suppressed持续审计过滤结论确保抑制策略符合实际安全预期。【免费下载链接】trivyFind vulnerabilities, misconfigurations, secrets, SBOM in containers, Kubernetes, code repositories, clouds and more项目地址: https://gitcode.com/GitHub_Trending/tr/trivy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考