stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

save checkpoint: save features

Browse Source
This commit is contained in:
master
2026-02-12 10:27:23 +02:00
parent dca86e1248
commit 5bca406787
8837 changed files with 1796879 additions and 5294 deletions
Download Patch File Download Diff File Expand all files Collapse all files

35
docs/features/checked/binaryindex/binary-symbol-table-diff-engine.md Normal file
View File

@@ -0,0 +1,35 @@
# Binary Symbol Table Diff Engine
## Module
BinaryIndex
## Status
VERIFIED
## Description
Symbol table comparison between binary versions tracking exported/imported symbol changes, version map diffs, GOT/PLT table modifications, and ABI compatibility assessment. Produces content-addressed diff IDs for deterministic reporting.
## Implementation Details
- **Modules**: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Builders/SymbolDiff/`
- **Key Classes**:
- `SymbolTableDiffAnalyzer` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Builders/SymbolDiff/SymbolTableDiffAnalyzer.cs`) - computes diffs between symbol tables with `ComputeDiffAsync` and `AssessAbiCompatibility`
- `SymbolTableDiff` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Builders/SymbolDiff/SymbolTableDiff.cs`) - diff result model with added/removed/changed symbols
- `VersionMapDiff` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Builders/SymbolDiff/VersionMapDiff.cs`) - tracks changes in ELF version maps
- `AbiCompatibility` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Builders/SymbolDiff/AbiCompatibility.cs`) - ABI compatibility assessment (FullyCompatible, Warnings, Incompatible)
- `DynamicLinkingDiff` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Builders/SymbolDiff/DynamicLinkingDiff.cs`) - GOT/PLT table modification tracking
- `NameDemangler` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Builders/SymbolDiff/NameDemangler.cs`) - C++ symbol name demangling
- **Interfaces**: `ISymbolTableDiffAnalyzer` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Builders/SymbolDiff/ISymbolTableDiffAnalyzer.cs`)
- **Registration**: `SymbolDiffServiceExtensions` for DI setup
## E2E Test Plan
- [ ] Compute diff between two ELF binaries with known symbol changes and verify added/removed symbols are correctly identified
- [ ] Verify `AssessAbiCompatibility` returns `FullyCompatible` when only symbols are added
- [ ] Verify `AssessAbiCompatibility` returns `Incompatible` when exported symbols are removed
- [ ] Verify version map diff detection for ELF version script changes
- [ ] Verify C++ symbol demangling produces human-readable names via `NameDemangler`
- [ ] Verify content-addressed diff IDs are deterministic for identical inputs
## Verification
- Verified by QA FLOW run `run-001` on 2026-02-11.
- Evidence: `docs/qa/feature-checks/runs/binaryindex/binary-symbol-table-diff-engine/run-001/` (Tier 0/1/2 artifacts).

32
docs/features/checked/binaryindex/binary-to-vex-claim-auto-generation.md Normal file
View File

@@ -0,0 +1,32 @@
# Binary-to-VEX Claim Auto-Generation (VexBridge Library)
## Module
BinaryIndex
## Status
VERIFIED
## Description
Automated generation of VEX claims from binary fingerprint match results. The VexBridge library translates binary match evidence into DSSE-signed VEX statements with confidence scores, enabling automated VEX claim production from binary analysis without manual triage.
## Implementation Details
- **Modules**: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.VexBridge/`
- **Key Classes**:
- `VexEvidenceGenerator` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.VexBridge/VexEvidenceGenerator.cs`) - generates VEX observations from `BinaryVulnMatch` results; maps `FixState` to `VexClaimStatus` (Fixed -> NotAffected, Vulnerable -> Affected, Unknown -> UnderInvestigation)
- `BinaryMatchEvidenceSchema` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.VexBridge/BinaryMatchEvidenceSchema.cs`) - defines evidence schema with match type constants (BuildId, DeltaSignature, etc.)
- `VexBridgeOptions` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.VexBridge/VexBridgeOptions.cs`) - configuration for confidence thresholds
- `DeltaSigVexBridge` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/VexIntegration/DeltaSigVexBridge.cs`) - bridges delta-signature analysis results into VEX observations with provenance data
- **Interfaces**: `IVexEvidenceGenerator` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.VexBridge/IVexEvidenceGenerator.cs`), `IDeltaSigVexBridge`
## E2E Test Plan
- [ ] Generate a VEX claim from a `Fixed` binary match and verify status is `NotAffected` with justification `VulnerableCodeNotPresent`
- [ ] Generate a VEX claim from a `Vulnerable` match and verify status is `Affected`
- [ ] Generate a VEX claim from an `Unknown` match and verify status is `UnderInvestigation`
- [ ] Verify confidence threshold enforcement: low-confidence matches below threshold are rejected
- [ ] Verify Build-ID references are included in VEX evidence when present
- [ ] Verify `DeltaSigVexBridge` produces VEX observations with symbol provenance metadata
- [ ] Verify generated VEX statements include correct DSSE evidence references
## Verification
- Verified by QA FLOW run `run-001` on 2026-02-11.
- Evidence: `docs/qa/feature-checks/runs/binaryindex/binary-to-vex-claim-auto-generation/run-001/` (Tier 0/1/2 artifacts).

27
docs/features/checked/binaryindex/binaryindex-ops-cli-commands.md Normal file
View File

@@ -0,0 +1,27 @@
# BinaryIndex Ops CLI Commands (stella binary ops)
## Module
BinaryIndex
## Status
IMPLEMENTED
## Description
CLI commands for BinaryIndex ops: health, bench, cache, config subcommands with JSON/table output and BinaryIndex base URL configuration. Also adds --semantic flag to deltasig extract/author/match commands.
## Implementation Details
- **Modules**: `src/BinaryIndex/StellaOps.BinaryIndex.WebService/Controllers/`, `src/Cli/`
- **Key Classes**:
- `BinaryIndexOpsController` (`src/BinaryIndex/StellaOps.BinaryIndex.WebService/Controllers/BinaryIndexOpsController.cs`) - serves health, bench, cache stats, and config endpoints consumed by CLI
- `BinaryIndexOpsHealthResponse` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/Configuration/BinaryIndexOpsModels.cs`) - health response model with lifter warmness, component versions
- `BinaryIndexOpsOptions` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/Configuration/BinaryIndexOpsModels.cs`) - ops configuration with redacted keys and bench rate limits
- `B2R2LifterPool` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Disassembly.B2R2/B2R2LifterPool.cs`) - lifter pool stats reported via ops health endpoint
- **Source**: SPRINT_20260112_006_CLI_binaryindex_ops_cli.md
## E2E Test Plan
- [ ] Run `stella binary ops health` and verify JSON output includes lifter warmness and version info
- [ ] Run `stella binary ops bench` and verify latency measurement results are returned
- [ ] Run `stella binary ops cache` and verify Valkey hit/miss statistics are reported
- [ ] Run `stella binary ops config` and verify effective configuration is returned with secrets redacted
- [ ] Run `stella deltasig extract --semantic` and verify semantic flag is passed through
- [ ] Verify table output format renders correctly for all subcommands

32
docs/features/checked/binaryindex/binaryindex-ops-endpoints.md Normal file
View File

@@ -0,0 +1,32 @@
# BinaryIndex Ops Endpoints (Health, Bench, Cache Stats, Config)
## Module
BinaryIndex
## Status
VERIFIED
## Description
Ops endpoints for BinaryIndex: health (lifter warmness), bench/run (latency measurement), cache stats (Valkey hit/miss), and effective config with deterministic JSON responses.
## Implementation Details
- **Modules**: `src/BinaryIndex/StellaOps.BinaryIndex.WebService/`
- **Key Classes**:
- `BinaryIndexOpsController` (`src/BinaryIndex/StellaOps.BinaryIndex.WebService/Controllers/BinaryIndexOpsController.cs`) - exposes `GET /api/v1/ops/binaryindex/health`, bench, cache stats, and config endpoints; integrates with `B2R2LifterPool` and `FunctionIrCacheService`
- `B2R2LifterPool` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Disassembly.B2R2/B2R2LifterPool.cs`) - provides pool stats (warm ISAs, pool sizes, acquire timeouts)
- `FunctionIrCacheService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Cache/FunctionIrCacheService.cs`) - Valkey-based function IR cache with hit/miss reporting
- `B2R2LifterPoolOptions` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Disassembly.B2R2/B2R2LifterPoolOptions.cs`) - pool configuration (MaxPoolSizePerIsa, EnableWarmPreload, AcquireTimeout)
- `BinaryIndexOptions` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/Configuration/BinaryIndexOptions.cs`) - top-level options with B2R2Pool, SemanticLifting sections
- `InMemoryBinaryVulnerabilityService` (`src/BinaryIndex/StellaOps.BinaryIndex.WebService/Services/InMemoryBinaryVulnerabilityService.cs`) - deterministic fallback DI implementation used to keep ops/resolution startup healthy in local/offline mode
- **Source**: SPRINT_20260112_004_BINIDX_b2r2_lowuir_perf_cache.md
## E2E Test Plan
- [x] Call `GET /api/v1/ops/binaryindex/health` and verify response includes lifter pool/cache readiness fields
- [x] Call `POST /api/v1/ops/binaryindex/bench/run` and verify deterministic latency measurement JSON
- [x] Call `GET /api/v1/ops/binaryindex/cache` and verify hit/miss counts and cache key metadata
- [x] Call `GET /api/v1/ops/binaryindex/config` and verify effective configuration is returned with secrets redacted
- [x] Verify negative path for bench input validation (`iterations=0` returns `400`)
## Verification
- Verified on 2026-02-11 via `run-002`.
- Artifacts: `docs/qa/feature-checks/runs/binaryindex/binaryindex-ops-endpoints/run-002/`

47
docs/features/checked/binaryindex/cross-distro-golden-set-for-backport-validation.md Normal file
View File

@@ -0,0 +1,47 @@
# Cross-Distro Golden Set for Backport Validation
## Module
BinaryIndex
## Status
VERIFIED
## Description
Golden set infrastructure exists in BinaryIndex with analysis pipeline and API. The advisory's detailed curated test cases (OpenSSL Heartbleed, sudo Baron Samedit, etc.) and specific database schema may not be fully populated yet.
## What's Implemented
- **Golden Set Infrastructure**: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.GoldenSet/` - full authoring, validation, storage, serialization
- `GoldenSetExtractor`, `NvdGoldenSetExtractor` - extraction from NVD data
- `GoldenSetEnrichmentService` - enriches golden sets with function hints
- `GoldenSetValidator`, `ICveValidator` - validation pipeline
- `PostgresGoldenSetStore` - PostgreSQL storage
- `GoldenSetYamlSerializer` - YAML serialization
- **Analysis Pipeline**: `GoldenSetAnalysisPipeline` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Analysis/`) - runs analysis against golden set definitions
- **API Controller**: `GoldenSetController` (`src/BinaryIndex/StellaOps.BinaryIndex.WebService/Controllers/`) - CRUD and listing endpoints
- **Corpus Connectors**: Alpine (`AlpineCorpusConnector`), Debian (`DebianCorpusConnector`), RPM (`RpmCorpusConnector`) for cross-distro support
- **Validation Harness**: `ValidationHarness` and `ValidationHarnessService` for running golden set tests
## What's Missing
- Curated cross-distro test cases for high-impact CVEs (OpenSSL Heartbleed CVE-2014-0160, sudo Baron Samedit CVE-2021-3156, etc.) may not be fully populated in the golden set database
- Cross-distro coverage matrix (Alpine vs Debian vs RHEL backport variations for same CVE) may need population
- Automated golden set population pipeline from NVD for new CVEs
## Implementation Plan
- Populate golden set database with curated cross-distro test cases for high-impact CVEs
- Validate backport detection accuracy across Alpine, Debian, and RHEL for each curated CVE
- Build automated pipeline to generate cross-distro golden set entries from NVD advisories
- Add cross-distro regression test suite using existing `ValidationHarness` infrastructure
## Related Documentation
- Golden set schema: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.GoldenSet/Models/GoldenSetDefinition.cs`
- Authoring workflow: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.GoldenSet/Authoring/`
## Verification
- Tier 0/1/2 artifacts: `docs/qa/feature-checks/runs/binaryindex/cross-distro-golden-set-for-backport-validation/run-001/`.
- Result: verified.
- Tier 1/Tier 2 initially hit a deterministic test compilation issue (`CS0117`) in cross-distro coverage tests; run-001 includes triage, fix, and retest artifacts.
- Final verification evidence:
- `tier1-test-goldenset-retest.log` passed (`261/261`).
- `tier2-test-goldenset.log` passed (`261/261`).
- `tier2-test-analysis.log` passed (`102/102`).

40
docs/features/checked/binaryindex/delta-signature-predicates.md Normal file
View File

@@ -0,0 +1,40 @@
# Delta-Signature Predicates (Function-Level Binary Diffs)
## Module
BinaryIndex
## Status
VERIFIED
## Description
Function-level delta signature predicates (v1 and v2) with signature generation, matching, and symbol change tracing. V2 adds symbol provenance and IR diffs, which is architecturally superior to the byte-level hunks proposed in the advisory.
## Implementation Details
- **Modules**: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/`
- **Key Classes**:
- `DeltaSigPredicate` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/Attestation/DeltaSigPredicate.cs`) - V1 predicate for attestation
- `DeltaSigPredicateV2` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/Attestation/DeltaSigPredicateV2.cs`) - V2 predicate with symbol provenance and IR diff support
- `DeltaSigPredicateConverter` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/Attestation/DeltaSigPredicateConverter.cs`) - converts between predicate versions
- `DeltaSigAttestorIntegration` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/Attestation/DeltaSigAttestorIntegration.cs`) - integrates delta-sig predicates with the Attestor module
- `GroundTruthProvenanceResolver` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/Provenance/GroundTruthProvenanceResolver.cs`) - enriches matches with symbol provenance data
- `CfgExtractor` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/CfgExtractor.cs`) - extracts control flow graphs for delta-sig generation
- **Models**: `Models.cs` in DeltaSig namespace - function match records, signature models
- **VEX Integration**: `DeltaSigVexBridge` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/VexIntegration/`)
## E2E Test Plan
- [ ] Generate a V1 delta-sig predicate and verify it contains function-level diff data
- [ ] Generate a V2 delta-sig predicate and verify it includes symbol provenance and IR diff metadata
- [ ] Convert between V1 and V2 predicates via `DeltaSigPredicateConverter` and verify data fidelity
- [ ] Verify `DeltaSigAttestorIntegration` produces valid attestation predicates for the Attestor module
- [ ] Verify `GroundTruthProvenanceResolver` enriches function matches with provenance sources
- [ ] Verify V2 predicates flow into VEX observations via `DeltaSigVexBridge`
## Verification
- Tier 0/1/2 artifacts: `docs/qa/feature-checks/runs/binaryindex/delta-signature-predicates/run-001/`.
- Result: verified.
- Evidence summary:
- `tier1-test-deltasig.log`: Passed 132/132.
- `tier1-test-vexbridge.log`: Passed 29/29.
- `tier2-test-deltasig.log`: Passed 132/132.
- `tier2-test-vexbridge.log`: Passed 29/29.
- Note: feature dossier key-class naming references `DeltaSigAttestorIntegration`; implementation currently exposes attestation integration behavior through `IDeltaSigAttestorService` and `DeltaSigEnvelopeBuilder` in `DeltaSigAttestorIntegration.cs`.

49
docs/features/checked/binaryindex/disassembly-and-binary-analysis-pipeline.md Normal file
View File

@@ -0,0 +1,49 @@
# Disassembly and binary analysis pipeline
## Module
BinaryIndex
## Status
VERIFIED
## Description
Pluggable disassembly framework with Ghidra integration (BSim + version tracking) for binary analysis capabilities.
## Implementation Details
- **Modules**: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Disassembly/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Disassembly.Abstractions/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Disassembly.B2R2/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Disassembly.Iced/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Ghidra/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Decompiler/`
- **Key Classes**:
- `DisassemblyService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Disassembly/DisassemblyService.cs`) - core disassembly orchestrator
- `HybridDisassemblyService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Disassembly/HybridDisassemblyService.cs`) - multi-backend hybrid disassembly with quality-based plugin selection
- `DisassemblyPluginRegistry` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Disassembly/DisassemblyPluginRegistry.cs`) - manages registered disassembly plugins
- `BinaryFormatDetector` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Disassembly/BinaryFormatDetector.cs`) - detects ELF/PE/Mach-O format from binary headers
- `B2R2DisassemblyPlugin` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Disassembly.B2R2/B2R2DisassemblyPlugin.cs`) - B2R2 backend with architecture mapping, instruction mapping, operand parsing
- `B2R2LowUirLiftingService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Disassembly.B2R2/B2R2LowUirLiftingService.cs`) - lifts machine code to LowUIR intermediate representation with SSA transformation
- `B2R2LifterPool` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Disassembly.B2R2/B2R2LifterPool.cs`) - object pool for B2R2 lifter instances with warm preloading
- `IcedDisassemblyPlugin` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Disassembly.Iced/IcedDisassemblyPlugin.cs`) - Iced x86/x64 disassembler plugin
- `GhidraDisassemblyPlugin` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Ghidra/Services/GhidraDisassemblyPlugin.cs`) - Ghidra integration
- `GhidraDecompilerAdapter` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Decompiler/GhidraDecompilerAdapter.cs`) - Ghidra decompilation with AST comparison
- **Abstractions**: `IDisassemblyPlugin`, `IDisassemblyPluginRegistry`, `IDisassemblyService` with models for `BinaryFormat`, `CpuArchitecture`, `DisassembledInstruction`, `InstructionKind`, etc.
- **Decompiler**: Full AST comparison engine with recursive parser, code normalizer, semantic equivalence checking
## E2E Test Plan
- [ ] Load an x86-64 ELF binary via `HybridDisassemblyService` and verify disassembly produces valid instructions
- [ ] Verify `BinaryFormatDetector` correctly identifies ELF, PE, and Mach-O formats
- [ ] Verify B2R2 plugin handles architecture mapping for x86, x64, ARM, AArch64
- [ ] Verify B2R2 LowUIR lifting produces valid IR with SSA form
- [ ] Verify Iced plugin disassembles x86/x64 instructions correctly
- [ ] Verify `B2R2LifterPool` warm preloading and pool size management
- [ ] Verify Ghidra decompiler adapter produces comparable ASTs via `AstComparisonEngine`
- [ ] Verify hybrid disassembly quality scoring selects the best plugin for each binary
## Verification
- Tier 0/1/2 artifacts: `docs/qa/feature-checks/runs/binaryindex/disassembly-and-binary-analysis-pipeline/run-001/`.
- Result: verified.
- Evidence summary:
- `tier1-test-disassembly.log`: Passed 45/45.
- `tier1-test-ghidra-retest.log`: Passed 122/122.
- `tier1-test-decompiler-retest.log`: Passed 35/35.
- `tier2-test-disassembly.log`: Passed 45/45.
- `tier2-test-ghidra.log`: Passed 122/122.
- `tier2-test-decompiler.log`: Passed 35/35.
- Note: initial Ghidra/Decompiler `--no-build` checks produced `Invalid TargetPath`; reran with build and captured final passing evidence.

44
docs/features/checked/binaryindex/known-build-binary-catalog.md Normal file
View File

@@ -0,0 +1,44 @@
# Known-build binary catalog (Build-ID + hash-based binary identity)
## Module
BinaryIndex
## Status
VERIFIED
## Description
BinaryIdentity model and vulnerability assertion repository implement the binary-key-based catalog using Build-ID and file SHA256 as primary keys.
## Implementation Details
- **Modules**: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Persistence/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Cache/`
- **Key Classes**:
- `BinaryIdentity` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/Models/BinaryIdentity.cs`) - core identity model with Build-ID and file SHA256 dimensions
- `BinaryIdentityService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/Services/BinaryIdentityService.cs`) - binary identity extraction/indexing service
- `BinaryIdentityRepository` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Persistence/Repositories/BinaryIdentityRepository.cs`) - repository lookups by Build-ID, binary key, and file SHA256
- `BinaryVulnerabilityService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Persistence/Services/BinaryVulnerabilityService.cs`) - assertion-backed vulnerability lookup with method mapping
- `CachedBinaryVulnerabilityService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Cache/CachedBinaryVulnerabilityService.cs`) - read-through cache for repeat identity lookups
- **Interfaces**:
- `IBinaryVulnerabilityService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/Services/IBinaryVulnerabilityService.cs`)
- `IBinaryVulnAssertionRepository` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/Services/IBinaryVulnAssertionRepository.cs`)
- `IBinaryIdentityRepository` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Persistence/Repositories/IBinaryIdentityRepository.cs`)
## E2E Test Plan
- [x] Register a binary identity with known Build-ID and verify it is stored in the catalog
- [x] Query the catalog by Build-ID and verify the correct binary identity is returned
- [x] Query by file SHA256 hash and verify the correct binary identity is returned
- [x] Assert a vulnerability against a binary identity and verify the assertion is persisted
- [x] Verify `CachedBinaryVulnerabilityService` caches lookups and returns cached results on repeat queries
- [x] Verify match method mapping: `buildid_catalog` maps to `MatchMethod.BuildIdCatalog`
## Verification
- Run: `run-002`
- Date (UTC): 2026-02-12
- Evidence: `docs/qa/feature-checks/runs/binaryindex/known-build-binary-catalog/run-002/`
- Tier 1 result: pass (`87/87` tests)
- Tier 2 result: pass (`10/10` targeted behavioral checks)
- Verified behaviors:
- Build-ID lookup positive and negative paths
- File SHA256 lookup, including latest-row precedence behavior
- Assertion persistence retrieval path
- `buildid_catalog` to `MatchMethod.BuildIdCatalog` mapping
- Repeat identity lookup cache-hit behavior

40
docs/features/checked/binaryindex/local-mirror-layer-for-corpus-sources.md Normal file
View File

@@ -0,0 +1,40 @@
# Local mirror layer for corpus sources
## Module
BinaryIndex
## Status
VERIFIED
## Description
Local mirror package-source layer for corpus ingestion across Debian, Alpine, and RPM ecosystems with offline-friendly cache fallback and deterministic corpus snapshot behavior.
## Implementation Details
- **Modules**: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Corpus/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Corpus.Debian/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Corpus.Alpine/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Corpus.Rpm/`
- **Key Classes**:
- `DebianMirrorPackageSource` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Corpus.Debian/DebianMirrorPackageSource.cs`) - Debian mirror index and package fetch support
- `AlpineMirrorPackageSource` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Corpus.Alpine/AlpineMirrorPackageSource.cs`) - Alpine APK mirror index/package fetch with cached fallback
- `RpmMirrorPackageSource` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Corpus.Rpm/RpmMirrorPackageSource.cs`) - RPM primary metadata/package fetch with cached fallback
- `DebianCorpusConnector` / `AlpineCorpusConnector` / `RpmCorpusConnector` - connector layer using package source abstractions and snapshot repository integration
- `ICorpusSnapshotRepository` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Corpus/ICorpusSnapshotRepository.cs`) - deterministic snapshot persistence for offline replay
- **Interfaces**: `IDebianPackageSource`, `IAlpinePackageSource`, `IRpmPackageSource`
## E2E Test Plan
- [x] Fetch Debian package index and validate deterministic package parsing behavior
- [x] Fetch Alpine package index and verify offline index cache fallback behavior
- [x] Fetch RPM package metadata and verify offline index cache fallback behavior
- [x] Download package payloads and verify cached payload fallback when remote fetch fails
- [x] Persist and query corpus snapshots deterministically for offline retrieval behavior
## Verification
- Run: `run-002`
- Date (UTC): 2026-02-12
- Evidence: `docs/qa/feature-checks/runs/binaryindex/local-mirror-layer-for-corpus-sources/run-002/`
- Tier 0 result: pass (`tier0-source-check.json`)
- Tier 1 result: pass (`34/34` tests)
- Tier 2 result: pass (`39/39` targeted integration checks)
- Verified behaviors:
- Debian, Alpine, and RPM mirror package-source implementations are present and wired through corpus connectors.
- Alpine and RPM mirror sources provide cached index and package payload fallback for offline/remote-failure paths.
- Corpus snapshot repository behavior remains deterministic for distro/release/architecture snapshot lookup paths.

35
docs/features/checked/binaryindex/patch-coverage-tracking.md Normal file
View File

@@ -0,0 +1,35 @@
# Patch Coverage Tracking
## Module
BinaryIndex
## Status
VERIFIED
## Description
Dedicated patch coverage API endpoint for tracking which CVE patches are covered in binary analysis.
## Implementation Details
- **Modules**: `src/BinaryIndex/StellaOps.BinaryIndex.WebService/Controllers/`
- **Key Classes**:
- `PatchCoverageController` (`src/BinaryIndex/StellaOps.BinaryIndex.WebService/Controllers/PatchCoverageController.cs`) - REST API controller for patch coverage queries using `IDeltaSignatureRepository`
- `DeltaSignatureMatcher` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/DeltaSignatureMatcher.cs`) - matches delta signatures to assess patch coverage
- `DeltaSigService` / `DeltaSigServiceV2` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/`) - service layer for delta-sig operations
- **Interfaces**: `IDeltaSignatureRepository` - repository for persisted delta signatures used by patch coverage queries
## E2E Test Plan
- [x] Query patch coverage API for a known CVE and verify coverage status (covered/not covered)
- [x] Verify patch coverage percentage calculation: submit binaries with partial patch coverage
- [x] Verify that delta signatures for the CVE fix are used to determine coverage
- [x] Verify API returns correct coverage for batch queries across multiple CVEs
- [x] Verify coverage tracking updates when new delta signatures are added
## Verification
- Tier 0/1/2 artifacts: `docs/qa/feature-checks/runs/binaryindex/patch-coverage-tracking/run-001/`.
- Result: verified.
- Evidence summary:
- `tier1-test-webservice-patchcoverage.log`: Passed 7/7.
- `tier1-test-deltasig-matcher.log`: Passed 8/8.
- `tier2-test-webservice-patchcoverage.log`: Passed 7/7.
- `tier2-test-deltasig-matcher.log`: Passed 8/8.
- Note: webservice and webservice-tests builds were run with scoped output paths in this run to avoid concurrent binary-lock collisions on shared `bin/Release` outputs.

31
docs/features/checked/binaryindex/patchdiffengine.md Normal file
View File

@@ -0,0 +1,31 @@
# PatchDiffEngine (Binary Pre/Post Patch Comparison for Fix Verification)
## Module
BinaryIndex
## Status
IMPLEMENTED
## Description
Compares pre-patch and post-patch binaries at multiple levels (BasicBlock, CFG, StringRefs, Semantic/KSG fingerprints) to determine if a vulnerability has been remediated. Produces structured verification results with confidence scores based on match depth. Core verification logic for the Golden Set Diff Layer.
## Implementation Details
- **Modules**: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Diff/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Builders/`
- **Key Classes**:
- `PatchDiffEngine` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Diff/PatchDiffEngine.cs`) - core engine comparing pre/post binaries using `ISignatureMatcher`, `IFunctionFingerprintExtractor`, and `IFunctionDiffer`; produces `PatchDiffResult` with confidence scores
- `PatchDiffEngine` (builders) (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Builders/PatchDiffEngine.cs`) - builder-level diff engine
- `FunctionDiffer` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Diff/FunctionDiffer.cs`) - function-level comparison with semantic analysis, call-graph edge diffing, and string reference comparison
- `FunctionRenameDetector` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Diff/FunctionRenameDetector.cs`) - detects renamed functions between versions
- `VerdictCalculator` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Diff/VerdictCalculator.cs`) - computes fix verification verdict from diff results
- **Models**: `PatchDiffResult`, `PatchDiffModels`, `DiffEvidenceModels`, `DiffOptions` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Diff/Models/`)
- **Storage**: `IDiffResultStore`, `InMemoryDiffResultStore` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Diff/Storage/`)
- **Source**: SPRINT_20260110_012_004_BINDEX_golden_set_diff_verify.md
## E2E Test Plan
- [ ] Submit pre-patch and post-patch binaries for a known CVE fix and verify the diff result shows patch applied
- [ ] Verify multi-level comparison: BasicBlock, CFG, StringRefs, and semantic fingerprints all contribute to confidence
- [ ] Verify `FunctionDiffer` with `IncludeSemanticAnalysis=true` computes semantic similarity
- [ ] Verify `FunctionRenameDetector` handles renamed functions between versions
- [ ] Verify `VerdictCalculator` produces correct verdict (Fixed, Vulnerable, Unknown) based on diff evidence
- [ ] Verify `NoPatchDetected` result is returned when binaries are identical
- [ ] Verify diff results are persistable via `IDiffResultStore` with content-addressed IDs

38
docs/features/checked/binaryindex/reproducible-distro-build-pipeline.md Normal file
View File

@@ -0,0 +1,38 @@
# Reproducible Distro Build Pipeline (Container-Based Builders)
## Module
BinaryIndex
## Status
VERIFIED
## Description
Container-based reproducible build pipeline for Alpine, Debian, and RHEL packages. Rebuilds upstream source packages in isolated containers to produce reference binaries for function-level fingerprint comparison, enabling backport detection by comparing distro-patched binaries against unpatched originals.
## Implementation Details
- **Modules**: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Builders/`, `src/BinaryIndex/StellaOps.BinaryIndex.Worker/`
- **Key Classes**:
- `ReproducibleBuildJob` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Builders/ReproducibleBuildJobTypes.cs`) - orchestrates distro-specific builds and fingerprint/patch-diff attribution
- `ReproducibleBuildJob` compatibility implementation (`src/BinaryIndex/StellaOps.BinaryIndex.Worker/Jobs/ReproducibleBuildJob.cs`)
- `ReproducibleBuildOptions` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Builders/ReproducibleBuildJobTypes.cs`) - build configuration (timeouts, architecture, concurrency)
- `IReproducibleBuilder` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Builders/IReproducibleBuilder.cs`) - abstraction for container-based builds
- `BuilderServiceOptions` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Builders/BuilderOptions.cs`) - builder infrastructure configuration
- `GuidProvider` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Builders/GuidProvider.cs`) - deterministic GUID generation for reproducibility
- **Integration**: Uses `IFingerprintClaimRepository` to store build verification claims; integrates with `IPatchDiffEngine` for post-build binary comparison
- **Source**: SPRINT_1227_0002_0001_LB_reproducible_builders.md
## E2E Test Plan
- [ ] Trigger a reproducible build for a Debian package and verify reference binaries are produced
- [ ] Compare distro-patched binary against unpatched original and verify fingerprint differences
- [ ] Verify container isolation: build runs in isolated container with controlled environment
- [ ] Verify `FingerprintClaim` records are generated with build provenance evidence
- [ ] Verify `GuidProvider` produces deterministic GUIDs for identical build inputs
- [ ] Verify backport detection: distro-patched binary with backported fix is correctly identified
## Verification
- Run ID: `run-001`
- Verified at: `2026-02-12T06:09:39.1151882Z`
- Evidence:
- `docs/qa/feature-checks/runs/binaryindex/reproducible-distro-build-pipeline/run-001/tier0-source-check.json`
- `docs/qa/feature-checks/runs/binaryindex/reproducible-distro-build-pipeline/run-001/tier1-build-check.json`
- `docs/qa/feature-checks/runs/binaryindex/reproducible-distro-build-pipeline/run-001/tier2-e2e-check.json`

31
docs/features/checked/binaryindex/semantic-analysis-library.md Normal file
View File

@@ -0,0 +1,31 @@
# Semantic Analysis Library (IR Lifting and Function Fingerprinting)
## Module
BinaryIndex
## Status
IMPLEMENTED
## Description
Semantic binary analysis with IR lifting, function fingerprint generation, semantic matching, graph extraction, and call n-gram generation for function-level binary comparison.
## Implementation Details
- **Modules**: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Semantic/`
- **Key Classes**:
- `IrLiftingService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Semantic/IrLiftingService.cs`) - lifts disassembled instructions to deterministic IR/SSA models (with B2R2-specific lifting types available under `Lifting/`)
- `SemanticFingerprintGenerator` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Semantic/SemanticFingerprintGenerator.cs`) - generates `SemanticFingerprint` using Weisfeiler-Lehman graph hashing (KsgWeisfeilerLehmanV1 algorithm)
- `SemanticGraphExtractor` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Semantic/SemanticGraphExtractor.cs`) - extracts key-semantics graphs (KSG) from lifted IR
- `SemanticMatcher` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Semantic/SemanticMatcher.cs`) - matches semantic fingerprints for similarity scoring
- `CallNgramGenerator` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Semantic/CallNgramGenerator.cs`) - call-sequence n-gram fingerprinting
- `WeisfeilerLehmanHasher` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Semantic/Internal/WeisfeilerLehmanHasher.cs`) - WL graph hash implementation
- `GraphCanonicalizer` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Semantic/Internal/GraphCanonicalizer.cs`) - graph canonicalization for deterministic hashing
- **Models**: `FingerprintModels` (SemanticFingerprint, SemanticFingerprintOptions, SemanticFingerprintAlgorithm), `GraphModels` (KeySemanticsGraph), `IrModels` (LiftedFunction, IrStatement)
- **Interfaces**: `IIrLiftingService`, `ISemanticFingerprintGenerator`, `ISemanticGraphExtractor`, `ISemanticMatcher`
## E2E Test Plan
- [ ] Lift a binary function to IR via `IrLiftingService` and verify IR structure contains valid statements
- [ ] Generate a semantic fingerprint via `SemanticFingerprintGenerator` and verify hash is deterministic
- [ ] Extract a key-semantics graph via `SemanticGraphExtractor` and verify node/edge structure
- [ ] Match two fingerprints of the same function (different compilers) via `SemanticMatcher` and verify high similarity
- [ ] Verify Weisfeiler-Lehman graph hash produces different hashes for structurally different functions
- [ ] Verify `GraphCanonicalizer` produces consistent canonical forms for isomorphic graphs

36
docs/features/checked/binaryindex/vulnerable-binaries-database.md Normal file
View File

@@ -0,0 +1,36 @@
# Vulnerable Binaries Database (BinaryIndex Module)
## Module
BinaryIndex
## Status
VERIFIED
## Description
Dedicated BinaryIndex module with web service, worker, and library structure for binary vulnerability detection independent of package metadata.
## Implementation Details
- **Modules**: `src/BinaryIndex/StellaOps.BinaryIndex.WebService/`, `src/BinaryIndex/StellaOps.BinaryIndex.Worker/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Persistence/`
- **Key Classes**:
- **Web Service**: `ResolutionController` (`Controllers/ResolutionController.cs`) - vulnerability resolution API; `GoldenSetController` - golden set management API; `PatchCoverageController` - patch coverage API; `BinaryIndexOpsController` - ops health/bench/cache endpoints
- **Worker**: `ReproducibleBuildJob` (`Jobs/ReproducibleBuildJob.cs`) - background worker for build verification
- **Persistence**: `BinaryVulnerabilityService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Persistence/Services/BinaryVulnerabilityService.cs`) - vulnerability detection service with match method mapping and corpus query integration
- **Cache**: `CachedBinaryVulnerabilityService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Cache/CachedBinaryVulnerabilityService.cs`) - Valkey-backed caching layer
- **Analysis**: `SignatureMatcher`, `TaintGateExtractor`, `ReachGraphBinaryReachabilityService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Analysis/`)
- **Ensemble**: `EnsembleDecisionEngine` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Ensemble/`) - multi-tier vulnerability classification
- **Program Entry**: `Program.cs` (`src/BinaryIndex/StellaOps.BinaryIndex.WebService/Program.cs`) - configures services, resolution caching, rate limiting
## E2E Test Plan
- [x] Query the database for a known vulnerable binary (by Build-ID) and verify vulnerability is detected
- [x] Submit a binary for analysis and verify detection works independent of package metadata
- [x] Verify web service endpoints are accessible: resolution, golden set, patch coverage, ops
- [x] Verify worker job processes reproducible build verification in the background
- [x] Verify cached lookups improve performance on repeated queries
- [x] Verify ensemble decision engine combines all matching signals for final vulnerability classification
## Verification
- Run: `docs/qa/feature-checks/runs/binaryindex/vulnerable-binaries-database/run-002/`
- Date (UTC): 2026-02-12
- Tier 0: Source and symbol checks passed, including Worker project buildability and WebService fallback wiring.
- Tier 1: Build and test gates passed for Analysis, Builders, Cache, Ensemble, Persistence, WebService, Worker, and related test projects.
- Tier 2: API checks passed for ops/config, golden set listing, patch coverage, invalid payload handling (`400`), single and batch resolution, and repeated cache-backed resolution replay (`fromCache=true`).