Files

master 4ca3ce8fb4 sprints completion. new product advisories prepared

2026-01-16 16:30:03 +02:00

16 KiB

Raw Blame History

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.

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:

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

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

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:

Policy Verdict	Observation State	OpenVEX Mapping	Description
`GuardedPass`	`PendingDeterminization`	`under_investigation`	Allowed with guardrails; monitoring required
`Deferred`	`PendingDeterminization`	`under_investigation`	Decision deferred; needs additional evidence
`Escalated` (conflict)	`Disputed`	`under_investigation`	Conflicting evidence; manual adjudication required

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:

Conflict Type	Detection	Adjudication Path
`VexReachabilityContradiction`	VEX not_affected + confirmed reachable	Manual review
`StaticRuntimeContradiction`	Static unreachable + runtime execution	Auto-escalate
`VexStatusConflict`	Multiple providers with conflicting status	Trust-weighted resolution or manual
`BackportStatusConflict`	Backport claimed + affected status	Manual review
`EpssRiskContradiction`	Low EPSS + KEV or high exploitation	Auto-escalate

10.4 Trigger Events for Reanalysis

The Grey Queue tracks triggers that caused reanalysis:

Event Type	Version	Delta Threshold	Description
`epss.updated`	1	0.1	EPSS score changed significantly
`vex.updated`	1	N/A	VEX statement added/modified
`reachability.updated`	1	N/A	Reachability analysis completed
`runtime.updated`	1	N/A	Runtime observation recorded
`sbom.updated`	1	N/A	SBOM content changed
`dsse_validation.changed`	1	N/A	DSSE validation status changed
`rekor_entry.added`	1	N/A	New Rekor transparency entry

10.5 Next Actions

Each unknown suggests next actions for resolution:

Action	Description
`await_vex`	Wait for vendor VEX statement
`run_reachability`	Execute reachability analysis
`enable_runtime`	Deploy runtime telemetry
`verify_backport`	Confirm backport availability
`manual_review`	Escalate to security team
`trust_resolution`	Resolve issuer trust conflict

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

Trigger	Default	Description
`epssDeltaThreshold`	0.2	Minimum EPSS delta to trigger reanalysis
`triggerOnThresholdCrossing`	true	Trigger when EPSS crosses a bucket threshold
`triggerOnRekorEntry`	true	Trigger on new Rekor transparency entry
`triggerOnVexStatusChange`	true	Trigger when VEX status changes
`triggerOnRuntimeTelemetryChange`	true	Trigger on runtime exploit/reachability signals
`triggerOnPatchProofAdded`	true	Trigger when binary patch proof is added
`triggerOnDsseValidationChange`	true	Trigger when DSSE validation state changes
`triggerOnToolVersionChange`	false	Trigger on tool version updates (disabled by default)

12.3 Conflict Handling Actions

Action	Description
`AutoResolve`	System resolves using trust scores
`RequireManualReview`	Route to Grey Queue for operator review
`RequestVendorClarification`	Queue for vendor outreach
`Escalate`	Escalate to security team
`Block`	Block until conflict is resolved

12.4 Environment Threshold Presets

Preset	MinConfidence	MaxEntropy	EPSS Threshold
Relaxed (dev)	0.40	0.7	0.6
Standard (staging)	0.60	0.5	0.4
Strict (production)	0.75	0.3	0.3

12.5 Configuration API

Endpoint	Method	Description
`/api/v1/policy/config/determinization`	GET	Get effective config for tenant
`/api/v1/policy/config/determinization/defaults`	GET	Get system defaults
`/api/v1/policy/config/determinization/audit`	GET	Get configuration change history
`/api/v1/policy/config/determinization`	PUT	Update config (policy-admin required)
`/api/v1/policy/config/determinization/validate`	POST	Validate config without saving

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

16 KiB Raw Blame History