# https://github.com/aquasecurity/trivy 项目说明书 生成时间：2026-06-19 03:31:48 UTC ## 目录 - [Trivy 概览与系统架构](#page-overview) - [扫描目标、依赖解析与漏洞检测](#page-scanners) - [运行模式、配置、数据库与故障排查](#page-operations) - [报告输出、SBOM、VEX 与供应链集成](#page-reporting) ## Trivy 概览与系统架构 ### 相关页面 相关主题：[扫描目标、依赖解析与漏洞检测](#page-scanners), [运行模式、配置、数据库与故障排查](#page-operations)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/aquasecurity/trivy/blob/main/README.md) - [helm/trivy/README.md](https://github.com/aquasecurity/trivy/blob/main/helm/trivy/README.md) - [integration/README.md](https://github.com/aquasecurity/trivy/blob/main/integration/README.md) - [examples/module/spring4shell/README.md](https://github.com/aquasecurity/trivy/blob/main/examples/module/spring4shell/README.md) - [brand/readme.md](https://github.com/aquasecurity/trivy/blob/main/brand/readme.md) - [pkg/dependency/parser/nodejs/packagejson/testdata/package.json](https://github.com/aquasecurity/trivy/blob/main/pkg/dependency/parser/nodejs/packagejson/testdata/package.json)
# Trivy 概览与系统架构 ## 项目定位与核心能力 Trivy 是由 [Aqua Security](https://aquasec.com) 维护的一款综合性安全扫描器，覆盖漏洞检测、密钥泄露扫描、IaC 配置审计、软件物料清单（SBOM）生成等能力。它以单一可执行文件或容器镜像形式分发，可在不安装额外代理的情况下直接对容器镜像、本地文件系统、Git 仓库和 Kubernetes 集群等多种目标执行扫描。资料来源：[README.md](https://github.com/aquasecurity/trivy/blob/main/README.md) 项目名 "Trivy" 的发音为：`tri` 读作 **tri**gger，`vy` 读作 en**vy**。资料来源：[README.md](https://github.com/aquasecurity/trivy/blob/main/README.md) 典型使用模式遵循统一的命令行语法： ```bash trivy [--scanners ] ``` 例如： ```bash trivy image python:3.4-alpine trivy fs --scanners vuln,secret,misconfig myproject/ trivy k8s --report summary cluster ``` 资料来源：[README.md](https://github.com/aquasecurity/trivy/blob/main/README.md) ## 系统架构与组件 Trivy 的设计核心是将"扫描目标（Target）"与"扫描器（Scanner）"解耦，使同一执行引擎能够面向不同输入复用同一套检测逻辑。 ```mermaid flowchart LR A["CLI: trivy "] --> B["目标驱动
image / fs / repo / k8s"] B --> C["fanal 分析层
提取 SBOM 与文件"] C --> D["扫描器
vuln / secret / misconfig"] D --> E["本地漏洞库
Trivy DB / Java DB"] D --> F["报告输出
table / json / sarif / ..." ] ``` - **入口**：用户通过 `trivy ` 触发扫描，目标与子命令由 CLI 解析器分发。 - **目标驱动**：分别支持 `image`、`fs`、`rootfs`、`repository`、`k8s` 等多种目标类型，仓库根目录 `pkg/commands/` 与 `pkg/fanal/artifact/` 下的实现分别负责调度与分析。 - **分析层（fanal）**：从镜像层、文件系统或仓库源码中抽取包清单。以 Node.js 为例，`pkg/dependency/parser/nodejs/packagejson` 能够解析标准 `package.json`（含 `dependencies`、`peerDependencies`、`optionalDependencies`、`devDependencies` 等）以及遗留的 `license` 数组结构。资料来源：[pkg/dependency/parser/nodejs/packagejson/testdata/package.json](https://github.com/aquasecurity/trivy/blob/main/pkg/dependency/parser/nodejs/packagejson/testdata/package.json) - **扫描器**：漏洞扫描器（`vuln`）匹配漏洞数据库；密钥扫描器（`secret`）使用正则与熵启发式；配置扫描器（`misconfig`）基于 [Rego](https://www.openpolicyagent.org/docs/latest/#rego) 策略评估。 资料来源：[README.md](https://github.com/aquasecurity/trivy/blob/main/README.md) ## 部署与运行模式 ### 客户端/服务器模式 Trivy 支持 Server/Client 部署：客户端将扫描请求发送至中心服务器，避免在每台主机上重复下载并维护漏洞数据库。Helm Chart 中通过 `trivy.serverToken` 完成客户端与服务器之间的认证。资料来源：[helm/trivy/README.md](https://github.com/aquasecurity/trivy/blob/main/helm/trivy/README.md) 社区曾提议让服务端同时承载 Java DB（[#3560](https://github.com/aquasecurity/trivy/issues/3560)），以进一步降低客户端网络与存储压力。 ### Kubernetes Helm 部署 官方提供独立 Helm Chart： ```bash helm repo add aquasecurity https://aquasecurity.github.io/helm-charts/ helm install my-trivy aquasecurity/trivy ``` 默认监听 `4954` 端口，可通过 `image.tag`、`service.port`、`trivy.gitHubToken` 等参数定制，同时支持通过 `trivy.existingSecret` 注入镜像仓库凭据。资料来源：[helm/trivy/README.md](https://github.com/aquasecurity/trivy/blob/main/helm/trivy/README.md) ### WASM 模块扩展 Trivy 通过 [WebAssembly](https://webassembly.org/) 模块实现可插拔扩展。以 `spring4shell` 模块为例： ```bash GOOS=wasip1 GOARCH=wasm go build -o spring4shell.wasm -buildmode=c-shared spring4shell.go mkdir -p ~/.trivy/modules && cp spring4shell.wasm ~/.trivy/modules ``` 也可通过 `trivy module install ghcr.io/aquasecurity/trivy-module-spring4shell` 一键安装。模块在加载后可读取镜像内文件（例如 Tomcat `RELEASE-NOTES` 与 JDK `release`），并根据检测到的 Java 与 Tomcat 版本调整漏洞严重等级——例如将 CVE-2022-22965 在受保护的 JDK 8 环境下从 CRITICAL 调整为 LOW。资料来源：[examples/module/spring4shell/README.md](https://github.com/aquasecurity/trivy/blob/main/examples/module/spring4shell/README.md) ## 报告输出与集成 Trivy 内置多种报告格式（`table`、`json`、`sarif`、`template` 等），可在 CI/CD 与 GitOps 场景中直接消费。社区曾提出新增 Markdown 模板以便在 PR 检查中直观展示结果（[#3201](https://github.com/aquasecurity/trivy/issues/3201)），并希望在单次运行中同时输出多种报告格式（[#3243](https://github.com/aquasecurity/trivy/issues/3243)）。 目前 Trivy 已在多个主流平台落地： - GitHub Actions：[aquasecurity/trivy-action](https://github.com/aquasecurity/trivy-action) - Kubernetes Operator：[aquasecurity/trivy-operator](https://github.com/aquasecurity/trivy-operator) - VS Code 插件：[aquasecurity/trivy-vscode-extension](https://github.com/aquasecurity/trivy-vscode-extension) 资料来源：[README.md](https://github.com/aquasecurity/trivy/blob/main/README.md) ## 已知问题与社区关注 - **扫描超时**：社区长期跟踪 `trivy image` 偶发的扫描超时问题（[#3421](https://github.com/aquasecurity/trivy/issues/3421)），常见原因包括首次下载漏洞数据库、镜像层数过多或网络受限。 - **操作系统覆盖**：关于支持 Fedora 等发行版的讨论已持续多年（[#121](https://github.com/aquasecurity/trivy/issues/121)），最新发布版 v0.71.1 在 OSPKG 检测器上持续扩展覆盖面。 - **CI 中输出灵活性**：多格式输出与 Markdown 模板的需求仍在持续讨论中。 - **集成测试管理**：项目通过 golden 文件维护集成测试结果，规范要求每个 golden 文件仅由一个测试函数作为"权威来源"更新，其余测试通过 `t.Skipf()` 仅做读取验证，以保证测试稳定性。资料来源：[integration/README.md](https://github.com/aquasecurity/trivy/blob/main/integration/README.md) ## See Also - [Trivy 官方文档](https://trivy.dev/docs/latest/) - [Helm Chart 仓库](https://github.com/aquasecurity/helm-charts) - [Trivy Operator](https://github.com/aquasecurity/trivy-operator) - [WASM 模块开发指南](https://trivy.dev/docs/latest/extension/module/) - [扫描覆盖率说明](https://trivy.dev/docs/latest/coverage/) --- ## 扫描目标、依赖解析与漏洞检测 ### 相关页面 相关主题：[Trivy 概览与系统架构](#page-overview), [报告输出、SBOM、VEX 与供应链集成](#page-reporting)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/aquasecurity/trivy/blob/main/README.md) - [pkg/dependency/parser/nodejs/packagejson/testdata/package.json](https://github.com/aquasecurity/trivy/blob/main/pkg/dependency/parser/nodejs/packagejson/testdata/package.json) - [pkg/dependency/parser/nodejs/packagejson/testdata/legacy_package.json](https://github.com/aquasecurity/trivy/blob/main/pkg/dependency/parser/nodejs/packagejson/testdata/legacy_package.json) - [pkg/dependency/parser/nodejs/packagejson/testdata/legacy_array_package.json](https://github.com/aquasecurity/trivy/blob/main/pkg/dependency/parser/nodejs/packagejson/testdata/legacy_array_package.json) - [pkg/dependency/parser/nodejs/packagejson/testdata/without_name_and_version_package.json](https://github.com/aquasecurity/trivy/blob/main/pkg/dependency/parser/nodejs/packagejson/testdata/without_name_and_version_package.json) - [pkg/fanal/analyzer/language/nodejs/yarn/testdata/happy/package.json](https://github.com/aquasecurity/trivy/blob/main/pkg/fanal/analyzer/language/nodejs/yarn/testdata/happy/package.json) - [pkg/fanal/analyzer/language/nodejs/yarn/testdata/monorepo/packages/package2/package.json](https://github.com/aquasecurity/trivy/blob/main/pkg/fanal/analyzer/language/nodejs/yarn/testdata/monorepo/packages/utils/util1/package.json) - [pkg/fanal/analyzer/language/nodejs/yarn/testdata/monorepo/packages/utils/util1/package.json](https://github.com/aquasecurity/trivy/blob/main/pkg/fanal/analyzer/language/nodejs/yarn/testdata/monorepo/packages/utils/util1/package.json) - [pkg/fanal/analyzer/language/nodejs/yarn/testdata/project-with-workspace-in-subdir/foo/package.json](https://github.com/aquasecurity/trivy/blob/main/pkg/fanal/analyzer/language/nodejs/yarn/testdata/project-with-workspace-in-subdir/foo/package.json) - [pkg/fanal/analyzer/language/nodejs/yarn/testdata/project-with-workspace-in-subdir/foo/bar/generators/package.json](https://github.com/aquasecurity/trivy/blob/main/pkg/fanal/analyzer/language/nodejs/yarn/testdata/project-with-workspace-in-subdir/foo/bar/generators/package.json) - [pkg/dependency/parser/conda/meta/testdata/invalid_package.json](https://github.com/aquasecurity/trivy/blob/main/pkg/dependency/parser/conda/meta/testdata/invalid_package.json) - [examples/module/spring4shell/README.md](https://github.com/aquasecurity/trivy/blob/main/examples/module/spring4shell/README.md) - [pkg/iac/scanners/terraform/parser/resolvers/testdata/terraform-aws-s3-bucket/README.md](https://github.com/aquasecurity/trivy/blob/main/pkg/iac/scanners/terraform/parser/resolvers/testdata/terraform-aws-s3-bucket/README.md) - [pkg/fanal/artifact/local/testdata/misconfig/json/passed/src/test2.json](https://github.com/aquasecurity/trivy/blob/main/pkg/fanal/artifact/local/testdata/misconfig/json/passed/src/test2.json)
# 扫描目标、依赖解析与漏洞检测 ## 概述与扫描目标 Trivy 是一款面向容器镜像、文件系统、IaC 模板、SBOM 与密钥的多用途扫描器，其核心流程可概括为：对输入的"工件（artifact）"执行分析，从各种清单文件与声明式配置中抽取依赖与策略，再与漏洞数据库（Vulnerability DB）或自定义模块规则进行匹配，最终产出报告 资料来源：[README.md](https://github.com/aquasecurity/trivy/blob/main/README.md)。在该流程中，**扫描目标**决定了后续要被激活的分析器组合：Node.js 项目会触发 `package.json`/lockfile 解析器，IaC 工件会触发 Terraform/CloudFormation/Kubernetes 扫描器，而 Java 应用则可能额外加载专用的 SBOM 提取与漏洞模块。 本次所引用的源码主要集中在 Node.js 生态的解析样例与一个自定义漏洞模块样例，集中体现了"清单抽取 → 依赖归一 → 漏洞匹配"这一通用范式。 ## 依赖解析：Node.js 与 Yarn ### 标准字段识别 Trivy 的 Node.js 依赖解析器需要兼容 `package.json` 的多种历史形态与字段集合。现代清单通常同时声明 `dependencies`、`peerDependencies`、`optionalDependencies`、`devDependencies` 等多种依赖键；测试样本中可以看到 `js-tokens` 同时出现在 `dependencies` 与 `optionalDependencies` 中，这要求解析器遍历所有依赖键而非仅处理单一字段 资料来源：[pkg/dependency/parser/nodejs/packagejson/testdata/package.json](https://github.com/aquasecurity/trivy/blob/main/pkg/dependency/parser/nodejs/packagejson/testdata/package.json)。与之相对，"happy path" 测试样本仅含 `dependencies` 与 `devDependencies` 两类声明，代表最常见的扁平结构 资料来源：[pkg/fanal/analyzer/language/nodejs/yarn/testdata/happy/package.json](https://github.com/aquasecurity/trivy/blob/main/pkg/fanal/analyzer/language/nodejs/yarn/testdata/happy/package.json)。 ### Yarn Workspace 与 Monorepo Yarn 工作区与 npm 的 monorepo 结构是项目拆分的常见方式。根清单中通过 `workspaces` 字段引用子目录，例如 `"workspaces": ["bar/*"]` 指向 `bar/generators` 中的独立清单 资料来源：[pkg/fanal/analyzer/language/nodejs/yarn/testdata/project-with-workspace-in-subdir/foo/package.json](https://github.com/aquasecurity/trivy/blob/main/pkg/fanal/analyzer/language/nodejs/yarn/testdata/project-with-workspace-in-subdir/foo/package.json)。子包自身的依赖（如 `hoek: 6.1.3`）也必须被独立识别 资料来源：[pkg/fanal/analyzer/language/nodejs/yarn/testdata/project-with-workspace-in-subdir/foo/bar/generators/package.json](https://github.com/aquasecurity/trivy/blob/main/pkg/fanal/analyzer/language/nodejs/yarn/testdata/project-with-workspace-in-subdir/foo/bar/generators/package.json)。 对于较为复杂的 monorepo，解析器还需区分纯内部桥接包（`"private": true`、仅用于聚合）与具备实际依赖的叶子包；测试样本中的 `packages/package2` 使用 `"private": true` 与 `type: "module"` 进行聚合声明，而 `packages/utils/util1` 则携带可被外部引用的 `dependencies` 与 `devDependencies` 资料来源：[pkg/fanal/analyzer/language/nodejs/yarn/testdata/monorepo/packages/package2/package.json](https://github.com/aquasecurity/trivy/blob/main/pkg/fanal/analyzer/language/nodejs/yarn/testdata/monorepo/packages/package2/package.json)、资料来源：[pkg/fanal/analyzer/language/nodejs/yarn/testdata/monorepo/packages/utils/util1/package.json](https://github.com/aquasecurity/trivy/blob/main/pkg/fanal/analyzer/language/nodejs/yarn/testdata/monorepo/packages/utils/util1/package.json)。 ### 边缘情况与容错 依赖解析器必须容忍缺失字段与异常历史形态。测试样本包含仅有 `"license": "MIT"`、缺少 `name` 与 `version` 的极简清单 资料来源：[pkg/dependency/parser/nodejs/packagejson/testdata/without_name_and_version_package.json](https://github.com/aquasecurity/trivy/blob/main/pkg/dependency/parser/nodejs/packagejson/testdata/without_name_and_version_package.json)；也包含 `license` 字段以对象数组形式出现的旧式写法，承载多许可证声明 资料来源：[pkg/dependency/parser/nodejs/packagejson/testdata/legacy_array_package.json](https://github.com/aquasecurity/trivy/blob/main/pkg/dependency/parser/nodejs/packagejson/testdata/legacy_array_package.json)。许可证对象的存在进一步表明解析器在抽取过程中需要跳过非依赖字段，而非对清单的顶层结构做强校验；类似的容错策略在其他生态中亦有体现，例如 conda 元数据解析器需要处理一个空对象 `{}` 作为"无效清单"用例 资料来源：[pkg/dependency/parser/conda/meta/testdata/invalid_package.json](https://github.com/aquasecurity/trivy/blob/main/pkg/dependency/parser/conda/meta/testdata/invalid_package.json)。 ## 基于模块的漏洞检测 除通用漏洞库匹配外，Trivy 支持通过外部"模块（module）"扩展漏洞检测与严重度修正逻辑。`spring4shell` 示例展示了如何结合运行时信息（Java 版本、Tomcat 版本）对已知 CVE 的等级进行覆写：在 Java 8 + Tomcat 8.5.77 环境下，CVE-2022-22965 的严重度被从 CRITICAL 降级为 LOW 资料来源：[examples/module/spring4shell/README.md](https://github.com/aquasecurity/trivy/blob/main/examples/module/spring4shell/README.md)。这种"通用漏洞库 + 模块二次判定"的组合让用户能够在不修改 Trivy 主程序的前提下，引入上下文敏感的修正规则，从而避免将不适用的告警统一上报为高风险。 下表总结了 `spring4shell` 模块工作流中可观察到的关键信号与作用： | 信号 | 来源 | 用途 | | --- | --- | --- | | Java 版本 | 应用运行时探测 | 判定 CVE-2022-22965 是否命中 | | Tomcat 版本 | 应用运行时探测 | 判定 CVE-2022-22965 是否命中 | | 原漏洞等级 | Vulnerability DB | 模块覆写前的初始值 | | 输出等级 | 模块规则 | 模块覆写后的最终严重度 | ## 已知问题与社区关注点 社区反馈的若干问题与本主题密切相关： - **镜像扫描超时**（Issue #3421）：当 `--security-checks` 被显式限制为 `vuln` 时仍出现整体流程超时，说明 DB 下载、依赖抽取、IaC/密钥扫描之间可能存在资源竞争；建议分别启用 `--security-checks vuln`、`config`、`secret` 以二分定位耗时模块。 - **服务器模式下缺少 Java DB**（Issue #3560）：当前 Java 包检测触发的 Java DB 下载仍由客户端发起，社区期望由 server 端集中托管并向 client 提供，以减少重复下载与磁盘占用。 - **多输出格式与 Markdown 模板**（Issue #3243、Issue #3201）：希望在同一次运行中既输出 UI 报告又写入文件，并支持自定义 Markdown 模板以便在 CI 中以 PR 评论形式审阅。 - **发行版覆盖**（Issue #121）：用户长期关注 Fedora 等发行版的支持，这间接影响 OS 包检测器在仓库 `pkg/detector/ospkg` 路径下的覆盖广度。 ## See Also - 漏洞数据库与服务器模式 - IaC 与 Misconfiguration 扫描 - SBOM 与多格式输出 - 自定义模块与漏洞覆写规则 --- ## 运行模式、配置、数据库与故障排查 ### 相关页面 相关主题：[Trivy 概览与系统架构](#page-overview), [报告输出、SBOM、VEX 与供应链集成](#page-reporting)
相关源码文件 以下源码文件用于生成本页说明： - [pkg/commands/server/run.go](https://github.com/aquasecurity/trivy/blob/main/pkg/commands/server/run.go) - [pkg/db/db.go](https://github.com/aquasecurity/trivy/blob/main/pkg/db/db.go) - [pkg/javadb/client.go](https://github.com/aquasecurity/trivy/blob/main/pkg/javadb/client.go) - [pkg/cache/cache.go](https://github.com/aquasecurity/trivy/blob/main/pkg/cache/cache.go) - [pkg/remote/remote.go](https://github.com/aquasecurity/trivy/blob/main/pkg/remote/remote.go) - [docs/guide/references/troubleshooting.md](https://github.com/aquasecurity/trivy/blob/main/docs/guide/references/troubleshooting.md) - [README.md](https://github.com/aquasecurity/trivy/blob/main/README.md)
# 运行模式、配置、数据库与故障排查 ## 概述 Trivy 是一个覆盖漏洞、配置与敏感信息检测的综合性安全扫描器，其运行涉及客户端/服务端模式选择、本地与远端数据库维护、缓存策略以及大量可调参数。本页面向运维与开发人员，梳理 Trivy 的运行模式、数据库与缓存机制、关键配置项以及社区中常见的故障定位思路，参考了 `README.md` 中给出的安装与生态链接。资料来源：[README.md](https://github.com/aquasecurity/trivy/blob/main/README.md) ## 运行模式 Trivy 主要支持两种运行模式：单机模式（Standalone）与客户端/服务端模式（Client/Server）。单机模式下，所有数据库下载、缓存、扫描执行均在同一台主机完成，适合个人开发与临时性 CI 任务；客户端/服务端模式则将数据库与缓存集中保存在服务端，多个客户端共享同一份更新，减少重复下载与磁盘占用。 ```mermaid graph LR A[CLI 客户端] -- 请求/结果 --> B[Trivy Server] B -- 缓存结果 --> C[(本地缓存层)] A -- 仅元数据 --> C B -- 下载/更新 --> D[(Trivy DB)] B -- 下载/更新 --> E[(Java DB)] D -.可选镜像.--> F[对象存储/S3] E -.可选镜像.--> F ``` 服务进程通过 `trivy server` 命令启动，其入口逻辑位于 [pkg/commands/server/run.go](https://github.com/aquasecurity/trivy/blob/main/pkg/commands/server/run.go)，负责信号注册、tracer 初始化与监听地址绑定。客户端可通过环境变量 `TRIVY_SERVER_URL` 切换为客户端/服务端模式，此时漏洞数据库与缓存均交由服务端统一管理。 ## 数据库与缓存 Trivy 依赖两类漏洞数据库：通用漏洞库 Trivy DB 与 Java 专用库 Java DB，两者的下载、更新与元数据解析由各自模块独立完成。资料来源：[pkg/db/db.go](https://github.com/aquasecurity/trivy/blob/main/pkg/db/db.go) 与 [pkg/javadb/client.go](https://github.com/aquasecurity/trivy/blob/main/pkg/javadb/client.go)。 | 组件 | 源码入口 | 触发条件 | 关键特性 | | --- | --- | --- | --- | | Trivy DB | `pkg/db/db.go` | 任何 OS 包扫描 | 默认源 `ghcr.io/aquasecurity/trivy-db` | | Java DB | `pkg/javadb/client.go` | 检测到 Java 包时 | 体积较大；社区已提出集中化诉求（issue #3560） | | 缓存层 | `pkg/cache/cache.go` | 客户端或服务端共享 | 支持本地文件系统与 Redis | | 远端后端 | `pkg/remote/remote.go` | 客户端无本地 DB 时 | 用于客户端/服务端模式对接 | 缓存与远端后端的抽象使单机模式也能复用 `TRIVY_CACHE_BACKEND` 等参数，按需切换到外部存储。资料来源：[pkg/cache/cache.go](https://github.com/aquasecurity/trivy/blob/main/pkg/cache/cache.go) 与 [pkg/remote/remote.go](https://github.com/aquasecurity/trivy/blob/main/pkg/remote/remote.go)。 ## 关键配置 Trivy 的配置既可通过命令行标志，也可通过 YAML 配置文件或环境变量注入。常见分组包括： - 扫描目标与类型：`--target`、`--scanners`（支持 `vuln`、`misconfig`、`secret`、`license`） - 安全检查范围：`--security-checks vuln,config` - 输出与并发：`--format`、`--output`、`--parallel` - 数据库/缓存：`--db-repository`、`--java-db-repository`、`--cache-dir` - 服务端模式：`TRIVY_SERVER_URL`、`--token`、`--token-header` ## 故障排查 Trivy 输出结构化日志（默认 INFO 级），可通过 `TRIVY_DEBUG` 开启 DEBUG 级以获取数据库下载、镜像层分析等细节。社区高频问题（issue #3421 “trivy image scan suddenly timing out”）显示，扫描偶发超时往往与数据库下载阻塞、镜像元数据抓取缓慢或服务端压力相关；该议题中用户反馈 `--security-checks vuln` 看似未生效，常见原因是被客户端/服务端模式下的服务端策略覆盖，或与输出格式不兼容。资料来源：[docs/guide/references/troubleshooting.md](https://github.com/aquasecurity/trivy/blob/main/docs/guide/references/troubleshooting.md)。 通用排查建议： 1. 启用 DEBUG 日志，定位卡顿发生在数据库下载、镜像拉取还是分析阶段 2. 客户端/服务端模式下确认 `--server` 或 `TRIVY_SERVER_URL` 已生效，避免本地重复下载数据库 3. 调整 `--timeout`、`--parallel` 与网络代理设置 4. 对 Java 项目，将 Java DB 托管至服务端可缓解客户端带宽压力（参考 issue #3560） 5. 在 Air-gapped 环境中，预下载数据库并通过 `--skip-db-update` 与 `--offline-scan` 复用 ## See Also - 扫描器与报告格式 - SBOM 与 IaC 检测 - 模块系统与扩展 --- ## 报告输出、SBOM、VEX 与供应链集成 ### 相关页面 相关主题：[扫描目标、依赖解析与漏洞检测](#page-scanners), [运行模式、配置、数据库与故障排查](#page-operations)
相关源码文件 以下源码文件用于生成本页说明： - [pkg/report/writer.go](https://github.com/aquasecurity/trivy/blob/main/pkg/report/writer.go) - [pkg/report/sarif.go](https://github.com/aquasecurity/trivy/blob/main/pkg/report/sarif.go) - [pkg/report/cyclonedx/cyclonedx.go](https://github.com/aquasecurity/trivy/blob/main/pkg/report/cyclonedx/cyclonedx.go) - [pkg/report/spdx/spdx.go](https://github.com/aquasecurity/trivy/blob/main/pkg/report/spdx/spdx.go) - [pkg/report/template.go](https://github.com/aquasecurity/trivy/blob/main/pkg/report/template.go) - [pkg/sbom/core/bom.go](https://github.com/aquasecurity/trivy/blob/main/pkg/sbom/core/bom.go) - [examples/module/spring4shell/README.md](https://github.com/aquasecurity/trivy/blob/main/examples/module/spring4shell/README.md)
# 报告输出、SBOM、VEX 与供应链集成 ## 概述 Trivy 的报告子系统将扫描结果（漏洞、配置、密钥、SBOM 等）转换为多种行业标准格式，使结果能够直接接入 CI/CD、GitHub Actions、IDE 等下游工具链。该子系统由 `pkg/report` 包统一协调，并配合 `pkg/sbom/core` 提供的统一内部 BOM 数据模型，让一次扫描能够同时输出多种格式的报告。此外，Trivy 通过 VEX 文档和可插拔的扫描模块（如 `spring4shell`）实现漏洞可利用性交换与供应链场景化检测。资料来源：[pkg/report/writer.go]() [pkg/sbom/core/bom.go]() ## 报告输出架构 `pkg/report/writer.go` 充当报告分发的中央调度器，根据用户通过 `--format`（或 `-f`）参数指定的格式枚举值，调用对应格式的 Writer 实现。Trivy 原生支持多种输出格式，包括表格（table）、JSON、SARIF、CycloneDX、SPDX 以及基于 Go template 的自定义模板。 ```mermaid flowchart LR A[扫描引擎
Artifact Scan Result] --> B[统一 Report
pkg/report] B --> C[Writer 分发
writer.go] C --> D1[table] C --> D2[JSON] C --> D3[SARIF
sarif.go] C --> D4[CycloneDX
cyclonedx.go] C --> D5[SPDX
spdx.go] C --> D6[Template
template.go] D3 --> E1[GitHub Code Scanning] D4 --> E2[依赖追踪平台] D5 --> E3[许可证审计] D6 --> E4[PR 评论 / 自定义 UI] ``` ### 关键格式说明 | 格式 | 适用场景 | 核心实现 | |------|---------|----------| | SARIF | GitHub Code Scanning、IDE 集成 | `pkg/report/sarif.go` | | CycloneDX | OWASP 依赖追踪、SBOM 交换 | `pkg/report/cyclonedx/cyclonedx.go` | | SPDX | 许可证合规、Linux 基金会生态 | `pkg/report/spdx/spdx.go` | | Template | 自定义 UI、PR 渲染 | `pkg/report/template.go` | 资料来源：[pkg/report/sarif.go]() [pkg/report/cyclonedx/cyclonedx.go]() [pkg/report/spdx/spdx.go]() [pkg/report/template.go]() 社区反馈显示，用户强烈希望同时输出多种格式（例如既在控制台显示表格，又生成 SARIF 上传到 GitHub）。相关讨论见 Issue #3243「Support multiple outputs in a single run」以及 Issue #3201「Add a Markdown format template」，表明 `template.go` 提供的 Go template 机制是扩展自定义报告的关键入口。 ## SBOM 核心数据模型 所有报告格式都依赖于 `pkg/sbom/core/bom.go` 中定义的统一内部 BOM 模型。该模型将 Trivy 在一次扫描中收集到的组件、依赖关系、属性、漏洞引用等信息抽象为可序列化的结构体，使上层 Writer 无需关心数据来源是容器镜像、文件系统、Git 仓库还是虚拟机镜像。资料来源：[pkg/sbom/core/bom.go]() 通过这种统一抽象，CycloneDX 和 SPDX 两种标准 SBOM 格式能够共享同一份内部数据，只需在各自的实现文件中完成字段映射。例如 CycloneDX 关注组件（component）、依赖（dependency）、属性（property）三要素，而 SPDX 则使用包（package）、关系（relationship）、许可证声明等概念，二者通过 `bom.go` 中的核心结构进行解耦转换。 ## VEX 与漏洞可利用性交换 VEX（Vulnerability Exploitability eXchange）是一种用于声明「漏洞是否实际可被利用」的标准机制。Trivy v0.71.1 的发布说明中包含 `fix(vex): load VEX documents from...` 提交，表明 VEX 文档的加载逻辑已被纳入主分支。VEX 的核心价值在于：当某个 CVE 报告存在但产品配置、运行时环境或缓解措施使其不可利用时，VEX 文档可以显式降低该漏洞的严重程度或将其标记为「not affected」。资料来源：[examples/module/spring4shell/README.md]() `examples/module/spring4shell/README.md` 给出了一个典型的供应链场景示例：扫描器在镜像中检测到 Spring Framework 与 Tomcat 后，会进一步识别 Java 与 Tomcat 的版本组合，并基于此判断 CVE-2022-22965（Spring4Shell）是否真正可利用。模块会将该 CVE 的严重程度从 CRITICAL 调整为 LOW（因为 Java 8 不受影响），这一行为本质上就是「模块化 VEX」——通过插件逻辑动态调整漏洞状态。该模式在 Trivy 中被称为「Trivy Module」，可作为 OCI 镜像分发，便于在企业供应链中复用。资料来源：[examples/module/spring4shell/README.md]() ## 供应链集成与模块化扫描 Trivy 的供应链集成围绕两条主线展开： 1. **SBOM 作为供应链传递物**：通过 CycloneDX 与 SPDX 格式输出，可直接被 Dependency-Track、Grype、Sigstore 等下游工具消费，实现 SBOM 的「一次生成、多处复用」。 2. **Module 机制扩展检测能力**：用户可以编写自定义 Module 镜像，在 Trivy 主程序中加载，对特定供应链场景（如 Spring4Shell、Log4Shell、自研框架漏洞）进行专项判断。Module 通过 OCI 分发，符合云原生供应链标准。 社区中关于「Trivy Java DB as part of server mode」的讨论（Issue #3560）反映出企业用户在中心化部署时，希望服务器端统一管理漏洞数据库与 VEX 策略，避免每个客户端重复下载并产生策略分歧。这一诉求与 SBOM + VEX 的整体设计目标一致——将漏洞数据、SBOM 清单、可利用性声明在供应链中统一治理。 ## 故障排查与最佳实践 - **多格式输出**：如需同时生成表格与 SARIF，可使用 `template.go` 提供的模板机制编写自定义格式，或在 CI 脚本中串行调用多次 Trivy（参考 Issue #3243 的讨论）。 - **模板格式**：当 SARIF 不便在 PR 评论中阅读时，可参考 Issue #3201，使用 Go template 编写 Markdown 模板，通过 `--template` 参数传入。 - **VEX 优先级**：当 VEX 文档与模块判断冲突时，模块的运行时判断通常优先级更高，因为它基于实际的环境检测而非静态声明。 ## See Also - 漏洞检测与数据库管理 - 配置审计与 IaC 扫描 - 容器镜像与文件系统分析器 - Trivy Server / Client 部署模式 资料来源：[pkg/report/writer.go]() [pkg/report/sarif.go]() [pkg/report/cyclonedx/cyclonedx.go]() [pkg/report/spdx/spdx.go]() [pkg/report/template.go]() [pkg/sbom/core/bom.go]() [examples/module/spring4shell/README.md]() --- --- ## Doramagic 踩坑日志 项目：aquasecurity/trivy 摘要：发现 11 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 涉及密钥、隐私或敏感领域。 ## 1. 安全/权限坑 · 涉及密钥、隐私或敏感领域 - 严重度：high - 证据强度：source_linked - 发现：项目文本出现 secret/private key/privacy/trading/finance 等敏感关键词。 - 对用户的影响：金融、交易、隐私和密钥场景必须比普通工具更保守。 - 证据：packet_text.keyword_scan | https://github.com/aquasecurity/trivy | matched secret / private key / privacy / trading / finance keyword ## 2. 安装坑 · 依赖 Docker 环境 - 严重度：medium - 证据强度：runtime_trace - 发现：安装/运行入口包含 Docker 命令：docker run aquasec/trivy - 对用户的影响：非工程用户可能没有 Docker，启动成本明显增加。 - 复现命令：`docker run aquasec/trivy` - 证据：identity.distribution | https://github.com/aquasecurity/trivy | docker run aquasec/trivy ## 3. 配置坑 · 来源证据：feat(misconf): add CloudFront standard logging v2 support to AVD-AWS-0010 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：feat(misconf): add CloudFront standard logging v2 support to AVD-AWS-0010 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/aquasecurity/trivy/issues/10622 | 来源类型 github_issue 暴露的待验证使用条件。 ## 4. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/aquasecurity/trivy | README/documentation is current enough for a first validation pass. ## 5. 运行坑 · 运行可能依赖外部服务 - 严重度：medium - 证据强度：source_linked - 发现：项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。 - 对用户的影响：本地安装成功不等于能力可用，外部服务不可用会阻断体验。 - 证据：packet_text.keyword_scan | https://github.com/aquasecurity/trivy | matched external service / cloud / webhook / database keyword ## 6. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/aquasecurity/trivy | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/aquasecurity/trivy | no_demo; severity=medium ## 8. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/aquasecurity/trivy | no_demo; severity=medium ## 9. 安全/权限坑 · 来源证据：bug: project dependencies are not extracted from pnpm-lock.yaml with multiple YAML documents (pnpm 11) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug: project dependencies are not extracted from pnpm-lock.yaml with multiple YAML documents (pnpm 11) - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/aquasecurity/trivy/issues/10859 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 10. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/aquasecurity/trivy | issue_or_pr_quality=unknown ## 11. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/aquasecurity/trivy | release_recency=unknown