stella-ops.org/git.stella-ops.org

Fork 0

Files

master 4903395618 sprints work.

2026-01-20 00:45:38 +02:00

4.1 KiB

Raw Blame History

DeltaSig v2 Predicate Schema

Sprint: SPRINT_20260119_004_BinaryIndex_deltasig_extensions
Status: Implemented

Overview

DeltaSig v2 extends the function-level binary diff predicate with:

Symbol Provenance: Links function matches to ground-truth corpus sources (debuginfod, ddeb, buildinfo, secdb)
IR Diff References: CAS-stored intermediate representation diffs for detailed analysis
Explicit Verdicts: Clear vulnerability status with confidence scores
Function Match States: Per-function vulnerable/patched/modified/unchanged classification

Schema

Predicate Type URI: https://stella-ops.org/predicates/deltasig/v2

Key Fields

Field	Type	Description
`schemaVersion`	string	Always `"2.0.0"`
`subject`	object	Single subject (PURL, digest, arch)
`functionMatches`	array	Function-level matches with evidence
`verdict`	string	`vulnerable`, `patched`, `partial`, `unknown`, `partially_patched`, `inconclusive`
`confidence`	number	0.0-1.0 confidence score
`summary`	object	Aggregate statistics

Function Match

{
  "functionId": "sha256:abc123...",
  "name": "ssl_handshake",
  "address": 4194304,
  "size": 256,
  "matchScore": 0.95,
  "matchMethod": "semantic_ksg",
  "matchState": "patched",
  "symbolProvenance": {
    "sourceId": "fedora-debuginfod",
    "observationId": "obs:gt:12345",
    "confidence": 0.98,
    "resolvedAt": "2026-01-19T12:00:00Z"
  },
  "irDiff": {
    "casDigest": "sha256:def456...",
    "statementsAdded": 5,
    "statementsRemoved": 3,
    "changedInstructions": 8
  }
}

Summary

{
  "totalFunctions": 150,
  "vulnerableFunctions": 0,
  "patchedFunctions": 12,
  "unknownFunctions": 138,
  "functionsWithProvenance": 45,
  "functionsWithIrDiff": 12,
  "avgMatchScore": 0.85,
  "minMatchScore": 0.42,
  "maxMatchScore": 0.99,
  "totalIrDiffSize": 1234
}

Version Negotiation

Clients can request specific predicate versions:

{
  "preferredVersion": "2",
  "requiredFeatures": ["provenance", "ir-diff"]
}

Response:

{
  "version": "2.0.0",
  "predicateType": "https://stella-ops.org/predicates/deltasig/v2",
  "features": ["provenance", "ir-diff"]
}

VEX Integration

DeltaSig v2 predicates can be converted to VEX observations via IDeltaSigVexBridge:

DeltaSig Verdict	VEX Status
`patched`	`fixed`
`vulnerable`	`affected`
`partially_patched`	`under_investigation`
`inconclusive`	`under_investigation`
`unknown`	`not_affected` (conservative)

Evidence Blocks

VEX observations include evidence blocks:

deltasig-summary: Aggregate statistics
deltasig-function-matches: High-confidence matches with provenance
deltasig-predicate-ref: Reference to full predicate

Implementation

Core Services

Interface	Implementation	Description
`IDeltaSigServiceV2`	`DeltaSigServiceV2`	V2 predicate generation
`ISymbolProvenanceResolver`	`GroundTruthProvenanceResolver`	Ground-truth lookup
`IIrDiffGenerator`	`IrDiffGenerator`	IR diff generation with CAS
`IDeltaSigVexBridge`	`DeltaSigVexBridge`	VEX observation generation

DI Registration

services.AddDeltaSigV2();

Or with options:

services.AddDeltaSigV2(
    configureProvenance: opts => opts.IncludeStale = false,
    configureIrDiff: opts => opts.MaxParallelism = 4
);

Migration from v1

Use DeltaSigPredicateConverter:

// v1 → v2
var v2 = DeltaSigPredicateConverter.ToV2(v1Predicate);

// v2 → v1
var v1 = DeltaSigPredicateConverter.ToV1(v2Predicate);

Notes:

v1 → v2: Provenance and IR diff will be empty (add via resolver/generator)
v2 → v1: Provenance and IR diff are discarded; verdict/confidence are lost

JSON Schema

Full schema: docs/schemas/predicates/deltasig-v2.schema.json

4.1 KiB Raw Blame History