feat(crypto): Complete Phase 2 - Configuration-driven crypto architecture with 100% compliance
## Summary
This commit completes Phase 2 of the configuration-driven crypto architecture, achieving
100% crypto compliance by eliminating all hardcoded cryptographic implementations.
## Key Changes
### Phase 1: Plugin Loader Infrastructure
- **Plugin Discovery System**: Created StellaOps.Cryptography.PluginLoader with manifest-based loading
- **Configuration Model**: Added CryptoPluginConfiguration with regional profiles support
- **Dependency Injection**: Extended DI to support plugin-based crypto provider registration
- **Regional Configs**: Created appsettings.crypto.{international,russia,eu,china}.yaml
- **CI Workflow**: Added .gitea/workflows/crypto-compliance.yml for audit enforcement
### Phase 2: Code Refactoring
- **API Extension**: Added ICryptoProvider.CreateEphemeralVerifier for verification-only scenarios
- **Plugin Implementation**: Created OfflineVerificationCryptoProvider with ephemeral verifier support
- Supports ES256/384/512, RS256/384/512, PS256/384/512
- SubjectPublicKeyInfo (SPKI) public key format
- **100% Compliance**: Refactored DsseVerifier to remove all BouncyCastle cryptographic usage
- **Unit Tests**: Created OfflineVerificationProviderTests with 39 passing tests
- **Documentation**: Created comprehensive security guide at docs/security/offline-verification-crypto-provider.md
- **Audit Infrastructure**: Created scripts/audit-crypto-usage.ps1 for static analysis
### Testing Infrastructure (TestKit)
- **Determinism Gate**: Created DeterminismGate for reproducibility validation
- **Test Fixtures**: Added PostgresFixture and ValkeyFixture using Testcontainers
- **Traits System**: Implemented test lane attributes for parallel CI execution
- **JSON Assertions**: Added CanonicalJsonAssert for deterministic JSON comparisons
- **Test Lanes**: Created test-lanes.yml workflow for parallel test execution
### Documentation
- **Architecture**: Created CRYPTO_CONFIGURATION_DRIVEN_ARCHITECTURE.md master plan
- **Sprint Tracking**: Created SPRINT_1000_0007_0002_crypto_refactoring.md (COMPLETE)
- **API Documentation**: Updated docs2/cli/crypto-plugins.md and crypto.md
- **Testing Strategy**: Created testing strategy documents in docs/implplan/SPRINT_5100_0007_*
## Compliance & Testing
- ✅ Zero direct System.Security.Cryptography usage in production code
- ✅ All crypto operations go through ICryptoProvider abstraction
- ✅ 39/39 unit tests passing for OfflineVerificationCryptoProvider
- ✅ Build successful (AirGap, Crypto plugin, DI infrastructure)
- ✅ Audit script validates crypto boundaries
## Files Modified
**Core Crypto Infrastructure:**
- src/__Libraries/StellaOps.Cryptography/CryptoProvider.cs (API extension)
- src/__Libraries/StellaOps.Cryptography/CryptoSigningKey.cs (verification-only constructor)
- src/__Libraries/StellaOps.Cryptography/EcdsaSigner.cs (fixed ephemeral verifier)
**Plugin Implementation:**
- src/__Libraries/StellaOps.Cryptography.Plugin.OfflineVerification/ (new)
- src/__Libraries/StellaOps.Cryptography.PluginLoader/ (new)
**Production Code Refactoring:**
- src/AirGap/StellaOps.AirGap.Importer/Validation/DsseVerifier.cs (100% compliant)
**Tests:**
- src/__Libraries/__Tests/StellaOps.Cryptography.Plugin.OfflineVerification.Tests/ (new, 39 tests)
- src/__Libraries/__Tests/StellaOps.Cryptography.PluginLoader.Tests/ (new)
**Configuration:**
- etc/crypto-plugins-manifest.json (plugin registry)
- etc/appsettings.crypto.*.yaml (regional profiles)
**Documentation:**
- docs/security/offline-verification-crypto-provider.md (600+ lines)
- docs/implplan/CRYPTO_CONFIGURATION_DRIVEN_ARCHITECTURE.md (master plan)
- docs/implplan/SPRINT_1000_0007_0002_crypto_refactoring.md (Phase 2 complete)
## Next Steps
Phase 3: Docker & CI/CD Integration
- Create multi-stage Dockerfiles with all plugins
- Build regional Docker Compose files
- Implement runtime configuration selection
- Add deployment validation scripts
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
master
305
docs/implplan/archived/SPRINT_6000_SUMMARY.md
Normal file
305
docs/implplan/archived/SPRINT_6000_SUMMARY.md
Normal file
@@ -0,0 +1,305 @@
|
||||
# Sprint 6000 Series Summary: BinaryIndex Module
|
||||
|
||||
## Overview
|
||||
|
||||
The 6000 series implements the **BinaryIndex** module - a vulnerable binaries database that enables detection of vulnerable code at the binary level, independent of package metadata.
|
||||
|
||||
**Advisory Source:** `docs/product-advisories/21-Dec-2025 - Mapping Evidence Within Compiled Binaries.md`
|
||||
|
||||
---
|
||||
|
||||
## MVP Roadmap
|
||||
|
||||
### MVP 1: Known-Build Binary Catalog (Sprint 6000.0001)
|
||||
|
||||
**Goal:** Query "is this Build-ID vulnerable?" with distro-level precision.
|
||||
|
||||
| Sprint | Topic | Description |
|
||||
|--------|-------|-------------|
|
||||
| 6000.0001.0001 | Binaries Schema | PostgreSQL schema creation |
|
||||
| 6000.0001.0002 | Binary Identity Service | Core identity extraction and storage |
|
||||
| 6000.0001.0003 | Debian Corpus Connector | Debian/Ubuntu package ingestion |
|
||||
| 6000.0001.0004 | Build-ID Lookup Service | Query API for Build-ID matching |
|
||||
|
||||
**Acceptance:** Given a Build-ID, return associated CVEs from known distro builds.
|
||||
|
||||
---
|
||||
|
||||
### MVP 2: Patch-Aware Backport Handling (Sprint 6000.0002)
|
||||
|
||||
**Goal:** Handle "version says vulnerable but distro backported the fix."
|
||||
|
||||
| Sprint | Topic | Description |
|
||||
|--------|-------|-------------|
|
||||
| 6000.0002.0001 | Fix Evidence Parser | Changelog and patch header parsing |
|
||||
| 6000.0002.0002 | Fix Index Builder | Merge evidence into fix index |
|
||||
| 6000.0002.0003 | Version Comparator Integration | **Reference existing Concelier comparators** (see note below) |
|
||||
| 6000.0002.0004 | RPM Corpus Connector | RHEL/Fedora package ingestion |
|
||||
|
||||
**Acceptance:** For a CVE that upstream marks vulnerable, correctly identify distro backport as fixed.
|
||||
|
||||
> **Note (2025-12-22):** Sprint 6000.0002.0003 originally planned to implement distro-specific version comparators. However, production-ready comparators already exist in Concelier:
|
||||
> - `src/Concelier/__Libraries/StellaOps.Concelier.Merge/Comparers/Nevra.cs` (RPM)
|
||||
> - `src/Concelier/__Libraries/StellaOps.Concelier.Merge/Comparers/DebianEvr.cs` (Debian/Ubuntu)
|
||||
> - `src/Concelier/__Libraries/StellaOps.Concelier.Merge/Comparers/ApkVersion.cs` (Alpine, via SPRINT_2000_0003_0001)
|
||||
>
|
||||
> This sprint should instead:
|
||||
> 1. Create a shared `StellaOps.VersionComparison` library extracting existing comparators
|
||||
> 2. Reference this library from BinaryIndex.FixIndex
|
||||
> 3. Add proof-line generation per SPRINT_4000_0002_0001
|
||||
>
|
||||
> See also:
|
||||
> - SPRINT_2000_0003_0001 (Alpine connector/comparator)
|
||||
> - SPRINT_2000_0003_0002 (Comprehensive version tests)
|
||||
> - SPRINT_4000_0002_0001 (Backport UX explainability)
|
||||
|
||||
---
|
||||
|
||||
### MVP 3: Binary Fingerprint Factory (Sprint 6000.0003)
|
||||
|
||||
**Goal:** Detect vulnerable code independent of package metadata.
|
||||
|
||||
| Sprint | Topic | Description |
|
||||
|--------|-------|-------------|
|
||||
| 6000.0003.0001 | Fingerprint Storage | Database and blob storage for fingerprints |
|
||||
| 6000.0003.0002 | Reference Build Pipeline | Generate vulnerable/fixed reference builds |
|
||||
| 6000.0003.0003 | Fingerprint Generator | Extract function fingerprints from binaries |
|
||||
| 6000.0003.0004 | Fingerprint Matching Engine | Similarity search and matching |
|
||||
| 6000.0003.0005 | Validation Corpus | Golden corpus for fingerprint validation |
|
||||
|
||||
**Acceptance:** Detect CVE in stripped binary with no package metadata, confidence > 0.95.
|
||||
|
||||
---
|
||||
|
||||
### MVP 4: Scanner Integration (Sprint 6000.0004)
|
||||
|
||||
**Goal:** Binary evidence in production scans.
|
||||
|
||||
| Sprint | Topic | Description |
|
||||
|--------|-------|-------------|
|
||||
| 6000.0004.0001 | Scanner Worker Integration | Wire BinaryIndex into scan pipeline |
|
||||
| 6000.0004.0002 | Findings Ledger Integration | Record binary matches as findings |
|
||||
| 6000.0004.0003 | Proof Segment Attestation | DSSE attestations for binary evidence |
|
||||
| 6000.0004.0004 | CLI Binary Match Inspection | CLI commands for match inspection |
|
||||
|
||||
**Acceptance:** Container scan produces binary match findings with evidence chain.
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph MVP1["MVP 1: Known-Build Catalog"]
|
||||
S6001[6000.0001.0001<br/>Schema]
|
||||
S6002[6000.0001.0002<br/>Identity Service]
|
||||
S6003[6000.0001.0003<br/>Debian Connector]
|
||||
S6004[6000.0001.0004<br/>Build-ID Lookup]
|
||||
|
||||
S6001 --> S6002
|
||||
S6002 --> S6003
|
||||
S6002 --> S6004
|
||||
S6003 --> S6004
|
||||
end
|
||||
|
||||
subgraph MVP2["MVP 2: Patch-Aware"]
|
||||
S6011[6000.0002.0001<br/>Fix Parser]
|
||||
S6012[6000.0002.0002<br/>Fix Index Builder]
|
||||
S6013[6000.0002.0003<br/>Version Comparators]
|
||||
S6014[6000.0002.0004<br/>RPM Connector]
|
||||
|
||||
S6011 --> S6012
|
||||
S6013 --> S6012
|
||||
S6012 --> S6014
|
||||
end
|
||||
|
||||
subgraph MVP3["MVP 3: Fingerprints"]
|
||||
S6021[6000.0003.0001<br/>FP Storage]
|
||||
S6022[6000.0003.0002<br/>Ref Build Pipeline]
|
||||
S6023[6000.0003.0003<br/>FP Generator]
|
||||
S6024[6000.0003.0004<br/>Matching Engine]
|
||||
S6025[6000.0003.0005<br/>Validation Corpus]
|
||||
|
||||
S6021 --> S6023
|
||||
S6022 --> S6023
|
||||
S6023 --> S6024
|
||||
S6024 --> S6025
|
||||
end
|
||||
|
||||
subgraph MVP4["MVP 4: Integration"]
|
||||
S6031[6000.0004.0001<br/>Scanner Integration]
|
||||
S6032[6000.0004.0002<br/>Findings Ledger]
|
||||
S6033[6000.0004.0003<br/>Attestations]
|
||||
S6034[6000.0004.0004<br/>CLI]
|
||||
|
||||
S6031 --> S6032
|
||||
S6032 --> S6033
|
||||
S6031 --> S6034
|
||||
end
|
||||
|
||||
MVP1 --> MVP2
|
||||
MVP1 --> MVP3
|
||||
MVP2 --> MVP4
|
||||
MVP3 --> MVP4
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Module Structure
|
||||
|
||||
```
|
||||
src/BinaryIndex/
|
||||
├── StellaOps.BinaryIndex.WebService/ # API service
|
||||
├── StellaOps.BinaryIndex.Worker/ # Corpus ingestion worker
|
||||
├── __Libraries/
|
||||
│ ├── StellaOps.BinaryIndex.Core/ # Domain models, interfaces
|
||||
│ ├── StellaOps.BinaryIndex.Persistence/ # PostgreSQL + RustFS
|
||||
│ ├── StellaOps.BinaryIndex.Corpus/ # Corpus connector framework
|
||||
│ ├── StellaOps.BinaryIndex.Corpus.Debian/ # Debian connector
|
||||
│ ├── StellaOps.BinaryIndex.Corpus.Rpm/ # RPM connector
|
||||
│ ├── StellaOps.BinaryIndex.FixIndex/ # Patch-aware fix index
|
||||
│ └── StellaOps.BinaryIndex.Fingerprints/ # Fingerprint generation
|
||||
└── __Tests/
|
||||
├── StellaOps.BinaryIndex.Core.Tests/
|
||||
├── StellaOps.BinaryIndex.Persistence.Tests/
|
||||
├── StellaOps.BinaryIndex.Corpus.Tests/
|
||||
└── StellaOps.BinaryIndex.Integration.Tests/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Interfaces
|
||||
|
||||
```csharp
|
||||
// Query interface (consumed by Scanner.Worker)
|
||||
public interface IBinaryVulnerabilityService
|
||||
{
|
||||
Task<ImmutableArray<BinaryVulnMatch>> LookupByIdentityAsync(BinaryIdentity identity, CancellationToken ct);
|
||||
Task<ImmutableArray<BinaryVulnMatch>> LookupByFingerprintAsync(CodeFingerprint fp, CancellationToken ct);
|
||||
Task<FixRecord?> GetFixStatusAsync(string distro, string release, string sourcePkg, string cveId, CancellationToken ct);
|
||||
}
|
||||
|
||||
// Corpus connector interface
|
||||
public interface IBinaryCorpusConnector
|
||||
{
|
||||
string ConnectorId { get; }
|
||||
Task<CorpusSnapshot> FetchSnapshotAsync(CorpusQuery query, CancellationToken ct);
|
||||
IAsyncEnumerable<ExtractedBinary> ExtractBinariesAsync(PackageReference pkg, CancellationToken ct);
|
||||
}
|
||||
|
||||
// Fix index interface
|
||||
public interface IFixIndexBuilder
|
||||
{
|
||||
Task BuildIndexAsync(DistroRelease distro, CancellationToken ct);
|
||||
Task<FixRecord?> GetFixRecordAsync(string distro, string release, string sourcePkg, string cveId, CancellationToken ct);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Database Schema
|
||||
|
||||
Schema: `binaries`
|
||||
Owner: BinaryIndex module
|
||||
|
||||
**Key Tables:**
|
||||
|
||||
| Table | Purpose |
|
||||
|-------|---------|
|
||||
| `binary_identity` | Known binary identities (Build-ID, hashes) |
|
||||
| `binary_package_map` | Binary → package mapping per snapshot |
|
||||
| `vulnerable_buildids` | Build-IDs known to be vulnerable |
|
||||
| `cve_fix_index` | Patch-aware fix status per distro |
|
||||
| `vulnerable_fingerprints` | Function fingerprints for CVEs |
|
||||
| `fingerprint_matches` | Match results (findings evidence) |
|
||||
|
||||
See: `docs/db/schemas/binaries_schema_specification.md`
|
||||
|
||||
---
|
||||
|
||||
## Integration Points
|
||||
|
||||
### Scanner.Worker
|
||||
|
||||
```csharp
|
||||
// During binary extraction
|
||||
var identity = await _featureExtractor.ExtractIdentityAsync(binaryStream, ct);
|
||||
var matches = await _binaryVulnService.LookupByIdentityAsync(identity, ct);
|
||||
|
||||
// If distro known, check fix status
|
||||
var fixStatus = await _binaryVulnService.GetFixStatusAsync(
|
||||
distro, release, sourcePkg, cveId, ct);
|
||||
```
|
||||
|
||||
### Findings Ledger
|
||||
|
||||
```csharp
|
||||
public record BinaryVulnerabilityFinding : IFinding
|
||||
{
|
||||
public string MatchType { get; init; } // "fingerprint", "buildid"
|
||||
public string VulnerablePurl { get; init; }
|
||||
public string MatchedSymbol { get; init; }
|
||||
public float Similarity { get; init; }
|
||||
public string[] LinkedCves { get; init; }
|
||||
}
|
||||
```
|
||||
|
||||
### Policy Engine
|
||||
|
||||
New proof segment type: `binary_fingerprint_evidence`
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
```yaml
|
||||
binaryindex:
|
||||
enabled: true
|
||||
corpus:
|
||||
connectors:
|
||||
- type: debian
|
||||
enabled: true
|
||||
releases: [bookworm, bullseye, jammy, noble]
|
||||
fingerprinting:
|
||||
enabled: true
|
||||
target_components: [openssl, glibc, zlib, curl]
|
||||
lookup:
|
||||
cache_ttl: 3600
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
### MVP 1
|
||||
- [ ] `binaries` schema deployed and migrated
|
||||
- [ ] Debian/Ubuntu corpus ingestion operational
|
||||
- [ ] Build-ID lookup returns CVEs with < 100ms p95 latency
|
||||
|
||||
### MVP 2
|
||||
- [ ] Fix index correctly handles Debian/RHEL backports
|
||||
- [ ] 95%+ accuracy on backport test corpus
|
||||
|
||||
### MVP 3
|
||||
- [ ] Fingerprints generated for OpenSSL, glibc, zlib, curl
|
||||
- [ ] < 5% false positive rate on validation corpus
|
||||
|
||||
### MVP 4
|
||||
- [ ] Scanner produces binary match findings
|
||||
- [ ] DSSE attestations include binary evidence
|
||||
- [ ] CLI `stella binary-matches` command operational
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- Architecture: `docs/modules/binaryindex/architecture.md`
|
||||
- Schema: `docs/db/schemas/binaries_schema_specification.md`
|
||||
- Advisory: `docs/product-advisories/21-Dec-2025 - Mapping Evidence Within Compiled Binaries.md`
|
||||
- Existing fingerprinting: `src/Scanner/__Libraries/StellaOps.Scanner.EntryTrace/Binary/`
|
||||
- Build-ID indexing: `src/Scanner/StellaOps.Scanner.Analyzers.Native/Index/`
|
||||
|
||||
---
|
||||
|
||||
*Document Version: 1.0.0*
|
||||
*Created: 2025-12-21*
|
||||
Reference in New Issue
Block a user