# 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
- Development: https://localhost:10360, http://localhost:10361
- Local alias: https://binaryindex.stella-ops.local, http://binaryindex.stella-ops.local
- Env var: STELLAOPS_BINARYINDEX_URL