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

2. PolicyVerdictStatus

Policy evaluations return a PolicyVerdictStatus indicating the outcome:

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:

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.

Anchor Metadata Fields:

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

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

5. Environment Thresholds

Thresholds vary by deployment environment:

6. Signal Update Events

The Determinization Gate subscribes to signal updates for automatic re-evaluation:

7. Metrics

OpenTelemetry metrics for monitoring:

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

9. Related Documentation

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

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:

10.2 Reanalysis Fingerprint

Each unknown is assigned a deterministic fingerprint enabling reproducible replays:

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

10.4 Trigger Events for Reanalysis

The Grey Queue tracks triggers that caused reanalysis:

10.5 Next Actions

Each unknown suggests next actions for resolution:

11. Related Documentation

• Determinization Library - Core determinization models
• Policy Engine Architecture - Overall policy engine design
• Signal Snapshot Models - Signal data structures
• VEX Consensus Guide - 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

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

12.3 Conflict Handling Actions

12.4 Environment Threshold Presets

12.5 Configuration API

12.6 Configuration Binding

In appsettings.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

13. Delta-If-Present Calculations (TSF-004)

Sprint: SPRINT_20260208_043_Policy_delta_if_present_calculations_for_missing_signals

The Delta-If-Present API provides “what-if” analysis for missing signals, showing hypothetical score changes if specific evidence were obtained.

13.1 Purpose

When making release decisions with incomplete evidence, operators need to understand:

• Gap prioritization: Which missing signals would have the most impact?
• Score bounds: What is the possible range of trust scores given current gaps?
• Risk simulation: What would the score be if a missing signal had a specific value?

13.2 API Endpoints

13.3 Single Signal Delta

Calculate hypothetical score change for one missing signal:

Request:

{
  "snapshot": {
    "cve": "CVE-2024-1234",
    "purl": "pkg:maven/org.example/lib@1.0.0",
    "vex": { "state": "not_queried" },
    "epss": { "state": "not_queried" },
    "reachability": {
      "state": "queried",
      "value": { "status": "Reachable", "analyzed_at": "2026-01-15T00:00:00Z" }
    },
    "runtime": { "state": "not_queried" },
    "backport": { "state": "not_queried" },
    "sbom": {
      "state": "queried",
      "value": { "sbom_digest": "sha256:abc", "format": "SPDX" }
    }
  },
  "signal_name": "VEX",
  "assumed_value": 0.0
}

Response:

{
  "signal": "VEX",
  "current_score": 0.65,
  "hypothetical_score": 0.52,
  "score_delta": -0.13,
  "assumed_value": 0.0,
  "signal_weight": 0.25,
  "current_entropy": 0.60,
  "hypothetical_entropy": 0.35,
  "entropy_delta": -0.25
}

13.4 Full Gap Analysis

Analyze all missing signals with best/worst/prior cases:

Response:

{
  "cve": "CVE-2024-1234",
  "purl": "pkg:maven/org.example/lib@1.0.0",
  "current_score": 0.65,
  "current_entropy": 0.60,
  "gap_analysis": [
    {
      "signal": "VEX",
      "gap_reason": "NotQueried",
      "best_case": {
        "assumed_value": 0.0,
        "hypothetical_score": 0.52,
        "score_delta": -0.13
      },
      "worst_case": {
        "assumed_value": 1.0,
        "hypothetical_score": 0.77,
        "score_delta": 0.12
      },
      "prior_case": {
        "assumed_value": 0.5,
        "hypothetical_score": 0.64,
        "score_delta": -0.01
      },
      "max_impact": 0.25
    }
  ],
  "prioritized_gaps": ["VEX", "Reachability", "EPSS", "Runtime", "Backport", "SBOMLineage"],
  "computed_at": "2026-01-15T12:00:00Z"
}

13.5 Score Bounds

Calculate the possible range of trust scores:

Response:

{
  "cve": "CVE-2024-1234",
  "purl": "pkg:maven/org.example/lib@1.0.0",
  "current_score": 0.65,
  "current_entropy": 0.60,
  "minimum_score": 0.35,
  "maximum_score": 0.85,
  "range": 0.50,
  "gap_count": 4,
  "missing_weight_percentage": 65.0,
  "computed_at": "2026-01-15T12:00:00Z"
}

13.6 Signal Weights

Default signal weights used in delta calculations:

Custom weights can be passed in requests to override defaults.

13.7 Use Cases

1. Evidence Prioritization: Determine which signals to acquire first based on maximum impact
2. Risk Bounding: Understand worst-case score before making release decisions
3. Sensitivity Analysis: Explore how different evidence values would affect outcomes
4. Operator Guidance: Help operators focus collection efforts on high-impact signals
5. Audit Trail: Document “what-if” analysis as part of release decision rationale