stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
6e687b523aa572c0850de61175d702ad3f7d9c24
git.stella-ops.org/docs/modules/scanner/design/change-trace-architecture.md
master 9873f80830 release orchestrator v1 draft and build fixes
2026-01-12 12:24:17 +02:00

362 lines
10 KiB
Markdown
Raw Blame History

# 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)
```csharp
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
```csharp
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
```csharp
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:
1. **Stable ordering**: Sort deltas by PURL, symbols by name, bytes by offset
2. **UTC timestamps**: Use `TimeProvider` for all timestamps
3. **Canonical JSON**: RFC 8785 compliant serialization
4. **No randomness**: Deterministic ID generation from content hashes
### Verification
```bash
# 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](../../implplan/SPRINT_20260112_200_000_INDEX_change_trace.md)
- [JSON Schema Contract](../../contracts/change-trace-schema.md)
- [Trust-Delta Contract](../../contracts/change-trace-trust-delta.md)
- [BinaryIndex Architecture](../../modules/binary-index/architecture.md)
- [VexLens Architecture](../../modules/vexlens/architecture.md)
---
*Document Version: 1.0.0*
*Last Updated: 2026-01-12*
Reference in New Issue View Git Blame Copy Permalink