Trivy 安全扫描器入门与源码解读：目标、扫描器与 CLI 用法全解析

Trivy 安全扫描器入门与源码解读：目标、扫描器与 CLI 用法全解析

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

Trivy 是 Aqua Security 推出的综合型安全扫描器，用于在容器镜像、文件系统、Git 仓库、虚拟机镜像和 Kubernetes 集群中发现漏洞（CVE）、IaC 与配置错误、敏感信息和软件许可证问题。本文基于仓库根目录的 README.md 展开，并结合pkg/commands、pkg/flag、pkg/types等源码目录，完整讲解 Trivy 的"目标 × 扫描器"模型、安装方式、通用命令语法及各子命令的实现脉络，帮助你在读完之后能够独立配置并运行一次完整的 Trivy 扫描，并理解其关键参数的默认值与取值来源。

一、核心模型：Targets（扫描目标）与 Scanners（扫描器）

README 开篇即给出了 Trivy 的设计模型：Trivy 由两类正交的概念组成——它在哪里找问题（Targets）与它能找到什么问题（Scanners）。二者可以自由组合，这也是理解全部子命令和--scanners参数的钥匙。

1.1 官方列出的扫描目标

README 中列出的 Trivy 可扫描对象包括：

• 容器镜像（Container Image）
• 文件系统（Filesystem）
• Git 仓库（Git Repository，支持远程地址）
• 虚拟机镜像（Virtual Machine Image）
• Kubernetes 集群

1.2 官方列出的扫描器能力

• OS 软件包与各语言依赖（即 SBOM 构建）
• 已知漏洞（CVE）
• IaC 问题与配置错误（Misconfigurations）
• 敏感信息（Secrets）
• 软件许可证（Licenses）

从源码看，这些扫描器在 pkg/types/scan.go 中被定义为一组常量，取值正是命令行中使用的短名：

同文件中还定义了AllImageConfigScanners（pkg/types/scan.go），表示容器镜像 config 层面可用的扫描器集合：misconfig、secret、none——这解释了为什么镜像配置层面的检查能力与根文件系统层面并不完全一致。

二、获取 Trivy

README 指出 Trivy 已发布到大多数常见分发渠道，完整安装选项见官方 Installation 文档（仓库内对应 docs/getting-started/installation.md）。README 给出了几个最流行的安装方式：

# Homebrew brew install trivy # Docker 镜像 docker run aquasec/trivy # 从 GitHub Releases 下载预编译二进制

仓库中也提供了社区安装脚本 contrib/install.sh，可用于在容器内直接安装（例如在trivy rootfs /的用法示例中就有通过该脚本安装后再扫描的流程）。

2.1 Canary 构建

README 专门提示：每次向main分支推送时都会自动生成 canary 构建（包括 Docker Hub、GitHub 容器包、ECR 镜像及二进制）。canary 构建可能存在严重缺陷，不建议用于生产环境——如果你在 CI 中固定使用稳定渠道，应认准正式 Release 版本。

三、通用命令语法与典型示例

README 给出的通用语法为：

trivy <target> [--scanners <scanner1,scanner2>] <subject>

其中<target>对应一个子命令（如image、fs、k8s），<subject>是扫描对象，--scanners控制启用哪些扫描器。README 提供了三个典型示例：

# 扫描容器镜像 trivy image python:3.4-alpine # 扫描本地文件系统，指定漏洞 + 敏感信息 + 配置错误扫描 trivy fs --scanners vuln,secret,misconfig myproject/ # 扫描 Kubernetes 集群并输出 summary 报告 trivy k8s --report summary cluster

值得注意的是第二个示例中--scanners的写法：它直接使用了源码常量对应的短名vuln,secret,misconfig，这与前文表格完全对应。第三个示例则展示了--report summary汇总报告形态，上图即trivy k8s --report summary cluster类输出的示意效果。

四、子命令全景：从 README 到源码

README 只点名了image、fs、k8s三个命令，但从 CLI 入口看，Trivy 实际提供了更完整的目标与工具命令集合。命令树由 pkg/commands/app.go 中的NewApp()工厂方法组装，所有扫描类子命令被归入 "Scanning Commands" 分组，管理命令归入 "Management Commands"，工具命令归入 "Utility Commands"。

4.1 扫描类命令

此外还有 client/server 模式（trivy server提供服务端、其他命令通过--server连接远程扫描，见 NewServerCommand 与flag.NewClientFlags()在各命令中的装配），以及插件机制——NewApp()会通过loadPluginCommands()（pkg/commands/app.go）动态把已安装插件注册为独立的顶层命令。

4.2 工具类命令

从同一个工厂方法还能看到若干运维向命令，对日常使用同样实用：

• clean：清理缓存（--all/--scan-cache/--vuln-db），见 NewCleanCommand
• convert：把 Trivy JSON 报告转换为其他格式，例如trivy convert --format cyclonedx --output result.cdx result.json
• registry login/logout：管理镜像仓库认证凭据，支持--password-stdin
• vex：[实验性] VEX 仓库管理（init / list / download），实现位于 pkg/vex/repo
• version：打印版本信息，--format json可输出结构化版本数据
• config：打印当前生效配置

五、--scanners参数的实现细节

这是理解"扫描器"主题最深入源码的一节。--scanners在 pkg/flag/scan_flags.go 中定义，有几个值得注意的实现事实：

1. 默认值是vuln,secret：如果不显式指定--scanners，Trivy 默认执行漏洞扫描和敏感信息扫描，misconfig与license需要显式开启。
2. 取值别名归一化：ValueNormalize函数会把vulnerability归一为vuln、把misconf/misconfiguration归一为misconfig；若使用旧名config会打印弃用警告并自动映射为misconfig。
3. 历史兼容：--scanners拥有别名--security-checks，标记为 Deprecated——这是从旧版命名迁移过来的兼容路径。

配置项对应关系同样来自该文件：--scanners对应配置文件键scan.scanners，Trivy 通过 Viper 加载 YAML 配置文件（根命令的PersistentPreRunE中完成initConfig，见 pkg/commands/app.go），因此--scanners也可以在trivy.yaml中统一配置。仓库提供了示例 examples/trivy-conf/trivy.yaml。

同组的扫描性能与范围控制参数（pkg/flag/scan_flags.go）包括：

六、执行流程：从main到扫描服务

结合 cmd/trivy/main.go 可以看清一次命令的完整生命周期：

1. main()调用run()；若设置了环境变量TRIVY_RUN_AS_PLUGIN，Trivy 会以插件形态运行自身（被其他插件管理器调用时）。
2. 注册defer commands.Cleanup()确保退出时清理缓存等资源，并用commands.NotifyContext建立信号上下文，实现优雅关闭。
3. commands.Run(ctx)进入 pkg/commands 的命令树，各子命令的PreRunE阶段先完成 Viper 与 flag 的绑定并校验参数，RunE阶段把 flag 转成Options后统一交给artifact.Run(cmd.Context(), options, artifact.TargetXXX)执行——可以看到image、fs、rootfs、repo等命令的差异本质上就体现在"传入了哪个Target枚举"以及各自装配了哪些 flag 组。
4. 错误处理上，main()区分了三种出口：types.ExitError（携带自定义退出码，直接os.Exit，方便 CI 判定）、types.UserError（用户错误）与致命错误（log.Fatal），见 cmd/trivy/main.go。

扫描结果的数据结构则在 pkg/types/scan.go 中：ScanTarget汇总了 OS、Repository、Packages、Misconfigurations、Secrets、Licenses 等分析产物，ScanOptions则携带 PkgTypes、Scanners、ImageConfigScanners、FilePatterns 等选项进入扫描服务——这与 README 中"Targets 产生数据、Scanners 消费数据"的模型一一对应。

七、FAQ 与社区

• 发音：tri读作trigger 的 tri，vy读作 envy的 vy。
• 生态集成：README 提到 Trivy 已与许多平台和应用集成（完整清单见 docs/ecosystem），典型例子包括 GitHub Actions 集成、Kubernetes operator 与 VS Code 插件等。
• 项目归属：Trivy 是 Aqua Security 的开源项目（Apache-2.0 协议，见 LICENSE），社区交流通过 GitHub Discussion 进行，行为准则遵循 Aqua 社区 Code of Conduct。
• 文档索引：更详细的配置参考可在仓库docs/guide/下按主题查找，例如配置总览 docs/guide/configuration/index.md、误报过滤 docs/guide/configuration/filtering.md、私有镜像仓库 docs/guide/advanced/private-registries、无网环境 docs/guide/advanced/air-gap.md 等。

八、小结

• Trivy 的能力矩阵 = 5 类扫描目标（image/fs/repo/vm/k8s）× 5 类用户可启用扫描器（vuln、misconfig、secret、license、rbac），源码常量定义在 pkg/types/scan.go。
• 命令行遵循trivy <target> [--scanners ...] <subject>的统一语法；--scanners默认vuln,secret，别名归一化与弃用映射逻辑见 pkg/flag/scan_flags.go。
• 所有扫描子命令最终收敛到artifact.Run(ctx, options, target)这一入口，命令装配、flag 分组与退出码语义分别实现在 pkg/commands/app.go 与 cmd/trivy/main.go。
• 生产环境请使用正式 Release 渠道，避免 canary 构建；缓存清理与报告格式转换可依赖trivy clean、trivy convert等工具命令。

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