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/release-aggregate-cve.md
+++ b/docs/modules/policy/gates/release-aggregate-cve.md
@@ -0,0 +1,137 @@
+# Release Aggregate CVE Gate
+
+**Gate ID:** `release-aggregate-cve`
+
+Enforces aggregate CVE count limits per release by severity level. Unlike per-finding gates, this gate evaluates the total CVE profile of a release candidate.
+
+## How It Works
+
+1. Counts CVE findings by severity (Critical, High, Medium, Low)
+2. Optionally filters by suppression status and reachability
+3. Compares counts against configured limits
+4. Blocks if any limit is exceeded
+5. Warns when counts approach limits (80% threshold)
+
+## Configuration
+
+```json
+{
+  "Policy": {
+    "Gates": {
+      "ReleaseAggregateCve": {
+        "Enabled": true,
+        "MaxCritical": 0,
+        "MaxHigh": 3,
+        "MaxMedium": 20,
+        "MaxLow": null,
+        "MaxTotal": null,
+        "CountSuppressed": false,
+        "OnlyCountReachable": false,
+        "Environments": {
+          "development": {
+            "Enabled": false
+          },
+          "staging": {
+            "MaxCritical": 1,
+            "MaxHigh": 10
+          },
+          "production": {
+            "MaxCritical": 0,
+            "MaxHigh": 0,
+            "OnlyCountReachable": true
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `Enabled` | bool | `true` | Whether the gate is active |
+| `MaxCritical` | int? | `0` | Maximum critical CVEs (CVSS 9.0+); null = unlimited |
+| `MaxHigh` | int? | `3` | Maximum high CVEs (CVSS 7.0-8.9); null = unlimited |
+| `MaxMedium` | int? | `20` | Maximum medium CVEs (CVSS 4.0-6.9); null = unlimited |
+| `MaxLow` | int? | `null` | Maximum low CVEs (CVSS 0.1-3.9); null = unlimited |
+| `MaxTotal` | int? | `null` | Maximum total CVEs regardless of severity; null = unlimited |
+| `CountSuppressed` | bool | `false` | Include suppressed/excepted CVEs in counts |
+| `OnlyCountReachable` | bool | `false` | Only count CVEs with reachable code paths |
+| `Environments` | dict | `{}` | Per-environment overrides |
+
+## Severity Classification
+
+| CVSS Score | Severity |
+|------------|----------|
+| 9.0 - 10.0 | Critical |
+| 7.0 - 8.9 | High |
+| 4.0 - 6.9 | Medium |
+| 0.1 - 3.9 | Low |
+| None/Invalid | Unknown |
+
+## Example Gate Results
+
+**Pass:**
+```
+Release CVE counts within limits. Critical: 0, High: 2, Medium: 15, Low: 8
+```
+
+**Pass (with warning):**
+```
+Release CVE counts within limits. Critical: 0, High: 2, Medium: 15, Low: 8. Warnings: High CVE count (2) approaching limit (3)
+```
+
+**Fail:**
+```
+Release CVE aggregate limits exceeded: Critical: 1/0, High: 5/3
+```
+
+**Fail (total limit):**
+```
+Release CVE aggregate limits exceeded: Total: 55/50
+```
+
+## CLI Usage
+
+```bash
+# Evaluate aggregate gate
+stella policy evaluate --gate release-aggregate-cve --image myapp:v1.2.3
+
+# Custom limits
+stella policy evaluate --gate release-aggregate-cve \
+  --max-critical 0 --max-high 5 --max-medium 30 \
+  --image myapp:v1.2.3
+
+# Only count reachable CVEs
+stella policy evaluate --gate release-aggregate-cve --only-reachable --image myapp:v1.2.3
+
+# Include suppressed CVEs
+stella policy evaluate --gate release-aggregate-cve --count-suppressed --image myapp:v1.2.3
+```
+
+## Suppression Handling
+
+When `CountSuppressed: false` (default):
+- CVEs with valid exceptions are excluded from counts
+- Expired exceptions are counted
+- CVEs suppressed via VEX statements are excluded
+
+When `CountSuppressed: true`:
+- All CVEs are counted regardless of suppression status
+- Useful for tracking true vulnerability exposure
+
+## Progressive Environment Strategy
+
+Recommended limit progression:
+
+| Environment | Critical | High | Medium | Notes |
+|-------------|----------|------|--------|-------|
+| Development | Disabled | - | - | No blocking in dev |
+| Staging | 1 | 10 | 50 | Lenient for testing |
+| Production | 0 | 0 | 20 | Strict, reachable-only |
+
+---
+
+*Last updated: 2026-01-19.*