kubesplaining

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 four cluster-takeover sinks (cluster-admin, system:masters, node-escape, 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.

• 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.

Krew (Kubernetes plugin manager, submission pending):

kubectl krew install splain

Homebrew (tap submission pending):

brew install 0hardik1/tap/kubesplaining

See Installation below for 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 four sinks (cluster-admin, system:masters, node-escape, kube-system-secrets).
• 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

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-README install snippets cover the from-clone path, Krew, and Homebrew; this section adds Go install, pre-built binaries, and Docker.

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 -v "$HOME/.kube:/root/.kube" ghcr.io/0hardik1/kubesplaining:latest scan

Krew (Kubernetes plugin manager)

Submission to the krew-index is pending; once accepted:

kubectl krew install splain
kubectl splain scan

Homebrew

The Homebrew tap is pending; once published:

brew install 0hardik1/tap/kubesplaining

What it checks

45 stable rule IDs across 8 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 │    │  7 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 actually looks like. Each rule produces a Finding with stable RuleID, severity, evidence, and remediation; the privesc rules additionally carry an EscalationPath array.

{
  "id": "KUBE-PRIVESC-PATH-CLUSTER-ADMIN:foo:builder-bot",
  "rule_id": "KUBE-PRIVESC-PATH-CLUSTER-ADMIN",
  "severity": "CRITICAL",
  "score": 9.3,
  "category": "privilege_escalation",
  "subject": { "kind": "ServiceAccount", "namespace": "foo", "name": "builder-bot" },
  "title": "ServiceAccount foo/builder-bot can reach cluster-admin equivalent in 2 hop(s)",
  "escalation_path": [
    {
      "from_subject": "ServiceAccount/foo/builder-bot",
      "to_subject":   "ServiceAccount/kube-system/replicaset-controller",
      "action":       "pod_create",
      "permission":   "create on pods",
      "gains":        "run a pod that mounts the kube-system replicaset-controller token"
    },
    {
      "from_subject": "ServiceAccount/kube-system/replicaset-controller",
      "to_subject":   "ClusterRole/cluster-admin",
      "action":       "wildcard_holder",
      "permission":   "*/*/*",
      "gains":        "this SA already holds cluster-admin equivalence"
    }
  ],
  "remediation": "Drop `create pods` from foo/builder-bot's role, OR move that workload off kube-system."
}

{
  "id": "KUBE-ESCAPE-001:default:debug-shell",
  "rule_id": "KUBE-ESCAPE-001",
  "severity": "CRITICAL",
  "score": 9.5,
  "category": "privilege_escalation",
  "resource": { "kind": "Pod", "namespace": "default", "name": "debug-shell" },
  "title": "Privileged container in default/debug-shell",
  "evidence": {
    "container": "debug",
    "securityContext": { "privileged": true },
    "volumeMounts": [{ "name": "host-root", "mountPath": "/host", "hostPath": "/" }]
  },
  "remediation": "Drop `privileged: true`; replace hostPath `/` with the specific files via ConfigMap / Secret / CSI."
}

{
  "id": "KUBE-RBAC-OVERBROAD-001::ops-team-admin",
  "rule_id": "KUBE-RBAC-OVERBROAD-001",
  "severity": "CRITICAL",
  "score": 9.0,
  "category": "privilege_escalation",
  "subject": { "kind": "Group", "name": "ops-team" },
  "title": "Group ops-team is bound to cluster-admin",
  "evidence": {
    "clusterRoleBinding": "ops-team-admin",
    "roleRef": "cluster-admin"
  },
  "remediation": "Replace cluster-admin with a least-privilege role scoped to what ops-team actually needs."
}

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

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.

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 resources: Roles/ClusterRoles/Bindings that look like delete candidates. Each row names the binding to remove (e.g. Delete ClusterRoleBinding/dashboard-admin (scope down to a narrower ClusterRole)).
• Role to verb activity: 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. Until the dedicated GitHub Action ships (post-release fast-follow), the docker run form works directly:

# .github/workflows/kubesplaining.yml
name: Kubesplaining
on: [push, pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
    steps:
      - uses: actions/checkout@v6
      - name: Scan manifests
        run: |
          docker run --rm \
            -v "${{ github.workspace }}:/work" -w /work \
            ghcr.io/0hardik1/kubesplaining:latest \
            scan-resource --input-file manifests/ --output-format sarif \
            --output-dir /work/kubesplaining-report
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: kubesplaining-report/results.sarif

Or 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 non-zero when the count of critical / high findings crosses the configured thresholds; combine with --severity-threshold to scope what counts.

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 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.

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). Severity is attenuated by chain length (hops ≥ 3 drop one bucket); use --max-privesc-depth to limit BFS aggressiveness.

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 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 pinned GHCR image, 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:
          # Pin to a released tag (e.g. v1) once v1.0.0 ships. `main` tracks
          # the development image and is fine for early adopters.
          version: main
          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):

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.