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-nsa1.2 与--compliance兼容的选项flag作用--report summary输出结果摘要针对每个控制项显示失败检查的数量--report all输出完整明细结果针对每个控制项显示在何处失败、为何失败--format table以文本表格形式输出结果适合人类阅读--format json以 JSON 格式输出结果适合机器解析与下游系统集成以上四项组合即为合规输出的主要定制维度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 --compliancek8s-pss-baseline --report summary # 集群CIS Kubernetes v1.23 完整明细 trivy k8s --compliancek8s-cis-1.23 --report all # 集群CIS Kubernetes v1.23 摘要 JSON供机器消费 trivy k8s --compliancek8s-cis-1.23 --report summary --format json # 集群CIS Kubernetes v1.23 完整明细 JSON trivy k8s --compliancek8s-cis-1.23 --report all --format json注意镜像类合规报告中表格的Issues列表示该控制项下失败的检查总数这一约定在 docs/guide/target/container_image.md 的Compliance小节中有明确说明。二、内置合规报告Built-in ComplianceTrivy 开箱即用提供若干内置合规报告。指定方式是按 ID 选择形如trivy --compliance compliance_id。2.1 Kubernetes 目标的内置报告根据 docs/guide/target/kubernetes.md 的Compliance小节trivy k8s目标内置以下报告合规基准命令中使用的名称说明NSA、CISA Kubernetes 加固指引 v1.0k8s-nsa-1.0面向防御性加固场景的 NSA/CISA 指引CIS Kubernetes 基准 v1.23k8s-cis-1.23针对 API Server、etcd、kubelet、工作负载等的 CIS 检查CIS RKE2 基准 v1.24rke2-cis-1.24Rancher Kubernetes Engine v2 专用CIS EKS 基准 v1.4eks-cis-1.4Amazon EKS 专用Pod Security StandardsBaseline基线k8s-pss-baseline-0.1覆盖 Kubernetes PSS 的 Baseline 级别Pod Security StandardsRestricted受限k8s-pss-restricted-0.1覆盖 Kubernetes PSS 的 Restricted 级别该清单与源码 pkg/types/report.go 中BuiltInK8sCompliances变量完全一致。此外 Trivy 的全局支持集合SupportedCompliancesreport.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小节合规基准命令中使用的名称CIS Docker Community Edition Benchmarkdocker-cis-1.6.0trivy image --compliance docker-cis-1.6.0 [YOUR_IMAGE_NAME]镜像合规扫描针对的是镜像构建与运行配置如 Dockerfile 指令、USER 设置、健康检查等镜像配置层信息评估 Docker CIS 基准中的对应条目。2.3 与 Kubernetes 集群扫描联动Node-CollectorKubernetes 集群合规特别是 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 key1value1:NoExecute,key2value2:NoSchedule # 通过节点标签排除某些节点格式 label-name:label-value trivy k8s --report summary --exclude-nodes kubernetes.io/arch:arm6三、把一个合规基准定义成内置报告贡献规范这一章面向想要为 Trivy 贡献一个新内置合规报告例如新版本 CIS Benchmark的开发者。合规报告的载体是合规 SpecCompliance SpecYAML 文件社区贡献的整体流程与仓库规范见 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报告 IDid字段是在执行合规扫描时传给 trivy 的名字。例如上面 YAML 定义的报告可通过以下命令执行trivy k8s --compliance k8s-cis-1.23ID 命名约定{platform}-{type}-{version}例如k8s-cis-1.23 平台k8s 类型cis 版本1.23。文件名也遵循类似的平台-类型-版本模式见 contrib-compliance.md。3.3 Compliance Platform平台platform字段指定该合规报告要运行在何种平台之上。支持取值k8s原生 Kubernetes 集群eksAmazon Elastic Kubernetes ServiceaksAzure Kubernetes ServicegkeGoogle Kubernetes Enginerke2Rancher Kubernetes Engine v2ocpOpenShift Container PlatformdockerDocker 引擎awsAmazon Web Services平台字段影响两件事一是 Spec 内部平台相关检查的选取二是当平台涉及节点级数据采集时命令配置文件见 3.9 节如何定位各平台的二进制与配置文件路径。3.4 Compliance Type类型type字段指定合规报告的种类可取cisCenter for Internet SecuritynsaNational Security AgencypssPod Security Standards3.5 Compliance Version版本version字段指定合规报告所对应的基准版本例如1.23。注意它是字符串类型因此 YAML 中建议用引号包裹如1.23避免被 YAML 解析器当作浮点数而丢失精度。3.6 Compliance Check ID检查 IDcontrols[].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_idAVD-KCV-0073。这段 Rego 也直观展示了上文中NodeInfo输入结构input.kind NodeInfo是如何承载节点采集数据的。从源码理解 Check ID 的前缀规则在 pkg/compliance/spec/compliance.go 的scannerByCheckID()中Trivy 根据检查 ID 前缀反推应启用的扫描器cve-/dla-/vuln-前缀 → 漏洞扫描器VulnerabilityScannersecret-前缀 → 密钥扫描器SecretScanneravd-前缀或以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项目中运行以下命令取得下一个可用 IDmake command-idCommand Keykey用于标识采集结果对应的字段名。可以复用已有 key也可以定义新 key确保 key 名不含空格。关键约束是key 的值必须与 Rego 检查求值时使用的字段名保持一致——对照上一节 Rego 中的sp.info.kubeletConfFilePermissions其字段来源正是 key 为kubeletConfFilePermissions的命令输出。Command Titletitle描述该命令的用途。Command NodeTypenodeType指定命令应在哪类节点上运行workermasterCommand Auditaudit填写实际要执行的 shell 命令。官方建议加上错误抑制2/dev/null避免权限不足或文件不存在时把噪音写入采集结果。Command Platformsplatforms列出支持该命令的平台列表名称需取自上文 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:1102: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.yamlbins列举可执行文件候选名兼容hyperkube kubelet这类间接启动方式confs列举配置文件候选路径。node-collector 会依据这份清单在目标节点上解析出$kubelet.kubeconfig之类的路径变量再展开执行audit中的命令。3.10 文件位置约定在 Trivy 的配套规则仓库trivy-checks中检查check文件位于checks目录Rego 源文件命令command文件位于commands目录命令配置文件同样位于commands目录下。当你贡献新的合规基准时需在这些目录里放置好对应的检查、命令与命令配置文件再在本仓库侧编写/更新 Spec 并完成验证与发布。3.11 完整的贡献闭环在 Trivy 中验证新 Spectrivy-checks项目提供make command-id之类的辅助目标管理命令编号。定义完成后参照 docs/guide/compliance/contrib-compliance.md 中的两种控制项填充方式引用 Trivy 已有检查若检查已存在于trivy-checks例如AVD-KCV-0070直接从通用 Spec如k8s-cis-1.23.yaml中复用其id/severity仅需替换为当前基准的id/name/description手动登记缺失检查若检查尚未在 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 isnt 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直接决定其在报告中的严重级别注意这里不使用被引用检查自身的 severitychecks[].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 后用文件路径方式选择该报告注意表示文件路径而非报告 IDtrivy --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自定义 ID作用VULN-CRITICAL仅保留 CRITICAL 级漏洞VULN-HIGH仅保留 HIGH 级漏洞SECRET-CRITICAL仅保留 CRITICAL 级密钥发现SECRET-HIGH仅保留 HIGH 级密钥发现它们与前缀规则相呼应vuln-/secret-同样在 compliance.go 中被识别为对应扫描器允许你的自定义报告定义集群不得存在 CRITICAL 漏洞这类基于严重级别的控制项。自定义报告的加载与校验顺序从 pkg/compliance/spec/compliance.go 的GetComplianceSpec()可以看到--compliance取值有三种来源按如下优先级解析以开头 → 直接从本地磁盘路径读取用户 Spec 文件os.ReadFile缓存目录存在策略包policy/metadata.json→ 从磁盘 bundle 加载cacheDir/policy/content/specs/compliance/id.yamlLoadFromBundle否则回退到编译期内嵌库compliance.GetSpec(specNameOrPath)。任一来源读到的字节都会经yaml.Unmarshal解析为ComplianceSpec校验失败会报spec yaml decode error。而命令行的未知合规 ID预检则发生在更早的参数阶段见 report_flags.go 的loadComplianceTypes。五、从扫描结果到合规报告底层执行链路把以上各章串起来一次合规扫描在源码中的实际数据流如下便于你在阅读代码时定位参数解析--compliance的值经 pkg/flag/report_flags.go 传入loadComplianceTypes合法性校验通过后调用spec.GetComplianceSpec()得到ComplianceSpeccompliance.go。扫描器推导ComplianceSpec.Scanners()遍历全部控制项与检查通过scannerByCheckID()汇总所需的扫描器集合compliance.goCheckIDs()则生成scanner → []checkID的映射供后续过滤。常规扫描按推导出的扫描器对目标执行标准扫描pkg/flag/options.go 会在此阶段屏蔽用户对 scanners 的手动修改。结果映射spec.AggregateAllChecksBySpecID()遍历每个扫描结果用MapSpecCheckIDToFilteredResults()把命中 Spec 检查 ID 的漏洞/配置问题以及custom.go中的自定义严重级别过滤器从全量结果中抽取并按 check ID 归组见 pkg/compliance/spec/mapper.go。报告组装与输出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一旦启用--complianceTrivy 会自动采用默认扫描器并忽略相关手动设置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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考