Kubescape v4.0.16 常用 CLI 命令详解

目标：覆盖 Kubescape CLI v4.0.16 全部 17 个子命令——按「扫描 / 工件 / 修复 / 策略开发 / 集群运维 / 生态接口」六类逐一给出用途、语法、实测示例与输出解读。环境 Ubuntu 22.04；所有「实测回显」均在本地 manifest 样本上运行取得，「官方帮助口径」标注的条目未实测。

一、环境信息

操作系统：Ubuntu 22.04.4 LTS（x86_64）
Kubescape：v4.0.16（Build commit d0ea07b，2026-10-14 构建；安装见《Ubuntu 22.04 安装 Kubescape v4.0.16 指南》篇）
扫描样本：manifests/ 目录 3 个含缺陷 YAML——特权 Pod（privileged/hostPID/hostNetwork/hostPath）、无资源限制 Deployment（latest 标签、SYS_ADMIN 能力、硬编码密码）、cluster-admin 的 ServiceAccount 绑定
离线规则包：artifacts/ 目录（kubescape download artifacts 产物，见《Kubescape v4.0.16 配置参数详解》8.3 节）
网络代理：export https_proxy=http://192.168.1.62:7897 http_proxy=http://192.168.1.62:7897（仅工件下载与联网场景需要）

二、命令清单总览

kubescape --help 实测的全部子命令（17 个，分类为本文行文顺序）：

分类	子命令	帮助原文一句话	本文实测
扫描	`scan`	Scan a Kubernetes cluster or YAML files for image vulnerabilities and misconfigurations	✅ 5 个变体实测
扫描	`list`	List the supported frameworks, controls and control configuration	✅ 实测
工件	`download`	Download artifacts,attack-tracks,control,controls-inputs,exceptions,framework	✅ 实测
工件	`update`	Update to latest release version	✅ 实测
工件	`config`	Handle cached configurations	✅ view 实测
修复	`fix`	Propose a fix for the misconfiguration found when scanning Kubernetes manifest files	✅ 实测
修复	`diff`	Compare two Kubescape scan JSON reports and show what changed	✅ 实测
修复	`patch`	Patch container images to fix known OS-level vulnerabilities	官方帮助口径
策略开发	`policy`	Author and test custom Rego controls	官方帮助口径
策略开发	`predict`	Predict the impact of security policy enforcement	官方帮助口径
策略开发	`vap`	Helper commands for managing Validating Admission Policies in a Kubernetes cluster	官方帮助口径
集群运维	`operator`	The operator is used to communicate with the Kubescape Operator within the cluster components.	未实测（需集群）
集群运维	`prerequisites`	Check prerequisites for installing Kubescape Operator	未实测（需集群）
生态	`mcpserver`	Start the Kubescape MCP server	官方帮助口径
生态	`completion`	Generate autocompletion script	✅ 实测
工具	`decrypt`	Decrypt a report produced by kubescape scan --encrypt	官方帮助口径
工具	`version`	Get current version	✅ 实测

⚠️ 注意：v4.0.16 没有 host-scan 子命令。历史资料里的 kubescape host-scan 属于旧版命令形态，实测本版：kubescape host-scan --help 报 Error: unknown command "host-scan" for "kubescape"（退出码 1）。同理 delete 也不是顶层命令（清缓存用 kubescape config delete）。查命令以 kubescape --help 实测清单为准，勿沿用旧文。

三、scan 扫描主命令

scan 是核心命令，实测有 5 个用法变体：

变体	语法	用途
扫描文件/目录	`kubescape scan <路径>`	递归扫描 YAML/JSON/Helm/Kustomize（可与框架名组合）
按框架扫	`kubescape scan framework <框架名> <路径>`	指定 NSA/MITRE/CIS 等框架
按控件扫	`kubescape scan control <控件ID> <路径>`	单控件核查
镜像漏洞	`kubescape scan image <镜像:tag>`	CVE 扫描（官方帮助口径）
单工作负载	`kubescape scan workload <Kind>/<名称> <路径>`	定点复查单个资源（官方帮助口径）
扫活集群	`kubescape scan`（无路径 + kubeconfig）	扫描 kubeconfig 指向的集群（本系列未做集群实测）

3.1 扫描本地 manifest（最常用闭环）

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

实测回显（关键段，与终端一致）：

Framework scanned: NSA

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

Failed resources by severity:

╭──────────┬───╮
│ Critical │ 0 │
│     High │ 3 │
│   Medium │ 5 │
│      Low │ 1 │
╰──────────┴───╯

Run with '--verbose'/'-v' to see control failures for each resource.

╭──────────┬──────────────────────────────────────┬──────────────────┬───────────────┬──────────────────╮
│ Severity │ Control name                         │ Failed resources │ All Resources │ Compliance score │
├──────────┼──────────────────────────────────────┼──────────────────┼───────────────┼──────────────────┤
│  High    │ Host PID/IPC privileges              │         1        │       1       │        0%        │
│  High    │ HostNetwork access                   │         1        │       1       │        0%        │
│  High    │ Privileged container                 │         1        │       1       │        0%        │
...
│          │      Resource Summary                │         1        │       1       │       55.00%     │
╰──────────┴──────────────────────────────────────┴──────────────────┴───────────────┴──────────────────╯

输出解读三步法：① 第一张表看总体（20 控件 11 过 9 失败）；② 第二张表按严重度定位高危（High 3 项）；③ 第三张表按控件/资源看合规分（55.00%）。整个 Pod 文件恰好命中 NSA 框架，特权类三项（Host PID/IPC / HostNetwork / Privileged container）全部为 High。

目录扫描（3 个样本一起）：

kubescape scan framework nsa manifests/

实测回显摘要：Controls 20 / Passed 7 / Failed 13，High 8 / Medium 10 / Low 2，Resource Summary Failed resources 2 / All Resources 3 / Compliance score 51.67%——目录递归把 Deployment 与 RBAC 的失败也计入，3 资源维度下分母变大分数下降。

3.2 scan framework：多框架组合

kubescape scan framework nsa,mitre manifests/

帮助原文口径：框架名逗号分隔可同扫多个框架；框架名来自 kubescape list frameworks（16 个，实测清单见《Kubescape v4.0.16 配置参数详解》8.1 节）。扫描多框架时每个框架一张分数表，适合「基线（NSA）+ 攻击路径（MITRE）」双视角巡检。

3.3 scan control：单控件核查

kubescape scan control C-0016 manifests/02-nginx-deployment.yaml --use-artifacts-from artifacts

实测回显（关键段）：

╭─────────────────┬───╮
│        Controls │ 1 │
│          Passed │ 0 │
│          Failed │ 1 │
╰─────────────────┴───╯

╭──────────┬────────────────────────────┬──────────────────┬───────────────┬──────────────────╮
│ Severity │ Control name               │ Failed resources │ All Resources │ Compliance score │
├──────────┼────────────────────────────┼──────────────────┼───────────────┼──────────────────┤
│  Medium  │ Allow privilege escalation │         1        │       1       │        0%        │
╰──────────┴────────────────────────────┴──────────────────┴───────────────┴──────────────────╯

用途定位：CI 里对刚修复的字段做定点复扫（只算 1 个控件，秒级返回）；控件 ID 与名称、文档链接的映射查 kubescape list controls（第四章）。

3.4 scan image / scan workload（官方帮助口径）

# 扫描镜像漏洞（含私有仓库凭据参数 -u/-p）
kubescape scan image "nginx:1.27" "redis:7" --image-scan-concurrency 4
# 定点扫描单个工作负载（从本地 manifest）
kubescape scan workload Deployment.v1.apps/nginx --file-path deploy.yaml

scan image 支持一次多镜像共享一次漏洞库加载、--platform linux/amd64 选多架构镜像变体、--exceptions 例外（注意帮助原文：archive/目录/SBOM 输入与 --exceptions 组合会按镜像报 Image Exceptions/Unsupported Input）。scan workload 的 Kind 参数支持 [.version[.group]] 后缀定位 API 组，-n 指定命名空间（集群搜索传 * 需集群级 list 权限）。两者本篇未实测（镜像拉取与集群依赖），参数口径以 --help 为准。

四、list 命令：框架与控件清单

kubescape list frameworks
kubescape list controls

list frameworks 实测输出 16 个框架名（NSA、MITRE、AllControls、ArmoBest、DevOpsBest、ISM、SOC2、AgentRuntimeHardening、6 个 CIS 变体）。

list controls 实测输出 290 个控件的长表（每行含控件 ID、名称、所属框架、严重度、文档链接），例如：

C-0001 │ Forbidden Container Registries │ ...

常用参数（list --help 实测原文）：

参数	作用
`--framework NSA`	只列出 NSA 框架内的控件
`--search container`	对控件 ID/名称/框架做大小写不敏感的文本过滤
`-f/--format`	输出格式：pretty-print/json/yaml/csv（默认 pretty-print）
`list controls-config`	第三种子形式：列出控件可配置的输入项及其当前值，配 `--controls-config <file>` 预演本地覆盖效果

组合示例（实测语法来自官方 Examples）：

kubescape list controls --framework NSA --search container

定位用法：给 exceptions 文件找准确控件 ID、写 CI 报告前确认框架覆盖范围，都用这条命令，避免凭记忆写错 C-xxxx。

五、download 命令：离线工件获取

kubescape download --help

实测帮助原文的子形式：artifacts,attack-tracks,control,controls-inputs,exceptions,framework——即六个下载对象，全部支持 --output <路径>。

实测单框架下载：

kubescape download framework nsa --output nsa-download.json

实测回显：

{"level":"info","ts":"2026-10-24T05:08:01+08:00","msg":"Downloaded","artifact":"framework","name":"NSA","path":"nsa-download.json"}

download artifacts（全量离线包，20 余个 JSON 含 16 框架 + controls-inputs + exceptions + attack-tracks）的完整实测流程、无代理时的降级告警回显与 --use-artifacts-from 离线扫描验证，见《Kubescape v4.0.16 配置参数详解》8.3 节，此处不重复。

六、config 命令：缓存配置管理

kubescape config view

实测回显：

clusterName: kind-solr-op

四个子命令（config --help 实测）：view（查看）、validate（校验缓存配置有效性）、set（设置 SaaS 四项凭据：accessKey/accountID/cloudAPIURL/cloudReportURL）、delete（删除缓存）。

⚠️ 注意：kubescape config delete 是破坏性操作——清掉缓存目录中的配置与工件后，下次扫描需重新下载（离线环境会直接失败）。离线服务器勿跑；启用 --incremental 增量扫描后清理判定缓存也走这条命令（kubescape config delete cache，帮助原文口径）。

七、update 命令：自更新

kubescape update

实测回显（受限网络下）：

{"level":"info","ts":"2026-10-24T04:58:44+08:00","msg":"Failed to check for updates"}

⚠️ 注意：更新检查失败只打一行 info 且退出码 0（实测记录 UPDATE_EXIT=0），不能以「没报错」认定已是最新版，必须用 kubescape version 对照官方 Releases 确认。生产环境更可靠的自更新路径是重跑官方安装脚本（支持 -v 锁版本，实测详见《Ubuntu 22.04 安装 Kubescape v4.0.16 指南》9.2 节）。

八、fix 命令：自动修复 manifest

工作流是「先扫描出 JSON 报告，再按报告修文件」：

# 第一步：扫描生成 JSON 报告
kubescape scan framework nsa manifests/01-privileged-pod.yaml --format json --output scan_nsa.json

# 第二步：修复（写副本到 fixed/ 目录，不动原文件）
kubescape fix scan_nsa.json --output-dir fixed

第二步实测回显（结构化日志多行，关键内容）：

The following changes will be applied:
File: /opt/data/quzuo/tmp/kubescape/manifests/01-privileged-pod.yaml
Namespace: default
Document index: 0
Resource: privileged-debug
Kind: Pod
Changes:
	1) spec.containers[0].securityContext.runAsNonRoot = true
	2) spec.containers[0].securityContext.runAsGroup = 1000
	3) spec.containers[0].securityContext.allowPrivilegeEscalation = false
	4) spec.containers[0].securityContext.privileged = false
	5) spec.containers[0].securityContext.readOnlyRootFilesystem = true
	6) spec.automountServiceAccountToken = false

Wrote 1 fixed file(s) to fixed, covering 5 of 9 flagged control instances. The original files were not modified.
Would auto-fix 5 of 9 flagged control instances. The following require manual remediation:
  - C-0030 Ingress and Egress blocked on Pod/privileged-debug (...) — no auto-fix available for this control
  - C-0038 Host PID/IPC privileges on Pod/privileged-debug (...) — no auto-fix available for this control
  - C-0041 HostNetwork access on Pod/privileged-debug (...) — no auto-fix available for this control
  - C-0055 Linux hardening on Pod/privileged-debug (...) — skipped: auto-fix requires a user-supplied value (--skip-user-values is set)

输出解读：9 个失败控件实例中 5 个自动修复、4 个需人工（3 个无自动修复规则，1 个因 --skip-user-values 默认 true 跳过需自定值的修复）。fixed/ 目录镜像原目录树结构，diff 对比原文件可见 securityContext 字段补齐。

常用参数（fix --help 实测）：

参数	默认	说明
`--output-dir`	无（原地修改！）	指定则写修复副本、原文件不动；不指定则直接改你的 manifest
`--dry-run`	false	只预演不落盘
`-i/--interactive`	false	逐资源确认后再修（仅原地修复模式生效）
`--include-controls` / `--skip-controls`	无	只修/跳过指定控件 ID（逗号分隔，大小写不敏感）
`--skip-user-values`	true	跳过需要用户给定值的自动修复（如 seccompProfile 需选 profile）
`--base-path`	无	校验报告内记录的扫描路径必须落在此目录内（防不可信 CI 报告指路）
`--no-confirm`	false	跳过确认；非空目录不传该参数会被拒

⚠️ 注意：帮助原文的强警告——「Use with caution, this command will change your files in-place unless --output-dir is given」。生产实践固定套路：fix report.json --output-dir fixed/ 出副本 → 人工 review → 自己 diff 合入，绝不默认原地改。另：集群扫描报告的 fix 不改集群，修复清单打印出来由你决定是否 apply（帮助原文：applying is your call）。

报错形态实测：直接把目录喂给 fix 会失败——

kubescape fix manifests/

实测回显（首行 Error，其余为用法提示）：

Error: "manifests/" is a directory, not a file. Please provide a JSON report file path
Usage:
  kubescape fix <report output file> [flags]
...

（退出码 2）。fix 的输入必须是 scan --format json --output 产出的报告文件，不是目录/manifest。

九、diff 命令：报告对比与漂移门禁

# 基线报告（无 exceptions）
kubescape scan framework nsa manifests/01-privileged-pod.yaml --use-artifacts-from artifacts --format json --output r1.json
# head 报告（加例外）
kubescape scan framework nsa manifests/01-privileged-pod.yaml --use-artifacts-from artifacts --exceptions exceptions-demo.json --format json --output r2.json
# 对比
kubescape diff r1.json r2.json

实测回显（节选）：

Still failing (unchanged) (12)
-----------------------------------
  [High] Host PID/IPC privileges (C-0038)
    Resource: path=3949387318/api=/v1/default/Pod/privileged-debug
    Rule: host-pid-ipc-privileges
    Evidence: deletePath spec.hostIPC
...
  [Low] Immutable container filesystem (C-0017)
    Resource: path=3949387318/api=/v1/default/Pod/privileged-debug
    Rule: immutable-container-filesystem
    Evidence: fixPath spec.containers[0].securityContext.readOnlyRootFilesystem

Summary: 0 new, 0 resolved, 12 unchanged, 0 incomparable

输出解读：四类结果——new（新引入失败）、resolved（已解决）、unchanged（仍未修，逐条带 Rule 与 Evidence 字段路径）、incomparable（不可比，如扫描范围变了）。Evidence 行区分 deletePath（该字段需删除）/fixPath（该字段需修复），是给 fix 命令同类引擎消费的证据链。

CI 门禁参数（帮助原文口径）：kubescape diff base.json head.json --fail-on-new --severity-threshold high——新增高危即失败退出，比全量阈值更适合存量老项目的渐进收紧。镜像报告对比时按 CVE ID+包名+包类型识别（升级同 CVE 包视为 unchanged），多镜像报告的发现合并池化（帮助原文：--fail-on-new 不标记 CVE 在镜像间的扩散）。

十、策略开发命令：policy / predict / vap（官方帮助口径，实验性）

# policy：自定义 Rego 控件的脚手架与测试（帮助原文标注 experimental）
kubescape policy init ./rules/no-privileged-containers   # 生成规则 + 可通过的测试夹具
kubescape policy test ./rules/my-custom-rule             # 跑规则测试，--update 重写期望输出

# predict：策略执行影响预演（不改集群）
kubescape predict pss -n production        # 预测命名空间在 Pod Security Standards 下的合规情况
kubescape predict pss ./manifests/         # 对本地 manifest 预测

# vap：管理集群内 Validating Admission Policies（CEL 准入策略）
kubescape vap list-policies --controls-only --format json
kubescape vap deploy-library --from-release v0.11 | kubectl apply -f -

定位：三者构成「规则开发（policy）→ 迁移预演（predict）→ 准入拦截（vap）」的自定义策略闭环。policy 产出的自定义 Rego 规则目录可被 scan 的 --custom-rules 参数纳入扫描（默认按 Medium 严重度计）；vap deploy-library 输出 YAML 管道给 kubectl apply，把 Kubescape 控件落成集群原生准入策略。三者帮助均标注实验性（might change），生产慎用。

十一、mcpserver 与 completion：生态接口

kubescape mcpserver --help

实测帮助原文：Start the Kubescape MCP server，参数 -t/--transport（stdio 或 sse，默认 stdio）、-p/--port（SSE 模式端口，默认 8080）。stdio 模式可直接作为 AI 代理（如 MCP 客户端）的子进程把 Kubescape 扫描能力挂进会话——本篇不实测运行中的 Server（长驻进程），仅记录接口形态。

kubescape completion bash | head -8

实测回显（节选）：

# bash completion for kubescape                            -*- shell-script -*-

__kubescape_debug()
{

装载：source <(kubescape completion bash)（zsh/fish/powershell 同理），子命令与参数的 Tab 补全对提高 CLI 使用效率显著。

十二、operator / prerequisites：集群侧命令（未实测声明）

命令	帮助原文定位	与 CLI 社区版的关系
`operator`	与集群内 Kubescape Operator 组件通信	Operator 未部署时报错；用于取配置、触发动作
`prerequisites`	检查安装 Kubescape Operator 的前置条件	检查集群版本、能力开关等

诚实声明：本系列文档的实测主线是「CLI 扫描本地 manifest」；活集群扫描（kubescape scan 直连 kubeconfig）、Operator 部署与 in-cluster 持续扫描路径未做实测，相关小节均以官方帮助口径标注。集群内安装 Operator 属 Helm Chart 部署范畴（kubescape/helm-charts 仓库），超出本篇 CLI 命令范围。

十三、命令组合与最佳实践

① CI 门禁流水线（离线 + 双报告 + 对比门禁）：

kubescape download artifacts --output /opt/kubescape/artifacts        # 构建镜像时预置
kubescape scan framework nsa --use-artifacts-from /opt/kubescape/artifacts \
  --exceptions /opt/kubescape/exceptions-prod.json \
  --format json --output head.json --exclude-path 'test/**'
kubescape diff /opt/kubescape/artifacts/base.json head.json --fail-on-new --severity-threshold high

② 修复工作流（副本 + review + 复扫验证）：

kubescape scan . --format json --output report.json
kubescape fix report.json --output-dir fixed/
diff -ru . fixed/            # 人工审查全部改动
kubescape scan framework nsa fixed/ --use-artifacts-from artifacts   # 复扫验证分数提升

③ 控件速查与单点核查：

kubescape list controls --framework NSA --search privileged    # 找准控件 ID
kubescape scan control C-0057 deploy.yaml                      # 定点复扫

④ 定时巡检（结果留档，绝不上报）：

kubescape scan framework nsa,cis-v1.12.0 --format json --output /var/log/kubescape/$(date +\%Y\%m\%d).json --keep-local --logger warning

十四、常见问题（FAQ）

Q1：kubescape host-scan 提示 unknown command？

实测回显 Error: unknown command "host-scan" for "kubescape"（退出码 1）。该命令属于旧版 CLI；v4.0.16 的扫描入口统一为 scan（集群/文件/镜像/单工作负载四个变体，见第三章）。旧文的节点级扫描诉求在 v4 的路线是 Operator 形态。

Q2：kubescape update 说成功但版本没变？

实测 update 在更新检查失败时只打一行 info 日志且退出码 0（第七章）。以 kubescape version 为准；升级用 bash install.sh（可 -v 锁版本）。

Q3：kubescape fix 报 report file must be a JSON format...？

fix 只吃 scan 的 JSON 报告（第八章实测回显与退出码 2），目录/单 YAML 都不行。先 scan --format json --output report.json 再 fix。

Q4：扫描本地文件为什么也提示 GitLocal？

实测日志中 Scanning GitLocal 与 in setContextMetadata ... repository host 'gitee.com' not supported（warn，不影响结果）：CLI 会探测扫描目标所在 Git 仓库并尝试补充仓库元数据，仓库托管平台不被识别或不在 git 仓库内都不影响扫描本体。

Q5：--exclude-namespaces 排了命名空间，集群级资源怎么也不见了？

这是帮助原文明确的行为：when running with exclude-namespace kubescape does not scan cluster-scoped objects——排除命名空间会连带放弃集群级对象（ClusterRole、Namespace 等）扫描。要保留集群级对象改用 --include-kinds/--exclude-kinds 组合。

十五、参考链接

官方 CLI 文档：https://kubescape.io/docs/cli/
控件文档 Hub（C-xxxx 说明与修复指引）：https://hub.armosec.io/docs/c-0001
regolibrary（自定义规则参考实现）：https://github.com/kubescape/regolibrary
patch 子命令文档：https://github.com/kubescape/kubescape/tree/master/cmd/patch
同系列文档：《Kubescape 介绍与选型指南》、《Ubuntu 22.04 安装 Kubescape v4.0.16 指南》、《Kubescape v4.0.16 配置参数详解》