stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 3 Releases Wiki Activity
Files
d27d68d8c6236b2c80d2642029148480eb4afcd3
git.stella-ops.org/src/BinaryIndex/AGENTS.md

6.8 KiB
Raw Blame History

BinaryIndex Module Charter

Mission

Own binary-level vulnerability detection and analysis. Provide deterministic binary identity resolution, delta signature matching for backport detection, and integration with the Scanner pipeline.

Module Overview

BinaryIndex is a collection of libraries and services for binary analysis:

Core Libraries

  • BinaryIndex.Core - Binary identity models, resolution logic, feature extractors
  • BinaryIndex.Contracts - API contracts and DTOs
  • BinaryIndex.Cache - Caching layer for binary analysis results
  • BinaryIndex.Persistence - PostgreSQL storage for signatures and identities (EF Core v10 + compiled models)

Delta Signature Stack (Backport Detection)

  • BinaryIndex.Disassembly.Abstractions - Plugin interfaces for disassembly
  • BinaryIndex.Disassembly - Service coordinating disassembly plugins
  • BinaryIndex.Disassembly.Iced - High-performance x86/x86-64 disassembly
  • BinaryIndex.Disassembly.B2R2 - Multi-architecture disassembly (ARM, MIPS, RISC-V)
  • BinaryIndex.Normalization - Instruction normalization for deterministic hashing
  • BinaryIndex.DeltaSig - Signature generation and matching

Corpus Builders

  • BinaryIndex.Corpus - Common corpus building infrastructure
  • BinaryIndex.Corpus.Rpm - RPM package corpus extraction
  • BinaryIndex.Corpus.Debian - DEB package corpus extraction
  • BinaryIndex.Corpus.Alpine - APK package corpus extraction

Services

  • BinaryIndex.WebService - REST API for binary queries
  • BinaryIndex.Worker - Background processing for corpus updates

Key Capabilities

  1. Binary Identity Resolution - Match binaries by Build-ID, fingerprint, or content hash
  2. Delta Signature Matching - Detect backported security fixes via normalized code comparison
  3. Vulnerability Correlation - Map binaries to known vulnerable/patched package versions
  4. VEX Evidence Generation - Produce VEX candidates with cryptographic proof of patch status

Architecture

?????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????
???                         Scanner.Worker                                   ???
???  ?????????????????????????????????????????????????????????????????????  ?????????????????????????????????????????????????????????????????????                       ???
???  ??? BinaryVulnerability ???  ???   DeltaSigAnalyzer   ???                       ???
???  ???     Analyzer        ???  ???                      ???                       ???
???  ?????????????????????????????????????????????????????????????????????  ????????????????????????????????????????????????????????????????????????                       ???
????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????
             ???                         ???
             ???                         ???
?????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????
???                    BinaryIndex Libraries                                 ???
???  ???????????????????????????????????????????????????  ??????????????????????????????????????????????????????  ??????????????????????????????????????????????????????????????????          ???
???  ???  Core/Cache   ???  ???  Disassembly   ???  ???   Normalization    ???          ???
???  ???  Persistence  ???  ???  Iced + B2R2   ???  ???   X64 + ARM64      ???          ???
???  ???????????????????????????????????????????????????  ??????????????????????????????????????????????????????  ??????????????????????????????????????????????????????????????????          ???
???                                ???                                         ???
???                                ???                                         ???
???                     ????????????????????????????????????????????????????????????                                ???
???                     ???     DeltaSig     ???                                ???
???                     ???  Generator/Match ???                                ???
???                     ????????????????????????????????????????????????????????????                                ???
?????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????????

Required Reading

  • docs/modules/binary-index/architecture.md
  • docs/modules/scanner/architecture.md
  • docs-archived/implplan/2026-01-02-completed-sprints/SPRINT_20260102_001_BE_binary_delta_signatures.md
  • docs-archived/product/advisories/30-Dec-2025 - Binary Diff Signatures for Patch Detection.md

Working Agreement

  1. Task status - Update DOING/DONE in sprint files when starting/finishing work.
  2. Determinism - All outputs must be deterministic (stable ordering, timestamps, hashes).
  3. Offline-first - Support air-gapped operation with signature packs.
  4. Recipe versioning - Increment recipe version for any normalization behavior change.
  5. Golden tests - Maintain golden tests for known CVEs (Heartbleed, Log4Shell, etc.).
  6. Coordination - Update Scanner AGENTS.md when changing integration contracts.

Sub-module Charters

Each library has its own AGENTS.md with specific responsibilities:

  • See __Libraries/StellaOps.BinaryIndex.*/AGENTS.md for library-specific charters
  • See __Tests/StellaOps.BinaryIndex.*.Tests/AGENTS.md for test charters

CLI Commands

Delta signature CLI (in StellaOps.Cli):

stella deltasig extract    # Extract signatures from binary
stella deltasig author     # Author vuln/patched signature pair
stella deltasig sign       # Sign signature as DSSE envelope
stella deltasig verify     # Verify signed signature
stella deltasig match      # Match binary against signatures
stella deltasig pack       # Create signature pack (ZIP)
stella deltasig inspect    # Inspect signature or envelope

Test Strategy

  • Unit tests - Per-library in __Tests/StellaOps.BinaryIndex.*.Tests
  • Property tests - FsCheck for normalization idempotency/determinism
  • Golden tests - Known CVE signature verification
  • Integration tests - End-to-end pipeline tests

Service Endpoints