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>
2025-12-23 18:20:00 +02:00
parent b444284be5
commit dac8e10e36
241 changed files with 22567 additions and 307 deletions
--- a/docs/testing/determinism-gates.md
+++ b/docs/testing/determinism-gates.md
@@ -0,0 +1,291 @@
+# Determinism Gates
+
+Determinism is a core principle of StellaOps - all artifact generation (SBOM, VEX, attestations) must be reproducible. This document describes how to test for determinism.
+
+## Why Determinism Matters
+
+- **Reproducible builds**: Same input → same output, always
+- **Cryptographic verification**: Hash-based integrity depends on byte-for-byte reproducibility
+- **Audit trails**: Deterministic timestamps and ordering for compliance
+- **Offline operation**: No reliance on external randomness or timestamps
+
+## Using Determinism Gates
+
+Add `StellaOps.TestKit` to your test project and use the `DeterminismGate` class:
+
+```csharp
+using StellaOps.TestKit.Determinism;
+using StellaOps.TestKit.Traits;
+using Xunit;
+
+public class SbomGeneratorTests
+{
+    [Fact]
+    [UnitTest]
+    [DeterminismTest]
+    public void SbomGenerationIsDeterministic()
+    {
+        // Verify that calling the function 3 times produces identical output
+        DeterminismGate.AssertDeterministic(() =>
+        {
+            return GenerateSbom();
+        }, iterations: 3);
+    }
+
+    [Fact]
+    [UnitTest]
+    [DeterminismTest]
+    public void SbomBinaryIsDeterministic()
+    {
+        // Verify binary reproducibility
+        DeterminismGate.AssertDeterministic(() =>
+        {
+            return GenerateSbomBytes();
+        }, iterations: 3);
+    }
+}
+```
+
+## JSON Determinism
+
+JSON output must have:
+- Stable property ordering (alphabetical or schema-defined)
+- Consistent whitespace/formatting
+- No random IDs or timestamps (unless explicitly from deterministic clock)
+
+```csharp
+[Fact]
+[UnitTest]
+[DeterminismTest]
+public void VexDocumentJsonIsDeterministic()
+{
+    // Verifies JSON canonicalization and property ordering
+    DeterminismGate.AssertJsonDeterministic(() =>
+    {
+        var vex = GenerateVexDocument();
+        return JsonSerializer.Serialize(vex);
+    });
+}
+
+[Fact]
+[UnitTest]
+[DeterminismTest]
+public void VerdictObjectIsDeterministic()
+{
+    // Verifies object serialization is deterministic
+    DeterminismGate.AssertJsonDeterministic(() =>
+    {
+        return GenerateVerdict();
+    });
+}
+```
+
+## Canonical Equality
+
+Compare two objects for canonical equivalence:
+
+```csharp
+[Fact]
+[UnitTest]
+public void VerdictFromDifferentPathsAreCanonicallyEqual()
+{
+    var verdict1 = GenerateVerdictFromSbom();
+    var verdict2 = GenerateVerdictFromCache();
+
+    // Asserts that both produce identical canonical JSON
+    DeterminismGate.AssertCanonicallyEqual(verdict1, verdict2);
+}
+```
+
+## Hash-Based Regression Testing
+
+Compute stable hashes for regression detection:
+
+```csharp
+[Fact]
+[UnitTest]
+[DeterminismTest]
+public void SbomHashMatchesBaseline()
+{
+    var sbom = GenerateSbom();
+    var hash = DeterminismGate.ComputeHash(sbom);
+
+    // This hash should NEVER change unless SBOM format changes intentionally
+    const string expectedHash = "abc123...";
+    Assert.Equal(expectedHash, hash);
+}
+```
+
+## Path Ordering
+
+File paths in manifests must be sorted:
+
+```csharp
+[Fact]
+[UnitTest]
+[DeterminismTest]
+public void SbomFilePathsAreSorted()
+{
+    var sbom = GenerateSbom();
+    var filePaths = ExtractFilePaths(sbom);
+
+    // Asserts paths are in deterministic (lexicographic) order
+    DeterminismGate.AssertSortedPaths(filePaths);
+}
+```
+
+## Timestamp Validation
+
+All timestamps must be UTC ISO 8601:
+
+```csharp
+[Fact]
+[UnitTest]
+[DeterminismTest]
+public void AttestationTimestampIsUtcIso8601()
+{
+    var attestation = GenerateAttestation();
+
+    // Asserts timestamp is UTC with 'Z' suffix
+    DeterminismGate.AssertUtcIso8601(attestation.Timestamp);
+}
+```
+
+## Determin
+
+istic Time in Tests
+
+Use `DeterministicClock` for reproducible timestamps:
+
+```csharp
+using StellaOps.TestKit.Time;
+
+[Fact]
+[UnitTest]
+[DeterminismTest]
+public void AttestationWithDeterministicTime()
+{
+    var clock = new DeterministicClock();
+
+    // All operations using this clock will get the same time
+    var attestation1 = GenerateAttestation(clock);
+    var attestation2 = GenerateAttestation(clock);
+
+    Assert.Equal(attestation1.Timestamp, attestation2.Timestamp);
+}
+```
+
+## Deterministic Random in Tests
+
+Use `DeterministicRandom` for reproducible randomness:
+
+```csharp
+using StellaOps.TestKit.Random;
+
+[Fact]
+[UnitTest]
+[DeterminismTest]
+public void GeneratedIdsAreReproducible()
+{
+    var rng1 = DeterministicRandomExtensions.WithTestSeed();
+    var id1 = GenerateId(rng1);
+
+    var rng2 = DeterministicRandomExtensions.WithTestSeed();
+    var id2 = GenerateId(rng2);
+
+    // Same seed → same output
+    Assert.Equal(id1, id2);
+}
+```
+
+## Module-Specific Gates
+
+### Scanner Determinism
+- SBOM file path ordering
+- Component hash stability
+- Dependency graph ordering
+
+### Concelier Determinism
+- Advisory normalization (same advisory → same canonical form)
+- Vulnerability merge determinism
+- No lattice ordering dependencies
+
+### Excititor Determinism
+- VEX document format stability
+- Preserve/prune decision ordering
+- No lattice dependencies
+
+### Policy Determinism
+- Verdict reproducibility (same inputs → same verdict)
+- Policy evaluation ordering
+- Unknown budget calculations
+
+### Attestor Determinism
+- DSSE envelope canonical bytes
+- Signature ordering (multiple signers)
+- Rekor receipt stability
+
+## Common Determinism Violations
+
+❌ **Timestamps from system clock**
+```csharp
+// Bad: Uses system time
+var timestamp = DateTimeOffset.UtcNow.ToString("o");
+
+// Good: Uses injected clock
+var timestamp = clock.UtcNow.ToString("o");
+```
+
+❌ **Random GUIDs**
+```csharp
+// Bad: Non-deterministic
+var id = Guid.NewGuid().ToString();
+
+// Good: Deterministic or content-addressed
+var id = ComputeContentHash(data);
+```
+
+❌ **Unordered collections**
+```csharp
+// Bad: Dictionary iteration order is undefined
+foreach (var (key, value) in dict) { ... }
+
+// Good: Explicit ordering
+foreach (var (key, value) in dict.OrderBy(x => x.Key)) { ... }
+```
+
+❌ **Floating-point comparisons**
+```csharp
+// Bad: Floating-point can differ across platforms
+var score = 0.1 + 0.2;  // Might not equal 0.3 exactly
+
+// Good: Use fixed-point or integers
+var scoreInt = (int)((0.1 + 0.2) * 1000);
+```
+
+❌ **Non-UTC timestamps**
+```csharp
+// Bad: Timezone-dependent
+var timestamp = DateTime.Now.ToString();
+
+// Good: Always UTC with 'Z'
+var timestamp = DateTimeOffset.UtcNow.ToString("o");
+```
+
+## Determinism Test Checklist
+
+When writing determinism tests, verify:
+
+- [ ] Multiple invocations produce identical output
+- [ ] JSON has stable property ordering
+- [ ] File paths are sorted lexicographically
+- [ ] Timestamps are UTC ISO 8601 with 'Z' suffix
+- [ ] No random GUIDs (use content-addressing)
+- [ ] Collections are explicitly ordered
+- [ ] No system time/random usage (use DeterministicClock/DeterministicRandom)
+
+## Related Documentation
+
+- TestKit README: `src/__Libraries/StellaOps.TestKit/README.md`
+- Testing Strategy: `docs/testing/testing-strategy-models.md`
+- Test Catalog: `docs/testing/TEST_CATALOG.yml`