# Container Image Governance Policy
## Policy Statement
All container images deployed to KuiperDesk clusters MUST be pulled exclusively through the Harbor registry at `registry.arivaran.ai`. Direct pulls from external registries are blocked by Kyverno admission control.
## Enforcement Mechanism
| Layer | Control | Effect |
|-------|---------|--------|
| **Admission** | Kyverno ClusterPolicy `require-registry` | Rejects any Pod with image not matching `registry.arivaran.ai/*` |
| **Runtime** | RKE2 `registries.yaml` mirror config | Intercepts pulls to docker.io, quay.io, ghcr.io, etc. and routes through Harbor |
| **Scan** | Trivy (Harbor built-in) | Scans every cached image for CRITICAL/HIGH CVEs |
| **Sign** | cosign (Harbor built-in) | Signs images with Sigstore; `redirect.disable: true` for external verification |
## Proxy-Cache Projects
| Harbor Project | Upstream Registry | Purpose |
|---|---|---|
| `library` | (local) | KuiperDesk product images (aa-hash-svc, aa-twin-svc, etc.) |
| `arivaran` | (local) | Company-built images (ci-runner, etc.) |
| `proxy-dockerhub` | docker.io | Docker Hub (nginx, postgres, redis, etc.) |
| `proxy-quay` | quay.io | Quay.io (keycloak, jetstack/cert-manager, etc.) |
| `proxy-ghcr` | ghcr.io | GitHub Container Registry (cloudnative-pg, etc.) |
| `proxy-k8s` | registry.k8s.io | Kubernetes project images (ingress-nginx, etc.) |
| `proxy-gcr` | gcr.io | Google Container Registry |
| `proxy-codeberg` | codeberg.org | Codeberg containers |
## Adding a New External Registry
1. **Create proxy-cache project** in Harbor admin UI or API:
- Project name: `proxy-<shortname>` (e.g., `proxy-mcr` for mcr.microsoft.com)
- Type: Proxy Cache
- Endpoint: upstream registry URL
2. **Update registries.yaml template**: `kuiperdesk/aainfra/ansible/templates/registries.yaml.j2`
3. **Deploy** to all cluster nodes (Ansible or manual)
4. **Rolling restart** RKE2 on each node (maintain etcd quorum)
5. **Update this document** with the new mapping
## Compliance Mapping
### SOC 2 Type II
| Trust Service Criteria | Control | How This Policy Satisfies |
|---|---|---|
| **CC6.1** Logical access controls | Kyverno admission + Harbor RBAC | Only authorized images from a controlled registry can run. No anonymous external pulls. |
| **CC6.6** Restrict access to system components | RKE2 registry mirrors | All image traffic funneled through a single managed endpoint with TLS. |
| **CC7.1** Monitor system components | Harbor audit logs + Trivy scans | Every image pull is logged. Every cached image is scanned for vulnerabilities. |
| **CC7.2** Monitor for anomalies | Trivy CRITICAL/HIGH alerts | New CVEs in cached images trigger alerts via Harbor webhook → AlertManager. |
| **CC8.1** Change management | Kyverno policy enforcement | Unauthorized images are rejected at admission — cannot bypass via kubectl. |
### FedRAMP (Moderate/High)
| NIST 800-53 Control | Control Family | How This Policy Satisfies |
|---|---|---|
| **CM-2** Baseline configuration | Configuration Mgmt | All images pinned to Harbor — reproducible, auditable baseline. |
| **CM-7** Least functionality | Configuration Mgmt | Only approved images run. No arbitrary container execution. |
| **SA-12** Supply chain protection | System Acquisition | Single controlled source for all software components. No direct internet pulls in production. |
| **SI-7** Software/firmware integrity | System & Info Integrity | cosign signatures verify image provenance. Trivy scans detect tampering/vulnerabilities. |
| **AU-2 / AU-3** Audit events + content | Audit & Accountability | Harbor logs: who pulled what, when, from where. Full provenance chain. |
| **SC-7** Boundary protection | System & Comms Protection | All image traffic through Harbor (single egress). No direct container registry access from pods. |
| **RA-5** Vulnerability scanning | Risk Assessment | Trivy auto-scans every image on push/pull. CRITICAL/HIGH CVEs block deployment (optional gate). |
### HIPAA (where applicable)
| Safeguard | How This Policy Satisfies |
|---|---|
| **§164.312(a)** Access control | Only Harbor-hosted images can execute in the environment |
| **§164.312(b)** Audit controls | Full pull/push audit trail in Harbor |
| **§164.312(c)** Integrity | cosign signatures + Trivy scans ensure image integrity |
### ISO 27001:2022
| Control | How This Policy Satisfies |
|---|---|
| **A.8.9** Configuration management | Centralized image registry with version control |
| **A.8.25** Secure development lifecycle | Images scanned before deployment |
| **A.8.28** Secure coding | No untrusted code execution (admission control) |
## Air-Gap Readiness
This architecture is air-gap ready:
1. **Pre-warm**: Pull all required images through Harbor while internet is connected
2. **Disconnect**: Remove internet access from cluster nodes
3. **Operate**: All pods pull from Harbor's local cache — no external connectivity needed
4. **Update**: Reconnect briefly to sync new versions, then disconnect again
This is the deployment model for FedRAMP High satellites on AWS GovCloud and on-premises Tier-A customer deployments.
## Incident Response
If an image with a critical CVE is discovered:
1. Harbor's Trivy scan flags it automatically
2. AlertManager webhook fires to `#security` Matrix room
3. Use Harbor's "Prevent Vulnerable Images" policy to block future pulls
4. Rebuild/update the affected image and push to Harbor
5. Rolling restart affected deployments
## Revision History
| Date | Change | Author |
|------|--------|--------|
| 2026-03-22 | Initial policy. All registries proxied through Harbor. Kyverno enforced. | Zara Okonkwo (QA), Navid Ahmadi (Security review) |