Add reference architecture and testing strategy documentation

- Created a new document for the Stella Ops Reference Architecture outlining the system's topology, trust boundaries, artifact association, and interfaces.
- Developed a comprehensive Testing Strategy document detailing the importance of offline readiness, interoperability, determinism, and operational guardrails.
- Introduced a README for the Testing Strategy, summarizing processing details and key concepts implemented.
- Added guidance for AI agents and developers in the tests directory, including directory structure, test categories, key patterns, and rules for test development.
This commit is contained in:
2025-12-22 07:59:15 +02:00
parent 5d398ec442
commit 53503cb407
96 changed files with 37565 additions and 71 deletions

View File

@@ -0,0 +1,81 @@
# Archived Advisory: Mapping Evidence Within Compiled Binaries
**Original Advisory:** `21-Dec-2025 - Mapping Evidence Within Compiled Binaries.md`
**Archived:** 2025-12-21
**Status:** Converted to Implementation Plan
---
## Summary
This advisory proposed building a **Vulnerable Binaries Database** that enables detection of vulnerable code at the binary level, independent of package metadata.
## Implementation Artifacts Created
### Architecture Documentation
- `docs/modules/binaryindex/architecture.md` - Full module architecture
- `docs/db/schemas/binaries_schema_specification.md` - Database schema
### Sprint Files
**Summary:**
- `docs/implplan/SPRINT_6000_SUMMARY.md` - MVP roadmap overview
**MVP 1: Known-Build Binary Catalog (Sprint 6000.0001)**
- `SPRINT_6000_0001_0001_binaries_schema.md` - PostgreSQL schema
- `SPRINT_6000_0001_0002_binary_identity_service.md` - Identity extraction
- `SPRINT_6000_0001_0003_debian_corpus_connector.md` - Debian/Ubuntu ingestion
**MVP 2: Patch-Aware Backport Handling (Sprint 6000.0002)**
- `SPRINT_6000_0002_0001_fix_evidence_parser.md` - Changelog/patch parsing
**MVP 3: Binary Fingerprint Factory (Sprint 6000.0003)**
- `SPRINT_6000_0003_0001_fingerprint_storage.md` - Fingerprint storage
**MVP 4: Scanner Integration (Sprint 6000.0004)**
- `SPRINT_6000_0004_0001_scanner_integration.md` - Scanner.Worker integration
## Key Decisions
| Decision | Rationale |
|----------|-----------|
| New `BinaryIndex` module | Binary vulnerability DB is distinct concern from Scanner |
| Build-ID as primary key | Most deterministic identifier for ELF binaries |
| `binaries` PostgreSQL schema | Aligns with existing per-module schema pattern |
| Three-tier lookup | Assertions → Build-ID → Fingerprints for precision |
| Patch-aware fix index | Handles distro backports correctly |
## Module Structure
```
src/BinaryIndex/
├── StellaOps.BinaryIndex.WebService/
├── StellaOps.BinaryIndex.Worker/
├── __Libraries/
│ ├── StellaOps.BinaryIndex.Core/
│ ├── StellaOps.BinaryIndex.Persistence/
│ ├── StellaOps.BinaryIndex.Corpus/
│ ├── StellaOps.BinaryIndex.Corpus.Debian/
│ ├── StellaOps.BinaryIndex.FixIndex/
│ └── StellaOps.BinaryIndex.Fingerprints/
└── __Tests/
```
## Database Tables
| Table | Purpose |
|-------|---------|
| `binaries.binary_identity` | Known binary identities |
| `binaries.binary_package_map` | Binary → package mapping |
| `binaries.vulnerable_buildids` | Vulnerable Build-IDs |
| `binaries.cve_fix_index` | Patch-aware fix status |
| `binaries.vulnerable_fingerprints` | Function fingerprints |
| `binaries.fingerprint_matches` | Scan match results |
## References
- Original advisory: This folder
- Architecture: `docs/modules/binaryindex/architecture.md`
- Schema: `docs/db/schemas/binaries_schema_specification.md`
- Sprints: `docs/implplan/SPRINT_6000_*.md`