stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
5593212b414864ab213082c8945a267451b99901
git.stella-ops.org/docs/features/checked/tools/golden-pairs-mirror-and-diff-pipeline.md

3.3 KiB
Raw Blame History

Golden Pairs Mirror and Diff Pipeline

Module

Tools

Status

VERIFIED

Description

Package mirror service to download pre/post-patch binary pairs from distro repos, and a diff pipeline service that runs section-hash diffing to produce golden diff reports for backport detection validation.

Implementation Details

  • Golden Pairs App: src/Tools/GoldenPairs/GoldenPairsApp.cs (320 lines) -- full CLI with mirror, diff, and validate sub-commands using System.CommandLine. Mirror downloads pre/post-patch binaries, diff runs section-hash comparison and writes JSON reports, validate iterates CVE directories and reports pass/fail summary.
  • Package Mirror Service: src/Tools/GoldenPairs/Services/PackageMirrorService.cs (286 lines) -- AptPackageMirrorService implementing IPackageMirrorService. Downloads from HTTP(S), apt:// (scheme-rewritten), and file:// URIs. Extracts files from .deb archives via SharpCompress (nested data.tar extraction). SHA-256 hash verification after download.
  • Diff Pipeline Service: src/Tools/GoldenPairs/Services/DiffPipelineService.cs (289 lines) -- section-by-section comparison (Identical/Modified/Added/Removed) using hash comparison. Verdict determination (Patched/Vanilla/Unknown) based on .text section changes with confidence scoring. Validation against expected diff.
  • Section Hash Provider: src/Tools/GoldenPairs/Services/SectionHashProvider.cs (87 lines) -- FileSectionHashProvider with LoadAsync (from JSON) and ExtractAsync (from binary via IElfSectionHashExtractor). Deterministically ordered SectionHashSet.
  • Golden Pair Loader: src/Tools/GoldenPairs/Services/GoldenPairLoader.cs (211 lines) -- loads metadata from JSON files with JSON Schema validation, deserialization, normalization, and error collection. Supports individual pair and index loading.
  • Golden Pairs Schema Provider: src/Tools/GoldenPairs/Schema/GoldenPairsSchemaProvider.cs (36 lines) -- lazy-loads metadata and index JSON schemas.
  • Models: src/Tools/GoldenPairs/Models/ (4 files, ~170 lines) -- GoldenPairMetadata, GoldenDiffReport, SectionHashModels, GoldenPairsIndex.
  • Serialization: src/Tools/GoldenPairs/Serialization/GoldenPairsJsonSerializer.cs (78 lines) -- deterministic property ordering via DeterministicTypeInfoResolver, camelCase naming, enum string conversion.

E2E Test Plan

  • Run PackageMirrorService to download a known CVE fix pair and verify both binaries are downloaded with correct metadata and SHA-256 verification
  • Run DiffPipelineService on a pair and verify the diff report identifies changed sections with correct verdict
  • Run SectionHashProvider on a known binary and verify section hashes are deterministic across multiple runs
  • Load a golden pair via GoldenPairLoader, re-run the diff pipeline, and verify the new diff report matches
  • Validate a diff report against the JSON schema and verify it passes validation
  • Verify hash mismatch detection in mirror service

Verification

  • Verified: 2026-02-10
  • Method: Tier 1 code review + Tier 2d test verification
  • Build: Passes (0 errors, 0 warnings)
  • Tests: 9 tests pass across 4 test files (DiffPipelineServiceTests: 2, GoldenPairLoaderTests: 2, PackageMirrorServiceTests: 2, GoldenPairSchemaTests: 3)