Trivy 离线环境（Air-gapped）部署完全指南：外部依赖清单与受限网络下的配置实践

Trivy 离线环境（Air-gapped）部署完全指南：外部依赖清单与受限网络下的配置实践

【免费下载链接】trivyFind vulnerabilities, misconfigurations, secrets, SBOM in containers, Kubernetes, code repositories, clouds and more项目地址: https://gitcode.com/GitHub_Trending/tr/trivy

在默认情况下，Trivy 运行依赖互联网连通性：漏洞库、Java 漏洞库、Misconfiguration 检查规则包（Checks Bundle）以 OCI 镜像形态存放在公共容器镜像仓库，VEX Hub、Maven 中央仓库、check.trivy.dev等资源也会被按需访问。如果组织对出口流量做了白名单或彻底断网，Trivy 将无法正常工作。本文围绕 docs/guide/advanced/air-gap.md 这一权威文档，系统梳理 Trivy 的完整网络依赖清单、各资源的连接主机与协议要求，并给出在受限网络乃至完全隔离（Air-gapped）环境中配置 Trivy 的可行方案——包括自建数据库仓库、手工回填本地缓存、关闭更新检查与遥测，以及用--offline-scan阻止 Java 依赖的远程识别请求。读完本文，你将能在一个完全不联网的 CI/CD 或生产环境中稳定地跑通镜像、文件系统与 IaC 漏洞扫描。

Trivy 的联网依赖全景

Trivy 的扫描引擎与安全数据是分离的：二进制/镜像只负责执行检测逻辑，而"哪些包存在哪些漏洞"这类安全情报由外部数据库提供。下表来自 air-gap.md，列出了 Trivy 正常运行所依赖的全部外部资源：

外部资源	关联功能	说明
Vulnerability Database（trivy-db）	漏洞扫描	Trivy DB 说明
Java Vulnerability Database（trivy-java-db）	Java 漏洞扫描	Trivy Java DB / JAR 扫描
Checks Bundle（trivy-checks）	Misconfiguration（IaC）扫描	内置检查规则
VEX Hub	VEX 漏洞利用信息	VEX 仓库（Repository）机制
Maven Central / 远程仓库	Java 漏洞扫描中的依赖识别	Java 远程仓库部分

官方文档同时给出了一条重要的前置认知（原文档的 note）：

Trivy 是一个依赖公共免费基础设施的开源项目。在极端负载情况下，当 Trivy 尝试连接外部资源时，你可能会遭遇限流（rate limiting）。

这意味着：即使网络策略允许访问，任何"以公共仓库作为生产依赖"的部署都应预置重试、超时与缓存机制；而在受限网络中，这些连接则必须被显式地重定向或彻底关闭，这正是本文要解决的问题。

OCI 数据库：Vulnerability DB / Java DB / Checks Bundle

Trivy 的三类数据库——trivy-db、trivy-java-db、trivy-checks——被打包为OCI 镜像，存放在公共容器镜像仓库中，客户端按容器镜像的方式拉取。具体打包内容与用途可参考 数据库总览文档。

连接要求

与 OCI Registry 的通信遵循OCI Distribution 规范（即docker pull底层使用的同一套仓库分发协议），因此所有兼容 OCI Distribution 的镜像仓库（Harbor、Nexus、自建 Registry 等）都能成为 Trivy 数据库的宿主。

默认情况下 Trivy 依次尝试从下列公共仓库拉取数据库镜像（顺序即优先级，见 db.md）：

1. mirror.gcr.io/aquasec
2. ghcr.io/aquasecurity

这两个默认仓库涉及的主机如下：

仓库	涉及主机	说明
Google Artifact Registry	mirror.gcr.io、googlecode.l.googleusercontent.com	Google 基础设施的 IP 段
GitHub Container Registry	ghcr.io、pkg-containers.githubusercontent.com	GitHub 基础设施的 IP 段

此外，trivy-db、trivy-java-db与trivy-checks也发布在 Docker Hub（aquasec/trivy-db等）与 AWS ECR（public.ecr.aws/aquasecurity/trivy-db等）等位置，并可通过 Google Container Registry Mirror 之类的 pull-through 缓存仓库间接获取，具体镜像地址见 数据库位置章节。

需要注意的是，当拉取trivy-db/trivy-java-db且未显式指定镜像 tag 时，Trivy 会默认使用数据库 schema 编号（如:2、:1）而不是latesttag，以保证数据库格式与当前 Trivy 版本兼容。

自建仓库（Self-hosting）

既然数据库本质是 OCI 镜像，最自然的隔离网络方案就是：在能联网的一台中转机上把镜像搬运到内网私有仓库，再让 Trivy 指向它。详细操作指南见 自托管文档。整体流程为：

1. 搬运镜像：使用任意容器仓库操作工具（如 crane、ORAS、regclient）把trivy-db、trivy-java-db、trivy-checks复制到内网 Registry。注意这三类镜像的 OCI 层媒体类型并非标准容器镜像类型（如trivy-db为application/vnd.aquasec.trivy.db.layer.v1.tar+gzip），做代理或网关时不要按普通镜像强校验。
2. 配置 Trivy 指向新地址：使用如下数据库位置参数（来自 db.md 的 Database Locations 章节）：
   • --db-repository
   • --java-db-repository
   • --checks-bundle-repository

例如：

trivy image --db-repository registry.gitlab.com/gitlab-org/security-products/dependencies/trivy-db alpine

参数支持多次传入以指定多个备选仓库；当某个仓库发生瞬时错误（如 HTTP 429 或 5xx）时，Trivy 会按传入顺序回退到下一个：

trivy image --db-repository my.registry.local/trivy-db --db-repository registry.gitlab.com/gitlab-org/security-products/dependencies/trivy-db alpine

这里有两个关键细节（文档中的 note）：

• 设置这些参数会覆盖默认的官方仓库位置；如果你想保留默认位置作为兜底，需要把官方地址一并写进参数列表。
• Checks Bundle 的仓库位置不支持多值回退——这是因为 Checks Bundle 拉取失败时，Trivy 会退而使用二进制内置的检查规则（见下文"嵌入式 Checks"小节）。

如果内网仓库需要认证，则按 私有仓库认证文档 配置凭证即可。

数据库管理相关参数

围绕 OCI 数据库，Trivy 在 pkg/flag/db_flags.go 中还定义了一组"跳过更新 / 仅下载 / 清理"的控制参数，在隔离网络场景中尤其常用：

参数	作用
--skip-db-update	跳过拉取/更新漏洞数据库
--skip-java-db-update	跳过拉取/更新 Java 数据库
--skip-check-update	跳过拉取/更新 Checks Bundle
--download-db-only	只下载漏洞数据库、不执行扫描
--download-java-db-only	只下载 Java 数据库、不执行扫描

跳过更新的典型组合：

trivy image --skip-db-update --skip-java-db-update --skip-check-update alpine

--download-db-only这类"仅更新"模式适合在联网机器上预取数据库并回填缓存（详见下文"端到端实操清单"）。清理数据库缓存则使用trivy clean命令，可按--vuln-db、--java-db、--checks-bundle、--scan-cache、-a/--all等参数精确选择删除范围。

嵌入式 Checks：离线环境下的内置兜底

与需要外部下载的漏洞库不同，Checks Bundle 会在构建期（build time）直接嵌入 Trivy 二进制文件内部。因此当外部 Checks Bundle 数据库不可用时，Trivy 会回退使用二进制内置的检查规则。

这带来一个对隔离网络至关重要的结论（来自 air-gap.md）：

即使在完全 air-gapped 的环境中，你仍然可以使用当前所用 Trivy 版本发布时内置的那批检查规则来扫描 Misconfiguration。

换句话说：离线部署下 IaC/配置扫描依然可用，代价是检查规则停留在该 Trivy release 的快照版本，无法增量更新。若需要较新的规则，就必须定期在联网机上把新版本的 Trivy（连同新内嵌规则）搬运进隔离环境，或改为通过自建仓库分发trivy-checks。这也解释了为什么--checks-bundle-repository不需要多仓库回退——内置规则本身就是最终的兜底。

VEX Hub：经 GitHub 直连获取的漏洞利用情报

VEX Hub 用于为扫描结果补充漏洞利用（exploit）相关情报。与数据库镜像不同，VEX Hub 是一个托管在github.com/aquasecurity/vexhub的公开 GitHub 仓库，Trivy 通过简单的 HTTPS 请求直接抓取该仓库内容（不是走 OCI 分发协议）。

连接要求

抓取 VEX Hub 会访问 GitHub 相关服务，已知涉及的主机为：

• api.github.com
• codeload.github.com

若你的网络只放行了ghcr.io等镜像主机而没放行 GitHub API/文件下载域，VEX 相关能力会静默失效，这是排查"离线后扫描结果缺少 VEX 信息"时的重点方向。

自建 VEX Hub

GitHub 域名不可达时，可以把 VEX Hub 复制到内网 HTTP 服务器上自托管，指引见 self-hosting.md 的 VEX Hub 章节。核心步骤包括：下载 VEX Hub 仓库归档、下载其仓库清单文件vex-repository.json、在内网 HTTP 服务器上同时提供归档与位于/.well-known路径下的清单，并把清单中的 Location URL 改指向内网归档地址。随后通过trivy vex repo init生成并修改 VEX 配置文件——禁用默认的官方 VEX Hub repo、添加指向内网服务器 URL 的 自定义 repository。若内网服务器需要认证，按 VEX 仓库认证章节 配置。

Maven Central / 远程仓库与 Java 扫描的离线模式

扫描 Java 应用时，为了在 JAR/WAR 等制品中正确识别包名与版本，Trivy 可能需要调用 Maven Central 或其他远程仓库核对构件哈希。这类识别请求通过 HTTPS 发出，已知会尝试连接的地址包括：

• https://repo.maven.apache.org/maven2

离线模式：--offline-scan

官方文档明确指出：在受限网络环境下没有任何办法利用 Maven Central，但你可以通过--offline-scan参数阻止 Trivy 发起这类连接。命令形如：

trivy image --offline-scan <image>

从源码看，该参数定义于 pkg/flag/scan_flags.go，其语义为"Do not issue API requests to identify dependencies"（不对依赖识别发起 API 请求），对应的配置文件字段为scan.offline，并已被标记为遥测安全（TelemetrySafe，即其取值可以被匿名上报而不会泄露路径等敏感信息）。在实际扫描执行链路中，它被传入离线开关：

Offline: opts.OfflineScan, // pkg/commands/artifact/run.go

因此建议在离线/受限网络环境中统一携带--offline-scan，让 Java 依赖识别只依赖本地已分析出的清单信息，而不是反复去连repo.maven.apache.org等待超时。

check.trivy.dev：版本检查与遥测服务

除上述扫描必需资源外，Trivy 还会通过https://check.trivy.dev域名做两件事（均来自 air-gap.md）：

1. 检查新版本并显示公告（详见 configuration/others.md）
2. 收集匿名的使用遥测（详见 telemetry.md）

与前面的数据库、VEX Hub 不同，该域名的连通完全是可选的，不影响 Trivy 的正常扫描功能。但它是一条"隐形"的出口流量——许多离线部署只封锁了镜像仓库域名，却忘了这条 TLS 探测连接同样会卡在防火墙上（虽然超时后不影响扫描，却会拖慢启动、产生告警噪音）。

必须同时关闭两个开关

要彻底阻止 Trivy 连接check.trivy.dev，必须同时禁用版本检查和遥测收集：

trivy image --skip-version-check --disable-telemetry <image>

这是两个由独立 flag 控制、相互独立的功能——只使用其中一个不足以阻断对该域名的全部连接。底层原因可以从 pkg/notification/notice.go 的实现注释中找到：版本检查与遥测共享同一次 HTTP 请求，其组合逻辑是：

--skip-version-check	--disable-telemetry	行为
开	开	跳过整个请求（Debug: "Version check and telemetry are disabled, skipping request"）
开	关	仍发送请求以投递匿名遥测，但抑制版本检查输出
关	开	执行版本检查，但不携带遥测标识头
关	关	完整执行"版本检查 + 遥测上报"

实现细节还包括：只有当遥测未被禁用时，请求才会附带Trivy-Identifier、Trivy-Command、Trivy-Flags、Trivy-OS、Trivy-Arch等匿名头（用户可控的路径、镜像名等会被打码或省略，详见 telemetry.md）；HTTP 客户端设置了 3 秒超时，失败时仅记录 Debug 日志，不会阻断扫描。因此只有双 flag 齐开才能让RunUpdateCheck在本地直接 return、不发任何请求，这也是 air-gap 场景下网络策略仍可保持全封闭的关键。

端到端实操清单：在完全隔离网络中启用 Trivy

综合 air-gap.md、db.md 与 self-hosting.md，一次完整的离线迁移通常分为"联网制备"与"离线运行"两个阶段：

阶段一：在联网中转机上制备数据

1. 用 Trivy 自身只下载数据库到当前目录（--cache-dir .让文件落盘，--download-db-only表示不扫描）：

trivy image --cache-dir . --download-db-only

得到metadata.json与trivy.db两个文件；Java DB 同理拉取ghcr.io/aquasecurity/trivy-java-db:1得到javadb.tar.gz。

2. 或者用 ORAS 等工具直接拉取数据库 OCI 归档再解包：

oras pull ghcr.io/aquasecurity/trivy-db:2 tar -xzf db.tar.gz

3. 将trivy-db/trivy-java-db/trivy-checks镜像推送到内网 Registry，并把 VEX Hub 归档与清单部署到内网 HTTP 服务器（方法见上文）。

阶段二：离线环境回填缓存

Trivy 把数据库文件缓存在本地缓存目录中（布局说明见 cache.md）。先用trivy -h | grep cache确认默认缓存位置，再把文件放入对应子目录：

TRIVY_CACHE_DIR=/home/user/.cache/trivy mkdir -p ${TRIVY_CACHE_DIR}/db cp /path/to/trivy.db /path/to/metadata.json ${TRIVY_CACHE_DIR}/db/

Java DB 的差别仅在于：归档名为javadb.tar.gz，缓存文件名为trivy-java.db与metadata.json，缓存子目录为java-db。若改用内网 Registry，则设置--db-repository、--java-db-repository、--checks-bundle-repository并配合私有仓库认证。

阶段三：离线运行的完整命令模板

trivy image \ --skip-db-update \ --skip-java-db-update \ --skip-check-update \ --offline-scan \ --skip-version-check \ --disable-telemetry \ <image>

各参数在此场景中的作用可概括为：前三个让 Trivy 不再尝试连接任何 OCI 数据库仓库；--offline-scan阻断 Java 依赖识别对 Maven Central/远程仓库的请求；后两个彻底关停对check.trivy.dev的版本检查与遥测请求。以上参数也可通过环境变量（如TRIVY_SKIP_DB_UPDATE=true）或 trivy.yaml 配置文件 统一固化，便于在整个团队/流水线中复用同一套离线策略。

小结

Trivy 的外部依赖分为四类性质截然不同的资源：走 OCI 分发协议的三类数据库镜像（可通过自建 Registry 无缝替代）、通过 HTTPS 直连 GitHub 的 VEX Hub（需自建 HTTP 仓库或放弃该能力）、Java 扫描依赖识别所需的 Maven Central（用--offline-scan关闭）、以及纯可选但容易遗漏的check.trivy.dev（须双 flag 齐关）。理解这张依赖地图、结合--skip-*系列参数与本地缓存回填，即可在完全无外网的环境中稳定使用 Trivy 执行漏洞、Secret 与 Misconfiguration 扫描——代价仅是安全情报停留在所搬运数据的快照时刻，因此离线环境的维护者需要建立定期"联网制备、离线回填"的更新节奏。

【免费下载链接】trivyFind vulnerabilities, misconfigurations, secrets, SBOM in containers, Kubernetes, code repositories, clouds and more项目地址: https://gitcode.com/GitHub_Trending/tr/trivy