Know your clusters before attackers do.
KubeVigil is a Kubernetes Security Posture Management (KSPM) CLI tool that scans clusters and YAML manifests for security misconfigurations. It runs 150 security checks across 12 categories, maps every finding to industry compliance frameworks (CIS Kubernetes Benchmark, MITRE ATT&CK, NSA/CISA), and outputs reports in 8 formats — from colored terminal text to SARIF for GitHub Security.
- Single binary, zero dependencies. No agents, no sidecars, no cluster components to install.
- 150 checks, 12 categories. Workload security, RBAC, network policies, secrets, Pod Security Standards, scheduling, storage, cluster config, supply chain, cloud provider, and CRD security — including Gateway API, admission webhook, and RBAC escalation-vector coverage added in v1.3.0.
- Dual-mode scanning. Scan live clusters or static YAML manifests.
- Compliance mapping. CIS v1.8, MITRE ATT&CK v14, NSA/CISA v1.2.
- 8 output formats. Text, JSON, Markdown, HTML, SARIF, YAML, JUnit, CSV.
- Auto-remediation.
kubevigil fixpatches manifests with comment-preserving YAML edits and a five-ring safety model. - CI-ready exit codes. Clean integration with any CI/CD pipeline.
- AI assistant integration. Built-in MCP server lets Claude, Cursor, and VS Code Copilot scan clusters, query findings, and get remediation guidance through natural conversation.
brew install stribog-cloud/tap/kubevigilkubectl krew install vigilcurl -sSL https://raw.githubusercontent.com/stribog-cloud/KubeVigil/main/install.sh | bashPre-built binaries for Linux, macOS, and Windows are available on the Releases page.
docker run --rm -v $(pwd):/manifests ghcr.io/stribog-cloud/kubevigil scan -f /manifests/
# Scan a live cluster
docker run --rm -v ~/.kube/config:/root/.kube/config ghcr.io/stribog-cloud/kubevigil scango install github.com/stribog-cloud/kubevigil/cmd/kubevigil@latestKubeVigil includes a built-in MCP server that lets AI assistants like Claude,
Cursor, and VS Code Copilot scan clusters, query findings, and get remediation
guidance through natural conversation. Add this to your Claude Desktop
configuration (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"kubevigil": {
"command": "kubevigil",
"args": ["mcp-server"]
}
}
}See the MCP Setup Guide for Cursor, VS Code, advanced configuration, and example conversations.
# Scan manifests (no cluster needed)
kubevigil scan -f ./manifests/
# Scan a live cluster
kubevigil scan
# Filter by severity
kubevigil scan --severity high
# Output as HTML report
kubevigil scan -f ./manifests/ -o report.html
# Preview auto-fixes (dry-run)
kubevigil fix ./manifests/
# Apply safe fixes
kubevigil fix ./manifests/ --applySee the Quick Start guide for more examples.
Full documentation lives in docs/:
| Section | Description |
|---|---|
| Getting Started | Installation, quickstart, core concepts |
| Security Checks | All 150 checks across 12 categories |
| Scanning | Live cluster and manifest scanning |
| Output Formats | Text, JSON, HTML, SARIF, and 4 more |
| Auto-Remediation | Fix engine, safety model, risk levels |
| Custom Policies | User-defined CEL checks |
| Baseline & Drift | Accept findings, gate on new only |
| Admission Webhook | Real-time deny/warn at admission |
| Compliance | CIS, MITRE ATT&CK, NSA/CISA mappings |
| Configuration | .kubevigil.yaml, exemptions, tuning |
| CLI Reference | All commands and flags |
| AI Assistants (MCP) | Claude, Cursor, VS Code integration |
| Integrations | SARIF, JUnit, IDE workflows |
| Architecture | Internal design for contributors |
| Contributing | How to add checks and fix strategies |
| Troubleshooting | Common issues and solutions |
| Changelog | What shipped in each version |
| Category | Checks | Examples |
|---|---|---|
| Workload | 30 | privileged, host-pid, run-as-root, windows-hostprocess, host-users-not-isolated |
| Image | 9 | image-tag-latest, image-registry-blocklist |
| RBAC | 22 | rbac-wildcard-verbs, rbac-cluster-admin, rbac-node-proxy-access, rbac-csr-approval |
| Secrets | 12 | secrets-in-env, secrets-unencrypted, secrets-envfrom-bulk, secrets-tls-weak-key |
| Network | 18 | network-policy-missing, ingress-no-tls, gateway-listener-no-tls, httproute-wildcard-hostname |
| PSA | 6 | psa-labels-missing, psa-baseline-violations |
| Scheduling | 11 | toleration-control-plane, pod-disruption-budget, job-active-deadline-missing |
| Storage | 9 | pvc-no-encryption, emptydir-size-limit, csi-inline-ephemeral-volume |
| Cluster | 15 | etcd-encryption, api-server-anonymous, validatingwebhook-failure-policy-ignore |
| Supply Chain | 7 | container-runtime-socket, liveness-readiness-probes, poststart-hook-network-call |
| Cloud | 4 | eks-imds-access, gke-metadata-concealment |
| CRD | 7 | crd-validation-missing, cert-manager-expiry, crd-preserve-unknown-fields |
See Checks Overview for the full list with severities, modes, and auto-fix status.
20 checks support automatic fixing with a five-ring safety model:
kubevigil fix ./manifests/ # Dry-run (preview)
kubevigil fix ./manifests/ --apply # Safe fixes only
kubevigil fix ./manifests/ --apply --risk-level moderate # + Likely Safe
kubevigil fix ./manifests/ --apply --verify # Fix + re-scan
kubevigil fix ./manifests/ --kustomize ./overlay/ # Kustomize output
kubevigil fix ./manifests/ -o kubectl # kubectl commandsSee Auto-Fix Overview and Safety Model for details.
Write your own checks as CEL expressions — no fork required. They run through the same pipeline as built-in checks (severity, exemptions, frameworks, every output format):
# policies.yaml
version: v1
policies:
- id: require-team-label
name: Workloads must carry a team label
severity: medium
expression: '!has(object.metadata.labels) || !("team" in object.metadata.labels)'
match: { kinds: [Deployment, StatefulSet] }kubevigil policy validate policies.yaml # compile-check
kubevigil scan -f ./manifests/ --policy-file policies.yamlSee Custom Policies.
Accept today's findings as a baseline, then fail CI only on new ones:
kubevigil scan -f ./manifests/ --save-baseline baseline.json # accept current state
kubevigil scan -f ./manifests/ --baseline baseline.json --fail-on-new # gate on new onlySee Baseline & Drift.
Gate deployments in real time instead of auditing after the fact. kubevigil webhook serves a Kubernetes ValidatingAdmissionWebhook that runs the same
checks and custom policies against each admitted object — denying findings at or
above --fail-on (with a detailed reason) and warning below. It fails open
so a webhook fault can never block your cluster.
kubevigil webhook --tls-cert tls.crt --tls-key tls.key --fail-on highDeploy manifests are in deploy/webhook/; see the
Admission Webhook guide.
Posture is only half the picture — an image can be perfectly configured and still
ship known-vulnerable software. kubevigil vuln scans a container image's SBOM
(SPDX or CycloneDX) against OSV.dev and reports known CVEs as
findings, fused into the same model and report formats as a posture scan.
syft myapp:1.4.0 -o spdx-json > app.spdx.json
kubevigil vuln --sbom app.spdx.json --image myapp:1.4.0 --fail-on highSeverity comes from each advisory's CVSS score; findings carry the CVE id,
affected package, and the fixed version to upgrade to. Needs network access to
api.osv.dev. See the Vulnerability Scanning guide.
| Format | Flag | Use Case |
|---|---|---|
| Text | -o text |
Terminal output (default) |
| JSON | -o json |
CI pipelines, jq processing |
| HTML | -o html |
Interactive dashboard report |
| SARIF | -o sarif |
GitHub Security, VS Code |
| Markdown | -o markdown |
PR comments |
| YAML | -o yaml |
Kubernetes tooling |
| JUnit | -o junit |
CI test reporting |
| CSV | -o csv |
Spreadsheet analysis |
Write to file: kubevigil scan -o report.html (format inferred from extension).
| Code | Scan | Fix |
|---|---|---|
| 0 | Clean | Fixes applied |
| 1 | Findings above threshold | Remaining findings after verify |
| 2 | Scan error | Total failure |
| 3 | Config error | Config error |
| 4 | — | Nothing to fix |
| 5 | — | Partial success |
See Exit Codes for CI/CD usage examples.
Run KubeVigil manifest scans in CI without a manual install step:
- uses: stribog-cloud/KubeVigil@main # pin to a release tag once available
with:
files: ./k8s/
fail-on: criticalDownloads and checksum-verifies the release binary, scans, and writes a SARIF report by default. See GitHub Action for inputs, outputs, and a Code Scanning upload example.
- Phase 1 — Core engine, 25 workload checks, text/JSON output, CLI
- Phase 2 — 85 additional checks (110 total), 6 new formats, compliance mapping
- Phase 3 — Auto-remediation, 20 fixable checks, YAML round-trip, safety model
- Phase 4a — Distribution (GoReleaser, GitHub Releases, Homebrew, Krew, Docker, install script)
- Phase 4b — MCP Server (AI assistant integration — scan, query, remediate via Claude/Cursor/Copilot)
- Phase 5 — v1.0.0 hardening & release engineering (Windows fix, SBOM/signing/provenance, e2e in CI; severity calibration ongoing)
- Phase 6 — CI/CD integration (GitHub Action; baseline + drift management in v1.1.0; PR decoration pending)
- Phase 7 — Runtime (validating admission webhook in v1.2.0; operator mode, Prometheus metrics pending)
- Detection breadth — 40 new checks (110 → 150) in v1.3.0; image CVE scanning via OSV.dev in v1.4.0
- Phase 8 — Enterprise (multi-cluster, trend analysis, custom CEL policies shipped in v1.1.0)
- Phase 9 — Ecosystem (SDK, plugin system, Helm chart)
make build # Build binary to ./bin/kubevigil
make test # Run all tests with race detection
make lint # Run golangci-lint
make check # All quality gates (vet + lint + test)See Contributing Guide for development setup and how to add new checks.
Apache 2.0 — See LICENSE for details.