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:

{
  "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:

Enable Runtime Monitoring: Start observing the component for vulnerable code execution
Schedule Review: Set up periodic review at reviewInterval
EPSS Escalation: Auto-escalate if EPSS score exceeds epssEscalationThreshold
Reachability Escalation: Auto-escalate if reachability transitions to escalating states
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:

// Register all determinization services
services.AddDeterminizationEngine();

// Or as part of full Policy Engine registration
services.AddPolicyEngine();  // Includes determinization

Determinization Library - Core determinization models
Policy Engine Architecture - Overall policy engine design
Signal Snapshot Models - Signal data structures

Last updated: 2026-01-07 (Sprint 20260106_001_003)

6.6 KiB Raw Blame History