Kubescape CLI Reference

July 17, 2026 · View on GitHub

This document provides a complete reference for all Kubescape CLI commands and options.

Global Options

These options are available for all commands:

Option	Description
`--cache-dir <path>`	Cache directory (default: `~/.kubescape`)
`--kube-context <context>`	Kubernetes context to use (default: current-context)
`-l, --logger <level>`	Log level: `debug`, `info`, `warning`, `error`, `fatal`
`--server <url>`	Backend discovery server URL
`-h, --help`	Help for any command

kubescape scan

Scan Kubernetes clusters, files, or images for security issues.

Synopsis

kubescape scan [target] [flags]

Target Types

No target: Scans the current cluster
Path: Scans local YAML files, Helm charts, or Kustomize directories
URL: Scans a Git repository

Flags

Flag	Description	Default
`--account <id>`	Kubescape SaaS account ID	from cache
`--access-key <key>`	Kubescape SaaS access key	from cache
`--compliance-threshold <float>`	Fail if compliance score is below threshold. Applies to `scan framework`, `scan control`, and `--view resource\|control` — see score thresholds.	`0`
`--controls-config <path>`	Path to controls configuration file	-
`-e, --exclude-namespaces <ns>`	Namespaces to exclude (comma-separated)	-
`--encrypt`	Encrypt sensitive report metadata using the master key provided through the `KUBESCAPE_MASTER_KEY` environment variable. Requires `--format json` for reports that will later be decrypted with `kubescape decrypt`. If both `--encrypt` and `--hide` are specified, `--encrypt` takes precedence.	`false`
`--exceptions <path>`	Path to exceptions file	-
`--fail-coverage-below <float>`	Fail if the scan coverage score is below threshold (`0` disables). Applies in every view — see score thresholds.	`0`
`-f, --format <format>`	Output format: `pretty-printer`, `json`, `junit`, `sarif`, `html`, `pdf`, `prometheus`	`pretty-printer`
`--hide`	Replace sensitive report metadata with deterministic pseudonyms. Ignored when `--encrypt` is also specified.	`false`
`--include-namespaces <ns>`	Namespaces to include (comma-separated)	-
`--keep-local`	Don't report results to backend	`false`
`--kubeconfig <path>`	Path to kubeconfig file	-
`-o, --output <path>`	Output file path	stdout
`--scan-images`	Also scan container images for vulnerabilities	`false`
`--severity-threshold <sev>`	Fail if findings at or above severity: `low`, `medium`, `high`, `critical`	-
`--submit`	Submit results to Kubescape SaaS	`false`
`--use-artifacts-from <path>`	Load artifacts from local directory (offline mode)	-
`--use-from <path>`	Load specific policy from path	-
`-v, --verbose`	Display all resources, not just failed ones	`false`
`--view <type>`	View type: `security`, `control`, `resource`	`security`

Examples

# Scan current cluster
kubescape scan

# Scan with specific framework
kubescape scan framework nsa
kubescape scan framework mitre
kubescape scan framework cis-v1.23-t1.0.1

# Scan specific control
kubescape scan control C-0005 -v

# Scan local files
kubescape scan /path/to/manifests/

# Scan Git repository
kubescape scan https://github.com/org/repo

# Anonymize sensitive report metadata
kubescape scan --hide

# Generate an anonymized JSON report
kubescape scan --hide --format json --output report.json

# The key is used as raw bytes and must be exactly 32 characters long.
# Note: `openssl rand -base64 32` (44 chars) and `openssl rand -hex 32` (64 chars)
# are NOT valid — they exceed 32 bytes once passed through as raw text.
export KUBESCAPE_MASTER_KEY=$(LC_ALL=C tr -dc 'A-Za-z0-9' </dev/urandom | head -c 32)

# Generate an encrypted JSON report
kubescape scan --encrypt --format json --output encrypted-report.json

# The key is used as raw bytes and must be exactly 32 characters long.
# Note: `openssl rand -base64 32` (44 chars) and `openssl rand -hex 32` (64 chars)
# are NOT valid — they exceed 32 bytes once passed through as raw text.
export KUBESCAPE_MASTER_KEY=$(LC_ALL=C tr -dc 'A-Za-z0-9' </dev/urandom | head -c 32)

# Decrypt an encrypted report
kubescape decrypt encrypted-report.json > decrypted-report.json

# Output to JSON file
kubescape scan --format json --output results.json

# Set compliance threshold (exit 1 if below). Combine with a framework,
# control, or --view resource|control (see "Score thresholds" below).
kubescape scan framework nsa --compliance-threshold 80
kubescape scan --view resource --compliance-threshold 80

# Exclude namespaces
kubescape scan --exclude-namespaces kube-system,kube-public

Score thresholds

--compliance-threshold (compliance score) and the deprecated --fail-threshold (risk score) apply to the following invocations:

kubescape scan framework <name> ...
kubescape scan control <id> ...
kubescape scan --view resource ... or --view control ...

The default kubescape scan [path] uses --view security, which does not evaluate against a score threshold. To gate a pipeline on the compliance or risk score, use one of the forms above. --severity-threshold and --fail-coverage-below apply in every view.

--fail-coverage-below gates on the scan coverage score, not the raw ratio of evaluated controls. The score starts from the percentage of controls that were evaluated and then subtracts a fixed penalty for each runtime gap: 3 points per silent failed GVR pull (a resource type that failed to collect entirely but whose dependent controls still evaluated via other resource types), 2 points per partial GVR pull, and 5 points per degraded policy input (control configurations or exceptions served from a fallback source). As a result a scan in which 100% of controls were evaluated can still drop below the threshold — for example, a single silent failed GVR pull yields a score of 97.

Behavior change: earlier releases compared only the ratio of evaluated controls. Pipelines that tuned --fail-coverage-below against that narrower meaning may now fail on scans that previously passed. Re-check your threshold if you rely on this flag in CI.

kubescape scan framework

Scan against a specific security framework.

Synopsis

kubescape scan framework <framework-name> [target] [flags]

Available Frameworks

Framework	Description
`nsa`	NSA-CISA Kubernetes Hardening Guidance
`mitre`	MITRE ATT&CK® for Kubernetes
`cis-v1.23-t1.0.1`	CIS Kubernetes Benchmark
`soc2`	SOC 2 compliance
`pci-dss`	PCI DSS compliance
`hipaa`	HIPAA compliance

Examples

kubescape scan framework nsa
kubescape scan framework mitre --include-namespaces production
kubescape scan framework cis-v1.23-t1.0.1 /path/to/manifests

kubescape scan control

Scan for a specific control.

Synopsis

kubescape scan control <control-id> [target] [flags]

Examples

# Scan for privileged containers
kubescape scan control C-0057 -v

# Scan specific files for a control
kubescape scan control C-0013 /path/to/deployment.yaml

kubescape scan workload

Scan a specific workload.

Synopsis

kubescape scan workload <kind>/<name> [flags]

Flags

Flag	Description
`--namespace <ns>`	Namespace of the workload

Examples

kubescape scan workload Deployment/nginx --namespace default
kubescape scan workload DaemonSet/fluentd --namespace logging

kubescape scan image

Scan a container image for vulnerabilities.

Synopsis

kubescape scan image <image>:<tag> [flags]

Flags

Flag	Description
`--exceptions <path>`	Path to exceptions file
`-p, --password <pass>`	Registry password
`-u, --username <user>`	Registry username
`--use-default-matchers`	Use default vulnerability matchers

Examples

# Scan public image
kubescape scan image nginx:1.21

# Scan with verbose output
kubescape scan image nginx:1.21 -v

# Scan private registry image
kubescape scan image myregistry.io/myimage:tag -u myuser -p mypass

kubescape fix

Auto-fix misconfigurations in Kubernetes manifest files.

Synopsis

kubescape fix <report-file> [flags]

Flags

Flag	Description	Default
`--dry-run`	Preview changes without applying	`false`
`--no-confirm`	Apply without confirmation	`false`
`--skip-user-values`	Skip changes requiring user values	`true`

Examples

# Generate scan results
kubescape scan /path/to/manifests --format json --output results.json

# Apply fixes
kubescape fix results.json

# Preview fixes
kubescape fix results.json --dry-run

# Apply without prompts
kubescape fix results.json --no-confirm

kubescape patch

Patch container images to fix OS-level vulnerabilities.

Synopsis

kubescape patch [flags]

Flags

Flag	Description	Default
`-i, --image <image>`	Image to patch (required)	-
`-t, --tag <tag>`	Output image tag	`<image>-patched`
`-a, --addr <addr>`	BuildKit daemon address	`unix:///run/buildkit/buildkitd.sock`
`--timeout <duration>`	Patching timeout	`5m`
`--ignore-errors`	Continue on errors	`false`
`--push`	Push the patched image to the source registry	`false`
`-u, --username <user>`	Registry username	-
`-p, --password <pass>`	Registry password	-
`-f, --format <format>`	Output format: `pretty-printer`, `json`, `sarif`	-
`-o, --output <path>`	Output file	stdout
`-v, --verbose`	Verbose output	`false`

Examples

# Start buildkitd first
sudo buildkitd &

# Patch an image
sudo kubescape patch --image nginx:1.22

# Custom output tag
sudo kubescape patch --image nginx:1.22 --tag nginx:1.22-fixed

# Verbose output
sudo kubescape patch --image nginx:1.22 -v

# Also push the patched image back to the source registry
sudo kubescape patch --image myregistry.example.com/team/app:1.2.3 --push

By default the patched image is only loaded into the local image store. Pass --push if you also want it pushed to the source registry.

Hiding sensitive metadata

Generate a report with anonymized sensitive report metadata.

Synopsis

kubescape scan [target] --hide [flags]

Description

Replaces sensitive report metadata with deterministic pseudonyms.

This reduces incidental exposure but is not a confidentiality guarantee. Values drawn from small or predictable sets (such as common namespace names) may be recovered by comparing candidate hashes.

Use --encrypt when sensitive metadata requires confidentiality.

Examples

# Scan the current cluster and generate an anonymized report
kubescape scan --hide --format json --output report.json

# Scan local manifests and save an anonymized report
kubescape scan /path/to/manifests \
  --hide \
  --format json \
  --output report.json

--hide replaces sensitive values with deterministic pseudonyms derived from an unsalted hash of the original value. Values drawn from a small or guessable set — such as common namespace names — can be recovered by hashing candidate values and matching the result, and identical values produce identical pseudonyms across reports. Use --hide to reduce incidental exposure, not as a confidentiality guarantee. To share a report whose metadata is genuinely protected, use --encrypt and withhold the master key.

Encrypting sensitive metadata

Generate a report with encrypted sensitive report metadata.

Synopsis

kubescape scan [target] --encrypt [flags]

Description

Encrypts sensitive report metadata using the master key supplied through the KUBESCAPE_MASTER_KEY environment variable.

The master key is used as raw bytes and must be exactly 32 characters long.

Use --format json to produce a report that can later be decrypted with kubescape decrypt.

If both --encrypt and --hide are specified, --encrypt takes precedence.

Examples

# The key is used as raw bytes and must be exactly 32 characters long.
# Note: `openssl rand -base64 32` (44 chars) and `openssl rand -hex 32` (64 chars)
# are NOT valid — they exceed 32 bytes once passed through as raw text.
export KUBESCAPE_MASTER_KEY=$(LC_ALL=C tr -dc 'A-Za-z0-9' </dev/urandom | head -c 32)

# Scan the current cluster and generate an encrypted report
kubescape scan \
  --encrypt \
  --format json \
  --output encrypted-report.json

# Scan local manifests and generate an encrypted report
kubescape scan /path/to/manifests \
  --encrypt \
  --format json \
  --output encrypted-report.json

--encrypt requires the KUBESCAPE_MASTER_KEY environment variable. The key must be exactly 32 characters long and the same key must be supplied later when running kubescape decrypt.

kubescape decrypt

Decrypt an encrypted Kubescape report.

Synopsis

kubescape decrypt <report-file>

Description

Decrypts report metadata that was protected with kubescape scan --encrypt.

Only metadata encrypted by kubescape scan --encrypt is restored. Metadata pseudonymized with --hide cannot be recovered by kubescape decrypt.

Flags

Flag	Description	Default
`-h, --help`	Help for decrypt	-

Examples

# The key is used as raw bytes and must be exactly 32 characters long.
# Note: `openssl rand -base64 32` (44 chars) and `openssl rand -hex 32` (64 chars)
# are NOT valid — they exceed 32 bytes once passed through as raw text.
export KUBESCAPE_MASTER_KEY=$(LC_ALL=C tr -dc 'A-Za-z0-9' </dev/urandom | head -c 32)

# Decrypt an encrypted report
kubescape decrypt encrypted-report.json

# Save the decrypted report to a file
kubescape decrypt encrypted-report.json > decrypted-report.json

kubescape decrypt restores metadata encrypted by kubescape scan --encrypt. It does not reverse deterministic pseudonymization produced by --hide.

kubescape list

List available frameworks and controls.

Synopsis

kubescape list <type> [flags]

Types

Type	Description
`frameworks`	List available security frameworks
`controls`	List available security controls

Flags

Flag	Description	Default
`--account <id>`	Account ID for custom frameworks	-
`--access-key <key>`	Access key	-
`--format <format>`	Output format: `pretty-print`, `json`	`pretty-print`

Examples

kubescape list frameworks
kubescape list controls
kubescape list controls --format json

kubescape download

Download artifacts for offline/air-gapped use.

Synopsis

kubescape download <type> [name] [flags]

Types

Type	Description
`artifacts`	Download all artifacts (frameworks, controls, config)
`framework`	Download a specific framework
`control`	Download a specific control

Flags

Flag	Description	Default
`-o, --output <path>`	Output path	`~/.kubescape`
`--account <id>`	Account ID	-
`--access-key <key>`	Access key	-

Examples

# Download all artifacts
kubescape download artifacts --output /path/to/offline

# Download specific framework
kubescape download framework nsa --output /path/to/nsa.json

# Use downloaded artifacts
kubescape scan --use-artifacts-from /path/to/offline

kubescape config

Manage Kubescape configuration.

Subcommands

Subcommand	Description
`view`	View current configuration
`set`	Set configuration value
`delete`	Delete cached configuration

Examples

# View configuration
kubescape config view

# Set account ID
kubescape config set accountID <account-id>

# Set cloud report URL
kubescape config set cloudReportURL https://api.example.com

# Delete configuration
kubescape config delete

kubescape operator

Interact with the in-cluster Kubescape operator.

Synopsis

kubescape operator scan <type> [flags]

Scan Types

Type	Description
`configurations`	Trigger configuration scan
`vulnerabilities`	Trigger vulnerability scan

Examples

kubescape operator scan configurations
kubescape operator scan vulnerabilities

kubescape vap deploy-library | kubectl apply -f -

create-policy-binding

Create a ValidatingAdmissionPolicyBinding.

kubescape vap create-policy-binding [flags]

Flags:

Flag	Description	Required
`-n, --name <name>`	Binding name	Yes
`-p, --policy <id>`	Policy/control ID	Yes
`--namespace <ns>`	Namespace selector (repeatable)	No
`--label <k=v>`	Label selector (repeatable)	No
`-a, --action <action>`	Action: `Deny`, `Audit`, `Warn`	No (default: `Deny`)
`-r, --parameter-reference <name>`	Parameter reference	No

Examples

# Deploy policy library
kubescape vap deploy-library | kubectl apply -f -

# Create binding
kubescape vap create-policy-binding \
  --name deny-privileged \
  --policy c-0057 \
  --namespace production \
  --action Deny | kubectl apply -f -

kubescape mcpserver

Start the MCP (Model Context Protocol) server for AI assistant integration.

Synopsis

kubescape mcpserver

Description

Starts an MCP server that exposes Kubescape data to AI assistants. The server communicates via stdio.

Prerequisites

Kubescape operator installed in the cluster
kubectl configured with cluster access

Examples

# Start MCP server
kubescape mcpserver

Claude Desktop Configuration

{
  "mcpServers": {
    "kubescape": {
      "command": "kubescape",
      "args": ["mcpserver"]
    }
  }
}

kubescape version

Display version information.

Synopsis

kubescape version

kubescape completion

Generate shell completion scripts.

Synopsis

kubescape completion <shell>

Supported Shells

bash
zsh
fish
powershell

Examples

# Bash
kubescape completion bash > /etc/bash_completion.d/kubescape

# Zsh
kubescape completion zsh > "${fpath[1]}/_kubescape"

# Fish
kubescape completion fish > ~/.config/fish/completions/kubescape.fish

Environment Variables

Kubescape respects the following environment variables:

Variable	Description
`KS_ACCOUNT`	Default account ID
`KS_CACHE_DIR`	Cache directory path
`KS_EXCLUDE_NAMESPACES`	Default namespaces to exclude
`KS_INCLUDE_NAMESPACES`	Default namespaces to include
`KS_FORMAT`	Default output format
`KS_LOGGER`	Log level
`KS_LOGGER_NAME`	Logger name
`KUBECONFIG`	Path to kubeconfig file
`KUBESCAPE_MASTER_KEY`	32-character master key used to encrypt and decrypt report metadata
`HTTPS_PROXY`	HTTPS proxy URL
`HTTP_PROXY`	HTTP proxy URL
`NO_PROXY`	Hosts to exclude from proxy

Exit Codes

Code	Description
`0`	Success
`1`	Failure (threshold exceeded, scan failed, etc.)