sprints completion. new product advisories prepared
This commit is contained in:
master
@@ -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
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user