doctor enhancements, setup, enhancements, ui functionality and design consolidation and , test projects fixes , product advisory attestation/rekor and delta verfications enhancements

2026-01-19 09:02:59 +02:00
parent 8c4bf54aed
commit 17419ba7c4
809 changed files with 170738 additions and 12244 deletions
--- a/docs/modules/policy/gates/cve-delta.md
+++ b/docs/modules/policy/gates/cve-delta.md
@@ -0,0 +1,133 @@
+# CVE Delta Gate
+
+**Gate ID:** `cve-delta`
+
+Blocks releases that introduce new high-severity CVEs compared to a baseline. This gate prevents security regressions by tracking the CVE delta between release versions.
+
+## How It Works
+
+1. Retrieves CVE findings for current release candidate
+2. Retrieves CVE findings from baseline (previous version or reference image)
+3. Computes delta: new CVEs, fixed CVEs, unchanged CVEs
+4. Blocks if new CVEs exceed severity threshold
+5. Optionally tracks remediation SLA for existing CVEs
+
+## Configuration
+
+```json
+{
+  "Policy": {
+    "Gates": {
+      "CveDelta": {
+        "Enabled": true,
+        "NewCveSeverityThreshold": 7.0,
+        "OnlyBlockReachable": false,
+        "RemediationSlaDays": 30,
+        "AllowFirstRelease": true,
+        "Environments": {
+          "development": {
+            "NewCveSeverityThreshold": 9.0
+          },
+          "staging": {
+            "NewCveSeverityThreshold": 7.0,
+            "OnlyBlockReachable": true
+          },
+          "production": {
+            "NewCveSeverityThreshold": 7.0,
+            "OnlyBlockReachable": true,
+            "RemediationSlaDays": 14
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `Enabled` | bool | `true` | Whether the gate is active |
+| `NewCveSeverityThreshold` | double | `7.0` | CVSS threshold for blocking new CVEs |
+| `OnlyBlockReachable` | bool | `false` | Only block new CVEs with reachable code paths |
+| `RemediationSlaDays` | int? | `null` | SLA days for existing CVE remediation (null = disabled) |
+| `AllowFirstRelease` | bool | `true` | Allow first release without baseline |
+| `Environments` | dict | `{}` | Per-environment overrides |
+
+## Delta Computation
+
+The gate computes three sets:
+
+| Set | Definition | Gate Behavior |
+|-----|------------|---------------|
+| **New CVEs** | In current, not in baseline | Block if ≥ threshold |
+| **Fixed CVEs** | In baseline, not in current | Reported as improvement |
+| **Unchanged CVEs** | In both current and baseline | Subject to SLA tracking |
+
+## Example Gate Results
+
+**Pass:**
+```
+CVE delta check passed. New: 3, Fixed: 5, Unchanged: 12 (3 new low-severity allowed)
+```
+
+**Pass (with improvement):**
+```
+CVE delta check passed. New: 0, Fixed: 8, Unchanged: 10. Warnings: Improvement: 3 high+ severity CVE(s) fixed
+```
+
+**Fail:**
+```
+Release introduces 2 new CVE(s) at or above severity 7.0: CVE-2024-1234 (CVSS: 8.1, reachable), CVE-2024-5678 (CVSS: 7.3)
+```
+
+**Fail (no baseline):**
+```
+CVE delta gate requires baseline reference but none provided
+```
+
+**Warning (SLA):**
+```
+CVE delta check passed. Warnings: 3 CVE(s) past remediation SLA: CVE-2024-0001, CVE-2024-0002, CVE-2024-0003
+```
+
+## Baseline Resolution
+
+The baseline can be provided in multiple ways:
+
+1. **Explicit reference**: Via `--baseline` flag or context
+2. **ICveDeltaProvider**: Custom provider implementation
+3. **Previous deployment**: Automatically resolved from environment history
+
+```bash
+# Explicit baseline
+stella policy evaluate --gate cve-delta --image myapp:v1.2.3 --baseline myapp:v1.2.2
+
+# Baseline from previous deployment
+stella policy evaluate --gate cve-delta --image myapp:v1.2.3 --env production
+```
+
+## CLI Usage
+
+```bash
+# Basic delta evaluation
+stella policy evaluate --gate cve-delta --image myapp:v1.2.3 --baseline myapp:v1.2.2
+
+# Only block reachable new CVEs
+stella policy evaluate --gate cve-delta --only-reachable --image myapp:v1.2.3
+
+# First release (no baseline)
+stella policy evaluate --gate cve-delta --allow-first-release --image myapp:v1.2.3
+```
+
+## Use Cases
+
+1. **Prevent regressions**: Block releases that add new vulnerabilities
+2. **Track improvements**: Report CVEs fixed between releases
+3. **SLA enforcement**: Warn on CVEs exceeding remediation timeline
+4. **Base image updates**: Evaluate security impact of base image changes
+
+---
+
+*Last updated: 2026-01-19.*