sprints completion. new product advisories prepared

2026-01-16 16:30:03 +02:00
parent a927d924e3
commit 4ca3ce8fb4
255 changed files with 42434 additions and 1020 deletions
--- a/docs/modules/policy/architecture.md
+++ b/docs/modules/policy/architecture.md
@@ -394,6 +394,9 @@ public sealed record GateResult
 | **SourceQuotaGate** | Prevent single-source dominance without corroboration | `gates.sourceQuota` |
 | **ReachabilityRequirementGate** | Require reachability proof for critical CVEs | `gates.reachabilityRequirement` |
 | **EvidenceFreshnessGate** | Reject stale evidence below freshness threshold | `gates.evidenceFreshness` |
+| **CvssThresholdGate** | Block findings above CVSS score threshold | `gates.cvssThreshold` |
+| **SbomPresenceGate** | Require valid SBOM for release artifacts | `gates.sbomPresence` |
+| **SignatureRequiredGate** | Require signatures on specified evidence types | `gates.signatureRequired` |

 #### MinimumConfidenceGate

@@ -466,6 +469,112 @@ gates:

 - **Behavior**: Fails when CRITICAL/HIGH CVE marked `not_affected` lacks reachability proof (unless bypass reason applies).

+#### CvssThresholdGate
+
+> **Sprint:** SPRINT_20260112_017_POLICY_cvss_threshold_gate
+
+Blocks findings above a configurable CVSS score threshold per environment:
+
+```yaml
+gates:
+  cvssThreshold:
+    enabled: true
+    priority: 15
+    defaultThreshold: 7.0
+    thresholds:
+      production: 7.0
+      staging: 8.0
+      development: 9.0
+    cvssVersionPreference: highest  # v3.1, v4.0, or highest
+    failOnMissingCvss: false
+    requireAllVersionsPass: false
+    allowlist:
+      - CVE-2024-XXXXX  # False positive
+    denylist:
+      - CVE-2024-YYYYY  # Always block
+```
+
+- **Behavior**: Fails when CVSS base score exceeds environment threshold.
+- **CVSS Versions**: Supports both CVSS v3.1 and v4.0; preference configurable.
+- **Allowlist**: CVEs that bypass threshold enforcement.
+- **Denylist**: CVEs that always fail regardless of score.
+- **Offline**: Operates without external lookups; uses injected or metadata scores.
+
+#### SbomPresenceGate
+
+> **Sprint:** SPRINT_20260112_017_POLICY_sbom_presence_gate
+
+Requires valid SBOM presence for release artifacts:
+
+```yaml
+gates:
+  sbomPresence:
+    enabled: true
+    priority: 5
+    enforcement:
+      production: required
+      staging: required
+      development: optional
+    acceptedFormats:
+      - spdx-2.3
+      - spdx-3.0.1
+      - cyclonedx-1.5
+      - cyclonedx-1.6
+    minimumComponents: 1
+    requireSignature: true
+    schemaValidation: true
+    requirePrimaryComponent: true
+```
+
+- **Enforcement Levels**: `required` (fail), `recommended` (warn), `optional` (pass).
+- **Format Validation**: Validates SBOM format against accepted list; normalizes format names.
+- **Schema Validation**: Validates SBOM against bundled JSON schemas.
+- **Signature Requirement**: Optionally requires signed SBOM.
+- **Minimum Components**: Ensures SBOM has meaningful inventory.
+
+#### SignatureRequiredGate
+
+> **Sprint:** SPRINT_20260112_017_POLICY_signature_required_gate
+
+Requires cryptographic signatures on specified evidence types:
+
+```yaml
+gates:
+  signatureRequired:
+    enabled: true
+    priority: 3
+    evidenceTypes:
+      sbom:
+        required: true
+        trustedIssuers:
+          - "*@company.com"
+          - "build-service@ci.example.com"
+        acceptedAlgorithms:
+          - ES256
+          - RS256
+      vex:
+        required: true
+        trustedIssuers:
+          - "*@vendor.com"
+      attestation:
+        required: true
+    enableKeylessVerification: true
+    fulcioRoots: /etc/stella/trust/fulcio-roots.pem
+    requireTransparencyLogInclusion: true
+    environments:
+      development:
+        requiredOverride: false
+        skipEvidenceTypes:
+          - sbom
+```
+
+- **Per-Evidence-Type**: Configure requirements per evidence type (SBOM, VEX, attestation).
+- **Issuer Constraints**: Wildcard support (`*@domain.com`) for email patterns.
+- **Algorithm Enforcement**: Limit accepted signature algorithms.
+- **Keyless (Fulcio)**: Support Sigstore keyless signatures with Fulcio certificate verification.
+- **Transparency Log**: Optionally require Rekor inclusion proof.
+- **Environment Overrides**: Relax requirements for non-production environments.
+
 #### Gate Registry

 Gates are registered via DI and evaluated in sequence:
@@ -496,6 +605,9 @@ public interface IPolicyGateRegistry
 | SourceQuotaGate | `src/Policy/__Libraries/StellaOps.Policy/Gates/SourceQuotaGate.cs` |
 | ReachabilityRequirementGate | `src/Policy/__Libraries/StellaOps.Policy/Gates/ReachabilityRequirementGate.cs` |
 | EvidenceFreshnessGate | `src/Policy/__Libraries/StellaOps.Policy/Gates/EvidenceFreshnessGate.cs` |
+| CvssThresholdGate | `src/Policy/__Libraries/StellaOps.Policy/Gates/CvssThresholdGate.cs` |
+| SbomPresenceGate | `src/Policy/__Libraries/StellaOps.Policy/Gates/SbomPresenceGate.cs` |
+| SignatureRequiredGate | `src/Policy/__Libraries/StellaOps.Policy/Gates/SignatureRequiredGate.cs` |

 See `etc/policy-gates.yaml.sample` for complete gate configuration options.

--- a/docs/modules/policy/determinization-api.md
+++ b/docs/modules/policy/determinization-api.md
@@ -216,3 +216,216 @@ services.AddPolicyEngine();  // Includes determinization
 ---

 *Last updated: 2026-01-07 (Sprint 20260106_001_003)*
+
+---
+
+## 10. Unknown Mapping and Grey Queue Semantics
+
+> **Sprint:** SPRINT_20260112_004_POLICY_unknowns_determinization_greyqueue
+
+When evidence is incomplete or conflicting, the Determinization Gate produces outcomes that map to the "Grey Queue" for operator review.
+
+### 10.1 Unknown State Mapping
+
+The Grey Queue captures observations with uncertain status:
+
+| Policy Verdict | Observation State | OpenVEX Mapping | Description |
+|----------------|------------------|-----------------|-------------|
+| `GuardedPass` | `PendingDeterminization` | `under_investigation` | Allowed with guardrails; monitoring required |
+| `Deferred` | `PendingDeterminization` | `under_investigation` | Decision deferred; needs additional evidence |
+| `Escalated` (conflict) | `Disputed` | `under_investigation` | Conflicting evidence; manual adjudication required |
+
+### 10.2 Reanalysis Fingerprint
+
+Each unknown is assigned a deterministic fingerprint enabling reproducible replays:
+
+```json
+{
+  "fingerprintId": "sha256:abc123...",
+  "dsseBundleDigest": "sha256:def456...",
+  "evidenceDigests": [
+    "sha256:111...",
+    "sha256:222..."
+  ],
+  "toolVersions": {
+    "scanner": "2.1.0",
+    "reachability": "1.5.2"
+  },
+  "productVersion": "1.0.0",
+  "policyConfigHash": "sha256:789...",
+  "signalWeightsHash": "sha256:aaa...",
+  "computedAt": "2026-01-15T10:00:00Z",
+  "triggers": [
+    {
+      "type": "epss.updated@1",
+      "receivedAt": "2026-01-15T09:55:00Z",
+      "delta": 0.15
+    }
+  ],
+  "nextActions": ["await_vex", "run_reachability"]
+}
+```
+
+### 10.3 Conflict Detection and Routing
+
+Conflicting evidence automatically routes to `Disputed` state:
+
+| Conflict Type | Detection | Adjudication Path |
+|---------------|-----------|-------------------|
+| `VexReachabilityContradiction` | VEX not_affected + confirmed reachable | Manual review |
+| `StaticRuntimeContradiction` | Static unreachable + runtime execution | Auto-escalate |
+| `VexStatusConflict` | Multiple providers with conflicting status | Trust-weighted resolution or manual |
+| `BackportStatusConflict` | Backport claimed + affected status | Manual review |
+| `EpssRiskContradiction` | Low EPSS + KEV or high exploitation | Auto-escalate |
+
+### 10.4 Trigger Events for Reanalysis
+
+The Grey Queue tracks triggers that caused reanalysis:
+
+| Event Type | Version | Delta Threshold | Description |
+|------------|---------|-----------------|-------------|
+| `epss.updated` | 1 | 0.1 | EPSS score changed significantly |
+| `vex.updated` | 1 | N/A | VEX statement added/modified |
+| `reachability.updated` | 1 | N/A | Reachability analysis completed |
+| `runtime.updated` | 1 | N/A | Runtime observation recorded |
+| `sbom.updated` | 1 | N/A | SBOM content changed |
+| `dsse_validation.changed` | 1 | N/A | DSSE validation status changed |
+| `rekor_entry.added` | 1 | N/A | New Rekor transparency entry |
+
+### 10.5 Next Actions
+
+Each unknown suggests next actions for resolution:
+
+| Action | Description |
+|--------|-------------|
+| `await_vex` | Wait for vendor VEX statement |
+| `run_reachability` | Execute reachability analysis |
+| `enable_runtime` | Deploy runtime telemetry |
+| `verify_backport` | Confirm backport availability |
+| `manual_review` | Escalate to security team |
+| `trust_resolution` | Resolve issuer trust conflict |
+
+---
+
+## 11. Related Documentation
+
+- [Determinization Library](./determinization-architecture.md) - Core determinization models
+- [Policy Engine Architecture](./architecture.md) - Overall policy engine design
+- [Signal Snapshot Models](../../api/signals/reachability-contract.md) - Signal data structures
+- [VEX Consensus Guide](../../VEX_CONSENSUS_GUIDE.md) - VEX correlation and consensus
+
+---
+
+## 12. Determinization Configuration
+
+> **Sprint:** SPRINT_20260112_012_POLICY_determinization_reanalysis_config
+
+The Determinization Gate uses persisted configuration for reanalysis triggers, conflict handling, and per-environment thresholds.
+
+### 12.1 Configuration Schema
+
+```json
+{
+  "reanalysisTriggers": {
+    "epssDeltaThreshold": 0.2,
+    "triggerOnThresholdCrossing": true,
+    "triggerOnRekorEntry": true,
+    "triggerOnVexStatusChange": true,
+    "triggerOnRuntimeTelemetryChange": true,
+    "triggerOnPatchProofAdded": true,
+    "triggerOnDsseValidationChange": true,
+    "triggerOnToolVersionChange": false
+  },
+  "conflictHandling": {
+    "vexReachabilityContradiction": "RequireManualReview",
+    "staticRuntimeContradiction": "RequireManualReview",
+    "vexStatusConflict": "RequestVendorClarification",
+    "backportStatusConflict": "RequireManualReview",
+    "escalationSeverityThreshold": 0.85,
+    "conflictTtlHours": 48
+  },
+  "environmentThresholds": {
+    "production": {
+      "minConfidence": 0.75,
+      "maxEntropy": 0.3,
+      "epssThreshold": 0.3,
+      "requireReachability": true
+    },
+    "staging": {
+      "minConfidence": 0.60,
+      "maxEntropy": 0.5,
+      "epssThreshold": 0.4,
+      "requireReachability": true
+    },
+    "development": {
+      "minConfidence": 0.40,
+      "maxEntropy": 0.7,
+      "epssThreshold": 0.6,
+      "requireReachability": false
+    }
+  }
+}
+```
+
+### 12.2 Reanalysis Trigger Defaults
+
+| Trigger | Default | Description |
+|---------|---------|-------------|
+| `epssDeltaThreshold` | 0.2 | Minimum EPSS delta to trigger reanalysis |
+| `triggerOnThresholdCrossing` | true | Trigger when EPSS crosses a bucket threshold |
+| `triggerOnRekorEntry` | true | Trigger on new Rekor transparency entry |
+| `triggerOnVexStatusChange` | true | Trigger when VEX status changes |
+| `triggerOnRuntimeTelemetryChange` | true | Trigger on runtime exploit/reachability signals |
+| `triggerOnPatchProofAdded` | true | Trigger when binary patch proof is added |
+| `triggerOnDsseValidationChange` | true | Trigger when DSSE validation state changes |
+| `triggerOnToolVersionChange` | false | Trigger on tool version updates (disabled by default) |
+
+### 12.3 Conflict Handling Actions
+
+| Action | Description |
+|--------|-------------|
+| `AutoResolve` | System resolves using trust scores |
+| `RequireManualReview` | Route to Grey Queue for operator review |
+| `RequestVendorClarification` | Queue for vendor outreach |
+| `Escalate` | Escalate to security team |
+| `Block` | Block until conflict is resolved |
+
+### 12.4 Environment Threshold Presets
+
+| Preset | MinConfidence | MaxEntropy | EPSS Threshold |
+|--------|---------------|------------|----------------|
+| Relaxed (dev) | 0.40 | 0.7 | 0.6 |
+| Standard (staging) | 0.60 | 0.5 | 0.4 |
+| Strict (production) | 0.75 | 0.3 | 0.3 |
+
+### 12.5 Configuration API
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/v1/policy/config/determinization` | GET | Get effective config for tenant |
+| `/api/v1/policy/config/determinization/defaults` | GET | Get system defaults |
+| `/api/v1/policy/config/determinization/audit` | GET | Get configuration change history |
+| `/api/v1/policy/config/determinization` | PUT | Update config (policy-admin required) |
+| `/api/v1/policy/config/determinization/validate` | POST | Validate config without saving |
+
+### 12.6 Configuration Binding
+
+In `appsettings.yaml`:
+
+```yaml
+Policy:
+  Determinization:
+    ReanalysisTriggers:
+      EpssDeltaThreshold: 0.2
+      TriggerOnThresholdCrossing: true
+      TriggerOnRekorEntry: true
+      TriggerOnVexStatusChange: true
+      TriggerOnToolVersionChange: false
+    ConflictHandling:
+      VexReachabilityContradiction: RequireManualReview
+      EscalationSeverityThreshold: 0.85
+    EnvironmentThresholds:
+      Production:
+        MinConfidence: 0.75
+        MaxEntropy: 0.3
+```