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

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

Binary Identity Resolution - Match binaries by Build-ID, fingerprint, or content hash
Delta Signature Matching - Detect backported security fixes via normalized code comparison
Vulnerability Correlation - Map binaries to known vulnerable/patched package versions
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/binaryindex/architecture.md
docs/modules/scanner/architecture.md
docs/implplan/SPRINT_20260102_001_BE_binary_delta_signatures.md
docs/product/advisories/30-Dec-2025 - Binary Diff Signatures for Patch Detection.md

Working Agreement

Task status - Update DOING/DONE in sprint files when starting/finishing work.
Determinism - All outputs must be deterministic (stable ordering, timestamps, hashes).
Offline-first - Support air-gapped operation with signature packs.
Recipe versioning - Increment recipe version for any normalization behavior change.
Golden tests - Maintain golden tests for known CVEs (Heartbleed, Log4Shell, etc.).
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

6.5 KiB Raw Blame History