# Compliance API

Module: `citadel_operator.k3s.compliance`

Integrates with kube-bench (CIS Kubernetes Benchmark) and Trivy Operator (vulnerability and config audit reports).

## Constants

```python
KUBE_BENCH_NAMESPACE = "citadel-compliance"
KUBE_BENCH_CRONJOB_NAME = "kube-bench-scan"
SEVERITY_CRITICAL = "CRITICAL"
SEVERITY_HIGH = "HIGH"
SEVERITY_MEDIUM = "MEDIUM"
SEVERITY_LOW = "LOW"
SEVERITY_UNKNOWN = "UNKNOWN"
```

## ComplianceFailure

Frozen dataclass representing a single CIS check failure.

```python
@dataclass(frozen=True)
class ComplianceFailure:
    check_id: str       # CIS check ID, e.g., "1.2.3"
    description: str
    severity: str       # One of VALID_SEVERITIES
    remediation: str
```

## ComplianceScanResult

Frozen dataclass representing CIS benchmark scan results.

```python
@dataclass(frozen=True)
class ComplianceScanResult:
    benchmark: str                              # Benchmark identifier
    score: float                                # 0.0 to 100.0
    total_checks: int
    passed: int
    failed: int
    warnings: int
    failures: tuple[ComplianceFailure, ...]
    scanned_at: str                             # ISO 8601
```

### Properties

| Property | Type | Description |
|----------|------|-------------|
| `passing_rate` | `float` | `passed / total_checks` |
| `has_critical_failures` | `bool` | Any CRITICAL severity failures |
| `has_high_failures` | `bool` | Any HIGH severity failures |
| `failures_by_severity` | `dict[str, list[ComplianceFailure]]` | Grouped by severity |

## ComplianceScanner

### Constructor

```python
ComplianceScanner(kubeconfig: str | None = None)
```

### Methods

| Method | Signature | Description |
|--------|-----------|-------------|
| `run_cis_benchmark` | `() -> ComplianceScanResult` | Parse latest kube-bench results from ConfigMaps |
| `trigger_cis_scan` | `() -> str` | Create one-off kube-bench Job, returns job name |
| `get_vulnerability_report` | `(namespace="default") -> list[dict]` | Trivy VulnerabilityReports |
| `get_config_audit_reports` | `(namespace="default") -> list[dict]` | Trivy ConfigAuditReports |
| `get_compliance_summary` | `() -> dict` | Aggregated CIS + Trivy summary |
| `list_non_compliant_workloads` | `(namespace="default") -> list[dict]` | HIGH+ severity violations |

### Usage

```python
from citadel_operator.k3s.compliance import ComplianceScanner

scanner = ComplianceScanner()

# Get latest CIS results
result = scanner.run_cis_benchmark()
print(f"CIS Score: {result.score:.1f}% ({result.passed}/{result.total_checks} passed)")

if result.has_critical_failures:
    for f in result.failures_by_severity.get("CRITICAL", []):
        print(f"  CRITICAL [{f.check_id}]: {f.description}")
        print(f"    Fix: {f.remediation}")

# Trigger a fresh scan
job_name = scanner.trigger_cis_scan()
print(f"Scan job created: {job_name}")

# Check for vulnerable workloads
vulns = scanner.list_non_compliant_workloads(namespace="production")
for w in vulns:
    print(f"  {w['workload']}: {w['severity']} - {w['description']}")
```
