Trivy 自托管实战将漏洞数据库、Checks Bundle 与 VEX Hub 搬进内网与离线环境【免费下载链接】trivyFind vulnerabilities, misconfigurations, secrets, SBOM in containers, Kubernetes, code repositories, clouds and more项目地址: https://gitcode.com/GitHub_Trending/tr/trivy导读本文围绕 Trivy 的 self-hosting.md 官方指南展开系统讲解如何把 Trivy 依赖的三种 OCI 数据库trivy-db、trivy-java-db、trivy-checks以及 VEX Hub 完整复制到自有基础设施中使 Trivy 在隔离网络乃至完全离线air-gapped环境中仍能正常工作。读完本文你将掌握三种自托管路径——镜像搬运至私有 Registry、手动填充本地缓存目录、搭建内部 VEX Hub——并理解背后的 OCI 媒体类型、缓存目录结构、仓库解析优先级等底层机制可直接落地到企业内部安全扫描流水线。一、为什么需要自托管Trivy 的外部依赖全景Trivy 二进制只包含扫描引擎本身并不携带漏洞情报等安全数据。真正用于“做出判断”的知识全部来自安装时自动拉取的外部数据库。根据 air-gap.md 的梳理Trivy 在正常工作中依赖如下外部资源外部资源作用场景说明Vulnerability Databasetrivy-db漏洞扫描CVE 信息汇总Java Vulnerability Databasetrivy-java-dbJAR/WAR/PAR/EAR 等 Java 制品识别Java 制品索引与哈希摘要Checks Bundletrivy-checks配置 / IaC 扫描内置 misconfiguration 检查逻辑VEX Hub漏洞豁免判定社区维护的 VEX 文档集合这些资源默认存放在公共容器 Registry 与 GitHub 等公网上。在阻断出网的企业环境或完全隔离的机房里若不预先自托管Trivy 将无法获取安全数据从而无法产出有效结果。需要特别说明的例外Trivy 二进制在构建期会将 Checks Bundle 内嵌进去当外部trivy-checks拉取失败时会自动回退使用随发布版本携带的内嵌检查逻辑。这意味着即使完全不联网你也可以使用当前发布版本对应的 misconfiguration 规则进行扫描只是规则不会更新。这一回退行为在 db.md 与 air-gap.md 中均有说明。二、OCI 数据库自托管镜像搬运方案2.1 哪些数据库被打包为 OCI 镜像三种数据库均以 OCI 镜像形态发布可在仓库内任意一台能访问公网的机器上拉取后转存trivy-db漏洞数据库trivy-java-dbJava 漏洞索引库trivy-checksmisconfiguration 检查规则包官方默认从mirror.gcr.io/aquasec与ghcr.io/aquasecurity两个位置依次拉取相关默认地址定义在 pkg/db/db.go 中trivy-db即ghcr.io/aquasecurity/trivy-db与mirror.gcr.io/aquasec/trivy-db。这些数据库的位置、内容与用途在 数据库文档 中有完整表格说明。2.2 第一步把镜像复制到你的目标 Registry可以使用任意容器 Registry 操作工具如crane、ORAS、regclient将上述三个镜像从公共仓库复制到你的内网 Registry。以crane为例的典型流程是crane cp源地址到目标地址ORAS 用户则对应oras copy。复制完成后你的内部 Registry 中就会出现三个对应的镜像仓库。⚠️ 持续更新提示镜像不是“搬一次就完事”。数据库每周都会发布包含新 CVE 的版本必须在自托管链路中建立周期性的同步任务否则随着时间推移扫描结果会逐渐失真。2.3 第二步把 Trivy 指向内部仓库复制完成后使用 db.md 中描述的“数据库位置”三件套标志覆盖默认仓库地址--db-repository指定trivy-db的 OCI 仓库地址--java-db-repository指定trivy-java-db的 OCI 仓库地址--checks-bundle-repository指定trivy-checks的 OCI 仓库地址示例trivy image \ --db-repository registry.local/sec/trivy-db \ --java-db-repository registry.local/sec/trivy-java-db \ --checks-bundle-repository registry.local/sec/trivy-checks \ nginx:1.25以下实现细节直接影响你在内网如何配置这些参数均可在源码中得到印证多仓库回退--db-repository与--java-db-repository是字符串数组型标志定义见 pkg/flag/db_flags.go可重复传入多个地址。当优先仓库发生瞬时错误如 HTTP 429、5xx时Trivy 会按声明顺序回退到下一个仓库。例如把内部镜像库放在首位、把官方 GHCR 作为兜底trivy image --db-repository my.registry.local/trivy-db --db-repository ghcr.io/aquasecurity/trivy-db alpine。--checks-bundle-repository不支持多仓库回退因为 Checks Bundle 拉取失败时 Trivy 会整体回退到构建期内嵌的检查逻辑相关标志定义见 pkg/flag/misconf_flags.go。覆盖即整体替换设置这些标志会覆盖默认仓库列表。若仍想保留官方仓库作为后备必须把它们显式写进参数列表中。默认 Tag 的隐藏逻辑从源码parseRepository见 pkg/flag/db_flags.go可以看到当指定仓库地址不带镜像 tag时Trivy 会自动补齐数据库 schema 版本号如trivy-db:2而非latest以兼容旧版本 Trivy。因此在你镜像同步脚本里务必同步带 schema 版本号 tag的镜像。2.4 私有 Registry 认证如果你的内部 Registry 需要登录认证按 私有 Registry 认证文档 描述的方式配置即可包括使用 Docker 凭证、--registry-*系列标志或指定认证配置文件等方式让 Trivy 在拉取自托管数据库时能通过鉴权。2.5 注意 OCI 媒体类型Media TypeTrivy 的数据库镜像不是标准容器镜像其 layer 的媒体类型是 Trivy/Aqua 自定义的。当你在内网搭建镜像代理、透明缓存或做镜像搬运/改写时必须保证这些自定义媒体类型被原样保留否则 Trivy 无法识别数据库内容DBMedia Typetrivy-dbapplication/vnd.aquasec.trivy.db.layer.v1.targziptrivy-java-dbapplication/vnd.aquasec.trivy.javadb.layer.v1.targziptrivy-checksapplication/vnd.oci.image.manifest.v1json如果你的镜像代理工具会对未知媒体类型进行改写或剥离例如某些安全扫描中间件需要将其加入白名单确保 Trivy 客户端能按 OCI Distribution 规范正常拉取。三、手动填充缓存方案不依赖私有 Registry如果你不想维护私有镜像仓库还可以采用“下载数据库文件 → 直接写入本地缓存目录”的方式。Trivy 使用本地缓存目录存放数据库文件缓存机制详见 cache.md因此只要把数据库文件“外科手术式”地放进正确的缓存子目录Trivy 就能离线命中缓存完全绕开网络拉取。3.1 第一步在有网机器上下载 DB 文件在任意能访问公网的机器上把数据库容器归档拉到本地工作目录以下命令都作用于当前工作目录方式 A使用 ORAS也可用其他 Registry 操作工具oras pull ghcr.io/aquasecurity/trivy-db:2拉取成功后当前目录会出现db.tar.gz解压后即为 DB 文件tar -xzf db.tar.gz方式 B直接用 Trivy 自己拉取利用--cache-dir .让 Trivy 把数据库文件下载到当前目录配合--download-db-only让它“只更新数据库、不做任何镜像扫描”trivy image --cache-dir . --download-db-only两种方式完成后你都会得到两个文件metadata.json与trivy.db。把它们拷贝到离线/隔离环境。结合 pkg/commands/artifact/run.go 的initDB/initJavaDB实现可以看到--download-db-only对应db.download-only配置项触发下载后即返回一个 “SkipScan” 信号跳过扫描而--download-java-db-only对 Java 数据库执行同样的“只更新不扫描”逻辑。同时源码中还有互斥校验--download-db-only与--skip-db-update、--download-java-db-only与--skip-java-db-update不能同时出现见 pkg/flag/db_flags.go。3.2 第二步填充 Trivy 缓存目录先确认离线机器的缓存目录位置。若 Trivy 使用默认位置可通过帮助信息中的 cache 字样定位trivy -h | grep cache下文假设缓存目录位置保存在环境变量中此处为示例值请按实际输出替换TRIVY_CACHE_DIR/home/user/.cache/trivy把 DB 文件放进缓存目录下的db子目录# 确保缓存 db 目录存在 mkdir -p ${TRIVY_CACHE_DIR}/db # 拷贝 db 文件 cp /path/to/trivy.db /path/to/metadata.json ${TRIVY_CACHE_DIR}/db/完成后再运行trivy image 镜像时只要不传--skip-db-update之外的更新参数Trivy 会命中该缓存在彻底离线环境建议配合--skip-db-update --skip-java-db-update --skip-check-update明确禁止一切在线更新尝试。3.3 Java DB 的适配差异Java 数据库的搬运流程完全一致只有四处不同镜像地址是ghcr.io/aquasecurity/trivy-java-db:1归档文件名是javadb.tar.gzDB 文件名是trivy-java.db与metadata.json缓存子目录是java-db而非db。mkdir -p ${TRIVY_CACHE_DIR}/java-db cp /path/to/trivy-java.db /path/to/metadata.json ${TRIVY_CACHE_DIR}/java-db/3.4 顺带一提缓存目录里还放了什么按 cache.md 的说明Trivy 的缓存目录包含扫描缓存Scan Cache、漏洞数据库、Java 索引库、misconfiguration 检查规则以及 VEX 仓库等。如果你在企业里统一管理多台机器的缓存也可以把数据库更新做成“中央缓存”再用--cache-dir指向共享目录或改用 Redis 缓存后端共享扫描结果。清理缓存时使用trivy clean例如trivy clean --vuln-db --java-db--all清空全部缓存具体组件选项参见 pkg/flag/clean_flags.go 与 db.md。四、VEX Hub 自托管内部 HTTP 服务器方案VEX漏洞利用性交换机制让 Trivy 能依据社区与维护者发布的 VEX 文档自动判定漏洞是否影响你的制品从而过滤误报。VEX Hub 是 Aqua Security 维护的默认 VEX 仓库Trivy 通过 HTTPS 直接抓取其 GitHub 仓库内容。在隔离网络中同样可以把它搬进内网。4.1 第一步在内网制作 VEX Hub 副本下载 VEX Hub 的仓库归档zip 格式与仓库清单文件vex-repository.json——归档提供全部 VEX 数据清单文件则描述了仓库结构及各数据源位置在内网准备或指定一台可被 Trivy 访问的 HTTP 服务器例如https://server.local将下载的归档文件挂到该服务器上供下载例如使https://server.local/main.zip可访问修改清单文件中对应归档的Location URL 字段指向你内网服务器上的归档地址即把url:改为https://server.local/main.zip之类的内部地址将修改后的清单文件放到服务器的/.well-known路径下对外提供例如https://server.local/.well-known/vex-repository.json。关于第 5 步“为什么是/.well-known/”可以在 pkg/vex/repo/repo.go 的实现里找到依据Trivy 下载仓库元数据时如果配置的 URL 路径不以vex-repository.json结尾就会自动在该路径的/.well-known/子路径下拼装清单文件地址再去拉取。也就是说VEX 仓库根 URL如https://server.local与清单的物理位置之间正是通过/.well-known/vex-repository.json约定建立映射的。4.2 第二步配置 Trivy 使用本地 VEX 仓库VEX 仓库通过--vex repo启用VEX 使用方式详见 VEX Repository 文档其配置以 YAML 文件维护先运行trivy vex repo init生成并定位VEX 配置文件默认位于$HOME/.trivy/vex/repository.yaml把默认的 VEX Hub 条目设为enabled: false以禁用对外网仓库的访问新增一个指向内网服务器的自定义仓库条目url填你的内部地址如https://server.local。默认与自定义配置的对照形如repositories: - name: default url: https://github.com/aquasecurity/vexhub enabled: false # 禁用默认的公共 VEX Hub - name: internal url: https://server.local # 指向内网自托管的 VEX Hub enabled: true关于自定义仓库的完整字段username/passwordBasic 认证、tokenBearer 认证、insecure跳过 TLS 校验、仓库按配置文件中的先后顺序决定优先级等可参考 VEX Repository 文档 的“Custom Repositories”与“Authentication”小节。4.3 认证与维护若你的内部服务器需要认证按 VEX Repository 文档 中的说明在仓库条目里配置凭据即可。维护要点VEX 仓库在扫描过程中会按仓库声明的更新频率自动更新离线环境下可加--skip-vex-repo-update禁用自动更新或提前用trivy vex repo download下载好仓库内容缓存清理用trivy clean --vex-repo。这些子命令在 repo.md 中有对应说明。五、离线扫描的整体配合与验收建议自托管数据库与 VEX Hub 只是离线化的一半另一半是让 Trivy 在扫描时彻底“闭嘴出网”。结合 air-gap.md 的建议建议在完全隔离环境统一使用trivy image \ --db-repository registry.local/sec/trivy-db \ --java-db-repository registry.local/sec/trivy-java-db \ --checks-bundle-repository registry.local/sec/trivy-checks \ --skip-db-update --skip-java-db-update --skip-check-update \ --offline-scan \ --skip-vex-repo-update \ nginx:1.25其中--offline-scan用于阻止 Trivy 为识别 Java 包而连接 Maven Central 等远程仓库--skip-version-check与--disable-telemetry可阻止 Trivy 访问check.trivy.dev的更新检查与遥测通道。落地时建议按以下顺序验收在内网机器上执行trivy image --download-db-only配合--db-repository确认能从自托管 Registry 正常拉取检查缓存目录是否生成db/trivy.db与java-db/trivy-java.db执行一次真实镜像扫描确认漏洞、misconfiguration 与 VEX 结果符合预期可用--show-suppressed核对被 VEX 过滤项相关输出示例见 repo.md为数据库与 VEX Hub 归档建立定期同步的自动化任务保证离线环境的安全情报不落后。六、总结三种自托管路径的取舍方案适用场景关键要点OCI 镜像搬运到私有 Registry已有内部 Registry 基础设施用--db-repository等三标志指路注意自定义媒体类型不被改写无 tag 时自动补齐 schema 版本号手动填充本地缓存无 Registry、机器数量少的离线环境有网机器oras pull/trivy image --cache-dir . --download-db-only下载拷入${TRIVY_CACHE_DIR}/db与java-db自托管 VEX Hub需要离线使用 VEX 豁免能力归档 改写后的清单放内网 HTTP 服务器配置文件中禁用默认仓库并新增自定义仓库三条路径都以 db.md数据库种类与配置、cache.md缓存目录结构、air-gap.md整体连通性方案为前置知识基础并与 VEX Repository 文档 相互印证。理解这套“数据离线、引擎本地”的部署模型后你可以把 Trivy 安全地嵌入任何网络受限的企业环境中同时保持漏洞情报与检查规则的持续更新能力。【免费下载链接】trivyFind vulnerabilities, misconfigurations, secrets, SBOM in containers, Kubernetes, code repositories, clouds and more项目地址: https://gitcode.com/GitHub_Trending/tr/trivy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
