Files

master c70e83719e finish off sprint advisories and sprints

2026-01-24 00:12:43 +02:00

7.4 KiB

Raw Blame History

Unified Trust Score

Ownership: Signals Guild / Platform Guild Services: StellaOps.Signals.UnifiedScore API: POST /api/v1/score/evaluate, GET /api/v1/score/{id}/replay CLI: stella score compute|explain|replay|verify, stella gate score evaluate

Overview

The Unified Trust Score is a facade over existing EWS (Evidence-Weighted Score) and Determinization systems. It provides a single API for computing risk scores, uncertainty metrics, and score replay proofs without replacing any underlying scoring logic.

How It Works

Input — Caller provides signal values (reachability, runtime, exploit, etc.) and optional context (CVE ID, PURL, SBOM ref)
EWS computation — The facade delegates to IEvidenceWeightedScoreCalculator using weights from a versioned manifest
Entropy calculation — IUncertaintyScoreCalculator computes the unknowns fraction (U) from signal presence/absence
Conflict detection — IConflictDetector identifies contradictory signals
Delta calculation — For missing signals, computes potential score impact ranges
Result assembly — Returns UnifiedScoreResult combining all outputs

The Unknowns Fraction (U)

The UnknownsFraction exposes how much of the score depends on absent data:

U = 1 - (weighted_present_signals / total_weight)

Unknowns Bands

U Range	Band	Meaning	Recommended Action
0.0 – 0.2	Complete	All signals present	Automated decisions safe
0.2 – 0.4	Adequate	Sufficient signal coverage	Automated decisions safe
0.4 – 0.6	Sparse	Signal gaps exist	Manual review recommended
0.6 – 1.0	Insufficient	Critical data missing	Block until more signals arrive

Band thresholds align with Determinization configuration:

RefreshEntropyThreshold: 0.40 — triggers signal refresh attempt
ManualReviewEntropyThreshold: 0.60 — requires human review

Delta-If-Present

When signals are absent, the facade calculates how the score would change if each missing signal were provided:

{
  "signal": "reachability",
  "min_impact": -15,
  "max_impact": 8,
  "weight": 0.30,
  "description": "If reachability confirmed as not-reachable, score decreases by up to 15"
}

This helps operators prioritize which signals to gather first.

Weight Manifests

EWS weights are stored in versioned JSON files under etc/weights/:

etc/weights/v2026-01-22.weights.json

Manifests are:

Immutable once published
Content-addressed via SHA-256 hash
Pinnable by policy rules via weights_ref
Auditable — the manifest version and hash are included in every score result

See Scoring Algebra §4 for the manifest schema.

API Endpoints

Method	Path	Purpose
`POST`	`/api/v1/score/evaluate`	Compute unified score
`GET`	`/api/v1/score/{scoreId}`	Retrieve previously computed score
`GET`	`/api/v1/score/weights`	List weight manifest versions
`GET`	`/api/v1/score/weights/{version}`	Get specific manifest
`GET`	`/api/v1/score/weights/effective`	Get effective manifest for a date
`GET`	`/api/v1/score/{scoreId}/replay`	Fetch signed replay proof
`POST`	`/api/v1/score/verify`	Verify a replay log

Evaluate Request

{
  "cve_id": "CVE-2024-1234",
  "purl": "pkg:npm/lodash@4.17.0",
  "signals": {
    "reachability": 0.9,
    "runtime": 0.7,
    "exploit": 0.3,
    "backport": 0.0,
    "source": 0.5,
    "mitigation": 0.0
  },
  "options": {
    "include_breakdown": true,
    "include_delta": true,
    "weight_set_id": "v2026-01-22"
  }
}

Evaluate Response (key fields)

{
  "score_id": "score_a1b2c3d4e5f67890",
  "score_value": 72,
  "bucket": "ScheduleNext",
  "unknowns_fraction": 0.15,
  "unknowns_band": "Complete",
  "weight_manifest": {
    "version": "v2026-01-22",
    "content_hash": "sha256:..."
  },
  "ews_digest": "sha256:...",
  "determinization_fingerprint": "sha256:...",
  "computed_at": "2026-01-23T10:00:00Z"
}

CLI Commands

`stella score compute`

Compute a unified score from signal values:

stella score compute \
  --finding-id CVE-2024-1234@pkg:npm/lodash@4.17.0 \
  --cvss 7.5 --epss 0.15 \
  --reachability 0.9 --runtime 0.7 \
  --format table

`stella score explain`

Show a detailed breakdown of a score:

stella score explain CVE-2024-1234@pkg:npm/lodash@4.17.0

`stella score replay`

Fetch the signed replay proof for a previously computed score:

stella score replay score_a1b2c3d4e5f67890

`stella score verify`

Re-execute the computation and verify it matches the original:

stella score verify score_a1b2c3d4e5f67890

`stella gate score evaluate` (enhanced)

Existing gate command with new flags:

stella gate score evaluate \
  --finding-id CVE-2024-1234@pkg:npm/lodash \
  --cvss 7.5 --epss 0.15 \
  --show-unknowns --show-deltas \
  --weights-version v2026-01-22

`stella gate score weights`

Manage weight manifests:

stella gate score weights list
stella gate score weights show v2026-01-22
stella gate score weights diff v2026-01-22 v2026-02-01

Score Replay and Verification

Every computed score can produce a replay proof — a DSSE-signed attestation (payload type application/vnd.stella.score+json) that records:

Canonical input hashes (SBOM, VEX, etc.)
Transform versions applied (canonicalization, normalization, decay)
Step-by-step algebra decisions (signal × weight = contribution)
Final score and metadata

Replay proofs enable:

Independent verification — auditors re-execute the computation
Transparency logging — optional anchoring to Rekor for non-repudiation
OCI storage — proofs stored as OCI referrers ("StellaBundle" pattern)

Troubleshooting

High Unknowns Fraction (U > 0.6)

Symptom: Score shows "Insufficient" band, decisions are blocked.

Causes:

Missing reachability analysis (run stella scan with --reachability)
No VEX data available (check VEX feed configuration)
Runtime observations not collected (configure runtime agent)

Resolution:

Run stella score explain <finding-id> to see which signals are missing
Use --show-deltas to understand which signals would have the most impact
Prioritize gathering signals with the highest weight × delta

Score Disagrees with CVSS

Symptom: EWS score is much lower than expected from CVSS alone.

Explanation: EWS incorporates reachability, runtime, backport, and mitigation signals that CVSS does not. A high-CVSS vulnerability that is not reachable or already mitigated will have a lower EWS score.

Resolution: Run stella score explain to see the per-dimension breakdown and understand which signals are reducing the score.

Replay Verification Fails

Symptom: stella score verify reports score_matches: false.