Change-Trace Architecture

Module: Scanner / ChangeTrace Version: 1.0.0 Status: Draft Last Updated: 2026-01-12

Overview

The Change-Trace feature provides deterministic comparison of binary artifacts across versions, producing a “trust-delta” view that explains what changed, why (backport, rebuild, upgrade), and what it means for security risk.

Strategic Value

Differentiating capability: Explains backports and security patches that competitors flag as “version mismatch”
Audit trail: Produces verifiable evidence for every version change decision
Reduced review time: Pre-computed deltas with proof steps eliminate manual investigation
Compliance support: Generates attestations suitable for regulatory frameworks

Architecture Diagram

                          +------------------+
                          |   CLI / API      |
                          |  (entry points)  |
                          +--------+---------+
                                   |
                    +-------------+v+-------------+
                    |      ChangeTraceBuilder     |
                    |  (orchestrates comparison)  |
                    +---+-----+-----+-----+------+
                        |     |     |     |
           +------------+     |     |     +------------+
           |                  |     |                  |
           v                  v     v                  v
   +-------+------+   +------+-----+------+   +-------+------+
   |  ScanResult  |   |  BinaryIndex      |   |  VexLens     |
   |   Loader     |   |  DeltaSigMatcher  |   |  Consensus   |
   +--------------+   +-------------------+   +--------------+
           |                  |                      |
           v                  v                      v
   +-------+------+   +------+-----+------+   +------+-------+
   | PackageDelta |   | SymbolDelta       |   | TrustDelta   |
   |  Generator   |   | + ByteDelta       |   | Calculator   |
   +--------------+   +-------------------+   +--------------+
           |                  |                      |
           +------------------+----------------------+
                              |
                    +---------v----------+
                    |    ChangeTrace     |
                    |   (output model)   |
                    +--------------------+
                              |
           +------------------+------------------+
           |                  |                  |
           v                  v                  v
   +-------+------+   +------+-----+------+  +--+-------------+
   | JSON Export  |   | DSSE Attestation  |  | CycloneDX      |
   | (standalone) |   | (signing)         |  | (embedded)     |
   +--------------+   +-------------------+  +----------------+

Data Flow

1. Input Stage

Scan1 (from)              Scan2 (to)
     |                         |
     v                         v
+----+----+               +----+----+
| SBOM    |               | SBOM    |
| Findings|               | Findings|
| Binary  |               | Binary  |
| Sigs    |               | Sigs    |
+---------+               +---------+

2. Comparison Stage

Package Comparison:
  - Match by PURL
  - Detect: Added, Removed, Upgraded, Downgraded, Patched, Rebuilt

Symbol Comparison (via BinaryIndex):
  - CFG hash matching
  - Instruction hash matching
  - Semantic hash matching
  - Chunk-level similarity

Byte Comparison (optional):
  - Rolling hash windows (2KB)
  - Per-section analysis
  - Delta identification

3. Trust Scoring Stage

For each PackageDelta:
  1. Get VEX consensus (from, to)
  2. Query reachability (from, to)
  3. Apply patch verification bonus
  4. Compute trust delta

Formula:
  TrustDelta = (AfterTrust - BeforeTrust) / max(BeforeTrust, 0.01)

4. Output Stage

ChangeTrace JSON
  -> Standalone export (.cdxchange.json)
  -> DSSE attestation (stella.ops/changetrace@v1)
  -> CycloneDX embedded (component-evidence extension)

Component Responsibilities

ChangeTraceBuilder

Location: src/Scanner/__Libraries/StellaOps.Scanner.ChangeTrace/

Orchestrates the comparison workflow:

Loads scan results
Coordinates package, symbol, and byte comparisons
Aggregates results into ChangeTrace model
Ensures deterministic output (stable ordering, UTC timestamps)

SymbolChangeTracer

Location: src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/

Performs binary-level comparison:

Compares SymbolSignature objects
Identifies change type (Added, Removed, Modified, Patched)
Computes similarity metrics
Generates human-readable explanations

TrustDeltaCalculator

Location: src/Scanner/__Libraries/StellaOps.Scanner.ChangeTrace/Scoring/

Computes risk impact:

Integrates with VexLens for consensus scores
Integrates with ReachGraph for reachability data
Applies patch verification bonus
Generates proof steps

ByteLevelDiffer

Location: src/Scanner/__Libraries/StellaOps.Scanner.ChangeTrace/ByteDiff/

Performs byte-level analysis:

Rolling hash window comparison
Section-aware diffing (ELF/PE/Mach-O)
Privacy-preserving output (hashes only)

Key Models

ChangeTrace (Root)

public sealed record ChangeTrace
{
    public const string SchemaVersion = "stella.change-trace/1.0";
    public string Schema { get; init; } = SchemaVersion;
    public required ChangeTraceSubject Subject { get; init; }
    public ImmutableArray<PackageDelta> Deltas { get; init; } = [];
    public required ChangeTraceSummary Summary { get; init; }
    public required DateTimeOffset AnalyzedAt { get; init; }
    public string AlgorithmVersion { get; init; } = "1.0";
}

PackageDelta

public sealed record PackageDelta
{
    public required string Purl { get; init; }
    public string? FromVersion { get; init; }
    public string? ToVersion { get; init; }
    public required ChangeType ChangeType { get; init; }
    public ImmutableArray<SymbolDelta> Symbols { get; init; } = [];
    public ImmutableArray<ByteDelta> Bytes { get; init; } = [];
    public required TrustDelta TrustDelta { get; init; }
}

TrustDelta

public sealed record TrustDelta
{
    public double Score { get; init; }  // [-1, +1]
    public double BeforeScore { get; init; }
    public double AfterScore { get; init; }
    public ReachabilityImpact ReachabilityImpact { get; init; }
    public ExploitabilityImpact ExploitabilityImpact { get; init; }
    public ImmutableArray<string> ProofSteps { get; init; } = [];
}

Trust-Delta Formula

Core Formula

TrustDelta = (AfterTrust - BeforeTrust) / max(BeforeTrust, 0.01)

Where:

BeforeTrust = VexConsensus(from) * ReachabilityFactor(from)
AfterTrust = VexConsensus(to) * ReachabilityFactor(to) + PatchBonus

Reachability Factor

ReachabilityFactor(callPaths) =
  - 1.0 if callPaths > 0 (reachable)
  - 0.7 if callPaths == 0 (unreachable, 30% reduction)
  - 1.0 if callPaths is null (unknown)

Patch Verification Bonus

PatchBonus =
  + (FunctionMatchWeight * PatchConfidence)      // 0.25 weight
  + (SectionMatchWeight * SymbolSimilarity)      // 0.15 weight
  + (AttestationWeight * IssuerAuthority)        // 0.10 weight (if DSSE present)

Verdict Mapping

Delta Range	Verdict
< -0.3	risk_down
-0.3 to +0.3	neutral
> +0.3	risk_up

Integration Points

VexLens Integration

IVexLensClient.GetConsensusAsync(purl, version): Get trust score
IVexLensClient.GetAdvisoryAsync(cveId): Get CVE details for proof steps

ReachGraph Integration

IReachGraphClient.GetReachabilityAsync(purl, version): Get call path count
Used for reachability impact calculation

BinaryIndex Integration

IDeltaSignatureMatcher.CompareSignaturesAsync(from, to): Symbol comparison
ISymbolChangeTracer.CompareSymbols(fromSymbol, toSymbol): Detailed symbol diff

Attestor Integration

IAttestationService.CreateChangeTraceAttestationAsync(trace): DSSE envelope
Predicate type: stella.ops/changetrace@v1

Determinism Requirements

All outputs must be reproducible:

Stable ordering: Sort deltas by PURL, symbols by name, bytes by offset
UTC timestamps: Use TimeProvider for all timestamps
Canonical JSON: RFC 8785 compliant serialization
No randomness: Deterministic ID generation from content hashes

Verification

# Two runs should produce identical output
stella change-trace build --from scan1 --to scan2 > trace1.json
stella change-trace build --from scan1 --to scan2 > trace2.json
diff trace1.json trace2.json  # Should be empty

Performance Targets

Metric	Target
Package comparison	< 100ms
Symbol comparison	< 100ms per binary
Byte-level diffing	< 500ms for binaries < 5MB
Full trace build	< 5s for typical container
Memory usage	< 500MB peak

Security Considerations

Privacy

Byte content is never included in output
Only hashes, offsets, and sizes are exported
Symbol names may be sensitive (review before external export)

Integrity

DSSE attestations provide tamper-evidence
Signature verification available via stella change-trace verify

Access Control

API endpoints require authentication
Traces inherit visibility from source scans

Future Enhancements

Phase 2

Function-level heatmap visualization
Side-by-side disassembly view
AI-assisted change explanation

Phase 3

Historical trend analysis
Anomaly detection for unexpected changes
Integration with SLSA provenance

References

Sprint INDEX
JSON Schema Contract
Trust-Delta Contract
BinaryIndex Architecture
VexLens Architecture

Implementation Status Note (2026-03-05)

The previously documented advisory-translation gaps are closed:

ChangeTraceBuilder no longer uses placeholder trace generation in production flow.
scan and binary traces now emit content-addressed subject digests (sha256:*) with deterministic ordering.
binary comparison paths use real file bytes/hashes for symbol/byte delta generation.
runtime trace ingestion now persists deterministic scan-to-trace indexes and returns deterministic trace lists for scan lookup.
Scanner WebService delta/actionables APIs are backed by deterministic delta payloads instead of static sample records.

Closure sprints:

docs/implplan/SPRINT_20260304_302_Scanner_trace_delta_and_actionables_completion.md
docs/implplan/SPRINT_20260304_303_Scanner_score_replay_contract_and_formula_alignment.md

Document Version: 1.0.0 Last Updated: 2026-03-05