SCC Orchestration System

⚠️ Disclaimer: This project is in its early, experimental stage and may change frequently as it progresses toward maturity.

Automated, zero-impact Security Context Constraint (SCC) migration for OpenShift/Kubernetes clusters.

The SCC Orchestration System provides a stateful, phased migration engine that transitions workloads between SCC policies safely — with traffic mirroring, incremental rollout, automatic rollback, and full governance controls. No manual coordination required.

---

What is an SCC?

A Security Context Constraint (SCC) is an OpenShift resource that controls what a pod can do at the OS level — root access, host networking, Linux capabilities, volume mounts, and more. OpenShift ranks built-in SCCs from most restrictive to most permissive:

restricted → nonroot → hostmount-anyuid → anyuid → hostaccess → hostnetwork → privileged

Migrating workloads between SCCs today is manual, risky, and all-or-nothing. This project automates the entire process with safety guardrails at every step.

---

Key Features

• Phased State Machine — Pending → Validating → Mirroring → TrafficShifting → Migrating → Completed, with automatic rollback on failure
• ML-Based Risk Engine — Scores every migration plan before execution using weighted signals (privilege gap, blast radius, namespace criticality, etc.)
• Per-Pod Admission Webhook — Dynamically mutates SCC annotations and reconciles pod security contexts at admission time
• Isolated Governance Plane — Policy evaluation, RBAC, audit logging, and SCC version tracking in a dedicated API
• Istio Traffic Management — Shadow traffic mirroring and incremental weight shifting (10→25→50→75→100%) with readiness gating
• SCC Version Registry — Full lifecycle tracking of every SCC version activation and deactivation

---

Architecture

flowchart TB
    subgraph GP["Isolated Governance Plane"]
        GAPI["Governance API<br/>#40;Node.js / Express#41;<br/>Policy Rules · RBAC · Audit Log<br/>SCC Version Registry · Per-Pod Tracking"]
    end

    subgraph KC["Kubernetes / OpenShift Cluster"]
        CTRL["SCC Migration Controller<br/>#40;Go / controller-runtime#41;<br/>Phase State Machine · Risk Engine<br/>Traffic Shifting · Readiness Gates"]
        WH["Admission Webhook<br/>#40;Go / HTTPS#41;<br/>Pod Interception · SCC Mutation<br/>Context Extraction · Security Reconciliation"]
        CRD["SCCMigrationPlan CRD<br/>#40;scc.poc/v1#41;"]
        ISTIO["Istio<br/>VirtualService · DestinationRule<br/>Mirror + Weight Shifting"]
    end

    CTRL -->|"Plan Validation"| GAPI
    WH -->|"Admission Check"| GAPI
    CTRL --> CRD
    CTRL --> ISTIO

    classDef gov fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1b5e20
    classDef k8s fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#0d47a1
    classDef ctrl fill:#bbdefb,stroke:#1976d2,stroke-width:1px,color:#0d47a1
    classDef wh fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px,color:#4a148c
    classDef crd fill:#ffcdd2,stroke:#c62828,stroke-width:1px,color:#b71c1c
    classDef istio fill:#d1c4e9,stroke:#512da8,stroke-width:1px,color:#311b92

    class GP gov
    class GAPI gov
    class KC k8s
    class CTRL ctrl
    class WH wh
    class CRD crd
    class ISTIO istio

Loading

---

Components

Component	Language	Description
SCC Migration Controller	Go	Kubernetes operator that drives SCCMigrationPlan CRDs through a phased state machine with risk assessment, traffic shifting, and readiness gating
Admission Webhook	Go	Mutating webhook that intercepts pod creation, extracts runtime context, and dynamically mutates SCC annotations with security context reconciliation
Governance API	Node.js	REST API providing policy evaluation, RBAC, audit logging, SCC version registry, and per-pod migration tracking
ML Risk Engine	Go	Weighted scoring model evaluating privilege gap, blast radius, namespace criticality, failure history, and timing
Istio Integration	YAML	VirtualService and DestinationRule configs for traffic mirroring and incremental weight shifting

---

Project Structure

├── cmd/
│   ├── controller/          # Controller entrypoint
│   ├── webhook/             # Webhook entrypoint
│   └── governance-api/      # Governance API server (Node.js)
├── pkg/
│   ├── api/v1/              # CRD types and deep copy
│   ├── controller/          # Reconciler, risk engine, phase state machine
│   ├── governance/          # Governance API client
│   └── webhook/             # Webhook handler, decision engine
├── deploy/
│   ├── base/                # Namespace, CRDs, RBAC, deployments
│   └── samples/             # Sample SCCMigrationPlan resources
├── scripts/                 # TLS cert generation
├── Dockerfile.controller    # Multi-stage Go build
├── Dockerfile.webhook       # Multi-stage Go build
├── Makefile                 # Build, test, deploy targets
└── go.mod                   # Go module definition

---

Quick Start

See GETTING_STARTED.md for prerequisites, build instructions, and deployment steps.

---

Documentation

Document	Description
GETTING_STARTED.md	Prerequisites, build, deploy, and monitoring guide
ARCHITECTURE.md	Deep-dive into component internals, state machine, decision flows, and risk model
API Reference	Complete REST API documentation — endpoints, schemas, auth, and examples
MAINTAINERS.md	Project maintainers and ownership