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 Databasetrivy-db漏洞扫描Trivy DB 说明Java Vulnerability Databasetrivy-java-dbJava 漏洞扫描Trivy Java DB / JAR 扫描Checks Bundletrivy-checksMisconfigurationIaC扫描内置检查规则VEX HubVEX 漏洞利用信息VEX 仓库Repository机制Maven Central / 远程仓库Java 漏洞扫描中的依赖识别Java 远程仓库部分官方文档同时给出了一条重要的前置认知原文档的 noteTrivy 是一个依赖公共免费基础设施的开源项目。在极端负载情况下当 Trivy 尝试连接外部资源时你可能会遭遇限流rate limiting。这意味着即使网络策略允许访问任何以公共仓库作为生产依赖的部署都应预置重试、超时与缓存机制而在受限网络中这些连接则必须被显式地重定向或彻底关闭这正是本文要解决的问题。OCI 数据库Vulnerability DB / Java DB / Checks BundleTrivy 的三类数据库——trivy-db、trivy-java-db、trivy-checks——被打包为OCI 镜像存放在公共容器镜像仓库中客户端按容器镜像的方式拉取。具体打包内容与用途可参考 数据库总览文档。连接要求与 OCI Registry 的通信遵循OCI Distribution 规范即docker pull底层使用的同一套仓库分发协议因此所有兼容 OCI Distribution 的镜像仓库Harbor、Nexus、自建 Registry 等都能成为 Trivy 数据库的宿主。默认情况下 Trivy 依次尝试从下列公共仓库拉取数据库镜像顺序即优先级见 db.mdmirror.gcr.io/aquasecghcr.io/aquasecurity这两个默认仓库涉及的主机如下仓库涉及主机说明Google Artifact Registrymirror.gcr.io、googlecode.l.googleusercontent.comGoogle 基础设施的 IP 段GitHub Container Registryghcr.io、pkg-containers.githubusercontent.comGitHub 基础设施的 IP 段此外trivy-db、trivy-java-db与trivy-checks也发布在 Docker Hubaquasec/trivy-db等与 AWS ECRpublic.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 指向它。详细操作指南见 自托管文档。整体流程为搬运镜像使用任意容器仓库操作工具如 crane、ORAS、regclient把trivy-db、trivy-java-db、trivy-checks复制到内网 Registry。注意这三类镜像的 OCI 层媒体类型并非标准容器镜像类型如trivy-db为application/vnd.aquasec.trivy.db.layer.v1.targzip做代理或网关时不要按普通镜像强校验。配置 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.comcodeload.github.com若你的网络只放行了ghcr.io等镜像主机而没放行 GitHub API/文件下载域VEX 相关能力会静默失效这是排查离线后扫描结果缺少 VEX 信息时的重点方向。自建 VEX HubGitHub 域名不可达时可以把 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检查新版本并显示公告详见 configuration/others.md收集匿名的使用遥测详见 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.mdHTTP 客户端设置了 3 秒超时失败时仅记录 Debug 日志不会阻断扫描。因此只有双 flag 齐开才能让RunUpdateCheck在本地直接 return、不发任何请求这也是 air-gap 场景下网络策略仍可保持全封闭的关键。端到端实操清单在完全隔离网络中启用 Trivy综合 air-gap.md、db.md 与 self-hosting.md一次完整的离线迁移通常分为联网制备与离线运行两个阶段阶段一在联网中转机上制备数据用 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。或者用 ORAS 等工具直接拉取数据库 OCI 归档再解包oras pull ghcr.io/aquasecurity/trivy-db:2 tar -xzf db.tar.gz将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_UPDATEtrue或 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考