Trivy config 命令完全指南用trivy config扫描 IaC 与配置文件中的错误配置【免费下载链接】trivyFind vulnerabilities, misconfigurations, secrets, SBOM in containers, Kubernetes, code repositories, clouds and more项目地址: https://gitcode.com/GitHub_Trending/tr/trivytrivy config是 Trivy统一安全扫描器中负责对**配置文件 / 基础设施即代码IaC**执行错误配置misconfiguration扫描的子命令。它支持 Dockerfile、Terraform、CloudFormation、Kubernetes、Helm、Ansible、Azure ARM 等十余种配置类型既可用内置的 checks bundle 规则开箱即用也可通过 Rego 策略定制扫描范围。阅读本文后你将完整掌握trivy config的语法、全部命令行选项的语义与默认值、各选项背后的源码实现逻辑以及将其嵌入 CI 流水线的典型用法。本文以官方 CLI 参考文档 docs/guide/references/configuration/cli/trivy_config.md 为骨架并结合pkg/commands/app.go、pkg/flag/下的实现进行纵深说明。文中所有链接均指向当前仓库。trivy config 命令是什么在 trivy 命令总览 中config是归入Scanning 组groupScanning的子命令其别名alias为conf一句Short描述即可概括其职责Scan config files for misconfigurations基本语法如下trivy config [flags] DIR它接收一个目录DIR作为参数对该目录树内的配置文件进行错误配置扫描。与trivy fs等通用文件系统扫描不同该命令在源码层面被专门收敛为纯错误配置扫描在 pkg/commands/app.go#L688-L760 的NewConfigCommand中命令创建时通过options.DisabledAnalyzers append(analyzer.TypeOSes, analyzer.TypeLanguages...)禁用了所有 OS 层与语言层分析器不再探测系统包、语言依赖与漏洞同时以options.Scanners types.Scanners{types.MisconfigScanner}强制只启用 misconfig 扫描器最终以artifact.Run(cmd.Context(), options, artifact.TargetFilesystem)的形式把DIR当作文件系统目标交给通用扫描管线执行。因此trivy config的输出聚焦于配置缺陷如非安全的权限、暴露的管理端口、不符合规范的编排资源等不会混杂容器漏洞与依赖漏洞信息。注意trivy config与trivy fs --scanners misconfig的可观测行为高度相似但它省去了手动指定--scanners misconfig与关闭无关分析器的麻烦。此外历史版本中形如--scanners config的写法已被废弃在 pkg/flag/scan_flags.go#L54-L60 中会打印弃用告警并自动将其映射为 misconfig 扫描器。全部命令行选项详解下表按功能分组整理了trivy config支持的全部选项均来自官方参考文档并标注了其在源码中的定义位置集中在 pkg/flag/misconf_flags.go、pkg/flag/rego_flags.go、pkg/flag/cache_flags.go、pkg/flag/report_flags.go以及可供配置文件trivy.yaml使用的键名ConfigName。IaC / 配置类型相关选项这些选项决定扫哪些配置类型、如何解析它们多数定义于 pkg/flag/misconf_flags.go。选项类型说明--misconfig-scanners strings逗号分隔列表指定参与错误配置扫描的扫描器集合。默认值为azure-arm,cloudformation,dockerfile,helm,kubernetes,terraform,terraformplan-json,terraformplan-snapshot,ansible对应配置键misconfiguration.scanners。从源码看默认值取自analyzer.TypeConfigFiles并剔除通用 YAML/JSON 类型--helm-values strings路径列表指定用于覆盖 Helm 模板渲染的values.yaml文件路径对应 Helm 模板-f/--values--helm-set stringskeyvalue列表在命令行直接指定 Helm values可多次传入或用逗号分隔多个key1val1,key2val2对应misconfiguration.helm.set--helm-set-file stringskeypath列表指定从文件读取的 Helm values形如key1path1,key2path2--helm-set-string stringskeyvalue列表类似--helm-set但强制将 value 视为字符串处理--helm-api-versions strings逗号分隔列表指定 Helm 模板渲染时Capabilities.APIVersions可用的 Kubernetes API 版本语义与helm template --api-versions相同如policy/v1/PodDisruptionBudget,apps/v1/Deployment--helm-kube-version string字符串指定Capabilities.KubeVersion语义与helm template --kube-version相同--tf-vars strings路径列表指定覆盖 Terraform 的*.tfvars文件路径--tf-exclude-downloaded-modules布尔排除已下载的 Terraform 模块中的错误配置配置键misconfiguration.terraform.exclude-downloaded-modules。CI 环境中若无需审查第三方模块可显著减少输出噪音--cf-params strings路径列表指定覆盖 CloudFormation 参数parameters文件的路径--ansible-playbook strings路径列表指定要扫描的 Ansible playbook 文件路径--ansible-inventory strings主机路径/列表指定 Ansible inventory 主机路径或以逗号分隔的主机列表--ansible-extra-vars stringskeyvalue/file为 Ansible 设置额外变量支持keyvalue形式或file引用 YAML/JSON 变量文件--raw-config-scanners strings允许值terraform额外对原始配置执行扫描即把未适配的结构化配置放入共享状态再评估。默认空--render-cause strings允许值terraform,ansible在 table 报告中展示指定配置类型的渲染后 cause。默认空--config-file-schemas strings路径列表指定 JSON 配置文件 schema 路径用于判断某文件匹配何种配置、并把 schema 传给 Rego check 做类型检查--k8s-version string字符串指定 Kubernetes 版本如1.21.0用于校验过期的 Kubernetes API。该命令仅保留这一个 k8s 相关选项见 pkg/commands/app.go#L716-L719Rego 自定义策略与 checks bundle 相关选项内置规则由 OCI 形态的 checks bundle 下发同时支持以 Rego 编写自定义策略。这些选项定义于 pkg/flag/rego_flags.go。选项默认值说明--checks-bundle-repository stringmirror.gcr.io/aquasecurity/trivy-checks:2拉取 checks bundle 的 OCI 仓库地址配置键misconfiguration.checks-bundle-repository。注意旧选项名--policy-bundle-repository已废弃--skip-check-updatefalse跳过拉取/更新 Rego checks bundle配合离线环境或固定版本规则使用别名--skip-policy-update已废弃--config-check strings无指定自定义 Rego check 文件的路径或包含它们的目录配置键rego.check。旧别名--policy、--config-policy已废弃--config-data strings无指定用于 Rego 规则评估的数据文件/目录其中的数据会被递归加载配置键rego.data--check-namespaces strings无自定义 Rego 规则所在的名字空间配置键rego.namespaces评估时会从这些命名空间加载规则--include-deprecated-checksfalse是否包含已被弃用的内置 check--rego-error-limit int10Rego 策略评估期间允许的最大编译错误数配置键rego.error-limit默认值来自 Rego 引擎的DefaultAllowedRegoErrors--trace-regofalse为自定义查询开启更详细的 Rego trace 输出配置键rego.trace排查自定义策略时非常有用结合 docs/guide/scanner/misconfiguration/custom 与教程 docs/tutorials/misconfiguration/custom-checks.md 可编写自有策略基本形态为--config-check ./policy --check-namespaces user。仓库中的 examples/ignore-policies/basic.rego 与 examples/ignore-policies/advanced.rego 提供了可直接参考的 Rego 片段。文件过滤与跳过选项选项默认值说明--skip-files strings无按文件名或 glob 模式跳过文件配置键scan.skip-files--skip-dirs strings无按目录或 glob 模式跳过目录配置键scan.skip-dirs例如排除vendor、.terraform等目录--file-patterns strings无指定需要匹配的配置文件模式用于自定义哪些文件算配置文件--include-non-failuresfalse在输出中同时包含通过无失败的检查结果仅配合 misconfig 扫描使用配置键misconfiguration.include-non-failures--severity strings-sUNKNOWN,LOW,MEDIUM,HIGH,CRITICAL要展示的问题级别可按需缩小为HIGH,CRITICAL等--ignorefile string.trivyignore指定 ignore 文件格式参考 docs/guide/configuration/filtering.md可用于按 rule ID 忽略特定检查--ignore-policy string无指定用于评估每条漏洞/问题的 Rego 文件路径实现细粒度豁免策略--skip-version-checkfalse抑制版本更新提示与 Trivy 公告--disable-telemetryfalse禁止向 Aqua 发送匿名使用数据从 pkg/commands/app.go#L689-L697 可以看出trivy config在完整 ScanFlagGroup 中只启用了上述--skip-dirs、--skip-files、--file-patterns、--skip-version-check、--disable-telemetry其余通用扫描标志被有意关闭。报告与输出选项选项默认值说明--format string-ftable输出格式。允许值table、json、template、sarif、cyclonedx、spdx、spdx-json、github、cosign-vuln--report stringall合规报告输出形式允许值all或summary。源码注释表明未来计划支持非合规报告的 summary 模式--template string-t无自定义模板模板文件路径必须以.tpl结尾需与--format template搭配。仓库内建模板示例见 contrib/html.tpl、contrib/junit.tpl、contrib/sarif.tpl 等--table-mode stringssummary,detailed实验性选项控制table格式中显示哪些表格允许值summary、detailed。注意源码中若与--format table之外的格式混用会直接报错--output string-o无将结果写入文件而非 stdout--output-plugin-arg string无实验性传给输出插件的参数--exit-code int0当发现安全问题且其严重度命中--severity过滤时进程退出码设为该值CI 中断门使用--compliance string无生成指定合规报告的扫描结果例如--compliancecis-v1.5之类内置规范或/path/to/spec.yaml自定义规范更多见 docs/guide/compliance/compliance.md关于模板的取舍源码 pkg/flag/report_flags.go#L220-L236 内置了校验逻辑当指定--template但格式不是template时打印告警并忽略模板反之若--format template而未指定模板同样告警。缓存相关选项trivy config的命令级默认缓存后端被改为memory见 pkg/commands/app.go#L706-L707因此在单次调用中默认不做磁盘缓存。选项默认值说明--cache-backend stringmemory该命令级覆盖实验性缓存后端。例如redis://localhost:6379。注意通用 flag 定义默认值在 pkg/flag/cache_flags.go#L25-L30 中为fs此处被 config 命令覆盖为memory--cache-ttl duration无使用 Redis 作为缓存后端时的缓存 TTL--redis-tlsfalse使用 Redis 缓存后端时启用 TLS基于公共证书--redis-ca string无Redis CA 证书文件路径--redis-cert string无Redis 客户端证书文件路径--redis-key string无Redis 客户端私钥文件路径模块与凭据选项选项说明--enable-modules strings实验性启用的 WASM 模块名需要扫描逻辑扩展时使用插件体系参见 docs/guide/advanced/modules.md--module-dir stringWASM 模块目录默认$HOME/.trivy/modules--registry-token string私有镜像仓库访问令牌当目标配置引用私有仓库资源时使用--username strings用户名支持逗号分隔多个安全起见生产环境建议用环境变量替代--password strings密码支持逗号分隔多个文档明确提示出于安全考虑应使用TRIVY_PASSWORD环境变量--password-stdin从标准输入读取密码不支持逗号分隔多个密码-h, --help显示 config 子命令帮助从父命令继承的全局选项这些选项对所有 Trivy 子命令通用定义于 pkg/flag/global_flags.go选项默认值说明-c, --config stringtrivy.yaml指定配置文件路径--generate-default-configfalse将默认配置写入当前目录的trivy-default.yaml-d, --debugfalse开启调试模式-q, --quietfalse抑制进度条与日志输出--timeout duration5m0s整体超时时间--cache-dir string/path/to/cache缓存目录示例占位路径实际随平台而定--cacert string无PEM 格式 CA 证书路径--insecurefalse允许不安全的服务器连接-v, --versionfalse显示版本典型用法示例# 扫描当前目录下的 IaC/配置文件Dockerfile、Terraform、K8s YAML 等自动识别 trivy config . # 只扫描指定类型的配置并只输出高危及以上 trivy config --misconfig-scanners terraform,kubernetes \ --severity HIGH,CRITICAL . # 以 JSON 输出并写入文件供后续程序消费 trivy config --format json --output result.json ./infra # 在 CI 中作为质量门禁发现问题即以退出码 1 结束 trivy config --exit-code 1 --severity HIGH,CRITICAL ./deploy # 渲染 Helm Chart 前先用自定义 values 试扫 trivy config --helm-values values-prod.yaml --helm-kube-version 1.28.0 ./chart # 加载自定义 Rego 检查与数据 trivy config --config-check ./policy --config-data ./data --check-namespaces user . # 跳过自动拉取 checks bundle离线环境 trivy config --skip-check-update .一次性扫描时trivy config .默认不落盘缓存--cache-backend memory若在 CI 中反复扫描同一目录并希望加速可显式改用磁盘/Redis 后端例如--cache-backend redis://localhost:6379。命令行选项与配置文件、环境变量的对应关系trivy config的所有选项都可以沉淀到trivy.yaml默认由-c指定。源码中每个 flag 都带有ConfigName例如--misconfig-scanners→misconfiguration.scanners--helm-set→misconfiguration.helm.set--tf-vars→misconfiguration.terraform.vars--cf-params→misconfiguration.cloudformation.params--config-check→rego.check--rego-error-limit→rego.error-limit--cache-backend→cache.backend--severity→severity--skip-dirs→scan.skip-dirs参考 examples/trivy-conf/trivy.yaml 展示的写法对应到 misconfig 场景的配置片段形如severity: - HIGH - CRITICAL exit-code: 1 misconfiguration: scanners: - terraform - kubernetes terraform: vars: - env.tfvars checks-bundle-repository: mirror.gcr.io/aquasecurity/trivy-checks:2 scan: skip-dirs: - .terraform rego: check: - policy namespaces: - user此外用户名/密码等敏感参数建议通过TRIVY_*环境变量注入例如TRIVY_PASSWORD避免在命令行与 CI 日志中明文泄露。通用配置机制的更多细节见 docs/guide/configuration/index.md。背后执行流程从命令到扫描trivy config在源码层是一个精简配置器 复用通用管线的实现理解它有助于预测命令行为组装 flag 组NewConfigCommand仅组合全局、缓存、Misconf、Module、Registry、Rego、报告与裁剪后的扫描 flag 组并将缓存后端默认值覆盖为memorypkg/commands/app.go#L688-L722裁剪报告选项禁用与本命令无关的--dependency-tree、--list-all-pkgs、--exit-on-eol、--show-suppressedpkg/commands/app.go#L699-L704绑定与转换通过configFlags.Bind(cmd)绑定 Cobra 标志再由ToOptions汇总为统一的Options锁定扫描目标RunE中把 OS 与语言分析器全部加入DisabledAnalyzers把Scanners固定为MisconfigScannerpkg/commands/app.go#L744-L748进入通用文件系统扫描以TargetFilesystem调用artifact.Run复用与trivy fs相同的分析、检测与报告流水线。因此trivy config的结果结构与trivy fs --scanners misconfig一致可无缝对接 SARIF、JUnit 等下游工具模板见 contrib。与其他子命令及配套文档的关系本命令的父命令为 trivyUnified security scanner错误配置扫描的整体概念与检查规则见 docs/guide/scanner/misconfiguration/index.md各配置类型Dockerfile、Kubernetes、Terraform、CloudFormation、Helm、Ansible、Azure ARM 等的检测细节见 docs/guide/scanner/misconfiguration/config/config.md自定义 Rego 策略开发参见 docs/guide/scanner/misconfiguration/custom 与教程 docs/tutorials/misconfiguration/custom-checks.md若同时需要扫描漏洞与密钥应改用trivy fs/trivy repo并配合--scanners vuln,secret,misconfig。小结trivy config提供了一条聚焦 IaC 与配置文件的扫描路径一条命令即可覆盖 Dockerfile、Terraform、CloudFormation、Kubernetes、Helm、Ansible、Azure ARM 等主流声明式配置支持通过 Helm values/tfvars/CF 参数/Ansible 变量注入真实渲染上下文并允许以 Rego 自定义规则与 JSON schema 扩展检测能力。结合--exit-code、--severity、--format sarif/json等选项它可直接作为 IaC 上线前的自动化质量门禁而其禁用无关分析器、固定 misconfig 扫描器的实现细节也决定了它能保持输出聚焦、语义清晰的特点。【免费下载链接】trivyFind vulnerabilities, misconfigurations, secrets, SBOM in containers, Kubernetes, code repositories, clouds and more项目地址: https://gitcode.com/GitHub_Trending/tr/trivy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考