save progress

2026-01-03 00:47:24 +02:00
parent 3f197814c5
commit ca578801fd
319 changed files with 32478 additions and 2202 deletions
--- a/src/BinaryIndex/AGENTS.md
+++ b/src/BinaryIndex/AGENTS.md
@@ -0,0 +1,100 @@
+# 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