Trivy 插件体系全指南：trivy plugin 命令参考与实战用法

Trivy 插件体系全指南：trivy plugin 命令参考与实战用法

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

Trivy 提供了一套插件（Plugin）机制，允许第三方在不改动 Trivy 核心代码的前提下扩展 CLI 能力，插件可以用于扫描 Kubernetes 资源、集成外部安全平台、处理扫描输出等场景。本文以docs/guide/references/configuration/cli/trivy_plugin.md及其子命令文档为骨架，结合pkg/plugin源码与用户指南，系统讲解trivy plugin的八个子命令、插件安装与发现流程、输出模式（Output Mode）以及插件元数据与缓存机制，帮助读者从命令使用到内部实现完整掌握 Trivy 插件体系。

插件体系概览

Trivy 的插件是一类与 Trivy 无缝集成的附加工具（add-on），其设计灵感来自 kubectl、Helm 和 Conftest 的插件系统。插件的核心价值在于：不必把每一个新特性都用 Go 写成 Trivy 核心的一部分，而是可以通过独立插件快速扩展功能集合。

插件的三个关键特性：

• 可增可减：插件可以从 Trivy 安装中随时添加或移除，不影响 Trivy 核心工具本身；
• 语言无关：插件可以用任意编程语言编写；
• 深度集成：插件会出现在 Trivy 的帮助信息与子命令列表中，使用体验与内置命令一致。

需要特别注意的是安全风险：公开渠道获取的 Trivy 插件并未经过安全审计，插件本质上是运行在你机器上的任意程序，安装和运行第三方插件需要自行承担风险。

从源码看，插件的元数据模型定义在 pkg/plugin/plugin.go，一个插件由name、repository、version、summary、description、platforms（按操作系统与架构选择可执行文件）以及安装信息installed组成，这为下文理解插件缓存与平台选择机制打下了基础。

trivy plugin 父命令

trivy plugin是所有插件管理操作的入口，其作用是"管理插件"（Manage plugins）。

trivy plugin [command]

可用子命令一览（详见本文后续各节）：

父命令选项

-h, --help help for plugin

继承自父命令的全局选项

以下选项在所有trivy plugin子命令中同样可用，它们来自 Trivy 的全局命令行框架：

--cacert string Path to PEM-encoded CA certificate file --cache-dir string cache directory (default "/path/to/cache") -c, --config string config path (default "trivy.yaml") -d, --debug debug mode --generate-default-config write the default config to trivy-default.yaml --insecure allow insecure server connections -q, --quiet suppress progress bar and log output --timeout duration timeout (default 5m0s) -v, --version show version

参数说明：

• --cacert：指定 PEM 编码的 CA 证书文件路径，用于访问需要自定义 CA 的 HTTPS 资源；
• --cache-dir：缓存目录，插件索引、插件本体等数据均存放于缓存相关路径；
• -c, --config：配置文件路径，默认trivy.yaml；
• -d, --debug：开启调试模式，输出详细日志；
• --generate-default-config：将默认配置写入trivy-default.yaml；
• --insecure：允许不安全的服务器连接（例如在下载插件索引或插件时跳过 TLS 校验）；
• -q, --quiet：抑制进度条与日志输出；
• --timeout：超时时间，默认5m0s（5 分钟）；
• -v, --version：显示版本信息。

其中--insecure与--timeout对插件下载场景尤其重要：trivy plugin update在下载插件索引、trivy plugin install在拉取插件包时都会受这些全局选项影响。

插件索引与发现：update 与 search

刷新本地插件索引

插件索引（plugin index）是 Trivy 官方维护的一份插件清单。在使用搜索与按名安装之前，建议先刷新本地副本：

$ trivy plugin update

命令原型：trivy plugin update，功能是"更新本地插件索引副本"。

从源码看，pkg/plugin/index.go 中的Update方法会将索引文件先下载到临时目录，再复制到本地插件目录，其注释明确说明这样做的目的是"避免删除已安装的插件"，即更新索引不会误伤本地已装插件。索引文件的地址常量同样定义在 pkg/plugin/index.go。

索引文件的 YAML 结构定义在 pkg/plugin/index.go：每个索引条目包含name、version、maintainer、summary、repository与output（是否支持输出模式）字段，这些字段正是下文trivy plugin search输出各列的来源。

搜索可用插件

$ trivy plugin search NAME DESCRIPTION MAINTAINER OUTPUT aqua A plugin for integration with Aqua Security SaaS platform aquasecurity kubectl A plugin scanning the images of a kubernetes resource aquasecurity referrer A plugin for OCI referrers aquasecurity ✓ [...]

命令原型：trivy plugin search [KEYWORD]，功能是"列出插件索引中的 Trivy 插件并支持搜索"。

• 不带参数时，列出索引中全部插件；
• 带关键词时，仅列出名称或描述中包含该关键词的插件，例如：

$ trivy plugin search referrer NAME DESCRIPTION MAINTAINER OUTPUT referrer A plugin for OCI referrers aquasecurity ✓

输出中的OUTPUT列标记插件是否支持"输出模式"（Output Mode），带✓的插件（如示例中的referrer）可以在 Trivy 内置命令中作为输出处理器使用，详见本文"输出模式"一节。output字段在索引结构体中有对应定义，是判断插件能力的重要依据。

安装插件：install

trivy plugin install用于安装插件，命令原型支持三种来源：

trivy plugin install NAME | URL | FILE_PATH

从插件索引按名安装

# 从插件索引安装插件 $ trivy plugin install referrer

指定插件版本

如果插件的 Git 仓库已按规范打上版本标签，可以指定具体版本：

# 指定要安装的插件版本 $ trivy plugin install referrer@v0.3.0

版本语法有两个硬性要求：

• 版本号前导v是必需的（如v0.3.0）；
• 版本号必须遵循语义化版本规范（Semantic Versioning）。

从仓库测试数据看，count插件在集成测试中同时存在count-0.1.0-plugin-with-before-flag.txt.golden与count-0.2.0-plugin.txt.golden两份 golden 输出（见 integration/testdata/fixtures），佐证了插件可以按版本演进并在升级后产生不同输出。

从 URL 或本地文件安装

对于未登记在索引中的插件，可以绕过索引直接指定下载地址：

# 通过仓库路径指定 $ trivy plugin install github.com/aquasecurity/trivy-plugin-kubectl # 通过 HTTP(S) 归档地址指定 $ trivy plugin install https://github.com/aquasecurity/trivy-plugin-kubectl/archive/refs/heads/main.zip # 通过本地文件路径指定 $ trivy plugin install ./myplugin.tar.gz

底层下载机制与支持协议

trivy plugin install在底层借助 go-getter 完成插件下载（用户指南中明确说明），这意味着以下协议均可用于插件分发：

• OCI 镜像仓库（OCI Registries）
• 本地文件（Local Files）
• Git
• HTTP/HTTPS
• Mercurial
• Amazon S3
• Google Cloud Storage

这一能力使插件既可以发布为简单的压缩包，也可以发布为 OCI 制品，分发方式非常灵活。

安装完成后，插件会进入本地插件缓存。pkg/plugin包中Manager负责插件的安装、卸载、升级与运行，相关逻辑可进一步阅读 pkg/plugin/manager.go 及测试 pkg/plugin/manager_test.go。

插件缓存位置与 XDG 规范

插件安装后存放在插件缓存目录中。Trivy 遵循 XDG 规范，具体位置取决于XDG_DATA_HOME是否设置，查找优先级如下：

1. 如果设置了XDG_DATA_HOME，且该目录下存在.trivy/plugins，则使用$XDG_DATA_HOME/.trivy/plugins；
2. 否则使用~/.trivy/plugins。

这一规则同样适用于插件索引的存放：索引文件被放置在插件目录中（Update方法会先创建目录再复制索引文件，见 pkg/plugin/index.go）。

查看插件信息：info 与 list

查看指定插件详情

trivy plugin info PLUGIN_NAME

trivy plugin info用于显示指定插件的详细信息（Show information about the specified plugin），输出内容对应插件元数据中的字段。

列出已安装插件

$ trivy plugin list

trivy plugin list用于列出本机已安装的全部插件（List installed plugin），同样会展示OUTPUT列，方便确认哪些已装插件支持输出模式。

使用插件：运行与集成

插件如何融入 Trivy CLI

插件安装完成后，Trivy 会在下一次执行时加载缓存中的全部插件，并基于插件名生成对应的 CLI 子命令。用trivy --help即可看到所有插件：

$ trivy --help NAME: trivy - A simple and comprehensive vulnerability scanner for containers USAGE: trivy [global options] command [command options] target VERSION: dev Scanning Commands config Scan config files for misconfigurations filesystem Scan local filesystem image Scan a container image ... Plugin Commands kubectl scan kubectl resources referrer Put referrers to OCI registry

如上所示，kubectl子命令出现在Plugin Commands一节。安装插件后直接以子命令方式调用即可，例如调用 kubectl 插件扫描现有 Kubernetes Deployment：

$ trivy kubectl deployment <deployment-id> -- --ignore-unfixed --severity CRITICAL

从集成测试看，仓库 integration/plugin_test.go 专门覆盖了插件的安装、运行与输出模式等行为，是验证插件用法的可执行参考。

即装即用：plugin run

如果只想临时使用某个插件、不想长期安装，可以使用trivy plugin run：

trivy plugin run kubectl pod your-pod -- --exit-code 1

命令原型：trivy plugin run NAME | URL | FILE_PATH，功能是"即时运行一个插件"（Run a plugin on the fly）。其行为特点是：先安装插件再立即运行；如果插件已存在于缓存中，则跳过安装步骤直接执行。

省略子命令：TRIVY_RUN_AS_PLUGIN

如果连插件子命令都想省略，可以通过TRIVY_RUN_AS_PLUGIN环境变量直接指定插件名：

$ TRIVY_RUN_AS_PLUGIN=kubectl trivy job your-job -- --format json

此时trivy job ...中的job会被当作 kubectl 插件的参数透传。注意--之后的内容会作为插件自身参数传入。

从源码看插件如何被执行

pkg/plugin/plugin.go 中的Cmd方法展示了插件的执行模型：Trivy 根据当前平台（操作系统/架构）从插件的platforms中选择对应的可执行文件，拼接插件目录下的二进制路径后通过exec.CommandContext启动，并将标准输入、标准输出、标准错误与环境变量全部透传给插件进程。这意味着：

• 插件本质上是独立的外部进程，Trivy 只是它的启动器与参数转发者；
• 插件二进制需要放在其元数据声明的平台对应路径下；
• 运行插件时的参数通过--之后的部分透传。

维护插件：upgrade 与 uninstall

升级插件

升级所有已安装插件到最新版本：

$ trivy plugin upgrade

只升级指定插件：

$ trivy plugin upgrade <PLUGIN1> <PLUGIN2>

命令原型：trivy plugin upgrade [PLUGIN_NAMES]，功能是"将已安装插件升级到更新版本"。不带参数时升级全部插件，带参数时仅升级列出的插件。

卸载插件

$ trivy plugin uninstall kubectl

命令原型：trivy plugin uninstall PLUGIN_NAME，功能是"卸载指定插件"。卸载后该插件对应的子命令将从trivy --help中消失。

输出模式（Output Mode，实验性）

什么是输出模式

插件通常作为 Trivy 的子命令使用，但支持输出模式的插件可以嵌入 Trivy 内置命令的流水线中：它们负责处理 Trivy 的扫描输出——例如转换输出格式，或将结果发送到其他系统。

实验性警告：该特性可能在不保证向后兼容的情况下变更，生产环境使用前需谨慎评估。

判断插件是否支持输出模式

检查trivy plugin search或trivy plugin list输出中的OUTPUT列，带✓即表示支持输出模式。例如下表中referrer支持输出模式：

$ trivy plugin search NAME DESCRIPTION MAINTAINER OUTPUT aqua A plugin for integration with Aqua Security SaaS platform aquasecurity kubectl A plugin scanning the images of a kubernetes resource aquasecurity referrer A plugin for OCI referrers aquasecurity ✓

在扫描命令中使用输出模式插件

以镜像扫描为例，支持输出模式的插件可以这样调用：

$ trivy image --format json --output plugin=<plugin_name> [--output-plugin-arg <plugin_flags>] <image_name>

关键机制：

• 扫描结果通过标准输入传递给插件，因此插件必须能够处理标准输入；
• 为避免 Trivy 挂起，插件必须在正常退出或报错退出前读完Stdin中的全部数据；
• 传入的格式不限于 JSON，SBOM 等格式同样可行（例如--format cyclonedx）；
• 插件需要的额外参数通过--output-plugin-arg透传，它会被原样转发为插件进程的参数。例如--output plugin=myplugin --output-plugin-arg "--foo --bar=baz"实际执行的是myplugin --foo --bar=baz。

完整示例：count 插件

以count插件为例（仓库测试数据中包含该插件的 golden 输出，见 integration/testdata/fixtures/count-0.1.0-plugin-with-before-flag.txt.golden 与 integration/testdata/fixtures/count-0.2.0-plugin.txt.golden），完整用法如下：

# 先安装插件 $ trivy plugin install count # 在镜像扫描中以输出模式调用插件，并透传插件参数 $ trivy image --format json --output plugin=count --output-plugin-arg "--published-after 2023-10-01" debian:12

快速上手：六步掌握插件使用

结合 docs/guide/plugin/index.md 中的 Quickstart，一个完整的插件使用流程如下：

1. 下载插件列表（刷新本地索引副本）：

   $ trivy plugin update

2. 浏览插件索引中的可用插件：

   $ trivy plugin search

3. 从列表中选择插件并安装：

   $ trivy plugin install referrer

4. 以子命令方式使用已安装插件：

   $ trivy referrer --help

5. 保持插件更新：

   $ trivy plugin upgrade

6. 卸载不再使用的插件：

   $ trivy plugin uninstall referrer

更深入的学习路径

• 命令参考：父命令见 docs/guide/references/configuration/cli/trivy_plugin.md，子命令包括 trivy plugin install、trivy plugin search、trivy plugin run、trivy plugin info、trivy plugin list、trivy plugin update、trivy plugin upgrade、trivy plugin uninstall；
• 插件总览与快速开始：docs/guide/plugin/index.md；
• 插件用户指南（发现、安装、使用、输出模式等）：docs/guide/plugin/user-guide.md；
• 插件开发指南（含插件仓库打标签规范）：docs/guide/plugin/developer-guide.md；
• 源码实现：插件元数据与执行逻辑见 pkg/plugin/plugin.go，索引更新与搜索逻辑见 pkg/plugin/index.go，管理器逻辑见 pkg/plugin/manager.go，相关测试见 pkg/plugin/manager_test.go、pkg/plugin/index_test.go 与 integration/plugin_test.go。

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