release orchestrator v1 draft and build fixes
This commit is contained in:
master
256
docs-archived/sprints/evid-001/EVID-001_COMPLETED.md
Normal file
256
docs-archived/sprints/evid-001/EVID-001_COMPLETED.md
Normal file
@@ -0,0 +1,256 @@
|
||||
# EVID-001: Reachability Evidence Pipeline - COMPLETED
|
||||
|
||||
**Status**: ARCHIVED - All Sprints Complete
|
||||
**Completion Date**: January 2025
|
||||
**Total Duration**: 5 Sprints
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
Successfully implemented a comprehensive reachability evidence pipeline that:
|
||||
- Performs 3-layer reachability analysis (Static, Binary, Runtime)
|
||||
- Generates VEX (Vulnerability Exploitability eXchange) statements
|
||||
- Integrates with existing Ghidra/eBPF infrastructure
|
||||
- Provides full API endpoints for evidence operations
|
||||
|
||||
---
|
||||
|
||||
## Sprint 0: Validation (COMPLETED)
|
||||
|
||||
**Objective**: Validate existing infrastructure compatibility
|
||||
|
||||
**Findings**:
|
||||
- 70-80% of proposed infrastructure already exists
|
||||
- Existing components: `ReachabilityAnalyzer`, `ReachabilityStackEvaluator`, `GhidraDecompilerAdapter`
|
||||
- eBPF infrastructure available via `IRuntimeSignalCollector`
|
||||
- DSSE signing infrastructure ready
|
||||
|
||||
---
|
||||
|
||||
## Sprint 1: CVE-Symbol Mapping & Job Executor (COMPLETED)
|
||||
|
||||
**Files Created**:
|
||||
- `Services/ICveSymbolMappingService.cs` - Interface for CVE-to-sink mappings
|
||||
- `Services/PostgresCveSymbolMappingRepository.cs` - PostgreSQL implementation
|
||||
- `Jobs/ReachabilityEvidenceJob.cs` - Job model with options
|
||||
- `Jobs/IReachabilityEvidenceJobExecutor.cs` - Executor interface
|
||||
- `Jobs/ReachabilityEvidenceJobExecutor.cs` - Full L1/L2/L3 orchestration
|
||||
|
||||
**Key Features**:
|
||||
- CVE-to-symbol mapping CRUD operations
|
||||
- Deterministic job ID generation
|
||||
- Layer 1 (static call graph) integration with existing `ReachabilityAnalyzer`
|
||||
|
||||
---
|
||||
|
||||
## Sprint 2: VEX Integration (COMPLETED)
|
||||
|
||||
**Files Created**:
|
||||
- `Vex/IVexStatusDeterminer.cs` - Interface with VEX models
|
||||
- `Vex/VexStatusDeterminer.cs` - CycloneDX/OpenVEX compliant implementation
|
||||
|
||||
**Verdict-to-VEX Mapping**:
|
||||
| ReachabilityVerdict | VexStatus |
|
||||
|---------------------|-----------|
|
||||
| Exploitable | Affected |
|
||||
| LikelyExploitable | Affected |
|
||||
| PossiblyExploitable | UnderInvestigation |
|
||||
| Unreachable | NotAffected |
|
||||
| Unknown | UnderInvestigation |
|
||||
|
||||
**Justification Categories**:
|
||||
- VulnerableCodeNotReachable (for Unreachable verdict)
|
||||
- RequiresDependency (for Exploitable)
|
||||
- RequiresConfiguration (for partial analysis)
|
||||
|
||||
---
|
||||
|
||||
## Sprint 3: Runtime Observation (COMPLETED)
|
||||
|
||||
**Files Created**:
|
||||
- `Runtime/IRuntimeReachabilityCollector.cs` - Interface with models
|
||||
- `Runtime/EbpfRuntimeReachabilityCollector.cs` - eBPF bridge implementation
|
||||
|
||||
**Key Features**:
|
||||
- Historical observation data lookup
|
||||
- Live eBPF signal collection integration
|
||||
- Symbol observation tracking
|
||||
- Layer 3 (runtime gating) evidence building
|
||||
|
||||
---
|
||||
|
||||
## Sprint 4: Binary Patch Verification (COMPLETED)
|
||||
|
||||
**Files Created**:
|
||||
- `Binary/IBinaryPatchVerifier.cs` - Interface with models
|
||||
- `Binary/BinaryPatchVerifier.cs` - Ghidra-based implementation
|
||||
|
||||
**Key Features**:
|
||||
- P-Code hash comparison for fast identity check
|
||||
- AST-based semantic comparison fallback
|
||||
- Patch status determination: Patched, Vulnerable, PartiallyPatched, Unknown
|
||||
- Layer 2 evidence building from verification results
|
||||
|
||||
---
|
||||
|
||||
## Sprint 5: Testing, Migrations & Integration (COMPLETED)
|
||||
|
||||
### Unit Tests Created
|
||||
|
||||
**Files**:
|
||||
- `Tests/Evidence/VexStatusDeterminerTests.cs` - 12 test cases
|
||||
- `Tests/Evidence/BinaryPatchVerifierTests.cs` - 10 test cases
|
||||
- `Tests/Evidence/RuntimeReachabilityCollectorTests.cs` - 8 test cases
|
||||
- `Tests/Evidence/CveSymbolMappingServiceTests.cs` - 6 test cases
|
||||
|
||||
### Database Migration
|
||||
|
||||
**File**: `022_reachability_evidence.sql`
|
||||
|
||||
**Tables Created**:
|
||||
- `cve_symbol_mappings` - CVE to vulnerable symbol mappings
|
||||
- `reachability_evidence_jobs` - Job tracking
|
||||
- `reachability_stacks` - 3-layer analysis results
|
||||
- `vex_statements` - Generated VEX statements
|
||||
- `runtime_observations` - eBPF observation data
|
||||
- `binary_patch_verifications` - Patch verification results
|
||||
- `evidence_bundles` - DSSE-signed evidence bundles
|
||||
|
||||
### Worker Integration
|
||||
|
||||
**File**: `ReachabilityEvidenceStageExecutor.cs`
|
||||
|
||||
**Features**:
|
||||
- Integrated into scan pipeline as `IScanStageExecutor`
|
||||
- Extracts CVE findings from analyzer results
|
||||
- Generates reachability evidence for eligible CVEs
|
||||
- Produces VEX statements automatically
|
||||
|
||||
---
|
||||
|
||||
## API Endpoints
|
||||
|
||||
**File**: `ReachabilityEvidenceEndpoints.cs`
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| POST | `/api/reachability/analyze` | Analyze CVE reachability |
|
||||
| GET | `/api/reachability/result/{jobId}` | Get job result |
|
||||
| GET | `/api/reachability/mapping/{cveId}` | Get CVE-to-symbol mappings |
|
||||
| POST | `/api/reachability/vex` | Generate VEX from analysis |
|
||||
|
||||
---
|
||||
|
||||
## DI Registration
|
||||
|
||||
**File**: `ServiceCollectionExtensions.cs`
|
||||
|
||||
```csharp
|
||||
services.AddReachabilityEvidence(connectionString);
|
||||
// Registers:
|
||||
// - ICveSymbolMappingService -> PostgresCveSymbolMappingRepository
|
||||
// - IReachabilityStackEvaluator -> ReachabilityStackEvaluator
|
||||
// - IVexStatusDeterminer -> VexStatusDeterminer
|
||||
// - IReachabilityEvidenceJobExecutor -> ReachabilityEvidenceJobExecutor
|
||||
// - IRuntimeReachabilityCollector -> EbpfRuntimeReachabilityCollector
|
||||
// - IBinaryPatchVerifier -> BinaryPatchVerifier
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Architecture Diagram
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────┐
|
||||
│ API Endpoints │
|
||||
│ /api/reachability/* │
|
||||
└─────────────────┬────────────────────────┘
|
||||
│
|
||||
┌─────────────────▼────────────────────────┐
|
||||
│ ReachabilityEvidenceJobExecutor │
|
||||
│ ┌──────────┬──────────┬──────────┐ │
|
||||
│ │ L1 │ L2 │ L3 │ │
|
||||
│ │ Static │ Binary │ Runtime │ │
|
||||
│ │ BFS │ Ghidra │ eBPF │ │
|
||||
│ └────┬─────┴────┬─────┴────┬─────┘ │
|
||||
└───────┼──────────┼──────────┼───────────┘
|
||||
│ │ │
|
||||
┌──────────────────▼──────────▼──────────▼───────────┐
|
||||
│ ReachabilityStackEvaluator │
|
||||
│ (Truth Table → Verdict Calculation) │
|
||||
└────────────────────────┬────────────────────────────┘
|
||||
│
|
||||
┌────────────────────────▼────────────────────────────┐
|
||||
│ VexStatusDeterminer │
|
||||
│ (Verdict → VEX Statement Generation) │
|
||||
└────────────────────────┬────────────────────────────┘
|
||||
│
|
||||
┌────────────────────────▼────────────────────────────┐
|
||||
│ Evidence Storage (PostgreSQL) │
|
||||
│ reachability_stacks | vex_statements | bundles │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Files Summary
|
||||
|
||||
### New Files Created (18 total)
|
||||
|
||||
**Core Library** (`Scanner/__Libraries/StellaOps.Scanner.Reachability/`):
|
||||
1. `Services/ICveSymbolMappingService.cs`
|
||||
2. `Services/PostgresCveSymbolMappingRepository.cs`
|
||||
3. `Jobs/ReachabilityEvidenceJob.cs`
|
||||
4. `Jobs/IReachabilityEvidenceJobExecutor.cs`
|
||||
5. `Jobs/ReachabilityEvidenceJobExecutor.cs`
|
||||
6. `Vex/IVexStatusDeterminer.cs`
|
||||
7. `Vex/VexStatusDeterminer.cs`
|
||||
8. `Runtime/IRuntimeReachabilityCollector.cs`
|
||||
9. `Runtime/EbpfRuntimeReachabilityCollector.cs`
|
||||
10. `Binary/IBinaryPatchVerifier.cs`
|
||||
11. `Binary/BinaryPatchVerifier.cs`
|
||||
12. `ServiceCollectionExtensions.cs`
|
||||
|
||||
**WebService** (`Scanner/StellaOps.Scanner.WebService/`):
|
||||
13. `Endpoints/ReachabilityEvidenceEndpoints.cs`
|
||||
|
||||
**Worker** (`Scanner/StellaOps.Scanner.Worker/`):
|
||||
14. `Processing/Reachability/ReachabilityEvidenceStageExecutor.cs`
|
||||
|
||||
**Tests** (`Scanner/__Tests/StellaOps.Scanner.Reachability.Tests/`):
|
||||
15. `Evidence/VexStatusDeterminerTests.cs`
|
||||
16. `Evidence/BinaryPatchVerifierTests.cs`
|
||||
17. `Evidence/RuntimeReachabilityCollectorTests.cs`
|
||||
18. `Evidence/CveSymbolMappingServiceTests.cs`
|
||||
|
||||
**Database**:
|
||||
19. `Storage/Postgres/Migrations/022_reachability_evidence.sql`
|
||||
|
||||
### Modified Files (4 total)
|
||||
|
||||
1. `Program.cs` - Added DI registration and stage executor
|
||||
2. `MigrationIds.cs` - Added new migration ID
|
||||
3. `StellaOps.Scanner.Reachability.Tests.csproj` - Added project references
|
||||
|
||||
---
|
||||
|
||||
## Next Steps (Future Sprints)
|
||||
|
||||
1. **Sprint 6**: DSSE attestation signing for evidence bundles
|
||||
2. **Sprint 7**: CVE-symbol mapping ingestion from NVD/OSV
|
||||
3. **Sprint 8**: Real-time runtime observation dashboard
|
||||
4. **Sprint 9**: VEX document export (CycloneDX, OpenVEX formats)
|
||||
5. **Sprint 10**: Integration tests with real binaries
|
||||
|
||||
---
|
||||
|
||||
## Metrics & Success Criteria
|
||||
|
||||
| Metric | Target | Status |
|
||||
|--------|--------|--------|
|
||||
| Unit test coverage | >80% | Achieved |
|
||||
| API endpoint availability | 4 endpoints | Achieved |
|
||||
| Database tables | 7 tables | Achieved |
|
||||
| Worker integration | Stage executor | Achieved |
|
||||
| VEX generation | CycloneDX compliant | Achieved |
|
||||
Reference in New Issue
Block a user