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
2025-12-23 18:20:00 +02:00
parent b444284be5
commit dac8e10e36
241 changed files with 22567 additions and 307 deletions

23
docs2/cli/audit-pack.md Normal file
View File

@@ -0,0 +1,23 @@
# Audit pack CLI
Audit pack commands
- audit-pack export: export audit packs for a scan.
- audit-pack verify: verify hashes and signatures.
- audit-pack info: show pack metadata and contents.
- audit-pack replay: replay a scan and compare verdicts.
- audit-pack verify-and-replay: combined workflow.
Typical workflow
1) Export and sign an audit pack.
2) Transfer to the offline environment.
3) Verify hashes and signatures.
4) Replay and compare verdict digests.
Environment variables
- STELLAOPS_AUDIT_PACK_VERIFY_SIGS controls signature verification default.
- STELLAOPS_AUDIT_PACK_TRUST_ROOTS points to trust roots.
- STELLAOPS_OFFLINE_BUNDLE provides offline inputs for replay.
Related references
- docs/cli/audit-pack-commands.md
- docs2/operations/replay-and-determinism.md

32
docs2/cli/commands.md Normal file
View File

@@ -0,0 +1,32 @@
# CLI command groups
Global options
- --tenant sets tenant context for all commands.
- --verbose enables verbose output.
- --help and --version are available everywhere.
Core groups
- scan: scan images and emit SBOMs and attestations.
- sbomer: offline SBOM layer, compose, and drift utilities.
- policy: lint, simulate, approve, and replay policy decisions.
- vex and advisory: ingest and inspect observations and linksets.
- reachability: compute and explain reachability results.
- score: compute and replay scoring with proof bundles.
- triage: list, show, decide, and export findings.
- unknowns: triage unresolved identities and edges.
- downloads and offline: export and verify bundles, offline kit flows.
- auth and admin: login, tokens, and admin operations.
Output formats
- Most commands support table, json, yaml, and sarif formats where applicable.
- Deterministic ordering is required for json and yaml outputs.
Offline posture
- Use offline bundles and preloaded feeds for air-gapped workflows.
- Avoid network calls when STELLAOPS_OFFLINE or equivalent flags are set.
Related references
- docs/cli/command-reference.md
- docs/cli/admin-reference.md
- docs/cli/audit-pack-commands.md
- docs2/cli/crypto.md

View File

@@ -0,0 +1,18 @@
# CLI crypto plugins
Plugin model
- Providers implement ICryptoProvider with SignAsync and VerifyAsync.
- Providers declare Name and SupportedAlgorithms.
- Optional diagnostics interface exposes health checks and metadata.
Key references
- CryptoKeyReference describes key id, source, and parameters.
- CryptoKeyInfo exposes key metadata and signing capabilities.
Registration
- Plugins are registered via DI in the CLI host.
- Provider selection uses the --provider flag or profile defaults.
Related references
- docs/cli/crypto-plugins.md
- docs2/cli/crypto.md

32
docs2/cli/crypto.md Normal file
View File

@@ -0,0 +1,32 @@
# CLI crypto and compliance
Crypto commands
- crypto sign: sign files with a selected provider and algorithm.
- crypto verify: verify signatures with provider and trust policy.
- crypto profiles: list providers and run diagnostics.
Distribution matrix (summary)
- International: default providers only.
- Russia: adds GOST providers (build flag StellaOpsEnableGOST).
- EU: adds eIDAS providers (build flag StellaOpsEnableEIDAS).
- China: adds SM providers (build flag StellaOpsEnableSM).
Compliance notes
- Use the regional build that matches the deployment jurisdiction.
- Regional providers may require licensed CSPs or remote TSP endpoints.
Configuration
- Profiles select preferred providers and key sources.
- Provider credentials use environment variables or config files.
- DSSE is the default signing format for bundles and manifests.
Plugin development (summary)
- Providers implement ICryptoProvider with SignAsync and VerifyAsync.
- Optional diagnostics interface provides health checks.
Related references
- docs/cli/crypto-commands.md
- docs/cli/crypto-plugins.md
- docs/cli/compliance-guide.md
- docs/cli/distribution-matrix.md
- docs2/security/crypto-compliance.md

View File

@@ -0,0 +1,18 @@
# CLI distribution matrix
Regional distributions
- International: default crypto providers only.
- Russia: adds GOST providers (build flag StellaOpsEnableGOST).
- EU: adds eIDAS providers (build flag StellaOpsEnableEIDAS).
- China: adds SM providers (build flag StellaOpsEnableSM).
Build notes
- Use deterministic publish settings for reproducible binaries.
- Flags control inclusion of provider projects at build time.
Supported platforms (typical)
- linux-x64, linux-arm64, osx-x64, osx-arm64, win-x64.
Related references
- docs/cli/distribution-matrix.md
- docs2/cli/crypto.md

View File

@@ -0,0 +1,22 @@
# CLI keyboard shortcuts
Interactive triage shortcuts
- j/k: next/previous finding.
- a/n/w/f: mark affected, not affected, wont_fix, false_positive.
- e: toggle evidence view.
- g: toggle graph view.
- /: search.
- q: save and quit.
Batch mode shortcuts
- PageUp/PageDown: skip blocks of findings.
- u: undo last decision.
- ?: help.
Accessibility
- All actions have non-shortcut menu equivalents.
- Shortcuts can be disabled in config.
Related references
- docs/cli/keyboard-shortcuts.md
- docs2/ui/accessibility.md

36
docs2/cli/overview.md Normal file
View File

@@ -0,0 +1,36 @@
# CLI overview
The stella CLI is the primary command-line interface for scans, evidence export,
policy workflows, and offline operations.
Core command groups
- scan and sbom: scanning, SBOM generation, and attestations.
- policy: lint, simulate, approve, and replay policy decisions.
- vex and advisory: ingest and inspect observations and linksets.
- reachability and smart-diff: reachability evidence and change detection.
- downloads and offline: bundle export, verify, and import.
- auth and admin: login, tokens, and administrative operations.
Authentication
- Interactive login uses OAuth and DPoP when configured.
- Offline tokens are supported for air-gapped operations.
Configuration
- Config files load in order: system, user, project, then env vars.
- STELLAOPS_* environment variables override file settings.
Offline usage
- Export bundles and verify hashes before transfer.
- Use offline kits for feeds, policies, and revocation bundles.
Related references
- docs/cli/README.md
- docs/cli/command-reference.md
- docs/cli/reachability-cli-reference.md
- docs/cli/unknowns-cli-reference.md
- docs/cli/triage-cli.md
- docs2/cli/commands.md
- docs2/cli/crypto.md
- docs2/cli/reachability.md
- docs2/cli/triage.md
- docs2/cli/unknowns.md

31
docs2/cli/reachability.md Normal file
View File

@@ -0,0 +1,31 @@
# Reachability, drift, and smart-diff CLI
Reachability commands
- reachability compute: compute reachability for a scan or graph snapshot.
- reachability findings: list reachability findings with filters.
- reachability explain: explain a finding and show paths.
- reachability summary and job status/logs for batch workflows.
Common options
- --scan-id selects the scan.
- --offline uses local bundles and caches.
- --output-format supports table, json, yaml, sarif.
Drift commands
- drift compare: compare reachability between base and head scans.
- drift show: display a saved drift result.
- Filters include severity, risk increases only, and output format.
Smart-diff commands
- smart-diff compares two artifacts and reports material risk changes.
- Output supports table, json, yaml, and sarif plus bundle output.
- Options include min-priority, tier filters, and offline feed dirs.
Proofs and verification
- smart-diff verify validates proof bundles and signatures.
- Use public keys or trust policy for verification.
Related references
- docs/cli/reachability-cli-reference.md
- docs/cli/drift-cli.md
- docs/cli/smart-diff-cli.md

20
docs2/cli/sbomer.md Normal file
View File

@@ -0,0 +1,20 @@
# SBOMer CLI
SBOMer commands
- sbomer layer: emit deterministic SBOM per layer.
- sbomer compose: merge layer SBOMs with stable ordering.
- sbomer drift: compute SBOM drift with ordered diffs.
- sbomer verify: validate SBOM hash and signatures.
Determinism rules
- Stable sort keys for components and edges.
- Fixed timestamps unless overridden.
- UTF-8, LF line endings, no BOM.
Offline posture
- Preload images and registries.
- Use STELLA_SBOMER_OFFLINE to block network pulls.
Related references
- docs/cli/sbomer.md
- docs2/sbom/overview.md

19
docs2/cli/score-proofs.md Normal file
View File

@@ -0,0 +1,19 @@
# Score proofs CLI
Score commands
- score compute: compute scores for a scan.
- score replay: replay scoring with specified feed or policy snapshots.
- score show: show score breakdown and evidence refs.
- score diff: compare score runs.
- score manifest and score inputs: inspect inputs and manifests.
Determinism
- Deterministic mode is default; optional fixed seed supported.
- Replay with original snapshots yields reproducible outputs.
Offline workflows
- Use --offline and --bundle for air-gapped replay.
Related references
- docs/cli/score-proofs-cli-reference.md
- docs2/security/risk-model.md

19
docs2/cli/triage.md Normal file
View File

@@ -0,0 +1,19 @@
# Triage CLI
Triage commands
- triage list: list findings with status and priority filters.
- triage show: show details with evidence and history.
- triage decide: record a decision with justification.
- triage batch: interactive batch triage mode.
- triage export: export findings for offline review.
Offline workflows
- Use --workspace to point to offline bundles.
- Export bundles with evidence and graph data for air-gapped review.
Interactive shortcuts
- j/k for navigation, a/n/w/f for decisions, e for evidence, q to save.
Related references
- docs/cli/triage-cli.md
- docs2/cli/keyboard-shortcuts.md

View File

@@ -0,0 +1,26 @@
# CLI troubleshooting
Authentication issues
- Verify Backend.BaseUrl and Authority reachability.
- Re-login when tokens expire or scopes are missing.
- Use API key auth for headless automation when allowed.
Crypto provider issues
- Ensure the correct regional build is installed.
- Verify provider configuration and key container paths.
- Use crypto profiles diagnostics to test provider health.
Build and distribution issues
- Confirm the expected build flags for regional plugins.
- Validate distribution metadata using stella --version.
Scanning and network issues
- Confirm registry access and offline cache settings.
- Use offline bundles when network is restricted.
Permissions and scopes
- Ensure the token includes required scopes for admin or policy commands.
Related references
- docs/cli/troubleshooting.md
- docs2/cli/crypto.md

19
docs2/cli/unknowns.md Normal file
View File

@@ -0,0 +1,19 @@
# Unknowns CLI
Unknowns commands
- unknowns list: list unknowns with filters and pagination.
- unknowns show: show details for an unknown id.
- unknowns summary: aggregate by status and category.
- unknowns escalate, resolve, suppress: update status with rationale.
- unknowns export and import: move triage results offline.
Filters and categories
- Filter by status, category, score, age, and purl patterns.
- Categories include unmapped_purl, checksum_miss, parsing_failure, language_gap.
Offline posture
- Export unknowns for offline triage and re-import results.
Related references
- docs/cli/unknowns-cli-reference.md
- docs2/signals/unknowns.md