stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
main
git.stella-ops.org/docs/features/unimplemented/binaryindex/symbol-change-tracking-in-binary-diffs.md
master 5bca406787 save checkpoint: save features
2026-02-12 10:27:23 +02:00

3.0 KiB
Raw Permalink Blame History

Symbol Change Tracking in Binary Diffs (SymbolChangeTracer)

Module

BinaryIndex

Status

PARTIALLY_IMPLEMENTED

Description

Extends BinaryIndex DeltaSignature module to track which specific symbols changed between binary versions (not just whether they match). Adds change metadata to SymbolMatchResult and provides detailed CFG hash and instruction hash comparison for symbol-level binary change forensics.

Implementation Details

  • Modules: src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/
  • Key Classes:
    • SymbolChangeTracer (src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/SymbolChangeTracer.cs) - traces symbol-level changes between binary versions with detailed CFG hash and instruction hash comparison
    • DeltaSignatureGenerator (src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/DeltaSignatureGenerator.cs) - generates delta signatures capturing symbol change metadata
    • DeltaSignatureMatcher (src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/DeltaSignatureMatcher.cs) - matches signatures with change tracking awareness
    • CfgExtractor (src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/Cfg/CfgExtractor.cs) - extracts CFG for hash comparison
    • IrDiffGenerator (src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/IrDiff/IrDiffGenerator.cs) - generates IR-level diffs for detailed change analysis
  • Interfaces: ISymbolChangeTracer (src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/ISymbolChangeTracer.cs)
  • Models: SymbolMatchResult with change metadata in Models.cs
  • Source: SPRINT_20260112_200_003_BINDEX_symbol_tracking.md

E2E Test Plan

  • Compare two binary versions with known symbol changes and verify SymbolChangeTracer identifies which symbols changed
  • Verify CFG hash comparison detects control flow changes in modified functions
  • Verify instruction hash comparison detects instruction-level changes
  • Verify SymbolMatchResult includes change metadata (added, removed, modified symbols)
  • Verify IR-level diff captures semantic changes beyond byte-level differences
  • Verify unchanged symbols are correctly identified as stable between versions

Verification Outcome (run-001)

  • Tier 0/1/2 artifacts: docs/qa/feature-checks/runs/binaryindex/symbol-change-tracking-in-binary-diffs/run-001/
  • Result: not implemented at full claim parity.
  • Verified behavior:
    • SymbolChangeTracer and related tests cover added/removed/modified/unchanged classification, patched heuristics, and chunk-index metadata.
    • SymbolMatchResult metadata fields are populated and exercised by the DeltaSig test suite.
  • Missing behavior:
    • IrDiffGenerator remains placeholder-backed (In a real implementation path with zeroed diff summary and placeholder digest), so the dossier's semantic IR-diff-forensics claim is not fully implemented.
    • No dedicated IrDiffGenerator behavioral tests were found in StellaOps.BinaryIndex.DeltaSig.Tests, so IR-level diff semantics are not verified by tests.