Kubescape v4.0.16 配置参数详解

目标：系统讲清 Kubescape CLI v4.0.16 的全部配置通道——命令行参数（scan 全参数族）、环境变量、缓存目录与 config 子命令、例外规则（exceptions）文件、框架/控件配置（NSA/CIS/MITRE 与 controls-inputs）与离线规则包（含离线 registry 凭据参数）。全部参数口径取自本机 --help 实测回显，关键行为均以实测验证，环境为 Ubuntu 22.04 + Kubescape v4.0.16。

一、环境信息

• 操作系统：Ubuntu 22.04.4 LTS（x86_64）
• Kubescape：v4.0.16（Build commit d0ea07b，2026-10-14 构建；安装过程见本专栏《Ubuntu 22.04 安装 Kubescape v4.0.16 指南》篇）
• 缓存目录：/root/.kubescape/（默认值，实测存在）
• 扫描样本：本机 manifests/ 目录 3 个含缺陷 YAML（特权 Pod、无资源限制 Deployment、cluster-admin RBAC 绑定）
• 参数口径来源：kubescape --help、kubescape scan --help（150 行）、各子命令 --help 全量实测

二、前置条件

1. 已按《Ubuntu 22.04 安装 Kubescape v4.0.16 指南》完成 kubescape CLI 安装，kubescape version 输出 Your current version is: v4.0.16（实测回显）。
2. 已有至少一个含 Kubernetes 资源的 YAML 文件用于验证参数效果（本文示例为 3 个缺陷 manifest）。
3. 联网环境（首次运行会下载规则包）；离线环境先按 8.3 节准备本地规则包目录。

三、参数查看与修改方式

Kubescape 是 CLI 形态工具，配置通过四条通道生效，按优先级与用途分工：

💡 技术拓展：K8s 安全工具的「参数/策略」分层普遍存在三层——CLI 参数（本次怎么扫）、控件配置 controls-inputs（规则阈值默认值）、例外策略 exceptions（哪些资源豁免）。Kubescape 的三层都能本地化（--controls-config、--exceptions、--use-artifacts-from），这意味着整套扫描策略可以进 Git 版本管理，CI 里的扫描结果才可复现。本文实际采用「CLI 参数 + 文件化 exceptions」组合，理由是扫描范围与豁免清单变更可评审、可回滚。

kubescape config 子命令族（实测 kubescape config --help）：

Handle cached configurations

Usage:
  kubescape config [command]

Examples:

  # View cached configurations
  kubescape config view

  # Validate cached configurations
  kubescape config validate

  # Delete cached configurations
  kubescape config delete

  # Set cached configurations
  kubescape config set --help

Available Commands:
  delete      Delete cached configurations
  set         Set configurations, supported: accessKey/accountID/cloudAPIURL/cloudReportURL
  validate    Validate cached configurations
  view        View cached configurations

config view 实测回显（本机 kubeconfig 存在 context kind-solr-op，Kubescape 以当前 context 名作为默认集群名缓存）：

clusterName: kind-solr-op

config set 支持四项：accessKey/accountID/cloudAPIURL/cloudReportURL——全部是 SaaS 上报通道凭据；纯离线用户用不到，也无需配置。

四、参数总览

4.1 全局参数（所有子命令共用）

实测 kubescape --help 全局段：

Flags:
      --cache-dir string      Cache directory [$KS_CACHE_DIR] (default "/root/.kubescape")
  -h, --help                  help for kubescape
      --kube-context string   Kube context. Default will use the current-context
  -l, --logger string         Logger level. Supported: debug/info/success/warning/error/fatal [$KS_LOGGER] (default "info")
      --server string         Backend discovery server URL

4.2 scan 参数族分组总览

kubescape scan --help 实测共 80+ 个参数，按用途分为七组（完整原文已落盘核对）：

五、核心参数分类详解

5.1 全局参数详解

1. --cache-dir（env KS_CACHE_DIR，默认 /root/.kubescape）：规则包与漏洞库缓存根目录。多套扫描实例共享缓存时重定向到大容量盘；实测缓存目录内含下载的 nsa.json（192310 字节）等规则文件。
2. --kube-context：扫描活集群时选择 kubeconfig 中的 context，缺省取 current-context（本机实测即 kind-solr-op）。
3. -l/--logger（env KS_LOGGER，默认 info）：日志级别，支持 debug/info/success/warning/error/fatal；排障参数行为时配 -l debug 与 --enable-rego-prints 可看到 Rego 求值过程。
4. --server：后端发现服务 URL，仅在对接自建/私有化后端时设置；纯 CLI 离线用法不涉及。

5.2 扫描目标与范围参数

5.3 策略与规则参数（框架/控件/例外）

5.4 输出与呈现参数

-f/--format（默认 pretty-printer）：实测帮助原文列出全部 15 种——"pretty-printer", "json", "junit", "prometheus", "pdf", "html", "sarif", "gitlab-sast", "github-actions", "yaml", "csv", "markdown", "cyclonedx-json", "spdx-json", "policyreport", "exceptions"。可一次多格式（--format json,html,junit --output result 为每种格式生成一个文件）。

-v/--verbose：默认只显示失败项摘要；加 -v 后逐资源列出失败控件（含控件文档链接）。实测对 3 文件目录扫描：

kubescape scan framework nsa manifests/01-privileged-pod.yaml --verbose

实测回显节选（每资源一段，含 Source/Kind/Name 与失败控件表）：

################################################################################
Source: tmp/kubescape/manifests/01-privileged-pod.yaml
ApiVersion: v1
Kind: Pod
Name: privileged-debug
Namespace: default

Controls: 14 (Failed: 9, action required: 0)

╭──────────┬──────────────────────────────────────┬────────────────────────────────────┬──────────────────────╮
│ Severity │ Control name                         │ Docs                               │ Assisted remediation │
├──────────┼──────────────────────────────────────┼────────────────────────────────────┼──────────────────────┤
│ Medium   │ Non-root containers                  │ https://hub.armosec.io/docs/c-0013 │ <nil>                │
...
│ High     │ Privileged container                 │ https://hub.armosec.io/docs/c-0057 │ <nil>                │
╰──────────┴──────────────────────────────────────┴────────────────────────────────────┴──────────────────────╯

--view（默认 security）：结果聚合视角，支持 resource/control/security/namespace。 -E/--show-evidence：pretty-printer 下显示每个失败控件的字段路径与当前值（证据链）；默认脱敏 Secret 值，--show-secrets 才显示明文。 --hide：报告元数据确定性匿名化（对外分享报告用）。 --encrypt：用 KUBESCAPE_MASTER_KEY（≥16 字符，Argon2id 派生 AES-256 密钥）加密报告敏感元数据，配 kubescape decrypt 恢复。

5.5 CI 门禁参数（退出码语义）

实测验证（对含 3 个 High 失败的 manifest 设 --severity-threshold high）：

kubescape scan framework nsa manifests/01-privileged-pod.yaml --severity-threshold high --use-artifacts-from artifacts
echo $?

实测结果：命令正常打印报告，进程退出码为 1（实测记录 THRESHOLD_EXIT=1），证明 CI 流水线可直接以退出码做门禁。

5.6 镜像漏洞扫描参数

💡 技术拓展：镜像漏洞扫描器的「漏洞库」选型——Kubescape 内嵌 Grype 库（anchore 系，本地 SQLite，支持 --grype-db-url 换源）；同类还有 Trivy DB（aquasecurity 系）。两者库结构不同不可互换；Kubescape 用户无需自选，内嵌 Grype 是唯一路径，--grype-db-url 只用于指向私有镜像的 Grype 库副本（离线漏洞库分发场景）。

5.7 上报与遥测参数

5.8 性能与超时参数

六、环境变量清单

从各 --help 原文提取的全部环境变量（默认值即帮助原文标注）：

七、例外规则（exceptions）详解与实测

7.1 文件格式

exceptions 是 postureExceptionPolicy 数组，实测下载的官方包 artifacts/exceptions.json 共 299 条，单条结构（取官方包第 1 条原文）：

{
  "guid": "",
  "name": "exclude-eks-resources-1",
  "attributes": {"systemException": true},
  "policyType": "postureExceptionPolicy",
  "actions": ["alertOnly"],
  "resources": [{"designatorType": "Attributes", "attributes": {"kind": "Pod", "namespace": "kube-system", "name": "aws-node-[A-Za-z0-9]+"}}],
  "posturePolicies": [{"frameworkName": "", "controlID": "C-.*"}]
}

字段说明：

• resources[].attributes：资源选择器，designatorType: Attributes 时支持 kind/namespace/name，name 支持正则（官方样例 aws-node-[A-Za-z0-9]+）；也可用 designatorType: Labels 按 label 匹配。
• posturePolicies[]：作用的控件范围，controlID: "C-.*" 表示全部控件；frameworkName 可限定框架。
• actions：决定豁免行为的关键，见 7.2 实测。

7.2 alertOnly 与 delete 的实测差异

准备一个只豁免特权 Pod 的 C-0057（Privileged container）与 C-0038（Host PID/IPC）的例外文件：

[
  {
    "name": "allow-privileged-debug-pod",
    "policyType": "postureExceptionPolicy",
    "actions": ["delete"],
    "resources": [
      {"designatorType": "Attributes", "attributes": {"kind": "Pod", "namespace": "default", "name": "privileged-debug"}}
    ],
    "posturePolicies": [
      {"frameworkName": "NSA", "controlID": "C-0057"},
      {"frameworkName": "NSA", "controlID": "C-0038"}
    ]
  }
]

实测对比（同一 manifest、同一规则包，仅 actions 不同）：

⚠️ 注意：想让例外资源从合规分与失败统计中消失必须用 actions: ["delete"]；alertOnly 只是把发现标记为「仅告警」，报告数字纹丝不动——这是实测验证过的高频误解点。

使用方式（--exceptions 指向文件；--use-artifacts-from 提供离线规则包）：

kubescape scan framework nsa manifests/01-privileged-pod.yaml \
  --exceptions exceptions-demo.json --use-artifacts-from artifacts

实测回显关键段（Passed 13 / Failed 7，与基线 11/9 对比可见豁免生效）：

╭─────────────────┬────╮
│        Controls │ 20 │
│          Passed │ 13 │
│          Failed │ 7  │
╰─────────────────┴────╯

7.3 内联注解豁免（kubescape.io/skip-*）

在资源上加 kubescape.io/skip-<CONTROL-ID> 注解即可豁免对应控件（如 kubescape.io/skip-C-0057: "true"）。注意帮助原文的口径：本地 manifest 扫描默认启用该行为（--honor-inline-exceptions 默认开），活集群扫描默认关闭——避免集群里他人埋注解绕过审计。要显式关闭传 --honor-inline-exceptions=false。

八、框架/控件配置与离线规则包（registry 离线路径）

8.1 框架与控件全景

kubescape list frameworks 实测输出 16 个框架：AgentRuntimeHardening、AllControls、ArmoBest、DevOpsBest、ISM、MITRE、NSA、SOC2、cis-aks-t1.2.0、cis-aks-t1.8.0、cis-eks-t1.7.0、cis-eks-t1.8.0、cis-gke-v1.9.0、cis-v1.10.0、cis-v1.12.0（外加强制性的 WorkloadScan/ClusterScan 内部框架随 artifacts 下载）。

kubescape list controls 实测输出 290 个控件（从 C-0001 Forbidden Container Registries 到 C-0292 Nginx Ingress Controller End of Life，中间有编号断档），每个控件附官方文档链接（如 https://hub.armosec.io/docs/c-0057）与所属框架。NSA 框架实测含 20 个控件（单文件扫描后表格行数实测）。

8.2 控件配置（controls-inputs）

部分控件的判定阈值可配置（如「禁止的镜像仓库」列表），集合在 controls-inputs 对象中：

• 默认：从 ARMO 管理门户下载；
• 本地化：--controls-config <path> 指向本地 JSON；
• 锁版本：--controls-version v2.0.38 把整套控件规则钉在 regolibrary 指定 tag。

⚠️ 注意：--controls-version 与 --account（云端后端）互斥——帮助原文明确「Has no effect when --account is set」。要走本地可复现 CI，就不要在扫描命令里混入 SaaS 账号参数。

8.3 离线规则包全流程（download artifacts + use-artifacts-from 实测）

第一步：联网机下载全量工件

export https_proxy=http://192.168.1.62:7897 http_proxy=http://192.168.1.62:7897
kubescape download artifacts --output artifacts

实测回显（节选，全部 info 无 warn 即完整成功）：

{"level":"info",...,"msg":"Downloaded","artifact":"controls-inputs","path":"artifacts/controls-inputs.json"}
{"level":"info",...,"msg":"Downloaded","artifact":"exceptions","path":"artifacts/exceptions.json"}
{"level":"info",...,"msg":"Downloaded","artifact":"framework","name":"NSA","path":"artifacts/nsa.json"}
...（16 个框架逐一下载）
{"level":"info",...,"msg":"Downloaded","attack tracks":"attack-tracks","path":"artifacts/attack-tracks.json"}

第二步：把 artifacts/ 目录拷贝到离线服务器（U 盘/内网文件服务均可，目录含 20 余个 JSON，约数 MB）。

第三步：离线扫描

kubescape scan framework nsa --use-artifacts-from artifacts manifests/02-nginx-deployment.yaml

实测回显（与在线扫描一致的完整报告，全程无网络请求）：

Framework scanned: NSA

╭─────────────────┬────╮
│        Controls │ 20 │
│          Passed │ 9  │
│          Failed │ 11 │
╰─────────────────┴────╯

💡 说明：私有 registry 的镜像漏洞扫描离线路径同样闭环——凭据用 5.6 节的 --registry-username/--registry-password（或同名环境变量）传入，内网地址映射用 --registry-mapping，漏洞库用 --skip-db-update 走本地缓存库并配 --grype-db-url 指向内网 Grype 库副本。这套「离线 registry + 离线规则包 + 离线漏洞库」组合即 Kubescape 在隔离环境的完整形态。

九、生产配置模板

9.1 CI 门禁模板（GitLab/GitHub 通用，内网可跑）

适用场景：4 核 8GB CI Runner、manifest 仓库千级 YAML、完全离线（规则包随仓库分发）。

kubescape scan framework nsa,mitre \
  --use-artifacts-from /opt/kubescape/artifacts \
  --controls-version v2.0.38 \
  --exceptions /opt/kubescape/exceptions-prod.json \
  --severity-threshold high \
  --format junit --output kubescape-report.xml \
  --exclude-path 'test/**,examples/**'

逐项说明：nsa,mitre 双框架兼顾基线与攻击路径；--use-artifacts-from 保证离线且版本可控；--controls-version 钉规则版本（升级靠改这行并评审）；--exceptions 指向进 Git 的豁免清单；--severity-threshold high 高危即失败；junit 输出对接 CI 测试面板；测试目录从扫描范围排除。

9.2 定期巡检模板（crontab，集群侧只读）

适用场景：8GB 内存运维机、kubeconfig 指向生产集群只读账号、每日凌晨巡检。

# crontab -e 添加（每日 02:30 巡检 NSA+CIS 双框架）
30 2 * * * /usr/local/bin/kubescape scan framework nsa,cis-v1.12.0 --format json --output /var/log/kubescape/$(date +\%Y\%m\%d).json --keep-local --logger warning

逐项说明：--keep-local 确保巡检结果绝不上报；--logger warning 压制 info 噪音；输出按日期落文件供趋势比对（进一步可配 --baseline 与 --baseline-fail-on-new 对「较昨日新增高危」告警）；建议对巡检机资源预留：kubescape 进程峰值内存与集群资源数成正比，千级资源集群预留 2GB 内存。

十、常见问题（FAQ）

Q1：扫描输出 Scan Coverage Warning，合规分可信吗？

实测现象：

Scan Coverage Warning
Scan coverage score: 90% (20/20 controls evaluated)

The following policy inputs could not be loaded and were served from bundled defaults:
  • controlInputs: error opening controls-inputs.json file, "controls-config" will be downloaded from ARMO management portal

原因：controls-inputs 没取到（断网/无代理），CLI 用内置默认值兜底继续扫。20/20 控件已求值、覆盖率 90%，但依赖外部配置的控件阈值可能是默认值。处置：补网络或 --use-artifacts-from；要「宁可失败不可兜底」加 --fail-on-degraded-config。

Q2：--exceptions 配了为什么不生效？

排查顺序：① actions 是否为 ["delete"]（alertOnly 不摘除，实测见 7.2 表）；② posturePolicies.controlID 拼写是否正确（C-0057 四位补零）；③ resources.attributes 的 kind/namespace/name 是否与目标资源精确匹配（name 支持正则，注意锚定）；④ 本地文件路径是否真的被 --exceptions 引用（默认会尝试从门户下载而非读本地）。

Q3：--controls-version 报「no effect」？

原因：命令里同时带了 --account（或缓存里有 SaaS 凭据），规则走云端下发，本地锁版被忽略。处置：去掉账号参数或用 --keep-local，帮助原文明确该参数「Has no effect when --account is set」。

Q4：规则包下载一半失败怎么办？

download artifacts 的失败是逐工件降级的：任一工件下载失败会 warn 并继续，末尾 Error 汇总（实测见《Ubuntu 22.04 安装 Kubescape v4.0.16 指南》10.2 节回显原文）。处置：设置 HTTPS_PROXY 后重跑直到回显全部为 Downloaded；校验方法即数一遍 info 行是否覆盖 16 框架 + controls-inputs + exceptions + attack-tracks。

Q5：两个集群同名 context 想分别出报告？

用 --kube-contexts ctx-a,ctx-b --output /tmp/scan 每个 context 生成一份 context 后缀的报告，加 --fleet-report /tmp/fleet.json 得到跨集群合并视图（含逐控件×集群矩阵）；--reference-cluster ctx-a 可以以某集群为基准高亮分歧项。

十一、参考链接

1. 官方 CLI 文档：https://kubescape.io/docs/cli/
2. regolibrary 规则库发布页（--controls-version 可选值）：https://github.com/kubescape/regolibrary/releases
3. 控件文档 Hub（C-xxxx 逐条说明）：https://hub.armosec.io/docs/c-0001
4. 官方 exceptions 示例与说明：https://kubescape.io/docs/exceptions/
5. 同系列文档：《Kubescape 介绍与选型指南》、《Ubuntu 22.04 安装 Kubescape v4.0.16 指南》、本专栏《Kubescape v4.0.16 常用 CLI 命令详解》（子命令全解）