# 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.

### 4.1 Anchored Evidence Rules (v1.1)

> **Sprint:** SPRINT_20260112_004_BE_policy_determinization_attested_rules

Anchored evidence (DSSE-signed with optional Rekor transparency) takes highest priority in rule evaluation. These rules short-circuit evaluation when cryptographically attested evidence is present.

| Priority | Rule | Condition | Result |
|----------|------|-----------|--------|
| 1 | AnchoredAffectedWithRuntimeHardFail | Anchored VEX affected + anchored runtime telemetry confirms loading | **Blocked** (hard fail) |
| 2 | AnchoredVexNotAffectedAllow | Anchored VEX not_affected or fixed | Pass (short-circuit) |
| 3 | AnchoredBackportProofAllow | Anchored backport proof detected | Pass (short-circuit) |
| 4 | AnchoredUnreachableAllow | Anchored reachability shows unreachable | Pass (short-circuit) |

**Anchor Metadata Fields:**

Evidence anchoring is tracked via these fields on each evidence type:

```json
{
  "anchor": {
    "anchored": true,
    "envelope_digest": "sha256:abc123...",
    "predicate_type": "https://stellaops.io/vex/v1",
    "rekor_log_index": 12345678,
    "rekor_entry_id": "24296fb24b8ad77a...",
    "scope": "finding",
    "verified": true,
    "attested_at": "2026-01-14T12:00:00Z"
  }
}
```

Evidence types with anchor support:
- `VexClaimSummary` (via `VexClaimAnchor`)
- `BackportEvidence`
- `RuntimeEvidence`
- `ReachabilityEvidence`

### 4.2 Standard Rules

Standard rules apply when no anchored evidence short-circuits evaluation:

| 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)*