audit work, fixed StellaOps.sln warnings/errors, fixed tests, sprints work, new advisories
This commit is contained in:
master
176
docs/modules/policy/determinization-api.md
Normal file
176
docs/modules/policy/determinization-api.md
Normal file
@@ -0,0 +1,176 @@
|
||||
# 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)*
|
||||
Reference in New Issue
Block a user