nitinjain999/platform-skills/kubescape

Find out how a Kubernetes change or cluster measures up against a security framework, in plain language, and stop new problems at the pull request.

Read references/kubescape.md before responding. It holds the verified install, the framework table, gate exit codes, the baseline recipe, how the two exception actions really behave, fix limits, the VAP rollout, and troubleshooting. The working files are in examples/kubescape.

The primary cloud for this organisation is ${user_config.primary_cloud}. If that reads as a literal placeholder or is empty, it is not configured: detect the provider from the cluster, or ask.

Ownership boundary (enforced at the menu)

Mode dispatch

Parse the first word of $ARGUMENTS as the mode. When $ARGUMENTS is empty, or is a question in plain words, run the interactive wizard.

Step 0 — detect before asking (silent)

Run these quietly and use the answers to skip questions. Never ask what the repository or cluster already tells you.

command -v kubescape && kubescape version                     # installed? version?
kubectl config current-context 2>/dev/null                     # is there a cluster?
kubectl version -o json 2>/dev/null | jq -r .serverVersion.gitVersion       # -eks- / -gke. → managed distribution
kubectl get nodes -o jsonpath='{.items[0].metadata.labels.kubernetes\.azure\.com/cluster}' 2>/dev/null   # non-empty → AKS
kubectl get nodes -o jsonpath='{.items[0].spec.providerID}' 2>/dev/null   # aws:// azure:// gce:// — a hint only
git ls-files | grep -E '(^|/)(Chart\.yaml|kustomization\.ya?ml)$'          # charts, overlays
git ls-files '*.yaml' '*.yml' | xargs grep -l '^kind:' 2>/dev/null | head  # plain manifests
ls .github/workflows/ 2>/dev/null; ls .kubescape/ 2>/dev/null               # existing CI, exceptions

• Kubescape missing → offer the install (laptop: brew install kubescape; CI and servers: the verified download in the reference) before anything else.
• Version below 4 → say so: --baseline, --kube-contexts and the disable exception behaviour described here need v4.
• Current context looks like production (name contains prod) → confirm before a cluster scan; it is read-only but heavy on the API server for large clusters.

Interactive wizard

Ask with the AskUserQuestion tool when it is available (one question per call, the recommended option first); otherwise print the numbered menu and wait. Three layers; stop as soon as the mode is clear.

Layer 1 — What do you want to know? (intent, in their words)

What are you trying to find out?
  1. "Is this change / chart safe to deploy?"         → scan
  2. "How secure is my cluster right now?"            → cluster
  3. "Stop insecure Kubernetes changes in PRs"        → ci
  4. "We've accepted this risk — stop flagging it"    → exceptions
  5. "Fix what Kubescape found"                       → fix
  6. "Block this at admission"                        → vap  (Kyverno installed? → /platform-skills:kyverno)
  7. "Is this image vulnerable?"                      → image (CI gate? → /platform-skills:trivy)
 
  Watch the cluster continuously / runtime alerts / NetworkPolicies → /platform-skills:kubescape-operator

Pre-select from Step 0: no cluster but manifests → 1; cluster and no manifests → 2; a workflow directory and no Kubescape job → mention 3.

Layer 2 — Measured against what? (framework, in plain words)

What should it be measured against?
  a. General hardening (NSA-CISA)                     → NSA        [recommended for manifests and charts]
  b. Attacker techniques (MITRE ATT&CK)               → MITRE
  c. An audit benchmark (CIS)                         → picked for you: <cis-eks-t1.8.0 | cis-aks-t1.8.0 | cis-gke-v1.9.0 | cis-v1.12.0>
  d. SOC 2 audit evidence                             → SOC2       (Terraform side → /platform-skills:compliance)
  e. Hardening + attacker techniques                  → nsa,mitre  [recommended for CI]

Pick the CIS benchmark from the distribution, not the cloud: API server gitVersion with -eks- → EKS, with -gke. → GKE, nodes labelled kubernetes.azure.com/cluster → AKS, otherwise cis-v1.12.0. providerID and the primary cloud above are only hints: a self-managed cluster on EC2 also reports aws://. When the hints and the signals disagree, or there is no cluster, ask which distribution it is. Say which benchmark and why. Skip this layer for exceptions, fix and image.

Layer 3 — Only the settings that can hurt

Ask only where a wrong default causes harm; offer the recommended value so Enter accepts it.

• Gate strictness (ci, or scan in a pipeline): "Fail on new High or Critical findings? [Y]". Explain that without a gate Kubescape always exits 0.
• Existing debt (ci, when a first scan shows more than about 10 failed controls): "Gate only on findings a PR adds (baseline)? [Y]". Brownfield repos need this, or the first PR after rollout fails for problems it did not create.
• Accepted risk (exceptions): the reason in one sentence and a review date, default 90 days. Never write an exception without both.
• Fix scope (fix): "Preview only, write fixed copies, or edit in place? [Preview]".

Do not pepper with questions. If the user typed a full command (/platform-skills:kubescape scan charts/api), run it.

Result card (every mode ends with this)

Translate the report; do not paste the raw table. Build it with the jq result-card helper in the reference.

Kubescape — NSA on charts/payments-api           Score: 45%   (gate: FAIL, 5 High)
 
Fix first:
  HIGH  C-0057  Privileged container                     payments-api   → securityContext.privileged: false
  HIGH  C-0041  HostNetwork access                       payments-api   → remove hostNetwork: true
  HIGH  C-0012  Credentials in configuration files       payments-api   → move DB_PASSWORD to a Secret (secretKeyRef)
  HIGH  C-0270  CPU limits not set                       payments-api   → resources.limits.cpu
  HIGH  C-0271  Memory limits not set                    payments-api   → resources.limits.memory
 
Kubescape can fix 5 of 11 automatically.        Next: /platform-skills:kubescape fix

One line of "why it matters" per control when the user is new to it (for example, privileged means root on the node). One suggested next command, not a list.

Mode: scan

1. Resolve the target: a path, a chart (Chart.yaml), an overlay (kustomization.yaml), a git URL, or - for stdin.
2. Helm: when Chart.yaml lists dependencies, build them first and stop on errors (helm repo add each https:// repository, then helm dependency build). Kubescape tries itself but only warns on failure and then scans without the subcharts. Pass --kube-version from the target cluster when known.
3. Run:

kubescape scan framework <framework> <target> --format json --output /tmp/kubescape.json

1. Print the result card. If the score is 100, say what was not checked: image contents (image mode) and host settings (cluster with the operator).

Mode: cluster

1. Confirm the context from Step 0 and the framework from Layer 2.
2. Run (read-only):

kubescape scan framework <framework> [--include-namespaces a,b] --format json --output /tmp/cluster.json
# several clusters:
kubescape scan framework <framework> --kube-contexts prod-eu,prod-us --fleet-report fleet.json --output cluster.json

1. Print the result card, then the skipped count. When controls are skipped for missing: hostdata…, say how many and offer /platform-skills:kubescape-operator install: on a CIS scan without it, about 40% of controls cannot run.
2. For a fleet, lead with divergence: controls that pass on one cluster and fail on another usually mean configuration drift.

Mode: ci

1. Copy examples/kubescape/workflows/kubescape.yml to .github/workflows/kubescape.yml.
2. Set SCAN_PATH from Step 0, FRAMEWORKS from Layer 2, SEVERITY_THRESHOLD from Layer 3.
3. If the repository has a different default branch, check on.push.branches.
4. Explain the three behaviours: PRs fail only on new findings (baseline from a worktree of the same clone), main reports without gating, expired disable exceptions fail the job.
5. Tell the user to make posture a required check.
6. Run zizmor on the new workflow if available (/platform-skills:zizmor).

Never: kubescape/github-action (bundles CLI v3.0.21), tj-actions/changed-files, unpinned uses:, a gate without --controls-version, a scan without --honor-inline-exceptions=false (a PR could suppress its own finding with a kubescape.io/skip-controls annotation), or a paths filter on the pull_request trigger of a required check (it would stay pending and block merges).

Mode: exceptions

1. Identify control ID, resource kind, namespace and name from the user or the last report.
2. Ask the reason and review date (Layer 3).
3. Write the entry to .kubescape/exceptions.json with "actions": ["disable"] and the name ending -until-YYYY-MM-DD. Use "alertOnly" only when the user wants the finding to keep failing (acknowledged, still tracked). Never any other actions form: an empty list, a missing field, a mixed list or a typo all suppress like disable.
4. Re-run the scan with --exceptions and show the control moving to passed (w/exceptions).
5. Ask whether the exception should also exist in the cluster: SecurityException with expiresAt → /platform-skills:kubescape-operator exceptions.

State plainly: alertOnly does not stop a gate; only disable does.

Mode: fix

1. Scan to JSON, then kubescape fix <report> --dry-run and translate the stderr output into a short list.
2. Warn about the two changes that break apps: readOnlyRootFilesystem: true (writes outside a volume) and runAsUser: 1000 (image built for another UID).
3. On approval: --output-dir for copies, or in place in a clean git tree so git diff is the review.
4. List what was not fixed and give the manual fix for each (limits, seccomp, NetworkPolicy, Secrets).
5. Cluster reports: write patched manifests to Git, never pipe to kubectl apply on production.

Mode: vap