Merge branch 'main' of https://git.stella-ops.org/stella-ops.org/git.stella-ops.org

2025-12-26 15:19:07 +02:00
parent 907783f625 c8f3120174
commit 81e4d76fb8
1 changed files with 105 additions and 1 deletions
--- 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 <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.