diff --git a/docs/modules/policy/architecture.md b/docs/modules/policy/architecture.md index d4a14eea4..96337ba27 100644 --- a/docs/modules/policy/architecture.md +++ b/docs/modules/policy/architecture.md @@ -206,7 +206,111 @@ All payloads are immutable and include analyzer fingerprints (`scanner.native@sh --- -### 6.2 · Trust Lattice Policy Gates +### 6.2 · CI/CD Release Gate API + +The Policy Engine exposes a gate evaluation API for CI/CD pipelines to validate images before deployment. + +#### Gate Endpoint + +``` +POST /api/v1/policy/gate/evaluate +``` + +**Request:** +```json +{ + "imageDigest": "sha256:abc123def456", + "baselineRef": "sha256:baseline789", + "policyId": "production-gate", + "tenantId": "tenant-1" +} +``` + +**Response:** +```json +{ + "verdict": "pass", + "status": "Pass", + "reason": "No new critical vulnerabilities", + "deltaCount": 0, + "criticalCount": 0, + "highCount": 2, + "mediumCount": 5, + "lowCount": 12, + "evaluatedAt": "2025-12-26T12:00:00Z", + "policyVersion": "v1.2.0" +} +``` + +#### Gate Status Values + +| Status | Exit Code | Description | +|--------|-----------|-------------| +| `Pass` | 0 | No blocking issues; safe to deploy | +| `Warn` | 1 | Non-blocking issues detected; configurable pass-through | +| `Fail` | 2 | Blocking issues; deployment should be halted | + +#### Webhook Integration + +The Policy Gateway accepts webhooks from container registries for automated gate evaluation: + +**Docker Registry v2:** +``` +POST /api/v1/webhooks/registry/docker +``` + +**Harbor:** +``` +POST /api/v1/webhooks/registry/harbor +``` + +**Generic (Zastava events):** +``` +POST /api/v1/webhooks/registry/generic +``` + +Webhook handlers enqueue async gate evaluation jobs in the Scheduler via `GateEvaluationJob`. + +#### Gate Bypass Auditing + +Bypass attempts are logged to `policy.gate_bypass_audit`: + +```json +{ + "bypassId": "bypass-uuid", + "imageDigest": "sha256:abc123", + "actor": "deploy-service@example.com", + "justification": "Emergency hotfix - JIRA-12345", + "ipAddress": "10.0.0.100", + "ciContext": { + "provider": "github-actions", + "runId": "12345678", + "workflow": "deploy.yml" + }, + "createdAt": "2025-12-26T12:00:00Z" +} +``` + +#### CLI Integration + +```bash +# Evaluate gate +stella gate evaluate --image sha256:abc123 --baseline sha256:baseline + +# Check gate status +stella gate status --job-id + +# Override with justification +stella gate evaluate --image sha256:abc123 \ + --allow-override \ + --justification "Emergency hotfix approved by CISO - JIRA-12345" +``` + +**See also:** [CI/CD Gate Workflows](.github/workflows/stellaops-gate-example.yml), [Keyless Signing Guide](../signer/guides/keyless-signing.md) + +--- + +### 6.3 · Trust Lattice Policy Gates The Policy Engine evaluates Trust Lattice gates after claim score merging to enforce trust-based constraints on VEX verdicts.