Eight Guardrails Framework

# Eight Guardrails Framework

## Overview

The Eight Guardrails Framework governs how the KubeAuto Day IDP was built and
how the platform itself enforces safety. Each guardrail is implemented across
three defensive layers, with problems caught at the cheapest possible point.

```
Cost to fix:  $        $$              $$$
              |         |                |
              v         v                v
         Git Hooks → Claude Code → Kubernetes
         (local)     (pre-exec)    (cluster)

Determinism:  100%      ~80%            100%
Latency:      <1s       1-30s           1-5s
Bypass risk:  None      Low*            None

* Prompt-based hooks are probabilistic. Bash-based hooks are deterministic.
```

---

## The Eight Guardrails

### 1. Propose-Approve-Execute

Every change follows a structured workflow: propose (Git commit), approve
(test gate), execute (ArgoCD sync).

| Layer | Implementation |
|-------|---------------|
| **Layer 1: Git** | Pre-push hook blocks push if phase tests fail |
| **Layer 2: Claude Code** | PreToolUse blocks `kubectl apply` in production namespaces after Phase 2 |
| **Layer 3: Kubernetes** | ArgoCD GitOps-only delivery. Backstage templates enforce structured service creation |

### 2. Blast Radius Limits

Contain the impact of any single change to the smallest possible scope.

| Layer | Implementation |
|-------|---------------|
| **Layer 1: Git** | Namespace scope check validates manifests target only phase-appropriate namespaces |
| **Layer 2: Claude Code** | PreToolUse blocks `kubectl delete namespace`, `terraform destroy`, operations on `kube-system` |
| **Layer 3: Kubernetes** | Namespace-scoped RBAC, ResourceQuotas (10 pods, 4 CPU, 8Gi in apps), NetworkPolicies (default-deny), VPC isolation |

### 3. Stop Hooks & Circuit Breakers

Automated mechanisms that halt progress when something is wrong.

| Layer | Implementation |
|-------|---------------|
| **Layer 1: Git** | Kubeconform schema validation, Kyverno CLI dry-run (pre-commit), full test suite (pre-push) |
| **Layer 2: Claude Code** | Ralph Wiggum Stop hook blocks exit without phase completion promise. Prompt-based evaluator verifies test criteria actually pass |
| **Layer 3: Kubernetes** | Kyverno admission webhooks reject non-compliant pods. Falco runtime rules detect anomalous behavior |

### 4. Assume Misunderstanding

Validate everything. Never trust that output is correct without verification.

| Layer | Implementation |
|-------|---------------|
| **Layer 1: Git** | yamllint, kubeconform, `terraform validate`, `helm lint` (pre-commit) |
| **Layer 2: Claude Code** | PostToolUse reminds to verify after `kubectl apply` and `terraform apply` |
| **Layer 3: Kubernetes** | Schema validation at admission. Kyverno validate rules enforce structural requirements |

### 5. Immutable Audit Trail

Every action is recorded. Nothing can be silently changed.

| Layer | Implementation |
|-------|---------------|
| **Layer 1: Git** | Conventional commit format with phase/component tags. Prompt logs in `prompts/`. Git history as timeline |
| **Layer 2: Claude Code** | PostToolUse reminders for scorecard updates after deployments. Session logging |
| **Layer 3: Kubernetes** | Prometheus metrics, Grafana dashboards, OTel distributed traces, Falco syscall logging, K8s audit logs |

### 6. Automated Rollback

When something fails, provide a fast path back to the last known-good state.

| Layer | Implementation |
|-------|---------------|
| **Layer 1: Git** | `git revert` is the cheapest rollback. Tagged commits at phase completion |
| **Layer 2: Claude Code** | PostToolUse suggests rollback options after failed terraform/helm/kubectl commands |
| **Layer 3: Kubernetes** | ArgoCD self-heal reverts drift. `argocd app rollback` for instant revision rollback. PDBs protect availability during changes |

### 7. Secrets & Credential Isolation

No secrets in code. No long-lived credentials. No accidental exposure.

| Layer | Implementation |
|-------|---------------|
| **Layer 1: Git** | gitleaks scans every commit. `.gitignore` excludes `*.pem`, `*.key`, `terraform.tfstate`. `.gitleaks.toml` allowlist for known test secrets |
| **Layer 2: Claude Code** | PreToolUse blocks `kubectl get secret -o yaml/json` and `cat` of secret files |
| **Layer 3: Kubernetes** | External Secrets Operator pulls from AWS Secrets Manager. Pod Identity (no static IAM keys). KMS encryption at rest |

### 8. Supply Chain Validation

Trust but verify. Only allow known-good artifacts.

| Layer | Implementation |
|-------|---------------|
| **Layer 1: Git** | Trivy Dockerfile scanning. Image registry allowlist check (pre-commit) |
| **Layer 2: Claude Code** | (Potential: block Helm installs from unapproved repos) |
| **Layer 3: Kubernetes** | Kyverno `restrict-image-registries` policy enforces ECR + GHCR + docker.io/library + registry.k8s.io |

---

## Coverage Summary

| Phase | Guardrails Active at Layer 3 |
|-------|------------------------------|
| After Phase 1 (Foundation) | #2 (VPC/SG), #7 (Pod Identity) |
| After Phase 2 (GitOps) | + #1 (ArgoCD), #6 (self-heal) |
| After Phase 3 (Security) | + #3 (Kyverno/Falco), #4 (admission), #7 (ESO), #8 (image policy) |
| After Phase 4 (Observability) | + #5 (Prometheus/OTel/Grafana) |
| After Phase 7 (Hardening) | All 8 guardrails at all 3 layers |

---

## Files

| Layer | Files |
|-------|-------|
| **Layer 1** | `.pre-commit-config.yaml`, `.yamllint.yml`, `.gitleaks.toml`, `.current-phase`, `.claude/hooks/check-image-allowlist.sh`, `.claude/hooks/check-namespace-scope.sh`, `.claude/hooks/commit-msg-validate.sh`, `.claude/hooks/pre-push-tests.sh` |
| **Layer 2** | `.claude/settings.json`, `.claude/hooks/cc-pretool-guard.sh`, `.claude/hooks/cc-posttool-audit.sh`, `.claude/hooks/cc-stop-deterministic.sh` |
| **Layer 3** | `policies/kyverno/`, `security/falco/`, `security/rbac/`, `security/network-policies/`, `security/eso/`, `security/quotas-pdbs/`, `gitops/`, `monitoring/`, `backstage/` |

---

## Cross-References

- Three-Layer architecture detail: `docs/WALKTHROUGH.md`
- Security posture: `docs/SECURITY.md`
- Reconciliation status: `docs/EIGHT-GUARDRAILS-RECONCILIATION.md`
- Scorecard: `spec/SCORECARD.md`
- Skill file guardrail mappings: `.claude/skills/*.md` (each has a "Guardrail Integration" section)