177 lines
6.6 KiB
Markdown
177 lines
6.6 KiB
Markdown
# Determinization Gate API Reference
|
|
|
|
> **Audience:** Backend integrators, policy operators, and security engineers working with CVE observations.
|
|
> **Sprint:** 20260106_001_003_POLICY_determinization_gates
|
|
|
|
This document describes the Determinization Gate API and the `GuardedPass` verdict status for uncertain CVE observations.
|
|
|
|
---
|
|
|
|
## 1. Overview
|
|
|
|
The Determinization Gate evaluates CVE observations against uncertainty thresholds and produces verdicts based on available evidence (EPSS, VEX, reachability, runtime, backport signals). It introduces `GuardedPass` status for observations that don't have enough evidence for a confident determination but don't exceed risk thresholds.
|
|
|
|
### Key Components
|
|
|
|
| Component | Purpose |
|
|
|-----------|---------|
|
|
| `DeterminizationGate` | Policy gate that evaluates uncertainty and produces verdicts |
|
|
| `DeterminizationPolicy` | Rule set for allow/quarantine/escalate decisions |
|
|
| `SignalUpdateHandler` | Handles signal updates and triggers re-evaluation |
|
|
| `DeterminizationGateMetrics` | OpenTelemetry metrics for observability |
|
|
|
|
---
|
|
|
|
## 2. PolicyVerdictStatus
|
|
|
|
Policy evaluations return a `PolicyVerdictStatus` indicating the outcome:
|
|
|
|
| Status | Code | Description | Monitoring Required |
|
|
|--------|------|-------------|---------------------|
|
|
| `Pass` | 0 | Finding meets policy requirements. No action needed. | No |
|
|
| `Blocked` | 1 | Finding fails policy checks; must be remediated. | No |
|
|
| `Ignored` | 2 | Finding deliberately ignored via policy exception. | No |
|
|
| `Warned` | 3 | Finding passes but with warnings. | No |
|
|
| `Deferred` | 4 | Decision deferred; needs additional evidence. | No |
|
|
| `Escalated` | 5 | Decision escalated for human review. | No |
|
|
| `RequiresVex` | 6 | VEX statement required to make decision. | No |
|
|
| `GuardedPass` | 7 | Finding allowed with runtime monitoring guardrails. | **Yes** |
|
|
|
|
---
|
|
|
|
## 3. GuardedPass Status
|
|
|
|
`GuardedPass` is a specialized status for CVE observations with uncertain evidence. It enables "allow with guardrails" semantics.
|
|
|
|
### 3.1 When Issued
|
|
|
|
- Observation has insufficient evidence for full determination (high entropy)
|
|
- Trust score below thresholds but above blocking level
|
|
- Non-production environments with moderate uncertainty
|
|
- Reachability status is unknown but not confirmed reachable
|
|
|
|
### 3.2 GuardRails Object
|
|
|
|
When `GuardedPass` is returned, the verdict includes a `guardRails` object:
|
|
|
|
```json
|
|
{
|
|
"status": "GuardedPass",
|
|
"reason": "Uncertain observation allowed with guardrails in staging",
|
|
"matchedRule": "GuardedAllowNonProd",
|
|
"guardRails": {
|
|
"enableRuntimeMonitoring": true,
|
|
"reviewInterval": "7.00:00:00",
|
|
"epssEscalationThreshold": 0.4,
|
|
"escalatingReachabilityStates": ["Reachable", "ObservedReachable"],
|
|
"maxGuardedDuration": "30.00:00:00",
|
|
"policyRationale": "Auto-allowed: entropy=0.45, trust=0.38, env=staging"
|
|
},
|
|
"suggestedObservationState": "PendingDeterminization",
|
|
"uncertaintyScore": {
|
|
"entropy": 0.45,
|
|
"completeness": 0.55,
|
|
"tier": "Medium",
|
|
"missingSignals": ["runtime", "backport"]
|
|
}
|
|
}
|
|
```
|
|
|
|
### 3.3 Consumer Responsibilities
|
|
|
|
When receiving `GuardedPass`:
|
|
|
|
1. **Enable Runtime Monitoring:** Start observing the component for vulnerable code execution
|
|
2. **Schedule Review:** Set up periodic review at `reviewInterval`
|
|
3. **EPSS Escalation:** Auto-escalate if EPSS score exceeds `epssEscalationThreshold`
|
|
4. **Reachability Escalation:** Auto-escalate if reachability transitions to escalating states
|
|
5. **Duration Limit:** Convert to `Blocked` if guard duration exceeds `maxGuardedDuration`
|
|
|
|
---
|
|
|
|
## 4. Determinization Rules
|
|
|
|
The gate evaluates rules in priority order:
|
|
|
|
| Priority | Rule | Condition | Result |
|
|
|----------|------|-----------|--------|
|
|
| 10 | RuntimeEscalation | Runtime evidence shows vulnerable code loaded | Escalated |
|
|
| 20 | EpssQuarantine | EPSS score exceeds threshold | Blocked |
|
|
| 25 | ReachabilityQuarantine | Code proven reachable | Blocked |
|
|
| 30 | ProductionEntropyBlock | High entropy in production | Blocked |
|
|
| 40 | StaleEvidenceDefer | Evidence is stale | Deferred |
|
|
| 50 | GuardedAllowNonProd | Uncertain in non-prod | GuardedPass |
|
|
| 60 | UnreachableAllow | Unreachable with high confidence | Pass |
|
|
| 65 | VexNotAffectedAllow | VEX not_affected from trusted issuer | Pass |
|
|
| 70 | SufficientEvidenceAllow | Low entropy, high trust | Pass |
|
|
| 80 | GuardedAllowModerateUncertainty | Moderate uncertainty, reasonable trust | GuardedPass |
|
|
| 100 | DefaultDefer | No rule matched | Deferred |
|
|
|
|
---
|
|
|
|
## 5. Environment Thresholds
|
|
|
|
Thresholds vary by deployment environment:
|
|
|
|
| Environment | MinConfidence | MaxEntropy | EPSS Threshold | Require Reachability |
|
|
|-------------|---------------|------------|----------------|---------------------|
|
|
| Production | 0.75 | 0.3 | 0.3 | Yes |
|
|
| Staging | 0.60 | 0.5 | 0.4 | Yes |
|
|
| Development | 0.40 | 0.7 | 0.6 | No |
|
|
|
|
---
|
|
|
|
## 6. Signal Update Events
|
|
|
|
The Determinization Gate subscribes to signal updates for automatic re-evaluation:
|
|
|
|
| Event Type | Description |
|
|
|------------|-------------|
|
|
| `epss.updated` | EPSS score changed |
|
|
| `vex.updated` | VEX statement added/modified |
|
|
| `reachability.updated` | Reachability analysis completed |
|
|
| `runtime.updated` | Runtime observation recorded |
|
|
| `backport.updated` | Backport detection result |
|
|
| `observation.state_changed` | Observation state transition |
|
|
|
|
---
|
|
|
|
## 7. Metrics
|
|
|
|
OpenTelemetry metrics for monitoring:
|
|
|
|
| Metric | Type | Description |
|
|
|--------|------|-------------|
|
|
| `stellaops_policy_determinization_evaluations_total` | Counter | Total evaluations by status/environment/rule |
|
|
| `stellaops_policy_determinization_rule_matches_total` | Counter | Rule matches by rule name/status/environment |
|
|
| `stellaops_policy_observation_state_transitions_total` | Counter | State transitions by from/to state/trigger |
|
|
| `stellaops_policy_determinization_entropy` | Histogram | Distribution of entropy scores |
|
|
| `stellaops_policy_determinization_trust_score` | Histogram | Distribution of trust scores |
|
|
| `stellaops_policy_determinization_evaluation_duration_ms` | Histogram | Evaluation latency |
|
|
|
|
---
|
|
|
|
## 8. Service Registration
|
|
|
|
Add determinization services via dependency injection:
|
|
|
|
```csharp
|
|
// Register all determinization services
|
|
services.AddDeterminizationEngine();
|
|
|
|
// Or as part of full Policy Engine registration
|
|
services.AddPolicyEngine(); // Includes determinization
|
|
```
|
|
|
|
---
|
|
|
|
## 9. 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
|
|
|
|
---
|
|
|
|
*Last updated: 2026-01-07 (Sprint 20260106_001_003)*
|