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/README.md
+++ b/docs/modules/policy/gates/README.md
@@ -0,0 +1,110 @@
+# Policy Gates
+
+Policy gates are automated checks that evaluate release candidates against configurable security criteria. Each gate produces a pass/fail result with detailed reasoning for policy decisions.
+
+## CVE-Aware Gates
+
+| Gate | ID | Description |
+|------|-----|-------------|
+| [EPSS Threshold](epss-threshold.md) | `epss-threshold` | Blocks CVEs above EPSS probability threshold |
+| [KEV Blocker](kev-blocker.md) | `kev-blocker` | Blocks CVEs in CISA Known Exploited Vulnerabilities catalog |
+| [Reachable CVE](reachable-cve.md) | `reachable-cve` | Blocks only CVEs with reachable code paths |
+| [CVE Delta](cve-delta.md) | `cve-delta` | Blocks releases introducing new high-severity CVEs vs baseline |
+| [Release Aggregate CVE](release-aggregate-cve.md) | `release-aggregate-cve` | Enforces aggregate CVE count limits per release |
+
+## Gate Configuration
+
+Gates are configured via `appsettings.json` under the `Policy:Gates` section:
+
+```json
+{
+  "Policy": {
+    "Gates": {
+      "EpssThreshold": {
+        "Enabled": true,
+        "Threshold": 0.6
+      },
+      "KevBlocker": {
+        "Enabled": true,
+        "AllowGracePeriod": true,
+        "GracePeriodDays": 14
+      },
+      "ReachableCve": {
+        "Enabled": true,
+        "SeverityThreshold": 7.0
+      },
+      "CveDelta": {
+        "Enabled": true,
+        "NewCveSeverityThreshold": 7.0,
+        "OnlyBlockReachable": false
+      },
+      "ReleaseAggregateCve": {
+        "Enabled": true,
+        "MaxCritical": 0,
+        "MaxHigh": 3,
+        "MaxMedium": 20
+      }
+    }
+  }
+}
+```
+
+## Environment Overrides
+
+Each gate supports per-environment configuration overrides:
+
+```json
+{
+  "Policy": {
+    "Gates": {
+      "CveDelta": {
+        "Enabled": true,
+        "NewCveSeverityThreshold": 7.0,
+        "Environments": {
+          "development": {
+            "Enabled": false
+          },
+          "staging": {
+            "NewCveSeverityThreshold": 9.0
+          },
+          "production": {
+            "NewCveSeverityThreshold": 7.0,
+            "OnlyBlockReachable": true
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## DI Registration
+
+Register all CVE gates:
+
+```csharp
+services.AddCvePolicyGates(configuration);
+```
+
+Or register individual gates:
+
+```csharp
+services.AddEpssThresholdGate(configuration);
+services.AddKevBlockerGate(configuration);
+services.AddReachableCveGate(configuration);
+services.AddCveDeltaGate(configuration);
+services.AddReleaseAggregateCveGate(configuration);
+```
+
+## Gate Results
+
+All gates return a `GateResult` containing:
+
+- `GateName`: Gate identifier
+- `Passed`: Boolean pass/fail status
+- `Reason`: Human-readable explanation
+- `Details`: Additional metadata (warnings, counts, etc.)
+
+---
+
+*Last updated: 2026-01-19.*
--- 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.*
--- a/docs/modules/policy/gates/epss-threshold.md
+++ b/docs/modules/policy/gates/epss-threshold.md
@@ -0,0 +1,86 @@
+# EPSS Threshold Gate
+
+**Gate ID:** `epss-threshold`
+
+Blocks CVEs with Exploit Prediction Scoring System (EPSS) probability above a configurable threshold. EPSS predicts the likelihood that a CVE will be exploited in the wild within 30 days.
+
+## How It Works
+
+1. For each CVE finding in the release candidate, queries the EPSS score
+2. Compares EPSS probability against the configured threshold
+3. Blocks if any CVE exceeds threshold (or all match in "all must pass" mode)
+4. Provides grace period for newly published CVEs
+
+## Configuration
+
+```json
+{
+  "Policy": {
+    "Gates": {
+      "EpssThreshold": {
+        "Enabled": true,
+        "Threshold": 0.6,
+        "Mode": "any",
+        "GracePeriodDays": 7,
+        "RequireReachability": false,
+        "Environments": {
+          "production": {
+            "Threshold": 0.3
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `Enabled` | bool | `true` | Whether the gate is active |
+| `Threshold` | double | `0.6` | EPSS probability threshold (0.0 - 1.0) |
+| `Mode` | string | `any` | `any` = block if any CVE exceeds; `all` = block only if all exceed |
+| `GracePeriodDays` | int? | `null` | Days after CVE publication before enforcing (null = no grace) |
+| `RequireReachability` | bool | `false` | Only evaluate reachable CVEs |
+| `Environments` | dict | `{}` | Per-environment overrides |
+
+## EPSS Score Interpretation
+
+| EPSS Range | Risk Level | Typical Action |
+|------------|------------|----------------|
+| 0.0 - 0.1 | Very Low | Monitor |
+| 0.1 - 0.3 | Low | Schedule remediation |
+| 0.3 - 0.6 | Medium | Prioritize remediation |
+| 0.6 - 0.9 | High | Block or exception required |
+| 0.9 - 1.0 | Critical | Immediate block |
+
+## Example Gate Results
+
+**Pass:**
+```
+EPSS threshold check passed. 12 CVE(s) evaluated, all below threshold 0.6
+```
+
+**Fail:**
+```
+EPSS threshold exceeded: CVE-2024-1234 (EPSS: 0.72), CVE-2024-5678 (EPSS: 0.85)
+```
+
+## CLI Usage
+
+```bash
+# Evaluate EPSS gate against image
+stella policy evaluate --gate epss-threshold --image myapp:v1.2.3
+
+# Override threshold for testing
+stella policy evaluate --gate epss-threshold --threshold 0.9 --image myapp:v1.2.3
+```
+
+## Data Source
+
+EPSS scores are fetched from [FIRST EPSS](https://www.first.org/epss/) via the configured `IEpssDataProvider`. Scores are cached and updated daily.
+
+---
+
+*Last updated: 2026-01-19.*
--- a/docs/modules/policy/gates/kev-blocker.md
+++ b/docs/modules/policy/gates/kev-blocker.md
@@ -0,0 +1,100 @@
+# KEV Blocker Gate
+
+**Gate ID:** `kev-blocker`
+
+Blocks CVEs listed in the CISA Known Exploited Vulnerabilities (KEV) catalog. KEV entries represent vulnerabilities with confirmed active exploitation in the wild.
+
+## How It Works
+
+1. For each CVE finding in the release candidate, checks KEV catalog membership
+2. Blocks any CVE present in KEV (with optional grace period)
+3. Reports KEV due dates for remediation tracking
+4. Optionally respects KEV due dates as soft deadlines
+
+## Configuration
+
+```json
+{
+  "Policy": {
+    "Gates": {
+      "KevBlocker": {
+        "Enabled": true,
+        "AllowGracePeriod": true,
+        "GracePeriodDays": 14,
+        "BlockPastDueDate": true,
+        "WarnBeforeDueDate": true,
+        "WarnDaysBeforeDue": 7,
+        "RequireReachability": false,
+        "Environments": {
+          "development": {
+            "Enabled": false
+          },
+          "production": {
+            "AllowGracePeriod": false
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `Enabled` | bool | `true` | Whether the gate is active |
+| `AllowGracePeriod` | bool | `true` | Allow grace period after KEV addition |
+| `GracePeriodDays` | int | `14` | Days after KEV addition before blocking |
+| `BlockPastDueDate` | bool | `true` | Block CVEs past their KEV due date |
+| `WarnBeforeDueDate` | bool | `true` | Emit warning as due date approaches |
+| `WarnDaysBeforeDue` | int | `7` | Days before due date to start warning |
+| `RequireReachability` | bool | `false` | Only evaluate reachable CVEs |
+| `Environments` | dict | `{}` | Per-environment overrides |
+
+## KEV Catalog Context
+
+The CISA KEV catalog contains:
+- CVEs with confirmed active exploitation
+- Required remediation due dates (typically 2-3 weeks from addition)
+- Affected vendor/product information
+
+KEV inclusion indicates:
+- Real-world exploitation is occurring
+- Federal agencies must remediate by due date (BOD 22-01)
+- High priority for all organizations
+
+## Example Gate Results
+
+**Pass:**
+```
+KEV blocker check passed. No KEV entries found in 15 CVE findings
+```
+
+**Fail:**
+```
+KEV entries found: CVE-2024-1234 (due: 2024-02-15, overdue), CVE-2024-5678 (due: 2024-02-28, 5 days remaining)
+```
+
+**Warning:**
+```
+KEV blocker check passed. Warnings: CVE-2024-9012 KEV due date approaching (7 days)
+```
+
+## CLI Usage
+
+```bash
+# Evaluate KEV gate against image
+stella policy evaluate --gate kev-blocker --image myapp:v1.2.3
+
+# Check with no grace period
+stella policy evaluate --gate kev-blocker --no-grace-period --image myapp:v1.2.3
+```
+
+## Data Source
+
+KEV data is fetched from [CISA KEV Catalog](https://www.cisa.gov/known-exploited-vulnerabilities-catalog) via the configured `IKevDataProvider`. The catalog is refreshed daily with catalog update timestamps tracked for staleness detection.
+
+---
+
+*Last updated: 2026-01-19.*
--- a/docs/modules/policy/gates/reachable-cve.md
+++ b/docs/modules/policy/gates/reachable-cve.md
@@ -0,0 +1,104 @@
+# Reachable CVE Gate
+
+**Gate ID:** `reachable-cve`
+
+Blocks only CVEs with confirmed reachable code paths from application entry points. This gate leverages Stella's reachability analysis to distinguish exploitable vulnerabilities from those in unreachable code.
+
+## How It Works
+
+1. Evaluates CVE findings against reachability analysis results
+2. Filters to only reachable CVEs (code path exists from entry point to vulnerable function)
+3. Applies severity threshold to reachable CVEs
+4. Blocks if reachable CVEs exceed severity threshold
+
+## Configuration
+
+```json
+{
+  "Policy": {
+    "Gates": {
+      "ReachableCve": {
+        "Enabled": true,
+        "SeverityThreshold": 7.0,
+        "RequireCompleteReachability": false,
+        "TreatUnknownAsReachable": false,
+        "BlockOnReachabilityError": false,
+        "Environments": {
+          "production": {
+            "SeverityThreshold": 4.0,
+            "TreatUnknownAsReachable": true
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `Enabled` | bool | `true` | Whether the gate is active |
+| `SeverityThreshold` | double | `7.0` | CVSS score threshold for reachable CVEs |
+| `RequireCompleteReachability` | bool | `false` | Require reachability analysis for all components |
+| `TreatUnknownAsReachable` | bool | `false` | Treat CVEs with unknown reachability as reachable |
+| `BlockOnReachabilityError` | bool | `false` | Fail gate if reachability analysis fails |
+| `Environments` | dict | `{}` | Per-environment overrides |
+
+## Reachability States
+
+| State | Description | Default Behavior |
+|-------|-------------|------------------|
+| `Reachable` | Code path confirmed from entry point | Subject to severity threshold |
+| `NotReachable` | No code path found | Allowed (not blocked) |
+| `Unknown` | Reachability not analyzed | Depends on `TreatUnknownAsReachable` |
+| `Partial` | Some paths reachable | Treated as reachable |
+
+## Example Gate Results
+
+**Pass:**
+```
+Reachable CVE check passed. 8 CVE(s) found, 2 reachable, none above threshold 7.0
+```
+
+**Pass (no reachable):**
+```
+Reachable CVE check passed. 15 CVE(s) found, 0 reachable (all in unreachable code)
+```
+
+**Fail:**
+```
+Reachable high-severity CVE(s) found: CVE-2024-1234 (CVSS: 9.1, reachable via /api/upload), CVE-2024-5678 (CVSS: 7.5, reachable via /auth/login)
+```
+
+## CLI Usage
+
+```bash
+# Evaluate reachable CVE gate
+stella policy evaluate --gate reachable-cve --image myapp:v1.2.3
+
+# With specific severity threshold
+stella policy evaluate --gate reachable-cve --severity 9.0 --image myapp:v1.2.3
+
+# Treat unknown as reachable (conservative)
+stella policy evaluate --gate reachable-cve --treat-unknown-reachable --image myapp:v1.2.3
+```
+
+## Integration with Reachability Analysis
+
+This gate requires reachability analysis results from the Stella Scanner. Ensure images are scanned with reachability enabled:
+
+```bash
+stella scan --image myapp:v1.2.3 --reachability
+```
+
+Reachability analysis examines:
+- Container entry points (ENTRYPOINT, CMD)
+- Exposed ports and expected protocols
+- Call graphs from entry points to vulnerable functions
+- Language-specific dependency loading patterns
+
+---
+
+*Last updated: 2026-01-19.*
--- 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.*