save checkpoint: save features
This commit is contained in:
master
@@ -1,28 +0,0 @@
|
||||
# Air-Gap Bundle System (DSSE-Signed Bundle Format with Import/Export)
|
||||
|
||||
## Module
|
||||
AirGap
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Comprehensive air-gap bundle system with DSSE signing and verification, bundle format with schemas/validation/trust snapshots, controller for state management, importer with quarantine-on-failure, atomic feed activation with rollback, file-based and router-based delivery transport, and offline kit validation (monotonicity checking, telemetry metrics). Covers offline update kits (OUK), replay packs, and audit pack export/import.
|
||||
|
||||
## Implementation Details
|
||||
- **Controller**: `src/AirGap/StellaOps.AirGap.Controller/` -- state management (`AirGapState.cs`, `AirGapStateService.cs`), endpoints (`AirGapEndpoints.cs` with seal/verify), startup options, telemetry
|
||||
- **Importer**: `src/AirGap/StellaOps.AirGap.Importer/` -- bundle planning (`BundleImportPlanner.cs`), quarantine on failure (`FileSystemQuarantineService.cs`, `IQuarantineService.cs`), evidence reconciliation (`EvidenceReconciler.cs`, `EvidenceGraph.cs`), SBOM/DSSE parsers, version monotonicity, trust root config, replay verification
|
||||
- **Bundle library**: `src/AirGap/__Libraries/StellaOps.AirGap.Bundle/` -- bundle format, schema validation, trust snapshot management
|
||||
- **Sync library**: `src/AirGap/__Libraries/StellaOps.AirGap.Sync/` -- synchronization for bundle delivery
|
||||
- **Persistence**: `src/AirGap/__Libraries/StellaOps.AirGap.Persistence/` and `src/AirGap/StellaOps.AirGap.Storage.Postgres/`
|
||||
- **Policy**: `src/AirGap/StellaOps.AirGap.Policy/` -- offline verification policy, analyzers
|
||||
- **Tests**: Controller, Importer, Persistence, Sync, Time, and Policy tests under `src/AirGap/__Tests/`
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Test bundle import with valid DSSE-signed bundle, verify state transition
|
||||
- [ ] Test quarantine behavior on invalid bundle signature
|
||||
- [ ] Test monotonicity check rejects older bundle version
|
||||
- [ ] Test evidence reconciliation correctly parses CycloneDx, DSSE attestations
|
||||
- [ ] Test atomic feed activation and rollback on failure
|
||||
- [ ] Verify bundle import planning produces correct plan
|
||||
@@ -1,25 +0,0 @@
|
||||
# Air-Gap Epistemic Mode with Sealed Startup and Feed Snapshots
|
||||
|
||||
## Module
|
||||
AirGap
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Full epistemic completeness for air-gapped environments: sealed startup validation, feed snapshot repositories, signed mirror connectors, cryptographic binding of knowledge state to scan results, snapshot management, and sealed install enforcement.
|
||||
|
||||
## Implementation Details
|
||||
- **Sealed startup**: `src/AirGap/StellaOps.AirGap.Controller/Services/AirGapStartupDiagnosticsHostedService.cs` -- validates sealed state at startup
|
||||
- **Startup options**: `src/AirGap/StellaOps.AirGap.Controller/Options/AirGapStartupOptions.cs` -- sealed startup configuration
|
||||
- **State management**: `src/AirGap/StellaOps.AirGap.Controller/Domain/AirGapState.cs`, `Services/AirGapStateService.cs`
|
||||
- **State stores**: `src/AirGap/StellaOps.AirGap.Controller/Stores/IAirGapStateStore.cs`, `InMemoryAirGapStateStore.cs`
|
||||
- **Feed snapshots**: `src/AirGap/__Libraries/StellaOps.AirGap.Bundle/` -- snapshot management in bundle library
|
||||
- **Offline verification**: `src/AirGap/StellaOps.AirGap.Importer/Policy/OfflineVerificationPolicy.cs`, `OfflineVerificationPolicyLoader.cs`
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify sealed startup validation prevents operation with incomplete knowledge state
|
||||
- [ ] Test feed snapshot loading and cryptographic binding
|
||||
- [ ] Verify state transitions in air-gap controller
|
||||
- [ ] Test offline verification policy enforcement
|
||||
@@ -1,25 +0,0 @@
|
||||
# Deterministic Rekor Receipts with Offline Verification
|
||||
|
||||
## Module
|
||||
AirGap
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Offline Rekor receipt verifier validates checkpoint signatures (ECDSA/Ed25519), Merkle inclusion proofs per RFC 6962, and root hash consistency without live transparency log access. Includes TileProxy for local tile-based transparency log proxy, and mirror snapshot resolution for air-gapped deployments.
|
||||
|
||||
## Implementation Details
|
||||
- **Rekor proof builder**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Rekor/EnhancedRekorProofBuilder.Build.cs`, `EnhancedRekorProofBuilder.Validate.cs`, `EnhancedRekorProofBuilder.cs`
|
||||
- **Rekor inclusion proof**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Rekor/RekorInclusionProof.cs`
|
||||
- **Rekor verification step**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Verification/RekorInclusionVerificationStep.cs`
|
||||
- **Replay verification**: `src/AirGap/StellaOps.AirGap.Controller/Services/ReplayVerificationService.cs`
|
||||
- **Importer replay**: `src/AirGap/StellaOps.AirGap.Importer/Contracts/ReplayVerificationRequest.cs`, `ReplayDepth.cs`
|
||||
- **Merkle proofs**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Merkle/DeterministicMerkleTreeBuilder.Proof.cs`, `MerkleProof.cs`
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify Rekor receipt offline verification validates checkpoint signatures (ECDSA/Ed25519)
|
||||
- [ ] Test Merkle inclusion proof verification per RFC 6962
|
||||
- [ ] Test root hash consistency verification without live transparency log
|
||||
- [ ] Verify replay verification service works in air-gapped mode
|
||||
@@ -1,25 +0,0 @@
|
||||
# Deterministic Replay and Verification in Air-Gap Mode
|
||||
|
||||
## Module
|
||||
AirGap
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Replay manifests capturing input artifacts, verification results, and media types for deterministic reproducibility. Replay verification service for air-gapped environments. Covers offline cryptography plugins and importer validation.
|
||||
|
||||
## Implementation Details
|
||||
- **Replay verification service**: `src/AirGap/StellaOps.AirGap.Controller/Services/ReplayVerificationService.cs`
|
||||
- **Replay contracts**: `src/AirGap/StellaOps.AirGap.Importer/Contracts/ReplayVerificationRequest.cs`, `ReplayDepth.cs`
|
||||
- **Attestor replay**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Replay/ReplayInputArtifact.cs`, `ReplayResult.cs`, `ReplayStatus.cs`, `ReplayVerificationResult.cs`, `ReplayPromptTemplate.cs`
|
||||
- **Offline crypto**: `src/Cryptography/StellaOps.Cryptography.Plugin/CryptoPluginBase.cs` and plugin implementations (GOST, eIDAS, SM, FIPS, HSM)
|
||||
- **Evidence reconciliation**: `src/AirGap/StellaOps.AirGap.Importer/Reconciliation/` -- EvidenceReconciler, EvidenceGraph, JSON normalizer, attestation/SBOM parsers
|
||||
- **Importer validation**: `src/AirGap/StellaOps.AirGap.Importer/Validation/` -- bundle validation
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify replay manifests capture all input artifacts with media types
|
||||
- [ ] Test replay verification produces identical results from same inputs
|
||||
- [ ] Test evidence reconciliation correctly builds evidence graph
|
||||
- [ ] Verify offline crypto plugin signing/verification works without network
|
||||
@@ -1,24 +0,0 @@
|
||||
# Deterministic Test Harness (Frozen Time, Seeded RNG, Network Isolation)
|
||||
|
||||
## Module
|
||||
AirGap
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Deterministic testing infrastructure with frozen time providers, deterministic fixtures, and Testcontainers for PostgreSQL isolation across backend and frontend.
|
||||
|
||||
## Implementation Details
|
||||
- **Test infrastructure**: `src/__Tests/__Libraries/StellaOps.Testing.Chaos/Models.cs` -- chaos/deterministic testing models
|
||||
- **AirGap tests**: `src/AirGap/__Tests/` -- Controller, Importer, Persistence, Sync, Time tests
|
||||
- **Frozen time**: `src/AirGap/StellaOps.AirGap.Time/` -- time anchor services with frozen time providers, staleness calculation
|
||||
- **Time fixtures**: `src/AirGap/StellaOps.AirGap.Time/fixtures/` -- deterministic time test fixtures
|
||||
- **Testcontainers**: PostgreSQL isolation via `src/AirGap/StellaOps.AirGap.Storage.Postgres.Tests/`
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify frozen time providers produce deterministic timestamps
|
||||
- [ ] Test seeded RNG produces reproducible results
|
||||
- [ ] Verify Testcontainers PostgreSQL isolation works correctly
|
||||
- [ ] Test deterministic fixtures produce identical outputs across runs
|
||||
@@ -1,25 +0,0 @@
|
||||
# DSSE/Receipt Schema for Authority/Sbomer/Vexer Flows
|
||||
|
||||
## Module
|
||||
AirGap
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
DSSE envelope signing/verification across multiple modules with schema types, SPDX3 integration, and air-gap bundle signing. The receipt schema supports Authority, Sbomer, and Vexer flows.
|
||||
|
||||
## Implementation Details
|
||||
- **DSSE signing**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Signing/DsseEnvelope.cs`, `DsseSignature.cs`, `ProofChainSigner.Verification.cs`
|
||||
- **DSSE SPDX3**: `src/Attestor/__Libraries/StellaOps.Attestor.Spdx3/DsseSpdx3Envelope.cs`, `DsseSpdx3Signature.cs`, `DsseSpdx3Signer.SignAsync.cs`, `DsseSpdx3Signer.Verify.cs`
|
||||
- **DSSE verification**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Verification/DsseSignatureVerificationStep.cs`
|
||||
- **Importer DSSE parsing**: `src/AirGap/StellaOps.AirGap.Importer/Reconciliation/Parsers/DsseAttestationParser.cs`
|
||||
- **Receipt models**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Receipts/VerificationReceipt.cs`, `VerificationResult.cs`, `VerificationCheck.cs`, `VerificationContext.cs`
|
||||
- **Signing profiles**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Signing/SigningKeyProfile.cs`
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify DSSE envelope creation for Authority/Sbomer/Vexer flows
|
||||
- [ ] Test DSSE signature verification with multiple key profiles
|
||||
- [ ] Verify receipt schema captures all required verification checks
|
||||
- [ ] Test SPDX3 DSSE integration
|
||||
@@ -1,29 +0,0 @@
|
||||
# Mirror Time Anchor Contract
|
||||
|
||||
## Module
|
||||
AirGap
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Defines canonical time-anchor fields (generatedAt UTC ISO-8601, optional sourceClock hint) and staleness computation (now - generatedAt with +/-5s tolerance) for mirror bundles in air-gapped environments.
|
||||
|
||||
## Implementation Details
|
||||
- **Time anchor module**: `src/AirGap/StellaOps.AirGap.Time/` -- full module with controllers, services, parsing, models, stores, config, hooks, health checks
|
||||
- **Time anchor parsing**: `src/AirGap/StellaOps.AirGap.Time/Parsing/` -- token parsing for time anchor extraction
|
||||
- **Staleness calculation**: services compute `now - generatedAt` with tolerance handling
|
||||
- **HLC merge services**: `src/AirGap/StellaOps.AirGap.Time/Services/` -- Hybrid Logical Clock for multi-node sync
|
||||
- **Deterministic time fixtures**: `src/AirGap/StellaOps.AirGap.Time/fixtures/`
|
||||
- **Bundle integration**: `src/AirGap/__Libraries/StellaOps.AirGap.Bundle/Services/` -- TimeAnchorContent, SnapshotBundleWriter.Sections.TimeAnchor, SnapshotBundleReader.Verify.TimeAnchor
|
||||
- **Attestor timestamping**: `src/Attestor/__Libraries/StellaOps.Attestor.Timestamping/TimeCorrelationValidator.Validate.cs`, `TimeCorrelationStatus.cs`
|
||||
- **Tests**: `src/AirGap/__Tests/StellaOps.AirGap.Time.Tests/` (TimeAnchorLoaderTests, StalenessCalculatorTests, TimeVerificationServiceTests, TimeTokenParserTests, etc.)
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify time anchor is embedded in air-gap bundle with correct ISO-8601 format
|
||||
- [ ] Verify staleness calculation correctly computes age with +/-5s tolerance
|
||||
- [ ] Verify time anchor verification rejects bundles with tampered timestamps
|
||||
- [ ] Verify HLC merge produces consistent ordering across multiple nodes
|
||||
|
||||
## Related Documentation
|
||||
- Source: SPRINT_0150_0001_0002_mirror_time.md
|
||||
@@ -1,24 +0,0 @@
|
||||
# Offline Kit Metrics and Diagnostics
|
||||
|
||||
## Module
|
||||
AirGap
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Offline kit metrics, telemetry, and startup diagnostics for monitoring air-gap bundle health.
|
||||
|
||||
## Implementation Details
|
||||
- **Telemetry**: `src/AirGap/StellaOps.AirGap.Controller/Services/AirGapTelemetry.cs` -- air-gap specific telemetry
|
||||
- **Telemetry options**: `src/AirGap/StellaOps.AirGap.Controller/Options/AirGapTelemetryOptions.cs` -- telemetry configuration
|
||||
- **Startup diagnostics**: `src/AirGap/StellaOps.AirGap.Controller/Services/AirGapStartupDiagnosticsHostedService.cs` -- diagnostics at startup
|
||||
- **Importer telemetry**: `src/AirGap/StellaOps.AirGap.Importer/Telemetry/` -- import-specific metrics
|
||||
- **Status endpoints**: `src/AirGap/StellaOps.AirGap.Controller/Endpoints/Contracts/AirGapStatusResponse.cs` -- status reporting
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify AirGap status endpoint returns correct metrics
|
||||
- [ ] Test startup diagnostics detect and report issues
|
||||
- [ ] Verify telemetry captures bundle import/export operations
|
||||
- [ ] Test importer telemetry tracks import duration and outcomes
|
||||
@@ -1,32 +0,0 @@
|
||||
# Time Anchoring for Offline Environments
|
||||
|
||||
## Module
|
||||
AirGap
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Time anchoring module with anchor loader, token parser, staleness calculator, and sealed startup validation for air-gapped environments. Includes HLC (Hybrid Logical Clock) merge services for multi-node sync.
|
||||
|
||||
## Implementation Details
|
||||
- **Time module**: `src/AirGap/StellaOps.AirGap.Time/` -- dedicated time anchoring service
|
||||
- **Controllers**: `src/AirGap/StellaOps.AirGap.Time/Controllers/` -- time anchor API controllers
|
||||
- **Services**: `src/AirGap/StellaOps.AirGap.Time/Services/` -- HLC merge, staleness calculation, anchor loading
|
||||
- **Parsing**: `src/AirGap/StellaOps.AirGap.Time/Parsing/` -- time anchor token parsing
|
||||
- **Models**: `src/AirGap/StellaOps.AirGap.Time/Models/` -- time anchor data models
|
||||
- **Stores**: `src/AirGap/StellaOps.AirGap.Time/Stores/` -- time anchor state stores
|
||||
- **Config**: `src/AirGap/StellaOps.AirGap.Time/Config/` -- time anchor configuration
|
||||
- **Hooks**: `src/AirGap/StellaOps.AirGap.Time/Hooks/` -- time-related event hooks
|
||||
- **Health**: `src/AirGap/StellaOps.AirGap.Time/Health/` -- time health checks
|
||||
- **Fixtures**: `src/AirGap/StellaOps.AirGap.Time/fixtures/` -- deterministic time test data
|
||||
- **Tests**: `src/AirGap/__Tests/StellaOps.AirGap.Time.Tests/`
|
||||
- **Attestor timestamping**: `src/Attestor/__Libraries/StellaOps.Attestor.Timestamping/TimeCorrelationValidator.Validate.cs`, `TimeCorrelationStatus.cs`
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify time anchor loading from sealed bundles
|
||||
- [ ] Test token parsing extracts correct anchor timestamps
|
||||
- [ ] Test staleness calculator produces correct durations
|
||||
- [ ] Verify HLC merge service handles multi-node sync correctly
|
||||
- [ ] Test health checks report time anchor status
|
||||
@@ -1,25 +0,0 @@
|
||||
# Trust Profile Management (CLI and Bundle)
|
||||
|
||||
## Module
|
||||
AirGap
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Named trust profiles (global, eu-eidas, us-fips, bg-gov) for configuring TSA chains, signing algorithms, and verification policies per deployment context. Includes CLI commands (stella trust-profile list/apply/show) and bundle-level profile loading. Distinct from the known "Trust Anchor Management" and "Regional Crypto Profiles" which are about crypto algorithms, not deployment-context trust configuration profiles.
|
||||
|
||||
## Implementation Details
|
||||
- **Bundle trust profiles**: `src/AirGap/__Libraries/StellaOps.AirGap.Bundle/` -- named trust profile definitions and loading
|
||||
- **Trust root config**: `src/AirGap/StellaOps.AirGap.Importer/Contracts/TrustRootConfig.cs` -- trust root configuration for import verification
|
||||
- **AirGap policy**: `src/AirGap/StellaOps.AirGap.Policy/` -- policy enforcement for trust profiles, includes analyzers and tests
|
||||
- **Offline verification policy**: `src/AirGap/StellaOps.AirGap.Importer/Policy/OfflineVerificationPolicy.cs`, `OfflineVerificationPolicyLoader.cs`
|
||||
- **Trust anchor verification**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Verification/TrustAnchorVerificationStep.cs`
|
||||
- **Source**: SPRINT_20260120_029_AirGap_offline_bundle_contract.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify CLI `stella trust-profile list` shows available profiles
|
||||
- [ ] Test `stella trust-profile apply` switches active profile
|
||||
- [ ] Test `stella trust-profile show` displays profile configuration
|
||||
- [ ] Verify trust profiles configure correct TSA chains and signing algorithms
|
||||
- [ ] Test bundle-level profile loading from bundle metadata
|
||||
@@ -1,21 +0,0 @@
|
||||
# Roslyn Analyzer for Canonicalization Enforcement (STELLA0100)
|
||||
|
||||
## Module
|
||||
__Analyzers
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Custom Roslyn static analyzer (diagnostic STELLA0100) that enforces canonicalization boundaries at compile time. Detects code paths that cross resolver boundaries without proper canonicalization, preventing non-deterministic serialization from leaking into deterministic evaluation pipelines. Includes ResolverBoundaryAttribute for marking boundary methods.
|
||||
|
||||
## Implementation Details
|
||||
- **Canonicalization Boundary Analyzer**: `src/__Analyzers/StellaOps.Determinism.Analyzers/CanonicalizationBoundaryAnalyzer.cs` -- Roslyn `DiagnosticAnalyzer` registered for C# syntax; reports diagnostic `STELLA0100` when code crosses canonicalization boundaries without proper serialization guards. Analyzes method invocations and property accesses to detect non-deterministic serialization patterns at resolver boundaries.
|
||||
- **Analyzer Tests**: `src/__Analyzers/StellaOps.Determinism.Analyzers.Tests/CanonicalizationBoundaryAnalyzerTests.cs` -- unit tests verifying the analyzer correctly reports STELLA0100 diagnostics for boundary violations and does not produce false positives for correctly guarded code.
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Add the `StellaOps.Determinism.Analyzers` package to a test project and verify the STELLA0100 diagnostic is reported when a method crosses a canonicalization boundary without a serialization guard
|
||||
- [ ] Verify the analyzer produces no diagnostics for code that correctly uses canonical serializers (e.g., `LedgerCanonicalJsonSerializer`, `Rfc8785JsonCanonicalizer`)
|
||||
- [ ] Verify the analyzer integrates with `dotnet build` and causes a build warning (or error if configured via `.editorconfig`) for violations
|
||||
- [ ] Verify the analyzer does not report false positives on non-serialization code paths or methods not annotated with `ResolverBoundaryAttribute`
|
||||
- [ ] Verify the analyzer works with partial classes and cross-file method calls within the same assembly
|
||||
@@ -1,21 +0,0 @@
|
||||
# AOC Roslyn Source Analyzer (Compile-Time Contract Enforcement)
|
||||
|
||||
## Module
|
||||
Aoc
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Roslyn source analyzer that enforces ingestion contracts at compile time via diagnostic rules (AOC0001, AOC0002, AOC0003), preventing forbidden field access patterns in AOC-related code.
|
||||
|
||||
## Implementation Details
|
||||
- **Intent Analyzer**: `src/__Analyzers/StellaOps.TestKit.Analyzers/IntentAnalyzer.cs` -- Roslyn `DiagnosticAnalyzer` that enforces test intent declaration contracts. Reports AOC0001 for missing intent attributes on test methods, AOC0002 for inconsistent intent declarations across test classes, and AOC0003 for intent/naming convention mismatches.
|
||||
- **Intent Analyzer Tests**: `src/__Analyzers/StellaOps.TestKit.Analyzers.Tests/IntentAnalyzerTests.cs` -- unit tests verifying the analyzer correctly reports AOC diagnostics for missing or mismatched intent declarations and validates that properly annotated tests produce no diagnostics.
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Add the `StellaOps.TestKit.Analyzers` package to a test project and verify AOC0001 is reported for test methods missing intent attributes
|
||||
- [ ] Verify AOC0002 is reported when a test class has inconsistent intent declarations across its test methods
|
||||
- [ ] Verify AOC0003 is reported for intent/naming convention mismatches (e.g., a test named `*Integration*` with a unit test intent attribute)
|
||||
- [ ] Verify no diagnostics are reported for correctly attributed test methods following the naming convention
|
||||
- [ ] Verify the analyzer integrates with `dotnet build` and CI pipelines to catch ingestion contract violations before merge
|
||||
@@ -1,28 +0,0 @@
|
||||
# Policy trace panel ("why blocked" / "what would make it pass")
|
||||
|
||||
## Module
|
||||
Api
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Block explanation API controller, CLI explain commands, and verdict rationale renderer provide policy trace functionality explaining why artifacts are blocked and what would unblock them.
|
||||
|
||||
## Implementation Details
|
||||
- **Scoring Endpoints**: `src/Findings/StellaOps.Findings.Ledger.WebService/Endpoints/ScoringEndpoints.cs` -- exposes REST endpoints for querying scored findings with policy trace context, including why a finding is blocked and which evidence would change the outcome.
|
||||
- **Evidence Graph Endpoints**: `src/Findings/StellaOps.Findings.Ledger.WebService/Endpoints/EvidenceGraphEndpoints.cs` -- serves evidence graph subgraphs connecting findings to attestations, VEX statements, and policy decisions, showing the trace of what inputs led to the verdict.
|
||||
- **Finding Summary Endpoints**: `src/Findings/StellaOps.Findings.Ledger.WebService/Endpoints/FindingSummaryEndpoints.cs` -- returns finding summaries with policy evaluation trace context including rule names, evaluation outcomes, and evidence references.
|
||||
- **Finding Scoring Service**: `src/Findings/StellaOps.Findings.Ledger.WebService/Services/FindingScoringService.cs` -- computes and caches finding scores combining CVSS, EPSS, VEX, and reachability signals; explains score composition.
|
||||
- **Evidence Graph Builder**: `src/Findings/StellaOps.Findings.Ledger.WebService/Services/EvidenceGraphBuilder.cs` -- constructs evidence subgraphs from ledger events and attestation pointers for trace visualization.
|
||||
- **VEX Consensus Service**: `src/Findings/StellaOps.Findings.Ledger.WebService/Services/VexConsensusService.cs` -- aggregates VEX decisions across sources to explain the consensus status.
|
||||
- **Policy Evaluation Service**: `src/Findings/StellaOps.Findings.Ledger/Infrastructure/Policy/PolicyEngineEvaluationService.cs` -- evaluates policy rules against findings and returns detailed trace output explaining each rule's contribution.
|
||||
- **Inline Policy Evaluation Service**: `src/Findings/StellaOps.Findings.Ledger/Infrastructure/Policy/InlinePolicyEvaluationService.cs` -- lightweight inline evaluation for single-finding traces without external policy engine calls.
|
||||
- **Tests**: `src/Findings/__Tests/StellaOps.Findings.Ledger.Tests/Integration/ScoringEndpointsIntegrationTests.cs`, `ScoringAuthorizationTests.cs`, `PolicyEngineEvaluationServiceTests.cs`, `InlinePolicyEvaluationServiceTests.cs`, `src/Findings/__Tests/StellaOps.Findings.Ledger.Tests/Services/EvidenceGraphBuilderTests.cs`, `FindingScoringServiceTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Submit a finding that fails policy evaluation and query the trace endpoint to verify the response explains which rule blocked it and what evidence is required to pass
|
||||
- [ ] Query the evidence graph endpoint for a blocked finding and verify the returned subgraph contains nodes for the finding, its attestations, VEX statements, and policy rules with correct edge relationships
|
||||
- [ ] Modify a finding's VEX status to "not_affected" and re-query the trace to verify the explanation updates to reflect the new unblocked status
|
||||
- [ ] Verify authorization: attempt to query trace endpoints without the required scope and confirm a 403 response
|
||||
- [ ] Verify the inline policy evaluation service returns the same trace results as the full policy engine evaluation service for a simple single-rule scenario
|
||||
@@ -1,28 +0,0 @@
|
||||
# Score API Endpoints (/api/v1/score/evaluate, /score/weights)
|
||||
|
||||
## Module
|
||||
Api
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
The advisory proposed dedicated REST endpoints for score evaluation, weight management, and replay. These were marked TODO (TSF-005, TSF-011) and have not been implemented.
|
||||
|
||||
## Implementation Details
|
||||
- **Scoring Endpoints**: `src/Findings/StellaOps.Findings.Ledger.WebService/Endpoints/ScoringEndpoints.cs` -- maps scoring-related routes for querying scored findings, score history, and aggregate metrics.
|
||||
- **Scored Findings Query Service**: `src/Findings/StellaOps.Findings.Ledger/Services/ScoredFindingsQueryService.cs` (implements `IScoredFindingsQueryService`) -- queries findings with their computed scores, supports filtering by severity, status, and component.
|
||||
- **Scored Findings Query Models**: `src/Findings/StellaOps.Findings.Ledger/Services/ScoredFindingsQueryModels.cs` -- query/response models for scored findings queries.
|
||||
- **Scored Findings Export Service**: `src/Findings/StellaOps.Findings.Ledger/Services/ScoredFindingsExportService.cs` -- exports scored findings as CSV/JSON for reporting and compliance.
|
||||
- **Scoring Metrics Service**: `src/Findings/StellaOps.Findings.Ledger/Services/ScoringMetricsService.cs` -- computes aggregate scoring metrics (mean score, distribution, trend).
|
||||
- **Score History Store**: `src/Findings/StellaOps.Findings.Ledger.WebService/Services/ScoreHistoryStore.cs` -- persists score snapshots over time for trend analysis.
|
||||
- **Scoring Contracts**: `src/Findings/StellaOps.Findings.Ledger.WebService/Contracts/ScoringContracts.cs` -- API DTOs for score requests and responses.
|
||||
- **Tests**: `src/Findings/__Tests/StellaOps.Findings.Ledger.Tests/ScoredFindingsQueryServiceTests.cs`, `src/Findings/__Tests/StellaOps.Findings.Ledger.Tests/Integration/ScoringEndpointsIntegrationTests.cs`, `ScoringObservabilityTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Query the score API with no filters and verify all findings are returned with their computed scores
|
||||
- [ ] Apply severity and component filters and verify only matching findings are returned
|
||||
- [ ] Export scored findings as CSV and verify the output contains correct headers and data rows matching the query results
|
||||
- [ ] Verify scoring metrics endpoint returns aggregate statistics (count, mean score, percentile distribution)
|
||||
- [ ] Verify authorization: confirm the scoring API requires the `findings:read` scope
|
||||
- [ ] Verify pagination: query with page size and offset parameters and confirm correct paging behavior
|
||||
@@ -1,25 +0,0 @@
|
||||
# Adaptive Noise Gating for Vulnerability Graphs
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Four-part noise reduction system: (1) Semantic edge deduplication collapsing redundant edges with provenance sets, (2) Proof Strength hierarchy (Authoritative=100 > BinaryProof=80 > StaticAnalysis=60 > Heuristic=40), (3) Stability damping gate preventing flip-flopping verdicts with hysteresis thresholds, (4) Delta sections categorizing changes as New/Resolved/ConfidenceUp/ConfidenceDown/PolicyImpact.
|
||||
|
||||
## Implementation Details
|
||||
- **ProofChain Graph**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Graph/` -- `InMemoryProofGraphService` (with `.Mutation`, `.Queries`, `.Subgraph` partials) provides the in-memory graph with node/edge deduplication. `ProofGraphEdge` and `ProofGraphEdgeType` define edge semantics including provenance sets. `ProofGraphNode` and `ProofGraphNodeType` classify node types with strength levels.
|
||||
- **Delta Verdict System**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Predicates/DeltaVerdictPredicate.cs` and `DeltaVerdictPredicate.Budget.cs` implement delta categorization (New/Resolved/ConfidenceUp/ConfidenceDown). `DeltaVerdictChange.cs` and `VerdictDeltaSummary.cs` track per-finding changes.
|
||||
- **Evidence Confidence**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Generators/BackportProofGenerator.Confidence.cs` computes confidence scores using proof-strength hierarchy. `EvidenceSummary.cs` aggregates evidence with strength weighting.
|
||||
- **Change Trace**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/ChangeTrace/ChangeTraceAttestationService.cs` (with `.Helpers` and `.Mapping` partials) tracks changes over time for stability damping.
|
||||
- **Verdict Delta Predicates**: `VerdictFindingChange.cs`, `VerdictRuleChange.cs` categorize changes by policy impact.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/Statements/DeltaVerdictStatementTests.cs`, `ChangeTrace/ChangeTracePredicateTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Create a proof graph with redundant edges (same source/target, different provenance) and verify that `InMemoryProofGraphService` deduplicates them into a single edge with merged provenance sets
|
||||
- [ ] Submit evidence at different proof-strength tiers (Authoritative, BinaryProof, StaticAnalysis, Heuristic) and verify the `BackportProofGenerator.Confidence` produces correct weighted confidence scores
|
||||
- [ ] Generate two consecutive verdict snapshots with minor score fluctuations below the hysteresis threshold and verify that `ChangeTraceAttestationService` suppresses the flip-flop delta
|
||||
- [ ] Generate a delta verdict where findings are added, resolved, and confidence-changed, then verify `DeltaVerdictPredicate` categorizes each change correctly (New/Resolved/ConfidenceUp/ConfidenceDown/PolicyImpact)
|
||||
- [ ] Query a subgraph via `InMemoryProofGraphService.Subgraph` and verify only reachable nodes from the root are included, with correct edge types
|
||||
@@ -1,30 +0,0 @@
|
||||
# AI-Assisted Explanation and Classification
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
AI authority classifier with explanation scoring, citation references, explanation types, and model identifiers. AI artifact verification step integrates into the verification pipeline.
|
||||
|
||||
## Implementation Details
|
||||
- **AIAuthorityClassifier**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Predicates/AI/AIAuthorityClassifier.cs` (with `.Explanation`, `.ExplanationScore`, `.PolicyDraft`, `.PolicyDraftScore`, `.Remediation`, `.RemediationScore`, `.VexDraft`, `.VexDraftScore` partials) -- classifies AI outputs into `Suggestion`, `EvidenceBacked`, or `AuthorityThreshold` based on citation rate, verified rate, and confidence score.
|
||||
- **AIAuthorityThresholds**: `AIAuthorityThresholds.cs` -- configurable thresholds: `MinCitationRate` (default 0.8), `MinConfidenceScore` (default 0.7), `MinVerifiedCitationRate` (default 0.9), `AuthorityThresholdScore` (default 0.95).
|
||||
- **AIArtifactAuthority enum**: `AIArtifactAuthority.cs` -- three levels: Suggestion (no evidence), EvidenceBacked (citations verified), AuthorityThreshold (meets auto-processing score).
|
||||
- **AIExplanationPredicate**: `AIExplanationPredicate.cs` -- record extending `AIArtifactBasePredicate` with `ExplanationType`, `Content`, `Citations`, `ConfidenceScore`, `CitationRate`, `Subject`, `ContextScope`.
|
||||
- **AIExplanationCitation**: `AIExplanationCitation.cs` -- links claims to evidence with `ClaimIndex`, `ClaimText`, `EvidenceId` (sha256 format), `EvidenceType`, `Verified` flag.
|
||||
- **AIExplanationType enum**: `AIExplanationType.cs` -- Exploitability, CodePath, PolicyDecision, RiskFactors, RemediationOptions, PlainLanguageSummary, EvidenceChain.
|
||||
- **AIModelIdentifier**: `AIModelIdentifier.cs` -- tracks provider/model/version with optional `WeightsDigest` for local models.
|
||||
- **Verification Step**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Verification/AIArtifactVerificationStep.cs` (with `.Execute`, `.Classify`, `.Helpers`, `.Summary`, `.VerifyParse`, `.VerifyValidation` partials) -- integrates into `VerificationPipeline` to verify AI artifacts in proof bundles.
|
||||
- **Tests**: `__Libraries/StellaOps.Attestor.ProofChain.Tests/AI/AIAuthorityClassifierTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Create an `AIExplanationPredicate` with citation rate >= 0.8, verified rate >= 0.9, and confidence >= 0.7, classify via `AIAuthorityClassifier`, and verify it returns `EvidenceBacked`
|
||||
- [ ] Create an explanation with citation rate < 0.8 and verify classifier returns `Suggestion` with appropriate reason messages
|
||||
- [ ] Create an explanation with quality score >= 0.95 and verify classifier returns `AuthorityThreshold`
|
||||
- [ ] Submit a proof bundle containing AI artifacts through `AIArtifactVerificationStep.ExecuteAsync` and verify all artifacts are validated (parse, schema, classification)
|
||||
- [ ] Submit a proof bundle with invalid AI artifacts (malformed predicate) and verify the verification step returns `Passed = false` with error details
|
||||
- [ ] Create an `AIExplanationCitation` with `Verified = false` and verify it lowers the verified rate below the threshold, causing the classifier to return `Suggestion`
|
||||
- [ ] Verify `AIModelIdentifier.ToString()` produces the canonical `provider:model:version` format
|
||||
@@ -1,31 +0,0 @@
|
||||
# AI Authority Classification Engine
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Authority classification engine that determines whether AI outputs are evidence-backed (authoritative) or suggestion-only, with configurable thresholds and scoring across multiple artifact types.
|
||||
|
||||
## Implementation Details
|
||||
- **Core Classifier**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Predicates/AI/AIAuthorityClassifier.cs` -- partial class with `DetermineAuthority()` method that evaluates `citationRate`, `verifiedRate`, `confidenceScore`, and `qualityScore` against configurable thresholds.
|
||||
- **Artifact-Specific Scoring**: Partial files implement scoring for each artifact type:
|
||||
- `AIAuthorityClassifier.Explanation.cs` / `AIAuthorityClassifier.ExplanationScore.cs` -- explanation classification and scoring
|
||||
- `AIAuthorityClassifier.PolicyDraft.cs` / `AIAuthorityClassifier.PolicyDraftScore.cs` -- policy draft classification
|
||||
- `AIAuthorityClassifier.Remediation.cs` / `AIAuthorityClassifier.RemediationScore.cs` -- remediation plan classification
|
||||
- `AIAuthorityClassifier.VexDraft.cs` / `AIAuthorityClassifier.VexDraftScore.cs` -- VEX statement draft classification
|
||||
- **Authority Levels**: `AIArtifactAuthority.cs` -- `Suggestion` (no evidence backing), `EvidenceBacked` (citations verified, evidence resolvable), `AuthorityThreshold` (auto-processing eligible)
|
||||
- **Thresholds Config**: `AIAuthorityThresholds.cs` -- `MinCitationRate` (0.8), `MinConfidenceScore` (0.7), `MinVerifiedCitationRate` (0.9), `AuthorityThresholdScore` (0.95), `RequireResolvableEvidence` (true)
|
||||
- **Classification Result**: `AIAuthorityClassificationResult.cs` -- captures authority level, reasons, and individual scores
|
||||
- **Evidence Resolution**: Constructor accepts optional `Func<string, bool>` evidence resolver to verify that cited evidence IDs are resolvable
|
||||
- **Tests**: `__Libraries/StellaOps.Attestor.ProofChain.Tests/AI/AIAuthorityClassifierTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Classify an explanation with all metrics above thresholds and verify `EvidenceBacked` result with three reason entries (citation rate, verified rate, confidence)
|
||||
- [ ] Classify a policy draft with `qualityScore >= 0.95` and verify `AuthorityThreshold` result regardless of other metrics
|
||||
- [ ] Classify a remediation plan with `citationRate = 0.5` and verify `Suggestion` result with reason mentioning citation rate below threshold
|
||||
- [ ] Classify a VEX draft with an evidence resolver that returns `false` for some evidence IDs and verify the verified rate drops below threshold
|
||||
- [ ] Override `AIAuthorityThresholds` with stricter values (e.g., `MinCitationRate = 0.95`) and verify classification changes accordingly
|
||||
- [ ] Verify all four artifact-type classifiers (Explanation, PolicyDraft, Remediation, VexDraft) produce correct `AIAuthorityClassificationResult` with type-specific scoring
|
||||
@@ -1,30 +0,0 @@
|
||||
# AI Remediation Plan Attestation
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Predicate types for AI-generated remediation plans including steps, risk assessments, and action types as signed attestation artifacts.
|
||||
|
||||
## Implementation Details
|
||||
- **AIRemediationPlanPredicate**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Predicates/AI/AIRemediationPlanPredicate.cs` -- extends `AIArtifactBasePredicate` with remediation-specific fields.
|
||||
- **RemediationStep**: `RemediationStep.cs` -- describes a single remediation action with status tracking.
|
||||
- **RemediationActionType enum**: `RemediationActionType.cs` -- types of remediation actions (e.g., upgrade, patch, configuration change).
|
||||
- **RemediationStepStatus enum**: `RemediationStepStatus.cs` -- tracks step execution status.
|
||||
- **RemediationRiskAssessment**: `RemediationRiskAssessment.cs` -- assesses risk impact of applying the remediation.
|
||||
- **RemediationVerificationStatus enum**: `RemediationVerificationStatus.cs` -- verification state after remediation application.
|
||||
- **Classifier Integration**: `AIAuthorityClassifier.Remediation.cs` classifies remediation plans; `AIAuthorityClassifier.RemediationScore.cs` computes quality scores for evidence-backing determination.
|
||||
- **Statement**: `__Libraries/StellaOps.Attestor.ProofChain/Statements/AIRemediationPlanStatement.cs` -- wraps predicate as in-toto statement.
|
||||
- **Base Class**: `AIArtifactBasePredicate.cs` provides `ModelIdentifier` (`AIModelIdentifier`), `DecodingParameters` (`AIDecodingParameters`), and timestamp fields inherited by the remediation predicate.
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Create an `AIRemediationPlanPredicate` with multiple `RemediationStep` entries of different `RemediationActionType` values and verify JSON serialization
|
||||
- [ ] Create a remediation plan with a `RemediationRiskAssessment` and verify the risk level is correctly captured in the predicate
|
||||
- [ ] Classify a remediation plan via `AIAuthorityClassifier.Remediation` with high citation/evidence scores and verify `EvidenceBacked` authority
|
||||
- [ ] Classify a remediation plan with low evidence backing and verify `Suggestion` authority
|
||||
- [ ] Wrap the predicate in `AIRemediationPlanStatement` and verify it produces a valid in-toto statement
|
||||
- [ ] Verify `RemediationStepStatus` progression (e.g., Pending -> InProgress -> Completed) is correctly serialized
|
||||
- [ ] Create a remediation plan with `RemediationVerificationStatus` set and verify the verification state persists through serialization
|
||||
@@ -1,31 +0,0 @@
|
||||
# ASN.1-Native RFC 3161 Timestamp Token Parsing
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Native ASN.1 parsing of RFC 3161 timestamp tokens using System.Formats.Asn1 (no BouncyCastle dependency). Includes request encoding, response decoding, TstInfo extraction, certificate chain parsing, and signature verification. This is the low-level implementation detail behind the known "RFC-3161 TSA Client" entry.
|
||||
|
||||
## Implementation Details
|
||||
- **Timestamp Service**: `src/Attestor/__Libraries/StellaOps.Attestor.Timestamping/AttestationTimestampService.cs` (with `.Helpers`, `.Timestamp`, `.Verify` partials) -- core service handling RFC 3161 timestamp request/response lifecycle.
|
||||
- **IAttestationTimestampService**: `IAttestationTimestampService.cs` -- interface for timestamp operations.
|
||||
- **Timestamp Policy**: `TimestampPolicy.cs`, `TimestampPolicyEvaluator.cs`, `TimestampPolicyResult.cs` -- policy evaluation for timestamp requirements.
|
||||
- **TSA Certificate Validation**: `TsaCertificateStatus.cs` -- certificate chain status. `TstVerificationStatus.cs` -- TstInfo verification result.
|
||||
- **Time Correlation**: `TimeCorrelationValidator.cs` (with `.Async`, `.GapChecks`, `.Validate` partials) -- validates timestamp consistency across multiple TSA sources. `TimeCorrelationPolicy.cs`, `TimeCorrelationResult.cs`, `TimeCorrelationStatus.cs` define correlation rules.
|
||||
- **Time Consistency**: `TimeConsistencyResult.cs` -- result of cross-TSA time consistency checks.
|
||||
- **Multi-Provider Fallback**: `src/Attestor/__Libraries/StellaOps.Attestor.Infrastructure/Timestamping/TsaMultiProvider.cs` -- fallback chain across multiple TSA providers.
|
||||
- **Configuration**: `AttestationTimestampOptions.cs`, `AttestationTimestampServiceOptions.cs`, `AttestationTimestampVerificationOptions.cs`, `AttestationTimestampPolicyContext.cs`.
|
||||
- **Timestamped Attestation**: `TimestampedAttestation.cs` -- wraps an attestation with its timestamp token.
|
||||
- **Tests**: `StellaOps.Attestor/StellaOps.Attestor.Tests/Timestamping/AttestationTimestampServiceTests.cs`, `AttestationTimestampPolicyTests.cs`, `TimeCorrelationValidatorTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Create a timestamp request for a SHA-256 hash via `AttestationTimestampService`, send to a TSA endpoint, and verify the response contains a valid TstInfo with matching hash
|
||||
- [ ] Parse an RFC 3161 timestamp token response and verify certificate chain extraction produces valid `TsaCertificateStatus`
|
||||
- [ ] Verify a timestamp token signature against the TSA certificate and confirm `TstVerificationStatus` indicates success
|
||||
- [ ] Configure `TimeCorrelationValidator` with two TSA sources and verify `TimeConsistencyResult` passes when timestamps are within configured gap tolerance
|
||||
- [ ] Configure `TimeCorrelationValidator` with a strict gap threshold and submit timestamps with drift exceeding the threshold, verifying `TimeCorrelationStatus` indicates failure
|
||||
- [ ] Test `TsaMultiProvider` fallback by configuring a primary TSA that fails and a secondary that succeeds, verifying the timestamp is obtained from the fallback provider
|
||||
- [ ] Create a `TimestampedAttestation` wrapping a DSSE envelope and verify the timestamp token is correctly associated
|
||||
@@ -1,29 +0,0 @@
|
||||
# Attestable Exception Objects with Expiries and Audit Trails
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Exceptions are modeled as auditable objects with IDs, owners, expiry dates, and audit trails. The exception ledger UI shows active/pending/expiring counts. Signed override badges indicate cryptographic attestation of exceptions.
|
||||
|
||||
## Implementation Details
|
||||
- **Exception Reference**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Services/ExceptionRef.cs` -- models exception objects with ID, owner, and expiry metadata.
|
||||
- **Budget Exception Entry**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Statements/BudgetExceptionEntry.cs` -- exception entry within the uncertainty budget system, tracking exception scope and validity period.
|
||||
- **Budget System Integration**: `BudgetDefinition.cs`, `BudgetObservation.cs`, `BudgetViolationEntry.cs` -- exceptions integrate with the uncertainty budget to allow controlled risk acceptance.
|
||||
- **VEX Override System**: `src/Attestor/__Libraries/StellaOps.Attestor.StandardPredicates/VexOverride/VexOverridePredicate.cs` -- signed VEX overrides serve as attestable exceptions. `VexOverridePredicateBuilder.cs` (with `.Build`, `.Serialize`, `.WithMethods` partials) constructs override predicates. `VexOverrideDecision.cs` captures the decision rationale.
|
||||
- **Evidence Reference**: `VexOverride/EvidenceReference.cs` -- links exception decisions to supporting evidence.
|
||||
- **Audit Trail**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Audit/AuditHashLogger.cs` (with `.Validation` partial) logs hash-based audit records. `HashAuditRecord.cs` captures individual audit entries. `AuditArtifactTypes.cs` defines auditable artifact types.
|
||||
- **Persistence**: `src/Attestor/__Libraries/StellaOps.Attestor.Persistence/Entities/AuditLogEntity.cs` -- database entity for audit log persistence.
|
||||
- **DSSE Signing**: Exceptions are signed via `ProofChainSigner` to produce cryptographic attestation (signed override badges).
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Create an exception via `BudgetExceptionEntry` with owner, expiry date, and justification, then verify all fields serialize correctly
|
||||
- [ ] Build a `VexOverridePredicate` with `VexOverridePredicateBuilder`, sign it via DSSE, and verify the signed envelope contains the override decision
|
||||
- [ ] Create an exception with an expiry date in the past and verify budget evaluation treats it as expired (no longer valid)
|
||||
- [ ] Create an exception with a future expiry and verify it is counted as active in the budget check
|
||||
- [ ] Log exception creation via `AuditHashLogger` and verify `HashAuditRecord` captures the artifact type, timestamp, and hash
|
||||
- [ ] Query audit trail for a specific exception ID and verify the complete history of changes is returned
|
||||
- [ ] Verify that `ExceptionRef` correctly links to `EvidenceReference` for evidence-backed exception justification
|
||||
@@ -1,29 +0,0 @@
|
||||
# Attestable reachability slices (DSSE/in-toto signed evidence)
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Reachability witness payloads wrapped in DSSE-signed attestations provide verifiable evidence slices for triage decisions.
|
||||
|
||||
## Implementation Details
|
||||
- **Reachability Witness Payload**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Statements/ReachabilityWitnessPayload.cs` (with `.Path` partial) -- defines the witness payload containing call paths from entry points to vulnerable functions.
|
||||
- **Witness Path Nodes**: `WitnessPathNode.cs`, `WitnessCallPathNode.cs` -- model individual nodes in the reachability call path.
|
||||
- **Witness Evidence Metadata**: `WitnessEvidenceMetadata.cs` -- metadata about the evidence source (scanner, analysis tool, timestamp).
|
||||
- **Witness Gate Info**: `WitnessGateInfo.cs` -- gate information for policy evaluation of witness data.
|
||||
- **Reachability Witness Statement**: `ReachabilityWitnessStatement.cs` -- wraps witness payload as an in-toto statement with subject and predicate.
|
||||
- **Reachability Subgraph**: `ReachabilitySubgraphStatement.cs` -- subgraph attestation for minimal reachability evidence. `ReachabilitySubgraphPredicate.cs` defines the subgraph predicate.
|
||||
- **DSSE Signing**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Signing/ProofChainSigner.cs` (with `.Verification` partial) signs statements. `DsseEnvelope.cs`, `DsseSignature.cs` model the envelope.
|
||||
- **Path Witness Predicate Types**: `src/Attestor/StellaOps.Attestor/StellaOps.Attestor.Core/PathWitnessPredicateTypes.cs` -- defines predicate type URIs for path witnesses.
|
||||
- **Proof Emitter**: `IProofEmitter.cs` -- interface for emitting signed proofs including reachability slices.
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Create a `ReachabilityWitnessPayload` with a call path containing 3+ nodes from entry point to vulnerable function, wrap in `ReachabilityWitnessStatement`, and verify the statement structure
|
||||
- [ ] Sign the witness statement via `ProofChainSigner` and verify the DSSE envelope contains valid signature and payload
|
||||
- [ ] Verify the signed reachability slice via `ProofChainSigner.Verification` and confirm signature validation passes
|
||||
- [ ] Create a `ReachabilitySubgraphPredicate` with a minimal subgraph (entry point -> intermediate -> sink) and verify it serializes with correct predicate type
|
||||
- [ ] Modify the signed envelope payload and verify that signature verification fails (tamper detection)
|
||||
- [ ] Create witness payloads with `WitnessEvidenceMetadata` from different analysis tools and verify metadata is preserved in the signed attestation
|
||||
@@ -1,28 +0,0 @@
|
||||
# Benchmark harness (reachability, scanner analyzers, policy engine, determinism)
|
||||
|
||||
## Module
|
||||
Bench
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Comprehensive benchmark harness exists covering reachability, scanner analyzers, policy engine, determinism, graph, and link-not-merge benchmarks with Prometheus metric export.
|
||||
|
||||
## Implementation Details
|
||||
- **LinkNotMerge Benchmark**: `src/Bench/StellaOps.Bench/LinkNotMerge/StellaOps.Bench.LinkNotMerge/` -- benchmark scenarios for linkset aggregation performance. Key files: `LinkNotMergeScenarioRunner.cs` (runs benchmark scenarios), `LinksetAggregator.cs` (aggregation logic under test), `ObservationData.cs` (test data models), `BenchmarkConfig.cs` (scenario configuration), `ScenarioStatistics.cs` / `ScenarioResult.cs` / `ScenarioExecutionResult.cs` (result models).
|
||||
- **LinkNotMerge VEX Benchmark**: `src/Bench/StellaOps.Bench/LinkNotMerge.Vex/StellaOps.Bench.LinkNotMerge.Vex/` -- VEX-specific linkset benchmarks. Key files: `VexScenarioRunner.cs`, `VexLinksetAggregator.cs`, `VexObservationGenerator.cs`, `VexScenarioConfig.cs`, `Statistics.cs`.
|
||||
- **Notify Benchmark**: `src/Bench/StellaOps.Bench/Notify/StellaOps.Bench.Notify/` -- notification dispatch benchmarks. Key files: `NotifyScenarioRunner.cs`, `DispatchAccumulator.cs`, `BenchmarkConfig.cs`.
|
||||
- **PolicyEngine Benchmark**: `src/Bench/StellaOps.Bench/PolicyEngine/StellaOps.Bench.PolicyEngine/` -- policy evaluation benchmarks. Key files: `PolicyScenarioRunner.cs`, `PathUtilities.cs`, `BenchmarkConfig.cs`.
|
||||
- **Scanner.Analyzers Benchmark**: `src/Bench/StellaOps.Bench/Scanner.Analyzers/StellaOps.Bench.ScannerAnalyzers/` -- scanner analyzer benchmarks. Key files: `ScenarioRunners.cs`, `NodeBenchMetrics.cs`, `BenchmarkConfig.cs`.
|
||||
- **Baseline Infrastructure**: Each benchmark has `Baseline/BaselineEntry.cs` and `Baseline/BaselineLoader.cs` for loading ground-truth comparison baselines.
|
||||
- **Reporting Infrastructure**: Each benchmark has `Reporting/BenchmarkJsonWriter.cs` (JSON output), `Reporting/BenchmarkScenarioReport.cs` (report model), `Reporting/PrometheusWriter.cs` (Prometheus metric export).
|
||||
- **Tests**: `src/Bench/StellaOps.Bench/LinkNotMerge/StellaOps.Bench.LinkNotMerge.Tests/LinkNotMergeScenarioRunnerTests.cs`, `BaselineLoaderTests.cs`, `BenchmarkScenarioReportTests.cs`; `src/Bench/StellaOps.Bench/LinkNotMerge.Vex/StellaOps.Bench.LinkNotMerge.Vex.Tests/VexScenarioRunnerTests.cs`; `src/Bench/StellaOps.Bench/Notify/StellaOps.Bench.Notify.Tests/NotifyScenarioRunnerTests.cs`, `PrometheusWriterTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Run the LinkNotMerge benchmark suite and verify it produces a valid `BenchmarkScenarioReport` with timing statistics and passes baseline comparison
|
||||
- [ ] Run the PolicyEngine benchmark and verify scenario results include evaluation counts and latency percentiles
|
||||
- [ ] Run the Scanner.Analyzers benchmark and verify `NodeBenchMetrics` are captured per analyzer
|
||||
- [ ] Verify Prometheus export: run any benchmark and confirm `PrometheusWriter` outputs valid Prometheus exposition format with scenario labels
|
||||
- [ ] Verify JSON export: run a benchmark and confirm `BenchmarkJsonWriter` produces valid JSON report matching the `BenchmarkScenarioReport` schema
|
||||
- [ ] Verify baseline comparison: load a baseline and run scenarios, confirm the harness reports regressions when results exceed baseline thresholds
|
||||
@@ -1,24 +0,0 @@
|
||||
# Reachability benchmarks with ground-truth datasets
|
||||
|
||||
## Module
|
||||
Bench
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Reachability benchmark suite with ground-truth datasets (Java Log4j, C# reachable/dead-code, native ELF), schema validation, and signal-level ground-truth validators.
|
||||
|
||||
## Implementation Details
|
||||
- **Scanner.Analyzers Benchmark**: `src/Bench/StellaOps.Bench/Scanner.Analyzers/StellaOps.Bench.ScannerAnalyzers/` -- benchmark runner for scanner analyzers against ground-truth datasets. Key files: `ScenarioRunners.cs` (orchestrates benchmark scenarios against corpus data), `NodeBenchMetrics.cs` (captures per-node precision/recall metrics), `BenchmarkConfig.cs` (configures which datasets and analyzers to run).
|
||||
- **Baseline Infrastructure**: `src/Bench/StellaOps.Bench/Scanner.Analyzers/StellaOps.Bench.ScannerAnalyzers/Baseline/BaselineEntry.cs` (ground-truth entry model), `BaselineLoader.cs` (loads ground-truth datasets from fixture files).
|
||||
- **Reporting**: `src/Bench/StellaOps.Bench/Scanner.Analyzers/StellaOps.Bench.ScannerAnalyzers/Reporting/BenchmarkJsonWriter.cs` (JSON output), `BenchmarkScenarioReport.cs` (report with precision/recall/F1), `PrometheusWriter.cs` (metric export).
|
||||
- **Tests**: `src/Bench/StellaOps.Bench/Scanner.Analyzers/StellaOps.Bench.ScannerAnalyzers.Tests/BaselineLoaderTests.cs`, `BenchmarkJsonWriterTests.cs`, `BenchmarkScenarioReportTests.cs`, `PrometheusWriterTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Load a Java Log4j ground-truth dataset via `BaselineLoader` and run the scanner analyzer benchmark; verify precision and recall metrics are computed against the ground truth
|
||||
- [ ] Load a C# reachable/dead-code ground-truth dataset and verify the benchmark correctly classifies true positives, false positives, and false negatives
|
||||
- [ ] Run the benchmark with a native ELF dataset and verify the `NodeBenchMetrics` captures per-node accuracy
|
||||
- [ ] Verify JSON report output contains precision, recall, F1 score, and per-scenario timing data
|
||||
- [ ] Verify that modifying the ground-truth baseline to include additional entries causes the benchmark to report new false negatives
|
||||
- [ ] Verify Prometheus metrics export includes labeled gauges for precision and recall per dataset
|
||||
@@ -1,34 +0,0 @@
|
||||
# Vendor comparison / scanner parity tracking
|
||||
|
||||
## Module
|
||||
Bench
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Scanner analyzer benchmarks and golden-set diff comparisons exist, but a dedicated vendor-comparison dashboard or automated parity scoring system as described in the advisory is not visible.
|
||||
|
||||
## What's Implemented
|
||||
- **Scanner Analyzers Benchmark**: `src/Bench/StellaOps.Bench/Scanner.Analyzers/StellaOps.Bench.ScannerAnalyzers/` -- benchmark harness that evaluates scanner analyzers against ground-truth datasets, computing precision, recall, and F1 metrics per scanner.
|
||||
- **Baseline Loader**: `src/Bench/StellaOps.Bench/Scanner.Analyzers/StellaOps.Bench.ScannerAnalyzers/Baseline/BaselineLoader.cs` -- loads ground-truth baseline data for benchmark comparison, enabling diff detection between scanner runs.
|
||||
- **Baseline Entry**: `src/Bench/StellaOps.Bench/Scanner.Analyzers/StellaOps.Bench.ScannerAnalyzers/Baseline/BaselineEntry.cs` -- data model for a single baseline entry with expected findings, labels, and metadata.
|
||||
- **Benchmark Scenario Report**: `src/Bench/StellaOps.Bench/Scanner.Analyzers/StellaOps.Bench.ScannerAnalyzers/Reporting/BenchmarkScenarioReport.cs` -- produces per-scenario benchmark reports with precision/recall/F1 breakdowns.
|
||||
- **Benchmark JSON Writer**: `src/Bench/StellaOps.Bench/Scanner.Analyzers/StellaOps.Bench.ScannerAnalyzers/Reporting/BenchmarkJsonWriter.cs` -- serializes benchmark results to JSON for CI consumption and historical tracking.
|
||||
- **Prometheus Writer**: `src/Bench/StellaOps.Bench/Scanner.Analyzers/StellaOps.Bench.ScannerAnalyzers/Reporting/PrometheusWriter.cs` -- exports benchmark metrics to Prometheus format for dashboard visualization.
|
||||
|
||||
## What's Missing
|
||||
- **Vendor Comparison Dashboard**: No dedicated UI or API endpoint exists for side-by-side vendor scanner comparison. Current benchmarks evaluate StellaOps scanners against ground truth, but do not compare against third-party vendor scanner outputs.
|
||||
- **Automated Parity Scoring**: No automated system computes a parity score between StellaOps scanner results and vendor scanner results (e.g., Snyk, Grype, Trivy) for the same input images.
|
||||
- **Vendor Result Ingestion**: No ingestion pipeline exists to import vendor scanner outputs (SARIF, JSON) as baseline comparisons alongside StellaOps results.
|
||||
- **Regression Tracking Dashboard**: While `PrometheusWriter` exports metrics, no pre-built Grafana dashboard or equivalent exists for tracking scanner parity over time.
|
||||
|
||||
## Implementation Plan
|
||||
- Add a vendor result ingestion pipeline that imports SARIF/JSON from third-party scanners and normalizes findings to a common schema
|
||||
- Extend `BenchmarkScenarioReport` to include vendor comparison columns (StellaOps vs. vendor findings, unique to each, overlap percentage)
|
||||
- Build an automated parity scoring system that computes agreement/disagreement rates between scanner outputs
|
||||
- Create a dashboard (Grafana or Web UI) for visualizing parity trends over time
|
||||
|
||||
## Related Documentation
|
||||
- Scanner benchmark infrastructure: `src/Bench/StellaOps.Bench/Scanner.Analyzers/`
|
||||
- Reachability benchmark datasets: `src/__Tests/__Benchmarks/reachability-benchmark/`
|
||||
@@ -1,28 +0,0 @@
|
||||
# Binary Call-Graph Extraction and Reachability Analysis
|
||||
|
||||
## Module
|
||||
BinaryIndex
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Binary call-graph extraction with BinaryCallGraphExtractor, reachability lifting via BinaryReachabilityLifter, dedicated BinaryIndex analysis module, and CLI binary commands.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Analysis/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Semantic/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/`
|
||||
- **Key Classes**:
|
||||
- `ReachGraphBinaryReachabilityService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Analysis/ReachGraphBinaryReachabilityService.cs`) - binary-level reachability integration with ReachGraph
|
||||
- `TaintGateExtractor` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Analysis/TaintGateExtractor.cs`) - extracts taint gates (bounds checks, null checks, auth checks, permission checks, type checks) from binary call paths
|
||||
- `CfgExtractor` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/CfgExtractor.cs`) - control flow graph extraction from disassembled binaries
|
||||
- `CallNgramGenerator` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Semantic/CallNgramGenerator.cs`) - generates call-sequence n-grams from lifted IR for call graph analysis
|
||||
- `CallGraphMatcherAdapter` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Validation/Matchers/MatcherAdapters.cs`) - adapter for call graph matching in validation harness
|
||||
- **Interfaces**: `ICallNgramGenerator`, `IBinaryFeatureExtractor`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Submit an ELF binary and verify call-graph extraction produces a valid set of function nodes and edges
|
||||
- [ ] Verify `TaintGateExtractor` classifies conditions correctly (bounds check, null check, auth check, permission check, type check)
|
||||
- [ ] Verify `CfgExtractor` produces control flow graphs from disassembled functions
|
||||
- [ ] Verify `CallNgramGenerator` generates n-grams (n=2,3,4) from lifted function IR and computes Jaccard similarity
|
||||
- [ ] Verify `ReachGraphBinaryReachabilityService` integrates with the ReachGraph module for function-level exploitability assessment
|
||||
- [ ] Verify call-graph-based reachability results feed into the ensemble decision engine
|
||||
@@ -1,29 +0,0 @@
|
||||
# Binary Identity Extraction (Build-ID Based)
|
||||
|
||||
## Module
|
||||
BinaryIndex
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Binary identity extraction using Build-IDs and symbol observations for ELF binary identification, with ground-truth validation and SBOM stability verification.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Persistence/`
|
||||
- **Key Classes**:
|
||||
- `BinaryIdentityService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/Services/BinaryIdentityService.cs`) - main service for extracting binary identity from ELF/PE/Mach-O binaries
|
||||
- `ElfFeatureExtractor` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/Services/ElfFeatureExtractor.cs`) - extracts Build-ID, symbol tables, and section info from ELF binaries
|
||||
- `PeFeatureExtractor` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/Services/PeFeatureExtractor.cs`) - extracts CodeView GUID from Windows PE binaries
|
||||
- `MachoFeatureExtractor` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/Services/MachoFeatureExtractor.cs`) - extracts LC_UUID from Mach-O binaries
|
||||
- `StreamGuard` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/Services/StreamGuard.cs`) - safe stream handling for non-seekable streams
|
||||
- **Interfaces**: `IBinaryFeatureExtractor` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/Services/IBinaryFeatureExtractor.cs`)
|
||||
- **Models**: `BinaryIdentity` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/Models/BinaryIdentity.cs`)
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Submit an ELF binary with a known Build-ID and verify the extracted identity matches
|
||||
- [ ] Submit a Windows PE binary and verify CodeView GUID extraction via `PeFeatureExtractor`
|
||||
- [ ] Submit a Mach-O binary and verify LC_UUID extraction via `MachoFeatureExtractor`
|
||||
- [ ] Verify that non-seekable streams are handled correctly via `StreamGuard`
|
||||
- [ ] Verify that binaries without Build-IDs fall back to symbol-based identification
|
||||
- [ ] Verify extracted identities are persisted and queryable through `BinaryVulnerabilityService`
|
||||
@@ -1,28 +0,0 @@
|
||||
# Binary Intelligence Graph / Binary Identity Indexing
|
||||
|
||||
## Module
|
||||
BinaryIndex
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Complete BinaryIndex module with binary identity indexing, ELF feature extraction, vulnerability fingerprint matching, and reachability status tracking. Advisory marked as SUPERSEDED by this implementation.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Persistence/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Analysis/`
|
||||
- **Key Classes**:
|
||||
- `BinaryIdentityService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/Services/BinaryIdentityService.cs`) - binary identity management
|
||||
- `ElfFeatureExtractor` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/Services/ElfFeatureExtractor.cs`) - ELF feature extraction
|
||||
- `BinaryVulnerabilityService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Persistence/Services/BinaryVulnerabilityService.cs`) - vulnerability matching with Build-ID catalog lookups
|
||||
- `SignatureMatcher` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Analysis/SignatureMatcher.cs`) - signature-based vulnerability fingerprint matching
|
||||
- `ReachGraphBinaryReachabilityService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Analysis/ReachGraphBinaryReachabilityService.cs`) - reachability status tracking
|
||||
- **Models**: `BinaryIdentity`, `FixModels` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/Models/`)
|
||||
- **Persistence**: `IBinaryVulnAssertionRepository`, `IBinaryVulnerabilityService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/Services/`)
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify end-to-end flow: submit binary, extract identity, index in the graph, and query by Build-ID
|
||||
- [ ] Verify vulnerability fingerprint matching via `SignatureMatcher` returns correct match scores
|
||||
- [ ] Verify reachability status tracking integrates with ReachGraph
|
||||
- [ ] Verify `BinaryVulnerabilityService` correctly maps match methods (buildid_catalog, delta_signature, etc.)
|
||||
- [ ] Verify binary identity indexing supports multi-tenant contexts via `ITenantContext`
|
||||
@@ -1,28 +0,0 @@
|
||||
# Binary Proof Verification Pipeline
|
||||
|
||||
## Module
|
||||
BinaryIndex
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Full binary proof verification with ground truth sources (buildinfo, debuginfod, reproducible builds), validation, and golden set testing.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.GroundTruth.Reproducible/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Validation/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Validation.Abstractions/`
|
||||
- **Key Classes**:
|
||||
- `ValidationHarnessService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.GroundTruth.Reproducible/ValidationHarnessService.cs`) - orchestrates reproducible-build-based validation runs
|
||||
- `ValidationHarness` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Validation/ValidationHarness.cs`) - main validation harness with matcher adapter factory integration
|
||||
- `KpiRegressionService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.GroundTruth.Reproducible/Services/KpiRegressionService.cs`) - KPI regression detection across validation runs
|
||||
- `GroundTruthProvenanceResolver` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/Provenance/GroundTruthProvenanceResolver.cs`) - resolves symbol provenance from ground truth sources
|
||||
- **Interfaces**: `IValidationHarness` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Validation.Abstractions/IValidationHarness.cs`), `IKpiRegressionService`, `ISymbolProvenanceResolver`
|
||||
- **Registration**: `ServiceCollectionExtensions.AddCorpusBundleExport/Import` for bundle exchange
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Run a validation harness against a known binary pair and verify proof correctness
|
||||
- [ ] Verify ground truth resolution from buildinfo sources produces correct provenance data
|
||||
- [ ] Verify KPI regression service detects accuracy drops between validation runs
|
||||
- [ ] Verify golden set validation produces deterministic, reproducible results
|
||||
- [ ] Verify corpus bundle export/import round-trips correctly
|
||||
- [ ] Verify validation run attestor generates valid attestation predicates with corpus snapshot IDs
|
||||
@@ -1,26 +0,0 @@
|
||||
# Binary Reachability Analysis
|
||||
|
||||
## Module
|
||||
BinaryIndex
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Binary-level reachability analysis integrating with the ReachGraph and taint gate extraction for function-level exploitability assessment.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Analysis/`
|
||||
- **Key Classes**:
|
||||
- `ReachGraphBinaryReachabilityService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Analysis/ReachGraphBinaryReachabilityService.cs`) - connects binary analysis to the ReachGraph module for function-level reachability
|
||||
- `TaintGateExtractor` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Analysis/TaintGateExtractor.cs`) - identifies taint gate types (BoundsCheck, NullCheck, AuthCheck, PermissionCheck, TypeCheck) from condition strings
|
||||
- `SignatureMatcher` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Analysis/SignatureMatcher.cs`) - matches vulnerability signatures at the binary level
|
||||
- **Models**: `AnalysisResultModels`, `FingerprintModels`, `SignatureIndexModels` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Analysis/Models/`)
|
||||
- **Interfaces**: defined in `Interfaces.cs`, implementations in `Implementations.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Submit a binary with a known vulnerable function and verify reachability analysis identifies it as reachable from entry points
|
||||
- [ ] Verify `TaintGateExtractor` correctly classifies all gate types (bounds, null, auth, permission, type checks)
|
||||
- [ ] Verify that unreachable vulnerable functions reduce the exploitability score
|
||||
- [ ] Verify integration between `ReachGraphBinaryReachabilityService` and the ReachGraph module
|
||||
- [ ] Verify that taint gate presence between entry point and vulnerable function is reflected in the analysis result
|
||||
@@ -1,30 +0,0 @@
|
||||
# Binary Resolution API with Cache Layer
|
||||
|
||||
## Module
|
||||
BinaryIndex
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
REST API endpoints (`POST /api/v1/resolve/vuln` and `/vuln/batch`) for querying whether a CVE is resolved through binary-level backport detection. Includes Valkey-backed response caching, rate limiting middleware, and telemetry instrumentation.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/BinaryIndex/StellaOps.BinaryIndex.WebService/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Cache/`
|
||||
- **Key Classes**:
|
||||
- `ResolutionController` (`src/BinaryIndex/StellaOps.BinaryIndex.WebService/Controllers/ResolutionController.cs`) - REST API controller with `POST /api/v1/resolve/vuln` and `/vuln/batch` endpoints
|
||||
- `ResolutionService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/Resolution/ResolutionService.cs`) - core resolution logic
|
||||
- `CachedResolutionService` (`src/BinaryIndex/StellaOps.BinaryIndex.WebService/Services/CachedResolutionService.cs`) - decorator adding Valkey-backed caching around ResolutionService
|
||||
- `ResolutionCacheService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Cache/ResolutionCacheService.cs`) - Valkey cache operations for resolution results
|
||||
- `RateLimitingMiddleware` (`src/BinaryIndex/StellaOps.BinaryIndex.WebService/Middleware/RateLimitingMiddleware.cs`) - per-tenant rate limiting with X-RateLimit headers
|
||||
- `ResolutionTelemetry` (`src/BinaryIndex/StellaOps.BinaryIndex.WebService/Telemetry/ResolutionTelemetry.cs`) - OpenTelemetry metrics for resolution requests, cache hits, rate limits
|
||||
- **Contracts**: `VulnResolutionRequest/Response`, `ResolutionMatchTypes` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Contracts/Resolution/VulnResolutionContracts.cs`)
|
||||
- **Cache Options**: `BinaryCacheOptions`, `CacheOptionsValidation` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Cache/`)
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Send `POST /api/v1/resolve/vuln` with a known CVE and package purl, verify resolution response contains match type (BuildId, DeltaSignature, etc.)
|
||||
- [ ] Send batch request to `/api/v1/resolve/vuln/batch` with multiple packages and verify all are resolved
|
||||
- [ ] Verify cache hit: send same request twice and confirm second response comes from cache (check telemetry counters)
|
||||
- [ ] Verify rate limiting: exceed the configured request limit and confirm 429 response with X-RateLimit headers
|
||||
- [ ] Verify telemetry: confirm resolution metrics are emitted (request count, cache hit ratio, latency histogram)
|
||||
- [ ] Verify disabled rate limiting mode passes requests through without headers
|
||||
@@ -1,30 +0,0 @@
|
||||
# Binary Symbol Table Diff Engine
|
||||
|
||||
## Module
|
||||
BinaryIndex
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Symbol table comparison between binary versions tracking exported/imported symbol changes, version map diffs, GOT/PLT table modifications, and ABI compatibility assessment. Produces content-addressed diff IDs for deterministic reporting.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Builders/SymbolDiff/`
|
||||
- **Key Classes**:
|
||||
- `SymbolTableDiffAnalyzer` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Builders/SymbolDiff/SymbolTableDiffAnalyzer.cs`) - computes diffs between symbol tables with `ComputeDiffAsync` and `AssessAbiCompatibility`
|
||||
- `SymbolTableDiff` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Builders/SymbolDiff/SymbolTableDiff.cs`) - diff result model with added/removed/changed symbols
|
||||
- `VersionMapDiff` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Builders/SymbolDiff/VersionMapDiff.cs`) - tracks changes in ELF version maps
|
||||
- `AbiCompatibility` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Builders/SymbolDiff/AbiCompatibility.cs`) - ABI compatibility assessment (FullyCompatible, Warnings, Incompatible)
|
||||
- `DynamicLinkingDiff` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Builders/SymbolDiff/DynamicLinkingDiff.cs`) - GOT/PLT table modification tracking
|
||||
- `NameDemangler` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Builders/SymbolDiff/NameDemangler.cs`) - C++ symbol name demangling
|
||||
- **Interfaces**: `ISymbolTableDiffAnalyzer` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Builders/SymbolDiff/ISymbolTableDiffAnalyzer.cs`)
|
||||
- **Registration**: `SymbolDiffServiceExtensions` for DI setup
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Compute diff between two ELF binaries with known symbol changes and verify added/removed symbols are correctly identified
|
||||
- [ ] Verify `AssessAbiCompatibility` returns `FullyCompatible` when only symbols are added
|
||||
- [ ] Verify `AssessAbiCompatibility` returns `Incompatible` when exported symbols are removed
|
||||
- [ ] Verify version map diff detection for ELF version script changes
|
||||
- [ ] Verify C++ symbol demangling produces human-readable names via `NameDemangler`
|
||||
- [ ] Verify content-addressed diff IDs are deterministic for identical inputs
|
||||
@@ -1,28 +0,0 @@
|
||||
# Binary-to-VEX Claim Auto-Generation (VexBridge Library)
|
||||
|
||||
## Module
|
||||
BinaryIndex
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Automated generation of VEX claims from binary fingerprint match results. The VexBridge library translates binary match evidence into DSSE-signed VEX statements with confidence scores, enabling automated VEX claim production from binary analysis without manual triage.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.VexBridge/`
|
||||
- **Key Classes**:
|
||||
- `VexEvidenceGenerator` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.VexBridge/VexEvidenceGenerator.cs`) - generates VEX observations from `BinaryVulnMatch` results; maps `FixState` to `VexClaimStatus` (Fixed -> NotAffected, Vulnerable -> Affected, Unknown -> UnderInvestigation)
|
||||
- `BinaryMatchEvidenceSchema` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.VexBridge/BinaryMatchEvidenceSchema.cs`) - defines evidence schema with match type constants (BuildId, DeltaSignature, etc.)
|
||||
- `VexBridgeOptions` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.VexBridge/VexBridgeOptions.cs`) - configuration for confidence thresholds
|
||||
- `DeltaSigVexBridge` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/VexIntegration/DeltaSigVexBridge.cs`) - bridges delta-signature analysis results into VEX observations with provenance data
|
||||
- **Interfaces**: `IVexEvidenceGenerator` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.VexBridge/IVexEvidenceGenerator.cs`), `IDeltaSigVexBridge`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Generate a VEX claim from a `Fixed` binary match and verify status is `NotAffected` with justification `VulnerableCodeNotPresent`
|
||||
- [ ] Generate a VEX claim from a `Vulnerable` match and verify status is `Affected`
|
||||
- [ ] Generate a VEX claim from an `Unknown` match and verify status is `UnderInvestigation`
|
||||
- [ ] Verify confidence threshold enforcement: low-confidence matches below threshold are rejected
|
||||
- [ ] Verify Build-ID references are included in VEX evidence when present
|
||||
- [ ] Verify `DeltaSigVexBridge` produces VEX observations with symbol provenance metadata
|
||||
- [ ] Verify generated VEX statements include correct DSSE evidence references
|
||||
@@ -1,27 +0,0 @@
|
||||
# BinaryIndex Ops CLI Commands (stella binary ops)
|
||||
|
||||
## Module
|
||||
BinaryIndex
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
CLI commands for BinaryIndex ops: health, bench, cache, config subcommands with JSON/table output and BinaryIndex base URL configuration. Also adds --semantic flag to deltasig extract/author/match commands.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/BinaryIndex/StellaOps.BinaryIndex.WebService/Controllers/`, `src/Cli/`
|
||||
- **Key Classes**:
|
||||
- `BinaryIndexOpsController` (`src/BinaryIndex/StellaOps.BinaryIndex.WebService/Controllers/BinaryIndexOpsController.cs`) - serves health, bench, cache stats, and config endpoints consumed by CLI
|
||||
- `BinaryIndexOpsHealthResponse` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/Configuration/BinaryIndexOpsModels.cs`) - health response model with lifter warmness, component versions
|
||||
- `BinaryIndexOpsOptions` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/Configuration/BinaryIndexOpsModels.cs`) - ops configuration with redacted keys and bench rate limits
|
||||
- `B2R2LifterPool` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Disassembly.B2R2/B2R2LifterPool.cs`) - lifter pool stats reported via ops health endpoint
|
||||
- **Source**: SPRINT_20260112_006_CLI_binaryindex_ops_cli.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Run `stella binary ops health` and verify JSON output includes lifter warmness and version info
|
||||
- [ ] Run `stella binary ops bench` and verify latency measurement results are returned
|
||||
- [ ] Run `stella binary ops cache` and verify Valkey hit/miss statistics are reported
|
||||
- [ ] Run `stella binary ops config` and verify effective configuration is returned with secrets redacted
|
||||
- [ ] Run `stella deltasig extract --semantic` and verify semantic flag is passed through
|
||||
- [ ] Verify table output format renders correctly for all subcommands
|
||||
@@ -1,27 +0,0 @@
|
||||
# BinaryIndex Ops Endpoints (Health, Bench, Cache Stats, Config)
|
||||
|
||||
## Module
|
||||
BinaryIndex
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Ops endpoints for BinaryIndex: health (lifter warmness), bench/run (latency measurement), cache stats (Valkey hit/miss), and effective config with deterministic JSON responses.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/BinaryIndex/StellaOps.BinaryIndex.WebService/`
|
||||
- **Key Classes**:
|
||||
- `BinaryIndexOpsController` (`src/BinaryIndex/StellaOps.BinaryIndex.WebService/Controllers/BinaryIndexOpsController.cs`) - exposes `GET /ops/health`, bench, cache stats, and config endpoints; integrates with `B2R2LifterPool` and `FunctionIrCacheService`
|
||||
- `B2R2LifterPool` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Disassembly.B2R2/B2R2LifterPool.cs`) - provides pool stats (warm ISAs, pool sizes, acquire timeouts)
|
||||
- `FunctionIrCacheService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Cache/FunctionIrCacheService.cs`) - Valkey-based function IR cache with hit/miss reporting
|
||||
- `B2R2LifterPoolOptions` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Disassembly.B2R2/B2R2LifterPoolOptions.cs`) - pool configuration (MaxPoolSizePerIsa, EnableWarmPreload, AcquireTimeout)
|
||||
- `BinaryIndexOptions` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/Configuration/BinaryIndexOptions.cs`) - top-level options with B2R2Pool, SemanticLifting sections
|
||||
- **Source**: SPRINT_20260112_004_BINIDX_b2r2_lowuir_perf_cache.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Call `GET /ops/health` and verify response includes lifter pool warmness state and component versions
|
||||
- [ ] Call bench endpoint and verify deterministic latency measurement JSON
|
||||
- [ ] Call cache stats endpoint and verify Valkey hit/miss counts and cache key count
|
||||
- [ ] Call config endpoint and verify effective configuration is returned with secrets redacted
|
||||
- [ ] Verify all ops responses use deterministic JSON serialization (consistent key ordering)
|
||||
@@ -1,30 +0,0 @@
|
||||
# BinaryIndex User Configuration System
|
||||
|
||||
## Module
|
||||
BinaryIndex
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Comprehensive user configuration for B2R2 lifter pooling, LowUIR enablement, Valkey function cache behavior, PostgreSQL persistence, with ops endpoints for health/bench/cache/config and redaction rules for operator visibility.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/Configuration/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Disassembly.B2R2/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Cache/`
|
||||
- **Key Classes**:
|
||||
- `BinaryIndexOptions` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/Configuration/BinaryIndexOptions.cs`) - top-level config with sections for B2R2Pool, SemanticLifting, cache, persistence
|
||||
- `B2R2PoolOptions` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Disassembly.B2R2/B2R2LifterPoolOptions.cs`) - MaxPoolSizePerIsa (1-64), EnableWarmPreload, AcquireTimeout, EnableMetrics, WarmPreloadIsas
|
||||
- `SemanticLiftingOptions` - B2R2Version, Enabled flag, function limits
|
||||
- `BinaryCacheOptions` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Cache/BinaryCacheOptions.cs`) - Valkey cache configuration
|
||||
- `CacheOptionsValidation` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Cache/CacheOptionsValidation.cs`) - validates cache config at startup
|
||||
- `FunctionIrCacheOptions` - function IR cache TTL and size limits
|
||||
- `BinaryIndexOpsOptions` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/Configuration/BinaryIndexOpsModels.cs`) - redacted keys list for operator visibility, bench rate limits
|
||||
- **Source**: SPRINT_20260112_007_BINIDX_binaryindex_user_config.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Configure B2R2 pool with custom MaxPoolSizePerIsa and verify pool initializes with correct size
|
||||
- [ ] Configure SemanticLifting as disabled and verify LowUIR lifting is skipped
|
||||
- [ ] Configure Valkey cache options and verify function IR cache respects TTL settings
|
||||
- [ ] Verify configuration binding from `StellaOps:BinaryIndex:*` config sections
|
||||
- [ ] Verify redacted keys do not appear in ops config endpoint responses
|
||||
- [ ] Verify CacheOptionsValidation rejects invalid configuration at startup
|
||||
@@ -1,30 +0,0 @@
|
||||
# Byte-Level Binary Diffing with Rolling Hash Windows
|
||||
|
||||
## Module
|
||||
BinaryIndex
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Byte-level binary comparison using rolling hash windows that identifies exactly which byte ranges changed between binary versions. Produces binary proof snippets with section analysis and privacy controls to strip raw bytes. Supports stream and file-based comparison.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Diff/`
|
||||
- **Key Classes**:
|
||||
- `PatchDiffEngine` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Diff/PatchDiffEngine.cs`) - core diffing engine computing byte-level differences between binary versions using function fingerprints
|
||||
- `FunctionDiffer` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Diff/FunctionDiffer.cs`) - function-level comparison with semantic analysis option and call-graph edge diffing
|
||||
- `FunctionRenameDetector` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Diff/FunctionRenameDetector.cs`) - detects function renames between versions using fingerprint similarity
|
||||
- `VerdictCalculator` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Diff/VerdictCalculator.cs`) - computes patch verification verdicts from diff results
|
||||
- `InMemoryDiffResultStore` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Diff/Storage/InMemoryDiffResultStore.cs`) - stores diff results with content-addressed IDs
|
||||
- **Models**: `PatchDiffModels`, `DiffEvidenceModels`, `BinaryReference` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Diff/Models/`)
|
||||
- **Interfaces**: `IPatchDiffEngine`, `IDiffResultStore` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Diff/`)
|
||||
- **Source**: SPRINT_20260112_200_004_CHGTRC_byte_diffing.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Submit two binary versions and verify byte-range differences are identified with correct offsets
|
||||
- [ ] Verify section analysis identifies which ELF sections changed (.text, .data, .rodata)
|
||||
- [ ] Verify privacy controls strip raw bytes from proof snippets when configured
|
||||
- [ ] Verify `FunctionRenameDetector` correctly identifies renamed functions between versions
|
||||
- [ ] Verify `VerdictCalculator` produces correct patch verification verdict (patched vs unpatched)
|
||||
- [ ] Verify diff results are stored with deterministic content-addressed IDs
|
||||
@@ -1,27 +0,0 @@
|
||||
# Call-Ngram Fingerprinting for Binary Similarity Analysis
|
||||
|
||||
## Module
|
||||
BinaryIndex
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Call-sequence n-gram extraction from lifted IR for improved cross-compiler binary similarity matching. Generates n-grams (n=2,3,4) from function call sequences and integrates into the semantic fingerprint pipeline with configurable dimension weights (instruction 0.4, CFG 0.3, call-ngram 0.2, semantic 0.1).
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Semantic/`
|
||||
- **Key Classes**:
|
||||
- `CallNgramGenerator` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Semantic/CallNgramGenerator.cs`) - generates `CallNgramFingerprint` from `LiftedFunction` call sequences; computes Jaccard similarity between fingerprints
|
||||
- `CallNgramFingerprint` (record in same file) - contains n-gram hash sets and metadata; has `Empty` sentinel for functions without calls
|
||||
- **Interfaces**: `ICallNgramGenerator` (defined in `CallNgramGenerator.cs`) - `Generate(LiftedFunction)` and `ComputeSimilarity(CallNgramFingerprint, CallNgramFingerprint)`
|
||||
- **Integration**: Used by `EnsembleDecisionEngine` and `FunctionAnalysisBuilder` as one of the matching dimensions with 0.2 default weight
|
||||
- **Source**: SPRINT_20260118_026_BinaryIndex_deltasig_enhancements.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Generate call-ngram fingerprint from a function with known call sequences and verify correct n-gram extraction (n=2,3,4)
|
||||
- [ ] Compute similarity between identical call sequences and verify similarity = 1.0
|
||||
- [ ] Compute similarity between disjoint call sequences and verify similarity = 0.0
|
||||
- [ ] Verify `CallNgramFingerprint.Empty` is returned for functions without call instructions
|
||||
- [ ] Verify call-ngram dimension integrates into ensemble scoring with configurable weight (default 0.2)
|
||||
- [ ] Verify cross-compiler similarity: same source compiled with GCC vs Clang should produce similar call n-grams
|
||||
@@ -1,34 +0,0 @@
|
||||
# Corpus Ingestion and Query Services
|
||||
|
||||
## Module
|
||||
BinaryIndex
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Corpus ingestion and query services with distro-specific connectors for Alpine, Debian, and RPM package ecosystems.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Corpus/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Corpus.Alpine/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Corpus.Debian/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Corpus.Rpm/`
|
||||
- **Key Classes**:
|
||||
- `CorpusIngestionService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Corpus/Services/CorpusIngestionService.cs`) - orchestrates binary ingestion into the corpus
|
||||
- `CorpusQueryService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Corpus/Services/CorpusQueryService.cs`) - queries corpus for function fingerprints and binary metadata
|
||||
- `BatchFingerprintPipeline` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Corpus/Services/BatchFingerprintPipeline.cs`) - batch fingerprint extraction from corpus binaries
|
||||
- `FunctionClusteringService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Corpus/Services/FunctionClusteringService.cs`) - clusters similar functions across corpus
|
||||
- `CveFunctionMappingUpdater` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Corpus/Services/CveFunctionMappingUpdater.cs`) - maps CVEs to affected functions
|
||||
- `AlpineCorpusConnector` / `AlpinePackageExtractor` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Corpus.Alpine/`)
|
||||
- `DebianCorpusConnector` / `DebianPackageExtractor` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Corpus.Debian/`)
|
||||
- `RpmCorpusConnector` / `RpmPackageExtractor` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Corpus.Rpm/`)
|
||||
- Library-specific connectors: `CurlCorpusConnector`, `GlibcCorpusConnector`, `OpenSslCorpusConnector`, `ZlibCorpusConnector` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Corpus/Connectors/`)
|
||||
- **Interfaces**: `ICorpusIngestionService`, `ICorpusQueryService`, `IBinaryCorpusConnector`, `ILibraryCorpusConnector`, `ICorpusRepository`, `ICorpusSnapshotRepository`
|
||||
- **Models**: `FunctionCorpusModels`, `CorpusQuery`, `CorpusSnapshot`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Ingest a Debian package via `DebianCorpusConnector` and verify binary fingerprints are stored
|
||||
- [ ] Ingest an Alpine APK via `AlpineCorpusConnector` and verify secfixes extraction via `ApkBuildSecfixesExtractor`
|
||||
- [ ] Ingest an RPM package via `RpmCorpusConnector` and verify changelog extraction via `SrpmChangelogExtractor`
|
||||
- [ ] Query corpus for a known function fingerprint via `CorpusQueryService` and verify match
|
||||
- [ ] Run `BatchFingerprintPipeline` on a corpus snapshot and verify all binaries are fingerprinted
|
||||
- [ ] Verify `CveFunctionMappingUpdater` creates correct CVE-to-function mappings
|
||||
- [ ] Verify corpus snapshot creation with deterministic snapshot IDs
|
||||
@@ -1,37 +0,0 @@
|
||||
# Cross-Distro Golden Set for Backport Validation
|
||||
|
||||
## Module
|
||||
BinaryIndex
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Golden set infrastructure exists in BinaryIndex with analysis pipeline and API. The advisory's detailed curated test cases (OpenSSL Heartbleed, sudo Baron Samedit, etc.) and specific database schema may not be fully populated yet.
|
||||
|
||||
## What's Implemented
|
||||
- **Golden Set Infrastructure**: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.GoldenSet/` - full authoring, validation, storage, serialization
|
||||
- `GoldenSetExtractor`, `NvdGoldenSetExtractor` - extraction from NVD data
|
||||
- `GoldenSetEnrichmentService` - enriches golden sets with function hints
|
||||
- `GoldenSetValidator`, `ICveValidator` - validation pipeline
|
||||
- `PostgresGoldenSetStore` - PostgreSQL storage
|
||||
- `GoldenSetYamlSerializer` - YAML serialization
|
||||
- **Analysis Pipeline**: `GoldenSetAnalysisPipeline` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Analysis/`) - runs analysis against golden set definitions
|
||||
- **API Controller**: `GoldenSetController` (`src/BinaryIndex/StellaOps.BinaryIndex.WebService/Controllers/`) - CRUD and listing endpoints
|
||||
- **Corpus Connectors**: Alpine (`AlpineCorpusConnector`), Debian (`DebianCorpusConnector`), RPM (`RpmCorpusConnector`) for cross-distro support
|
||||
- **Validation Harness**: `ValidationHarness` and `ValidationHarnessService` for running golden set tests
|
||||
|
||||
## What's Missing
|
||||
- Curated cross-distro test cases for high-impact CVEs (OpenSSL Heartbleed CVE-2014-0160, sudo Baron Samedit CVE-2021-3156, etc.) may not be fully populated in the golden set database
|
||||
- Cross-distro coverage matrix (Alpine vs Debian vs RHEL backport variations for same CVE) may need population
|
||||
- Automated golden set population pipeline from NVD for new CVEs
|
||||
|
||||
## Implementation Plan
|
||||
- Populate golden set database with curated cross-distro test cases for high-impact CVEs
|
||||
- Validate backport detection accuracy across Alpine, Debian, and RHEL for each curated CVE
|
||||
- Build automated pipeline to generate cross-distro golden set entries from NVD advisories
|
||||
- Add cross-distro regression test suite using existing `ValidationHarness` infrastructure
|
||||
|
||||
## Related Documentation
|
||||
- Golden set schema: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.GoldenSet/Models/GoldenSetDefinition.cs`
|
||||
- Authoring workflow: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.GoldenSet/Authoring/`
|
||||
@@ -1,30 +0,0 @@
|
||||
# Delta signature matching and patch coverage analysis
|
||||
|
||||
## Module
|
||||
BinaryIndex
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Delta signature matching traces symbol-level changes between vulnerable and fixed builds. PatchCoverageController exposes an API for patch coverage assessment.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/`, `src/BinaryIndex/StellaOps.BinaryIndex.WebService/Controllers/`
|
||||
- **Key Classes**:
|
||||
- `DeltaSignatureMatcher` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/DeltaSignatureMatcher.cs`) - matches delta signatures against target binaries
|
||||
- `DeltaSignatureGenerator` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/DeltaSignatureGenerator.cs`) - generates delta signatures from binary pairs
|
||||
- `DeltaSigService` / `DeltaSigServiceV2` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/`) - service layer for delta signature operations (V2 adds IR diffs)
|
||||
- `PatchCoverageController` (`src/BinaryIndex/StellaOps.BinaryIndex.WebService/Controllers/PatchCoverageController.cs`) - REST API for patch coverage queries using `IDeltaSignatureRepository`
|
||||
- `SymbolChangeTracer` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/SymbolChangeTracer.cs`) - traces symbol-level changes between builds
|
||||
- `DeltaScopePolicyGate` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/Policy/DeltaScopePolicyGate.cs`) - policy gate for delta scope enforcement
|
||||
- **Interfaces**: `IDeltaSigService`, `IDeltaSignatureGenerator`, `IDeltaSignatureMatcher`, `ISymbolChangeTracer`
|
||||
- **IR Diff**: `IrDiffGenerator` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/IrDiff/`) - generates IR-level diffs between function versions
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Generate a delta signature from known vulnerable/fixed binary pair and verify signature captures changed functions
|
||||
- [ ] Match the generated delta signature against a target binary and verify correct patch status detection
|
||||
- [ ] Query `PatchCoverageController` API for patch coverage and verify coverage percentage
|
||||
- [ ] Verify `SymbolChangeTracer` identifies added, removed, and modified symbols
|
||||
- [ ] Verify `DeltaScopePolicyGate` enforces delta scope policies
|
||||
- [ ] Verify IR-level diff generation captures semantic function changes beyond byte-level diffs
|
||||
@@ -1,30 +0,0 @@
|
||||
# Delta-Signature Predicates (Function-Level Binary Diffs)
|
||||
|
||||
## Module
|
||||
BinaryIndex
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Function-level delta signature predicates (v1 and v2) with signature generation, matching, and symbol change tracing. V2 adds symbol provenance and IR diffs, which is architecturally superior to the byte-level hunks proposed in the advisory.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/`
|
||||
- **Key Classes**:
|
||||
- `DeltaSigPredicate` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/Attestation/DeltaSigPredicate.cs`) - V1 predicate for attestation
|
||||
- `DeltaSigPredicateV2` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/Attestation/DeltaSigPredicateV2.cs`) - V2 predicate with symbol provenance and IR diff support
|
||||
- `DeltaSigPredicateConverter` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/Attestation/DeltaSigPredicateConverter.cs`) - converts between predicate versions
|
||||
- `DeltaSigAttestorIntegration` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/Attestation/DeltaSigAttestorIntegration.cs`) - integrates delta-sig predicates with the Attestor module
|
||||
- `GroundTruthProvenanceResolver` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/Provenance/GroundTruthProvenanceResolver.cs`) - enriches matches with symbol provenance data
|
||||
- `CfgExtractor` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/CfgExtractor.cs`) - extracts control flow graphs for delta-sig generation
|
||||
- **Models**: `Models.cs` in DeltaSig namespace - function match records, signature models
|
||||
- **VEX Integration**: `DeltaSigVexBridge` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/VexIntegration/`)
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Generate a V1 delta-sig predicate and verify it contains function-level diff data
|
||||
- [ ] Generate a V2 delta-sig predicate and verify it includes symbol provenance and IR diff metadata
|
||||
- [ ] Convert between V1 and V2 predicates via `DeltaSigPredicateConverter` and verify data fidelity
|
||||
- [ ] Verify `DeltaSigAttestorIntegration` produces valid attestation predicates for the Attestor module
|
||||
- [ ] Verify `GroundTruthProvenanceResolver` enriches function matches with provenance sources
|
||||
- [ ] Verify V2 predicates flow into VEX observations via `DeltaSigVexBridge`
|
||||
@@ -1,36 +0,0 @@
|
||||
# Disassembly and binary analysis pipeline
|
||||
|
||||
## Module
|
||||
BinaryIndex
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Pluggable disassembly framework with Ghidra integration (BSim + version tracking) for binary analysis capabilities.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Disassembly/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Disassembly.Abstractions/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Disassembly.B2R2/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Disassembly.Iced/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Ghidra/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Decompiler/`
|
||||
- **Key Classes**:
|
||||
- `DisassemblyService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Disassembly/DisassemblyService.cs`) - core disassembly orchestrator
|
||||
- `HybridDisassemblyService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Disassembly/HybridDisassemblyService.cs`) - multi-backend hybrid disassembly with quality-based plugin selection
|
||||
- `DisassemblyPluginRegistry` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Disassembly/DisassemblyPluginRegistry.cs`) - manages registered disassembly plugins
|
||||
- `BinaryFormatDetector` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Disassembly/BinaryFormatDetector.cs`) - detects ELF/PE/Mach-O format from binary headers
|
||||
- `B2R2DisassemblyPlugin` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Disassembly.B2R2/B2R2DisassemblyPlugin.cs`) - B2R2 backend with architecture mapping, instruction mapping, operand parsing
|
||||
- `B2R2LowUirLiftingService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Disassembly.B2R2/B2R2LowUirLiftingService.cs`) - lifts machine code to LowUIR intermediate representation with SSA transformation
|
||||
- `B2R2LifterPool` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Disassembly.B2R2/B2R2LifterPool.cs`) - object pool for B2R2 lifter instances with warm preloading
|
||||
- `IcedDisassemblyPlugin` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Disassembly.Iced/IcedDisassemblyPlugin.cs`) - Iced x86/x64 disassembler plugin
|
||||
- `GhidraDisassemblyPlugin` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Ghidra/Services/GhidraDisassemblyPlugin.cs`) - Ghidra integration
|
||||
- `GhidraDecompilerAdapter` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Decompiler/GhidraDecompilerAdapter.cs`) - Ghidra decompilation with AST comparison
|
||||
- **Abstractions**: `IDisassemblyPlugin`, `IDisassemblyPluginRegistry`, `IDisassemblyService` with models for `BinaryFormat`, `CpuArchitecture`, `DisassembledInstruction`, `InstructionKind`, etc.
|
||||
- **Decompiler**: Full AST comparison engine with recursive parser, code normalizer, semantic equivalence checking
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Load an x86-64 ELF binary via `HybridDisassemblyService` and verify disassembly produces valid instructions
|
||||
- [ ] Verify `BinaryFormatDetector` correctly identifies ELF, PE, and Mach-O formats
|
||||
- [ ] Verify B2R2 plugin handles architecture mapping for x86, x64, ARM, AArch64
|
||||
- [ ] Verify B2R2 LowUIR lifting produces valid IR with SSA form
|
||||
- [ ] Verify Iced plugin disassembles x86/x64 instructions correctly
|
||||
- [ ] Verify `B2R2LifterPool` warm preloading and pool size management
|
||||
- [ ] Verify Ghidra decompiler adapter produces comparable ASTs via `AstComparisonEngine`
|
||||
- [ ] Verify hybrid disassembly quality scoring selects the best plugin for each binary
|
||||
@@ -1,41 +0,0 @@
|
||||
# ELF Normalization and Delta Hashing
|
||||
|
||||
## Module
|
||||
BinaryIndex
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Low-entropy delta signatures over ELF segments with normalization (relocation zeroing, NOP canonicalization, jump table rewriting). Not yet implemented.
|
||||
|
||||
## What's Implemented
|
||||
- **Delta Signature Infrastructure**: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/` - function-level delta signatures with V1 and V2 predicates exist
|
||||
- `DeltaSignatureGenerator` - generates delta signatures (function-level, not ELF-segment-level)
|
||||
- `DeltaSignatureMatcher` - matches delta signatures
|
||||
- `CfgExtractor` - extracts control flow graphs
|
||||
- `IrDiffGenerator` - IR-level diff generation
|
||||
- **Binary Diff Engine**: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Diff/PatchDiffEngine.cs` - byte-level and function-level diffing
|
||||
- **ELF Feature Extraction**: `ElfFeatureExtractor` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/Services/`) - extracts Build-ID and section info from ELF binaries
|
||||
- **Disassembly**: `B2R2DisassemblyPlugin`, `HybridDisassemblyService` - multi-backend disassembly infrastructure
|
||||
|
||||
## What's Missing
|
||||
- ELF segment-level normalization (relocation zeroing to eliminate position-dependent bytes)
|
||||
- NOP canonicalization (normalizing NOP sled variations across compilers)
|
||||
- Jump table rewriting (normalizing indirect jump table entries)
|
||||
- Low-entropy delta hashing over normalized ELF segments (currently delta-sig operates at function level, not segment level)
|
||||
- Segment-aware normalization that handles .text, .rodata, .data sections separately
|
||||
|
||||
## Implementation Plan
|
||||
- Add ELF segment normalization pass to `ElfFeatureExtractor` or new `ElfNormalizer` class
|
||||
- Implement relocation zeroing: identify and zero-out position-dependent bytes (GOT/PLT entries, absolute addresses)
|
||||
- Implement NOP canonicalization: normalize all NOP variants to canonical form
|
||||
- Implement jump table rewriting: normalize indirect jump table entries
|
||||
- Add segment-level delta hashing on normalized output
|
||||
- Integrate with existing `DeltaSignatureGenerator` for hybrid function+segment signatures
|
||||
- Add tests using known ELF binaries with position-dependent variations
|
||||
|
||||
## Related Documentation
|
||||
- Current delta-sig: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/`
|
||||
- ELF extraction: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/Services/ElfFeatureExtractor.cs`
|
||||
- Disassembly: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Disassembly.B2R2/`
|
||||
@@ -1,30 +0,0 @@
|
||||
# Ensemble decision engine for multi-tier matching
|
||||
|
||||
## Module
|
||||
BinaryIndex
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Ensemble decision engine combines multiple matching tiers (range match, Build-ID, fingerprint) with configurable weight tuning for vulnerability classification.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Ensemble/`
|
||||
- **Key Classes**:
|
||||
- `EnsembleDecisionEngine` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Ensemble/EnsembleDecisionEngine.cs`) - combines multiple matching signals with configurable weights into a final vulnerability classification decision
|
||||
- `FunctionAnalysisBuilder` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Ensemble/FunctionAnalysisBuilder.cs`) - builds function analysis inputs including optional ML embeddings
|
||||
- `WeightTuningService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Ensemble/WeightTuningService.cs`) - tunes ensemble weights based on golden set validation results
|
||||
- `EnsembleOptions` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Ensemble/Models.cs`) - configurable weights and thresholds for matching tiers
|
||||
- `MlEmbeddingMatcherAdapter` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.ML/Training/MlEmbeddingMatcherAdapter.cs`) - adapts ML function embeddings for ensemble use
|
||||
- **Interfaces**: `IEnsembleDecisionEngine` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Ensemble/IEnsembleDecisionEngine.cs`)
|
||||
- **Registration**: `EnsembleServiceCollectionExtensions.AddBinarySimilarityServices()` for full pipeline setup
|
||||
- **Benchmarks**: `EnsembleAccuracyBenchmarks`, `EnsembleLatencyBenchmarks` (`src/BinaryIndex/__Tests/StellaOps.BinaryIndex.Benchmarks/`)
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Submit a binary with known vulnerability and verify ensemble produces correct classification
|
||||
- [ ] Verify weight tuning: adjust instruction weight to 0.6 and verify it changes classification outcomes
|
||||
- [ ] Verify multi-tier integration: Build-ID match, fingerprint match, and ML embedding all contribute to score
|
||||
- [ ] Verify `FunctionAnalysisBuilder` correctly assembles all matching dimensions
|
||||
- [ ] Verify `WeightTuningService` optimizes weights based on golden set validation accuracy
|
||||
- [ ] Run accuracy benchmark and verify F1 score meets minimum threshold
|
||||
@@ -1,28 +0,0 @@
|
||||
# Known-build binary catalog (Build-ID + hash-based binary identity)
|
||||
|
||||
## Module
|
||||
BinaryIndex
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
BinaryIdentity model and vulnerability assertion repository implement the binary-key-based catalog using Build-ID and file SHA256 as primary keys.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Persistence/`
|
||||
- **Key Classes**:
|
||||
- `BinaryIdentity` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/Models/BinaryIdentity.cs`) - core model with Build-ID, file SHA256, symbol tables as primary keys
|
||||
- `BinaryIdentityService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/Services/BinaryIdentityService.cs`) - manages binary identity lifecycle
|
||||
- `BinaryVulnerabilityService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Persistence/Services/BinaryVulnerabilityService.cs`) - vulnerability assertion repository with Build-ID catalog lookups and match method mapping (buildid_catalog, delta_signature, etc.)
|
||||
- `CachedBinaryVulnerabilityService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Cache/CachedBinaryVulnerabilityService.cs`) - cached decorator with `LookupByDeltaSignatureAsync`
|
||||
- **Interfaces**: `IBinaryVulnerabilityService`, `IBinaryVulnAssertionRepository` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/Services/`)
|
||||
- **Models**: `FixModels` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Core/Models/`) - `FixState`, `FixStatusResult`, `MatchMethod`, `MatchEvidence`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Register a binary identity with known Build-ID and verify it is stored in the catalog
|
||||
- [ ] Query the catalog by Build-ID and verify the correct binary identity is returned
|
||||
- [ ] Query by file SHA256 hash and verify the correct binary identity is returned
|
||||
- [ ] Assert a vulnerability against a binary identity and verify the assertion is persisted
|
||||
- [ ] Verify `CachedBinaryVulnerabilityService` caches lookups and returns cached results on repeat queries
|
||||
- [ ] Verify match method mapping: `buildid_catalog` maps to `MatchMethod.BuildIdCatalog`
|
||||
@@ -1,28 +0,0 @@
|
||||
# Local Mirror Layer for Corpus Sources
|
||||
|
||||
## Module
|
||||
BinaryIndex
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Local mirror service for caching and serving corpus data from remote sources, supporting offline operation.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Corpus/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Corpus.Debian/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Corpus.Alpine/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Corpus.Rpm/`
|
||||
- **Key Classes**:
|
||||
- `DebianMirrorPackageSource` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Corpus.Debian/DebianMirrorPackageSource.cs`) - mirrors Debian package repositories for offline access
|
||||
- `DebianCorpusConnector` with `ICorpusSnapshotRepository` - creates snapshots of remote corpus state for local use
|
||||
- `AlpineCorpusConnector` with snapshot support - caches Alpine APK package data locally
|
||||
- `RpmCorpusConnector` - caches RPM package data for offline operation
|
||||
- `ICorpusSnapshotRepository` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Corpus/ICorpusSnapshotRepository.cs`) - persists corpus snapshots for offline retrieval
|
||||
- **Interfaces**: `IDebianPackageSource`, `IAlpinePackageSource`, `IRpmPackageSource` - distro-specific package source abstractions
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Fetch packages from Debian mirror source and verify local cache is populated
|
||||
- [ ] Disconnect network and verify cached corpus data is still accessible
|
||||
- [ ] Create a corpus snapshot and verify it captures the complete state of remote data
|
||||
- [ ] Verify Alpine APK packages are cached locally via `AlpineCorpusConnector`
|
||||
- [ ] Verify RPM packages are cached locally via `RpmCorpusConnector`
|
||||
- [ ] Verify snapshot-based queries return consistent results when the remote source changes
|
||||
@@ -1,25 +0,0 @@
|
||||
# Patch Coverage Tracking
|
||||
|
||||
## Module
|
||||
BinaryIndex
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Dedicated patch coverage API endpoint for tracking which CVE patches are covered in binary analysis.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/BinaryIndex/StellaOps.BinaryIndex.WebService/Controllers/`
|
||||
- **Key Classes**:
|
||||
- `PatchCoverageController` (`src/BinaryIndex/StellaOps.BinaryIndex.WebService/Controllers/PatchCoverageController.cs`) - REST API controller for patch coverage queries using `IDeltaSignatureRepository`
|
||||
- `DeltaSignatureMatcher` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/DeltaSignatureMatcher.cs`) - matches delta signatures to assess patch coverage
|
||||
- `DeltaSigService` / `DeltaSigServiceV2` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/`) - service layer for delta-sig operations
|
||||
- **Interfaces**: `IDeltaSignatureRepository` - repository for persisted delta signatures used by patch coverage queries
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Query patch coverage API for a known CVE and verify coverage status (covered/not covered)
|
||||
- [ ] Verify patch coverage percentage calculation: submit binaries with partial patch coverage
|
||||
- [ ] Verify that delta signatures for the CVE fix are used to determine coverage
|
||||
- [ ] Verify API returns correct coverage for batch queries across multiple CVEs
|
||||
- [ ] Verify coverage tracking updates when new delta signatures are added
|
||||
@@ -1,31 +0,0 @@
|
||||
# PatchDiffEngine (Binary Pre/Post Patch Comparison for Fix Verification)
|
||||
|
||||
## Module
|
||||
BinaryIndex
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Compares pre-patch and post-patch binaries at multiple levels (BasicBlock, CFG, StringRefs, Semantic/KSG fingerprints) to determine if a vulnerability has been remediated. Produces structured verification results with confidence scores based on match depth. Core verification logic for the Golden Set Diff Layer.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Diff/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Builders/`
|
||||
- **Key Classes**:
|
||||
- `PatchDiffEngine` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Diff/PatchDiffEngine.cs`) - core engine comparing pre/post binaries using `ISignatureMatcher`, `IFunctionFingerprintExtractor`, and `IFunctionDiffer`; produces `PatchDiffResult` with confidence scores
|
||||
- `PatchDiffEngine` (builders) (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Builders/PatchDiffEngine.cs`) - builder-level diff engine
|
||||
- `FunctionDiffer` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Diff/FunctionDiffer.cs`) - function-level comparison with semantic analysis, call-graph edge diffing, and string reference comparison
|
||||
- `FunctionRenameDetector` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Diff/FunctionRenameDetector.cs`) - detects renamed functions between versions
|
||||
- `VerdictCalculator` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Diff/VerdictCalculator.cs`) - computes fix verification verdict from diff results
|
||||
- **Models**: `PatchDiffResult`, `PatchDiffModels`, `DiffEvidenceModels`, `DiffOptions` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Diff/Models/`)
|
||||
- **Storage**: `IDiffResultStore`, `InMemoryDiffResultStore` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Diff/Storage/`)
|
||||
- **Source**: SPRINT_20260110_012_004_BINDEX_golden_set_diff_verify.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Submit pre-patch and post-patch binaries for a known CVE fix and verify the diff result shows patch applied
|
||||
- [ ] Verify multi-level comparison: BasicBlock, CFG, StringRefs, and semantic fingerprints all contribute to confidence
|
||||
- [ ] Verify `FunctionDiffer` with `IncludeSemanticAnalysis=true` computes semantic similarity
|
||||
- [ ] Verify `FunctionRenameDetector` handles renamed functions between versions
|
||||
- [ ] Verify `VerdictCalculator` produces correct verdict (Fixed, Vulnerable, Unknown) based on diff evidence
|
||||
- [ ] Verify `NoPatchDetected` result is returned when binaries are identical
|
||||
- [ ] Verify diff results are persistable via `IDiffResultStore` with content-addressed IDs
|
||||
@@ -1,29 +0,0 @@
|
||||
# Reproducible Distro Build Pipeline (Container-Based Builders)
|
||||
|
||||
## Module
|
||||
BinaryIndex
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Container-based reproducible build pipeline for Alpine, Debian, and RHEL packages. Rebuilds upstream source packages in isolated containers to produce reference binaries for function-level fingerprint comparison, enabling backport detection by comparing distro-patched binaries against unpatched originals.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Builders/`, `src/BinaryIndex/StellaOps.BinaryIndex.Worker/`
|
||||
- **Key Classes**:
|
||||
- `ReproducibleBuildJob` (`src/BinaryIndex/StellaOps.BinaryIndex.Worker/Jobs/ReproducibleBuildJob.cs`) - background worker job using `IFunctionFingerprintExtractor` and `IPatchDiffEngine` to rebuild packages and compare fingerprints
|
||||
- `ReproducibleBuildOptions` - build configuration (timeout, container images, source package locations)
|
||||
- `IReproducibleBuilder` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Builders/IReproducibleBuilder.cs`) - abstraction for container-based builds
|
||||
- `BuilderOptions` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Builders/BuilderOptions.cs`) - builder configuration
|
||||
- `GuidProvider` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Builders/GuidProvider.cs`) - deterministic GUID generation for reproducibility
|
||||
- **Integration**: Uses `IFingerprintClaimRepository` to store build verification claims; integrates with `IPatchDiffEngine` for post-build binary comparison
|
||||
- **Source**: SPRINT_1227_0002_0001_LB_reproducible_builders.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Trigger a reproducible build for a Debian package and verify reference binaries are produced
|
||||
- [ ] Compare distro-patched binary against unpatched original and verify fingerprint differences
|
||||
- [ ] Verify container isolation: build runs in isolated container with controlled environment
|
||||
- [ ] Verify `FingerprintClaim` records are generated with build provenance evidence
|
||||
- [ ] Verify `GuidProvider` produces deterministic GUIDs for identical build inputs
|
||||
- [ ] Verify backport detection: distro-patched binary with backported fix is correctly identified
|
||||
@@ -1,31 +0,0 @@
|
||||
# Semantic Analysis Library (IR Lifting and Function Fingerprinting)
|
||||
|
||||
## Module
|
||||
BinaryIndex
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Semantic binary analysis with IR lifting, function fingerprint generation, semantic matching, graph extraction, and call n-gram generation for function-level binary comparison.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Semantic/`
|
||||
- **Key Classes**:
|
||||
- `IrLiftingService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Semantic/IrLiftingService.cs`) - lifts machine code to intermediate representation using B2R2
|
||||
- `SemanticFingerprintGenerator` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Semantic/SemanticFingerprintGenerator.cs`) - generates `SemanticFingerprint` using Weisfeiler-Lehman graph hashing (KsgWeisfeilerLehmanV1 algorithm)
|
||||
- `SemanticGraphExtractor` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Semantic/SemanticGraphExtractor.cs`) - extracts key-semantics graphs (KSG) from lifted IR
|
||||
- `SemanticMatcher` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Semantic/SemanticMatcher.cs`) - matches semantic fingerprints for similarity scoring
|
||||
- `CallNgramGenerator` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Semantic/CallNgramGenerator.cs`) - call-sequence n-gram fingerprinting
|
||||
- `WeisfeilerLehmanHasher` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Semantic/Internal/WeisfeilerLehmanHasher.cs`) - WL graph hash implementation
|
||||
- `GraphCanonicalizer` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Semantic/Internal/GraphCanonicalizer.cs`) - graph canonicalization for deterministic hashing
|
||||
- **Models**: `FingerprintModels` (SemanticFingerprint, SemanticFingerprintOptions, SemanticFingerprintAlgorithm), `GraphModels` (KeySemanticsGraph), `IrModels` (LiftedFunction, IrStatement)
|
||||
- **Interfaces**: `IIrLiftingService`, `ISemanticFingerprintGenerator`, `ISemanticGraphExtractor`, `ISemanticMatcher`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Lift a binary function to IR via `IrLiftingService` and verify IR structure contains valid statements
|
||||
- [ ] Generate a semantic fingerprint via `SemanticFingerprintGenerator` and verify hash is deterministic
|
||||
- [ ] Extract a key-semantics graph via `SemanticGraphExtractor` and verify node/edge structure
|
||||
- [ ] Match two fingerprints of the same function (different compilers) via `SemanticMatcher` and verify high similarity
|
||||
- [ ] Verify Weisfeiler-Lehman graph hash produces different hashes for structurally different functions
|
||||
- [ ] Verify `GraphCanonicalizer` produces consistent canonical forms for isomorphic graphs
|
||||
@@ -1,30 +0,0 @@
|
||||
# Symbol Change Tracking in Binary Diffs (SymbolChangeTracer)
|
||||
|
||||
## Module
|
||||
BinaryIndex
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Extends BinaryIndex DeltaSignature module to track which specific symbols changed between binary versions (not just whether they match). Adds change metadata to SymbolMatchResult and provides detailed CFG hash and instruction hash comparison for symbol-level binary change forensics.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/`
|
||||
- **Key Classes**:
|
||||
- `SymbolChangeTracer` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/SymbolChangeTracer.cs`) - traces symbol-level changes between binary versions with detailed CFG hash and instruction hash comparison
|
||||
- `DeltaSignatureGenerator` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/DeltaSignatureGenerator.cs`) - generates delta signatures capturing symbol change metadata
|
||||
- `DeltaSignatureMatcher` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/DeltaSignatureMatcher.cs`) - matches signatures with change tracking awareness
|
||||
- `CfgExtractor` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/CfgExtractor.cs`) - extracts CFG for hash comparison
|
||||
- `IrDiffGenerator` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/IrDiff/IrDiffGenerator.cs`) - generates IR-level diffs for detailed change analysis
|
||||
- **Interfaces**: `ISymbolChangeTracer` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.DeltaSig/ISymbolChangeTracer.cs`)
|
||||
- **Models**: `SymbolMatchResult` with change metadata in `Models.cs`
|
||||
- **Source**: SPRINT_20260112_200_003_BINDEX_symbol_tracking.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Compare two binary versions with known symbol changes and verify `SymbolChangeTracer` identifies which symbols changed
|
||||
- [ ] Verify CFG hash comparison detects control flow changes in modified functions
|
||||
- [ ] Verify instruction hash comparison detects instruction-level changes
|
||||
- [ ] Verify `SymbolMatchResult` includes change metadata (added, removed, modified symbols)
|
||||
- [ ] Verify IR-level diff captures semantic changes beyond byte-level differences
|
||||
- [ ] Verify unchanged symbols are correctly identified as stable between versions
|
||||
@@ -1,28 +0,0 @@
|
||||
# Symbol Source Connectors (Debuginfod, Buildinfo, Ddeb, SecDb)
|
||||
|
||||
## Module
|
||||
BinaryIndex
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Four symbol source connector implementations (Debuginfod, Debian Buildinfo, Ubuntu Ddeb, Alpine SecDb), each with plugin registration and configuration support.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Corpus/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Corpus.Alpine/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Corpus.Debian/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Corpus.Rpm/`
|
||||
- **Key Classes**:
|
||||
- **Alpine SecDb**: `AlpineCorpusConnector` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Corpus.Alpine/AlpineCorpusConnector.cs`) - connects to Alpine security database; `ApkBuildSecfixesExtractor` - extracts secfixes from APK build files
|
||||
- **Debian Buildinfo**: `DebianCorpusConnector` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Corpus.Debian/DebianCorpusConnector.cs`) - connects to Debian buildinfo sources; `DebianMirrorPackageSource` - mirrors Debian repositories
|
||||
- **RPM**: `RpmCorpusConnector` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Corpus.Rpm/RpmCorpusConnector.cs`) - connects to RPM repositories; `SrpmChangelogExtractor` - extracts changelogs from source RPMs
|
||||
- **Library-specific**: `CurlCorpusConnector`, `GlibcCorpusConnector`, `OpenSslCorpusConnector`, `ZlibCorpusConnector` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Corpus/Connectors/`)
|
||||
- **Interfaces**: `IBinaryCorpusConnector`, `ILibraryCorpusConnector`, `IAlpinePackageSource`, `IDebianPackageSource`, `IRpmPackageSource`
|
||||
- **Package Extractors**: `AlpinePackageExtractor`, `DebianPackageExtractor`, `RpmPackageExtractor` - extract binaries from packages using `IBinaryFeatureExtractor`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Connect via `AlpineCorpusConnector` and verify secfixes data is extracted from APK builds
|
||||
- [ ] Connect via `DebianCorpusConnector` and verify buildinfo data is retrieved from Debian mirrors
|
||||
- [ ] Connect via `RpmCorpusConnector` and verify RPM changelog extraction works
|
||||
- [ ] Verify library-specific connectors (OpenSSL, glibc, curl, zlib) retrieve correct binary versions
|
||||
- [ ] Verify all connectors produce `CorpusSnapshot` with consistent snapshot IDs
|
||||
- [ ] Verify package extractors use `IBinaryFeatureExtractor` to extract identity features from packages
|
||||
@@ -1,29 +0,0 @@
|
||||
# Validation Harness and Reproducibility Verification
|
||||
|
||||
## Module
|
||||
BinaryIndex
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Validation harness with determinism validation, SBOM stability checking, and reproducible build verification. Includes local rebuild backend and bundle export/import.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Validation/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.GroundTruth.Reproducible/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Builders/`
|
||||
- **Key Classes**:
|
||||
- `ValidationHarness` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Validation/ValidationHarness.cs`) - main validation harness with `IMatcherAdapterFactory` for pluggable matching
|
||||
- `ValidationHarnessService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.GroundTruth.Reproducible/ValidationHarnessService.cs`) - reproducible-build validation with `ValidationRunContext`
|
||||
- `ReproducibleBuildJob` (`src/BinaryIndex/StellaOps.BinaryIndex.Worker/Jobs/ReproducibleBuildJob.cs`) - local rebuild backend
|
||||
- `KpiRegressionService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.GroundTruth.Reproducible/Services/KpiRegressionService.cs`) - SBOM stability and KPI regression tracking
|
||||
- **Bundle Export/Import**: `ServiceCollectionExtensions.AddCorpusBundleExport/Import` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.GroundTruth.Reproducible/ServiceCollectionExtensions.cs`)
|
||||
- **Interfaces**: `IValidationHarness`, `IKpiRegressionService`, `IReproducibleBuildJob`
|
||||
- **Registration**: `ValidationServiceCollectionExtensions.AddValidationHarness()`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Run validation harness and verify deterministic results for identical inputs
|
||||
- [ ] Verify SBOM stability checking detects unstable hash generation
|
||||
- [ ] Verify reproducible build verification: rebuild from source and compare against original binary
|
||||
- [ ] Verify bundle export produces a self-contained archive importable on air-gapped systems
|
||||
- [ ] Verify bundle import restores corpus data and enables offline validation
|
||||
- [ ] Verify KPI regression tracking across multiple validation harness runs
|
||||
@@ -1,29 +0,0 @@
|
||||
# Vulnerable Binaries Database (BinaryIndex Module)
|
||||
|
||||
## Module
|
||||
BinaryIndex
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Dedicated BinaryIndex module with web service, worker, and library structure for binary vulnerability detection independent of package metadata.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/BinaryIndex/StellaOps.BinaryIndex.WebService/`, `src/BinaryIndex/StellaOps.BinaryIndex.Worker/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Persistence/`
|
||||
- **Key Classes**:
|
||||
- **Web Service**: `ResolutionController` (`Controllers/ResolutionController.cs`) - vulnerability resolution API; `GoldenSetController` - golden set management API; `PatchCoverageController` - patch coverage API; `BinaryIndexOpsController` - ops health/bench/cache endpoints
|
||||
- **Worker**: `ReproducibleBuildJob` (`Jobs/ReproducibleBuildJob.cs`) - background worker for build verification
|
||||
- **Persistence**: `BinaryVulnerabilityService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Persistence/Services/BinaryVulnerabilityService.cs`) - vulnerability detection service with match method mapping and corpus query integration
|
||||
- **Cache**: `CachedBinaryVulnerabilityService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Cache/CachedBinaryVulnerabilityService.cs`) - Valkey-backed caching layer
|
||||
- **Analysis**: `SignatureMatcher`, `TaintGateExtractor`, `ReachGraphBinaryReachabilityService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Analysis/`)
|
||||
- **Ensemble**: `EnsembleDecisionEngine` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Ensemble/`) - multi-tier vulnerability classification
|
||||
- **Program Entry**: `Program.cs` (`src/BinaryIndex/StellaOps.BinaryIndex.WebService/Program.cs`) - configures services, resolution caching, rate limiting
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Query the database for a known vulnerable binary (by Build-ID) and verify vulnerability is detected
|
||||
- [ ] Submit a binary for analysis and verify detection works independent of package metadata
|
||||
- [ ] Verify web service endpoints are accessible: resolution, golden set, patch coverage, ops
|
||||
- [ ] Verify worker job processes reproducible build verification in the background
|
||||
- [ ] Verify cached lookups improve performance on repeated queries
|
||||
- [ ] Verify ensemble decision engine combines all matching signals for final vulnerability classification
|
||||
@@ -1,30 +0,0 @@
|
||||
# Vulnerable Code Fingerprint Matching (CFG + Basic Block + String Refs Ensemble)
|
||||
|
||||
## Module
|
||||
BinaryIndex
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Function-level vulnerability detection independent of package metadata using an ensemble of fingerprint algorithms: basic block hashing, control flow graph fingerprinting, and string reference fingerprinting. Combined generator provides multi-algorithm similarity matching with configurable thresholds. Includes pre-seeded fingerprints for high-impact CVEs in OpenSSL, glibc, zlib, and curl.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Analysis/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Ensemble/`, `src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Persistence/`
|
||||
- **Key Classes**:
|
||||
- `SignatureMatcher` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Analysis/SignatureMatcher.cs`) - matches vulnerability signatures using fingerprint index
|
||||
- `EnsembleDecisionEngine` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Ensemble/EnsembleDecisionEngine.cs`) - combines CFG, basic block, string ref, and ML embedding fingerprints with configurable weights
|
||||
- `FunctionAnalysisBuilder` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Ensemble/FunctionAnalysisBuilder.cs`) - assembles multi-algorithm fingerprint inputs
|
||||
- `SemanticFingerprintGenerator` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Semantic/SemanticFingerprintGenerator.cs`) - KSG-based semantic fingerprinting
|
||||
- `CallNgramGenerator` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Semantic/CallNgramGenerator.cs`) - call-sequence fingerprinting
|
||||
- `BinaryVulnerabilityService` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Persistence/Services/BinaryVulnerabilityService.cs`) - vulnerability lookup with pre-seeded fingerprints
|
||||
- **Models**: `SignatureIndexModels` (`src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.Analysis/Models/`) - fingerprint index models
|
||||
- **Source**: SPRINT_20251226_013_BINIDX_fingerprint_factory.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Match a known vulnerable function (e.g., OpenSSL Heartbleed) against pre-seeded fingerprints and verify detection
|
||||
- [ ] Verify multi-algorithm ensemble: CFG fingerprint + basic block hash + string refs all contribute to match score
|
||||
- [ ] Verify configurable threshold: adjust threshold to 0.8 and verify borderline matches are excluded
|
||||
- [ ] Verify pre-seeded fingerprints exist for high-impact CVEs (OpenSSL, glibc, zlib, curl)
|
||||
- [ ] Verify false positive rate: submit clean binary functions and verify no false matches
|
||||
- [ ] Verify `EnsembleDecisionEngine` weight tuning affects match outcomes
|
||||
@@ -1,26 +0,0 @@
|
||||
# PostgreSQL Backend for Rekor Metadata
|
||||
|
||||
## Module
|
||||
devops
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
PostgreSQL-based Rekor backend with checkpoint storage, submission queue tables, and VEX-Rekor linkage migration.
|
||||
|
||||
## Implementation Details
|
||||
- **Rekor Inclusion Proof Models**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Rekor/RekorInclusionProof.cs` -- model for Rekor inclusion proof data including log index, root hash, tree size, and inclusion hashes.
|
||||
- **Enhanced Rekor Proof Builder**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Rekor/EnhancedRekorProofBuilder.cs` (with partials `.Build.cs`, `.Validate.cs`) -- builds and validates Rekor inclusion proofs, storing metadata for PostgreSQL persistence.
|
||||
- **Pipeline Rekor Entry**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Pipeline/RekorEntry.cs` -- pipeline model for Rekor transparency log entries.
|
||||
- **Rekor Inclusion Verification**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Verification/RekorInclusionVerificationStep.cs` -- verification step that validates Rekor inclusion proofs against stored checkpoints.
|
||||
- **Database Cluster Config**: `devops/database/postgres/cluster-production.yaml`, `cluster-staging.yaml` -- PostgreSQL cluster definitions for CloudNativePG with Rekor metadata tables.
|
||||
- **Database Pooler Config**: `devops/database/postgres/pooler-production.yaml`, `pooler-staging.yaml` -- PgBouncer pooler configurations for Rekor query workloads.
|
||||
- **Compose Configuration**: `devops/compose/docker-compose.stella-ops.yml` -- includes PostgreSQL service configuration for the Rekor backend.
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Submit a DSSE attestation through the proof chain pipeline and verify the Rekor entry metadata (log index, root hash, tree size) is persisted to PostgreSQL
|
||||
- [ ] Query the stored Rekor checkpoint and verify it matches the transparency log state at submission time
|
||||
- [ ] Verify Rekor inclusion proof validation: retrieve a stored proof from PostgreSQL and run `RekorInclusionVerificationStep` to confirm it validates correctly
|
||||
- [ ] Verify the submission queue processes entries in order and marks them as submitted after successful Rekor log inclusion
|
||||
- [ ] Deploy the PostgreSQL cluster configuration and verify the database schema includes the required Rekor metadata tables
|
||||
@@ -1,25 +0,0 @@
|
||||
# VEX-Rekor Linkage
|
||||
|
||||
## Module
|
||||
devops
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Database migration linking VEX observations to Rekor entries for transparent VEX decision tracking.
|
||||
|
||||
## Implementation Details
|
||||
- **VEX Proof Integrator**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Generators/VexProofIntegrator.Helpers.cs` and `VexProofIntegrator.Metadata.cs` -- integrates VEX verdicts with proof chain by generating Rekor-linked evidence, binding VEX decisions to transparency log entries.
|
||||
- **VEX Verdict Proof Payload**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Generators/VexVerdictProofPayload.cs` -- payload model for VEX verdict proofs containing Rekor entry references.
|
||||
- **VEX Verdict ID**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Identifiers/VexVerdictId.cs` -- content-addressed identifier for VEX verdicts, used to link VEX observations to their Rekor transparency log entries.
|
||||
- **VEX Delta Models**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Predicates/VexDeltaChange.cs`, `VexDeltaStatement.cs`, `VexDeltaSummary.cs` -- models for tracking VEX status changes across Rekor-linked observations.
|
||||
- **VEX Merge Trace**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Predicates/VexMergeTrace.cs` -- audit trace for VEX statement merges, including Rekor entry references for each source.
|
||||
- **Compose Configuration**: `devops/compose/docker-compose.stella-ops.yml` -- Docker Compose with PostgreSQL services supporting VEX-Rekor linkage tables.
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Create a VEX verdict via the proof chain pipeline and verify it generates a Rekor entry with the VEX payload; confirm the linkage is persisted in PostgreSQL with both the VEX verdict ID and Rekor log index
|
||||
- [ ] Query VEX observations by Rekor entry and verify the linked VEX status (affected, not_affected, under_investigation) is correctly returned
|
||||
- [ ] Update a VEX status and verify a new Rekor entry is created; confirm the delta change record links both the old and new Rekor entries
|
||||
- [ ] Verify the VEX merge trace includes Rekor references for each merged source statement
|
||||
- [ ] Verify the linkage survives database migration: run the migration on an existing database and confirm existing VEX-Rekor links are preserved
|
||||
@@ -1,31 +0,0 @@
|
||||
# Developer Portal (Astro/Starlight)
|
||||
|
||||
## Module
|
||||
DevPortal
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Static developer portal built with Astro/Starlight framework providing interactive schema viewer, try-it API console, SDK quickstart guides, and offline bundle for air-gapped environments.
|
||||
|
||||
## Implementation Details
|
||||
- **Astro/Starlight Site**: `src/DevPortal/StellaOps.DevPortal.Site/` -- Astro-based static site with Starlight documentation theme. Configuration in `astro.config.mjs`, dependencies in `package.json`.
|
||||
- **Content Configuration**: `src/DevPortal/StellaOps.DevPortal.Site/src/content/config.ts` -- defines content collections for docs with schema validation.
|
||||
- **API Reference Page**: `src/DevPortal/StellaOps.DevPortal.Site/src/content/docs/api-reference.mdx` -- interactive API reference page with OpenAPI spec rendering.
|
||||
- **Getting Started Guide**: `src/DevPortal/StellaOps.DevPortal.Site/src/content/docs/guides/getting-started.mdx` -- SDK quickstart guide for developers.
|
||||
- **Navigation Search Guide**: `src/DevPortal/StellaOps.DevPortal.Site/src/content/docs/guides/navigation-search.mdx` -- documentation for portal navigation and search features.
|
||||
- **OpenAPI Spec**: `src/DevPortal/StellaOps.DevPortal.Site/public/api/stella.yaml` -- OpenAPI specification served by the portal for interactive API exploration.
|
||||
- **Try-It Console**: `src/DevPortal/StellaOps.DevPortal.Site/public/js/try-it-console.js` -- interactive API console for testing endpoints from the browser.
|
||||
- **RapiDoc Loader**: `src/DevPortal/StellaOps.DevPortal.Site/public/js/rapidoc-loader.js` -- loads RapiDoc component for OpenAPI rendering.
|
||||
- **API Reference Script**: `src/DevPortal/StellaOps.DevPortal.Site/public/js/api-reference.js` -- client-side script for API reference page interactions.
|
||||
- **Build Scripts**: `src/DevPortal/StellaOps.DevPortal.Site/scripts/build-offline.mjs` (offline bundle), `check-links.mjs` (link validation), `check-perf.mjs` (performance checks), `run-a11y.mjs` (accessibility audit), `sync-spec.mjs` (OpenAPI spec sync).
|
||||
- **Integrity Check**: `src/DevPortal/StellaOps.DevPortal.Site/SHA256SUMS.devportal-stubs` -- SHA-256 checksums for vendored stubs ensuring supply-chain integrity.
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Build the DevPortal site with `npm run build` and verify it produces a static site with all pages rendered
|
||||
- [ ] Navigate to the API reference page and verify the OpenAPI spec is loaded and interactive (expandable endpoints, try-it functionality)
|
||||
- [ ] Run the offline build script (`build-offline.mjs`) and verify the output bundle is self-contained and works without network access
|
||||
- [ ] Run the link checker script (`check-links.mjs`) and verify no broken links exist in the rendered site
|
||||
- [ ] Run the accessibility audit (`run-a11y.mjs`) and verify no critical a11y violations
|
||||
- [ ] Verify the SHA256SUMS file matches the actual checksums of the devportal stubs
|
||||
@@ -1,26 +0,0 @@
|
||||
# Developer Onboarding / Quick Start Documentation
|
||||
|
||||
## Module
|
||||
docs
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Quick start guide and development documentation exist covering setup, testing, and local CI workflows.
|
||||
|
||||
## Implementation Details
|
||||
- **Repo Documentation Index**: `docs/README.md` -- top-level entry point linking to all documentation areas including setup, architecture, and module dossiers.
|
||||
- **System Architecture**: `docs/07_HIGH_LEVEL_ARCHITECTURE.md` -- high-level architecture overview for new developers.
|
||||
- **Platform Overview**: `docs/modules/platform/architecture-overview.md` -- platform architecture overview covering module interactions and deployment topology.
|
||||
- **Code of Conduct**: `docs/code-of-conduct/CODE_OF_CONDUCT.md` -- binding coding standards for all implementers.
|
||||
- **Testing Practices**: `docs/code-of-conduct/TESTING_PRACTICES.md` -- testing standards and practices for QA and developers.
|
||||
- **Module Dossiers**: `docs/modules/<module>/architecture.md` -- per-module architecture documentation with contracts, schemas, and API surface.
|
||||
- **DevPortal Site**: `src/DevPortal/StellaOps.DevPortal.Site/src/content/docs/guides/getting-started.mdx` -- SDK quickstart guide with code examples and setup instructions.
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Follow the quick start guide from scratch on a clean machine and verify all setup steps complete successfully (clone, install dependencies, build, run tests)
|
||||
- [ ] Verify the `docs/README.md` index page links to all active documentation sections and none return 404
|
||||
- [ ] Verify the DevPortal getting-started guide renders correctly and code examples are syntactically valid
|
||||
- [ ] Verify the architecture overview document is consistent with the current module layout under `src/`
|
||||
- [ ] Verify a new contributor can find the testing practices document from the README and understand the test layer requirements
|
||||
@@ -1,24 +0,0 @@
|
||||
# Implementor Guidelines Document
|
||||
|
||||
## Module
|
||||
docs
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
The implementor guidelines document exists at the declared path covering operational checklists for code and doc changes.
|
||||
|
||||
## Implementation Details
|
||||
- **Code of Conduct**: `docs/code-of-conduct/CODE_OF_CONDUCT.md` -- binding coding standards for all implementers covering naming conventions, error handling patterns, commit discipline, and code review expectations.
|
||||
- **Testing Practices**: `docs/code-of-conduct/TESTING_PRACTICES.md` -- testing standards defining required test layers (unit, integration, E2E, performance, security), determinism requirements, and flakiness policies.
|
||||
- **Repo-Wide Agent Contract**: `CLAUDE.md` -- defines sprint file discipline, directory ownership, git safety rules, documentation sync requirements, dependency license gates, and role-based behavior contracts.
|
||||
- **Module-Local AGENTS.md**: Various `src/<module>/AGENTS.md` files -- per-module implementation guidelines that add module-specific rules without relaxing repo-wide standards.
|
||||
- **Sprint Template**: Defined in `CLAUDE.md` section 6 -- mandatory sprint file structure (Topic & Scope, Dependencies, Delivery Tracker, Execution Log, Decisions & Risks).
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify the `CODE_OF_CONDUCT.md` file exists and covers all sections referenced by the repo-wide agent contract (naming, error handling, commit discipline)
|
||||
- [ ] Verify the `TESTING_PRACTICES.md` file exists and defines all required test layers (unit, integration, E2E, performance, security)
|
||||
- [ ] Verify that at least 5 module directories under `src/` contain a module-local `AGENTS.md` file
|
||||
- [ ] Verify the sprint template in `CLAUDE.md` section 6 is complete and includes all required sections
|
||||
- [ ] Verify a new contributor can locate the implementor guidelines from the `docs/README.md` entry point within 2 navigation steps
|
||||
@@ -1,24 +0,0 @@
|
||||
# Doctor AdvisoryAI Integration
|
||||
|
||||
## Module
|
||||
Doctor
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Integration between Doctor diagnostics and AdvisoryAI system to provide AI-powered health diagnosis explanations, with an evidence schema registry for Doctor health results, prompt templates for health context, and a diagnosis API endpoint. While "AdvisoryAI Pipeline with Guardrails" and "AdvisoryAI Orchestrator" exist in known features, the Doctor-specific AI integration for health diagnostics is a distinct feature.
|
||||
|
||||
## Implementation Details
|
||||
- **AI diagnosis service**: `src/Doctor/__Libraries/StellaOps.Doctor/AdvisoryAI/IDoctorAIDiagnosisService.cs` -- AI-powered diagnosis interface
|
||||
- **Context adapter**: `src/Doctor/__Libraries/StellaOps.Doctor/AdvisoryAI/DoctorContextAdapter.cs`, `IDoctorContextAdapter.cs` -- adapts doctor check results to AI context
|
||||
- **Evidence schema registry**: `src/Doctor/__Libraries/StellaOps.Doctor/AdvisoryAI/IEvidenceSchemaRegistry.cs` -- schemas for doctor health results
|
||||
- **AI context models**: `src/Doctor/__Libraries/StellaOps.Doctor/AdvisoryAI/Models/DoctorAIContext.cs` -- AI context data models
|
||||
- **Web UI**: `src/Web/StellaOps.Web/src/app/features/doctor/` -- Doctor feature UI
|
||||
- **Source**: SPRINT_20260118_022_Doctor_advisoryai_integration.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify AI diagnosis endpoint accepts doctor health check results
|
||||
- [ ] Test context adapter converts health results to proper AI context
|
||||
- [ ] Verify evidence schema registry returns valid schemas
|
||||
- [ ] Test Doctor UI displays AI-powered diagnosis explanations
|
||||
@@ -1,24 +0,0 @@
|
||||
# Doctor Check Quality Improvements (Real Diagnostics Replacing Mocks)
|
||||
|
||||
## Module
|
||||
Doctor
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Replaced mock implementations in PolicyEngineHealthCheck, OidcProviderConnectivityCheck, and FipsComplianceCheck with real diagnostic logic. Added discriminating evidence fields for AI reasoning and safety annotations (IsDestructive/DryRunVariant) for destructive remediation commands.
|
||||
|
||||
## Implementation Details
|
||||
- **Policy engine check**: `src/Doctor/__Plugins/StellaOps.Doctor.Plugin.Policy/Checks/PolicyEngineHealthCheck.cs`
|
||||
- **OIDC connectivity check**: `src/Doctor/__Plugins/StellaOps.Doctor.Plugin.Auth/Checks/OidcProviderConnectivityCheck.cs`
|
||||
- **FIPS compliance check**: `src/Doctor/__Plugins/StellaOps.Doctor.Plugin.Crypto/Checks/FipsComplianceCheck.cs`
|
||||
- **Other crypto checks**: eIDAS (`EidasComplianceCheck.cs`), GOST (`GostAvailabilityCheck.cs`), HSM (`HsmPkcs11AvailabilityCheck.cs`), SM crypto (`SmCryptoAvailabilityCheck.cs`)
|
||||
- **Remediation models**: `src/__Libraries/StellaOps.Doctor/Models/RemediationStep.cs` -- includes IsDestructive/DryRunVariant safety annotations
|
||||
- **Source**: SPRINT_20260118_015_Doctor_check_quality_improvements.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify PolicyEngineHealthCheck performs real diagnostic (not mock)
|
||||
- [ ] Test OidcProviderConnectivityCheck actually probes OIDC endpoint
|
||||
- [ ] Verify FipsComplianceCheck validates FIPS mode status
|
||||
- [ ] Test remediation commands include safety annotations (IsDestructive, DryRunVariant)
|
||||
@@ -1,26 +0,0 @@
|
||||
# Doctor Diagnostic Bundle Export for Support Tickets
|
||||
|
||||
## Module
|
||||
Doctor
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Generates comprehensive shareable diagnostic bundles (.zip) for support tickets containing doctor check results, system configuration, evidence, and remediation suggestions. Enables self-service troubleshooting without support escalation.
|
||||
|
||||
## Implementation Details
|
||||
- **Report storage**: `src/Doctor/StellaOps.Doctor.WebService/Services/IReportStorageService.cs` -- report storage interface
|
||||
- **In-memory storage**: `src/Doctor/StellaOps.Doctor.WebService/Services/InMemoryReportStorageService.cs`
|
||||
- **Postgres storage**: `src/Doctor/StellaOps.Doctor.WebService/Services/PostgresReportStorageService.cs`
|
||||
- **Doctor run service**: `src/Doctor/StellaOps.Doctor.WebService/Services/DoctorRunService.cs` -- orchestrates diagnostic runs
|
||||
- **Doctor endpoints**: `src/Doctor/StellaOps.Doctor.WebService/Endpoints/DoctorEndpoints.cs` -- API endpoints for triggering runs and retrieving results
|
||||
- **Models**: `src/Doctor/StellaOps.Doctor.WebService/Contracts/DoctorModels.cs` -- diagnostic bundle models
|
||||
- **Tests**: `src/Doctor/__Tests/StellaOps.Doctor.WebService.Tests/Services/InMemoryReportStorageServiceTests.cs`, `DoctorRunServiceTests.cs`
|
||||
- **Source**: SPRINT_20260112_001_009_DOCTOR_self_service.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify diagnostic bundle export generates valid .zip file
|
||||
- [ ] Test bundle includes check results, configuration, and remediation suggestions
|
||||
- [ ] Verify bundle can be stored/retrieved via both in-memory and Postgres backends
|
||||
- [ ] Test Doctor API endpoints for triggering runs and downloading bundles
|
||||
@@ -1,39 +0,0 @@
|
||||
# Doctor Diagnostics Runner
|
||||
|
||||
## Module
|
||||
Doctor
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Doctor plugin infrastructure with multiple plugins (Vex, BinaryAnalysis, Notify, Observability, Timestamping) providing health checks, diagnostics, and remediation commands is implemented.
|
||||
|
||||
## Implementation Details
|
||||
- **Plugin interface**: `src/Doctor/__Plugins/StellaOps.Doctor.Plugins.Core/IDoctorPlugin.cs` -- base plugin contract
|
||||
- **Plugins** (14 total):
|
||||
- Agent: `AgentDoctorPlugin.cs` -- agent health (capacity, heartbeat, version, certificates, cluster, task queue)
|
||||
- Attestor: `AttestorDoctorPlugin.cs` -- Rekor, cosign, signing key, transparency log checks
|
||||
- Auth: `AuthDoctorPlugin.cs` -- OIDC, signing key, token service checks
|
||||
- BinaryAnalysis: `BinaryAnalysisDoctorPlugin.cs` -- debuginfod, buildinfo cache, corpus mirror, symbol recovery
|
||||
- Compliance: `CompliancePlugin.cs` -- audit readiness, evidence tamper, provenance completeness, attestation signing
|
||||
- Crypto: eIDAS, FIPS, GOST, HSM, SM crypto, cert chain validation checks
|
||||
- Environment: `EnvironmentDoctorPlugin.cs` -- connectivity, capacity, drift, secrets, network policy
|
||||
- EvidenceLocker: `EvidenceLockerDoctorPlugin.cs` -- evidence index, Merkle anchor, provenance chain
|
||||
- Notify: `NotifyDoctorPlugin.cs` -- Slack, Teams, Email, Webhook connectivity checks
|
||||
- Observability: `ObservabilityDoctorPlugin.cs` -- OTLP, Prometheus, log directory checks
|
||||
- Operations: `OperationsDoctorPlugin.cs` -- job queue, dead letter queue, scheduler checks
|
||||
- Policy: `PolicyEngineHealthCheck.cs`
|
||||
- Postgres: `PostgresDoctorPlugin.cs` -- connectivity, connection pool, migration status
|
||||
- Release: `ReleaseDoctorPlugin.cs` -- active release, environment readiness, promotion gates, rollback
|
||||
- Scanner: `ScannerDoctorPlugin.cs` -- SBOM generation, vulnerability scan, reachability, slice cache, witness graph
|
||||
- Storage: `StorageDoctorPlugin.cs` -- disk space, backup directory, evidence locker write
|
||||
- Timestamping: `TimestampingHealthCheckPlugin.cs` -- TSA, OCSP, CRL, time skew, evidence staleness
|
||||
- Vex: `VexDoctorPlugin.cs` -- VEX document validation, issuer trust, schema compliance
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify all 14+ plugins register and execute successfully
|
||||
- [ ] Test plugin discovery and loading mechanism
|
||||
- [ ] Verify each plugin category produces valid health check results
|
||||
- [ ] Test failure scenarios for each check type
|
||||
@@ -1,29 +0,0 @@
|
||||
# Doctor Health Checks for Integrations
|
||||
|
||||
## Module
|
||||
Doctor
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Individual health checks for webhooks, Slack, Teams, email, OTLP endpoints, debuginfod, corpus mirrors, and more are implemented as pluggable Doctor checks.
|
||||
|
||||
## Implementation Details
|
||||
- **Webhook checks**: `src/Doctor/__Plugins/StellaOps.Doctor.Plugin.Notify/Checks/WebhookConfiguredCheck.cs`, `WebhookConnectivityCheck.cs`
|
||||
- **Slack checks**: `SlackConfiguredCheck.cs`, `SlackConnectivityCheck.cs`
|
||||
- **Teams checks**: `TeamsConfiguredCheck.cs`, `TeamsConnectivityCheck.cs`
|
||||
- **Email checks**: `EmailConfiguredCheck.cs`, `EmailConnectivityCheck.cs`
|
||||
- **Queue checks**: `NotifyQueueHealthCheck.cs`
|
||||
- **OTLP check**: `src/Doctor/__Plugins/StellaOps.Doctor.Plugin.Observability/Checks/OtlpEndpointCheck.cs`
|
||||
- **Prometheus check**: `PrometheusScrapeCheck.cs`
|
||||
- **Debuginfod check**: `src/Doctor/__Plugins/StellaOps.Doctor.Plugin.BinaryAnalysis/Checks/DebuginfodAvailabilityCheck.cs`
|
||||
- **Corpus mirror check**: `CorpusMirrorFreshnessCheck.cs`
|
||||
- **Tests**: `src/Doctor/__Tests/StellaOps.Doctor.Plugin.Notify.Tests/`, `StellaOps.Doctor.Plugin.Observability.Tests/`, `StellaOps.Doctor.Plugin.BinaryAnalysis.Tests/`
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify webhook connectivity check probes configured endpoint
|
||||
- [ ] Test Slack/Teams/Email configured checks detect missing configuration
|
||||
- [ ] Verify OTLP and Prometheus checks validate endpoint reachability
|
||||
- [ ] Test debuginfod and corpus mirror freshness checks
|
||||
@@ -1,21 +0,0 @@
|
||||
# Doctor Runbook URL Integration
|
||||
|
||||
## Module
|
||||
Doctor
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Extended Doctor diagnostic framework to support runbook URL links in remediation output, making operational runbooks discoverable directly from `stella doctor` CLI and UI results.
|
||||
|
||||
## Implementation Details
|
||||
- **Remediation models**: `src/__Libraries/StellaOps.Doctor/Models/RemediationStep.cs` -- includes runbook URL field
|
||||
- **Doctor models**: `src/Doctor/StellaOps.Doctor.WebService/Contracts/DoctorModels.cs` -- API models with runbook references
|
||||
- **Auto-remediation**: `src/Doctor/__Plugins/StellaOps.Doctor.Plugin.Timestamping/AutoRemediation.cs` -- remediation with linked runbooks
|
||||
- **Source**: SPRINT_20260117_029_DOCS
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify doctor check results include runbook URLs where applicable
|
||||
- [ ] Test CLI `stella doctor` output displays runbook links
|
||||
- [ ] Verify Web UI Doctor page shows clickable runbook links
|
||||
@@ -1,28 +0,0 @@
|
||||
# Doctor Scheduled Runs with Alerting and Trend Analysis
|
||||
|
||||
## Module
|
||||
Doctor
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Cron-based scheduled execution of Doctor health checks with configurable schedules, trend data storage for historical analysis, anomaly detection for health metric degradation, and alerting service integration for notifications on health regressions.
|
||||
|
||||
## Implementation Details
|
||||
- **Schedule worker**: `src/Doctor/StellaOps.Doctor.Scheduler/DoctorScheduleWorker.cs` -- background worker for cron-based execution
|
||||
- **Schedule executor**: `src/Doctor/StellaOps.Doctor.Scheduler/Services/ScheduleExecutor.cs` -- executes scheduled doctor runs
|
||||
- **Schedule models**: `src/Doctor/StellaOps.Doctor.Scheduler/Models/DoctorSchedule.cs` -- schedule configuration
|
||||
- **Execution tracking**: `src/Doctor/StellaOps.Doctor.Scheduler/Models/ScheduleExecution.cs` -- execution records
|
||||
- **Trend data**: `src/Doctor/StellaOps.Doctor.Scheduler/Models/TrendDataPoint.cs` -- trend analysis data model
|
||||
- **Alert service**: `src/Doctor/StellaOps.Doctor.Scheduler/Services/IAlertService.cs` -- alerting interface for health regressions
|
||||
- **Schedule repository**: `src/Doctor/StellaOps.Doctor.Scheduler/Services/IScheduleRepository.cs`
|
||||
- **Trend repository**: `src/Doctor/StellaOps.Doctor.Scheduler/Services/ITrendRepository.cs` -- trend data persistence
|
||||
- **Options**: `src/Doctor/StellaOps.Doctor.Scheduler/Options/DoctorSchedulerOptions.cs` -- scheduler configuration
|
||||
- **Source**: SPRINT_20260118_020_Doctor_scheduled_runs_trending.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify scheduled doctor runs execute at configured intervals
|
||||
- [ ] Test trend data accumulation over multiple runs
|
||||
- [ ] Verify alert service triggers on health degradation
|
||||
- [ ] Test schedule CRUD operations via repository
|
||||
@@ -1,25 +0,0 @@
|
||||
# Doctor YAML Pack Loader and First-Party Packs
|
||||
|
||||
## Module
|
||||
Doctor
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
YAML-based diagnostic pack loader allowing first-party and user-defined diagnostic packs, with a self-service Doctor UI page for running health checks interactively.
|
||||
|
||||
## Implementation Details
|
||||
- **Plugin core**: `src/Doctor/__Plugins/StellaOps.Doctor.Plugins.Core/IDoctorPlugin.cs` -- plugin interface for pack loading
|
||||
- **First-party packs**: 14+ doctor plugins under `src/Doctor/__Plugins/` covering Agent, Attestor, Auth, BinaryAnalysis, Compliance, Crypto, Environment, EvidenceLocker, Notify, Observability, Operations, Policy, Postgres, Release, Scanner, Storage, Timestamping, Vex
|
||||
- **WebService**: `src/Doctor/StellaOps.Doctor.WebService/` -- web service for Doctor UI and API
|
||||
- **Doctor endpoints**: `src/Doctor/StellaOps.Doctor.WebService/Endpoints/DoctorEndpoints.cs` -- API for loading and running packs
|
||||
- **Doctor service options**: `src/Doctor/StellaOps.Doctor.WebService/Options/DoctorServiceOptions.cs` -- configuration including pack paths
|
||||
- **Web UI**: `src/Web/StellaOps.Web/src/app/features/doctor/` -- self-service Doctor UI page
|
||||
- **Source**: SPRINT_20260113_005_DOCTOR
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify YAML pack loading discovers and registers all first-party packs
|
||||
- [ ] Test custom/user-defined pack loading from configured paths
|
||||
- [ ] Verify Doctor UI page allows interactive check execution
|
||||
- [ ] Test pack results display correctly in UI
|
||||
@@ -1,31 +0,0 @@
|
||||
# EPSS Signal-Ready Layer (Tenant-Scoped Actionable Events)
|
||||
|
||||
## Module
|
||||
Feedser
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
EPSS signal emission pipeline with change detection, signal flow integration, and signal attaching to risk evaluations. EPSS evidence feeds into the policy determinization scoring system.
|
||||
|
||||
## Implementation Details
|
||||
- **EPSS Signal Attacher**: `src/Feedser/StellaOps.Feedser.Core/Signals/EpssSignalAttacher.cs` (implements `ISignalAttacher`) -- attaches EPSS probability scores to findings as risk signals, enabling downstream policy evaluation and scoring.
|
||||
- **KEV Signal Attacher**: `src/Feedser/StellaOps.Feedser.Core/Signals/KevSignalAttacher.cs` (implements `ISignalAttacher`) -- attaches CISA Known Exploited Vulnerabilities (KEV) status signals to findings.
|
||||
- **Signal Attacher Interface**: `src/Feedser/StellaOps.Feedser.Core/Signals/ISignalAttacher.cs` -- contract for signal attachment implementations.
|
||||
- **Signal DI Extensions**: `src/Feedser/StellaOps.Feedser.Core/Signals/SignalAttacherServiceExtensions.cs` -- registers `EpssSignalAttacher` and `KevSignalAttacher` in the DI container.
|
||||
- **Function Signature Extractor**: `src/Feedser/StellaOps.Feedser.Core/FunctionSignatureExtractor.cs` -- extracts function signatures from patch data for vulnerability correlation.
|
||||
- **Hunk Signature Extractor**: `src/Feedser/StellaOps.Feedser.Core/HunkSigExtractor.cs` -- extracts patch hunk signatures for binary-level vulnerability matching.
|
||||
- **Patch Signature Model**: `src/Feedser/StellaOps.Feedser.Core/Models/PatchSignature.cs` -- model for extracted patch signatures.
|
||||
- **Binary Fingerprinting**: `src/Feedser/StellaOps.Feedser.BinaryAnalysis/BinaryFingerprintFactory.cs` -- factory for creating binary fingerprints using multiple strategies.
|
||||
- **Fingerprinters**: `src/Feedser/StellaOps.Feedser.BinaryAnalysis/Fingerprinters/InstructionHashFingerprinter.cs` (instruction-level hashing), `SimplifiedTlshFingerprinter.cs` (TLSH fuzzy hashing).
|
||||
- **Binary Fingerprint Model**: `src/Feedser/StellaOps.Feedser.BinaryAnalysis/Models/BinaryFingerprint.cs` -- model for binary fingerprint data.
|
||||
- **Tests**: `src/Feedser/__Tests/StellaOps.Feedser.Core.Tests/Signals/EpssSignalAttacherTests.cs`, `src/Feedser/__Tests/StellaOps.Feedser.Core.Tests/FunctionSignatureExtractorTests.cs`, `HunkSigExtractorTests.cs`; `src/Feedser/__Tests/StellaOps.Feedser.BinaryAnalysis.Tests/BinaryFingerprintTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Attach an EPSS signal to a finding via `EpssSignalAttacher` and verify the EPSS probability score is available in the finding's signal set
|
||||
- [ ] Attach a KEV signal and verify the finding is marked as a known exploited vulnerability
|
||||
- [ ] Verify signal change detection: attach an EPSS signal, update the EPSS score, and confirm only the changed signal triggers a re-evaluation event
|
||||
- [ ] Extract function signatures from a patch file and verify they match expected signatures for the patched functions
|
||||
- [ ] Generate a binary fingerprint using `InstructionHashFingerprinter` and verify it produces a deterministic hash for the same binary input
|
||||
- [ ] Generate a TLSH fingerprint via `SimplifiedTlshFingerprinter` and verify it produces a similarity-preserving hash that detects near-duplicate binaries
|
||||
@@ -1,29 +0,0 @@
|
||||
# Admin audit trails (comprehensive logging of changes)
|
||||
|
||||
## Module
|
||||
Findings
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Policy evaluation trace snapshots, evidence graph builder, and exception event auditing provide admin-level audit trails for governance.
|
||||
|
||||
## Implementation Details
|
||||
- **Ledger Event Write Service**: `src/Findings/StellaOps.Findings.Ledger/Services/LedgerEventWriteService.cs` -- writes append-only ledger events; every finding state change, VEX decision, and policy evaluation is recorded as an immutable event with timestamp, actor, and payload.
|
||||
- **Evidence Graph Builder**: `src/Findings/StellaOps.Findings.Ledger.WebService/Services/EvidenceGraphBuilder.cs` -- constructs evidence subgraphs from ledger events and attestation pointers for audit visualization.
|
||||
- **Attestation Pointer Service**: `src/Findings/StellaOps.Findings.Ledger/Services/AttestationPointerService.cs` -- links findings to their attestation evidence for audit chain tracking.
|
||||
- **Attestation Status Calculator**: `src/Findings/StellaOps.Findings.Ledger/Infrastructure/Attestation/AttestationStatusCalculator.cs` -- computes attestation coverage status for audit dashboards.
|
||||
- **Decision Service**: `src/Findings/StellaOps.Findings.Ledger/Services/DecisionService.cs` (implements `IDecisionService`) -- records policy decisions with full trace context.
|
||||
- **Decision Hook Interface**: `src/Findings/StellaOps.Findings.Ledger/Services/IDecisionHook.cs` -- extension point for hooking into decision events for custom audit processing.
|
||||
- **Ledger Incident Coordinator**: `src/Findings/StellaOps.Findings.Ledger/Services/Incident/LedgerIncidentCoordinator.cs` -- coordinates incident response workflows with audit trail recording.
|
||||
- **Ledger Telemetry**: `src/Findings/StellaOps.Findings.Ledger/Observability/LedgerTelemetry.cs` -- OpenTelemetry instrumentation for ledger operations providing trace-level audit visibility.
|
||||
- **Ledger Timeline**: `src/Findings/StellaOps.Findings.Ledger/Observability/LedgerTimeline.cs` -- timeline view of ledger events for audit review.
|
||||
- **Tests**: `src/Findings/StellaOps.Findings.Ledger.Tests/FindingsLedgerIntegrationTests.cs`, `src/Findings/__Tests/StellaOps.Findings.Ledger.Tests/LedgerEventWriteServiceTests.cs`, `src/Findings/__Tests/StellaOps.Findings.Ledger.Tests/Services/LedgerEventWriteServiceIncidentTests.cs`, `src/Findings/StellaOps.Findings.Ledger.Tests/Observability/LedgerTelemetryTests.cs`, `LedgerTimelineTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Submit a finding state change via `LedgerEventWriteService` and verify the event is recorded with correct timestamp, actor, and payload in the append-only ledger
|
||||
- [ ] Query the evidence graph for a finding that has multiple audit events and verify the graph shows the chronological chain of state changes
|
||||
- [ ] Trigger a policy decision and verify `DecisionService` records the full trace context (rule name, inputs, outcome) as an auditable event
|
||||
- [ ] Verify incident coordination audit: create an incident via `LedgerIncidentCoordinator` and confirm the incident creation, status changes, and resolution are all recorded in the ledger
|
||||
- [ ] Verify telemetry integration: perform a ledger operation and confirm OpenTelemetry spans are emitted with the correct operation name and attributes
|
||||
@@ -1,27 +0,0 @@
|
||||
# Attested Reduction Scoring in Findings Ledger
|
||||
|
||||
## Module
|
||||
Findings
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Anchor-aware evidence wiring into Findings Ledger scoring with reduction profile metadata, hard-fail flag, short-circuit reason, and anchor metadata (DSSE envelope digest, Rekor log index/entry) in API responses.
|
||||
|
||||
## Implementation Details
|
||||
- **Finding Scoring Service**: `src/Findings/StellaOps.Findings.Ledger.WebService/Services/FindingScoringService.cs` -- computes attested reduction scores combining CVSS base score with reachability, VEX, and attestation evidence; includes anchor metadata (DSSE digest, Rekor index) in the score breakdown.
|
||||
- **Finding Evidence Provider**: `src/Findings/StellaOps.Findings.Ledger.WebService/Services/FindingEvidenceProvider.cs` -- resolves evidence artifacts for scoring, including attestation anchors and proof chain references.
|
||||
- **Scoring Contracts**: `src/Findings/StellaOps.Findings.Ledger.WebService/Contracts/ScoringContracts.cs` -- API DTOs including reduction profile, hard-fail flag, short-circuit reason, and anchor metadata fields.
|
||||
- **Attestation Contracts**: `src/Findings/StellaOps.Findings.Ledger.WebService/Contracts/AttestationContracts.cs` -- DTOs for attestation evidence references in scoring responses.
|
||||
- **Attestation Pointer Contracts**: `src/Findings/StellaOps.Findings.Ledger.WebService/Contracts/AttestationPointerContracts.cs` -- DTOs for attestation pointer queries.
|
||||
- **Attestation Query Service**: `src/Findings/StellaOps.Findings.Ledger.WebService/Services/AttestationQueryService.cs` -- queries attestation evidence linked to findings for scoring input.
|
||||
- **Scoring Endpoints**: `src/Findings/StellaOps.Findings.Ledger.WebService/Endpoints/ScoringEndpoints.cs` -- REST endpoints exposing scored findings with attested reduction metadata.
|
||||
- **Tests**: `src/Findings/__Tests/StellaOps.Findings.Ledger.Tests/Services/FindingScoringServiceTests.cs`, `src/Findings/StellaOps.Findings.Ledger.Tests/Exports/AttestationQueryServiceTests.cs`, `src/Findings/__Tests/StellaOps.Findings.Ledger.Tests/Integration/ScoringEndpointsIntegrationTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Submit a finding with a DSSE-attested reachability proof and verify the scoring response includes the reduction from the attestation with anchor metadata (DSSE digest, Rekor log index)
|
||||
- [ ] Submit a finding with a hard-fail attestation (e.g., missing required evidence) and verify the score response includes `hardFail: true` with the short-circuit reason
|
||||
- [ ] Verify reduction profile: submit a finding with multiple evidence types and verify the response includes a breakdown of each reduction source and its contribution percentage
|
||||
- [ ] Verify the scoring endpoint returns anchor metadata: query a scored finding and confirm the response includes `dsseEnvelopeDigest` and `rekorLogIndex` fields
|
||||
- [ ] Verify short-circuit: submit a finding with an "affected" VEX status and verify scoring short-circuits with the appropriate reason without evaluating further reductions
|
||||
@@ -1,26 +0,0 @@
|
||||
# CVSS/VEX Sorting (Multi-Dimension)
|
||||
|
||||
## Module
|
||||
Findings
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
CVSS v4.0 scoring engine combined with findings summary builder supports multi-dimensional sorting by CVSS and VEX status.
|
||||
|
||||
## Implementation Details
|
||||
- **Finding Summary Builder**: `src/Findings/StellaOps.Findings.Ledger.WebService/Services/FindingSummaryBuilder.cs` -- builds finding summaries with sortable dimensions including CVSS score, VEX status, severity, and component name.
|
||||
- **Finding Summary Service**: `src/Findings/StellaOps.Findings.Ledger.WebService/Services/FindingSummaryService.cs` -- queries and sorts finding summaries by multiple dimensions.
|
||||
- **Finding Summary Endpoints**: `src/Findings/StellaOps.Findings.Ledger.WebService/Endpoints/FindingSummaryEndpoints.cs` -- REST endpoints for querying sorted finding summaries with multi-dimension ordering.
|
||||
- **Finding Summary DTO**: `src/Findings/StellaOps.Findings.Ledger.WebService/Contracts/FindingSummary.cs` -- API response model including CVSS score, VEX status, severity level, and component identity.
|
||||
- **VEX Consensus Service**: `src/Findings/StellaOps.Findings.Ledger.WebService/Services/VexConsensusService.cs` -- aggregates VEX decisions across multiple sources to determine consensus status for sorting.
|
||||
- **VEX Lens Contracts**: `src/Findings/StellaOps.Findings.Ledger.WebService/Contracts/VexLensContracts.cs` -- DTOs for VEX status data used in multi-dimension sorting.
|
||||
- **Tests**: `src/Findings/__Tests/StellaOps.Findings.Ledger.Tests/Services/FindingSummaryBuilderTests.cs`, `src/Findings/__Tests/StellaOps.Findings.Ledger.Tests/ScoredFindingsQueryServiceTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Query finding summaries sorted by CVSS score descending and verify the results are ordered from highest to lowest CVSS score
|
||||
- [ ] Query finding summaries sorted by VEX status and verify findings are grouped by status (affected, not_affected, under_investigation, fixed)
|
||||
- [ ] Apply multi-dimension sorting (primary: VEX status, secondary: CVSS score) and verify the ordering respects both dimensions
|
||||
- [ ] Verify findings with no VEX status are sorted correctly (treated as "no_vex" or equivalent default)
|
||||
- [ ] Submit findings with mixed CVSS v3.1 and v4.0 scores and verify the summary builder normalizes them for consistent sorting
|
||||
@@ -1,33 +0,0 @@
|
||||
# Findings Ledger with Append-Only Events
|
||||
|
||||
## Module
|
||||
Findings
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Findings Ledger with event write service, event constants, integration tests, and contract tests for append-only event persistence.
|
||||
|
||||
## Implementation Details
|
||||
- **Ledger Event Write Service**: `src/Findings/StellaOps.Findings.Ledger/Services/LedgerEventWriteService.cs` -- core service that appends immutable events to the findings ledger; each event has a unique chain ID, timestamp, event type, actor, and JSON payload.
|
||||
- **Ledger Event Models**: `src/Findings/StellaOps.Findings.Ledger/Domain/LedgerEventModels.cs` -- domain models for ledger events including event type, payload, and metadata.
|
||||
- **Ledger Event Constants**: `src/Findings/StellaOps.Findings.Ledger/Domain/LedgerEventConstants.cs` -- event type constants (e.g., FindingCreated, VexStatusChanged, PolicyEvaluated, DecisionRecorded).
|
||||
- **Ledger Chain ID Generator**: `src/Findings/StellaOps.Findings.Ledger/Domain/LedgerChainIdGenerator.cs` -- generates content-addressed chain IDs linking events to their predecessors for tamper detection.
|
||||
- **Evidence Reference**: `src/Findings/StellaOps.Findings.Ledger/Domain/EvidenceReference.cs` -- references to evidence artifacts attached to ledger events.
|
||||
- **Ledger Event Repository Interface**: `src/Findings/StellaOps.Findings.Ledger/Infrastructure/ILedgerEventRepository.cs` -- persistence contract for ledger events.
|
||||
- **Ledger Event Stream Interface**: `src/Findings/StellaOps.Findings.Ledger/Infrastructure/ILedgerEventStream.cs` -- streaming interface for replaying event sequences.
|
||||
- **Postgres Ledger Event Repository**: `src/Findings/StellaOps.Findings.Ledger/Infrastructure/Postgres/PostgresLedgerEventRepository.cs` -- PostgreSQL implementation of the event repository with append-only guarantees.
|
||||
- **Postgres Ledger Event Stream**: `src/Findings/StellaOps.Findings.Ledger/Infrastructure/Postgres/PostgresLedgerEventStream.cs` -- PostgreSQL event stream for replay and projection.
|
||||
- **In-Memory Ledger Event Repository**: `src/Findings/StellaOps.Findings.Ledger/Infrastructure/InMemory/InMemoryLedgerEventRepository.cs` -- in-memory implementation for testing.
|
||||
- **Ledger Event Request/Response**: `src/Findings/StellaOps.Findings.Ledger.WebService/Contracts/LedgerEventRequest.cs`, `LedgerEventResponse.cs` -- API DTOs for event submission and retrieval.
|
||||
- **Ledger Event Mapping**: `src/Findings/StellaOps.Findings.Ledger.WebService/Mappings/LedgerEventMapping.cs` -- maps between domain events and API DTOs.
|
||||
- **Tests**: `src/Findings/StellaOps.Findings.Ledger.Tests/FindingsLedgerIntegrationTests.cs`, `FindingsLedgerWebServiceContractTests.cs`, `src/Findings/__Tests/StellaOps.Findings.Ledger.Tests/LedgerEventWriteServiceTests.cs`, `src/Findings/StellaOps.Findings.Ledger.Tests/Infrastructure/InMemoryLedgerEventRepositoryTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Submit a finding event via the REST API and verify it is persisted in the ledger with a valid chain ID linking to the previous event
|
||||
- [ ] Verify append-only guarantee: attempt to modify or delete an existing ledger event and confirm the operation is rejected
|
||||
- [ ] Submit multiple events in sequence and verify the chain IDs form a valid hash chain (each event's chain ID includes the previous event's hash)
|
||||
- [ ] Replay the event stream and verify all events are returned in chronological order with correct payloads
|
||||
- [ ] Verify contract tests: submit events with all defined event types from `LedgerEventConstants` and verify each produces a valid response
|
||||
- [ ] Verify the in-memory repository passes the same test suite as the PostgreSQL repository
|
||||
@@ -1,26 +0,0 @@
|
||||
# Ledger Projections
|
||||
|
||||
## Module
|
||||
Findings
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Projection worker that materializes event streams into queryable read models.
|
||||
|
||||
## Implementation Details
|
||||
- **Ledger Projection Worker**: `src/Findings/StellaOps.Findings.Ledger/Infrastructure/Projection/LedgerProjectionWorker.cs` -- background worker that consumes ledger event streams and materializes them into queryable projection read models.
|
||||
- **Ledger Projection Reducer**: `src/Findings/StellaOps.Findings.Ledger/Services/LedgerProjectionReducer.cs` -- reduces event sequences into projection state, applying each event to build the current finding state from its event history.
|
||||
- **Projection Models**: `src/Findings/StellaOps.Findings.Ledger/Domain/ProjectionModels.cs` -- read-side projection models materialized from events (finding state, VEX status, scoring state).
|
||||
- **Projection Hashing**: `src/Findings/StellaOps.Findings.Ledger/Hashing/ProjectionHashing.cs` -- computes deterministic hashes of projection state for consistency verification between replays.
|
||||
- **Finding Projection Repository Interface**: `src/Findings/StellaOps.Findings.Ledger/Infrastructure/IFindingProjectionRepository.cs` -- persistence contract for materialized projections.
|
||||
- **Postgres Finding Projection Repository**: `src/Findings/StellaOps.Findings.Ledger/Infrastructure/Postgres/PostgresFindingProjectionRepository.cs` -- PostgreSQL persistence for projection read models.
|
||||
- **Tests**: `src/Findings/__Tests/StellaOps.Findings.Ledger.Tests/LedgerProjectionReducerTests.cs`, `src/Findings/StellaOps.Findings.Ledger.Tests/ProjectionHashingTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Submit a sequence of finding events (create, update VEX, add attestation) and verify the projection worker materializes the final finding state with correct VEX status and attestation references
|
||||
- [ ] Verify projection consistency: replay the same event sequence twice and confirm the projection hashes match (deterministic projection)
|
||||
- [ ] Verify projection catch-up: stop the projection worker, submit events, restart the worker, and confirm it processes all missed events and reaches the correct state
|
||||
- [ ] Verify the projection reducer correctly handles out-of-order event delivery by ordering events by sequence number before applying
|
||||
- [ ] Query the materialized projection via the finding query endpoints and verify the response matches the expected state from the event history
|
||||
@@ -1,27 +0,0 @@
|
||||
# Ledger Replay Determinism
|
||||
|
||||
## Module
|
||||
Findings
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Replay determinism verification with dedicated tests and a replay harness tool for offline validation.
|
||||
|
||||
## Implementation Details
|
||||
- **Ledger Replay Harness**: `src/Findings/StellaOps.Findings.Ledger/tools/LedgerReplayHarness/` -- offline tool for replaying ledger event sequences and verifying determinism. Key files: `Program.cs` (CLI entry point), `HarnessFixtureReader.cs` (loads event fixtures from files), `HarnessDraftParser.cs` (parses draft event formats), `HarnessMath.cs` (statistical verification of replay results), `HarnessFixtureException.cs` (fixture parsing errors).
|
||||
- **Standalone Replay Harness**: `src/Findings/tools/LedgerReplayHarness/` -- standalone version with additional infrastructure. Key files: `HarnessRunner.cs` (orchestrates replay execution), `HarnessFixtureEntry.cs` (fixture entry model), `HarnessFixtureReader.cs`, `HarnessStats.cs` (statistics), `MerkleCalculator.cs` (verifies Merkle hashes during replay), `TaskThrottler.cs` (controls concurrency), `ILedgerClient.cs` and `InMemoryLedgerClient.cs` (ledger client abstraction for replay).
|
||||
- **Ledger Hashing**: `src/Findings/StellaOps.Findings.Ledger/Hashing/LedgerHashing.cs` -- computes deterministic hashes of ledger events for replay verification.
|
||||
- **Ledger Canonical JSON Serializer**: `src/Findings/StellaOps.Findings.Ledger/Hashing/LedgerCanonicalJsonSerializer.cs` -- canonical JSON serialization ensuring identical byte output regardless of property ordering.
|
||||
- **Hash Utilities**: `src/Findings/StellaOps.Findings.Ledger/Hashing/HashUtilities.cs` -- SHA-256 hashing utilities for deterministic event hashing.
|
||||
- **Projection Hashing**: `src/Findings/StellaOps.Findings.Ledger/Hashing/ProjectionHashing.cs` -- verifies projection state determinism after replay.
|
||||
- **Tests**: `src/Findings/StellaOps.Findings.Ledger.Tests/LedgerReplayDeterminismTests.cs`, `src/Findings/__Tests/StellaOps.Findings.Ledger.Tests/HarnessRunnerTests.cs`, `src/Findings/__Tests/StellaOps.Findings.Ledger.ReplayHarness.Tests/HarnessFixtureReaderTests.cs`, `HarnessMathTests.cs`, `src/Findings/__Tests/StellaOps.Findings.Tools.LedgerReplayHarness.Tests/HarnessFixtureReaderTests.cs`, `HarnessRunnerTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Run the ledger replay harness against a fixture file and verify the replay produces identical ledger hashes to the original execution
|
||||
- [ ] Replay the same event sequence 10 times and verify all runs produce identical projection hashes (statistical determinism)
|
||||
- [ ] Modify a single event payload in a fixture and verify the replay harness detects the hash mismatch and reports it as a determinism violation
|
||||
- [ ] Verify Merkle hash consistency: replay events and confirm `MerkleCalculator` produces the same Merkle root as the original anchoring
|
||||
- [ ] Verify canonical JSON serialization: serialize the same event with different property orderings and confirm `LedgerCanonicalJsonSerializer` produces identical byte output
|
||||
- [ ] Verify the `HarnessFixtureReader` correctly loads fixtures from both draft and final formats
|
||||
@@ -1,29 +0,0 @@
|
||||
# Merkle Anchoring for Audit Integrity
|
||||
|
||||
## Module
|
||||
Findings
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Dedicated Merkle anchor worker that periodically anchors ledger events to Merkle trees for tamper-evident audit integrity.
|
||||
|
||||
## Implementation Details
|
||||
- **Merkle Anchor Worker**: `src/Findings/StellaOps.Findings.Ledger/Infrastructure/Merkle/LedgerMerkleAnchorWorker.cs` -- background worker that periodically collects unanchored ledger events, builds a Merkle tree, and stores the anchor (root hash, tree size, event range).
|
||||
- **Merkle Tree Builder**: `src/Findings/StellaOps.Findings.Ledger/Infrastructure/Merkle/MerkleTreeBuilder.cs` -- builds Merkle trees from ledger event hashes for tamper-evident anchoring.
|
||||
- **Ledger Anchor Queue**: `src/Findings/StellaOps.Findings.Ledger/Infrastructure/Merkle/LedgerAnchorQueue.cs` -- queues events for periodic Merkle anchoring.
|
||||
- **Merkle Anchor Repository Interface**: `src/Findings/StellaOps.Findings.Ledger/Infrastructure/Merkle/IMerkleAnchorRepository.cs` -- persistence contract for Merkle anchor records.
|
||||
- **Postgres Merkle Anchor Repository**: `src/Findings/StellaOps.Findings.Ledger/Infrastructure/Postgres/PostgresMerkleAnchorRepository.cs` -- PostgreSQL persistence for Merkle anchor data.
|
||||
- **Merkle Anchor Scheduler Interface**: `src/Findings/StellaOps.Findings.Ledger/Infrastructure/IMerkleAnchorScheduler.cs` -- scheduling contract for anchor operations.
|
||||
- **Postgres Merkle Anchor Scheduler**: `src/Findings/StellaOps.Findings.Ledger/Infrastructure/Merkle/PostgresMerkleAnchorScheduler.cs` -- PostgreSQL-backed anchor scheduling.
|
||||
- **Null Merkle Anchor Scheduler**: `src/Findings/StellaOps.Findings.Ledger/Infrastructure/Merkle/NullMerkleAnchorScheduler.cs` -- no-op scheduler for environments where Merkle anchoring is disabled.
|
||||
- **Ledger Hashing**: `src/Findings/StellaOps.Findings.Ledger/Hashing/LedgerHashing.cs` -- computes deterministic hashes of ledger events that become Merkle tree leaves.
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Submit a batch of ledger events, trigger the Merkle anchor worker, and verify a Merkle anchor record is created with the correct root hash and event range
|
||||
- [ ] Verify tamper detection: retrieve an anchored event, modify its payload, recompute the Merkle proof, and confirm the proof fails validation against the stored root hash
|
||||
- [ ] Verify the Merkle tree builder produces the same root hash when given the same event hashes in the same order
|
||||
- [ ] Verify anchor scheduling: configure a 10-second anchor interval and submit events over 30 seconds; confirm at least 3 anchor records are created
|
||||
- [ ] Verify the null scheduler correctly disables anchoring without errors when configured
|
||||
- [ ] Verify anchor persistence: create anchors, restart the service, and confirm previously stored anchors are retrievable from PostgreSQL
|
||||
@@ -1,32 +0,0 @@
|
||||
# Mirror Creator
|
||||
|
||||
## Module
|
||||
Mirror
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Mirror creator module exists as a separate directory but appears to have limited implementation compared to the comprehensive AirGap module.
|
||||
|
||||
## What's Implemented
|
||||
- **Module Directory**: `src/Mirror/` -- directory exists in the source tree, indicating the module was planned and scaffolded.
|
||||
- **Related AirGap Functionality**: The `src/AirGap/` module provides comprehensive offline/air-gap mirroring capabilities including feed mirroring, registry mirroring, and offline bundle creation that may overlap with the intended Mirror module scope.
|
||||
- **Golden Pairs Mirror Service**: `src/Tools/GoldenPairs/StellaOps.Tools.GoldenPairs/Services/PackageMirrorService.cs` -- provides package mirroring for golden pair validation, which demonstrates the mirroring pattern but is scoped to the testing toolchain.
|
||||
|
||||
## What's Missing
|
||||
- **Mirror Creator Service**: No core service implementation exists in `src/Mirror/` -- the directory is empty with no C# source files, project files, or service definitions.
|
||||
- **Mirror Configuration**: No configuration models or API endpoints for defining mirror sources, schedules, or target registries.
|
||||
- **Mirror Sync Engine**: No synchronization engine for incrementally mirroring container images, SBOMs, VEX documents, or advisory feeds from upstream sources to local storage.
|
||||
- **Mirror Status Tracking**: No status tracking or progress reporting for active mirror operations.
|
||||
- **Mirror Attestation**: No attestation generation for mirrored content to verify integrity after transfer.
|
||||
|
||||
## Implementation Plan
|
||||
- Determine whether the Mirror module should be a standalone service or merged into the existing AirGap module (which already provides substantial mirroring capabilities)
|
||||
- If standalone: implement core mirror service with source configuration, sync engine, progress tracking, and attestation
|
||||
- If merged: archive the `src/Mirror/` directory and update documentation to point to `src/AirGap/` for all mirroring functionality
|
||||
- Add integration tests with Testcontainers OCI registry for mirror sync verification
|
||||
|
||||
## Related Documentation
|
||||
- AirGap module (existing mirror capabilities): `src/AirGap/`
|
||||
- Golden Pairs mirror pattern: `src/Tools/GoldenPairs/StellaOps.Tools.GoldenPairs/Services/PackageMirrorService.cs`
|
||||
@@ -1,31 +0,0 @@
|
||||
# Ack Tokens for Approval Workflows
|
||||
|
||||
## Module
|
||||
Notifier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
HMAC-based ack token service with bridge integration for acknowledgement workflows. Note: uses HMAC rather than DSSE-signed tokens as described in the advisory.
|
||||
|
||||
## Implementation Details
|
||||
- **IAckTokenService interface**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Security/IAckTokenService.cs` -- `CreateToken`, `VerifyToken`, `CreateAckUrl` for signed acknowledgement tokens with configurable expiration and metadata
|
||||
- **HmacAckTokenService**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Security/HmacAckTokenService.cs` -- HMAC-SHA256 implementation with HKDF key derivation, `soa1` token prefix, versioned token format, configurable signing key
|
||||
- **IAckBridge interface**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Escalation/IAckBridge.cs` -- bridge between ack tokens and escalation engine
|
||||
- **AckBridge**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Escalation/AckBridge.cs` -- processes ack requests, maps external IDs to internal incident IDs, integrates with `IEscalationEngine` and `IIncidentManager`, supports audit logging
|
||||
- **SecurityContracts**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.WebService/Contracts/SecurityContracts.cs` -- ack token request/response DTOs
|
||||
- **PackApprovalAckRequest**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.WebService/Contracts/PackApprovalAckRequest.cs` -- pack approval ack request model
|
||||
- **EscalationEndpoints**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.WebService/Endpoints/EscalationEndpoints.cs` -- REST endpoints for ack token processing
|
||||
- **SecurityEndpoints**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.WebService/Endpoints/SecurityEndpoints.cs` -- security-related endpoints
|
||||
- **Tests**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.WebService.Tests/Escalation/AckBridgeTests.cs`
|
||||
- **OpenAPI**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.WebService/openapi/pack-approvals.yaml`
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify HMAC ack token creation with configurable expiration (default 7 days)
|
||||
- [ ] Test token verification rejects expired, tampered, or malformed tokens
|
||||
- [ ] Verify AckBridge routes ack actions (ack, resolve, escalate) to escalation engine
|
||||
- [ ] Test ack URL generation and round-trip verification
|
||||
- [ ] Verify pack approval ack workflow through EscalationEndpoints
|
||||
- [ ] Test audit logging of ack processing events
|
||||
@@ -1,33 +0,0 @@
|
||||
# Digest Windows and Throttling
|
||||
|
||||
## Module
|
||||
Notifier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Digest generation for coalescing notifications within configurable time windows.
|
||||
|
||||
## Implementation Details
|
||||
- **INotifyThrottler interface**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Correlation/NotifyThrottler.cs` -- `RecordEventAsync`, `CheckAsync` (with configurable window/maxEvents), `ClearAsync` for per-key throttle management
|
||||
- **InMemoryNotifyThrottler**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Correlation/NotifyThrottler.cs` -- in-memory sliding window throttler with `ConcurrentDictionary<string, ThrottleState>`, `ThrottlerOptions` for default window/max
|
||||
- **IThrottleConfigService**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Correlation/IThrottleConfigService.cs` -- per-tenant throttle configuration
|
||||
- **ThrottleConfigService**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Correlation/ThrottleConfigService.cs` -- resolves throttle windows per event kind
|
||||
- **ThrottleConfigurationService**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Correlation/ThrottleConfigurationService.cs` -- advanced throttle configuration management
|
||||
- **QuietHoursServiceExtensions**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Correlation/QuietHoursServiceExtensions.cs` -- quiet hours integration with throttling
|
||||
- **ThrottleEndpoints**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.WebService/Endpoints/ThrottleEndpoints.cs` -- REST API for throttle configuration
|
||||
- **QuietHoursContracts**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.WebService/Contracts/QuietHoursContracts.cs` -- quiet hours request/response models
|
||||
- **IOperatorOverrideService**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Correlation/IOperatorOverrideService.cs` -- operator override for throttle bypass
|
||||
- **OperatorOverrideService**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Correlation/OperatorOverrideService.cs` -- operator override implementation
|
||||
- **OperatorOverrideEndpoints**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.WebService/Endpoints/OperatorOverrideEndpoints.cs` -- REST API for operator overrides
|
||||
- **Tests**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Tests/Correlation/NotifyThrottlerTests.cs`, `ThrottleConfigServiceTests.cs`, `ThrottleConfigurationServiceTests.cs`
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify sliding window throttling suppresses notifications exceeding maxEvents within window
|
||||
- [ ] Test per-tenant throttle configuration via ThrottleEndpoints API
|
||||
- [ ] Verify quiet hours suppress notifications during configured periods
|
||||
- [ ] Test operator override allows bypassing throttle for specific keys
|
||||
- [ ] Verify throttle state clears after incident resolution
|
||||
- [ ] Test throttle configuration persists across service restarts
|
||||
@@ -1,39 +0,0 @@
|
||||
# Multi-Channel Delivery (Slack, Teams, Email, Webhooks)
|
||||
|
||||
## Module
|
||||
Notifier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Multi-channel notification delivery with Slack, Webhook connectors (and PagerDuty in Notifier), with snapshot testing and error handling.
|
||||
|
||||
## Implementation Details
|
||||
- **IChannelAdapter interface**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Channels/IChannelAdapter.cs` -- `DispatchAsync` (sends notification via channel), `CheckHealthAsync` (verifies channel connectivity), typed by `NotifyChannelType`
|
||||
- **ChannelAdapterFactory**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Channels/ChannelAdapterFactory.cs` -- resolves channel adapters by type, `GetAdapter`/`GetAllAdapters` for DI-based adapter registry
|
||||
- **SlackChannelAdapter**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Channels/SlackChannelAdapter.cs` -- Slack delivery adapter
|
||||
- **WebhookChannelAdapter**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Channels/WebhookChannelAdapter.cs` -- generic webhook delivery adapter
|
||||
- **ChatWebhookChannelAdapter**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Channels/ChatWebhookChannelAdapter.cs` -- chat-specific webhook adapter (Teams, Discord, etc.)
|
||||
- **PagerDutyChannelAdapter**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Channels/PagerDutyChannelAdapter.cs` -- PagerDuty incident creation adapter
|
||||
- **OpsGenieChannelAdapter**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Channels/OpsGenieChannelAdapter.cs` -- OpsGenie alert adapter
|
||||
- **EmailChannelAdapter**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Channels/EmailChannelAdapter.cs` -- email delivery adapter
|
||||
- **InAppChannelAdapter**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Channels/InAppChannelAdapter.cs` -- in-app notification adapter
|
||||
- **WebhookChannelDispatcher**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Dispatch/WebhookChannelDispatcher.cs` -- dispatches to webhook-based channels
|
||||
- **IWebhookSecurityService**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Security/IWebhookSecurityService.cs` -- webhook signature verification
|
||||
- **IFallbackHandler**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Fallback/IFallbackHandler.cs` -- fallback when primary channel fails
|
||||
- **HttpEgressSloSink**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Processing/HttpEgressSloSink.cs` -- SLO tracking for HTTP egress
|
||||
- **Templates**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.WebService/offline/notifier/templates/` -- Slack and webhook templates for risk, attestation, deprecation events
|
||||
- **Tests**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Tests/Channels/WebhookChannelAdapterTests.cs`, `Dispatch/WebhookChannelDispatcherTests.cs`, `Dispatch/SimpleTemplateRendererTests.cs`, `Security/WebhookSecurityServiceTests.cs`, `Fallback/FallbackHandlerTests.cs`, `HttpEgressSloSinkTests.cs`
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify Slack channel adapter delivers notifications with Block Kit formatting
|
||||
- [ ] Test webhook channel adapter posts to configured URLs with HMAC signature
|
||||
- [ ] Verify PagerDuty adapter creates incidents with correct severity mapping
|
||||
- [ ] Test OpsGenie adapter creates alerts with priority
|
||||
- [ ] Verify email adapter sends with subject and rendered body
|
||||
- [ ] Test in-app notification adapter records notifications for UI retrieval
|
||||
- [ ] Verify channel health checks detect unreachable endpoints
|
||||
- [ ] Test fallback handler routes to secondary channel on primary failure
|
||||
- [ ] Verify egress SLO tracking records delivery latency
|
||||
@@ -1,31 +0,0 @@
|
||||
# Notification Correlation Engine
|
||||
|
||||
## Module
|
||||
Notifier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Correlates related notification events across time windows to reduce noise and group related alerts, preventing notification storms during large-scale vulnerability disclosures or policy changes.
|
||||
|
||||
## Implementation Details
|
||||
- **ICorrelationEngine interface**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Correlation/ICorrelationEngine.cs` -- `CorrelateAsync` for event correlation
|
||||
- **CorrelationEngine**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Correlation/CorrelationEngine.cs` -- orchestrates correlation key building, incident management, throttling, and quiet hours evaluation; multi-step pipeline: (1) build correlation key, (2) get/create incident, (3) check throttle, (4) evaluate quiet hours
|
||||
- **ICorrelationKeyBuilder**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Correlation/ICorrelationKeyBuilder.cs` -- builds correlation keys from events
|
||||
- **ICorrelationKeyEvaluator**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Correlation/ICorrelationKeyEvaluator.cs` -- evaluates correlation key expressions
|
||||
- **DefaultCorrelationKeyEvaluator**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Correlation/DefaultCorrelationKeyEvaluator.cs` -- default key evaluator implementation
|
||||
- **IncidentManager**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Correlation/IncidentManager.cs` -- creates/manages incidents from correlated events
|
||||
- **NotifyIncident**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Correlation/NotifyIncident.cs` -- incident model
|
||||
- **CorrelationServiceExtensions**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Correlation/CorrelationServiceExtensions.cs` -- DI registration for correlation services
|
||||
- **NotifierEventProcessor**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Processing/NotifierEventProcessor.cs` -- integrates correlation engine into event processing pipeline
|
||||
- **Tests**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Tests/Correlation/CorrelationEngineTests.cs`, `IncidentManagerTests.cs`
|
||||
- **Source**: SPRINT_0172_0001_0002_notifier_ii.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify events with same correlation key are grouped into a single incident
|
||||
- [ ] Test time-window-based correlation correctly groups events within window
|
||||
- [ ] Verify throttling suppresses repeat notifications for same incident
|
||||
- [ ] Test quiet hours evaluation defers notifications during configured periods
|
||||
- [ ] Verify new incidents are created when correlation window expires
|
||||
- [ ] Test correlation key building for different event kinds (CVE, policy, attestation)
|
||||
@@ -1,27 +0,0 @@
|
||||
# Notification Digest Generator
|
||||
|
||||
## Module
|
||||
Notifier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Configurable digest aggregation that batches notifications into scheduled summary digests (hourly/daily/weekly) with customizable grouping and priority thresholds.
|
||||
|
||||
## Implementation Details
|
||||
- **IDigestGenerator interface**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Digest/IDigestGenerator.cs` -- `GenerateAsync` and `PreviewAsync` for producing digest reports
|
||||
- **DigestGenerator**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Digest/DigestGenerator.cs` -- default implementation; queries IncidentManager for events in time range, produces `DigestResult` with `DigestId`, `TotalIncidentCount`, and `Summary.TotalEvents`; supports preview mode
|
||||
- **DigestScheduleRunner**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Digest/DigestScheduleRunner.cs` -- `BackgroundService` that runs digest generation on configured schedules; uses `IDigestDistributor` to deliver digests, `IDigestTenantProvider` for multi-tenant support; configurable via `DigestScheduleOptions.Enabled` and `Schedules`
|
||||
- **DigestTypes**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Digest/DigestTypes.cs` -- digest models (`DigestResult`, `DigestQuery`, `DigestSummary`)
|
||||
- **DigestServiceExtensions**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Digest/DigestServiceExtensions.cs` -- DI registration for digest services
|
||||
- **Tests**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Tests/Digest/DigestGeneratorTests.cs`
|
||||
- **Source**: SPRINT_0172_0001_0002_notifier_ii.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify scheduled digest generation runs at configured intervals (hourly/daily/weekly)
|
||||
- [ ] Test digest aggregates incidents within the configured time window
|
||||
- [ ] Verify preview mode returns digest without side effects
|
||||
- [ ] Test multi-tenant digest generation processes each tenant independently
|
||||
- [ ] Verify digest distribution delivers summary to configured channels
|
||||
- [ ] Test DigestScheduleRunner respects Enabled=false configuration
|
||||
@@ -1,33 +0,0 @@
|
||||
# Notification Rules Engine
|
||||
|
||||
## Module
|
||||
Notifier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Rules engine with NotifyRule model, rule evaluator interface, evaluation outcomes, and schema migration support.
|
||||
|
||||
## Implementation Details
|
||||
- **DefaultNotifyRuleEvaluator**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Processing/DefaultNotifyRuleEvaluator.cs` -- evaluates `NotifyRule` against `NotifyEvent`; matches on event kind, namespace, repository, digest, severity (ranked none=0 through blocker=6); returns `NotifyRuleEvaluationOutcome` with match/not-matched reason
|
||||
- **NotifierEventProcessor**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Processing/NotifierEventProcessor.cs` -- integrates rule evaluation into the event processing pipeline
|
||||
- **SimulationEngine**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Simulation/SimulationEngine.cs` -- dry-run simulation of rule evaluation
|
||||
- **DefaultNotifySimulationEngine**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Simulation/DefaultNotifySimulationEngine.cs` -- default simulation engine implementation
|
||||
- **ISimulationEngine**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Simulation/ISimulationEngine.cs` -- simulation interface
|
||||
- **RuleEndpoints**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.WebService/Endpoints/RuleEndpoints.cs` -- REST API for rule CRUD and testing
|
||||
- **SimulationEndpoints**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.WebService/Endpoints/SimulationEndpoints.cs` -- REST API for rule simulation
|
||||
- **RiskTemplateSeeder**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.WebService/Setup/RiskTemplateSeeder.cs` -- seeds default risk notification rules
|
||||
- **AttestationTemplateSeeder**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.WebService/Setup/AttestationTemplateSeeder.cs` -- seeds attestation notification rules
|
||||
- **InMemoryNotifyRepositories**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Storage/InMemoryNotifyRepositories.cs` -- in-memory rule storage
|
||||
- **Sample rules**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.docs/risk-rules.sample.json`
|
||||
- **Tests**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Tests/RuleEvaluatorTests.cs`, `Simulation/SimulationEngineTests.cs`, `EventProcessorTests.cs`, `Endpoints/NotifyApiEndpointsTests.cs`
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify rule evaluator matches events by kind, namespace, repository, and severity
|
||||
- [ ] Test disabled rules are skipped with "rule_disabled" reason
|
||||
- [ ] Verify severity-based filtering (e.g., minimum severity threshold)
|
||||
- [ ] Test rule CRUD through RuleEndpoints API
|
||||
- [ ] Verify simulation endpoints allow dry-run rule testing without side effects
|
||||
- [ ] Test seeded default rules for risk and attestation scenarios
|
||||
@@ -1,27 +0,0 @@
|
||||
# Notification Storm Breaker
|
||||
|
||||
## Module
|
||||
Notifier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Circuit breaker mechanism that detects notification storms and applies adaptive throttling to prevent overwhelming downstream channels during mass event cascades.
|
||||
|
||||
## Implementation Details
|
||||
- **IStormBreaker interface**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/StormBreaker/IStormBreaker.cs` -- `EvaluateAsync` (records event and checks storm condition), `GetStateAsync` (gets current storm state for a key), `GetActiveStormsAsync` (lists all active storms for a tenant)
|
||||
- **StormBreakerServiceExtensions**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/StormBreaker/StormBreakerServiceExtensions.cs` -- DI registration for storm breaker services
|
||||
- **ChannelAdapterOptions**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Channels/ChannelAdapterOptions.cs` -- circuit breaker configuration for channel adapters
|
||||
- **StormBreakerEndpoints**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.WebService/Endpoints/StormBreakerEndpoints.cs` -- REST API for viewing and managing active storms
|
||||
- **INotifierMetrics**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Worker/Observability/INotifierMetrics.cs` -- metrics counters for storm detection events
|
||||
- **Tests**: `src/Notifier/StellaOps.Notifier/StellaOps.Notifier.Tests/StormBreaker/StormBreakerTests.cs`
|
||||
- **Source**: SPRINT_0172_0001_0002_notifier_ii.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify storm detection triggers when event rate exceeds configured threshold
|
||||
- [ ] Test storm consolidation batches events into summary notifications
|
||||
- [ ] Verify active storm state is queryable via StormBreakerEndpoints API
|
||||
- [ ] Test storm resolution when event rate drops below threshold
|
||||
- [ ] Verify per-tenant storm isolation (storms in one tenant do not affect others)
|
||||
- [ ] Test metrics emission for storm detection and resolution events
|
||||
@@ -1,38 +0,0 @@
|
||||
# Packs Registry Service with Mirroring and Compliance Dashboards
|
||||
|
||||
## Module
|
||||
PacksRegistry
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Registry service for managing pack lifecycle (publish, version, deprecate) with mirroring support for air-gapped environments, attestation integration, and compliance dashboard APIs.
|
||||
|
||||
## Implementation Details
|
||||
- **Pack Service**: `src/PacksRegistry/StellaOps.PacksRegistry/StellaOps.PacksRegistry.Core/Services/PackService.cs` -- core pack lifecycle operations: publish, query, version, and deprecate packs.
|
||||
- **Mirror Service**: `src/PacksRegistry/StellaOps.PacksRegistry/StellaOps.PacksRegistry.Core/Services/MirrorService.cs` -- manages mirror sources for air-gapped pack distribution.
|
||||
- **Attestation Service**: `src/PacksRegistry/StellaOps.PacksRegistry/StellaOps.PacksRegistry.Core/Services/AttestationService.cs` -- manages attestation records for packs, verifying pack provenance and signatures.
|
||||
- **Compliance Service**: `src/PacksRegistry/StellaOps.PacksRegistry/StellaOps.PacksRegistry.Core/Services/ComplianceService.cs` -- computes compliance summaries for pack registries (attestation coverage, signature verification status).
|
||||
- **Lifecycle Service**: `src/PacksRegistry/StellaOps.PacksRegistry/StellaOps.PacksRegistry.Core/Services/LifecycleService.cs` -- manages pack lifecycle transitions (active, deprecated, archived).
|
||||
- **Parity Service**: `src/PacksRegistry/StellaOps.PacksRegistry/StellaOps.PacksRegistry.Core/Services/ParityService.cs` -- tracks parity between primary and mirror registries.
|
||||
- **Export Service**: `src/PacksRegistry/StellaOps.PacksRegistry/StellaOps.PacksRegistry.Core/Services/ExportService.cs` -- exports pack data for offline/air-gap seeding.
|
||||
- **Core Contracts**: `src/PacksRegistry/StellaOps.PacksRegistry/StellaOps.PacksRegistry.Core/Contracts/` -- interfaces: `IPackRepository.cs`, `IMirrorRepository.cs`, `IAttestationRepository.cs`, `IAuditRepository.cs`, `ILifecycleRepository.cs`, `IParityRepository.cs`, `IPackSignatureVerifier.cs`.
|
||||
- **Core Models**: `src/PacksRegistry/StellaOps.PacksRegistry/StellaOps.PacksRegistry.Core/Models/` -- `PackRecord.cs`, `MirrorSourceRecord.cs`, `AttestationRecord.cs`, `AuditRecord.cs`, `LifecycleRecord.cs`, `ParityRecord.cs`, `PackPolicyOptions.cs`.
|
||||
- **Web API Contracts**: `src/PacksRegistry/StellaOps.PacksRegistry/StellaOps.PacksRegistry.WebService/Contracts/` -- DTOs: `PackUploadRequest.cs`, `PackResponse.cs`, `PackManifestResponse.cs`, `MirrorRequest.cs`, `MirrorResponse.cs`, `MirrorSyncRequest.cs`, `AttestationUploadRequest.cs`, `AttestationResponse.cs`, `ComplianceSummaryResponse.cs`, `LifecycleRequest.cs`, `LifecycleResponse.cs`, `ParityRequest.cs`, `ParityResponse.cs`, `OfflineSeedRequest.cs`, `RotateSignatureRequest.cs`.
|
||||
- **Infrastructure (File System)**: `src/PacksRegistry/StellaOps.PacksRegistry/StellaOps.PacksRegistry.Infrastructure/FileSystem/` -- file-based repository implementations: `FilePackRepository.cs`, `FileMirrorRepository.cs`, `FileAttestationRepository.cs`, `FileAuditRepository.cs`, `FileLifecycleRepository.cs`, `FileParityRepository.cs`.
|
||||
- **Infrastructure (InMemory)**: `src/PacksRegistry/StellaOps.PacksRegistry/StellaOps.PacksRegistry.Infrastructure/InMemory/` -- in-memory repository implementations for testing.
|
||||
- **Signature Verification**: `src/PacksRegistry/StellaOps.PacksRegistry/StellaOps.PacksRegistry.Infrastructure/Verification/RsaSignatureVerifier.cs`, `SimpleSignatureVerifier.cs` -- RSA and simple signature verification for pack integrity.
|
||||
- **Postgres Persistence**: `src/PacksRegistry/__Libraries/StellaOps.PacksRegistry.Persistence/Postgres/Repositories/` -- `PostgresPackRepository.cs`, `PostgresMirrorRepository.cs`, `PostgresAttestationRepository.cs`, `PostgresAuditRepository.cs`, `PostgresLifecycleRepository.cs`, `PostgresParityRepository.cs`.
|
||||
- **EF Core Context**: `src/PacksRegistry/__Libraries/StellaOps.PacksRegistry.Persistence/EfCore/Context/PacksRegistryDbContext.cs` -- Entity Framework Core context.
|
||||
- **Worker**: `src/PacksRegistry/StellaOps.PacksRegistry/StellaOps.PacksRegistry.Worker/Worker.cs` -- background worker for mirror sync and parity checks.
|
||||
- **Tests**: `src/PacksRegistry/StellaOps.PacksRegistry/StellaOps.PacksRegistry.Tests/PackServiceTests.cs`, `PacksApiTests.cs`, `FilePackRepositoryTests.cs`, `ExportServiceTests.cs`, `RsaSignatureVerifierTests.cs`; `src/PacksRegistry/__Tests/StellaOps.PacksRegistry.Persistence.Tests/PostgresPackRepositoryTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Publish a pack via the REST API and verify it is stored in the registry with correct metadata (name, version, digest)
|
||||
- [ ] Configure a mirror source and trigger a sync; verify the pack is replicated to the mirror with matching digest
|
||||
- [ ] Upload an attestation for a published pack and verify the compliance dashboard endpoint reports the pack as attested
|
||||
- [ ] Deprecate a pack via lifecycle API and verify it is no longer returned in active pack queries but remains queryable with a deprecated filter
|
||||
- [ ] Verify parity check: publish a pack, sync to mirror, then update the primary; run parity check and confirm the mirror is reported as out-of-sync
|
||||
- [ ] Export packs for offline seeding and verify the exported bundle contains all pack data and attestations needed for air-gap import
|
||||
- [ ] Verify RSA signature verification: publish a signed pack and verify `RsaSignatureVerifier` validates the signature on retrieval
|
||||
@@ -1,23 +0,0 @@
|
||||
# Advisory Locks / LISTEN-NOTIFY
|
||||
|
||||
## Module
|
||||
Platform
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Advisory lock patterns are used in classification history for safe concurrent updates; LISTEN/NOTIFY patterns support real-time event propagation.
|
||||
|
||||
## Implementation Details
|
||||
- **PlatformAnalyticsMaintenanceService**: `src/Platform/StellaOps.Platform.WebService/Services/PlatformAnalyticsMaintenanceService.cs` -- BackgroundService using PeriodicTimer to run analytics maintenance; calls `REFRESH MATERIALIZED VIEW CONCURRENTLY` for `analytics.mv_supplier_concentration`, `analytics.mv_license_distribution`, `analytics.mv_vuln_exposure`, `analytics.mv_attestation_coverage`; uses `SELECT analytics.compute_daily_rollups(@date)` for daily rollup computation
|
||||
- **AnalyticsIngestionDataSource**: `src/Platform/StellaOps.Platform.Analytics/Services/AnalyticsIngestionDataSource.cs` -- PostgreSQL data source for analytics with connection management
|
||||
- **VulnerabilityCorrelationService**: `src/Platform/StellaOps.Platform.Analytics/Services/VulnerabilityCorrelationService.cs` -- correlates vulnerabilities with SBOM components using PURL matching
|
||||
- **ScannerOrchestratorEvents**: `src/Platform/StellaOps.Platform.Analytics/Models/ScannerOrchestratorEvents.cs` -- event models for scanner report ready / scan completed events via event streams
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify advisory locks prevent concurrent classification history updates
|
||||
- [ ] Test LISTEN/NOTIFY propagates real-time events to subscribers
|
||||
- [ ] Verify materialized view concurrent refresh completes without locking reads
|
||||
- [ ] Test daily rollup computation produces correct aggregates for a given date
|
||||
@@ -1,24 +0,0 @@
|
||||
# Materialized Views for Analytics
|
||||
|
||||
## Module
|
||||
Platform
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Materialized views with indexes, VEX validity filters, and deterministic arrays are used for analytics with a dedicated maintenance service for refresh.
|
||||
|
||||
## Implementation Details
|
||||
- **PlatformAnalyticsMaintenanceService**: `src/Platform/StellaOps.Platform.WebService/Services/PlatformAnalyticsMaintenanceService.cs` -- BackgroundService that periodically refreshes 4 materialized views (`mv_supplier_concentration`, `mv_license_distribution`, `mv_vuln_exposure`, `mv_attestation_coverage`) using `REFRESH MATERIALIZED VIEW CONCURRENTLY`; supports daily rollup backfill, configurable interval, and run-on-startup mode via `PlatformAnalyticsMaintenanceOptions`
|
||||
- **PlatformAnalyticsQueryExecutor**: `src/Platform/StellaOps.Platform.WebService/Services/PlatformAnalyticsQueryExecutor.cs` -- executes analytical queries against materialized views
|
||||
- **PlatformAnalyticsService**: `src/Platform/StellaOps.Platform.WebService/Services/PlatformAnalyticsService.cs` -- service layer for analytics queries (suppliers, licenses, vulnerabilities, backlog, attestation coverage, vulnerability/component trends)
|
||||
- **AnalyticsEndpoints**: `src/Platform/StellaOps.Platform.WebService/Endpoints/AnalyticsEndpoints.cs` -- REST API at `/api/analytics` with 7 endpoints: suppliers, licenses, vulnerabilities, backlog, attestation-coverage, trends/vulnerabilities, trends/components; all require `AnalyticsRead` authorization
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify materialized views refresh concurrently without blocking reads
|
||||
- [ ] Test daily rollup backfill covers configured BackfillDays range
|
||||
- [ ] Verify analytics endpoints return correct data from materialized views
|
||||
- [ ] Test analytics service returns 503 when analytics storage is not configured
|
||||
- [ ] Verify trend endpoints return daily data points for specified time windows
|
||||
@@ -1,28 +0,0 @@
|
||||
# Platform Service Aggregation Layer
|
||||
|
||||
## Module
|
||||
Platform
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Backend Platform Service acting as aggregation layer for health status, quotas, onboarding progress, user preferences, and global search across all modules.
|
||||
|
||||
## Implementation Details
|
||||
- **PlatformEndpoints**: `src/Platform/StellaOps.Platform.WebService/Endpoints/PlatformEndpoints.cs` -- REST API at `/api/v1/platform` with 6 endpoint groups: health (summary/dependencies/incidents/metrics), quotas (summary/tenants/alerts), onboarding (status/complete/skip), preferences (dashboard/profiles), search, metadata; all with tenant-scoped authorization policies
|
||||
- **PlatformHealthService**: `src/Platform/StellaOps.Platform.WebService/Services/PlatformHealthService.cs` -- aggregates health status from all platform services
|
||||
- **PlatformQuotaService**: service for quota tracking with alert management (create alert thresholds per tenant)
|
||||
- **PlatformOnboardingService**: `src/Platform/StellaOps.Platform.WebService/Services/PlatformOnboardingService.cs` -- tracks onboarding progress with step completion and skip support
|
||||
- **PlatformPreferencesService**: `src/Platform/StellaOps.Platform.WebService/Services/PlatformPreferencesService.cs` -- user dashboard preferences with profile management (CRUD)
|
||||
- **PlatformSearchService**: global search across all modules with source filtering, pagination
|
||||
- **PlatformMetadataService**: `src/Platform/StellaOps.Platform.WebService/Services/PlatformMetadataService.cs` -- platform metadata retrieval
|
||||
- **PlatformCache**: `src/Platform/StellaOps.Platform.WebService/Services/PlatformCache.cs` -- caching layer with TTL and data-as-of timestamps
|
||||
- **Source**: SPRINT_20251229_043_PLATFORM_platform_service_foundation
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify health summary endpoint aggregates all service statuses
|
||||
- [ ] Test quota alerts are created and returned with proper authorization
|
||||
- [ ] Verify onboarding step completion transitions correctly
|
||||
- [ ] Test global search returns results from multiple sources with pagination
|
||||
- [ ] Verify dashboard preferences persist and load per tenant/user
|
||||
@@ -1,26 +0,0 @@
|
||||
# Platform Setup Wizard Backend API
|
||||
|
||||
## Module
|
||||
Platform
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Real /api/v1/setup/* endpoints replacing UI mocks with deterministic session state (create, resume, execute, skip, finalize), tenant scoping, and offline-first "data as of" metadata.
|
||||
|
||||
## Implementation Details
|
||||
- **SetupEndpoints**: `src/Platform/StellaOps.Platform.WebService/Endpoints/SetupEndpoints.cs` -- REST API at `/api/v1/setup` with 3 endpoint groups: sessions (GET current, POST create, POST resume, POST finalize), steps (POST execute, POST skip), definitions (GET step definitions); AllowAnonymous during initial setup, requires auth after completion
|
||||
- **SetupStateDetector**: detects setup completion state from storage/DB settings; routes between bootstrap context and authenticated context
|
||||
- **PlatformSetupService**: service layer for setup wizard operations (CreateSessionAsync, ResumeOrCreateSessionAsync, ExecuteStepAsync, SkipStepAsync, FinalizeSessionAsync, GetStepDefinitionsAsync)
|
||||
- **SetupWizardModels**: `src/Platform/StellaOps.Platform.WebService/Contracts/SetupWizardModels.cs` -- request/response models (CreateSetupSessionRequest, SetupSessionResponse, ExecuteSetupStepRequest, SkipSetupStepRequest, FinalizeSetupSessionRequest, FinalizeSetupSessionResponse, SetupStepDefinitionsResponse)
|
||||
- **Problem+JSON errors**: all endpoints return RFC 7807 ProblemDetails on errors
|
||||
- **Source**: SPRINT_20260112_004_PLATFORM_setup_wizard_backend.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify setup session creates with bootstrap context when auth is unavailable
|
||||
- [ ] Test session resume returns existing session or creates new one
|
||||
- [ ] Verify step execution updates session state correctly
|
||||
- [ ] Test step skip marks step as skipped and advances session
|
||||
- [ ] Verify finalize completes setup and subsequent requests require authentication
|
||||
- [ ] Test step definitions endpoint returns all available setup steps
|
||||
@@ -1,27 +0,0 @@
|
||||
# SBOM Analytics Lake (Star-Schema PostgreSQL)
|
||||
|
||||
## Module
|
||||
Platform
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Star-schema PostgreSQL analytics layer for SBOM data with component registry, vulnerability correlation tables, attestation tracking, materialized views for trend analysis, and stored procedures for analytics queries. While "Materialized Views for Analytics" is in the known list, this is a much broader star-schema analytics subsystem with dedicated migration, ingestion services, and multi-table analytics design.
|
||||
|
||||
## Implementation Details
|
||||
- **AnalyticsIngestionService**: `src/Platform/StellaOps.Platform.Analytics/Services/AnalyticsIngestionService.cs` -- BackgroundService subscribing to `scanner.report.ready` events via IEventStream; parses SBOM (CycloneDX/SPDX), resolves artifact digests, upserts into star-schema tables (`analytics.artifacts`, `analytics.raw_sboms`, `analytics.components`, `analytics.artifact_components`); uses stored procedures (`analytics.compute_daily_rollups`, `analytics.parse_purl`, `analytics.normalize_supplier`, `analytics.categorize_license`); builds dependency paths via BFS from root component
|
||||
- **VulnerabilityCorrelationService**: `src/Platform/StellaOps.Platform.Analytics/Services/VulnerabilityCorrelationService.cs` -- correlates PURL-based components with known vulnerabilities; updates artifact vulnerability counts
|
||||
- **AttestationIngestionService**: `src/Platform/StellaOps.Platform.Analytics/Services/AttestationIngestionService.cs` -- ingests attestation events into analytics
|
||||
- **Utilities**: PurlParser (PURL normalization), LicenseExpressionRenderer (license aggregation), Sha256Hasher (digest computation), TenantNormalizer (tenant filtering), VersionRuleEvaluator, VulnerabilityCorrelationRules
|
||||
- **AnalyticsIngestionOptions**: `src/Platform/StellaOps.Platform.Analytics/Options/AnalyticsIngestionOptions.cs` -- configurable stream names, tenant allowlists, ingest/schema versions
|
||||
- **Tests**: `src/Platform/__Tests/StellaOps.Platform.Analytics.Tests/`
|
||||
- **Source**: SPRINT_20260120_030_Platform_sbom_analytics_lake.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify SBOM ingestion from scanner.report.ready events populates all star-schema tables
|
||||
- [ ] Test component deduplication via (purl, hash_sha256) conflict resolution
|
||||
- [ ] Verify dependency path BFS builds correct depth and introduced_via values
|
||||
- [ ] Test vulnerability correlation updates component and artifact vulnerability counts
|
||||
- [ ] Verify daily rollup stored procedure computes correct aggregates
|
||||
- [ ] Test tenant filtering respects AllowedTenants configuration
|
||||
@@ -1,25 +0,0 @@
|
||||
# Scanner Platform Events (Redis Streams)
|
||||
|
||||
## Module
|
||||
Platform
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Scanner WebService emits `scanner.report.ready` and `scanner.scan.completed` platform events via Redis Streams with DSSE envelopes embedded verbatim, configurable via `scanner:events:*` settings.
|
||||
|
||||
## Implementation Details
|
||||
- **AnalyticsIngestionService**: `src/Platform/StellaOps.Platform.Analytics/Services/AnalyticsIngestionService.cs` -- subscribes to event stream (configurable via `scanner:events:*` settings); filters for `scanner.report.ready` and `scanner.scan.completed` event kinds from OrchestratorEventEnvelope; tenant-scoped event filtering
|
||||
- **ScannerOrchestratorEvents**: `src/Platform/StellaOps.Platform.Analytics/Models/ScannerOrchestratorEvents.cs` -- event models for scanner platform events
|
||||
- **RekorEvents**: `src/Platform/StellaOps.Platform.Analytics/Models/RekorEvents.cs` -- Rekor transparency log event models
|
||||
- **AdvisoryEvents**: `src/Platform/StellaOps.Platform.Analytics/Models/AdvisoryEvents.cs` -- advisory event models
|
||||
- **IEventStream/IEventStreamFactory**: from `StellaOps.Messaging` -- event stream abstraction for subscribing to platform events with position tracking (Beginning/End)
|
||||
- **Source**: 2025-10-19-scanner-policy.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify scanner.report.ready events are consumed and processed by analytics ingestion
|
||||
- [ ] Test scanner.scan.completed events trigger appropriate analytics updates
|
||||
- [ ] Verify DSSE envelopes are embedded verbatim in event payloads
|
||||
- [ ] Test event stream position tracking resumes from correct position after restart
|
||||
- [ ] Verify tenant filtering skips events from non-allowed tenants
|
||||
@@ -1,40 +0,0 @@
|
||||
# Immutable Advisory Feed Snapshots
|
||||
|
||||
## Module
|
||||
Replay
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
The replay infrastructure supports input manifests and determinism tracking which conceptually align with point-in-time query capability, but a dedicated feed snapshotting system with per-provider immutable blobs and point-in-time advisory resolution is not directly implemented as described.
|
||||
|
||||
## What's Implemented
|
||||
- **Input Manifest Resolver**: `src/Replay/StellaOps.Replay.Core/InputManifestResolver.cs` -- resolves input manifests that capture the exact inputs (feed data, SBOM, VEX, policy) used for a verdict, enabling replay with identical inputs. This provides partial snapshot functionality by recording what feed data was consumed.
|
||||
- **Determinism Verifier**: `src/Replay/StellaOps.Replay.Core/DeterminismVerifier.cs` -- verifies that replaying a verdict with the same inputs produces the same output, which indirectly validates feed data consistency.
|
||||
- **Replay Executor**: `src/Replay/StellaOps.Replay.Core/ReplayExecutor.cs` -- executes verdict replay using captured input manifests, consuming the recorded feed data rather than live feeds.
|
||||
- **Policy Simulation Input Lock**: `src/Replay/StellaOps.Replay.Core/PolicySimulationInputLock.cs` -- locks policy simulation inputs to prevent mutation during replay, ensuring deterministic execution.
|
||||
- **Replay Job Queue**: `src/Replay/StellaOps.Replay.Core/ReplayJobQueue.cs` -- manages replay job scheduling and execution.
|
||||
- **Trace Anonymizer**: `src/Replay/StellaOps.Replay.Anonymization/TraceAnonymizer.cs` -- anonymizes replay traces for sharing without exposing sensitive feed data.
|
||||
- **Verdict Replay Endpoints**: `src/Replay/StellaOps.Replay.WebService/VerdictReplayEndpoints.cs` -- API endpoints for triggering and querying verdict replays.
|
||||
|
||||
## What's Missing
|
||||
- **Per-Provider Feed Snapshots**: No system exists to capture immutable snapshots of advisory feeds on a per-provider basis (e.g., NVD snapshot at epoch T, GHSA snapshot at epoch T). The input manifest records which feed data was used but does not create addressable, immutable blob snapshots.
|
||||
- **Point-in-Time Advisory Resolution**: No API exists to query "what was the advisory state for CVE-X at time T?" across all providers. Feed data is consumed in real-time; historical queries require replaying from input manifests.
|
||||
- **Feed Snapshot Storage**: No dedicated content-addressable storage for feed snapshots (e.g., immutable blobs with digest-based retrieval). Feed data flows through the pipeline but is not persisted as versioned snapshots.
|
||||
- **Snapshot Epoch Registry**: No registry that maps epoch identifiers to feed snapshot digests, enabling O(1) lookup of historical feed state.
|
||||
- **Snapshot Attestation**: No attestation mechanism for feed snapshots that proves the snapshot was captured at a specific time and has not been tampered with.
|
||||
|
||||
## Implementation Plan
|
||||
- Design a per-provider feed snapshot format (content-addressable blob with provider ID, epoch timestamp, digest)
|
||||
- Implement a snapshot capture service that creates immutable blobs when feed data is ingested, storing them in content-addressable storage
|
||||
- Build a snapshot epoch registry mapping epoch IDs to snapshot digests for all providers
|
||||
- Add point-in-time advisory resolution API that resolves advisory state by looking up the appropriate epoch snapshot
|
||||
- Add snapshot attestation (signed digest + timestamp) for tamper-evidence
|
||||
- Integrate with the existing `InputManifestResolver` so replay can reference snapshots by epoch/digest rather than inline data
|
||||
|
||||
## Related Documentation
|
||||
- Replay infrastructure: `src/Replay/StellaOps.Replay.Core/`
|
||||
- Feed ingestion (Concelier): `src/Concelier/`
|
||||
- Feed processing (Excititor): `src/Excititor/`
|
||||
- Determinism testing: `src/__Tests/__Libraries/StellaOps.Testing.Determinism/`
|
||||
@@ -1,25 +0,0 @@
|
||||
# Point-in-Time Vulnerability Query (As-Of Date)
|
||||
|
||||
## Status
|
||||
NOT_FOUND
|
||||
|
||||
## Description
|
||||
The ability to evaluate vulnerabilities against advisory data as of a specific historical date is not implemented. The replay system tracks inputs but does not provide temporal advisory queries.
|
||||
|
||||
## Why Not Implemented
|
||||
- No temporal/as-of-date vulnerability query API found in `src/`
|
||||
- The Replay module (`src/__Libraries/StellaOps.Replay.Core/`) and Unknowns module (`src/Unknowns/`) track historical state but do not provide temporal advisory queries
|
||||
- The Unknowns persistence layer has SQL migrations with `point_in_time` references: `src/Unknowns/__Libraries/StellaOps.Unknowns.Persistence/Migrations/001_initial_schema.sql`
|
||||
- `IUnknownRepository` has methods that could support temporal queries
|
||||
- The Facet module has `FacetSeal` with point-in-time concepts: `src/__Libraries/StellaOps.Facet/FacetSeal.cs`
|
||||
- The Scanner has historical data in Smart Diff tables: `src/Scanner/__Libraries/StellaOps.Scanner.Storage/Postgres/Migrations/005_smart_diff_tables.sql`
|
||||
- Key rotation service tracks historical keys: `src/Signer/__Libraries/StellaOps.Signer.KeyManagement/IKeyRotationService.cs`
|
||||
- Infrastructure for temporal queries exists but no unified "as-of date" API endpoint has been built
|
||||
|
||||
## Source
|
||||
- Feature matrix scan
|
||||
|
||||
## Notes
|
||||
- Module: Uncategorized
|
||||
- Modules referenced: N/A
|
||||
- Related: `src/Unknowns/` (historical tracking), `src/__Libraries/StellaOps.Facet/` (point-in-time seals), `src/__Libraries/StellaOps.Replay.Core/` (replay system)
|
||||
@@ -1,28 +0,0 @@
|
||||
# Replay Infrastructure (Manifest, Determinism Verifier, Verdict Engine, Drift Detection)
|
||||
|
||||
## Module
|
||||
Replay
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Full replay infrastructure: DeterminismVerifier re-hydrates exact inputs from manifest and verifies bit-for-bit verdict reproduction. Run manifest model capturing pipeline state (feeds, rules, versions). DeterministicResolver with feed snapshots, bundle export, and web service. Verdict replay with divergence detection and input drift testing.
|
||||
|
||||
## Implementation Details
|
||||
- **Determinism Verifier**: `src/Replay/__Libraries/StellaOps.Replay.Core/DeterminismVerifier.cs` -- re-hydrates exact inputs from a run manifest and verifies bit-for-bit verdict reproduction; reports divergences between original and replayed verdicts.
|
||||
- **Input Manifest Resolver**: `src/Replay/__Libraries/StellaOps.Replay.Core/InputManifestResolver.cs` -- resolves and snapshots all inputs (feed versions, policy rules, SBOM state) needed to reproduce a verdict, creating a self-contained input manifest.
|
||||
- **Replay Executor**: `src/Replay/__Libraries/StellaOps.Replay.Core/ReplayExecutor.cs` -- orchestrates verdict replay by loading the input manifest, executing the policy evaluation pipeline, and comparing outputs against the original verdict.
|
||||
- **Replay Job Queue**: `src/Replay/__Libraries/StellaOps.Replay.Core/ReplayJobQueue.cs` -- background job queue for scheduling and processing replay verification requests.
|
||||
- **Policy Simulation Input Lock**: `src/Replay/__Libraries/StellaOps.Replay.Core/PolicySimulationInputLock.cs` -- locks input state during replay to prevent concurrent modifications from affecting determinism verification.
|
||||
- **Verdict Replay Endpoints**: `src/Replay/StellaOps.Replay.WebService/VerdictReplayEndpoints.cs` -- REST endpoints for submitting replay requests and querying replay results.
|
||||
- **Web Service Entry Point**: `src/Replay/StellaOps.Replay.WebService/Program.cs` -- ASP.NET Core web service hosting replay endpoints.
|
||||
- **Tests**: `src/Replay/__Tests/StellaOps.Replay.Core.Tests/Unit/DeterminismVerifierTests.cs`, `Unit/InputManifestResolverTests.cs`, `VerdictReplayIntegrationTests.cs`, `VerdictReplayEndpointsTests.cs`, `PolicySimulationInputLockValidatorTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Submit a verdict for replay via the REST endpoint and verify `DeterminismVerifier` produces a bit-for-bit identical verdict when given the same input manifest
|
||||
- [ ] Modify a policy rule between the original verdict and the replay and verify the verifier detects the divergence and reports the specific rule that changed
|
||||
- [ ] Verify input manifest completeness: resolve a manifest for a verdict, then replay using only the manifest contents (no external lookups) and confirm successful reproduction
|
||||
- [ ] Verify input lock: start a replay and concurrently attempt to modify the locked inputs; confirm the modification is blocked until the replay completes
|
||||
- [ ] Submit multiple replay requests to the job queue and verify they execute in order with correct results
|
||||
- [ ] Verify drift detection: replay a verdict with a different feed snapshot version and confirm the verifier reports input drift
|
||||
@@ -1,26 +0,0 @@
|
||||
# Replay Recording and Verification Service
|
||||
|
||||
## Module
|
||||
Replay
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Dedicated replay service that records verdict inputs/outputs and provides endpoints to replay and verify deterministic verdict execution, ensuring reproducibility of security decisions.
|
||||
|
||||
## Implementation Details
|
||||
- **Verdict Replay Endpoints**: `src/Replay/StellaOps.Replay.WebService/VerdictReplayEndpoints.cs` -- REST API endpoints for recording verdict executions, submitting replay requests, and querying verification results.
|
||||
- **Replay Executor**: `src/Replay/__Libraries/StellaOps.Replay.Core/ReplayExecutor.cs` -- executes recorded verdicts with snapshotted inputs and compares outputs for determinism verification.
|
||||
- **Determinism Verifier**: `src/Replay/__Libraries/StellaOps.Replay.Core/DeterminismVerifier.cs` -- compares original and replayed verdict outputs, detecting any divergences in the decision.
|
||||
- **Trace Anonymizer**: `src/Replay/__Libraries/StellaOps.Replay.Anonymization/TraceAnonymizer.cs` (implements `ITraceAnonymizer`) -- anonymizes sensitive data in replay traces before storage or export, enabling safe sharing of replay data for debugging.
|
||||
- **Anonymization Models**: `src/Replay/__Libraries/StellaOps.Replay.Anonymization/Models.cs` -- data models for anonymized trace records.
|
||||
- **Replay Job Queue**: `src/Replay/__Libraries/StellaOps.Replay.Core/ReplayJobQueue.cs` -- queues replay verification jobs for background processing.
|
||||
- **Tests**: `src/Replay/__Tests/StellaOps.Replay.Core.Tests/VerdictReplayIntegrationTests.cs`, `VerdictReplayEndpointsTests.cs`; `src/Replay/__Tests/StellaOps.Replay.Anonymization.Tests/TraceAnonymizerTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Record a verdict execution via the REST API and verify the recording captures all inputs (policy rules, feed state, SBOM) and the output verdict
|
||||
- [ ] Submit a replay request for the recorded verdict and verify the replayed output matches the original bit-for-bit
|
||||
- [ ] Verify trace anonymization: record a verdict with sensitive data (CVE IDs, package names), anonymize the trace via `TraceAnonymizer`, and confirm sensitive fields are replaced while the trace structure is preserved
|
||||
- [ ] Verify the replay service returns a clear divergence report when a non-deterministic element is introduced
|
||||
- [ ] Verify replay queue ordering: submit 5 replay requests and confirm they are processed sequentially in submission order
|
||||
@@ -1,26 +0,0 @@
|
||||
# Tetragon/eBPF Runtime Instrumentation Bridge (Runtime Witnesses, Build Correlation)
|
||||
|
||||
## Module
|
||||
RuntimeInstrumentation
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Tetragon-based eBPF runtime instrumentation with event adaptation, witness bridging, frame canonicalization, privacy filtering, hot-symbol tracking, stack sampling, and runtime correlation to build artifacts for runtime reachability analysis.
|
||||
|
||||
## Implementation Details
|
||||
- **Runtime Traces Endpoints**: `src/Findings/StellaOps.Findings.Ledger.WebService/Endpoints/RuntimeTracesEndpoints.cs` -- REST endpoints for ingesting runtime trace data from Tetragon/eBPF instrumentation.
|
||||
- **Runtime Timeline Endpoints**: `src/Findings/StellaOps.Findings.Ledger.WebService/Endpoints/RuntimeTimelineEndpoints.cs` -- endpoints for querying runtime event timelines correlated with build artifacts.
|
||||
- **Runtime Traces Contracts**: `src/Findings/StellaOps.Findings.Ledger.WebService/Contracts/RuntimeTracesContracts.cs` -- DTOs for runtime trace events including stack frames, symbol data, and correlation metadata.
|
||||
- **Runtime Signal Ingester**: `src/Unknowns/__Libraries/StellaOps.Unknowns.Core/Services/RuntimeSignalIngester.cs` -- ingests runtime signals from eBPF probes and correlates them with known vulnerability findings.
|
||||
- **Null Runtime Traces Service**: `src/Findings/StellaOps.Findings.Ledger.WebService/Services/NullRuntimeTracesService.cs` -- no-op implementation for environments without runtime instrumentation.
|
||||
- **Signal Snapshot Builder**: `src/Findings/StellaOps.Findings.Ledger/Observations/SignalSnapshotBuilder.cs` -- builds snapshots of runtime signals for replay and audit.
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Submit a runtime trace event from Tetragon (stack frames with symbol data) via the runtime traces endpoint and verify it is persisted and queryable
|
||||
- [ ] Correlate a runtime trace with a build artifact: submit trace data referencing a package and verify the timeline endpoint shows the runtime observation linked to the build artifact's SBOM entry
|
||||
- [ ] Verify privacy filtering: submit a trace with user-space memory addresses and confirm they are canonicalized or stripped before storage
|
||||
- [ ] Verify hot-symbol tracking: submit multiple traces for the same symbol and verify the timeline aggregates them with frequency counts
|
||||
- [ ] Verify the null runtime traces service handles requests without errors when runtime instrumentation is disabled
|
||||
- [ ] Query the runtime timeline for a time range and verify events are returned in chronological order with correct correlation metadata
|
||||
@@ -1,31 +0,0 @@
|
||||
# AI Governance Policy Loader for ML-BOM Scanning
|
||||
|
||||
## Module
|
||||
Scanner
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Configurable AI governance policies for scanner-level enforcement of model card requirements, training data lineage thresholds, and EU AI Act compliance categories during SBOM analysis.
|
||||
|
||||
## Implementation Details
|
||||
- **Policy Loader**:
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Policy/AiGovernancePolicyLoader.cs` - Loads and validates AI governance policy configurations
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Policy/AiGovernancePolicy.cs` - Policy model defining model card requirements, training data lineage thresholds, and EU AI Act compliance categories
|
||||
- **Enforcement Analyzers**:
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Analyzers/ModelCardCompletenessAnalyzer.cs` - Enforces model card completeness requirements from policy
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Analyzers/ModelCardScoring.cs` - Scores model cards against policy thresholds
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Analyzers/TrainingDataProvenanceAnalyzer.cs` - Validates training data lineage against policy thresholds
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Analyzers/AiSafetyRiskAnalyzer.cs` - EU AI Act risk classification
|
||||
- **Worker Integration**:
|
||||
- `src/Scanner/StellaOps.Scanner.Worker/Processing/AiMlSecurity/AiMlSecurityStageExecutor.cs` - Stage executor that loads governance policy and runs analyzers during scan
|
||||
- **Models**: `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Models/AiMlSecurityModels.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Configure an AI governance policy with specific model card requirements (e.g., require description, intended use, limitations fields)
|
||||
- [ ] Scan an image containing an ML model with incomplete model card metadata
|
||||
- [ ] Verify the scan produces findings for missing model card fields per policy
|
||||
- [ ] Configure training data lineage threshold and verify scan flags models below threshold
|
||||
- [ ] Configure EU AI Act compliance category and verify classification is applied to findings
|
||||
- [ ] Verify policy changes are picked up on subsequent scans without service restart
|
||||
@@ -1,43 +0,0 @@
|
||||
# AI/ML Supply Chain Security Analysis Module
|
||||
|
||||
## Module
|
||||
Scanner
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Dedicated scanner module for AI/ML supply chain security including EU AI Act risk classification, model card completeness analysis, training data provenance verification, bias/fairness analysis, and AI governance policy enforcement. Distinct from the existing "AI Authority Classification Engine" which focuses on VEX/advisory AI classification, not ML-BOM supply chain scanning.
|
||||
|
||||
## Implementation Details
|
||||
- **Core Analyzer**:
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/AiMlSecurityAnalyzer.cs` - `IAiMlSecurityAnalyzer` / `AiMlSecurityAnalyzer` orchestrates all AI/ML security checks
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/AiMlSecurityServiceCollectionExtensions.cs` - DI registration
|
||||
- **Analysis Context & Results**:
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Analyzers/AiMlSecurityContext.cs` - `AiMlSecurityContext` input model
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Analyzers/AiMlSecurityResult.cs` - `AiMlSecurityResult`, `IAiMlSecurityCheck` interface for pluggable checks
|
||||
- **Individual Analyzers** (each implements `IAiMlSecurityCheck`):
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Analyzers/AiSafetyRiskAnalyzer.cs` - EU AI Act risk classification
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Analyzers/ModelCardCompletenessAnalyzer.cs` - Model card completeness scoring
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Analyzers/ModelCardScoring.cs` - Scoring logic for model card fields
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Analyzers/TrainingDataProvenanceAnalyzer.cs` - Training data lineage verification
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Analyzers/BiasFairnessAnalyzer.cs` - Bias and fairness analysis
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Analyzers/ModelBinaryAnalyzer.cs` - Model binary format analysis
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Analyzers/ModelProvenanceVerifier.cs` - Model provenance verification
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Analyzers/AiModelInventoryGenerator.cs` - Generates inventory of discovered AI/ML models
|
||||
- **Governance Policy**:
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Policy/AiGovernancePolicyLoader.cs` - Policy configuration loader
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Policy/AiGovernancePolicy.cs` - Policy model
|
||||
- **Reporting**: `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Reporting/AiMlSecurityReportFormatter.cs`
|
||||
- **Models**: `src/Scanner/__Libraries/StellaOps.Scanner.AiMlSecurity/Models/AiMlSecurityModels.cs`
|
||||
- **Worker Stage**: `src/Scanner/StellaOps.Scanner.Worker/Processing/AiMlSecurity/AiMlSecurityStageExecutor.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Scan a container image containing ML model artifacts (e.g., ONNX, TensorFlow SavedModel, PyTorch)
|
||||
- [ ] Verify `AiModelInventoryGenerator` discovers and lists all ML models in the scan results
|
||||
- [ ] Verify `ModelCardCompletenessAnalyzer` produces findings for models with missing/incomplete model cards
|
||||
- [ ] Verify `AiSafetyRiskAnalyzer` assigns EU AI Act risk classification (unacceptable, high, limited, minimal)
|
||||
- [ ] Verify `TrainingDataProvenanceAnalyzer` flags models without verifiable training data lineage
|
||||
- [ ] Verify `BiasFairnessAnalyzer` produces bias/fairness findings where applicable
|
||||
- [ ] Verify `ModelBinaryAnalyzer` identifies model format and potential binary-level issues
|
||||
- [ ] Verify all findings appear in the unified scan report and SARIF export
|
||||
@@ -1,31 +0,0 @@
|
||||
# API Gateway Boundary Extractor (Kong, Envoy/Istio, AWS API Gateway, Traefik)
|
||||
|
||||
## Module
|
||||
Scanner
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Parses API gateway configurations from Kong, Envoy/Istio, AWS API Gateway, and Traefik to extract route-level boundary information for reachability analysis. Determines which internal services are exposed through gateway routes.
|
||||
|
||||
## Implementation Details
|
||||
- **Core Extractor**:
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Boundary/GatewayBoundaryExtractor.cs` - `GatewayBoundaryExtractor` implements `IBoundaryProofExtractor`; parses Kong, Envoy/Istio, AWS API Gateway, and Traefik configurations
|
||||
- Includes gateway-specific auth detection: `DetectKongAuth()`, `DetectEnvoyAuth()` (including Istio JWT/AuthorizationPolicy), `DetectTraefikAuth()`
|
||||
- Identifies Istio mesh internal routes and external ingress routes
|
||||
- **Supporting Infrastructure**:
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Boundary/IacBoundaryExtractor.cs` - Infrastructure-as-code boundary extraction
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Boundary/BoundaryServiceCollectionExtensions.cs` - DI registration for boundary extractors
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Boundary/BoundaryExtractionContext.cs` - Context model for boundary extraction
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.Reachability/Boundary/RichGraphBoundaryExtractor.cs` - Integrates boundary data into rich graphs
|
||||
- **Tests**:
|
||||
- `src/Scanner/__Tests/StellaOps.Scanner.Reachability.Tests/GatewayBoundaryExtractorTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Provide a Kong configuration file with routes exposing internal services and verify extracted boundary information includes route paths, upstream services, and auth requirements
|
||||
- [ ] Provide an Envoy/Istio configuration with VirtualService and AuthorizationPolicy and verify correct route-to-service mappings and auth detection
|
||||
- [ ] Provide an AWS API Gateway configuration and verify correct extraction of REST/HTTP API routes with Lambda/ECS integrations
|
||||
- [ ] Provide a Traefik configuration with middleware auth and verify correct route extraction with authentication metadata
|
||||
- [ ] Verify extracted boundaries are reflected in the reachability rich graph via `GET /api/v1/scans/{scanId}/reachability`
|
||||
- [ ] Verify that gated gateway routes (auth-required) reduce reachability risk scores compared to ungated routes
|
||||
@@ -1,32 +0,0 @@
|
||||
# Auto-VEX Generation from Smart-Diff
|
||||
|
||||
## Module
|
||||
Scanner
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
VEX candidate emission from SmartDiff detection results, generating VEX statements backed by delta evidence.
|
||||
|
||||
## Implementation Details
|
||||
- **VEX Candidate Emission**:
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.SmartDiff/Detection/VexCandidateEmitter.cs` - Emits VEX candidates from SmartDiff detection results
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.SmartDiff/Detection/VexCandidateModels.cs` - VEX candidate data models
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.SmartDiff/Detection/VexEvidence.cs` - Delta evidence backing VEX statements
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.SmartDiff/Detection/Repositories.cs` - Repository interfaces for VEX candidate persistence
|
||||
- **SmartDiff Predicate**:
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.SmartDiff/SmartDiffPredicate.cs` - SmartDiff predicate model including VEX data
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.SmartDiff/Detection/ReachabilityGateBridge.cs` - Bridges reachability gate data into SmartDiff VEX candidates
|
||||
- **SARIF Output**:
|
||||
- `src/Scanner/__Libraries/StellaOps.Scanner.SmartDiff/Output/SarifOutputGenerator.cs` - SARIF export including VEX candidate data
|
||||
- **API Endpoint**:
|
||||
- `src/Scanner/StellaOps.Scanner.WebService/Endpoints/SmartDiffEndpoints.cs` - `SmartDiffEndpoints` exposes VEX candidates via REST (`VexCandidatesResponse`, `VexCandidateDto`, `ReviewRequest`)
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Scan two versions of the same image to produce a smart-diff delta
|
||||
- [ ] Call `GET /api/v1/smart-diff/{scanId}/vex-candidates` and verify VEX candidates are returned
|
||||
- [ ] Verify each VEX candidate includes evidence links referencing the specific delta changes
|
||||
- [ ] Submit a review decision via `POST /api/v1/smart-diff/{scanId}/vex-candidates/review` and verify the candidate status updates
|
||||
- [ ] Export the SARIF output and verify VEX candidate data is embedded in the SARIF report
|
||||
- [ ] Verify VEX candidates include reachability gate context when gates are detected
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user