# 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
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/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
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