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:
23
docs2/cli/audit-pack.md
Normal file
23
docs2/cli/audit-pack.md
Normal 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
32
docs2/cli/commands.md
Normal 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
|
||||
18
docs2/cli/crypto-plugins.md
Normal file
18
docs2/cli/crypto-plugins.md
Normal 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
32
docs2/cli/crypto.md
Normal 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
|
||||
18
docs2/cli/distribution-matrix.md
Normal file
18
docs2/cli/distribution-matrix.md
Normal 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
|
||||
22
docs2/cli/keyboard-shortcuts.md
Normal file
22
docs2/cli/keyboard-shortcuts.md
Normal 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
36
docs2/cli/overview.md
Normal 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
31
docs2/cli/reachability.md
Normal 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
20
docs2/cli/sbomer.md
Normal 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
19
docs2/cli/score-proofs.md
Normal 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
19
docs2/cli/triage.md
Normal 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
|
||||
26
docs2/cli/troubleshooting.md
Normal file
26
docs2/cli/troubleshooting.md
Normal 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
19
docs2/cli/unknowns.md
Normal 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
|
||||
Reference in New Issue
Block a user