Kubesplaining

Kubesplaining is an open-source Kubernetes security assessment CLI that reads a live cluster or a captured snapshot and tells you exactly how an attacker can move through it. Unlike scanners that stop at "this resource is misconfigured," it builds a multi-hop RBAC privilege-escalation graph from every non-system subject to nine sinks (among them cluster-admin, system:masters, node-escape, and kube-system-secrets) and renders each chain with the actual verbs, evidence, and remediation. Outputs are risk-prioritized HTML, JSON, CSV, and SARIF reports for human review, GitHub code scanning, or CI delta gates.

The Attack paths tab of the HTML report. Each box is an identity and each arrow is one hop. The columns show how many hops an identity is from the target. Here, 23 paths end at cluster-admin, and the longest has three hops.

• Live example report

Install

Pick whichever fits your workflow.

From a fresh clone (easiest, no install needed):

git clone https://github.com/0hardik1/kubesplaining
cd kubesplaining
make scan

make scan builds the binary (Hermit auto-downloads the pinned Go toolchain) and runs it against your current kubectl context in one step.

See Installation below for krew, go install, pre-built binaries, and checksums.

vs the alternatives

Most scanners overlap on "is this pod privileged?" The differentiator is whether they show you the chain from a non-admin subject to cluster takeover, and whether they ship an actionable fix.

Inspired by Kinnaird McQuade at BeyondTrust Phantom Labs and his Cloudsplaining, which does the same job for AWS IAM. Kubesplaining reads a live cluster or a previously captured snapshot, analyzes it against a library of techniques, and produces a prioritized list of findings: explanation, not just detection.

Why kubesplaining

Most Kubernetes scanners stop at "this resource is misconfigured." Kubesplaining answers a different question: how would an attacker actually move through your cluster? Given the RBAC bindings and pods you already have, it walks the escalation graph from every non-system subject and tells you which can reach cluster-admin, host root, or kube-system secrets, with the full hop chain attached.

It focuses on the ground attackers actually exploit:

• Privilege escalation paths: graph-based chains of "subject A can become subject B can reach sink X" via BFS to nine sinks (cluster-admin, system:masters, node-escape, kube-system-secrets, namespace-admin, token-mint, aws-iam-role, traffic-intercept, node-identity).
• Overly permissive RBAC: wildcards, impersonation, bind/escalate, secret reads, pod creation, token mint.
• Pod-escape surface area: privileged containers, host namespaces, sensitive hostPath mounts, container socket mounts.
• Network isolation gaps: namespaces with no NetworkPolicy, policies that allow broad internet egress.
• Admission-control bypass: webhooks that fail open, objectSelector bypasses, exempt sensitive namespaces.
• Secrets and service-account hygiene: legacy token secrets, credentials in ConfigMaps, default-SA mounting, DaemonSet token blast-radius.

Every finding names the technique, shows the evidence, and includes remediation.

Use cases:

• Pentest / red-team engagements: the escalation paths are the attack plan.
• Security review before a new binding: see if it closes the graph from someone untrusted to a sink.
• Continuous assurance in CI: --ci-mode with severity budgets fails the pipeline when high-severity findings cross a threshold.
• Post-incident replay: capture the snapshot, analyze offline, explain how the actor could have moved.

Quickstart

After installing (see Installation below), point Kubesplaining at your current kubectl context:

kubesplaining scan                          # writes ./kubesplaining-report/
open kubesplaining-report/report.html       # macOS; xdg-open on Linux

To ask one question in the terminal, with no report to open:

kubesplaining paths --to cluster-admin              # who can reach cluster-admin?
kubesplaining paths --from ServiceAccount/dev/ci    # what can this identity reach?

See Ask a question for the output and the other filters.

Already cloned the repo? make scan builds the binary (Hermit auto-downloads the pinned Go toolchain) and runs it against your current kubectl context in one step, no separate install needed. Pass extra flags via ARGS, e.g. make scan ARGS="--severity-threshold high --only-modules privesc".

For air-gapped or audit workflows, capture a snapshot first and analyze it offline:

kubesplaining download --output-file snapshot.json
kubesplaining scan --input-file snapshot.json

For one-off manifest checks without cluster access:

kubesplaining scan-resource --input-file deployment.yaml

Installation

Pick the path that fits. They all produce the same kubesplaining CLI. The top of this README covers the from-clone path; this section adds krew, Go install, pre-built binaries, and Docker.

kubectl krew

Install as a kubectl plugin via Krew:

kubectl krew install kubesplaining
kubectl kubesplaining scan

Every command in this README works the same way behind kubectl, e.g. kubectl kubesplaining scan --input-file snapshot.json.

Go install

go install github.com/0hardik1/kubesplaining/cmd/kubesplaining@latest

Pre-built binary

Grab the archive matching your OS / arch from the Releases page, extract, and put kubesplaining on your PATH. Each release ships:

• kubesplaining_<version>_Linux_x86_64.tar.gz / Linux_arm64.tar.gz
• kubesplaining_<version>_Darwin_x86_64.tar.gz / Darwin_arm64.tar.gz
• kubesplaining_<version>_Windows_x86_64.zip
• kubesplaining_<version>_checksums.txt (SHA-256)

Verify the checksum, then move the binary into place:

shasum -a 256 -c kubesplaining_<version>_checksums.txt
sudo install kubesplaining /usr/local/bin/

Docker

docker run --rm \
  --user "$(id -u):$(id -g)" \
  -v "$HOME/.kube/config:/kubeconfig:ro" -e KUBECONFIG=/kubeconfig \
  -v "$PWD:/work" -w /work \
  ghcr.io/0hardik1/kubesplaining:latest scan

The report is written to ./kubesplaining-report/ in the current directory. --user makes the container run as you, so it can read your kubeconfig and write the report with your ownership.

The image holds only the kubesplaining binary. Two kinds of kubeconfig do not work from inside it:

• A kubeconfig that calls a helper program for credentials (EKS with aws eks get-token, GKE with gke-gcloud-auth-plugin).
• A kubeconfig that points at 127.0.0.1 (kind, minikube, Docker Desktop).

For those clusters, use the binary. You can also capture a snapshot with the binary and analyze it in the container, which needs no kubeconfig:

docker run --rm --user "$(id -u):$(id -g)" -v "$PWD:/work" -w /work \
  ghcr.io/0hardik1/kubesplaining:latest scan --input-file snapshot.json

What it checks

104 stable rule IDs across 11 modules today, plus the privilege-escalation graph that chains them. Full per-rule severity, detection logic, and remediation: docs/findings.md.

Every finding is tagged with a RiskCategory (privilege_escalation, data_exfiltration, lateral_movement, infrastructure_modification, defense_evasion) so the HTML report can group by impact lane.

Rule IDs are a public surface: they are stable across releases and referenced from findings.json, the SARIF output, and the e2e assertions in scripts/kind-e2e.sh.

How it works

Four-stage pipeline:

┌───────────────┐    ┌───────────────┐    ┌───────────────┐    ┌───────────────┐
│  Connection   │ →  │  Collection   │ →  │   Analysis    │ →  │    Report     │
│  kubeconfig   │    │ snapshot.json │    │ 11 modules ∥  │    │  html/json/   │
│ / in-cluster  │    │ RBAC+workload │    │  findings[]   │    │   csv/sarif   │
└───────────────┘    └───────────────┘    └───────────────┘    └───────────────┘

The boundary that matters most: the collector is the only thing that talks to the Kubernetes API; analyzers consume a Snapshot and never make network calls. That's what makes download → scan --input-file work for offline analysis. Read-only access is sufficient: no admission webhooks, no agents, no CRDs installed.

For the per-stage walkthrough, the privesc graph mechanics, the data model, and the scoring formula: docs/architecture.md.

Sample finding

What the output looks like. Each rule produces a finding with a stable rule_id, a severity, evidence, and a remediation. A privesc path finding also has an escalation_path array.

The three samples below come from the findings.json of the live example report. Each sample is abridged: the long text fields (description, impact, attack_scenario, remediation_steps, references, learn_more) and the namespace, scope, tags, mitre_techniques, and frameworks fields are left out.

{
  "id": "KUBE-PRIVESC-PATH-CLUSTER-ADMIN:ServiceAccount/rbac-fixtures/sa-pod-create:cluster_admin_equivalent",
  "rule_id": "KUBE-PRIVESC-PATH-CLUSTER-ADMIN",
  "severity": "CRITICAL",
  "score": 9.25,
  "category": "privilege_escalation",
  "title": "`ServiceAccount/rbac-fixtures/sa-pod-create` can reach **cluster-admin equivalent** in 2 hop(s)",
  "subject": { "kind": "ServiceAccount", "name": "sa-pod-create", "namespace": "rbac-fixtures" },
  "evidence": {
    "chain_summary": [
      "1. pod_create_token_theft [create pods]",
      "2. wildcard_permission [*:*:*]"
    ],
    "first_action": "pod_create_token_theft",
    "hop_count": 2,
    "target": "cluster_admin_equivalent",
    "target_namespace": "",
    "techniques": [
      "pod_create_token_theft",
      "wildcard_permission"
    ]
  },
  "escalation_path": [
    {
      "step": 1,
      "action": "pod_create_token_theft",
      "technique": "KUBE-PRIVESC-001",
      "difficulty": "moderate",
      "from_subject": { "kind": "ServiceAccount", "name": "sa-pod-create", "namespace": "rbac-fixtures" },
      "to_subject": { "kind": "ServiceAccount", "name": "cert-manager", "namespace": "cert-manager" },
      "permission": "create pods",
      "gains": "can create pods that mount ServiceAccount cert-manager/cert-manager",
      "source_binding": "crb-pod-create",
      "source_role": "cr-pod-create"
    },
    {
      "step": 2,
      "action": "wildcard_permission",
      "technique": "KUBE-PRIVESC-017",
      "difficulty": "easy",
      "from_subject": { "kind": "ServiceAccount", "name": "cert-manager", "namespace": "cert-manager" },
      "to_subject": { "kind": "", "name": "" },
      "permission": "*:*:*",
      "gains": "wildcard verbs on wildcard resources in wildcard API groups",
      "source_binding": "cutres-deputy-cm-admin",
      "source_role": "cluster-admin"
    }
  ],
  "remediation": "Break the chain at the weakest hop: remove the `create pods` capability that enables hop 1 (`ServiceAccount/rbac-fixtures/sa-pod-create` → `ServiceAccount/cert-manager/cert-manager`)."
}

{
  "id": "KUBE-ESCAPE-001:Deployment:vulnerable:risky-app:app",
  "rule_id": "KUBE-ESCAPE-001",
  "severity": "CRITICAL",
  "score": 9.9,
  "category": "privilege_escalation",
  "title": "Privileged container `app` in `Deployment/vulnerable/risky-app`",
  "resource": { "kind": "Deployment", "name": "risky-app", "namespace": "vulnerable", "api_group": "apps" },
  "evidence": { "container": "app" },
  "remediation": "Remove `privileged: true` and explicitly grant only the Linux capabilities the workload actually needs."
}

{
  "id": "KUBE-RBAC-OVERBROAD-001:ServiceAccount/rbac-fixtures/sa-cluster-admin::",
  "rule_id": "KUBE-RBAC-OVERBROAD-001",
  "severity": "CRITICAL",
  "score": 10,
  "category": "privilege_escalation",
  "title": "Non-system subject `ServiceAccount/rbac-fixtures/sa-cluster-admin` directly bound to `cluster-admin`",
  "subject": { "kind": "ServiceAccount", "name": "sa-cluster-admin", "namespace": "rbac-fixtures" },
  "resource": { "kind": "RBACRule", "name": "cluster-admin", "api_group": "rbac.authorization.k8s.io" },
  "evidence": {
    "api_groups": null,
    "namespace": "",
    "resource_names": null,
    "resources": null,
    "scope": "cluster",
    "source_binding": "crb-cluster-admin",
    "source_binding_kind": "ClusterRoleBinding",
    "source_role": "cluster-admin",
    "source_role_kind": "ClusterRole",
    "verbs": null
  },
  "remediation": "Replace `cluster-admin` with a custom least-privilege ClusterRole, or scope the binding to a dedicated short-lived admin group reachable only via JIT/break-glass procedures."
}

For the full rule catalog (severity, detection, remediation per rule): docs/findings.md.

Ask a question

scan writes a full report. paths answers one question in the terminal. It searches the same graph, so each path has the same ID, score, and hops as the finding in the report.

Who can reach a target? --to keeps the paths that end at one target:

$ kubesplaining paths --to cluster-admin
SEVERITY  SCORE  SOURCE                                TARGET         HOPS  CHAIN
CRITICAL  9.65   ServiceAccount/dashboard/admin-sa     cluster-admin  1     bound_to_cluster_admin
CRITICAL  9.25   ServiceAccount/monitoring/prometheus  cluster-admin  2     pod_create_token_theft > bound_to_cluster_admin

2 attack paths.

What can one identity reach? --from starts the search at that identity. Add --verbose to see each hop, the binding that grants it, and the fix:

$ kubesplaining paths --from ServiceAccount/monitoring/prometheus --to cluster-admin --verbose
ServiceAccount/monitoring/prometheus -> cluster-admin
  severity: CRITICAL (score 9.25)   hops: 2
  id: KUBE-PRIVESC-PATH-CLUSTER-ADMIN:ServiceAccount/monitoring/prometheus:cluster_admin_equivalent

  1. pod_create_token_theft (moderate)
     from:       ServiceAccount/monitoring/prometheus
     to:         ServiceAccount/dashboard/admin-sa
     permission: create pods
     granted by: ClusterRoleBinding prometheus-reader (role prometheus-reader)
     result:     can create pods that mount ServiceAccount dashboard/admin-sa
  2. bound_to_cluster_admin (easy)
     from:       ServiceAccount/dashboard/admin-sa
     to:         cluster-admin
     permission: cluster-admin
     granted by: ClusterRoleBinding dashboard-admin (role cluster-admin)
     result:     bound to cluster-admin via dashboard-admin

  fix: Break the chain at the weakest hop: remove the create pods capability that enables hop 1 (ServiceAccount/monitoring/prometheus → ServiceAccount/dashboard/admin-sa).
    # Edit the binding and remove the offending subject from subjects:.
    kubectl edit clusterrolebinding prometheus-reader

The real output ends with a diff of that binding, left out here.

paths reads the live cluster by default. Each run collects the cluster again, so for more than one question capture the cluster one time and ask offline. An answer from a snapshot takes less than a second and needs no cluster access:

kubesplaining download --output-file snapshot.json
kubesplaining paths --input-file snapshot.json --to node-escape
kubesplaining paths --input-file snapshot.json --from ServiceAccount/dev/ci --output-format json

Three behaviors to know:

• With no --from, paths lists the attack paths that scan reports, and the same exclusions apply. The output says how many paths the exclusions hide.
• --from ignores the exclusions, and it accepts an identity that scan does not use as a starting point: a built-in system: identity, a control-plane ServiceAccount, or a group such as Group/system:authenticated ("what can every authenticated user reach?").
• An identity that is not in the cluster is an error, not an empty answer. An empty answer for a mistyped name would look like "this identity is safe".

Check a change before you apply it

--overlay applies manifests on top of a snapshot in memory. --overlay-delete removes one object. --diff then lists the attack paths that the change adds, removes, and changes. Nothing touches the cluster, so you can ask "does this RoleBinding open a path?" in a pull request, or "does this fix close the path?" before you run kubectl.

A new binding that looks harmless in review:

$ kubesplaining paths --input-file snapshot.json --overlay ci-deployer-admin.yaml --diff
ADDED (2)
SEVERITY  SCORE  SOURCE                         TARGET         HOPS  CHAIN
CRITICAL  9.65   ServiceAccount/ci/deployer     cluster-admin  1     bound_to_cluster_admin
CRITICAL  9.25   ServiceAccount/default/reader  cluster-admin  2     pod_create_token_theft > bound_to_cluster_admin

The change adds 2 attack paths, removes 0, and changes 0. 2 stay the same.
$ echo $?
2

The first path is in the manifest. The second is not: default/reader can create pods, so it can now start a pod that runs as the new admin ServiceAccount.

A fix, checked before it is applied:

$ kubesplaining paths --input-file snapshot.json --overlay-delete ClusterRoleBinding/reader-role --diff
REMOVED (2)
SEVERITY  SCORE  SOURCE                         TARGET               HOPS  CHAIN
CRITICAL  9.0    ServiceAccount/default/reader  node-escape          1     pod_create_privileged_escape
HIGH      8.45   ServiceAccount/default/reader  kube-system-secrets  1     read_secrets

The change adds 0 attack paths, removes 2, and changes 0. 0 stay the same.

A path that stays open by a second route is not listed as removed. It is listed under CHANGED, with the binding behind each route, so a fix that is not sufficient does not look like a fix:

$ kubesplaining paths --input-file snapshot.json --to cluster-admin --overlay-delete ClusterRoleBinding/reader-admin-a --diff
CHANGED (1): still open, by a different route
ServiceAccount/default/reader -> cluster-admin
  before: bound_to_cluster_admin [ClusterRoleBinding reader-admin-a (role cluster-admin)]
          also: bound_to_cluster_admin [ClusterRoleBinding reader-admin-b (role cluster-admin)]
  after:  bound_to_cluster_admin [ClusterRoleBinding reader-admin-b (role cluster-admin)]

The change adds 0 attack paths, removes 0, and changes 1. 0 stay the same.

For a Helm chart or a Kustomize directory, render first and pipe the result in:

helm template my-release ./chart | kubesplaining paths --input-file snapshot.json --overlay - --diff

What the overlay does and does not model:

• It applies Role, ClusterRole, RoleBinding, ClusterRoleBinding, ServiceAccount, Namespace, and Pod. It skips other kinds and says so. A Deployment in the overlay adds no pod, because no controller runs. To model a new workload, overlay a Pod with the same pod spec.
• After a change to a ClusterRole, it derives the rules of the aggregated ClusterRoles (admin, edit, view, and your own) again, so a new role with an aggregate-to-* label has its effect.
• --diff does not apply the default exclusions, so a path that the change adds is never hidden. Pass an exclusions flag to apply them.
• scan takes the same three --overlay flags and writes a full report of the state after the change. The report says that it includes an overlay.

Use with an AI agent

The repository ships an Agent Skill named attack-paths. A skill is a Markdown file that tells a coding agent when and how to use a tool. With the skill installed, you can ask in plain words:

• "Who can reach cluster-admin in this cluster?"
• "What can the ci ServiceAccount in dev escalate to? Give me the smallest fix."
• "Review the RBAC in this cluster and show me the three worst paths."

The agent captures a snapshot with kubesplaining download, gets the answer from kubesplaining paths as JSON, explains each hop, proposes the change to the binding, and checks that change offline with --overlay and --diff before it shows it to you. The skill tells the agent not to change the cluster: you get a command or a patch, and you apply it.

In Claude Code:

/plugin install kubesplaining --marketplace 0hardik1/kubesplaining

Or from a shell:

claude plugin marketplace add 0hardik1/kubesplaining
claude plugin install kubesplaining@kubesplaining

For other agents: the skill uses only the fields of the open Agent Skills format, so an agent that reads SKILL.md files can use it. Copy plugins/kubesplaining/skills/attack-paths/ into the skills directory of your agent.

What to know before you use it:

• The skill needs the kubesplaining binary on your PATH, from v1.4.0 or later, the first release that has the paths command. It does not install the binary for you.
• The agent runs the binary with your kubeconfig, so it can read what you can read. kubesplaining only reads.
• The agent sees the output of paths: the names of identities, bindings, and roles. The skill tells it to keep the snapshot file out of the repository and not to send the file to a different service.

Offline analysis

The collector and the analyzer are decoupled: the snapshot is a plain JSON file. Capture once, analyze repeatedly, in environments where credentials shouldn't sit on the analyst's machine:

# On a jumphost with cluster credentials:
kubesplaining download --output-file snapshot.json

# Move snapshot.json to your laptop / audit machine, then:
kubesplaining scan --input-file snapshot.json

Useful for:

• Audit trails: the snapshot is the evidence; reruns produce identical findings.
• Air-gapped review: analyze a production cluster without bringing kubeconfig off the jumphost.
• Manifest scans: kubesplaining scan-resource --input-file deployment.yaml runs the same analyzers against a single YAML, no cluster needed.

Privacy posture for snapshots

The collector never reads raw Secret values (only metadata) and blanks every ConfigMap value through redactConfigMapValues so keys survive but payloads do not. Two well-known kube-system ConfigMaps are carve-outs and are stored verbatim because the analyzers that consume them need the values:

• kube-system/aws-auth: the EKS mapRoles / mapUsers payload (IAM role and user ARNs, mapped Kubernetes usernames and groups) is read by the cloud aws-auth analyzers to name the IAM principal that has cluster-admin reach. A snapshot from an EKS cluster therefore contains the cluster's IAM-to-RBAC trust map verbatim.
• kube-system/coredns: the Corefile value is substring-matched by KUBE-CONFIGMAP-002 to detect rewrite directives and external DNS forwarders (forward . 8.8.8.8, forward . 1.1.1.1, forward . tls://...).

Treat snapshot files (and any HTML/JSON/CSV/SARIF reports generated from them) as sensitive when sharing across teams or storing in CI artifact buckets, especially on EKS clusters where the aws-auth carve-out exposes account IDs, IAM role inventory, and SSO group naming conventions. Every other ConfigMap value (including ones not on this allow-list) is blanked.

Live EKS demo

Provisions a real EKS cluster in your own AWS account that exhibits a cross-namespace + AWS-pivot privilege escalation chain kubesplaining detects, then walks through actually exploiting it (privileged-pod node escape → harvest a co-resident IRSA token → assume the AWS role via STS → loop back as system:masters via aws-auth). Useful as a self-service teaching environment.

make eks-demo-up      # ~12 min: cluster + IAM + S3 + K8s manifests + aws-auth mapping
make eks-demo-scan    # ~30 sec: produces .tmp/eks-demo-report/report.html
make eks-demo-poc     # default dry-run; --execute to step through the attack interactively
make eks-demo-down    # ~10 min: tears down everything (cluster, IAM role, S3 bucket)

The cluster is named holy-splain. All AWS resources carry generic, account-agnostic names so the same scripts reproduce identically across operators. Cost: approximately $5/day while running.

Three docs go with the demo:

• docs/eks-demo.md: operator reference (prereqs, commands, troubleshooting).
• docs/eks-demo-walkthrough.md: chapter-style learning narrative. Walks through the attack chain step by step, explains every K8s and AWS internal involved (IRSA, projected SA tokens, Pod Security Admission, aws-auth, STS assume-role-with-web-identity), and ends with a defense recap of where each link in the chain could be broken.
• docs/eks-demo-iam.md: operator IAM permissions required to run the setup.

Least-Privilege analyzer (audit-log driven)

The leastprivilege module compares the RBAC permissions a ServiceAccount has (from the snapshot) against the ones it has actually exercised (from a kube-apiserver audit log) and flags the delta. It's the analog of AWS IAM Access Advisor for Kubernetes RBAC.

It emits four rule IDs:

• KUBE-RBAC-UNUSED-ROLE-001: Role bound to a mounted SA with zero observed events in the audit window.
• KUBE-RBAC-UNUSED-RULE-001: Every (verb, resource) triple in a Role rule is unused.
• KUBE-RBAC-UNUSED-VERB-001: Some verbs in a Role rule are unused; suggests a narrower verb list.
• KUBE-RBAC-WILDCARD-USED-PARTIAL-001: verbs: ["*"] is granted but the SA only used a subset.

The pre-existing KUBE-RBAC-STALE-* rules surface alongside in the Least privilege HTML tab so dangling-binding cleanup and verb-level narrowing live in one view. Cluster-admin grants live in their own "Subjects bound to cluster-admin" inventory table on the same tab: directly bound subjects are listed for review rather than each one being flagged CRITICAL, because cluster-admin has legitimate uses (system:masters, break-glass groups) that vary by cluster. The standalone KUBE-RBAC-OVERBROAD-001 finding still fires from the rbac module and shows up in the main Findings tab (and in JSON/CSV/SARIF output) for operators who want the per-binding alert.

When does it fire?

The module is opt-in via --audit-log. A plain kubesplaining scan (no audit log) silently skips it, so no LP findings ship and existing CI baselines stay unchanged.

Quick start

# 1. Capture audit logs from your cluster - see docs/audit-logs.md for
#    kubeadm / kind / EKS setup. Audit policy level "Metadata" is enough.

# 2. Run the focused mode against a snapshot (or live cluster) + your audit log:
make scan-lp AUDIT_LOG=./audit.log ARGS="--input-file snapshot.json"

# or directly:
kubesplaining scan \
  --input-file snapshot.json \
  --audit-log ./audit.log \
  --audit-source native \
  --audit-window-days 30 \
  --least-privilege-only

What's in the report

The Least privilege tab carries two summary tables on top, each row spelling out the exact action:

• Unused RBAC objects: Roles/ClusterRoles/Bindings that look like delete candidates. Each row names the object to remove (e.g. Delete RoleBinding/billing/cleanup-cron (target Role missing)).
• Verbs to remove: Verb-level narrowing opportunities with side-by-side Used vs Unused verb lists grouped by verb (get: deployments|pods), plus a "What to do" action and the suggested narrower-Role YAML on the per-finding card below.

When the audit log contains non-ServiceAccount callers (humans, groups, kubelets), the tab shows a one-line note explaining they're out of scope: kubesplaining only correlates ServiceAccount-bound RBAC, and human users belong in IdP / SSO group review.

Audit log details

docs/audit-logs.md walks through enabling audit logging on self-managed / kubeadm, kind, and EKS clusters, what audit-policy level is needed, and how to export from CloudWatch. The privacy posture is preserved: audit Metadata level does not include request bodies, so secrets and ConfigMap values are still never read.

CI integration

The SARIF output integrates with GitHub code scanning so findings appear as PR annotations. On GitHub Actions, the GitHub Action runs the scan and uploads findings.sarif in one step.

On any other CI system, call the CLI and fail the build on findings over budget with --ci-mode:

kubesplaining scan --ci-mode --ci-max-critical 0 --ci-max-high 0

--ci-mode exits with code 2 when the count of critical / high findings crosses the configured thresholds; combine with --severity-threshold to scope what counts. Any other failure (bad flags, unreachable cluster) exits with code 1, so a pipeline can tell "over budget" from "the scan did not run". The gate counts every finding: --max-findings shortens the HTML report only.

Exclusions

scan, scan-resource, and report auto-apply the standard exclusions preset by default, so findings about built-in Kubernetes plumbing are suppressed up front. That covers kube-system / kube-public / kube-node-lease / gatekeeper-system namespaces, kube-controller-manager service accounts (clusterrole-aggregation-controller, generic-garbage-collector, …), system:* users / groups / roles, and kubeadm:* groups and bootstrap roles. None of it is something an operator can change without breaking their cluster, so showing it as risk just buries the things that are actionable.

Pick a different baseline with --exclusions-preset:

Layer custom rules on top with --exclusions-file path.yml. The user file is merged with the preset, so you keep the defaults and add your own suppressions (specific service accounts, expected workloads, custom rule-ID patterns). Generate a starter file:

kubesplaining create-exclusions-file --preset standard --output-file exclusions.yml

See docs/exclusions.md for the full YAML schema (Global / RBAC / PodSecurity / NetworkPolicy sections, all matchers support shell-style globs).

To audit what the defaults are hiding, re-run with --exclusions-preset=none and diff.

Cheatsheet

Commands

Frequently used flags

Output formats

FAQ

Why is system:masters flagged in some clusters but not others? The privesc analyzer skips system:* subjects as traversable intermediates (so paths don't launder through the control plane) but it does report system:* as a sink-reach target if you can impersonate or otherwise escalate into it. If the analyzer doesn't see anyone with that capability, the rule stays silent. Three built-in groups are traversed rather than skipped: system:authenticated, system:serviceaccounts, and system:serviceaccounts:<ns>. Every identity of the matching type belongs to them, so a grant to one of them is reported as a path from each member.

How accurate are the privesc paths? Each hop is validated against the snapshot's RBAC and pod state. The analyzer doesn't speculate. False positives come from chains that are structurally possible but operationally suppressed (e.g. an SA bound to a role that's never actually used). The score goes down with the difficulty of the hops, not with the length of the chain: each hop is rated easy, moderate, or hard, and a chain that has a hard hop drops one severity level. --max-privesc-depth sets the maximum number of hops in a path (default 5).

Can I run this against my prod cluster? Yes. Read-only access is sufficient. No webhooks, CRDs, agents, or pods are installed. Forbidden listings are downgraded to warnings, not fatal, so locked-down clusters still produce useful output.

Why no admission webhook? Out of scope. The intent is assessment, not enforcement. If you want enforcement, generate Kyverno / Gatekeeper policies from the findings (--remediation-patches) and hand them off to your policy engine.

Why are findings excluded by default? The standard preset suppresses control-plane noise (kube-system, system:, kubeadm:) that an operator can't change without breaking their cluster. Re-run with --exclusions-preset=none to see everything.

Where to go next

• Full rule catalog (implemented + planned): docs/findings.md
• Architecture deep-dive (per-stage walkthrough, scoring, data model): docs/architecture.md
• Exclusions YAML schema (presets, sections, glob semantics): docs/exclusions.md
• Roadmap & status: PLAN.md
• Releases & changelog: CHANGELOG.md / GitHub Releases
• Contributing: CONTRIBUTING.md
• Security disclosure: SECURITY.md (GitHub Private Vulnerability Reporting only)
• License: Apache-2.0
• End-to-end verification: make e2e provisions a local kind cluster with intentionally risky manifests in testdata/ and asserts expected findings

Use the GitHub Action

The repository ships a composite Action at action.yml, so you can wire kubesplaining into a workflow without authoring the docker run invocation yourself. The action pulls the GHCR image (the latest tag unless you set version), executes a scan against either a live cluster (via a base64-encoded kubeconfig) or a pre-collected snapshot JSON, and optionally uploads the SARIF result to GitHub code scanning.

# .github/workflows/kubesplaining.yml
name: Kubesplaining
on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read
  security-events: write   # required by upload-sarif

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      # Option A: scan a pre-collected snapshot checked into the repo.
      - name: Scan offline snapshot
        uses: 0hardik1/kubesplaining@main
        with:
          input-file: testdata/snapshots/minimal-risky.json
          severity-threshold: medium
          fail-on-critical: 'true'
          upload-sarif: 'true'

      # Option B: scan a live cluster. Store the kubeconfig as a base64
      # secret (e.g. `cat ~/.kube/config | base64 | pbcopy`) under the
      # `KUBE_CONFIG_B64` repository secret first.
      # - name: Scan live cluster
      #   uses: 0hardik1/kubesplaining@main
      #   with:
      #     kubeconfig: ${{ secrets.KUBE_CONFIG_B64 }}
      #     severity-threshold: high
      #     compliance: cis

Inputs (all optional unless noted):

The ref after @ selects the action definition, and version selects the container image that it runs. The action definitions in releases v1.1.0 to v1.3.0 default version to main, an image tag that was never published. If you pin the action to one of those releases, set version too, for example uses: 0hardik1/[email protected] with version: 1.3.0.

Outputs: report-dir (absolute path to the report directory) and sarif-file (absolute path to findings.sarif, when emitted). The .github/workflows/action-smoke.yml workflow in this repo exercises the action against testdata/snapshots/minimal-risky.json on every PR that touches it.

Credits

• Kinnaird McQuade, for the tool idea. His Cloudsplaining inspired this project.
• Ramesh Ramani (@secmesh): the least-privilege mode was inspired by his idea.