✅ NIST 800-218 Control Coverage

KlusterShield maps every check to a specific SSDF practice:

🚀 Quickstart

Prerequisites

• Proxmox 7+ (or any VM host) or existing k3s/Kubernetes cluster
• Python 3.11+
• kubectl configured with cluster access
• Helm 3+

1. Clone and install

git clone https://github.com/rudymartinezai/klustershield.git
cd KlusterShield
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Note: If you hit a setuptools.backends.legacy error during install, bypass it with the PYTHONPATH wrapper below instead of pip install -e .

2. Set up the CLI wrapper (recommended)

Instead of pip install -e ., use a wrapper script that works reliably across environments:

sudo tee /usr/local/bin/klustershield > /dev/null <<'EOF'
#!/bin/bash
PYTHONPATH=/opt/klustershield /opt/klustershield/.venv/bin/python \
  -c "from klustershield.cli import main; main()" -- "$@"
EOF
sudo chmod +x /usr/local/bin/klustershield

Adjust /opt/klustershield to wherever you cloned the repo.

3. Point at your cluster

export KUBECONFIG=~/.kube/config
# Verify access
kubectl get nodes

4. Run a baseline compliance scan

Important: Run from the directory where you want the report saved. The output path must be within your current working directory.

cd ~
klustershield scan --output baseline-report.html

5. Provision a hardened namespace

klustershield provision \
  --namespace production \
  --profile nist-800-218 \
  --team platform

6. Scan the hardened namespace

klustershield scan --namespace production --output production-report.html

7. Open the compliance reports

open baseline-report.html
open production-report.html

🏗️ Full Proxmox Deployment (Ops CT + Terraform + Ansible)

For a fully automated on-premises deployment with a dedicated ops workstation:

What gets built:

• 1x Proxmox LXC Container (CT) — ops workstation running Terraform + Ansible + KlusterShield
• 3x Ubuntu 22.04 VMs — 1 k3s control plane + 2 workers
• All provisioned and configured without touching your laptop

See docs/proxmox-setup.md for the full walkthrough.

Stack:

• Terraform (bpg/proxmox provider v0.50+) — VM provisioning
• Ansible (community.general) — k3s install + kubeconfig fetch
• k3s v1.28.4+k3s2 — lightweight Kubernetes
• KlusterShield — compliance automation

📁 Project Structure

KlusterShield/
├── klustershield/
│   ├── provisioner/        # Namespace, RBAC, NetworkPolicy automation
│   ├── scanner/            # NIST control checks and scoring
│   ├── enforcer/           # OPA/Gatekeeper policy management
│   └── auditor/            # Audit log collection and report generation
├── manifests/
│   ├── namespaces/         # Hardened namespace templates
│   ├── rbac/               # Least-privilege RBAC templates
│   ├── network-policies/   # Zero-trust network policy templates
│   └── gatekeeper/         # OPA constraint templates
├── scripts/
│   ├── provision_cluster.py  # Proxmox VM + k3s bootstrap
│   └── teardown.py           # Clean cluster removal
├── docs/
│   ├── architecture.md
│   ├── nist-control-mapping.md
│   └── proxmox-setup.md
├── tests/
├── examples/
│   └── demo-workload/      # Sample hardened app deployment
├── requirements.txt
├── pyproject.toml
└── CHANGELOG.md

🔧 Core Modules

klustershield provision

Creates a new namespace with all security controls pre-applied:

• RBAC with least-privilege roles
• NetworkPolicy enforcing zero-trust pod communication
• ResourceQuota and LimitRange
• PodSecurityAdmission labels (restricted profile)
• Audit annotation labels for traceability

klustershield scan

Runs the full NIST 800-218 control suite against a target namespace or entire cluster:

• Checks 13 control families
• Scores each control as PASS / FAIL / WARN
• Generates weighted compliance percentage
• Outputs HTML report or JSON for pipeline integration

klustershield enforce

Installs and manages OPA Gatekeeper constraint templates:

• Blocks privileged containers
• Requires resource limits on all pods
• Enforces approved image registries
• Requires security context on all workloads

klustershield audit

Ships Kubernetes audit logs to a configurable backend:

• Splunk HEC
• Loki / Grafana
• Local JSON file

📊 Real-World Scan Results

These results were captured from a live Proxmox deployment: a 3-node k3s cluster (1 control plane + 2 workers) provisioned via Terraform and Ansible, scanned with KlusterShield from a dedicated Linux CT ops workstation.

Baseline — Fresh cluster, no hardening

klustershield scan --output baseline-report.html

Compliance Score: 76.7%
  Passed: 8  Failed: 1  Warned: 1  Skipped: 2  Errors: 0

k3s starts reasonably secure out of the box — 76.7% before any hardening. The only hard failure is the default namespace missing Pod Security Admission labels.

Post-Hardening — After klustershield provision

klustershield provision --namespace production --profile nist-800-218 --team platform
klustershield scan --namespace production --output production-report.html

Compliance Score: 100.0%
  Passed: 12  Failed: 0  Warned: 0  Skipped: 0  Errors: 0

Provisioning applies PSA labels, zero-trust NetworkPolicies, least-privilege RBAC, ResourceQuota, and LimitRange — all 12 controls satisfied.

🖥️ Built and Tested On

⚠️ Known Compatibility Notes

🗺️ Roadmap

• Core provisioner and RBAC templates
• NIST 800-218 scanner with HTML report
• OPA/Gatekeeper enforcement module
• Audit log shipper (Splunk + Loki)
• SBOM generation (CycloneDX)
• Automated remediation suggestions
• GitHub Actions / GitLab CI integration
• Web dashboard (FastAPI + HTMX)
• CMMC Level 2 control overlay

🤝 Contributing

Contributions welcome. Please read CONTRIBUTING.md and open an issue before submitting a PR.

📄 License

Licensed under the Apache License 2.0 — see LICENSE for details.

Apache 2.0 was chosen deliberately: it includes an explicit patent grant, making KlusterShield safe for use in defense contractor and government-adjacent environments where MIT's patent silence creates legal uncertainty.

👤 Author

**Rudy