Trivy `trivy image` 命令完整参考：容器镜像安全扫描的语法、全部参数与实现原理

Trivytrivy image命令完整参考容器镜像安全扫描的语法、全部参数与实现原理【免费下载链接】trivyFind vulnerabilities, misconfigurations, secrets, SBOM in containers, Kubernetes, code repositories, clouds and more项目地址: https://gitcode.com/GitHub_Trending/tr/trivytrivy image是 Trivy开源统一安全扫描器中最核心的子命令用于对容器镜像执行漏洞vulnerability、错误配置misconfig、密钥secret与许可证license等多类安全检测。本篇以仓库内 docs/guide/references/configuration/cli/trivy_image.md 为骨架完整继承其命令语法、示例与全部参数表并结合 pkg/commands/app.go 与 pkg/commands/artifact/run.go 等源码剖析参数背后的执行链路。读完本文你将能精确理解每一个 flag 的作用与默认行为并针对「本地镜像 / tar 归档 / 客户端-服务器模式 / 仅漏洞 / 合规报告」等场景拼装出可直接落地的扫描命令。命令概述与基本语法trivy image用于扫描容器镜像属于根命令下 Scanning Commands 分组并提供了短别名i等价于trivy i ...。命令定义位于 pkg/commands/app.go#L247-L338其Use声明如下trivy image [flags] IMAGE_NAME其中IMAGE_NAME是要扫描的镜像名例如python:3.4-alpine、alpine:latest如果不提供镜像名而使用--input则扫描本地 tar 归档内的镜像。位置参数经过validateArgs校验见 pkg/commands/app.go 中的PreRunE随后进入统一的 artifact 扫描流程。从源码结构看image子命令在创建时挂载了十几个 flag 分组全局、缓存、DB、镜像专属、许可证、misconfig、模块、包、客户端/服务器、仓库注册、Rego、报告、扫描、密钥与漏洞分组因此它继承了 Trivy 绝大多数与容器扫描相关的能力。这些 flag 既支持命令行传入也支持通过-c trivy.yaml配置文件与TRIVY_*环境变量注入每个 flag 都声明了ConfigName见 pkg/flag/image_flags.go#L18-L70 中诸如image.platform、image.source的映射三种配置方式的完整键值集可参考 schema/trivy-config.json。典型用法示例官方文档给出了七个覆盖最常见场景的示例逐一说明如下# 扫描一个容器镜像 $ trivy image python:3.4-alpine # 从 tar 归档扫描容器镜像无需 Docker 守护进程 $ trivy image --input ruby-3.1.tar # 按严重级别过滤 $ trivy image --severity HIGH,CRITICAL alpine:3.15 # 忽略未修复unfixed/unpatched的漏洞 $ trivy image --ignore-unfixed alpine:3.15 # 客户端模式下扫描容器镜像连接远端 trivy server $ trivy image --server http://127.0.0.1:4954 alpine:latest # 输出 JSON 结果 $ trivy image --format json --output result.json alpine:3.15 # 生成 CycloneDX 格式的报告SBOM $ trivy image --format cyclonedx --output result.cdx alpine:3.15几点解读第一个示例会同时命中默认的两个扫描器vuln与secret见 pkg/flag/scan_flags.go#L37-L73 中ScannersFlag的默认值[vuln,secret]因此除 CVE 外还会输出镜像内的密钥发现。--input适用于离线环境通常配合docker save或skopeo copy生成的镜像归档使用。--format json/--format cyclonedx与--output组合可实现机器可读结果与软件物料清单SBOM导出后续还可交给trivy convert做格式互转参考 docs/guide/references/configuration/cli/trivy_convert.md。从命令到扫描trivy image 的执行链路理解参数必须先理解执行链路。当trivy image被调用后pkg/commands/app.go 的RunE会将解析好的flag.Options交给artifact.Run(ctx, options, artifact.TargetContainerImage)随后在 pkg/commands/artifact/run.go#L422-L467 的run()中按「扫描 → 过滤 → 输出」三步执行。四种扫描模式的自动选择在 pkg/commands/artifact/run.go#L199-L220 的ScanImage中根据--input与--server两个参数是否为空会分派到四种不同的扫描服务实现条件模式有--input、无--server独立模式扫描镜像 tar 归档有--input、有--server客户端/服务器模式下提交归档扫描无--input、无--server独立模式直接扫描镜像走 Docker/containerd/podman 或远端仓库无--input、有--server客户端/服务器模式由远端服务完成扫描其中「镜像从哪来」由--image-src决定支持docker、containerd、podman、remote四种来源默认按[docker,containerd,podman,remote]优先级探测定义见 pkg/fanal/types/image.go#L23-L30。若--image-src只保留remote则 Trivy 不会调用本地容器运行时而是直接从镜像仓库拉取并解析镜像。DB 初始化与流水线正式扫描前NewRunner会完成三项准备见 pkg/commands/artifact/run.go#L325-L376 的initDB/initJavaDB若启用了vuln扫描器且未指定--server先下载/更新漏洞数据库trivy-db--download-db-only会在此步骤后直接返回SkipScan实现「只更新数据库、不扫描」。Java 相关扫描pom.xml、gradle 等需要额外的 Java 索引数据库由trivy-java-db承载。加载 WASM 模块、下载 VEX 仓库--vex repo场景、后台静默执行版本更新检查。扫描完成后依次经过result.Filter依据--severity、--ignore-unfixed、.trivyignore等裁剪结果与pkgReport.Write依据--format、--template、--output等写出报告最后由operation.Exit根据--exit-code决定进程退出码方便 CI 集成。此外还需注意ScanImage会将analyzer.TypeLockfiles各类语言锁文件分析器整体禁用即镜像扫描不会重复去解析语言锁文件容器内已安装的依赖由对应语言分析器直接探测。参数全景按功能分组的完整参考下面是trivy image的全部可选参数按功能归类整理默认值均来自当前仓库文档与源码方便按场景查阅。一、镜像来源、目标与运行环境参数说明默认值--input string用镜像 tar 归档路径代替镜像名进行扫描空--image-src strings按优先级使用的镜像来源可取docker、containerd、podman、remote[docker,containerd,podman,remote]--docker-host string指定用于 Docker 扫描的 unix 域套接字路径空--podman-host string指定用于 Podman 扫描的 unix 套接字路径空--platform string多平台镜像选择平台格式os/arch如linux/amd64*表示任意 OS空--max-image-size string[EXPERIMENTAL]可处理的最大镜像尺寸人类可读格式如44kB、17MB超限报错空--removed-pkgs检测已删除软件包中的漏洞仅 Alpinefalse--distro string[EXPERIMENTAL]显式指定发行版格式family/version空说明--platform的取值在 pkg/flag/image_flags.go#L124-L135 中会经go-containerregistry的ParsePlatform校验解析失败会直接报错--max-image-size则通过units.FromHumanSize换算为字节数。--docker-host/--podman-host的配置键分别为image.docker.host与image.podman.host对应源码见 pkg/flag/image_flags.go#L45-L56。二、扫描器与扫描范围参数说明默认值--scanners strings要检测的安全问题类型vuln、misconfig、secret、license[vuln,secret]--image-config-scanners strings对容器镜像配置Dockerfile 等额外检测的类型misconfig、secret空--pkg-types strings包类型范围os系统包、library语言依赖[os,library]--pkg-relationships strings纳入报告的包依赖关系unknown/root/workspace/direct/indirect全部五种--list-all-pkgs在 JSON 报告中输出全部软件包无论是否有漏洞true--skip-dirs strings跳过的目录或 glob 模式空--skip-files strings跳过的文件或 glob 模式空--offline-scan不发起 API 请求识别依赖false--parallel int并行扫描的 goroutine 数0表示按 CPU 自动检测5--file-patterns strings指定配置文件匹配模式空补充说明--scanners兼容历史写法misconf/misconfiguration等价misconfig已废弃的config与--security-checks也会被自动归一化/告警pkg/flag/scan_flags.go#L50-L73。--parallel 0时源码会自动将其设置为 CPU 核数pkg/flag/scan_flags.go#L242-L246。--removed-pkgs需要结合 Alpine 的 apk 数据库变更记录工作。三、严重级别、漏洞过滤与忽略策略参数说明默认值-s, --severity strings展示的安全问题严重级别UNKNOWN/LOW/MEDIUM/HIGH/CRITICAL全部五种--ignore-unfixed只展示有修复版本fixed的漏洞false--ignore-status strings忽略指定漏洞状态unknown/not_affected/affected/fixed/under_investigation/will_not_fix/fix_deferred/end_of_life空--ignorefile string指定.trivyignore忽略文件.trivyignore--ignore-policy string指定用于逐条评估漏洞的 Rego 文件路径空--ignored-licenses strings指定要忽略的许可证列表空--show-suppressed[EXPERIMENTAL]显示被抑制的漏洞false--exit-code int发现任何安全问题时指定的进程退出码未设置--exit-on-eol int当 OS 到达服务/生命周期终点EOL时以指定码退出未设置值得强调的实现细节--ignore-unfixed在代码层面其实是--ignore-status的「速记写法」。当二者同时出现时pkg/flag/vulnerability_flags.go#L90-L109 会打印警告并忽略--ignore-unfixed单独使用时它等价于除fixed以外的所有状态都被忽略即「只留下已修复的漏洞」。四、检测优先级与漏洞严重级别数据源参数说明默认值--detection-priority stringprecise以最小化误报为优先comprehensive检出更多安全问题、容忍潜在误报precise--vuln-severity-source strings决定采用哪个数据源的严重级别优先级顺序nvd/redhat/redhat-oval/debian/ubuntu/alpine/amazon/oracle-oval/suse-cvrf/photon/arch-linux/alma/rocky/cbl-mariner/azure/ruby-advisory-db/php-security-advisories/nodejs-security-wg/ghsa/glad/aqua/osv/k8s/wolfi/chainguard/bitnami/govulndb/julia/bottlerocket/echo/minimos/rootio/rapidfort及auto[auto]--vex strings[EXPERIMENTAL]VEX 来源repo、oci或文件路径空--skip-vex-repo-update[EXPERIMENTAL]跳过 VEX 仓库更新false--vuln-severity-source的允许值枚举了各发行版/生态的漏洞数据源 ID取值定义位于 pkg/flag/vulnerability_flags.go#L39-L48。当出现数据源对同一 CVE 定级不一致时该列表顺序决定了最终的严重级别归属。五、漏洞数据库与缓存管理参数说明默认值--db-repository strings按优先级下载 trivy-db 的 OCI 仓库列表[mirror.gcr.io/aquasec/trivy-db:2,ghcr.io/aquasecurity/trivy-db:2]--skip-db-update跳过漏洞数据库更新false--download-db-only只下载/更新漏洞数据库不执行扫描false--java-db-repository strings按优先级下载 trivy-java-db 的 OCI 仓库列表[mirror.gcr.io/aquasec/trivy-java-db:1,ghcr.io/aquasecurity/trivy-java-db:1]--skip-java-db-update跳过 Java 索引数据库更新false--download-java-db-only只下载/更新 Java 索引数据库不执行扫描false--checks-bundle-repository string获取 checks bundle 的 OCI 仓库 URLmirror.gcr.io/aquasec/trivy-checks:2--skip-check-update跳过 Rego check 更新拉取false--cache-backend string[EXPERIMENTAL]缓存后端如redis://localhost:6379fs--cache-ttl duration使用 Redis 缓存后端时的缓存 TTL空--redis-ca stringRedis 缓存后端的 CA 证书文件路径空--redis-cert stringRedis 缓存后端的客户端证书文件路径空--redis-key stringRedis 缓存后端的客户端密钥文件路径空--redis-tls使用公共证书启用 Redis TLS配合上述三项false--download-db-only与--download-java-db-only的语义在 pkg/commands/artifact/run.go#L325-L376 中体现前者会先按需更新 DB 然后返回SkipScan结束整个流程适合 CI 预热缓存。Redis 相关 TLS 选项的配置键是cache.redis.*pkg/flag/cache_flags.go#L36-L56。六、客户端/服务器模式与仓库认证参数说明默认值--server string客户端模式下 Trivy server 地址空--custom-headers strings客户端模式下附加的自定义请求头空--token string客户端/服务器模式下的认证 token空--token-header stringtoken 的请求头名称Trivy-Token--registry-token string镜像仓库 bearer token空--username strings镜像仓库用户名支持逗号分隔多个空--password strings镜像仓库密码出于安全原因建议使用环境变量TRIVY_PASSWORD空--password-stdin从 stdin 读取密码不支持逗号分隔多密码false--insecure允许不安全的服务器连接继承自父命令false客户端/服务器模式把镜像层解析、扫描重活放到远端 server瘦客户端只需上传目标描述适用于大规模集群场景。注意从 pkg/commands/artifact/run.go#L471 附近的checkOptions可看到misconfig 与 secret 扫描在客户端/服务器模式下仍会在客户端本地执行只有漏洞扫描被卸载到服务端。七、输出格式与报告参数说明默认值-f, --format string输出格式table/json/template/sarif/cyclonedx/spdx/spdx-json/github/cosign-vulntable-o, --output string输出文件名空-t, --template string输出模板模板文件须以.tpl结尾配合--format template空--report string合规报告格式all或summarysummary--table-mode strings[EXPERIMENTAL]table 格式展示的模块summary/detailed[summary,detailed]--dependency-tree[EXPERIMENTAL]展示漏洞包的依赖来源树false--output-plugin-arg string[EXPERIMENTAL]传给输出插件的参数空--render-cause strings指定在 table 报告中展示渲染原因cause的配置类型terraform/ansible空--no-progress隐藏进度条false--exit-code int见「过滤」分组同时在报告阶段生效未设置--skip-version-check抑制版本更新通知与 Trivy 公告false--disable-telemetry禁止向 Aqua 发送匿名使用数据false模板与多种格式的具体输出样例可参考仓库集成测试的 golden 文件例如 integration/testdata/alpine-310.json.golden、integration/testdata/alpine-310.sarif.golden 与 integration/testdata/alpine-310.html.goldenCycloneDX/SBOM 相关能力见 pkg/sbom 目录。八、合规报告Compliance参数说明默认值--compliance string要生成的合规报告内置合规项docker-cis-1.6.0空--include-deprecated-checks包含已废弃的检查项false--include-non-failures包含「通过」的结果需配合--scanners misconfigfalse合规报告模式下--report才有意义all/summary。源码中 pkg/commands/app.go#L248-L256 将image命令的报告格式默认覆盖为summary并把内置合规项限定为docker-cis-1.6.0。九、Misconfig / Rego 自定义策略与 IaC 相关参数参数说明默认值--config-check strings指定 Rego 检查文件或目录路径应用于配置文件空--config-data strings指定供 Rego 检查递归加载数据的路径空--config-file-schemas strings指定 JSON 配置文件 schema 路径用于判断文件类型并做类型检查空--check-namespaces stringsRego 命名空间空--misconfig-scanners strings用于 misconfig 扫描的扫描器列表[azure-arm,cloudformation,dockerfile,helm,kubernetes,terraform,terraformplan-json,terraformplan-snapshot,ansible]--raw-config-scanners strings额外以原始配置扫描的类型如terraform空--trace-rego为自定义查询输出更详细的 Rego tracefalse--rego-error-limit intRego 策略评估允许的最大编译错误数10--tf-exclude-downloaded-modules排除已下载 Terraform 模块的 misconfig 结果false--helm-api-versions strings与helm template --api-versions等价可多值/逗号分隔空--helm-kube-version string与helm template --kube-version等价空--helm-set strings命令行指定 Helm valueskey1val1,key2val2空--helm-set-file strings从文件指定 Helm values空--helm-set-string strings命令行指定 Helm 字符串值空--helm-values strings指定覆盖 Helmvalues.yaml的路径空--ansible-extra-vars strings以keyvalue或fileYAML/JSON附加变量空--ansible-inventory strings指定 inventory 主机路径或逗号分隔主机列表空--ansible-playbook strings指定要扫描的 playbook 文件路径空这些参数让trivy image --scanners misconfig能够对镜像内嵌的 IaC/配置Dockerfile、Kubernetes manifests、Helm chart 等执行策略检查。注意在镜像扫描场景中位于 pkg/commands/app.go#L258-L263 的misconfFlagGroup会屏蔽--cf-params与--tf-vars这两个参数仅用于仓库/文件系统扫描。十、密钥扫描、许可证、模块与其他参数说明默认值--secret-config string密钥扫描的配置文件路径trivy-secret.yaml--license-confidence-level float许可证分类器的置信度阈值0.9--license-full更彻底地在源码头部与许可证文件中查找许可证false--enable-modules strings[EXPERIMENTAL]启用的 WASM 模块名空--module-dir string存放待加载 wasm 模块的目录$HOME/.trivy/modules--sbom-sources strings[EXPERIMENTAL]尝试从指定来源oci、rekor获取现成 SBOM空--rekor-url string[EXPERIMENTAL]Rekor 透明度日志服务器地址https://rekor.sigstore.dev-h, --help查看image命令帮助—十一、父命令继承的全局参数以下参数由根命令继承而来同样适用于trivy image参数说明默认值-c, --config string配置文件路径trivy.yaml--cache-dir string缓存目录文档中默认值显示为占位符/path/to/cache视环境而定--cacert stringPEM 编码 CA 证书文件路径空--insecure允许不安全的服务器连接false-d, --debug调试模式false-q, --quiet抑制进度条与日志输出false--timeout duration超时时间5m0s--generate-default-config将默认配置写入trivy-default.yamlfalse-v, --version显示版本信息—其中--generate-default-config会在artifact.Run中拦截执行遍历当前所有有效配置键并生成一份trivy-default.yaml见 pkg/commands/artifact/run.go#L383-L401是了解完整配置键的便捷入口。一份实际的 YAML 配置样例可参考 examples/trivy-conf/trivy.yaml。常用实战组合结合上文参数语义可拼出如下高频组合# 只做漏洞扫描并忽略未修复项控制台以表格展示 HIGH/CRITICAL $ trivy image --scanners vuln --severity HIGH,CRITICAL --ignore-unfixed alpine:3.15 # 多架构镜像指定平台 输出 SARIF 供代码扫描平台消费 $ trivy image --platform linux/arm64 --format sarif --output result.sarif ghcr.io/org/app:latest # 无 Docker 环境下扫描离线镜像包 $ trivy image --image-src remote --input ruby-3.1.tar --format json -o result.json # CI 中存在任一 HIGH 漏洞即返回 1 $ trivy image --exit-code 1 --severity HIGH,CRITICAL python:3.4-alpine # 企业内网指定自建镜像仓库并关闭遥测与版本检查 $ trivy image --image-src remote --registry-token $TOKEN --disable-telemetry --skip-version-check your-registry.example.com/app:1.2.3 # 镜像配置合规扫描Docker CIS $ trivy image --compliance docker-cis-1.6.0 --report all your-image:tag # 同时检测镜像内的密钥与错误配置 $ trivy image --scanners vuln,secret,misconfig --image-config-scanners misconfig,secret your-image:tag相关命令与延伸阅读trivy image属于扫描命令族的一员同族还包括文件系统/根文件系统/仓库/SBOM/VM/K8s 等目标根命令总览见 docs/guide/references/configuration/cli/trivy.md。与之配套的常用命令trivy convert把 image 扫描得到的 JSON 报告再转换为 CycloneDX/SPDX 等其他格式docs/guide/references/configuration/cli/trivy_convert.mdtrivy server/trivy client客户端-服务器部署模式docs/guide/references/configuration/cli/trivy_server.mdtrivy clean清理各类缓存docs/guide/references/configuration/cli/trivy_clean.md。源码层面参数定义集中在 pkg/flag 目录镜像专属见 pkg/flag/image_flags.go执行流水线见 pkg/commands/artifact/run.go扫描服务与各类报告格式的实现分别位于 pkg/scan、pkg/report 与 pkg/sbom可供深入研读其内部原理。【免费下载链接】trivyFind vulnerabilities, misconfigurations, secrets, SBOM in containers, Kubernetes, code repositories, clouds and more项目地址: https://gitcode.com/GitHub_Trending/tr/trivy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考