Trivy 内置合规报告与自定义 Compliance Spec 完全指南：从 CIS/NSA 基准扫描到企业自定义合规策略

Trivy 内置合规报告与自定义 Compliance Spec 完全指南：从 CIS/NSA 基准扫描到企业自定义合规策略

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

本指南以 docs/guide/compliance/compliance.md 为主体，结合pkg/compliance/目录下的源码实现进行验证与纵深解读。阅读对象为希望用 Trivy 快速产出 CIS、NSA、Pod Security Standards 等业界合规评估，或希望将企业自身安全基线固化为可复用报告的安全工程师与平台工程团队。

Compliance（合规）能力让 Trivy 从"一次扫描输出上百条独立检查结果"升级为"围绕一组既定控制项（Control）给出针对性评估报告"。在默认的 Trivy 扫描中，针对容器、Kubernetes、云资源等会执行成百上千条不同组件与配置的检查；但很多时候你并不需要全部结果，而是只关心某几组明确的问题——例如 CIS 基准、某个厂商规范，或自己组织内部的合规策略。Trivy 内置了一套灵活的合规基础设施：合规报告（Compliance Report）本质上只是一份用 YAML 描述的清单，用来挑选需要进入报告的检查项。本文覆盖该功能的运行方式、内置报告清单、报告 YAML 的完整字段说明，以及如何把一个新基准（Benchmark）贡献为内置报告、如何编写完全自定义的报告，并用 pkg/compliance/spec 与 pkg/compliance/report 的源码解释其底层执行原理。

⚠️EXPERIMENTAL：该特性仍处于实验阶段，后续版本可能在不保证向后兼容的情况下发生变化（compliance.md 开头的原始标注即为此意）。

一、合规报告的使用方式

1.1 支持的扫描目标

截至当前仓库版本，合规报告在以下两个 Trivy 子命令中受支持：

• trivy image—— 扫描容器镜像（针对镜像配置）
• trivy k8s—— 扫描 Kubernetes 集群

使用方式是在命令行中加入--compliance参数，并把它的值设置为想要评估的报告。例如（本仓库 docs/guide/target/kubernetes.md 中同样给出了该示例）：

trivy k8s cluster --compliance k8s-nsa

1.2 与--compliance兼容的选项

以上四项组合即为合规输出的主要定制维度：summary/all决定粒度，table/json决定载体。这一点也能从源码得到印证——pkg/compliance/report/report.go 中Write()的 switch 分支只接受json与table两种格式，其余格式直接报错unknown format %q. Use "json" or "table"；而Option.Report字段（对应--report）随后会被 table.go 与 json.go 两个 Writer 读取，从而决定渲染"摘要"还是"全部"。

另一个值得注意的行为在 pkg/flag/options.go：一旦--compliance被指定，Trivy 会禁用用户对扫描器（scanners）与镜像配置扫描器的手动调整，直接采用默认扫描器组合，并打印如下提示：

The option to change scanners is disabled for scanning with the "--compliance" flag. Default scanners used.

这是因为合规报告必须按 Spec 中引用的检查 ID 反推所需的扫描器集合（详见下文"自定义合规报告的 Check ID"），不允许用户自行加减。

1.3 报告的两种粒度的实际效果

• --report summary：报告为"每个 Control + 失败数量"的汇总视图。报告数据模型对应源码中的SummaryReport/ControlCheckSummary（仅含ID、Name、Severity、TotalFail，见 report.go）。
• --report all：每个 Control 下附带其关联检查的全部明细结果（对应ComplianceReport/ControlCheckResult，见 report.go），其中DefaultStatus表示该控制项在未检测到资源时的默认状态（源码中预定义了FAIL/PASS/WARN三种状态，见 pkg/compliance/spec/compliance.go）。

1.4 结合目标文档的完整示例

由于--compliance属于报告输出层的统一入口，内置清单随目标不同而不同。以下命令均来自目标文档，可在你的环境直接执行：

# 容器镜像：Docker CIS 基准合规（summary 报告） trivy image --compliance docker-cis-1.6.0 [YOUR_IMAGE_NAME] # 集群：Pod Security Standards Baseline 合规 trivy k8s --compliance=k8s-pss-baseline --report summary # 集群：CIS Kubernetes v1.23 完整明细 trivy k8s --compliance=k8s-cis-1.23 --report all # 集群：CIS Kubernetes v1.23 摘要 + JSON（供机器消费） trivy k8s --compliance=k8s-cis-1.23 --report summary --format json # 集群：CIS Kubernetes v1.23 完整明细 + JSON trivy k8s --compliance=k8s-cis-1.23 --report all --format json

注意：镜像类合规报告中表格的Issues列表示该控制项下失败的检查总数，这一约定在 docs/guide/target/container_image.md 的Compliance小节中有明确说明。

二、内置合规报告（Built-in Compliance）

Trivy 开箱即用提供若干内置合规报告。指定方式是按 ID 选择，形如trivy --compliance <compliance_id>。

2.1 Kubernetes 目标的内置报告

根据 docs/guide/target/kubernetes.md 的Compliance小节，trivy k8s目标内置以下报告：

该清单与源码 pkg/types/report.go 中BuiltInK8sCompliances变量完全一致。此外 Trivy 的全局支持集合SupportedCompliances（report.go）还包含 AWS 相关的aws-cis-1.2、aws-cis-1.4与 Docker 的docker-cis-1.6.0。因此若在--compliance后填入不在该集合内、且不以@开头的字符串，命令行解析阶段就会直接报unknown compliance错误——该校验位于 pkg/flag/report_flags.go。

2.2 容器镜像目标的内置报告

根据 docs/guide/target/container_image.md 的Compliance小节：

trivy image --compliance docker-cis-1.6.0 [YOUR_IMAGE_NAME]

镜像合规扫描针对的是镜像构建与运行配置（如 Dockerfile 指令、USER 设置、健康检查等镜像配置层信息），评估 Docker CIS 基准中的对应条目。

2.3 与 Kubernetes 集群扫描联动：Node-Collector

Kubernetes 集群合规（特别是 CIS 类基准）依赖节点级数据。Trivy 的node-collector是一个扫描任务（scan job），负责收集节点的配置参数与权限信息，这些信息随后会被用来对照 Kubernetes 加固基准（如 CIS benchmark）与最佳实践值进行评估，最终呈现在基础设施评估与 CIS 合规报告中。相关说明详见 docs/guide/target/kubernetes.md 的Node-Collector小节，可用控制项包括：

# 关闭节点采集任务（排除 Node 基础设施相关的合规发现） trivy k8s --report summary --disable-node-collector # 为采集任务添加容忍（taint/toleration），使其能调度到被污染节点 trivy k8s --report summary --tolerations key1=value1:NoExecute,key2=value2:NoSchedule # 通过节点标签排除某些节点（格式 label-name:label-value） trivy k8s --report summary --exclude-nodes kubernetes.io/arch:arm6

三、把一个合规基准定义成内置报告（贡献规范）

这一章面向想要为 Trivy 贡献一个新内置合规报告（例如新版本 CIS Benchmark）的开发者。合规报告的载体是"合规 Spec"（Compliance Spec）YAML 文件，社区贡献的整体流程与仓库规范见 docs/guide/compliance/contrib-compliance.md。其核心是：先在 Trivy 配套的trivy-checks项目中按规范存放检查（checks）与命令（commands）描述，再在此仓库通过 Spec 把它们组装成报告，最后经由 magefile 等流程内嵌进二进制（compliance.GetSpec()走的就是"内嵌库"路径，见 pkg/compliance/spec/compliance.go）。

3.1 定义一份基于 CIS Benchmark 或其它规范的 Spec

以下是一份 CIS 合规报告的 YAML 示例（即本指南主体文档中的原始示例）：

--- spec: id: k8s-cis-1.23 title: CIS Kubernetes Benchmarks v1.23 description: CIS Kubernetes Benchmarks platform: k8s type: cis version: '1.23' relatedResources: - https://www.cisecurity.org/benchmark/kubernetes controls: - id: 1.1.1 name: Ensure that the API server pod specification file permissions are set to 600 or more restrictive description: Ensure that the API server pod specification file has permissions of 600 or more restrictive checks: - id: AVD-KCV-0073 commands: - id: CMD-0001 severity: HIGH

该 YAML 在源码侧对应 pkg/compliance/spec/compliance.go 的ComplianceSpec{ Spec iacTypes.Spec }结构：Spec内包含id、title、description、platform、type、version、relatedResources以及一组controls。每个control至少包含自己的id/name/description/severity，以及它要引用的检查集合（checks[].id）与（k8s 节点采集场景下的）命令集合（commands[].id）。

3.2 Compliance ID（报告 ID）

id字段是在执行合规扫描时传给 trivy 的名字。例如，上面 YAML 定义的报告可通过以下命令执行：

trivy k8s --compliance k8s-cis-1.23

ID 命名约定：{platform}-{type}-{version}（例如k8s-cis-1.23= 平台k8s+ 类型cis+ 版本1.23）。文件名也遵循类似的"平台-类型-版本"模式，见 contrib-compliance.md。

3.3 Compliance Platform（平台）

platform字段指定该合规报告要运行在何种平台之上。支持取值：

• k8s：原生 Kubernetes 集群
• eks：Amazon Elastic Kubernetes Service
• aks：Azure Kubernetes Service
• gke：Google Kubernetes Engine
• rke2：Rancher Kubernetes Engine v2
• ocp：OpenShift Container Platform
• docker：Docker 引擎
• aws：Amazon Web Services

平台字段影响两件事：一是 Spec 内部平台相关检查的选取，二是当平台涉及节点级数据采集时，命令配置文件（见 3.9 节）如何定位各平台的二进制与配置文件路径。

3.4 Compliance Type（类型）

type字段指定合规报告的种类，可取：

• cis：Center for Internet Security
• nsa：National Security Agency
• pss：Pod Security Standards

3.5 Compliance Version（版本）

version字段指定合规报告所对应的基准版本，例如1.23。注意它是字符串类型，因此 YAML 中建议用引号包裹（如'1.23'），避免被 YAML 解析器当作浮点数而丢失精度。

3.6 Compliance Check ID（检查 ID）

controls[].checks[].id引用一条具体检查（check）。该检查需要根据命令数据（command data）的输出评估控制项是否满足，通常用 Rego 编写。一个检查在trivy-checks项目的checks目录下以"METADATA 注释头 + Rego 规则体"的形式定义，例如评估kubelet.conf文件权限是否为 600 或更严格的检查：

# METADATA # title: "Ensure that the --kubeconfig kubelet.conf file permissions are set to 600 or more restrictive" # description: "Ensure that the kubelet.conf file has permissions of 600 or more restrictive." # scope: package # schemas: # - input: schema["kubernetes"] # related_resources: # - https://www.cisecurity.org/benchmark/kubernetes # custom: # id: KCV0073 # avd_id: AVD-KCV-0073 # severity: HIGH # short_code: ensure-kubelet.conf-file-permissions-600-or-more-restrictive. # recommended_action: "Change the kubelet.conf file permissions to 600 or more restrictive if exist" # input: # selector: # - type: kubernetes package builtin.kubernetes.KCV0073 import data.lib.kubernetes types := ["master", "worker"] validate_kubelet_file_permission(sp) := {"kubeletConfFilePermissions": violation} { sp.kind == "NodeInfo" sp.type == types[_] violation := {permission | permission = sp.info.kubeletConfFilePermissions.values[_]; permission > 600} count(violation) > 0 } deny[res] { output := validate_kubelet_file_permission(input) msg := "Ensure that the --kubeconfig kubelet.conf file permissions are set to 600 or more restrictive" res := result.new(msg, output) }

Spec 中引用它时，使用的就是 METADATA 头里声明的avd_id：AVD-KCV-0073。这段 Rego 也直观展示了上文中NodeInfo输入结构（input.kind == "NodeInfo"）是如何承载节点采集数据的。

从源码理解 Check ID 的前缀规则：在 pkg/compliance/spec/compliance.go 的scannerByCheckID()中，Trivy 根据检查 ID 前缀反推应启用的扫描器：

• cve-/dla-/vuln-前缀 → 漏洞扫描器（VulnerabilityScanner）
• secret-前缀 → 密钥扫描器（SecretScanner）
• avd-前缀，或以aws、azu、gcp、ksv、kcv、kube、opnstk、nif、dig、oci、cldstk、git、ds等已知前缀开头 → 配置扫描器（MisconfigScanner）
• 其余 →UnknownScanner，直接报unsupported check ID错误

这就是为什么自定义报告的 check ID 必须遵循特定前缀格式，而不是任意字符串。

3.7 Compliance Command ID（命令 ID）与节点采集

注意：commands字段并非必填，它只在启用 node-collector 的 k8s 合规报告中相关。

commands[].id指定为了评估控制项而需要执行的采集命令 ID。命令本体在trivy-checks项目的commands目录下定义。例如：

--- - id: CMD-0001 key: kubeletConfFilePermissions title: kubelet.conf file permissions nodeType: worker audit: stat -c %a $kubelet.kubeconfig platforms: - k8s - aks

各子字段的约定如下。

Command ID

命令 ID 是顺序编号。可在trivy-checks项目中运行以下命令取得下一个可用 ID：

make command-id

Command Key

key用于标识采集结果对应的字段名。可以复用已有 key，也可以定义新 key（确保 key 名不含空格）。关键约束是：key 的值必须与 Rego 检查求值时使用的字段名保持一致——对照上一节 Rego 中的sp.info.kubeletConfFilePermissions，其字段来源正是 key 为kubeletConfFilePermissions的命令输出。

Command Title

title描述该命令的用途。

Command NodeType

nodeType指定命令应在哪类节点上运行：

• worker
• master

Command Audit

audit填写实际要执行的 shell 命令。官方建议加上错误抑制2>/dev/null，避免权限不足或文件不存在时把噪音写入采集结果。

Command Platforms

platforms列出支持该命令的平台列表，名称需取自上文 Compliance Platform 的枚举。

3.8 Node-Collector 输出

node-collector 会读取命令并逐条执行，把输出合并进NodeInfo资源。结合 3.6 节的 Rego 样例（sp.info.kubeletConfFilePermissions.values[_]）可以看懂下面的输出结构：

{ "apiVersion": "v1", "kind": "NodeInfo", "metadata": { "creationTimestamp": "2023-01-04T11:37:11+02:00" }, "type": "master", "info": { "adminConfFileOwnership": { "values": [ "root:root" ] }, "adminConfFilePermissions": { "values": [ 600 ] } ... } }

NodeInfo.kind、.type与.info直接对应 Rego 规则中sp.kind、sp.type、sp.info的求值路径，实现了"命令采集 → NodeInfo 结构化输入 → Rego 检查 → 控制项评估"的完整链路。

3.9 Command Config Files（命令配置文件）

命令执行依赖一份配置文件，用于按不同平台（例如 Rancher、原生 Kubernetes 等）定位各组件二进制与配置文件的路径。例如：

kubelet: bins: - kubelet - hyperkube kubelet confs: - /etc/kubernetes/kubelet-config.yaml - /var/lib/kubelet/config.yaml

bins列举可执行文件候选名（兼容hyperkube kubelet这类间接启动方式），confs列举配置文件候选路径。node-collector 会依据这份清单在目标节点上解析出$kubelet.kubeconfig之类的路径变量，再展开执行audit中的命令。

3.10 文件位置约定

在 Trivy 的配套规则仓库（trivy-checks）中：

• 检查（check）文件位于checks目录（Rego 源文件）；
• 命令（command）文件位于commands目录；
• 命令配置文件同样位于commands目录下。

当你贡献新的合规基准时，需在这些目录里放置好对应的检查、命令与命令配置文件，再在本仓库侧编写/更新 Spec 并完成验证与发布。

3.11 完整的贡献闭环（在 Trivy 中验证新 Spec）

trivy-checks项目提供make command-id之类的辅助目标管理命令编号。定义完成后，参照 docs/guide/compliance/contrib-compliance.md 中的两种控制项填充方式：

1. 引用 Trivy 已有检查：若检查已存在于trivy-checks（例如AVD-KCV-0070），直接从通用 Spec（如k8s-cis-1.23.yaml）中复用其id/severity，仅需替换为当前基准的id/name/description；
2. 手动登记缺失检查：若检查尚未在 AVD 中注册，checks填null，将id、name、description从官方合规报告（如 EKS CIS v1.4.0）中摘录，severity 取报告给定值（报告未给定时通常使用MEDIUM）。

随后通过--compliance传入新 Spec 路径进行端到端验证：

trivy k8s cluster --compliance @</path/to/compliance.yaml> --report summary

注意：文件路径前必须带@前缀。

四、自定义合规报告（Custom Compliance）

你完全不需要修改 Trivy 本体，就能创建属于自己的合规报告。一份自定义合规报告就是一个按如下格式书写的 YAML 文档：

spec: id: "k8s-myreport" # report unique identifier. this should not contain spaces. title: "My custom Kubernetes report" # report title. Any one-line title. description: "Describe your report" # description of the report. Any text. relatedResources : - https://some.url # useful references. URLs only. version: "1.0" # spec version (string) controls: - name: "Non-root containers" # Name for the control (appears in the report as is). Any one-line name. description: 'Check that container is not running as root' # Description (appears in the report as is). Any text. id: "1.0" # control identifier (string) checks: # list of existing Trivy checks that define the control - id: AVD-KSV-0012 # check ID. Must start with `AVD-` or `CVE-` severity: "MEDIUM" # Severity for the control (note that checks severity isn't used) - name: "Immutable container file systems" description: 'Check that container root file system is immutable' id: "1.1" checks: - id: AVD-KSV-0014 severity: "LOW"

字段要点：

• spec.id是报告唯一标识符，不能包含空格；
• spec.title/spec.description是出现在报告中的标题与描述，取任意单行文本即可；
• spec.relatedResources仅接受 URL，作为有用参考；
• spec.version是 Spec 版本（字符串）；
• 每个control需提供展示用的name、description、id，以及checks列表中现存 Trivy 检查的 AVD ID 集合；
• 关键约定：check ID 必须以AVD-或CVE-开头。这与 pkg/compliance/spec/compliance.go 中scannerByCheckID()的前缀分派逻辑一致（AVD- 归入配置扫描器、CVE- 归入漏洞扫描器）；因此你也可以在合规控制项中直接引用具体的 CVE 编号，让报告呈现"某版本组件是否命中指定 CVE"的判定；
• 控制项的severity直接决定其在报告中的严重级别（注意：这里不使用被引用检查自身的 severity）；
• checks[].id引用的是检查的 "AVD ID"。该 ID 可以方便地在检查源码的 METADATA 头中找到（如avd_id: AVD-KSV-0012），也可以在 Aqua Vulnerability Database 的 Misconfigurations 与 Vulnerabilities 分区中检索到。Trivy 社区贡献的新 Spec 一律以这类业界基准为蓝本，存放于配套规则仓库的pkg/specs/compliance/目录，文件名遵循"provider-resource-spectype-version"格式（如aws-eks-cis-1.4.yaml），详情参考 contrib-compliance.md。

写好 YAML 后，用文件路径方式选择该报告（注意@表示"文件路径"而非"报告 ID"）：

trivy --compliance @</path/to/compliance.yaml>

例如结合k8s子命令：

trivy k8s cluster --compliance @</path/to/compliance.yaml> --report all

自定义 ID 的高级用法：按严重级别筛选

除了引用具体的AVD-/CVE-检查外，从源码 pkg/compliance/spec/custom.go 可以看到 Trivy 还内置了四类"伪检查 ID"：

它们与前缀规则相呼应（vuln-/secret-同样在 compliance.go 中被识别为对应扫描器），允许你的自定义报告定义"集群不得存在 CRITICAL 漏洞"这类基于严重级别的控制项。

自定义报告的加载与校验顺序

从 pkg/compliance/spec/compliance.go 的GetComplianceSpec()可以看到，--compliance取值有三种来源，按如下优先级解析：

1. 以@开头 → 直接从本地磁盘路径读取用户 Spec 文件（os.ReadFile）；
2. 缓存目录存在策略包（policy/metadata.json）→ 从磁盘 bundle 加载<cacheDir>/policy/content/specs/compliance/<id>.yaml（LoadFromBundle）；
3. 否则回退到编译期内嵌库compliance.GetSpec(specNameOrPath)。

任一来源读到的字节都会经yaml.Unmarshal解析为ComplianceSpec，校验失败会报spec yaml decode error。而命令行的"未知合规 ID"预检则发生在更早的参数阶段（见 report_flags.go 的loadComplianceTypes）。

五、从扫描结果到合规报告：底层执行链路

把以上各章串起来，一次合规扫描在源码中的实际数据流如下（便于你在阅读代码时定位）：

1. 参数解析：--compliance的值经 pkg/flag/report_flags.go 传入loadComplianceTypes，合法性校验通过后调用spec.GetComplianceSpec()得到ComplianceSpec（compliance.go）。
2. 扫描器推导：ComplianceSpec.Scanners()遍历全部控制项与检查，通过scannerByCheckID()汇总所需的扫描器集合（compliance.go）；CheckIDs()则生成scanner → []checkID的映射，供后续过滤。
3. 常规扫描：按推导出的扫描器对目标执行标准扫描（pkg/flag/options.go 会在此阶段屏蔽用户对 scanners 的手动修改）。
4. 结果映射：spec.AggregateAllChecksBySpecID()遍历每个扫描结果，用MapSpecCheckIDToFilteredResults()把命中 Spec 检查 ID 的漏洞/配置问题（以及custom.go中的自定义严重级别过滤器）从全量结果中"抽取"并按 check ID 归组（见 pkg/compliance/spec/mapper.go）。
5. 报告组装与输出：report.BuildComplianceReport()把归组结果重新挂到每个 Control 下（pkg/compliance/report/report.go），最后依据--report summary/all与--format table/json的组合，由Write()分发到 summary.go、table.go、json.go 完成渲染。

六、实践建议与注意事项

• 先 summary 后 all：对大型集群，建议先用--report summary快速定位失败集中区域，再针对具体控制项用--report all获取明细；从源码 table.go 的渲染逻辑可以看出，摘要视图聚焦于"每个 Control 的失败计数"，最便于汇报与分级跟进。
• 机器消费请用 JSON：--format json输出ComplianceReport/SummaryReport的标准结构，可直接对接 CI、工单系统或内部合规仪表盘；json 序列化测试见 json_test.go。
• 不要试图在合规扫描里手动改 scanners：一旦启用--compliance，Trivy 会自动采用默认扫描器并忽略相关手动设置（options.go），这与 Spec 按 ID 反推扫描器的模型是强耦合的。
• 理解实验性：合规特性当前仍标注为 EXPERIMENTAL，报告字段与行为在后续版本可能调整；在做长期集成时留意升级日志（CHANGELOG.md）。
• 定制从 YAML 开始：先通过自定义报告（@path）在企业内部验证控制项集合与严重级别是否合适，再决定是否走社区贡献流程把它固化为内置 Spec，这是成本最低的演进路径。

相关深入资料可在仓库内继续阅读：合规总览文档、社区贡献合规 Spec 指南、Kubernetes 目标文档、容器镜像目标文档，以及上述各源码文件。

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