Skip to content

About

Offline Kubernetes security posture scanner for YAML manifests: 26 CIS-aligned checks, table/JSON/SARIF output, CI-friendly exit codes

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

KubePosture

CI License: MIT Go version Release

KubePosture is an offline Kubernetes security posture scanner. It reads Kubernetes YAML manifests, the same files you keep in Git and apply with kubectl or a GitOps controller, and audits them against 26 checks aligned with the CIS Kubernetes Benchmark: privileged containers, host namespace sharing, wildcard RBAC, cluster-admin bindings, secrets in environment variables, missing NetworkPolicies, and more.

It never talks to a cluster and never phones home. Scanned files stay on your machine, which makes it safe to run in CI on private manifests.

Install

With Go 1.24 or newer:

go install github.com/RahilSahu/kubeposture/cmd/kubeposture@v1.0.0

Or build from source:

git clone https://github.com/RahilSahu/kubeposture.git
cd kubeposture
go build -o kubeposture ./cmd/kubeposture

Usage

Scan one file, several files, or whole directory trees (searched recursively for .yaml and .yml files):

kubeposture deploy.yaml
kubeposture manifests/ overlays/prod/
kubeposture --format json manifests/ > report.json
kubeposture --format sarif manifests/ > kubeposture.sarif
kubeposture --fail-on medium manifests/

Example output for the intentionally insecure manifests in examples/bad.yaml:

KubePosture 1.0.0
Scanned 1 file(s), 3 object(s)

[CRITICAL] KP001 Privileged container
  Deployment/bad-web, container app, namespace default (examples/bad.yaml)
  container "app" runs privileged, with full access to the host
  CIS 5.2.1 | Fix: Set securityContext.privileged: false, or remove the setting.

[CRITICAL] KP025 cluster-admin role bound
  ClusterRoleBinding/wildcard-admin-binding (examples/bad.yaml)
  binding grants the cluster-admin ClusterRole cluster-wide, which is full administrative access
  CIS 5.1.3 | Fix: Bind a least-privilege role instead of cluster-admin; reserve cluster-admin for break-glass administration.

...

Summary: 2 critical, 9 high, 9 medium, 6 low, 26 findings total

The hardened set in examples/good.yaml passes all 26 checks.

Supported kinds

Pod, Deployment, StatefulSet, DaemonSet, Job and CronJob are decoded into a uniform workload view (pod spec plus containers and init containers). Role, ClusterRole, RoleBinding and ClusterRoleBinding feed the RBAC checks. NetworkPolicy, ServiceAccount, Service and Ingress are recognised and counted. List documents (the shape kubectl get -o yaml produces, including PodList and other *List kinds) are expanded so every item is scanned as its own object. Unknown kinds are skipped safely, malformed documents are reported as warnings on stderr, and a scan never stops at the first bad file.

Rules

CIS references are to the CIS Kubernetes Benchmark (v1.8 section numbering) and are listed only where a control genuinely maps to the check.

ID Severity Check CIS
KP001 critical Container runs privileged 5.2.1
KP002 high allowPrivilegeEscalation is unset or true 5.2.5
KP003 high runAsNonRoot is not true at pod or container level 5.2.6
KP004 high runAsUser is explicitly 0 (root) 5.2.6
KP005 medium readOnlyRootFilesystem is not true
KP006 high Pod shares the host network namespace 5.2.4
KP007 high Pod shares the host PID namespace 5.2.2
KP008 high Pod shares the host IPC namespace 5.2.3
KP009 high A volume uses hostPath 5.2.10
KP010 high Container adds ALL, SYS_ADMIN or NET_ADMIN capabilities 5.2.8
KP011 medium Capabilities drop does not include ALL 5.2.9
KP012 medium Container adds the NET_RAW capability 5.2.7
KP013 medium Container is missing CPU or memory limits
KP014 low Container is missing CPU or memory requests
KP015 medium Image has no tag or uses the :latest tag (and no digest)
KP016 low Image is not pinned by digest
KP017 low Container has no liveness probe
KP018 low Container has no readiness probe
KP019 medium No seccomp profile, or it is Unconfined, at pod or container level 5.7.2
KP020 medium automountServiceAccountToken is unset or true in the pod spec
KP021 low Workload runs in the default namespace 5.7.4
KP022 low Workload sets no serviceAccountName and uses the default service account 5.1.5
KP023 high A secret-looking environment variable (password, token, key) holds a literal value 5.4.1
KP024 high Role or ClusterRole grants wildcard verbs or wildcard resources 5.1.3
KP025 critical A binding grants the cluster-admin ClusterRole 5.1.3
KP026 medium The workload's namespace has no NetworkPolicy in the scanned files 5.3.2

Notes on interpretation:

  • KP026 is evaluated against the set of files you scan: it means "no NetworkPolicy for this namespace was in the scanned manifests". Scan the full manifest set for a namespace to use it as a coverage check.
  • KP023 only fires on literal values. A variable sourced with valueFrom.secretKeyRef is the recommended pattern and is not a finding.
  • Effective settings follow Kubernetes semantics: a container-level securityContext value overrides the pod-level one (KP003, KP004, KP019).

Output formats

  • table (default): grouped, human-readable findings with the fix for each one, plus a severity summary.
  • json: a versioned report with a summary (files, objects, findings, bySeverity) and the full finding list, suitable for scripting.
  • sarif: SARIF 2.1.0 with all 26 rules described in the tool driver, ready to upload to GitHub code scanning or other SARIF consumers.

Exit codes

Code Meaning
0 The scan ran and no finding reached the --fail-on severity
1 At least one finding is at or above the --fail-on severity (default: high)
2 The scan could not run: bad flags, unreadable input, or no Kubernetes documents found

This makes CI gating one line:

kubeposture --fail-on high manifests/

Roadmap

Not in v1, and not claimed anywhere above:

  • Live cluster mode (reading objects from the API server instead of files).
  • File and line locations in SARIF results.
  • Per-rule configuration: disabling rules and overriding severities.

Contributing

See CONTRIBUTING.md. The short version: every rule ships with positive and negative tests, and gofmt, go vet and go test ./... must be clean.

Responsible use

KubePosture audits manifests; run it on manifests you own or are authorised to assess. Findings are posture signals to review, not proof of exploitability.

License

MIT. See LICENSE.

About

Offline Kubernetes security posture scanner for YAML manifests: 26 CIS-aligned checks, table/JSON/SARIF output, CI-friendly exit codes

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages