more features checks. setup improvements
This commit is contained in:
master
@@ -0,0 +1,40 @@
|
||||
# AdvisoryAI Orchestrator (Chat + Workbench + Runs)
|
||||
|
||||
## Module
|
||||
AdvisoryAI
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
The AdvisoryAI module provides a chat orchestrator with session management, run tracking (with artifacts and events), and tool routing. Backend web service with chat and run endpoints is operational.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/AdvisoryAI/StellaOps.AdvisoryAI/`, `src/AdvisoryAI/StellaOps.AdvisoryAI.WebService/`, `src/AdvisoryAI/StellaOps.AdvisoryAI.Worker/`
|
||||
- **Key Classes**:
|
||||
- `AdvisoryPipelineOrchestrator` (`src/AdvisoryAI/StellaOps.AdvisoryAI/Orchestration/AdvisoryPipelineOrchestrator.cs`) - main pipeline orchestrator coordinating task plans and execution
|
||||
- `AdvisoryPipelineExecutor` (`src/AdvisoryAI/StellaOps.AdvisoryAI/Execution/AdvisoryPipelineExecutor.cs`) - executes advisory pipeline stages
|
||||
- `AdvisoryChatService` (`src/AdvisoryAI/StellaOps.AdvisoryAI/Chat/Services/AdvisoryChatService.cs`) - chat session orchestration service
|
||||
- `ConversationService` (`src/AdvisoryAI/StellaOps.AdvisoryAI/Chat/ConversationService.cs`) - manages conversation state and context
|
||||
- `RunService` (`src/AdvisoryAI/StellaOps.AdvisoryAI/Runs/RunService.cs`) - tracks runs with artifacts and events
|
||||
- `InMemoryRunStore` (`src/AdvisoryAI/StellaOps.AdvisoryAI/Runs/InMemoryRunStore.cs`) - in-memory storage for run data
|
||||
- `AdvisoryChatIntentRouter` (`src/AdvisoryAI/StellaOps.AdvisoryAI/Chat/Routing/AdvisoryChatIntentRouter.cs`) - routes chat intents to appropriate handlers
|
||||
- `ChatEndpoints` (`src/AdvisoryAI/StellaOps.AdvisoryAI.WebService/Endpoints/ChatEndpoints.cs`) - REST endpoints for chat operations
|
||||
- `RunEndpoints` (`src/AdvisoryAI/StellaOps.AdvisoryAI.WebService/Endpoints/RunEndpoints.cs`) - REST endpoints for run tracking
|
||||
- `AdvisoryTaskWorker` (`src/AdvisoryAI/StellaOps.AdvisoryAI.Worker/Services/AdvisoryTaskWorker.cs`) - background worker processing advisory tasks
|
||||
- **Interfaces**: `IAdvisoryPipelineOrchestrator`, `IRunService`, `IRunStore`
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Submit a chat message via `ChatEndpoints` and verify `AdvisoryChatService` processes it with correct conversation context
|
||||
- [ ] Create a run via `RunEndpoints` and verify `RunService` tracks artifacts and events in `InMemoryRunStore`
|
||||
- [ ] Verify `AdvisoryChatIntentRouter` routes different intent types (explain, remediate, policy) to correct handlers
|
||||
- [ ] Verify `AdvisoryPipelineOrchestrator` creates and executes task plans with `AdvisoryPipelineExecutor`
|
||||
- [ ] Verify `AdvisoryTaskWorker` picks up queued tasks and processes them to completion
|
||||
- [ ] Verify conversation context is maintained across multiple messages in the same session via `ConversationService`
|
||||
|
||||
## Verification
|
||||
- Verified on 2026-02-11 via `run-001`.
|
||||
- Tier 0: `docs/qa/feature-checks/runs/advisoryai/advisoryai-orchestrator/run-001/tier0-source-check.json`
|
||||
- Tier 1: `docs/qa/feature-checks/runs/advisoryai/advisoryai-orchestrator/run-001/tier1-build-check.json`
|
||||
- Tier 2: `docs/qa/feature-checks/runs/advisoryai/advisoryai-orchestrator/run-001/tier2-api-check.json`
|
||||
@@ -0,0 +1,44 @@
|
||||
# AdvisoryAI Pipeline with Guardrails
|
||||
|
||||
## Module
|
||||
AdvisoryAI
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Full advisory AI pipeline with guardrails, chat interface, action execution, and idempotency handling. Includes retrieval, structured/vector retrievers, and SBOM context retrieval.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/AdvisoryAi/StellaOps.AdvisoryAI/`, `src/AdvisoryAi/StellaOps.AdvisoryAI.Hosting/`
|
||||
- **Key Classes**:
|
||||
- `AdvisoryGuardrailPipeline` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Guardrails/AdvisoryGuardrailPipeline.cs`) - guardrail pipeline filtering AI inputs and outputs
|
||||
- `AdvisoryPipelineOrchestrator` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Orchestration/AdvisoryPipelineOrchestrator.cs`) - orchestrates pipeline stages with guardrail checks
|
||||
- `AdvisoryPipelineExecutor` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Execution/AdvisoryPipelineExecutor.cs`) - executes pipeline with pre/post guardrails
|
||||
- `AdvisoryStructuredRetriever` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Retrievers/AdvisoryStructuredRetriever.cs`) - retrieves structured advisory data
|
||||
- `AdvisoryVectorRetriever` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Retrievers/AdvisoryVectorRetriever.cs`) - vector-based semantic retrieval
|
||||
- `SbomContextRetriever` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Retrievers/SbomContextRetriever.cs`) - retrieves SBOM context for vulnerability analysis
|
||||
- `ActionExecutor` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Actions/ActionExecutor.cs`) - executes AI-proposed actions
|
||||
- `IdempotencyHandler` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Actions/IdempotencyHandler.cs`) - ensures idempotent action execution
|
||||
- `GuardrailAllowlistLoader` (`src/AdvisoryAi/StellaOps.AdvisoryAI.Hosting/GuardrailAllowlistLoader.cs`) - loads guardrail allowlists from configuration
|
||||
- `GuardrailPhraseLoader` (`src/AdvisoryAi/StellaOps.AdvisoryAI.Hosting/GuardrailPhraseLoader.cs`) - loads guardrail phrase filters
|
||||
- `AdvisoryAiGuardrailOptions` (`src/AdvisoryAi/StellaOps.AdvisoryAI.Hosting/AdvisoryAiGuardrailOptions.cs`) - guardrail configuration options
|
||||
- **Interfaces**: `IAdvisoryStructuredRetriever`, `IAdvisoryVectorRetriever`, `ISbomContextRetriever`, `IActionExecutor`, `IIdempotencyHandler`
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Submit a prompt through `AdvisoryGuardrailPipeline` and verify guardrails filter prohibited content before reaching LLM
|
||||
- [ ] Verify `AdvisoryStructuredRetriever` returns relevant CVE/advisory data for a given vulnerability query
|
||||
- [ ] Verify `AdvisoryVectorRetriever` performs semantic search and returns ranked results
|
||||
- [ ] Verify `SbomContextRetriever` enriches prompts with SBOM component context
|
||||
- [ ] Execute an action through `ActionExecutor` and verify `IdempotencyHandler` prevents duplicate execution
|
||||
- [ ] Verify `GuardrailAllowlistLoader` and `GuardrailPhraseLoader` correctly load and enforce content filters
|
||||
- [ ] Verify the full pipeline flow: retrieval -> guardrail check -> LLM inference -> output guardrail -> response
|
||||
|
||||
## Verification
|
||||
- Verified on 2026-02-11 via `run-001`.
|
||||
- Tier 0: `docs/qa/feature-checks/runs/advisoryai/advisoryai-pipeline-with-guardrails/run-001/tier0-source-check.json`
|
||||
- Tier 1: `docs/qa/feature-checks/runs/advisoryai/advisoryai-pipeline-with-guardrails/run-001/tier1-build-check.json`
|
||||
- Tier 2: `docs/qa/feature-checks/runs/advisoryai/advisoryai-pipeline-with-guardrails/run-001/tier2-integration-check.json`
|
||||
|
||||
|
||||
37
docs/features/unchecked/advisoryai/ai-action-policy-gate.md
Normal file
37
docs/features/unchecked/advisoryai/ai-action-policy-gate.md
Normal file
@@ -0,0 +1,37 @@
|
||||
# AI Action Policy Gate (K4 Lattice Governance for AI-Proposed Actions)
|
||||
|
||||
## Module
|
||||
AdvisoryAI
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Connects AI-proposed actions to the Policy Engine's K4 lattice for governance-aware automation. Moves beyond simple role checks to VEX-aware policy gates with approval workflows, idempotency tracking, and action audit ledger. Enables "AI that acts" with governance guardrails.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/AdvisoryAi/StellaOps.AdvisoryAI/Actions/`
|
||||
- **Key Classes**:
|
||||
- `ActionPolicyGate` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Actions/ActionPolicyGate.cs`) - evaluates AI-proposed actions against K4 lattice policy rules
|
||||
- `ActionRegistry` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Actions/ActionRegistry.cs`) - registry of available AI actions with metadata and policy requirements
|
||||
- `ActionExecutor` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Actions/ActionExecutor.cs`) - executes approved actions with policy gate checks
|
||||
- `ActionAuditLedger` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Actions/ActionAuditLedger.cs`) - immutable audit trail of all action decisions and executions
|
||||
- `ApprovalWorkflowAdapter` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Actions/ApprovalWorkflowAdapter.cs`) - integrates with approval workflows for gated actions
|
||||
- `IdempotencyHandler` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Actions/IdempotencyHandler.cs`) - ensures actions are not duplicated
|
||||
- `ActionDefinition` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Actions/ActionDefinition.cs`) - defines an action's capabilities, constraints, and policy metadata
|
||||
- **Interfaces**: `IActionPolicyGate`, `IActionRegistry`, `IActionExecutor`, `IActionAuditLedger`, `IApprovalWorkflowAdapter`, `IIdempotencyHandler`, `IGuidGenerator`
|
||||
- **Source**: SPRINT_20260109_011_004_BE_policy_action_integration.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Register an action in `ActionRegistry` and verify `ActionPolicyGate` evaluates it against K4 lattice policy rules
|
||||
- [ ] Submit an action requiring approval and verify `ApprovalWorkflowAdapter` creates an approval request
|
||||
- [ ] Execute a gated action after approval and verify `ActionAuditLedger` records the decision, approval, and execution
|
||||
- [ ] Submit a duplicate action and verify `IdempotencyHandler` prevents re-execution
|
||||
- [ ] Submit an action that violates policy and verify `ActionPolicyGate` rejects it with a policy violation reason
|
||||
- [ ] Verify `ActionDefinition` metadata (risk level, required approvals, allowed scopes) is enforced during gate evaluation
|
||||
## Verification
|
||||
- Verified on 2026-02-11 via `run-002`.
|
||||
- Tier 0: `docs/qa/feature-checks/runs/advisoryai/ai-action-policy-gate/run-002/tier0-source-check.json`
|
||||
- Tier 1: `docs/qa/feature-checks/runs/advisoryai/ai-action-policy-gate/run-002/tier1-build-check.json`
|
||||
- Tier 2: `docs/qa/feature-checks/runs/advisoryai/ai-action-policy-gate/run-002/tier2-integration-check.json`
|
||||
|
||||
@@ -0,0 +1,34 @@
|
||||
# AI Codex / Zastava Companion
|
||||
|
||||
## Module
|
||||
AdvisoryAI
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Companion explanation feature that combines AdvisoryAI evidence-grounded explanations with runtime signals (for example Zastava observer signals) and exposes an API endpoint for companion explain generation.
|
||||
|
||||
## Implementation Details
|
||||
- **Companion Service**: `src/AdvisoryAI/StellaOps.AdvisoryAI/Explanation/CodexZastavaCompanionService.cs`
|
||||
- `ICodexCompanionService` contract and deterministic `CodexZastavaCompanionService` implementation.
|
||||
- Normalizes and deduplicates runtime signals, computes deterministic companion hash, and returns companion summary/highlights.
|
||||
- **Web Endpoint Registration**: `src/AdvisoryAI/StellaOps.AdvisoryAI.WebService/Program.cs`
|
||||
- Registers `ICodexCompanionService` and maps `POST /v1/advisory-ai/companion/explain`.
|
||||
- **API Contracts**: `src/AdvisoryAI/StellaOps.AdvisoryAI.WebService/Contracts/CompanionExplainContracts.cs`
|
||||
- `CompanionExplainRequest`, `CompanionExplainResponse`, runtime-signal request/response contracts, and domain mapping.
|
||||
- **Behavioral Tests**:
|
||||
- `src/AdvisoryAI/__Tests/StellaOps.AdvisoryAI.Companion.Tests/CodexZastavaCompanionServiceTests.cs`
|
||||
- `src/AdvisoryAI/__Tests/StellaOps.AdvisoryAI.Companion.Tests/CompanionExplainEndpointTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Submit companion explain request without scopes and verify the endpoint returns `403`.
|
||||
- [ ] Submit companion explain request with `advisory:companion` scope and verify mapped request + companion response payload.
|
||||
- [ ] Submit companion explain request where companion service rejects input and verify endpoint returns `400`.
|
||||
- [ ] Verify deterministic companion hash for permuted/deduplicated runtime signal inputs.
|
||||
|
||||
## Verification
|
||||
- Verified on 2026-02-11 via `run-002`.
|
||||
- Tier 0: `docs/qa/feature-checks/runs/advisoryai/ai-codex-zastava-companion/run-002/tier0-source-check.json`
|
||||
- Tier 1: `docs/qa/feature-checks/runs/advisoryai/ai-codex-zastava-companion/run-002/tier1-build-check.json`
|
||||
- Tier 2: `docs/qa/feature-checks/runs/advisoryai/ai-codex-zastava-companion/run-002/tier2-integration-check.json`
|
||||
@@ -0,0 +1,37 @@
|
||||
# Deterministic AI Artifact Replay
|
||||
|
||||
## Module
|
||||
AdvisoryAI
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Deterministic replay infrastructure for AI artifacts including replay manifests, prompt template versioning, and input artifact hashing for reproducible AI outputs.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/AdvisoryAI/StellaOps.AdvisoryAI/Replay/`, `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Replay/`
|
||||
- **Key Classes**:
|
||||
- `AIArtifactReplayer` (`src/AdvisoryAI/StellaOps.AdvisoryAI/Replay/AIArtifactReplayer.cs`) - replays AI artifacts with deterministic inputs for verification
|
||||
- `ReplayInputArtifact` (`src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Replay/ReplayInputArtifact.cs`) - input artifact model with content-addressed hashing
|
||||
- `ReplayPromptTemplate` (`src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Replay/ReplayPromptTemplate.cs`) - versioned prompt templates for replay
|
||||
- `ReplayResult` (`src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Replay/ReplayResult.cs`) - replay execution result with comparison data
|
||||
- `ReplayVerificationResult` (`src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Replay/ReplayVerificationResult.cs`) - verification of replay output against original
|
||||
- `ReplayStatus` (`src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Replay/ReplayStatus.cs`) - replay status tracking
|
||||
- `DeterministicHashVectorEncoder` (`src/AdvisoryAI/StellaOps.AdvisoryAI/Vectorization/DeterministicHashVectorEncoder.cs`) - deterministic hash-based vector encoding for reproducibility
|
||||
- **Interfaces**: None (uses concrete replay pipeline)
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Record an AI inference run and verify `AIArtifactReplayer` can replay it with identical inputs
|
||||
- [ ] Verify `ReplayInputArtifact` computes content-addressed hashes that match across replay invocations
|
||||
- [ ] Verify `ReplayPromptTemplate` versioning: replay with a v1 template produces the same output as the original v1 run
|
||||
- [ ] Verify `ReplayVerificationResult` detects differences when the replay output diverges from the original
|
||||
- [ ] Verify `DeterministicHashVectorEncoder` produces identical vectors for identical inputs across runs
|
||||
- [ ] Verify replay with temperature=0 and fixed seed produces bit-identical outputs for supported providers
|
||||
|
||||
## Verification
|
||||
- Verified on 2026-02-11 via `run-001`.
|
||||
- Tier 0: `docs/qa/feature-checks/runs/advisoryai/deterministic-ai-artifact-replay/run-001/tier0-source-check.json`
|
||||
- Tier 1: `docs/qa/feature-checks/runs/advisoryai/deterministic-ai-artifact-replay/run-001/tier1-build-check.json`
|
||||
- Tier 2: `docs/qa/feature-checks/runs/advisoryai/deterministic-ai-artifact-replay/run-001/tier2-integration-check.json`
|
||||
@@ -1,27 +0,0 @@
|
||||
# 4-Tier Backport Evidence Resolver
|
||||
|
||||
## Module
|
||||
Concelier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Multi-tier backport evidence resolution with tier precedence, distro mappings, cross-distro OVAL integration, and deterministic backport verdicts.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/Concelier/__Libraries/StellaOps.Concelier.Merge/`, `src/Concelier/__Libraries/StellaOps.Concelier.BackportProof/`
|
||||
- **Key Classes**:
|
||||
- `BackportEvidenceResolver` (`src/Concelier/__Libraries/StellaOps.Concelier.Merge/Backport/BackportEvidenceResolver.cs`) - multi-tier evidence resolution with tier precedence logic
|
||||
- `BackportStatusService` (`src/Concelier/__Libraries/StellaOps.Concelier.BackportProof/Services/BackportStatusService.cs`) - backport status lookups with version comparison
|
||||
- `FixIndexService` (`src/Concelier/__Libraries/StellaOps.Concelier.BackportProof/Services/FixIndexService.cs`) - O(1) distro patch lookups via fix index
|
||||
- `ProvenanceScopeService` (`src/Concelier/__Libraries/StellaOps.Concelier.Merge/Backport/ProvenanceScopeService.cs`) - provenance scope tracking for backport-aware deduplication
|
||||
- **Persistence**: `ProvenanceScopeRepository` (`src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Postgres/Repositories/ProvenanceScopeRepository.cs`)
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Submit a CVE with known backport status across multiple distros and verify the `BackportEvidenceResolver` returns correct tier-based verdict
|
||||
- [ ] Verify tier precedence: Tier 1 evidence (direct patch proof) overrides Tier 2/3/4 evidence
|
||||
- [ ] Verify cross-distro resolution: same CVE produces correct backport verdicts for Alpine, Debian, and RedHat simultaneously
|
||||
- [ ] Verify deterministic verdicts: identical inputs produce identical backport verdicts across repeated runs
|
||||
- [ ] Verify `FixIndexService` returns O(1) lookup performance for known distro patch entries
|
||||
@@ -1,32 +0,0 @@
|
||||
# Advisory Connector Architecture (NVD, OSV, GHSA, Vendor Feeds)
|
||||
|
||||
## Module
|
||||
Concelier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Extensive advisory connector ecosystem with vendor-specific connectors for VMware, Oracle, MSRC, Cisco, Chromium, Apple, plus NVD, OSV, GHSA, RedHat, SUSE, Debian, Alpine, Ubuntu, KEV, EPSS, CERT-FR, CERT-CC, CERT-Bund feeds.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/Concelier/__Libraries/StellaOps.Concelier.Connector.*`, `src/Concelier/__Connectors/`, `src/Concelier/StellaOps.Concelier.Plugin.Unified/`
|
||||
- **Key Classes**:
|
||||
- **Plugin System**: `FeedPluginAdapterFactory`, `FeedPluginAdapter` (`src/Concelier/StellaOps.Concelier.Plugin.Unified/`) - unified plugin adapter for `IConnectorPlugin` implementations
|
||||
- **Orchestration**: `ConnectorRegistrationService` (`src/Concelier/__Libraries/StellaOps.Concelier.Core/Orchestration/ConnectorRegistrationService.cs`) - discovers and registers connector plugins
|
||||
- `ConnectorWorker` (`src/Concelier/__Libraries/StellaOps.Concelier.Core/Orchestration/ConnectorWorker.cs`) - executes connector ingestion cycles
|
||||
- **Vendor Connectors**: `CiscoConnector`, `VmwareConnector`, `OracleConnector`, `MsrcConnector`, `AppleConnector`, `ChromiumConnector`, `AdobeConnector` (each in `src/Concelier/__Libraries/StellaOps.Concelier.Connector.Vndr.*`)
|
||||
- **Feed Connectors**: `NvdConnector`, `OsvConnector`, `GhsaConnector`, `EpssConnector`, `KevConnector`, `CveConnector` (each in `src/Concelier/__Libraries/StellaOps.Concelier.Connector.*`)
|
||||
- **CERT Connectors**: `CertBundConnector`, `CertFrConnector`, `CertCcConnector`, `CertInConnector` (each in `src/Concelier/__Libraries/StellaOps.Concelier.Connector.Cert*`)
|
||||
- **Distro Connectors**: `AlpineConnector`, `DebianConnector`, `RedHatConnector`, `SuseConnector`, `UbuntuConnector` (each in `src/Concelier/__Libraries/StellaOps.Concelier.Connector.Distro.*`)
|
||||
- **Regional Connectors**: `AcscConnector`, `KisaConnector`, `JvnConnector`, `IcsCisaConnector`, `KasperskyConnector`, `RuBduConnector`, `RuNkckiConnector`, `AstraConnector`, `StellaOpsMirrorConnector`
|
||||
- **Interfaces**: `IFeedConnector`, `IConnectorPlugin`
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify `ConnectorRegistrationService` discovers all connector plugins via DI
|
||||
- [ ] Trigger a connector ingestion cycle via `ConnectorWorker` for NVD and verify advisories are stored
|
||||
- [ ] Verify GHSA connector fetches GitHub Security Advisories and maps to canonical format
|
||||
- [ ] Verify EPSS connector fetches exploit prediction scores and associates with CVE IDs
|
||||
- [ ] Verify at least one vendor connector (e.g., Cisco) fetches vendor-specific advisories
|
||||
- [ ] Verify at least one distro connector (e.g., Debian) fetches distro-specific patch data
|
||||
@@ -1,30 +0,0 @@
|
||||
# Advisory Federation with Delta Bundle Export/Import
|
||||
|
||||
## Module
|
||||
Concelier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Cursor-based federation system for synchronizing canonical advisories across sites (including air-gapped). Exports ZST-compressed NDJSON delta bundles with DSSE signatures, imports with verification (hash, signature, site policy), merge with conflict detection, and sync ledger for cursor tracking. Supports CLI commands (feedser bundle export/import) and REST API endpoints.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/Concelier/__Libraries/StellaOps.Concelier.Federation/`, `src/Concelier/__Libraries/StellaOps.Concelier.Persistence/`
|
||||
- **Key Classes**:
|
||||
- `BundleExportService` (`src/Concelier/__Libraries/StellaOps.Concelier.Federation/Export/BundleExportService.cs`) - exports ZST-compressed NDJSON delta bundles with DSSE signatures
|
||||
- `BundleImportService` (`src/Concelier/__Libraries/StellaOps.Concelier.Federation/Import/BundleImportService.cs`) - imports bundles with verification and conflict detection
|
||||
- `BundleVerifier` (`src/Concelier/__Libraries/StellaOps.Concelier.Federation/Import/BundleVerifier.cs`) - verifies bundle hash and DSSE signatures
|
||||
- `SyncLedgerRepository` (`src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Postgres/Repositories/SyncLedgerRepository.cs`) - cursor-based sync ledger for tracking federation state
|
||||
- `SyncLedgerEntity` (`src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Postgres/Models/SyncLedgerEntity.cs`) - persistence model for sync ledger entries
|
||||
- `PostgresExportStateStore` (`src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Postgres/Repositories/PostgresExportStateStore.cs`) - export state tracking
|
||||
- **Interfaces**: `IBundleExportService`, `IBundleImportService`, `IBundleVerifier`, `ISyncLedgerRepository`
|
||||
- **Source**: SPRINT_8200_0014_0001 + 0002 + 0003
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Export a delta bundle via `BundleExportService` and verify the output is ZST-compressed NDJSON with a DSSE signature
|
||||
- [ ] Import the exported bundle via `BundleImportService` and verify all advisories are restored
|
||||
- [ ] Verify `BundleVerifier` rejects a bundle with a tampered hash or invalid signature
|
||||
- [ ] Verify cursor-based sync: export with cursor, add new advisories, export again, verify only delta is included
|
||||
- [ ] Verify `SyncLedgerRepository` tracks cursor positions per remote site
|
||||
- [ ] Verify deterministic export: same input produces identical bundle content (excluding timestamps)
|
||||
@@ -1,30 +0,0 @@
|
||||
# Advisory Ingestion with Canonical Deduplication
|
||||
|
||||
## Module
|
||||
Concelier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Advisory ingestion pipeline with canonical deduplication, linkset observation factory, and raw advisory processing.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/Concelier/__Libraries/StellaOps.Concelier.Core/`, `src/Concelier/__Libraries/StellaOps.Concelier.Merge/`, `src/Concelier/__Libraries/StellaOps.Concelier.Persistence/`
|
||||
- **Key Classes**:
|
||||
- `CanonicalAdvisoryService` (`src/Concelier/__Libraries/StellaOps.Concelier.Core/Canonical/CanonicalAdvisoryService.cs`) - core canonical advisory management
|
||||
- `CachingCanonicalAdvisoryService` (`src/Concelier/__Libraries/StellaOps.Concelier.Core/Canonical/CachingCanonicalAdvisoryService.cs`) - caching decorator for canonical advisory lookups
|
||||
- `MergeHashCalculator` (`src/Concelier/__Libraries/StellaOps.Concelier.Merge/Identity/MergeHashCalculator.cs`) - deterministic semantic merge hash for deduplication
|
||||
- `ConnectorWorker` (`src/Concelier/__Libraries/StellaOps.Concelier.Core/Orchestration/ConnectorWorker.cs`) - orchestrates advisory ingestion cycles
|
||||
- `AdvisoryRepository` (`src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Postgres/Repositories/AdvisoryRepository.cs`) - raw advisory persistence
|
||||
- `AdvisoryCanonicalRepository` (`src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Postgres/Repositories/AdvisoryCanonicalRepository.cs`) - canonical advisory persistence
|
||||
- `AdvisorySourceEdgeEntity` (`src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Postgres/Models/AdvisorySourceEdgeEntity.cs`) - source-to-canonical edge tracking
|
||||
- **Interfaces**: `ICanonicalAdvisoryService`, `IMergeHashCalculator`, `IAdvisoryRepository`, `IAdvisoryCanonicalRepository`
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Ingest the same advisory from two different sources (e.g., NVD and GHSA) and verify they deduplicate to a single canonical advisory
|
||||
- [ ] Verify `MergeHashCalculator` produces identical hashes for semantically equivalent advisories from different sources
|
||||
- [ ] Verify `AdvisorySourceEdgeEntity` tracks both source edges pointing to the same canonical
|
||||
- [ ] Verify `CachingCanonicalAdvisoryService` returns cached results on repeated lookups
|
||||
- [ ] Verify new advisories with different CVE IDs produce distinct canonicals
|
||||
@@ -1,32 +0,0 @@
|
||||
# Advisory Interest Scoring Service
|
||||
|
||||
## Module
|
||||
Concelier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Learns which advisories matter to an organization by computing interest scores from SBOM intersection, reachability, deployment, VEX status, and age decay signals. Includes background recalculation jobs and stub degradation for low-interest advisories.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/Concelier/__Libraries/StellaOps.Concelier.Interest/`, `src/Concelier/__Libraries/StellaOps.Concelier.Persistence/`
|
||||
- **Key Classes**:
|
||||
- `InterestScoringService` (`src/Concelier/__Libraries/StellaOps.Concelier.Interest/InterestScoringService.cs`) - main service computing interest scores from multiple signals
|
||||
- `InterestScoreCalculator` (`src/Concelier/__Libraries/StellaOps.Concelier.Interest/InterestScoreCalculator.cs`) - calculates weighted interest scores
|
||||
- `InterestScoreRecalculationJob` (`src/Concelier/__Libraries/StellaOps.Concelier.Interest/Jobs/InterestScoreRecalculationJob.cs`) - `BackgroundService` for periodic recalculation
|
||||
- `InterestScoreOptions` (`src/Concelier/__Libraries/StellaOps.Concelier.Interest/InterestScoreOptions.cs`) - configurable weights and thresholds
|
||||
- `InterestScoreWeights` (`src/Concelier/__Libraries/StellaOps.Concelier.Interest/InterestScoreOptions.cs`) - weight configuration for scoring signals
|
||||
- `InterestScoringMetrics` (`src/Concelier/__Libraries/StellaOps.Concelier.Interest/InterestScoringMetrics.cs`) - OpenTelemetry metrics for scoring operations
|
||||
- `InterestScoreRepository` (`src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Postgres/Repositories/InterestScoreRepository.cs`) - PostgreSQL persistence for interest scores
|
||||
- **API**: `InterestScoreEndpointExtensions` (`src/Concelier/StellaOps.Concelier.WebService/Extensions/InterestScoreEndpointExtensions.cs`) - REST endpoints for interest score queries
|
||||
- **Interfaces**: `IInterestScoringService`, `IInterestScoreRepository`
|
||||
- **Source**: SPRINT_8200_0013_0002_CONCEL_interest_scoring.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Compute interest score for an advisory that intersects with a deployed SBOM and verify score is high
|
||||
- [ ] Compute interest score for an advisory with no SBOM intersection and verify score is low
|
||||
- [ ] Verify age decay: recompute score for an older advisory and confirm it decreases over time
|
||||
- [ ] Verify `InterestScoreRecalculationJob` runs periodically and updates scores in the repository
|
||||
- [ ] Verify configurable weights: adjust `InterestScoreWeights` and confirm scoring output changes accordingly
|
||||
- [ ] Verify REST endpoints return interest scores for queried advisories
|
||||
@@ -1,26 +0,0 @@
|
||||
# Advisory-Mode Formula for Evidence-Weighted Scoring
|
||||
|
||||
## Module
|
||||
Concelier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
New FormulaMode enum (Advisory vs Legacy) for the EWS scoring engine that adds CVSS base score, exploit maturity level, and patch proof confidence as first-class scoring dimensions. Includes VEX override logic where authoritative not_affected status forces score to zero. Extends beyond the known "Evidence-Weighted Score (EWS) Model" with new dimensions and formula modes.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/Concelier/__Libraries/StellaOps.Concelier.Interest/`, `src/Concelier/__Libraries/StellaOps.Concelier.Core/Risk/`
|
||||
- **Key Classes**:
|
||||
- `InterestScoreCalculator` (`src/Concelier/__Libraries/StellaOps.Concelier.Interest/InterestScoreCalculator.cs`) - scoring calculator with formula mode support
|
||||
- `InterestScoreOptions` (`src/Concelier/__Libraries/StellaOps.Concelier.Interest/InterestScoreOptions.cs`) - formula mode configuration and weight tuning
|
||||
- `VendorRiskSignalExtractor` (`src/Concelier/__Libraries/StellaOps.Concelier.Core/Risk/VendorRiskSignalExtractor.cs`) - extracts risk signals from vendor advisories
|
||||
- `PolicyStudioSignalPicker` (`src/Concelier/__Libraries/StellaOps.Concelier.Core/Risk/PolicyStudio/PolicyStudioSignalPicker.cs`) - picks signals for policy studio integration
|
||||
- **Source**: batch_37/file_05.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Compute EWS score in Advisory mode with CVSS base, exploit maturity, and patch proof inputs and verify all dimensions contribute
|
||||
- [ ] Compute EWS score in Legacy mode and verify it uses the original formula without new dimensions
|
||||
- [ ] Verify VEX override: submit an advisory with authoritative `not_affected` VEX status and verify score is forced to zero
|
||||
- [ ] Verify exploit maturity signal: advisory with active exploitation scores higher than one without
|
||||
- [ ] Verify patch proof confidence: advisory with confirmed patch proof scores lower (less urgent) than one without
|
||||
@@ -1,32 +0,0 @@
|
||||
# Astra Linux OVAL Feed Connector
|
||||
|
||||
## Module
|
||||
Concelier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Advisory feed connector for Astra Linux (Russian certified distro) implementing IFeedConnector interface. Includes OVAL XML feed research, plugin scaffold, AstraOptions configuration, and trust defaults. Reuses DebianVersionComparer for version comparison. OVAL XML parser is partially implemented.
|
||||
|
||||
## What's Implemented
|
||||
- **Connector Plugin**: `AstraConnectorPlugin` (`src/Concelier/__Connectors/StellaOps.Concelier.Connector.Astra/AstraConnectorPlugin.cs`) - `IConnectorPlugin` registration with DI
|
||||
- **Connector**: `AstraConnector` (`src/Concelier/__Connectors/StellaOps.Concelier.Connector.Astra/AstraConnector.cs`) - `IFeedConnector` implementation scaffold
|
||||
- **Documentation**: `IMPLEMENTATION_NOTES.md` and `README.md` in the connector directory
|
||||
|
||||
## What's Missing
|
||||
- Full OVAL XML parser for Astra Linux specific advisory format
|
||||
- Version comparison integration with DebianVersionComparer for Astra-specific version strings
|
||||
- Test coverage with sample Astra Linux OVAL feeds
|
||||
- Trust level calibration for Astra Linux as an advisory source
|
||||
|
||||
## Implementation Plan
|
||||
- Complete the OVAL XML parser to handle Astra Linux specific OVAL definitions
|
||||
- Integrate DebianVersionComparer for version range matching
|
||||
- Add unit tests with sample Astra OVAL XML feeds
|
||||
- Calibrate trust defaults based on Astra Linux advisory source quality
|
||||
- Add integration test with `ConnectorRegistrationService` for plugin discovery
|
||||
|
||||
## Related Documentation
|
||||
- Source: SPRINT_20251229_005_CONCEL_astra_connector.md
|
||||
- Implementation notes: `src/Concelier/__Connectors/StellaOps.Concelier.Connector.Astra/IMPLEMENTATION_NOTES.md`
|
||||
@@ -1,31 +0,0 @@
|
||||
# Backport-Aware Advisory Deduplication with Provenance Scope
|
||||
|
||||
## Module
|
||||
Concelier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Enhances canonical advisory deduplication to be backport-aware. Same CVE with different backport status produces correctly differentiated canonicals. Includes provenance_scope tracking, configurable vendor vs. distro precedence lattice, and patch lineage normalization for merge_hash computation.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/Concelier/__Libraries/StellaOps.Concelier.Merge/`, `src/Concelier/__Libraries/StellaOps.Concelier.Persistence/`
|
||||
- **Key Classes**:
|
||||
- `MergeHashCalculator` (`src/Concelier/__Libraries/StellaOps.Concelier.Merge/Identity/MergeHashCalculator.cs`) - merge hash computation with backport-aware normalization
|
||||
- `MergeHashBackfillService` (`src/Concelier/__Libraries/StellaOps.Concelier.Merge/Services/MergeHashBackfillService.cs`) - backfills merge hashes for existing advisories
|
||||
- `MergeHashBackfillJob` (`src/Concelier/__Libraries/StellaOps.Concelier.Merge/Jobs/MergeHashBackfillJob.cs`) - scheduled job for merge hash backfill
|
||||
- `MergeHashShadowWriteService` (`src/Concelier/__Libraries/StellaOps.Concelier.Merge/Identity/MergeHashShadowWriteService.cs`) - shadow writes for merge hash validation
|
||||
- `ProvenanceScopeService` (`src/Concelier/__Libraries/StellaOps.Concelier.Merge/Backport/ProvenanceScopeService.cs`) - provenance scope tracking and management
|
||||
- `ProvenanceScopeRepository` (`src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Postgres/Repositories/ProvenanceScopeRepository.cs`) - PostgreSQL persistence for provenance scopes
|
||||
- `ProvenanceScopeEntity` (`src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Postgres/Models/ProvenanceScopeEntity.cs`) - database entity for provenance scope
|
||||
- `PostgresProvenanceScopeStore` (`src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Postgres/Repositories/PostgresProvenanceScopeStore.cs`) - store implementation
|
||||
- **Interfaces**: `IMergeHashCalculator`, `IProvenanceScopeService`, `IProvenanceScopeRepository`
|
||||
- **Source**: SPRINT_8200_0015_0001_CONCEL_backport_integration.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Ingest same CVE with different backport status (patched vs unpatched) from two distros and verify they produce distinct canonical advisories
|
||||
- [ ] Verify `MergeHashCalculator` differentiates merge hashes when backport status differs for the same CVE
|
||||
- [ ] Verify `ProvenanceScopeService` correctly tracks which provenance scope each canonical belongs to
|
||||
- [ ] Verify vendor vs. distro precedence: when vendor says "not affected" but distro says "patched", verify the precedence lattice resolves correctly
|
||||
- [ ] Verify `MergeHashBackfillService` can retroactively update merge hashes for pre-existing advisories
|
||||
@@ -1,26 +0,0 @@
|
||||
# Backport FixIndex Service with O(1) Distro Patch Lookups
|
||||
|
||||
## Module
|
||||
Concelier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Indexed distro patch lookup service providing O(1) performance for determining whether a specific package version contains a backported fix for a given CVE across multiple distributions.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/Concelier/__Libraries/StellaOps.Concelier.BackportProof/`
|
||||
- **Key Classes**:
|
||||
- `FixIndexService` (`src/Concelier/__Libraries/StellaOps.Concelier.BackportProof/Services/FixIndexService.cs`) - O(1) indexed lookup for distro patch status
|
||||
- `BackportStatusService` (`src/Concelier/__Libraries/StellaOps.Concelier.BackportProof/Services/BackportStatusService.cs`) - backport status resolution with version comparison
|
||||
- `BackportEvidenceResolver` (`src/Concelier/__Libraries/StellaOps.Concelier.Merge/Backport/BackportEvidenceResolver.cs`) - multi-tier evidence resolution consuming fix index data
|
||||
- **Interfaces**: `IFixIndexService`, `IBackportStatusService`
|
||||
- **Source**: SPRINT_20251229_004_002_BE_backport_status_service.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Query `FixIndexService` for a known CVE+distro+package combination and verify it returns patch status in O(1)
|
||||
- [ ] Verify `BackportStatusService` correctly compares package versions to determine if a backport fix is present
|
||||
- [ ] Verify cross-distro lookups: query the same CVE for Alpine, Debian, and RedHat and verify correct fix status for each
|
||||
- [ ] Verify index population: ingest distro connector data and verify the fix index is populated
|
||||
- [ ] Verify negative case: query for a CVE with no known backport fix and verify "unknown" or "not fixed" status
|
||||
@@ -1,28 +0,0 @@
|
||||
# Canonical Advisory Source Edge Schema (Database Layer)
|
||||
|
||||
## Module
|
||||
Concelier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Database schema for provenance-scoped canonical advisory deduplication. Stores deduplicated advisories with merge_hash identity and links each to source documents via DSSE-signed source edges. Enables multi-source advisory merge with full provenance tracking.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/Concelier/__Libraries/StellaOps.Concelier.Persistence/`, `src/Concelier/__Libraries/StellaOps.Concelier.Merge/`
|
||||
- **Key Classes**:
|
||||
- `AdvisorySourceEdgeEntity` (`src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Postgres/Models/AdvisorySourceEdgeEntity.cs`) - database entity linking canonical advisories to source documents
|
||||
- `AdvisoryCanonicalRepository` (`src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Postgres/Repositories/AdvisoryCanonicalRepository.cs`) - canonical advisory CRUD with merge_hash identity
|
||||
- `AdvisoryRepository` (`src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Postgres/Repositories/AdvisoryRepository.cs`) - raw advisory persistence
|
||||
- `MergeHashCalculator` (`src/Concelier/__Libraries/StellaOps.Concelier.Merge/Identity/MergeHashCalculator.cs`) - deterministic merge hash for deduplication identity
|
||||
- `ConcelierDbContext` (`src/Concelier/__Libraries/StellaOps.Concelier.Persistence/EfCore/Context/ConcelierDbContext.cs`) - EF Core context with source edge schema
|
||||
- `ConcelierDataSource` (`src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Postgres/ConcelierDataSource.cs`) - PostgreSQL data source configuration
|
||||
- **Source**: SPRINT_8200_0012_0002_DB_canonical_source_edge_schema.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Insert a canonical advisory with merge_hash and verify it persists in PostgreSQL via `AdvisoryCanonicalRepository`
|
||||
- [ ] Insert two source edges linking different raw advisories to the same canonical and verify both edges are retrievable
|
||||
- [ ] Verify merge_hash uniqueness: attempting to insert a duplicate merge_hash updates the existing canonical rather than creating a new one
|
||||
- [ ] Verify source edge provenance: query a canonical and verify all linked source documents are returned with provenance metadata
|
||||
- [ ] Verify schema migration applies cleanly on a fresh database
|
||||
@@ -1,25 +0,0 @@
|
||||
# CCCS Advisory Connector
|
||||
|
||||
## Module
|
||||
Concelier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Canadian Centre for Cyber Security (CCCS) advisory connector with HTML parsing, raw document mapping, and scheduled job ingestion. The known list has "Cross-Distro Advisory Connectors" and "Advisory Connector Architecture (NVD, OSV, GHSA, Vendor Feeds)" but not CCCS specifically.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/Concelier/__Libraries/StellaOps.Concelier.Connector.Cccs/`
|
||||
- **Key Classes**:
|
||||
- `CccsConnector` (`src/Concelier/__Libraries/StellaOps.Concelier.Connector.Cccs/CccsConnector.cs`) - `IFeedConnector` implementation for CCCS advisory feed ingestion
|
||||
- `CccsConnectorPlugin` (`src/Concelier/__Libraries/StellaOps.Concelier.Connector.Cccs/CccsConnectorPlugin.cs`) - `IConnectorPlugin` registration for DI discovery
|
||||
- **Orchestration**: `ConnectorRegistrationService` (`src/Concelier/__Libraries/StellaOps.Concelier.Core/Orchestration/ConnectorRegistrationService.cs`) - discovers and registers the CCCS plugin
|
||||
- **Interfaces**: `IFeedConnector`, `IConnectorPlugin`
|
||||
- **Source**: Sprint 0117 (batch_14/file_18.md)
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Trigger CCCS connector ingestion and verify advisory documents are fetched and mapped to canonical format
|
||||
- [ ] Verify `CccsConnectorPlugin` is discovered by `ConnectorRegistrationService` during startup
|
||||
- [ ] Verify HTML parsing: submit a sample CCCS HTML advisory and verify fields are correctly extracted
|
||||
- [ ] Verify scheduled ingestion: confirm the connector runs on its configured schedule via `ConnectorWorker`
|
||||
@@ -1,25 +0,0 @@
|
||||
# Cisco Vendor Advisory Connector
|
||||
|
||||
## Module
|
||||
Concelier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Cisco vendor advisory connector for ingesting Cisco security advisories with provenance-tracked mapping. Not individually listed in the known features.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/Concelier/__Libraries/StellaOps.Concelier.Connector.Vndr.Cisco/`
|
||||
- **Key Classes**:
|
||||
- `CiscoConnector` (`src/Concelier/__Libraries/StellaOps.Concelier.Connector.Vndr.Cisco/CiscoConnector.cs`) - `IFeedConnector` implementation for Cisco PSIRT advisory ingestion
|
||||
- `VndrCiscoConnectorPlugin` (`src/Concelier/__Libraries/StellaOps.Concelier.Connector.Vndr.Cisco/VndrCiscoConnectorPlugin.cs`) - `IConnectorPlugin` registration for DI discovery
|
||||
- `CiscoRawAdvisory` (`src/Concelier/__Libraries/StellaOps.Concelier.Connector.Vndr.Cisco/Internal/CiscoRawAdvisory.cs`) - raw Cisco advisory model
|
||||
- **Interfaces**: `IFeedConnector`, `IConnectorPlugin`
|
||||
- **Source**: Sprint 0117 (batch_14/file_18.md)
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Trigger Cisco connector ingestion and verify Cisco PSIRT advisories are fetched and stored
|
||||
- [ ] Verify `VndrCiscoConnectorPlugin` is discovered by `ConnectorRegistrationService` during startup
|
||||
- [ ] Verify `CiscoRawAdvisory` correctly maps Cisco-specific fields (advisory ID, CVSS, affected products)
|
||||
- [ ] Verify provenance tracking: ingested advisories retain Cisco as the provenance source
|
||||
@@ -1,27 +0,0 @@
|
||||
# Concelier Advisory Chunks API (Paragraph-Anchored)
|
||||
|
||||
## Module
|
||||
Concelier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
REST API endpoint serving paragraph-anchored advisory chunks with tenant enforcement, AdvisoryRead scopes, and filters for sections/formats/limits/minLength. Designed for Advisory AI to pull deterministic paragraph anchors plus source metadata.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/Concelier/StellaOps.Concelier.WebService/`
|
||||
- **Key Classes**:
|
||||
- `AdvisoryChunkBuilder` (`src/Concelier/StellaOps.Concelier.WebService/Services/AdvisoryChunkBuilder.cs`) - builds paragraph-anchored chunks from advisory content
|
||||
- `AdvisoryChunkCache` (`src/Concelier/StellaOps.Concelier.WebService/Services/AdvisoryChunkCache.cs`) - in-memory cache for advisory chunks
|
||||
- `MessagingAdvisoryChunkCache` (`src/Concelier/StellaOps.Concelier.WebService/Services/MessagingAdvisoryChunkCache.cs`) - messaging-backed cache implementation
|
||||
- `AdvisoryChunkOptions` (`src/Concelier/StellaOps.Concelier.WebService/Options/ConcelierOptions.cs`) - configuration for chunk sizes, limits, and formats
|
||||
- **Interfaces**: `IAdvisoryChunkCache`
|
||||
- **Source**: 2025-11-07-concelier-advisory-chunks.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Call the advisory chunks endpoint with a valid advisory ID and verify paragraph-anchored chunks are returned
|
||||
- [ ] Verify tenant enforcement: request chunks without AdvisoryRead scope and confirm 403 response
|
||||
- [ ] Verify section filter: request only specific sections and confirm only matching chunks are returned
|
||||
- [ ] Verify minLength filter: set minLength and confirm short paragraphs are excluded
|
||||
- [ ] Verify caching: request same advisory chunks twice and confirm second response is served from cache
|
||||
@@ -1,24 +0,0 @@
|
||||
# Concelier Deprecation Headers Middleware
|
||||
|
||||
## Module
|
||||
Concelier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
HTTP deprecation headers middleware for Concelier API endpoints, signaling API version lifecycle to consumers. Not in the known list.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/Concelier/StellaOps.Concelier.WebService/Deprecation/`
|
||||
- **Key Classes**:
|
||||
- `DeprecationMiddleware` (`src/Concelier/StellaOps.Concelier.WebService/Deprecation/DeprecationMiddleware.cs`) - ASP.NET Core middleware that adds HTTP deprecation headers to responses
|
||||
- `DeprecationMiddlewareExtensions` (`src/Concelier/StellaOps.Concelier.WebService/Deprecation/DeprecationMiddleware.cs`) - extension methods for middleware registration
|
||||
- `DeprecationMiddlewareRegistration` (`src/Concelier/StellaOps.Concelier.WebService/Deprecation/DeprecationMiddleware.cs`) - DI registration helpers
|
||||
- **Source**: Sprint 0116 (batch_14/file_17.md)
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Call a deprecated API endpoint and verify the response includes `Deprecation` and `Sunset` HTTP headers
|
||||
- [ ] Call a non-deprecated endpoint and verify no deprecation headers are present
|
||||
- [ ] Verify the deprecation date format conforms to RFC 7231
|
||||
- [ ] Verify middleware registration: confirm `DeprecationMiddleware` is in the ASP.NET Core pipeline
|
||||
@@ -1,28 +0,0 @@
|
||||
# Concelier LNM Linkset Cache with Telemetry
|
||||
|
||||
## Module
|
||||
Concelier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
PostgreSQL-backed deterministic cache for Link-Not-Merge advisory linksets with telemetry instrumentation, OpenAPI spec, and deprecation headers. While "Link-Not-Merge Advisory Architecture" is in the known list, this specific linkset caching with persistence and telemetry is a distinct implementation detail.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/Concelier/__Libraries/StellaOps.Concelier.Core/Linksets/`, `src/Concelier/__Libraries/StellaOps.Concelier.Persistence/`, `src/Concelier/__Libraries/StellaOps.Concelier.Cache.Valkey/`
|
||||
- **Key Classes**:
|
||||
- `LinksetCorrelationService` (`src/Concelier/__Libraries/StellaOps.Concelier.Core/Linksets/LinksetCorrelationService.cs`) - main service for linkset correlation and caching
|
||||
- `LinksetCorrelationV2` (`src/Concelier/__Libraries/StellaOps.Concelier.Core/Linksets/LinksetCorrelationV2.cs`) - V2 algorithm for linkset correlation
|
||||
- `LinksetCorrelation` (`src/Concelier/__Libraries/StellaOps.Concelier.Core/Linksets/LinksetCorrelation.cs`) - V1 linkset correlation logic
|
||||
- `ValkeyAdvisoryCacheService` (`src/Concelier/__Libraries/StellaOps.Concelier.Cache.Valkey/ValkeyAdvisoryCacheService.cs`) - Valkey-backed caching layer
|
||||
- `AdvisoryCacheKeys` (`src/Concelier/__Libraries/StellaOps.Concelier.Cache.Valkey/AdvisoryCacheKeys.cs`) - deterministic cache key generation
|
||||
- **Interfaces**: `ILinksetCorrelationService`, `IAdvisoryCacheService`
|
||||
- **Source**: Sprint 0112 (batch_14/file_13.md)
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Request a linkset for a known CVE and verify the correlation result is returned
|
||||
- [ ] Verify caching: request the same linkset twice and confirm the second call is served from cache
|
||||
- [ ] Verify telemetry: confirm cache hit/miss metrics are emitted via OpenTelemetry
|
||||
- [ ] Verify determinism: identical linkset inputs produce identical cache keys via `AdvisoryCacheKeys`
|
||||
- [ ] Verify V2 algorithm: use `LinksetCorrelationV2` and verify improved correlation accuracy over V1
|
||||
@@ -1,24 +0,0 @@
|
||||
# Concelier Policy Studio Signal Picker
|
||||
|
||||
## Module
|
||||
Concelier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Policy Studio integration that selects and filters risk signals from advisory data for policy evaluation, including vendor risk signal extraction and fix availability emission. Not in the known list.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/Concelier/__Libraries/StellaOps.Concelier.Core/Risk/PolicyStudio/`, `src/Concelier/__Libraries/StellaOps.Concelier.Core/Risk/`
|
||||
- **Key Classes**:
|
||||
- `PolicyStudioSignalPicker` (`src/Concelier/__Libraries/StellaOps.Concelier.Core/Risk/PolicyStudio/PolicyStudioSignalPicker.cs`) - selects and filters risk signals for policy evaluation
|
||||
- `VendorRiskSignalExtractor` (`src/Concelier/__Libraries/StellaOps.Concelier.Core/Risk/VendorRiskSignalExtractor.cs`) - extracts risk signals from vendor advisory data
|
||||
- **Interfaces**: `IPolicyStudioSignalPicker`
|
||||
- **Source**: Sprint 0114-0115 (batch_14/file_15-16.md)
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Provide an advisory with vendor risk data and verify `PolicyStudioSignalPicker` extracts the correct signals
|
||||
- [ ] Verify fix availability signal: advisory with a known fix emits a fix-available signal
|
||||
- [ ] Verify `VendorRiskSignalExtractor` correctly maps vendor-specific fields to standardized risk signals
|
||||
- [ ] Verify signal filtering: configure the picker to exclude certain signal types and confirm they are omitted
|
||||
@@ -1,25 +0,0 @@
|
||||
# Concelier Tenant Scoping
|
||||
|
||||
## Module
|
||||
Concelier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Tenant-scoped advisory data isolation with scope normalization and capabilities endpoint for multi-tenant Concelier deployments. Not in the known list as a Concelier-specific feature.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/Concelier/__Libraries/StellaOps.Concelier.Core/Tenancy/`
|
||||
- **Key Classes**:
|
||||
- `TenantScopeNormalizer` (`src/Concelier/__Libraries/StellaOps.Concelier.Core/Tenancy/TenantScopeNormalizer.cs`) - normalizes tenant scope identifiers for consistent isolation
|
||||
- `LinkNotMergeTenantCapabilitiesProvider` (`src/Concelier/__Libraries/StellaOps.Concelier.Core/Tenancy/TenantCapabilitiesEndpoint.cs`) - exposes tenant capabilities including LNM support
|
||||
- `TenantScopeException` (`src/Concelier/__Libraries/StellaOps.Concelier.Core/Tenancy/TenantScope.cs`) - exception for tenant scope violations
|
||||
- **Interfaces**: `ITenantCapabilitiesProvider`
|
||||
- **Source**: Sprint 0115 (batch_14/file_16.md)
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Create advisories under tenant A and verify they are not visible to tenant B
|
||||
- [ ] Verify `TenantScopeNormalizer` normalizes different scope formats to a canonical form
|
||||
- [ ] Verify capabilities endpoint: query tenant capabilities and confirm LNM feature availability is reported
|
||||
- [ ] Verify scope violation: attempt cross-tenant access and confirm `TenantScopeException` is thrown
|
||||
@@ -1,24 +0,0 @@
|
||||
# Concelier Vendor Risk Signal Provider
|
||||
|
||||
## Module
|
||||
Concelier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Extracts vendor-specific risk signals from advisory data, emits fix availability events, and tracks advisory field changes for risk scoring. Not in the known list.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/Concelier/__Libraries/StellaOps.Concelier.Core/Risk/`
|
||||
- **Key Classes**:
|
||||
- `VendorRiskSignalExtractor` (`src/Concelier/__Libraries/StellaOps.Concelier.Core/Risk/VendorRiskSignalExtractor.cs`) - extracts vendor-specific risk signals (CVSS, exploit maturity, fix availability) from advisory data
|
||||
- `PolicyStudioSignalPicker` (`src/Concelier/__Libraries/StellaOps.Concelier.Core/Risk/PolicyStudio/PolicyStudioSignalPicker.cs`) - filters and selects signals for policy evaluation
|
||||
- **Interfaces**: `IPolicyStudioSignalPicker`
|
||||
- **Source**: Sprint 0115 (batch_14/file_16.md)
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Provide a vendor advisory with CVSS and fix availability and verify `VendorRiskSignalExtractor` produces correct risk signals
|
||||
- [ ] Verify fix availability emission: advisory with a fix emits a fix-available signal event
|
||||
- [ ] Verify field change tracking: update an advisory field and verify the risk signal reflects the change
|
||||
- [ ] Verify signal extraction handles missing fields gracefully (no CVSS, no fix info)
|
||||
@@ -1,29 +0,0 @@
|
||||
# Deterministic Semantic Merge Hash for Advisory Deduplication
|
||||
|
||||
## Module
|
||||
Concelier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Computes identity-based semantic hash from (CVE + PURL/CPE + version-range + CWE + patch_lineage) for cross-distro advisory deduplication. Includes normalizers (PURL, CPE, version range, CWE, patch lineage), golden corpus validation (Debian/RHEL/SUSE/Alpine), fuzzing tests (1000 random inputs), shadow-write migration mode, and backfill service. Distinct from "Advisory Ingestion with Canonical Deduplication" which is the overall dedup concept; this is the specific merge_hash identity algorithm.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/Concelier/__Libraries/StellaOps.Concelier.Merge/Identity/`, `src/Concelier/__Libraries/StellaOps.Concelier.Merge/Services/`, `src/Concelier/__Libraries/StellaOps.Concelier.Merge/Jobs/`
|
||||
- **Key Classes**:
|
||||
- `MergeHashCalculator` (`src/Concelier/__Libraries/StellaOps.Concelier.Merge/Identity/MergeHashCalculator.cs`) - computes deterministic semantic hash from (CVE + PURL/CPE + version-range + CWE + patch_lineage) with input normalizers
|
||||
- `MergeHashShadowWriteService` (`src/Concelier/__Libraries/StellaOps.Concelier.Merge/Identity/MergeHashShadowWriteService.cs`) - shadow-write mode for migration validation
|
||||
- `MergeHashBackfillService` (`src/Concelier/__Libraries/StellaOps.Concelier.Merge/Services/MergeHashBackfillService.cs`) - retroactive backfill of merge hashes for existing advisories
|
||||
- `MergeHashBackfillJob` (`src/Concelier/__Libraries/StellaOps.Concelier.Merge/Jobs/MergeHashBackfillJob.cs`) - scheduled `IJob` for backfill execution
|
||||
- **Interfaces**: `IMergeHashCalculator`
|
||||
- **Source**: SPRINT_8200_0012_0001_CONCEL_merge_hash_library.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Compute merge hash for two semantically identical advisories from different sources (e.g., Debian and RHEL for same CVE) and verify identical hash output
|
||||
- [ ] Verify PURL normalization: different PURL formats for the same package produce the same merge hash
|
||||
- [ ] Verify CPE normalization: equivalent CPE strings produce identical hashes
|
||||
- [ ] Verify determinism: same input produces the same hash across 1000 repeated computations
|
||||
- [ ] Verify golden corpus: validate merge hash against the golden corpus of known Debian/RHEL/SUSE/Alpine advisories
|
||||
- [ ] Verify shadow-write mode: enable shadow writes and confirm both old and new hashes are persisted for comparison
|
||||
- [ ] Verify backfill: run `MergeHashBackfillJob` and confirm pre-existing advisories receive computed merge hashes
|
||||
@@ -1,30 +0,0 @@
|
||||
# Distro Connectors (Alpine, Debian, RedHat, SUSE, Ubuntu)
|
||||
|
||||
## Module
|
||||
Concelier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
All major distro connectors for vulnerability feed ingestion (Alpine secdb, Debian security tracker, RHEL errata, SUSE advisories, Ubuntu USN).
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/Concelier/__Libraries/StellaOps.Concelier.Connector.Distro.*/`
|
||||
- **Key Classes**:
|
||||
- `AlpineConnector` + `AlpineConnectorPlugin` (`src/Concelier/__Libraries/StellaOps.Concelier.Connector.Distro.Alpine/`) - Alpine secdb feed ingestion
|
||||
- `DebianConnector` + `DebianConnectorPlugin` (`src/Concelier/__Libraries/StellaOps.Concelier.Connector.Distro.Debian/`) - Debian security tracker ingestion
|
||||
- `RedHatConnector` + `RedHatConnectorPlugin` (`src/Concelier/__Libraries/StellaOps.Concelier.Connector.Distro.RedHat/`) - RHEL errata and OVAL ingestion
|
||||
- `SuseConnector` + `SuseConnectorPlugin` (`src/Concelier/__Libraries/StellaOps.Concelier.Connector.Distro.Suse/`) - SUSE advisory ingestion
|
||||
- `UbuntuConnector` + `UbuntuConnectorPlugin` (`src/Concelier/__Libraries/StellaOps.Concelier.Connector.Distro.Ubuntu/`) - Ubuntu USN ingestion
|
||||
- **Interfaces**: `IFeedConnector`, `IConnectorPlugin`
|
||||
- **Orchestration**: `ConnectorRegistrationService` (`src/Concelier/__Libraries/StellaOps.Concelier.Core/Orchestration/ConnectorRegistrationService.cs`)
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Trigger Alpine connector ingestion and verify Alpine secdb advisories are fetched and stored
|
||||
- [ ] Trigger Debian connector ingestion and verify Debian security tracker entries are parsed
|
||||
- [ ] Trigger RedHat connector ingestion and verify RHEL errata are mapped to canonical format
|
||||
- [ ] Trigger SUSE connector ingestion and verify SUSE advisories are stored
|
||||
- [ ] Trigger Ubuntu connector ingestion and verify USN entries are parsed and stored
|
||||
- [ ] Verify all 5 distro connectors are discovered by `ConnectorRegistrationService` at startup
|
||||
@@ -1,27 +0,0 @@
|
||||
# Distro Fix Database with Multi-Provider Ingestion
|
||||
|
||||
## Module
|
||||
Concelier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Comprehensive vulnerability feed ingestion from distro (Alpine, Debian, RHEL, SUSE, Ubuntu) and vendor sources with normalization and merge.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/Concelier/__Libraries/StellaOps.Concelier.BackportProof/`, `src/Concelier/__Libraries/StellaOps.Concelier.Connector.Distro.*/`, `src/Concelier/__Libraries/StellaOps.Concelier.Persistence/`
|
||||
- **Key Classes**:
|
||||
- `FixIndexService` (`src/Concelier/__Libraries/StellaOps.Concelier.BackportProof/Services/FixIndexService.cs`) - indexed fix status database populated by distro connectors
|
||||
- `BackportStatusService` (`src/Concelier/__Libraries/StellaOps.Concelier.BackportProof/Services/BackportStatusService.cs`) - multi-distro backport status resolution
|
||||
- `PostgresAdvisoryStore` (`src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Postgres/Advisories/PostgresAdvisoryStore.cs`) - advisory persistence with multi-provider merge
|
||||
- `PostgresSourceStateAdapter` (`src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Postgres/SourceStateAdapter.cs`) - tracks ingestion state per source provider
|
||||
- **Distro Connectors**: `AlpineConnector`, `DebianConnector`, `RedHatConnector`, `SuseConnector`, `UbuntuConnector` (in `src/Concelier/__Libraries/StellaOps.Concelier.Connector.Distro.*/`)
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Ingest the same CVE from multiple distro providers and verify the fix database contains entries from all providers
|
||||
- [ ] Verify normalization: different distro-specific advisory formats are normalized to a common schema
|
||||
- [ ] Verify merge: advisories from different providers for the same CVE are linked to the same canonical
|
||||
- [ ] Verify `PostgresSourceStateAdapter` tracks per-provider ingestion cursors for incremental sync
|
||||
- [ ] Verify `FixIndexService` is populated with fix entries after distro ingestion completes
|
||||
@@ -1,25 +0,0 @@
|
||||
# EPSS Feed Connector (Concelier Three-Stage Pattern)
|
||||
|
||||
## Module
|
||||
Concelier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Concelier connector for EPSS (Exploit Prediction Scoring System) feed ingestion following three-stage Fetch/Parse/Map pattern. Reuses Scanner's EpssCsvStreamParser for CSV parsing, supports ETag conditional requests, air-gap bundle fallback, priority band classification (Critical/High/Medium/Low at 0.70/0.40/0.10 thresholds), and daily scheduled ingestion (10:00 UTC).
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/Concelier/__Libraries/StellaOps.Concelier.Connector.Epss/`
|
||||
- **Key Classes**:
|
||||
- `EpssConnector` (`src/Concelier/__Libraries/StellaOps.Concelier.Connector.Epss/Internal/EpssConnector.cs`) - `IFeedConnector` implementation with three-stage Fetch/Parse/Map pattern
|
||||
- `EpssConnectorPlugin` (`src/Concelier/__Libraries/StellaOps.Concelier.Connector.Epss/EpssConnectorPlugin.cs`) - `IConnectorPlugin` registration for DI discovery
|
||||
- **Interfaces**: `IFeedConnector`, `IConnectorPlugin`
|
||||
- **Source**: SPRINT_4000_0002_0001_epss_feed_connector.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Trigger EPSS connector ingestion and verify EPSS scores are fetched and stored for CVE IDs
|
||||
- [ ] Verify priority band classification: CVEs with EPSS > 0.70 are classified as Critical, 0.40-0.70 as High, 0.10-0.40 as Medium, < 0.10 as Low
|
||||
- [ ] Verify ETag conditional requests: second ingestion with unchanged data returns 304 and skips re-parsing
|
||||
- [ ] Verify air-gap bundle fallback: configure offline mode and verify ingestion falls back to local bundle
|
||||
- [ ] Verify daily scheduled ingestion runs at the configured time
|
||||
@@ -1,33 +0,0 @@
|
||||
# Feed Snapshot Coordinator
|
||||
|
||||
## Module
|
||||
Concelier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Feed snapshot persistence and retrieval exists (repository, entity model). However, the advisory notes this as TODO (Feed Snapshot Coordinator for cross-platform pinning/coordination is still in progress).
|
||||
|
||||
## What's Implemented
|
||||
- **Persistence**: `FeedSnapshotRepository` (`src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Postgres/Repositories/FeedSnapshotRepository.cs`) - PostgreSQL repository for feed snapshot storage and retrieval
|
||||
- **Entity Model**: `FeedSnapshotEntity` (`src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Postgres/Models/FeedSnapshotEntity.cs`) - database entity for feed snapshots
|
||||
- **API Endpoints**: `FeedSnapshotEndpointExtensions` (`src/Concelier/StellaOps.Concelier.WebService/Extensions/FeedSnapshotEndpointExtensions.cs`) - REST endpoints for snapshot queries
|
||||
- **Options**: `FeedSnapshotOptions` (`src/Concelier/StellaOps.Concelier.WebService/Options/ConcelierOptions.cs`) - configuration for snapshot behavior
|
||||
|
||||
## What's Missing
|
||||
- Feed Snapshot Coordinator service that coordinates cross-platform feed pinning
|
||||
- Snapshot version pinning across multiple Concelier instances (for consistency in federated deployments)
|
||||
- Automatic snapshot rollback on ingestion failure
|
||||
- Snapshot comparison and diff reporting
|
||||
|
||||
## Implementation Plan
|
||||
- Create `FeedSnapshotCoordinator` service in `src/Concelier/__Libraries/StellaOps.Concelier.Core/` or `Federation/`
|
||||
- Implement cross-instance snapshot pinning using the `SyncLedgerRepository` for coordination
|
||||
- Add automatic rollback on ingestion failure to return to last-known-good snapshot
|
||||
- Add snapshot diff reporting for audit and troubleshooting
|
||||
- Add tests for coordinator logic with multi-instance scenarios
|
||||
|
||||
## Related Documentation
|
||||
- Persistence: `src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Postgres/Repositories/FeedSnapshotRepository.cs`
|
||||
- API: `src/Concelier/StellaOps.Concelier.WebService/Extensions/FeedSnapshotEndpointExtensions.cs`
|
||||
@@ -1,25 +0,0 @@
|
||||
# Full SBOM Extraction with Enriched ParsedSbom Model
|
||||
|
||||
## Module
|
||||
Concelier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Upgraded SBOM parser that extracts ALL fields from CycloneDX 1.7 and SPDX 3.0.1 (not just PURL/CPE). The enriched ParsedSbom model carries full SBOM data including services, crypto properties, ML model metadata, build/formulation info, compositions, vulnerabilities, and dependencies for downstream consumers (Scanner, Policy, etc.).
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/Concelier/__Libraries/StellaOps.Concelier.SbomIntegration/`
|
||||
- **Key Classes**:
|
||||
- `ParsedSbomParser` (`src/Concelier/__Libraries/StellaOps.Concelier.SbomIntegration/Parsing/ParsedSbomParser.cs`) - full SBOM extraction from CycloneDX 1.7 and SPDX 3.0.1 with enriched model
|
||||
- `SbomAdvisoryMatcher` (`src/Concelier/__Libraries/StellaOps.Concelier.SbomIntegration/Matching/SbomAdvisoryMatcher.cs`) - matches SBOM components against advisories
|
||||
- **Interfaces**: `IParsedSbomParser`, `ISbomAdvisoryMatcher`
|
||||
- **Source**: SPRINT_20260119_015_Concelier_sbom_full_extraction.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Parse a CycloneDX 1.7 SBOM and verify all fields are extracted (components, services, compositions, vulnerabilities, dependencies)
|
||||
- [ ] Parse an SPDX 3.0.1 SBOM and verify enriched model includes packages, relationships, and annotations
|
||||
- [ ] Verify crypto properties extraction: SBOM with crypto components has crypto metadata in the ParsedSbom model
|
||||
- [ ] Verify ML model metadata: SBOM with ML model components has model metadata extracted
|
||||
- [ ] Verify downstream consumption: pass ParsedSbom to `SbomAdvisoryMatcher` and verify advisory matching works with enriched fields
|
||||
@@ -1,29 +0,0 @@
|
||||
# Ingestion Telemetry and Orchestration
|
||||
|
||||
## Module
|
||||
Concelier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Telemetry instrumentation for ingestion pipeline with OpenTelemetry metrics and orchestration registry for connector management.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/Concelier/__Libraries/StellaOps.Concelier.Core/Orchestration/`, `src/Concelier/StellaOps.Concelier.WebService/Diagnostics/`
|
||||
- **Key Classes**:
|
||||
- `ConnectorWorker` (`src/Concelier/__Libraries/StellaOps.Concelier.Core/Orchestration/ConnectorWorker.cs`) - orchestrates connector ingestion cycles with telemetry hooks
|
||||
- `ConnectorWorkerFactory` (`src/Concelier/__Libraries/StellaOps.Concelier.Core/Orchestration/ConnectorWorker.cs`) - factory for creating connector worker instances
|
||||
- `ConnectorRegistrationService` (`src/Concelier/__Libraries/StellaOps.Concelier.Core/Orchestration/ConnectorRegistrationService.cs`) - connector discovery and registration
|
||||
- `ConnectorMetadata` (`src/Concelier/__Libraries/StellaOps.Concelier.Core/Orchestration/ConnectorMetadata.cs`) - metadata model for registered connectors
|
||||
- `IngestionMetrics` (`src/Concelier/StellaOps.Concelier.WebService/Diagnostics/IngestionMetrics.cs`) - OpenTelemetry metrics for ingestion operations
|
||||
- **Interfaces**: `IConnectorWorker`, `IConnectorWorkerFactory`, `IConnectorRegistrationService`
|
||||
- **Registration**: `OrchestrationServiceCollectionExtensions` (`src/Concelier/__Libraries/StellaOps.Concelier.Core/Orchestration/OrchestrationServiceCollectionExtensions.cs`)
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Start the Concelier web service and verify all registered connectors appear in `ConnectorRegistrationService`
|
||||
- [ ] Trigger a connector ingestion cycle and verify `IngestionMetrics` emits advisory count, duration, and error metrics
|
||||
- [ ] Verify `ConnectorWorkerFactory` creates workers with correct connector metadata
|
||||
- [ ] Verify orchestration: trigger multiple connectors and verify they execute according to their configured schedules
|
||||
- [ ] Verify OpenTelemetry export: confirm ingestion metrics are visible in the configured OTel collector
|
||||
@@ -1,29 +0,0 @@
|
||||
# Link-Not-Merge Advisory Architecture
|
||||
|
||||
## Module
|
||||
Concelier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Advisory confirmed that existing Link-Not-Merge model is architecturally superior to proposed Unified Advisory Schema (UAS). Preserves conflict evidence and 3-component trust vector.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/Concelier/__Libraries/StellaOps.Concelier.Core/Linksets/`, `src/Concelier/__Libraries/StellaOps.Concelier.Core/Tenancy/`, `src/Concelier/__Libraries/StellaOps.Concelier.Merge/`
|
||||
- **Key Classes**:
|
||||
- `LinksetCorrelationService` (`src/Concelier/__Libraries/StellaOps.Concelier.Core/Linksets/LinksetCorrelationService.cs`) - correlates advisory linksets preserving source identity
|
||||
- `LinksetCorrelationV2` (`src/Concelier/__Libraries/StellaOps.Concelier.Core/Linksets/LinksetCorrelationV2.cs`) - V2 correlation algorithm with improved accuracy
|
||||
- `LinksetCorrelation` (`src/Concelier/__Libraries/StellaOps.Concelier.Core/Linksets/LinksetCorrelation.cs`) - V1 correlation logic
|
||||
- `LinkNotMergeTenantCapabilitiesProvider` (`src/Concelier/__Libraries/StellaOps.Concelier.Core/Tenancy/TenantCapabilitiesEndpoint.cs`) - tenant capabilities for LNM feature
|
||||
- `MergeHashCalculator` (`src/Concelier/__Libraries/StellaOps.Concelier.Merge/Identity/MergeHashCalculator.cs`) - merge hash for linking semantically equivalent advisories
|
||||
- `CanonicalAdvisoryService` (`src/Concelier/__Libraries/StellaOps.Concelier.Core/Canonical/CanonicalAdvisoryService.cs`) - canonical advisory with linked source edges
|
||||
- **Interfaces**: `ILinksetCorrelationService`, `ITenantCapabilitiesProvider`
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Ingest two advisories from different sources for the same CVE and verify they are linked (not merged) with separate source identities preserved
|
||||
- [ ] Verify conflict evidence: ingest conflicting advisories (different CVSS scores for same CVE) and confirm both values are preserved in the linkset
|
||||
- [ ] Verify 3-component trust vector: query a linked advisory and confirm trust scores from each source are available
|
||||
- [ ] Verify `LinksetCorrelationService` returns all linked sources for a given canonical advisory
|
||||
- [ ] Verify tenant capabilities: confirm LNM feature is reported as available via the capabilities endpoint
|
||||
@@ -1,25 +0,0 @@
|
||||
# Linkset Correlation V2 Algorithm
|
||||
|
||||
## Module
|
||||
Concelier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
V2 linkset correlation algorithm with graph connectivity scoring, pairwise PURL coverage scoring, typed conflict severities, and reference conflict logic fixes. Has dedicated tests.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/Concelier/__Libraries/StellaOps.Concelier.Core/Linksets/`
|
||||
- **Key Classes**:
|
||||
- `LinksetCorrelationV2` (`src/Concelier/__Libraries/StellaOps.Concelier.Core/Linksets/LinksetCorrelationV2.cs`) - V2 algorithm with graph connectivity scoring and pairwise PURL coverage
|
||||
- `LinksetCorrelation` (`src/Concelier/__Libraries/StellaOps.Concelier.Core/Linksets/LinksetCorrelation.cs`) - V1 correlation for comparison
|
||||
- `LinksetCorrelationService` (`src/Concelier/__Libraries/StellaOps.Concelier.Core/Linksets/LinksetCorrelationService.cs`) - service layer selecting V1 or V2 algorithm
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Correlate a linkset with multiple overlapping advisories and verify the V2 algorithm produces correct graph connectivity scores
|
||||
- [ ] Verify pairwise PURL coverage: two advisories covering the same PURLs score higher than non-overlapping ones
|
||||
- [ ] Verify typed conflict severities: conflicting CVSS scores produce appropriately typed severity levels
|
||||
- [ ] Verify reference conflict logic: conflicting reference URLs are handled without errors
|
||||
- [ ] Compare V1 vs V2 results: run both algorithms on the same input and verify V2 produces improved correlation accuracy
|
||||
@@ -1,27 +0,0 @@
|
||||
# Plugin System with DI, Signing, and Version Attributes
|
||||
|
||||
## Module
|
||||
Concelier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Plugin architecture using IDependencyInjectionRoutine and ServiceBinding attributes for dependency injection, with isolated AssemblyLoadContext loading. Cosign signature verification and StellaPluginVersion attributes are defined.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/Concelier/StellaOps.Concelier.Plugin.Unified/`, `src/Concelier/__Libraries/StellaOps.Concelier.Core/Orchestration/`
|
||||
- **Key Classes**:
|
||||
- `FeedPluginAdapterFactory` (`src/Concelier/StellaOps.Concelier.Plugin.Unified/FeedPluginAdapterFactory.cs`) - factory creating plugin adapters from `IConnectorPlugin` implementations
|
||||
- `FeedPluginAdapter` (`src/Concelier/StellaOps.Concelier.Plugin.Unified/FeedPluginAdapter.cs`) - unified adapter wrapping plugin connectors
|
||||
- `ConnectorRegistrationService` (`src/Concelier/__Libraries/StellaOps.Concelier.Core/Orchestration/ConnectorRegistrationService.cs`) - DI-based plugin discovery and registration
|
||||
- Each connector has an `IConnectorPlugin` implementation (e.g., `NvdConnectorPlugin`, `GhsaConnectorPlugin`, `VmwareConnectorPlugin`, etc.)
|
||||
- **Interfaces**: `IConnectorPlugin`, `IFeedConnector`, `IConnectorRegistrationService`
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify plugin discovery: all `IConnectorPlugin` implementations are found via DI at startup
|
||||
- [ ] Verify `FeedPluginAdapterFactory` creates adapters for each discovered plugin
|
||||
- [ ] Verify isolated loading: plugin assemblies load in isolated `AssemblyLoadContext` without leaking into the host
|
||||
- [ ] Verify version attributes: query a loaded plugin and confirm `StellaPluginVersion` metadata is accessible
|
||||
- [ ] Verify registration service: `ConnectorRegistrationService` exposes metadata for all registered plugins
|
||||
@@ -1,28 +0,0 @@
|
||||
# PostgreSQL as System of Record (with JSONB)
|
||||
|
||||
## Module
|
||||
Concelier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
PostgreSQL is universally adopted as the system of record across all persistence-bearing modules via Npgsql/NpgsqlDataSource.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/Concelier/__Libraries/StellaOps.Concelier.Persistence/`
|
||||
- **Key Classes**:
|
||||
- `ConcelierDataSource` (`src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Postgres/ConcelierDataSource.cs`) - NpgsqlDataSource wrapper for Concelier
|
||||
- `ConcelierDbContext` (`src/Concelier/__Libraries/StellaOps.Concelier.Persistence/EfCore/Context/ConcelierDbContext.cs`) - EF Core context for Concelier tables
|
||||
- `PostgresDocumentStore` (`src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Postgres/DocumentStore.cs`) - JSONB document store for advisory data
|
||||
- `PostgresAdvisoryStore` (`src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Postgres/Advisories/PostgresAdvisoryStore.cs`) - advisory persistence via Npgsql
|
||||
- `PostgresSourceStateAdapter` (`src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Postgres/SourceStateAdapter.cs`) - source state tracking via Npgsql
|
||||
- **Interfaces**: `IDocumentStore`, `IAdvisoryStore`, `ISourceStateStore`, `IStorageDocumentStore`
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify Concelier connects to PostgreSQL via `ConcelierDataSource` and can read/write advisories
|
||||
- [ ] Verify JSONB storage: store a canonical advisory with nested JSON and retrieve it with full fidelity
|
||||
- [ ] Verify `PostgresDocumentStore` supports document-level operations (get, put, delete)
|
||||
- [ ] Verify EF Core context: `ConcelierDbContext` migrations apply cleanly on a fresh PostgreSQL instance
|
||||
- [ ] Verify connection pooling: multiple concurrent requests share NpgsqlDataSource connections efficiently
|
||||
@@ -1,32 +0,0 @@
|
||||
# PostgreSQL Storage Layer (Proof Evidence Repositories)
|
||||
|
||||
## Module
|
||||
Concelier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Three PostgreSQL repository implementations backed by Dapper/Npgsql. Database schema defines 6 tables across 3 schemas (vuln: distro_advisories, changelog_evidence, patch_evidence, patch_signatures; feedser: binary_fingerprints; attestor: proof_blobs) with 18 indices including GIN indices for CVE array queries and composite indices for CVE+package lookups.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Postgres/`
|
||||
- **Key Classes**:
|
||||
- `AdvisoryRepository` (`src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Postgres/Repositories/AdvisoryRepository.cs`) - raw advisory CRUD with GIN index support
|
||||
- `AdvisoryCanonicalRepository` (`src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Postgres/Repositories/AdvisoryCanonicalRepository.cs`) - canonical advisory persistence
|
||||
- `PostgresDtoStore` (`src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Postgres/Repositories/PostgresDtoStore.cs`) - DTO storage layer
|
||||
- `PostgresChangeHistoryStore` (`src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Postgres/Repositories/PostgresChangeHistoryStore.cs`) - advisory change history tracking
|
||||
- `PostgresPsirtFlagStore` (`src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Postgres/Repositories/PostgresPsirtFlagStore.cs`) - PSIRT flag persistence
|
||||
- `PostgresJpFlagStore` (`src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Postgres/Repositories/PostgresJpFlagStore.cs`) - JP flag persistence
|
||||
- `InterestScoreRepository` (`src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Postgres/Repositories/InterestScoreRepository.cs`) - interest score persistence
|
||||
- `FeedSnapshotRepository` (`src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Postgres/Repositories/FeedSnapshotRepository.cs`) - feed snapshot persistence
|
||||
- `SyncLedgerRepository` (`src/Concelier/__Libraries/StellaOps.Concelier.Persistence/Postgres/Repositories/SyncLedgerRepository.cs`) - federation sync ledger
|
||||
- **Interfaces**: `IAdvisoryRepository`, `IAdvisoryCanonicalRepository`, `IDtoStore`, `IChangeHistoryStore`
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify CVE array query: insert advisories with multiple CVE IDs and query using GIN index-backed CVE array search
|
||||
- [ ] Verify composite index: query by CVE+package combination and confirm efficient lookup
|
||||
- [ ] Verify change history: update an advisory and confirm `PostgresChangeHistoryStore` records the change
|
||||
- [ ] Verify all 6 tables are created during schema migration across the 3 schemas (vuln, feedser, attestor)
|
||||
- [ ] Verify `SyncLedgerRepository` persists and retrieves federation sync cursors
|
||||
@@ -1,27 +0,0 @@
|
||||
# SBOM-Advisory Intersection Matching and Learning
|
||||
|
||||
## Module
|
||||
Concelier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
SBOM registration and learning system that finds which canonical advisories affect an organization's components. Matches by PURL and CPE, triggers interest score updates, and supports incremental delta SBOM matching. Provides POST /api/v1/learn/sbom endpoint and auto-learning from scan events.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/Concelier/__Libraries/StellaOps.Concelier.SbomIntegration/`, `src/Concelier/__Libraries/StellaOps.Concelier.Interest/`
|
||||
- **Key Classes**:
|
||||
- `SbomAdvisoryMatcher` (`src/Concelier/__Libraries/StellaOps.Concelier.SbomIntegration/Matching/SbomAdvisoryMatcher.cs`) - matches SBOM components against canonical advisories by PURL and CPE
|
||||
- `ParsedSbomParser` (`src/Concelier/__Libraries/StellaOps.Concelier.SbomIntegration/Parsing/ParsedSbomParser.cs`) - parses SBOMs for component extraction
|
||||
- `InterestScoringService` (`src/Concelier/__Libraries/StellaOps.Concelier.Interest/InterestScoringService.cs`) - triggered to update interest scores after SBOM matching
|
||||
- `InterestScoreCalculator` (`src/Concelier/__Libraries/StellaOps.Concelier.Interest/InterestScoreCalculator.cs`) - recalculates interest based on SBOM intersection
|
||||
- **Interfaces**: `ISbomAdvisoryMatcher`, `IParsedSbomParser`, `IInterestScoringService`
|
||||
- **Source**: SPRINT_8200_0013_0003_SCAN_sbom_intersection_scoring.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Submit an SBOM via the learn endpoint and verify advisories affecting its components are identified
|
||||
- [ ] Verify PURL matching: SBOM with a component matching an advisory PURL produces a match
|
||||
- [ ] Verify CPE matching: SBOM with a component matching an advisory CPE produces a match
|
||||
- [ ] Verify interest score update: after SBOM learning, affected advisories have their interest scores recalculated
|
||||
- [ ] Verify incremental delta: submit an updated SBOM with new components and verify only the delta is processed
|
||||
@@ -1,26 +0,0 @@
|
||||
# Source Intelligence Parsing (Changelog + Patch Header)
|
||||
|
||||
## Module
|
||||
Concelier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Source intelligence parsing for Tier 2 and Tier 3 evidence collection. Includes changelog parsing (debian/changelog, RPM changelog), patch header parsing, and integration with upstream advisory sources (Debian Security Tracker, Red Hat Errata).
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/Concelier/__Libraries/StellaOps.Concelier.BackportProof/`, `src/Concelier/__Libraries/StellaOps.Concelier.Connector.Distro.*/`
|
||||
- **Key Classes**:
|
||||
- `BackportEvidenceResolver` (`src/Concelier/__Libraries/StellaOps.Concelier.Merge/Backport/BackportEvidenceResolver.cs`) - resolves backport evidence from changelog and patch header sources
|
||||
- `BackportStatusService` (`src/Concelier/__Libraries/StellaOps.Concelier.BackportProof/Services/BackportStatusService.cs`) - backport status determination from parsed source intelligence
|
||||
- `DebianConnector` (`src/Concelier/__Libraries/StellaOps.Concelier.Connector.Distro.Debian/DebianConnector.cs`) - ingests Debian Security Tracker data
|
||||
- `RedHatConnector` (`src/Concelier/__Libraries/StellaOps.Concelier.Connector.Distro.RedHat/RedHatConnector.cs`) - ingests Red Hat Errata data
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Parse a debian/changelog file and verify CVE fix entries are correctly extracted as Tier 2 evidence
|
||||
- [ ] Parse an RPM changelog and verify patch entries are extracted
|
||||
- [ ] Parse patch headers and verify commit references and CVE links are extracted as Tier 3 evidence
|
||||
- [ ] Verify integration: Debian Security Tracker data feeds into `BackportEvidenceResolver` for backport verdict
|
||||
- [ ] Verify Red Hat Errata integration: errata data provides evidence for backport status determination
|
||||
@@ -1,27 +0,0 @@
|
||||
# Valkey Advisory Cache Service
|
||||
|
||||
## Module
|
||||
Concelier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Valkey (Redis-compatible) caching layer for canonical advisories with TTL policies based on interest score, PURL index lookups, hot set ranking, and p99 < 20ms read target. Includes cache warmup, metrics, and fallback mode.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/Concelier/__Libraries/StellaOps.Concelier.Cache.Valkey/`
|
||||
- **Key Classes**:
|
||||
- `ValkeyAdvisoryCacheService` (`src/Concelier/__Libraries/StellaOps.Concelier.Cache.Valkey/ValkeyAdvisoryCacheService.cs`) - Valkey-backed cache with TTL policies, PURL index, and hot set ranking
|
||||
- `AdvisoryCacheKeys` (`src/Concelier/__Libraries/StellaOps.Concelier.Cache.Valkey/AdvisoryCacheKeys.cs`) - deterministic cache key generation for advisory lookups
|
||||
- `CachingCanonicalAdvisoryService` (`src/Concelier/__Libraries/StellaOps.Concelier.Core/Canonical/CachingCanonicalAdvisoryService.cs`) - caching decorator wrapping the canonical advisory service
|
||||
- **Interfaces**: `IAdvisoryCacheService`
|
||||
- **Source**: SPRINT_8200_0013_0001_GW_valkey_advisory_cache.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Store a canonical advisory in Valkey and retrieve it, verifying p99 read latency is < 20ms
|
||||
- [ ] Verify TTL policy: high-interest advisories have longer TTLs than low-interest ones
|
||||
- [ ] Verify PURL index lookup: query by PURL and verify matching advisories are returned from cache
|
||||
- [ ] Verify hot set ranking: frequently accessed advisories are promoted in the hot set
|
||||
- [ ] Verify cache warmup: on startup, verify high-interest advisories are pre-loaded into cache
|
||||
- [ ] Verify fallback mode: disable Valkey and confirm the service falls back to direct PostgreSQL queries
|
||||
@@ -1,28 +0,0 @@
|
||||
# VEX conflict resolution (side-by-side merge with provenance)
|
||||
|
||||
## Module
|
||||
Concelier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
VEX conflict resolver and consensus engine merge statements from multiple sources with rationale models explaining merge outcomes.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/Concelier/__Libraries/StellaOps.Concelier.SbomIntegration/Vex/`
|
||||
- **Key Classes**:
|
||||
- `VexConflictResolver` (`src/Concelier/__Libraries/StellaOps.Concelier.SbomIntegration/Vex/VexConflictResolver.cs`) - resolves conflicts between VEX statements from multiple sources with provenance-based precedence
|
||||
- `VexConsumptionReporter` (`src/Concelier/__Libraries/StellaOps.Concelier.SbomIntegration/Vex/VexConsumptionReporter.cs`) - reports VEX consumption outcomes and merge rationale
|
||||
- `VexConsumptionPolicyLoader` (`src/Concelier/__Libraries/StellaOps.Concelier.SbomIntegration/Vex/VexConsumptionPolicyLoader.cs`) - loads VEX consumption policies defining merge rules
|
||||
- `VexConsumptionPolicyDefaults` (`src/Concelier/__Libraries/StellaOps.Concelier.SbomIntegration/Vex/VexConsumptionPolicy.cs`) - default merge policy configuration
|
||||
- `VexConsumptionOptions` (`src/Concelier/__Libraries/StellaOps.Concelier.SbomIntegration/Vex/VexConsumptionOptions.cs`) - options for VEX consumption behavior
|
||||
- **Interfaces**: `IVexConflictResolver`, `IVexConsumptionReporter`, `IVexConsumptionPolicyLoader`
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Submit two conflicting VEX statements (affected vs not_affected) for the same CVE+product and verify the resolver produces a merged outcome with rationale
|
||||
- [ ] Verify provenance-based precedence: vendor VEX statement takes precedence over community source
|
||||
- [ ] Verify `VexConsumptionReporter` emits a report explaining why one statement won over another
|
||||
- [ ] Verify policy-based resolution: load a custom merge policy and confirm it changes the resolution outcome
|
||||
- [ ] Verify side-by-side preservation: both original statements remain accessible after merge
|
||||
@@ -1,28 +0,0 @@
|
||||
# VEX Consumption from SBOM Documents (Embedded VEX Extraction)
|
||||
|
||||
## Module
|
||||
Concelier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Extracts embedded VEX statements from CycloneDX and SPDX SBOMs, evaluates per-statement trust based on source provenance and evidence quality, resolves conflicts when multiple VEX sources disagree, and generates consumption reports. This is distinct from the known "VEX Multi-Source Consensus Engine" which merges standalone VEX documents; this feature specifically processes VEX embedded within SBOM documents.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/Concelier/__Libraries/StellaOps.Concelier.SbomIntegration/Vex/`, `src/Concelier/__Libraries/StellaOps.Concelier.SbomIntegration/Parsing/`
|
||||
- **Key Classes**:
|
||||
- `VexConsumptionReporter` (`src/Concelier/__Libraries/StellaOps.Concelier.SbomIntegration/Vex/VexConsumptionReporter.cs`) - generates consumption reports from extracted VEX statements
|
||||
- `VexConsumptionPolicyLoader` (`src/Concelier/__Libraries/StellaOps.Concelier.SbomIntegration/Vex/VexConsumptionPolicyLoader.cs`) - loads trust and precedence policies for VEX evaluation
|
||||
- `VexConflictResolver` (`src/Concelier/__Libraries/StellaOps.Concelier.SbomIntegration/Vex/VexConflictResolver.cs`) - resolves conflicts between embedded VEX statements
|
||||
- `VexConsumptionOptions` (`src/Concelier/__Libraries/StellaOps.Concelier.SbomIntegration/Vex/VexConsumptionOptions.cs`) - configuration for VEX consumption behavior
|
||||
- `ParsedSbomParser` (`src/Concelier/__Libraries/StellaOps.Concelier.SbomIntegration/Parsing/ParsedSbomParser.cs`) - extracts embedded VEX from CycloneDX and SPDX SBOMs
|
||||
- **Interfaces**: `IVexConsumptionReporter`, `IVexConsumptionPolicyLoader`, `IVexConflictResolver`
|
||||
- **Source**: SPRINT_20260119_020_Concelier_vex_consumption.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Parse a CycloneDX SBOM with embedded VEX statements and verify all VEX entries are extracted
|
||||
- [ ] Parse an SPDX SBOM with embedded VEX and verify extraction works across formats
|
||||
- [ ] Verify per-statement trust evaluation: VEX from a vendor SBOM receives higher trust than from a third-party
|
||||
- [ ] Verify conflict resolution: two embedded VEX statements with conflicting status for the same CVE are resolved with rationale
|
||||
- [ ] Verify consumption report: `VexConsumptionReporter` generates a report listing all consumed VEX statements with trust scores
|
||||
@@ -1,29 +0,0 @@
|
||||
# VEX Distribution Network (Moat Score 3-4)
|
||||
|
||||
## Module
|
||||
Concelier
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
32 advisory connectors covering national CERTs, distro security trackers, vendor advisories, ICS sources, and general vulnerability databases.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/Concelier/__Libraries/StellaOps.Concelier.Connector.*/`, `src/Concelier/__Connectors/`
|
||||
- **Key Connectors** (32 total, each implementing `IFeedConnector` + `IConnectorPlugin`):
|
||||
- **National CERTs**: `CertBundConnector` (Germany), `CertFrConnector` (France), `CertCcConnector` (US), `CertInConnector` (India), `CccsConnector` (Canada), `AcscConnector` (Australia), `KisaConnector` (Korea), `JvnConnector` (Japan), `RuBduConnector` (Russia BDU), `RuNkckiConnector` (Russia NKCKI)
|
||||
- **General Vulnerability DBs**: `NvdConnector`, `OsvConnector`, `GhsaConnector`, `CveConnector`, `KevConnector`, `EpssConnector`
|
||||
- **Distro Security Trackers**: `AlpineConnector`, `DebianConnector`, `RedHatConnector`, `SuseConnector`, `UbuntuConnector`
|
||||
- **Vendor Advisories**: `CiscoConnector`, `VmwareConnector`, `OracleConnector`, `MsrcConnector`, `AppleConnector`, `ChromiumConnector`, `AdobeConnector`
|
||||
- **ICS Sources**: `IcsCisaConnector`, `KasperskyConnector`
|
||||
- **Regional/Special**: `AstraConnector`, `StellaOpsMirrorConnector`
|
||||
- **Orchestration**: `ConnectorRegistrationService`, `ConnectorWorker` (`src/Concelier/__Libraries/StellaOps.Concelier.Core/Orchestration/`)
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify all 32 connectors are discovered and registered by `ConnectorRegistrationService` at startup
|
||||
- [ ] Trigger ingestion for at least one connector from each category (national CERT, general DB, distro, vendor, ICS) and verify advisories are stored
|
||||
- [ ] Verify connector count: query the registration service and confirm 32 connectors are registered
|
||||
- [ ] Verify scheduled ingestion: confirm connectors run on their configured schedules without manual intervention
|
||||
- [ ] Verify air-gap support: configure a connector in offline mode and verify it falls back to local bundle
|
||||
@@ -1,33 +0,0 @@
|
||||
# AI Code Guard (Secrets Scanning + Attribution Check + License Hygiene)
|
||||
|
||||
## Module
|
||||
Integrations
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
AI Code Guard has policy signal binding and annotation services. Evidence provider interfaces and annotation contracts exist. The advisory's proposed `stella guard run` CLI and full YAML-driven pipeline checks are partially represented through policy signal binding rather than a standalone CLI tool.
|
||||
|
||||
## What's Implemented
|
||||
- **AI Code Guard annotation contracts**: `src/Integrations/__Libraries/StellaOps.Integrations.Contracts/AiCodeGuardAnnotationContracts.cs` -- annotation DTOs for AI code guard findings
|
||||
- **AI Code Guard annotation service**: `src/Integrations/__Libraries/StellaOps.Integrations.Services/AiCodeGuard/AiCodeGuardAnnotationService.cs` -- annotation generation service
|
||||
- **Tests**: `src/Integrations/__Libraries/__Tests/StellaOps.Integrations.Services.Tests/AiCodeGuard/AiCodeGuardAnnotationServiceTests.cs`
|
||||
- Policy signal binding exists in `src/Policy/` for AI code guard policy evaluation
|
||||
- Source: Feature matrix scan
|
||||
|
||||
## What's Missing
|
||||
- `stella guard run` CLI command for standalone execution
|
||||
- YAML-driven pipeline check configuration
|
||||
- Full secrets scanning engine (currently annotation-only)
|
||||
- Attribution check automation
|
||||
- License hygiene scanning and enforcement
|
||||
|
||||
## Implementation Plan
|
||||
- Add CLI command wrapping AI Code Guard annotation service
|
||||
- Implement YAML-driven check configuration loader
|
||||
- Build secrets scanning and attribution check engines
|
||||
- Integrate license hygiene with SBOM/licensing data
|
||||
|
||||
## Related Documentation
|
||||
- Source: See feature catalog
|
||||
@@ -1,30 +0,0 @@
|
||||
# Built-in Container Registry Connectors (Docker Hub, Harbor, ACR, ECR, GCR, Generic OCI)
|
||||
|
||||
## Module
|
||||
Integrations
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Six container registry connectors implemented using raw HTTP clients (no cloud SDKs): Docker Hub with rate limiting, Harbor for self-hosted, ACR with Azure AD token exchange, ECR with AWS SigV4, GCR with JWT/OAuth2, and Generic OCI for any compliant registry. All resolve tags to digests.
|
||||
|
||||
## Implementation Details
|
||||
- **Plugin interface**: `src/Integrations/__Libraries/StellaOps.Integrations.Contracts/IIntegrationConnectorPlugin.cs` -- connector plugin contract
|
||||
- **Harbor connector**: `src/Integrations/__Plugins/StellaOps.Integrations.Plugin.Harbor/HarborConnectorPlugin.cs` -- Harbor self-hosted registry connector
|
||||
- **Integration models**: `src/Integrations/__Libraries/StellaOps.Integrations.Core/IntegrationModels.cs` -- registry connection models
|
||||
- **Integration enums**: `src/Integrations/__Libraries/StellaOps.Integrations.Core/IntegrationEnums.cs` -- connector type enums (registry types)
|
||||
- **Integration core**: `src/Integrations/__Libraries/StellaOps.Integrations.Core/Integration.cs` -- base integration with Vault-type references
|
||||
- **Plugin loader**: `src/Integrations/StellaOps.Integrations.WebService/IntegrationPluginLoader.cs` -- dynamic plugin loading
|
||||
- **Integration service**: `src/Integrations/StellaOps.Integrations.WebService/IntegrationService.cs` -- integration lifecycle management
|
||||
- **Persistence**: `src/Integrations/__Libraries/StellaOps.Integrations.Persistence/PostgresIntegrationRepository.cs`, `IIntegrationRepository.cs`, `IntegrationDbContext.cs`
|
||||
- **In-memory connector**: `src/Integrations/__Plugins/StellaOps.Integrations.Plugin.InMemory/InMemoryConnectorPlugin.cs` -- test connector
|
||||
- **Tests**: `src/Integrations/__Tests/StellaOps.Integrations.Tests/IntegrationServiceTests.cs`, `IntegrationPluginLoaderTests.cs`, `StellaOps.Integrations.Plugin.Tests/InMemoryConnectorPluginTests.cs`
|
||||
- **Source**: SPRINT_20260110_102_004_INTHUB_registry_connectors.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify Harbor connector resolves tags to digests
|
||||
- [ ] Test plugin loader discovers and loads registry connector plugins
|
||||
- [ ] Verify integration service manages connector lifecycle
|
||||
- [ ] Test PostgreSQL persistence stores integration configurations
|
||||
- [ ] Verify connector handles authentication for each registry type
|
||||
@@ -1,28 +0,0 @@
|
||||
# Built-in Vault Connectors (HashiCorp Vault, Azure Key Vault, AWS Secrets Manager)
|
||||
|
||||
## Module
|
||||
Integrations
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Three vault connectors using raw HTTP clients: HashiCorp Vault (Token, AppRole, Kubernetes auth), Azure Key Vault (Service Principal, Managed Identity), and AWS Secrets Manager (IAM SigV4). Unified secret resolution interface for integration configuration encryption.
|
||||
|
||||
## Implementation Details
|
||||
- **Integration core**: `src/Integrations/__Libraries/StellaOps.Integrations.Core/Integration.cs` -- base integration with vault-type references for HashiCorp Vault, Azure Key Vault, AWS Secrets Manager
|
||||
- **Integration models**: `src/Integrations/__Libraries/StellaOps.Integrations.Core/IntegrationModels.cs` -- vault connection configuration models
|
||||
- **Integration enums**: `src/Integrations/__Libraries/StellaOps.Integrations.Core/IntegrationEnums.cs` -- vault type enumerations
|
||||
- **Connector plugin contract**: `src/Integrations/__Libraries/StellaOps.Integrations.Contracts/IIntegrationConnectorPlugin.cs` -- unified secret resolution interface
|
||||
- **Integration service**: `src/Integrations/StellaOps.Integrations.WebService/IntegrationService.cs` -- manages vault connector instances
|
||||
- **Persistence**: `src/Integrations/__Libraries/StellaOps.Integrations.Persistence/PostgresIntegrationRepository.cs` -- vault configuration persistence
|
||||
- **Infrastructure**: `src/Integrations/StellaOps.Integrations.WebService/Infrastructure/Abstractions.cs`, `DefaultImplementations.cs` -- vault-agnostic abstractions
|
||||
- **Tests**: `src/Integrations/__Tests/StellaOps.Integrations.Tests/IntegrationServiceTests.cs`
|
||||
- **Source**: SPRINT_20260110_102_005_INTHUB_vault_connector.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify HashiCorp Vault connector authenticates via Token, AppRole, and Kubernetes auth
|
||||
- [ ] Test Azure Key Vault connector with Service Principal and Managed Identity
|
||||
- [ ] Verify AWS Secrets Manager connector uses IAM SigV4 signing
|
||||
- [ ] Test unified secret resolution interface across all vault types
|
||||
- [ ] Verify vault credential encryption in persistence layer
|
||||
@@ -1,28 +0,0 @@
|
||||
# Connector Runtime with Resilience Patterns (Circuit Breaker, Retry, Rate Limiting, Pooling)
|
||||
|
||||
## Module
|
||||
Integrations
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Connector runtime managing connector instantiation, connection pooling, retry with exponential backoff, circuit breaker for fault isolation, and per-integration rate limiting. Handles both built-in and plugin connectors uniformly via ConnectorFactory.
|
||||
|
||||
## Implementation Details
|
||||
- **Integration service**: `src/Integrations/StellaOps.Integrations.WebService/IntegrationService.cs` -- connector runtime managing instantiation and lifecycle
|
||||
- **Plugin loader**: `src/Integrations/StellaOps.Integrations.WebService/IntegrationPluginLoader.cs` -- dynamic loading of built-in and plugin connectors
|
||||
- **Infrastructure abstractions**: `src/Integrations/StellaOps.Integrations.WebService/Infrastructure/Abstractions.cs` -- circuit breaker, retry, rate limiting interfaces
|
||||
- **Default implementations**: `src/Integrations/StellaOps.Integrations.WebService/Infrastructure/DefaultImplementations.cs` -- resilience pattern implementations
|
||||
- **Plugin contract**: `src/Integrations/__Libraries/StellaOps.Integrations.Contracts/IIntegrationConnectorPlugin.cs` -- unified connector interface
|
||||
- **Integration DTOs**: `src/Integrations/__Libraries/StellaOps.Integrations.Contracts/IntegrationDtos.cs` -- connector data transfer objects
|
||||
- **API endpoints**: `src/Integrations/StellaOps.Integrations.WebService/IntegrationEndpoints.cs` -- connector management API
|
||||
- **Tests**: `src/Integrations/__Tests/StellaOps.Integrations.Tests/IntegrationServiceTests.cs`, `IntegrationPluginLoaderTests.cs`
|
||||
- **Source**: SPRINT_20260110_102_002_INTHUB_connector_runtime.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify circuit breaker isolates failed connectors
|
||||
- [ ] Test retry with exponential backoff recovers from transient failures
|
||||
- [ ] Verify per-integration rate limiting prevents API quota exhaustion
|
||||
- [ ] Test connection pooling reuses connections efficiently
|
||||
- [ ] Verify ConnectorFactory handles both built-in and plugin connectors
|
||||
@@ -1,29 +0,0 @@
|
||||
# GitHub App Connector
|
||||
|
||||
## Module
|
||||
Integrations
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
GitHub App connector with authentication, health checks, annotation support, and Code Scanning extensions is fully implemented.
|
||||
|
||||
## Implementation Details
|
||||
- **Connector plugin**: `src/Integrations/__Plugins/StellaOps.Integrations.Plugin.GitHubApp/GitHubAppConnectorPlugin.cs` -- GitHub App connector with authentication and health checks
|
||||
- **Annotation client**: `src/Integrations/__Plugins/StellaOps.Integrations.Plugin.GitHubApp/GitHubAppAnnotationClient.cs` -- PR annotations via GitHub App
|
||||
- **Code scanning client**: `src/Integrations/__Plugins/StellaOps.Integrations.Plugin.GitHubApp/CodeScanning/GitHubCodeScanningClient.cs`, `IGitHubCodeScanningClient.cs` -- GitHub Code Scanning API
|
||||
- **Code scanning extensions**: `src/Integrations/__Plugins/StellaOps.Integrations.Plugin.GitHubApp/CodeScanning/GitHubCodeScanningExtensions.cs` -- DI registration
|
||||
- **Alert filter**: `src/Integrations/__Plugins/StellaOps.Integrations.Plugin.GitHubApp/CodeScanning/AlertFilter.cs` -- code scanning alert filtering
|
||||
- **SARIF upload**: `src/Integrations/__Plugins/StellaOps.Integrations.Plugin.GitHubApp/CodeScanning/SarifUploadRequest.cs`, `SarifUploadResult.cs`, `SarifUploadStatus.cs` -- SARIF upload models
|
||||
- **Processing status**: `src/Integrations/__Plugins/StellaOps.Integrations.Plugin.GitHubApp/CodeScanning/ProcessingStatus.cs`
|
||||
- **Code scanning alert model**: `src/Integrations/__Plugins/StellaOps.Integrations.Plugin.GitHubApp/CodeScanning/CodeScanningAlert.cs`
|
||||
- **Tests**: `src/Integrations/__Tests/StellaOps.Integrations.Tests/CodeScanning/GitHubCodeScanningClientTests.cs`
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify GitHub App authenticates using app installation tokens
|
||||
- [ ] Test PR annotation creates check runs with finding summaries
|
||||
- [ ] Verify Code Scanning API uploads SARIF results
|
||||
- [ ] Test alert filtering by severity and rule
|
||||
- [ ] Verify health check validates GitHub App connectivity
|
||||
@@ -1,29 +0,0 @@
|
||||
# GitHub Code Scanning Upload Client
|
||||
|
||||
## Module
|
||||
Integrations
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
GitHub Code Scanning REST API client is implemented with SARIF upload, processing status polling, alert filtering, and integration with the GitHubApp connector plugin.
|
||||
|
||||
## Implementation Details
|
||||
- **Code scanning client**: `src/Integrations/__Plugins/StellaOps.Integrations.Plugin.GitHubApp/CodeScanning/GitHubCodeScanningClient.cs`, `IGitHubCodeScanningClient.cs` -- SARIF upload and alert retrieval
|
||||
- **SARIF upload request**: `src/Integrations/__Plugins/StellaOps.Integrations.Plugin.GitHubApp/CodeScanning/SarifUploadRequest.cs` -- upload payload model
|
||||
- **SARIF upload result**: `src/Integrations/__Plugins/StellaOps.Integrations.Plugin.GitHubApp/CodeScanning/SarifUploadResult.cs` -- upload response model
|
||||
- **Upload status**: `src/Integrations/__Plugins/StellaOps.Integrations.Plugin.GitHubApp/CodeScanning/SarifUploadStatus.cs` -- upload status tracking
|
||||
- **Processing status**: `src/Integrations/__Plugins/StellaOps.Integrations.Plugin.GitHubApp/CodeScanning/ProcessingStatus.cs` -- processing state enum
|
||||
- **Alert filter**: `src/Integrations/__Plugins/StellaOps.Integrations.Plugin.GitHubApp/CodeScanning/AlertFilter.cs` -- alert filtering logic
|
||||
- **Alert model**: `src/Integrations/__Plugins/StellaOps.Integrations.Plugin.GitHubApp/CodeScanning/CodeScanningAlert.cs` -- alert data model
|
||||
- **DI extensions**: `src/Integrations/__Plugins/StellaOps.Integrations.Plugin.GitHubApp/CodeScanning/GitHubCodeScanningExtensions.cs`
|
||||
- **Tests**: `src/Integrations/__Tests/StellaOps.Integrations.Tests/CodeScanning/GitHubCodeScanningClientTests.cs`
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify SARIF upload to GitHub Code Scanning API
|
||||
- [ ] Test processing status polling until upload is complete
|
||||
- [ ] Verify alert filtering returns relevant alerts
|
||||
- [ ] Test upload handles large SARIF files (gzip compression)
|
||||
- [ ] Verify integration with GitHubApp connector plugin authentication
|
||||
@@ -1,26 +0,0 @@
|
||||
# Integration Concierge (Setup Wizard + Health)
|
||||
|
||||
## Module
|
||||
Integrations
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Integration wizard UI, integration hub with detail views, and service-layer models for integration management are implemented in the Angular frontend.
|
||||
|
||||
## Implementation Details
|
||||
- **Backend API**: `src/Integrations/StellaOps.Integrations.WebService/IntegrationEndpoints.cs` -- REST endpoints for integration management
|
||||
- **Integration service**: `src/Integrations/StellaOps.Integrations.WebService/IntegrationService.cs` -- integration lifecycle and configuration
|
||||
- **Integration DTOs**: `src/Integrations/__Libraries/StellaOps.Integrations.Contracts/IntegrationDtos.cs` -- data transfer objects for API
|
||||
- **Integration models**: `src/Integrations/__Libraries/StellaOps.Integrations.Core/IntegrationModels.cs` -- configuration and health models
|
||||
- **Persistence**: `src/Integrations/__Libraries/StellaOps.Integrations.Persistence/PostgresIntegrationRepository.cs` -- integration config persistence
|
||||
- **Frontend**: Angular integration hub with wizard UI, detail views, and service-layer models (in `src/Web/StellaOps.Web/src/app/features/integrations/`)
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify integration wizard guides through connector setup
|
||||
- [ ] Test integration hub lists all configured integrations with health status
|
||||
- [ ] Verify detail views show connector configuration and diagnostics
|
||||
- [ ] Test integration CRUD operations through API
|
||||
- [ ] Verify health check results display in UI
|
||||
@@ -1,27 +0,0 @@
|
||||
# Integration Doctor Checks (Connectivity, Credentials, Permissions, Rate Limits)
|
||||
|
||||
## Module
|
||||
Integrations
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Doctor diagnostic checks for integration health: connectivity verification, credential validation, permission checks, and rate limit status monitoring. Generates aggregated health reports across all integrations.
|
||||
|
||||
## Implementation Details
|
||||
- **Integration service**: `src/Integrations/StellaOps.Integrations.WebService/IntegrationService.cs` -- health check orchestration across all integrations
|
||||
- **Infrastructure abstractions**: `src/Integrations/StellaOps.Integrations.WebService/Infrastructure/Abstractions.cs` -- connectivity, credential, permission check interfaces
|
||||
- **Integration models**: `src/Integrations/__Libraries/StellaOps.Integrations.Core/IntegrationModels.cs` -- health report models
|
||||
- **Plugin contract**: `src/Integrations/__Libraries/StellaOps.Integrations.Contracts/IIntegrationConnectorPlugin.cs` -- plugins implement health check methods
|
||||
- **API endpoints**: `src/Integrations/StellaOps.Integrations.WebService/IntegrationEndpoints.cs` -- health check API
|
||||
- **Doctor plugin integration**: Cross-module with `src/Doctor/` -- Doctor integration checks reference integration health
|
||||
- **Tests**: `src/Integrations/__Tests/StellaOps.Integrations.Tests/IntegrationServiceTests.cs`
|
||||
- **Source**: SPRINT_20260110_102_006_INTHUB_doctor_checks.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify connectivity checks detect unreachable integrations
|
||||
- [ ] Test credential validation catches expired or invalid credentials
|
||||
- [ ] Verify permission checks identify missing API scopes
|
||||
- [ ] Test rate limit monitoring reports quota usage
|
||||
- [ ] Verify aggregated health report covers all configured integrations
|
||||
@@ -1,26 +0,0 @@
|
||||
# Registry Webhook Handlers (Docker/Harbor)
|
||||
|
||||
## Module
|
||||
Integrations
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Webhook handlers for Docker Registry v2 and Harbor image-push events that trigger async gate evaluation. Accepts webhook payloads at `/api/v1/webhooks/registry/*` and queues gate evaluation jobs via an in-memory Channel-based queue with a background worker.
|
||||
|
||||
## Implementation Details
|
||||
- **API endpoints**: `src/Integrations/StellaOps.Integrations.WebService/IntegrationEndpoints.cs` -- webhook receiver at `/api/v1/webhooks/registry/*`
|
||||
- **Integration service**: `src/Integrations/StellaOps.Integrations.WebService/IntegrationService.cs` -- processes webhook payloads and queues gate evaluation
|
||||
- **Harbor plugin**: `src/Integrations/__Plugins/StellaOps.Integrations.Plugin.Harbor/HarborConnectorPlugin.cs` -- Harbor-specific webhook handling
|
||||
- **GitHub App plugin**: `src/Integrations/__Plugins/StellaOps.Integrations.Plugin.GitHubApp/GitHubAppConnectorPlugin.cs` -- GitHub webhook processing
|
||||
- **Integration DTOs**: `src/Integrations/__Libraries/StellaOps.Integrations.Contracts/IntegrationDtos.cs` -- webhook payload models
|
||||
- **WebService program**: `src/Integrations/StellaOps.Integrations.WebService/Program.cs` -- webhook endpoint registration
|
||||
- **Source**: SPRINT_20251226_001_BE_cicd_gate_integration.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify Docker Registry v2 webhook payloads are accepted
|
||||
- [ ] Test Harbor image-push webhook triggers gate evaluation
|
||||
- [ ] Verify Channel-based queue processes jobs asynchronously
|
||||
- [ ] Test webhook authentication validates payload signatures
|
||||
- [ ] Verify gate evaluation job queuing under load
|
||||
@@ -1,24 +0,0 @@
|
||||
# SCM Annotation Client Contracts (PR/MR Comments + Status Checks)
|
||||
|
||||
## Module
|
||||
Integrations
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Unified SCM annotation contracts for PR/MR comments, status checks, and check runs with evidence link fields, plus GitHub App and GitLab implementations.
|
||||
|
||||
## Implementation Details
|
||||
- **SCM annotation contracts**: `src/Integrations/__Libraries/StellaOps.Integrations.Contracts/ScmAnnotationContracts.cs` -- unified interface for PR/MR comments, status checks, and check runs with evidence link fields
|
||||
- **GitHub App annotation client**: `src/Integrations/__Plugins/StellaOps.Integrations.Plugin.GitHubApp/GitHubAppAnnotationClient.cs` -- GitHub implementation of SCM annotations
|
||||
- **GitLab annotation client**: `src/Integrations/__Plugins/StellaOps.Integrations.Plugin.GitLab/GitLabAnnotationClient.cs` -- GitLab implementation of SCM annotations
|
||||
- **Integration DTOs**: `src/Integrations/__Libraries/StellaOps.Integrations.Contracts/IntegrationDtos.cs` -- annotation payload models
|
||||
- **Source**: SPRINT_20260112_006_INTEGRATIONS_scm_annotations.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify GitHub App creates PR check runs with finding summaries
|
||||
- [ ] Test GitLab annotation posts MR comments with evidence links
|
||||
- [ ] Verify status check updates reflect policy evaluation results
|
||||
- [ ] Test evidence link fields contain valid URLs to evidence artifacts
|
||||
- [ ] Verify annotation contracts handle both pass/fail outcomes
|
||||
@@ -1,30 +0,0 @@
|
||||
# Toolchain-Agnostic Integrations (SCM/CI/Registry)
|
||||
|
||||
## Module
|
||||
Integrations
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Plugin-based integration architecture with connector plugins, integration hub UI, and setup wizard is implemented.
|
||||
|
||||
## Implementation Details
|
||||
- **Plugin contract**: `src/Integrations/__Libraries/StellaOps.Integrations.Contracts/IIntegrationConnectorPlugin.cs` -- toolchain-agnostic connector interface
|
||||
- **Plugin loader**: `src/Integrations/StellaOps.Integrations.WebService/IntegrationPluginLoader.cs` -- dynamic plugin loading for SCM/CI/Registry connectors
|
||||
- **Built-in plugins**: GitHub App (`StellaOps.Integrations.Plugin.GitHubApp/`), GitLab (`StellaOps.Integrations.Plugin.GitLab/`), Harbor (`StellaOps.Integrations.Plugin.Harbor/`), InMemory (`StellaOps.Integrations.Plugin.InMemory/`)
|
||||
- **Integration service**: `src/Integrations/StellaOps.Integrations.WebService/IntegrationService.cs` -- manages plugin lifecycle
|
||||
- **Integration endpoints**: `src/Integrations/StellaOps.Integrations.WebService/IntegrationEndpoints.cs` -- REST API for managing integrations
|
||||
- **SCM annotations**: `src/Integrations/__Libraries/StellaOps.Integrations.Contracts/ScmAnnotationContracts.cs` -- SCM-agnostic annotation interface
|
||||
- **Integration core**: `src/Integrations/__Libraries/StellaOps.Integrations.Core/` -- `Integration.cs`, `IntegrationModels.cs`, `IntegrationEnums.cs`
|
||||
- **Persistence**: `src/Integrations/__Libraries/StellaOps.Integrations.Persistence/PostgresIntegrationRepository.cs`
|
||||
- **Frontend**: Integration hub wizard UI and detail views in `src/Web/`
|
||||
- **Tests**: `src/Integrations/__Tests/StellaOps.Integrations.Tests/IntegrationServiceTests.cs`, `IntegrationPluginLoaderTests.cs`, `StellaOps.Integrations.Plugin.Tests/InMemoryConnectorPluginTests.cs`
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify plugin loader discovers connectors for SCM, CI, and Registry types
|
||||
- [ ] Test GitHub App and GitLab connectors through unified interface
|
||||
- [ ] Verify Harbor and InMemory registry connectors work interchangeably
|
||||
- [ ] Test integration management API handles all connector types
|
||||
- [ ] Verify toolchain-agnostic contract allows adding new connector plugins
|
||||
@@ -1,32 +0,0 @@
|
||||
# Adversarial Input Validation for Scoring Inputs
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Input validation and sanitization for scoring engine inputs to prevent adversarial manipulation of risk scores through crafted CVSS vectors, EPSS values, or other scoring parameters.
|
||||
|
||||
## Implementation Details
|
||||
- **Scoring Engine**: `src/Policy/StellaOps.Policy.Engine/Scoring/` -- scoring engine with input validation
|
||||
- `Engines/AdvancedScoringEngine.cs` -- advanced scoring with validation
|
||||
- `Engines/ProofAwareScoringEngine.cs` -- proof-aware scoring with integrity checks
|
||||
- `Engines/SimpleScoringEngine.cs` -- base scoring engine
|
||||
- `IScoringEngine.cs` -- scoring engine interface
|
||||
- `ScoringEngineFactory.cs` -- factory for scoring engine selection
|
||||
- **CVSS Scoring Library**: `src/Policy/StellaOps.Policy.Scoring/` -- CVSS v4.0 scoring engine with vector validation
|
||||
- **Determinism Guard**: `src/Policy/StellaOps.Policy.Engine/DeterminismGuard/DeterminismGuardService.cs` -- guards against non-deterministic inputs
|
||||
- `ProhibitedPatternAnalyzer.cs` -- detects prohibited patterns in policy expressions
|
||||
- `DeterminismViolation.cs` -- violation model for detected issues
|
||||
- **Score Provenance**: `src/Policy/StellaOps.Policy.Engine/Attestation/ScoreProvenanceChain.cs` -- tracks provenance of scoring inputs
|
||||
- `ScoringDeterminismVerifier.cs` -- verifies scoring determinism
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Submit a crafted CVSS v4.0 vector with out-of-range metric values and verify rejection
|
||||
- [ ] Submit an EPSS score outside [0,1] range and verify clamping or rejection
|
||||
- [ ] Verify scoring engine produces identical scores for identical inputs (determinism)
|
||||
- [ ] Submit duplicate scoring requests and verify idempotent results
|
||||
- [ ] Verify score provenance chain records all input hashes
|
||||
- [ ] Submit adversarial policy expressions and verify ProhibitedPatternAnalyzer catches them
|
||||
@@ -1,33 +0,0 @@
|
||||
# Anchor-Aware Determinization Rules in Policy Engine
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Determinization rules that are aware of trust anchors, ensuring policy evaluation produces consistent results based on the trust anchor configuration and signal snapshots.
|
||||
|
||||
## Implementation Details
|
||||
- **Determinization Gate**: `src/Policy/StellaOps.Policy.Engine/Gates/Determinization/DeterminizationGate.cs` -- determinization gate evaluator
|
||||
- `DeterminizationGateMetrics.cs` -- gate metrics tracking
|
||||
- `ISignalSnapshotBuilder.cs` / `SignalSnapshotBuilder.cs` -- builds signal snapshots for deterministic evaluation
|
||||
- **Determinization Policy**: `src/Policy/StellaOps.Policy.Engine/Policies/DeterminizationPolicy.cs` -- determinization policy definition
|
||||
- `DeterminizationRuleSet.cs` -- rule set for determinization
|
||||
- `IDeterminizationPolicy.cs` -- policy interface
|
||||
- **Determinization Library**: `src/Policy/__Libraries/StellaOps.Policy.Determinization/` -- core determinization library
|
||||
- `Models/` -- determinization models
|
||||
- `Scoring/` -- determinization scoring
|
||||
- `Evidence/` -- evidence-based determinization
|
||||
- **DI Registration**: `src/Policy/StellaOps.Policy.Engine/DependencyInjection/DeterminizationEngineExtensions.cs` -- service registration
|
||||
- **Configuration Endpoints**: `src/Policy/StellaOps.Policy.Engine/Endpoints/DeterminizationConfigEndpoints.cs` -- API for determinization configuration
|
||||
- **Events**: `src/Policy/StellaOps.Policy.Engine/Subscriptions/DeterminizationEvents.cs` -- determinization event subscriptions
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Configure determinization rules via API and verify they apply during evaluation
|
||||
- [ ] Evaluate a policy with signal snapshots and verify deterministic output
|
||||
- [ ] Change trust anchor configuration and verify determinization rules adapt
|
||||
- [ ] Run same evaluation twice with identical snapshots and verify identical results
|
||||
- [ ] Verify determinization metrics are emitted (gate pass/fail counts)
|
||||
- [ ] Test determinization configuration endpoint returns current rule set
|
||||
@@ -1,35 +0,0 @@
|
||||
# Auditable Exception Objects
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Exception objects with full audit trail including creation, approval, application, expiry, and revocation events. Supports evidence-linked approval workflows and audit-grade persistence.
|
||||
|
||||
## Implementation Details
|
||||
- **Exception Library**: `src/Policy/__Libraries/StellaOps.Policy.Exceptions/` -- core exception system
|
||||
- `Models/` -- exception domain models (ExceptionRecord, ExceptionApproval, etc.)
|
||||
- `Services/` -- exception services (ExceptionService, ExceptionApprovalService)
|
||||
- `Repositories/` -- exception persistence (IExceptionRepository)
|
||||
- **Exception Adapter**: `src/Policy/StellaOps.Policy.Engine/Adapters/ExceptionAdapter.cs` -- adapts exceptions for policy evaluation
|
||||
- `ExceptionEffectRegistry.cs` -- tracks effects of applied exceptions
|
||||
- **Exception Domain**: `src/Policy/StellaOps.Policy.Engine/Domain/ExceptionContracts.cs` -- exception contracts
|
||||
- `ExceptionMapper.cs` -- maps between exception models
|
||||
- **Exception Cache**: `src/Policy/StellaOps.Policy.Engine/ExceptionCache/` -- exception caching
|
||||
- `ExceptionCacheModels.cs`, `IExceptionEffectiveCache.cs`, `MessagingExceptionEffectiveCache.cs`, `RedisExceptionEffectiveCache.cs`
|
||||
- **Exception Events**: `src/Policy/StellaOps.Policy.Engine/Events/ExceptionEventPublisher.cs` -- publishes exception lifecycle events
|
||||
- **Lifecycle Workers**: `src/Policy/StellaOps.Policy.Engine/Workers/ExceptionLifecycleService.cs`, `ExceptionLifecycleWorker.cs` -- background processing
|
||||
- **Approval Rules**: `src/Policy/StellaOps.Policy.Engine/Services/ExceptionApprovalRulesService.cs` -- approval workflow rules
|
||||
- **Exception-Aware Evaluation**: `src/Policy/StellaOps.Policy.Engine/Services/ExceptionAwareEvaluationService.cs` -- evaluation with exception awareness
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Create an exception object and verify audit trail records creation event
|
||||
- [ ] Approve an exception with evidence links and verify approval audit record
|
||||
- [ ] Apply an exception to a policy evaluation and verify it modifies the verdict
|
||||
- [ ] Let an exception expire and verify expiry event is recorded
|
||||
- [ ] Revoke an exception and verify revocation audit trail
|
||||
- [ ] Query exception history via API and verify all lifecycle events present
|
||||
- [ ] Verify exception cache invalidation on approval/revocation
|
||||
@@ -1,25 +0,0 @@
|
||||
# Batch Exception Loading for Policy Evaluation
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Efficient batch loading of policy exceptions for large-scale evaluation, avoiding N+1 queries when evaluating many findings against exception records.
|
||||
|
||||
## Implementation Details
|
||||
- **Batch Exception Loader**: `src/Policy/StellaOps.Policy.Engine/BatchEvaluation/BatchExceptionLoader.cs` -- bulk exception loading
|
||||
- `BatchEvaluationModels.cs` -- batch evaluation request/response models
|
||||
- **Batch Evaluation Endpoint**: `src/Policy/StellaOps.Policy.Engine/Endpoints/BatchEvaluationEndpoint.cs` -- API for batch evaluation
|
||||
- **Batch Context**: `src/Policy/StellaOps.Policy.Engine/BatchContext/BatchContextService.cs` -- batch context management
|
||||
- `BatchContextModels.cs` -- batch context models
|
||||
- **Batch Context Endpoint**: `src/Policy/StellaOps.Policy.Engine/Endpoints/BatchContextEndpoint.cs` -- API for batch contexts
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Submit a batch evaluation request with 100+ findings and verify all exceptions loaded efficiently
|
||||
- [ ] Verify batch context is created and reused across evaluations in the same batch
|
||||
- [ ] Measure evaluation latency for batch vs. individual exception loading
|
||||
- [ ] Verify batch evaluation API returns results for all submitted findings
|
||||
- [ ] Test batch context cleanup after evaluation completes
|
||||
@@ -1,51 +0,0 @@
|
||||
# Batch Simulation Orchestration
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Batch simulation orchestration for running multiple policy simulations in parallel with a dedicated simulation service in the policy registry.
|
||||
|
||||
## Implementation Details
|
||||
- **RiskSimulationService**: `src/Policy/StellaOps.Policy.Engine/Simulation/RiskSimulationService.cs` -- `RiskSimulationService` (sealed class)
|
||||
- `Simulate(RiskSimulationRequest)` runs a single risk simulation with finding scores, distributions, top movers, and aggregate metrics
|
||||
- `SimulateWithBreakdown(RiskSimulationRequest, RiskSimulationBreakdownOptions?)` runs with detailed breakdown analytics per POLICY-RISK-67-003
|
||||
- `CompareProfilesWithBreakdown(baseProfileId, compareProfileId, findings)` runs comparison simulation between two risk profiles with trend analysis
|
||||
- `GenerateBreakdown(result, findings)` generates standalone breakdown for existing simulation results
|
||||
- Score formula: signal values * weights -> normalized to 0-100 range
|
||||
- Signal types: Boolean (0/1), Numeric (direct), Categorical (mapped: none=0.0, low=0.3, medium=0.6, critical=1.0)
|
||||
- Severity thresholds: Critical >= 90, High >= 70, Medium >= 40, Low >= 10, else Informational
|
||||
- Actions: Critical/High -> Deny, Medium -> Review, Low/Info -> Allow
|
||||
- Supports severity and decision overrides via predicate matching on signal values
|
||||
- Produces distribution with 10 buckets and percentiles (p25, p50, p75, p90, p95, p99)
|
||||
- Top 10 movers identified by score with primary driver signals
|
||||
- **RiskSimulationBreakdownService**: `src/Policy/StellaOps.Policy.Engine/Simulation/RiskSimulationBreakdownService.cs` -- generates detailed breakdown analytics and comparison breakdowns
|
||||
- **SimulationAnalyticsService**: `src/Policy/StellaOps.Policy.Engine/Simulation/SimulationAnalyticsService.cs` -- simulation analytics with delta summary computation
|
||||
- **WhatIfSimulationService**: `src/Policy/StellaOps.Policy.Engine/WhatIfSimulation/WhatIfSimulationService.cs` -- `WhatIfSimulationService` (internal sealed class)
|
||||
- `SimulateAsync(WhatIfSimulationRequest)` executes what-if simulation without persisting results
|
||||
- Supports hypothetical SBOM diffs (add/remove/upgrade/downgrade operations) and draft policy evaluation
|
||||
- Computes decision changes between baseline and simulated: status_changed, severity_changed, new, removed
|
||||
- Impact analysis: risk delta (increased/decreased/unchanged), blocked/warning deltas, recommendations
|
||||
- VEX override handling: not_affected overrides deny to allow; unreachable downgrades deny to warn
|
||||
- Uses EffectiveDecisionMap, PolicyCompilationService, PolicyPackRepository
|
||||
- **Simulation Endpoints**: `src/Policy/StellaOps.Policy.Engine/Endpoints/RiskSimulationEndpoints.cs` -- REST API for simulation runs
|
||||
- **Overlay Simulation**: `src/Policy/StellaOps.Policy.Engine/Endpoints/OverlaySimulationEndpoint.cs` -- overlay-based simulation
|
||||
- **Console Simulation**: `src/Policy/StellaOps.Policy.Engine/Endpoints/ConsoleSimulationEndpoint.cs` -- console surface simulation
|
||||
- **Path Scope Simulation**: `src/Policy/StellaOps.Policy.Engine/Endpoints/PathScopeSimulationEndpoint.cs` -- path-scoped simulation
|
||||
- **Batch Evaluation**: `src/Policy/StellaOps.Policy.Engine/BatchEvaluation/BatchEvaluationModels.cs` -- models for batch evaluation runs
|
||||
- **Telemetry**: `RiskSimulationsRun` counter via `PolicyEngineTelemetry`, activity tracing with `risk_simulation.run` and `policy.whatif.simulate`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] POST to risk simulation endpoint with a profile ID and list of findings; verify response contains simulation ID, finding scores, distributions, and aggregate metrics
|
||||
- [ ] POST with `IncludeContributions=true` and verify signal contribution percentages sum to ~100% and override chain is returned
|
||||
- [ ] POST with `IncludeDistribution=true` and verify 10 buckets, 6 percentile levels, severity breakdown covering all 5 levels
|
||||
- [ ] Run `SimulateWithBreakdown` and verify breakdown analytics are present alongside the base simulation result
|
||||
- [ ] Run `CompareProfilesWithBreakdown` with two profile IDs and verify baseline vs compare results with trend analysis
|
||||
- [ ] POST what-if simulation with SBOM diff (add component with advisory) and verify new `deny` decision appears
|
||||
- [ ] POST what-if simulation with SBOM diff (remove component) and verify `allow` decision and `removed` change type
|
||||
- [ ] POST what-if simulation with draft policy YAML and verify simulated policy reference includes computed digest
|
||||
- [ ] Verify simulation IDs are deterministic (same inputs produce same `rsim-*` prefix ID)
|
||||
- [ ] Verify simulation with 0 findings returns zeroed aggregate metrics
|
||||
@@ -1,54 +0,0 @@
|
||||
# Belnap K4 Trust Lattice Engine (VEX Resolution, Trust Algebra)
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Full K4 lattice implementation with 4-valued logic (unknown/true/false/conflict), trust labels, lattice store, claim score merging, conflict penalization, and disposition selection. VEX normalization for OpenVEX and CSAF formats. Deterministic, commutative, idempotent merge operations. Comprehensive tests including property-based tests.
|
||||
|
||||
## Implementation Details
|
||||
- **K4Lattice**: `src/Policy/__Libraries/StellaOps.Policy/TrustLattice/K4Lattice.cs` -- Belnap four-valued logic implementation
|
||||
- `K4Value` enum: Unknown (bottom), True, False, Conflict (top)
|
||||
- Knowledge ordering: Unknown < True|False < Conflict; True and False are incomparable
|
||||
- `Join(a, b)` -- knowledge join (union of support): T join F = Conflict; short-circuits on Conflict
|
||||
- `JoinAll(values)` -- order-independent aggregation over sequence; short-circuits on Conflict
|
||||
- `Meet(a, b)` -- knowledge meet (intersection): T meet F = Unknown; Conflict meet X = X
|
||||
- `LessOrEqual(a, b)` -- knowledge ordering predicate
|
||||
- `Negate(v)` -- swaps True/False; Unknown and Conflict are self-negating
|
||||
- `FromSupport(hasTrueSupport, hasFalseSupport)` -- constructs K4 value from support flags
|
||||
- Helper predicates: `HasTrueSupport`, `HasFalseSupport`, `IsDefinite`, `IsIndeterminate`
|
||||
- **TrustLatticeEngine**: `src/Policy/__Libraries/StellaOps.Policy/TrustLattice/TrustLatticeEngine.cs` -- orchestrates complete trust evaluation pipeline
|
||||
- Pipeline: VEX normalization -> claim ingestion -> K4 lattice evaluation -> disposition selection -> proof bundle generation
|
||||
- `IngestVex(document, format, principal, trustLabel?)` -- ingests VEX document via registered normalizers
|
||||
- `IngestClaim(claim)` / `IngestClaims(claims)` -- direct claim ingestion into LatticeStore
|
||||
- `GetDisposition(subject)` -- evaluates subject and returns DispositionResult
|
||||
- `MergeClaims(scoredClaims, policy?)` -- merges scored VEX claims using ClaimScore-based algorithm
|
||||
- `Evaluate(options?)` -- evaluates all subjects with optional proof bundle generation and subject filtering
|
||||
- Fluent `ClaimBuilder` with `Assert(atom, value)`, `Present()`, `Applies()`, `Reachable()`, `Mitigated()`, `Fixed()`, `Misattributed()`
|
||||
- **ClaimScoreMerger**: `src/Policy/__Libraries/StellaOps.Policy/TrustLattice/ClaimScoreMerger.cs` -- lattice-based merge with conflict penalization
|
||||
- `Merge(scoredClaims, policy)` -- orders by adjusted score, specificity, original score; selects winner
|
||||
- `ConflictPenalizer` applies configurable penalty (default 0.25) to conflicting claims
|
||||
- `MergePolicy` options: `ConflictPenalty`, `PreferSpecificity`, `RequireReplayProofOnConflict`
|
||||
- Returns `MergeResult` with: winning claim, all scored claims, conflict records, confidence, RequiresReplayProof flag
|
||||
- **LatticeStore**: `src/Policy/__Libraries/StellaOps.Policy/TrustLattice/LatticeStore.cs` -- subject state storage and claim aggregation
|
||||
- **DispositionSelector**: `src/Policy/__Libraries/StellaOps.Policy/TrustLattice/DispositionSelector.cs` -- applies policy rules to select final disposition
|
||||
- **ConflictPenalizer**: `src/Policy/__Libraries/StellaOps.Policy/TrustLattice/ConflictPenalizer.cs` -- applies configurable penalties to conflicting claims
|
||||
- **SecurityAtom**: `src/Policy/__Libraries/StellaOps.Policy/TrustLattice/SecurityAtom.cs` -- atomic propositions (Present, Applies, Reachable, Mitigated, Fixed, Misattributed)
|
||||
- **VEX Normalizers**: `src/Policy/__Libraries/StellaOps.Policy/TrustLattice/VexNormalizers.cs`, `OpenVexNormalizer.cs`, `CsafVexNormalizer.cs` -- normalize CycloneDX, OpenVEX, CSAF formats to claims
|
||||
- **TrustLabel**: `src/Policy/__Libraries/StellaOps.Policy/TrustLattice/TrustLabel.cs` -- trust level annotations for claims
|
||||
- **PolicyBundle / ProofBundle**: `src/Policy/__Libraries/StellaOps.Policy/TrustLattice/PolicyBundle.cs`, `ProofBundle.cs` -- policy configuration and proof bundles with decision traces
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Create TrustLatticeEngine with default policy; ingest two claims with True and False assertions for same subject; verify K4 value is Conflict
|
||||
- [ ] Ingest claims from OpenVEX, CycloneDX, and CSAF documents; verify all three normalizers produce valid claims in the LatticeStore
|
||||
- [ ] Verify Join commutativity: `Join(a, b) == Join(b, a)` for all K4Value combinations
|
||||
- [ ] Verify Join idempotency: `Join(a, a) == a` for all K4Value values
|
||||
- [ ] Verify Meet/Join absorption: `Join(a, Meet(a, b)) == a` for all K4Value combinations
|
||||
- [ ] Verify conflict penalization: merge two claims with different VEX statuses; winning claim has lower adjusted score than original when conflict detected
|
||||
- [ ] Verify `RequiresReplayProof` is set when `RequireReplayProofOnConflict=true` and conflicts exist
|
||||
- [ ] Evaluate all subjects with `GenerateProofBundle=true` and verify proof bundle contains atom tables, claims, and decisions
|
||||
- [ ] Verify subject filter: evaluate with SubjectFilter containing one digest; only that subject's disposition is returned
|
||||
- [ ] Verify ClaimBuilder fluent API: create claim with `Present().Reachable().Mitigated()` and verify three assertions are ingested
|
||||
@@ -1,37 +0,0 @@
|
||||
# Blast radius / fleet view
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Blast radius containment schema and unknown ranker service assess impact across environments and services.
|
||||
|
||||
## Implementation Details
|
||||
- **BlastRadius Model**: `src/Policy/__Libraries/StellaOps.Policy.Unknowns/Models/BlastRadius.cs` -- `BlastRadius` (sealed record)
|
||||
- `Dependents` (int) -- number of packages that directly or transitively depend on this package; 0 indicates isolation
|
||||
- `NetFacing` (bool) -- whether the package is reachable from network-facing entrypoints
|
||||
- `Privilege` (string?) -- privilege level: root, user, none
|
||||
- **ContainmentSignals Model**: `src/Policy/__Libraries/StellaOps.Policy.Unknowns/Models/ContainmentSignals.cs` -- runtime containment posture
|
||||
- Seccomp enforcement status, filesystem mode (ro/rw), network policy (isolated/connected)
|
||||
- **UnknownRanker Integration**: `src/Policy/__Libraries/StellaOps.Policy.Unknowns/Services/UnknownRanker.cs` -- blast radius is integrated into the `ComputeContainmentReduction` method
|
||||
- Isolated package (Dependents=0): 15% risk reduction
|
||||
- Not network-facing: 5% risk reduction
|
||||
- Non-root privilege (user/none): 5% risk reduction
|
||||
- Seccomp enforced: 10% reduction; read-only filesystem: 10% reduction; network isolated: 5% reduction
|
||||
- Maximum containment reduction capped at 40%
|
||||
- Applied after time-based decay: `finalScore = decayedScore * (1 - containmentReduction)`
|
||||
- **UnknownRankerOptions**: Configurable reductions via `IsolatedReduction`, `NotNetFacingReduction`, `NonRootReduction`, `SeccompEnforcedReduction`, `FsReadOnlyReduction`, `NetworkIsolatedReduction`, `MaxContainmentReduction`
|
||||
- **Unknown Model**: `src/Policy/__Libraries/StellaOps.Policy.Unknowns/Models/Unknown.cs` -- unknown entity with blast radius reference
|
||||
- **Unknowns Budget Enforcer**: `src/Policy/__Libraries/StellaOps.Policy.Unknowns/UnknownsBudgetEnforcer.cs` -- enforces blast radius-aware budget thresholds
|
||||
- **Unknowns Endpoints**: `src/Policy/StellaOps.Policy.Engine/Endpoints/UnknownsEndpoints.cs` -- REST API for querying unknowns with blast radius data
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Rank an unknown with `Dependents=0, NetFacing=false, Privilege="none"` and verify containment reduction is 25% (15+5+5)
|
||||
- [ ] Rank an unknown with `Dependents=50, NetFacing=true, Privilege="root"` and verify containment reduction is 0%
|
||||
- [ ] Rank an unknown with full containment signals (seccomp=enforced, fs=ro, network=isolated) and blast radius isolation; verify capped at 40% max reduction
|
||||
- [ ] Query unknowns API and verify each unknown includes blast radius data (dependents, netFacing, privilege)
|
||||
- [ ] Verify a high-score unknown (HOT band) drops to WARM band when isolated package containment is applied
|
||||
- [ ] Verify containment reduction is disabled when `EnableContainmentReduction=false` in options
|
||||
@@ -1,46 +0,0 @@
|
||||
# Blast Radius Scoring for Unknowns (Dependency Graph Impact)
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Adds dependency graph impact scoring (dependent count, network-facing flag, privilege level) to the unknowns ranking algorithm. Isolated packages (0 dependents) get 15% risk reduction, non-network-facing gets 5%, non-root privilege gets 5%.
|
||||
|
||||
## Implementation Details
|
||||
- **UnknownRanker**: `src/Policy/__Libraries/StellaOps.Policy.Unknowns/Services/UnknownRanker.cs` -- `UnknownRanker` (sealed class implements `IUnknownRanker`)
|
||||
- Sprint: SPRINT_4000_0001_0002_unknowns_blast_radius_containment
|
||||
- Two-factor ranking formula: `Score = (Uncertainty * 50) + (ExploitPressure * 50)`
|
||||
- Uncertainty factors: Missing VEX (+0.40), Missing reachability (+0.30), Conflicting sources (+0.20), Stale advisory (+0.10)
|
||||
- Exploit pressure factors: In KEV (+0.50), EPSS >= 0.90 (+0.30), EPSS >= 0.50 (+0.15), CVSS >= 9.0 (+0.05)
|
||||
- `ComputeContainmentReduction(input)` applies blast radius scoring:
|
||||
- `BlastRadius.Dependents == 0` -> IsolatedReduction (default 15%)
|
||||
- `BlastRadius.NetFacing == false` -> NotNetFacingReduction (default 5%)
|
||||
- `BlastRadius.Privilege in ["user", "none"]` -> NonRootReduction (default 5%)
|
||||
- ContainmentSignals scoring:
|
||||
- `Seccomp == "enforced"` -> SeccompEnforcedReduction (default 10%)
|
||||
- `FileSystem == "ro"` -> FsReadOnlyReduction (default 10%)
|
||||
- `NetworkPolicy == "isolated"` -> NetworkIsolatedReduction (default 5%)
|
||||
- Max total containment reduction capped at 40%
|
||||
- Score = decayedScore * (1 - containmentReduction)
|
||||
- **UnknownRankInput**: Includes `BlastRadius?` and `Containment?` fields for dependency graph impact and runtime containment posture
|
||||
- **BlastRadius Record**: `src/Policy/__Libraries/StellaOps.Policy.Unknowns/Models/BlastRadius.cs` -- `Dependents` (int), `NetFacing` (bool), `Privilege` (string?)
|
||||
- **ContainmentSignals Record**: `src/Policy/__Libraries/StellaOps.Policy.Unknowns/Models/ContainmentSignals.cs` -- `Seccomp`, `FileSystem`, `NetworkPolicy`
|
||||
- **Band Assignment**: Hot >= 75, Warm >= 50, Cold >= 25, else Resolved (configurable via `UnknownRankerOptions`)
|
||||
- **Decay Buckets**: Time-based score decay using basis points: 7d=100%, 30d=90%, 90d=75%, 180d=60%, 365d=40%, >365d=20%
|
||||
- **Reason Codes**: `DetermineReasonCode` returns most actionable reason: AnalyzerLimit, Reachability, Identity, Provenance, VexConflict, FeedGap, ConfigUnknown
|
||||
- **Remediation Hints**: `RemediationHintsRegistry` provides short remediation hints per reason code
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Rank unknown with isolated blast radius (Dependents=0, NetFacing=false, Privilege="none"); verify 25% containment reduction applied (15+5+5)
|
||||
- [ ] Rank unknown with exposed blast radius (Dependents=100, NetFacing=true, Privilege="root"); verify 0% containment reduction
|
||||
- [ ] Rank unknown with mixed signals (isolated but network-facing); verify only IsolatedReduction (15%) applied
|
||||
- [ ] Rank unknown with full containment (blast radius + runtime signals); verify capped at MaxContainmentReduction (40%)
|
||||
- [ ] Verify score 80 with 25% containment reduction produces final score of 60 (80 * 0.75)
|
||||
- [ ] Verify HOT band unknown (score 80) drops to WARM band (score 60) after blast radius reduction
|
||||
- [ ] Verify reason code is AnalyzerLimit when `IsAnalyzerSupported=false`
|
||||
- [ ] Verify reason code is Reachability when `HasReachabilityData=false`
|
||||
- [ ] Verify decay factor applied: unknown last evaluated 90 days ago gets 75% multiplier (7500 bps)
|
||||
- [ ] Verify containment reduction is 0 when `EnableContainmentReduction=false`
|
||||
@@ -1,47 +0,0 @@
|
||||
# CI/CD Gate Exit Code Convention
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Standardized CI exit code convention for gate evaluation: 0=Pass, 1=Warn (configurable pass-through), 2=Fail/Block, 10+=errors. The `stella gate evaluate` CLI command returns these exit codes, enabling direct CI/CD pipeline integration without parsing output.
|
||||
|
||||
## Implementation Details
|
||||
- **PolicyGateEvaluator**: `src/Policy/StellaOps.Policy.Engine/Gates/PolicyGateEvaluator.cs` -- `PolicyGateEvaluator` (sealed class implements `IPolicyGateEvaluator`)
|
||||
- Sprint: SPRINT_20251226_001_BE_cicd_gate_integration
|
||||
- `EvaluateAsync(PolicyGateRequest)` returns `PolicyGateDecision` with decision type: Allow, Warn, Block
|
||||
- Evaluates gates in sequence: Evidence Completeness -> Lattice State -> VEX Trust -> Uncertainty Tier -> Confidence Threshold
|
||||
- Short-circuits on first Block (subsequent gates skipped)
|
||||
- Override support: `AllowOverride` with `OverrideJustification` and minimum length validation
|
||||
- **PolicyGateDecision**: `src/Policy/StellaOps.Policy.Engine/Gates/PolicyGateDecision.cs` -- decision model
|
||||
- `PolicyGateDecisionType`: Allow, Warn, Block
|
||||
- Contains: GateId, RequestedStatus, Subject, Evidence, Gates (array of results), Advisory, BlockedBy, BlockReason, Suggestion
|
||||
- **PolicyGateResultType**: Pass, PassWithNote, Warn, Block, Skip -- per-gate evaluation outcomes
|
||||
- **Exit Code Mapping** (CLI integration):
|
||||
- Allow -> exit 0 (CI pass)
|
||||
- Warn -> exit 1 (CI configurable: pass-through or soft fail)
|
||||
- Block -> exit 2 (CI hard fail)
|
||||
- Error/Exception -> exit 10+ (CI infrastructure error)
|
||||
- **Gate Types**:
|
||||
- Evidence Completeness Gate: requires graphHash (DSSE-attested) and pathAnalysis for not_affected
|
||||
- Lattice State Gate: checks lattice state compatibility (CU allows not_affected; SR/RO/CR block not_affected)
|
||||
- VEX Trust Gate: minimum composite score and signature verification per environment
|
||||
- Uncertainty Tier Gate: T1 blocks not_affected, T2 warns, T3 note, T4 pass
|
||||
- Confidence Threshold Gate: warns below min confidence for not_affected
|
||||
- **PolicyGateOptions**: `src/Policy/StellaOps.Policy.Engine/Gates/PolicyGateOptions.cs` -- configuration for gate thresholds
|
||||
- **CLI Gate Command**: `src/Cli/StellaOps.Cli/Commands/` -- `stella gate evaluate` translates decision type to process exit code
|
||||
- **Endpoints**: `src/Policy/StellaOps.Policy.Engine/Endpoints/PolicyDecisionEndpoint.cs` -- HTTP API for gate evaluation
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Run `stella gate evaluate` with a passing scenario (all evidence present, CU lattice state, T4 uncertainty); verify exit code 0
|
||||
- [ ] Run `stella gate evaluate` with a warning scenario (SU lattice state for not_affected); verify exit code 1
|
||||
- [ ] Run `stella gate evaluate` with a blocking scenario (no graphHash for not_affected); verify exit code 2
|
||||
- [ ] Run `stella gate evaluate` with invalid input (missing required arguments); verify exit code >= 10
|
||||
- [ ] POST to policy decision endpoint with Block decision; verify response includes `blockedBy`, `blockReason`, and `suggestion`
|
||||
- [ ] POST with `AllowOverride=true` and valid justification; verify overridden Block becomes Warn with advisory message
|
||||
- [ ] POST with `AllowOverride=true` but justification too short; verify Block is not overridden
|
||||
- [ ] Verify VEX Trust gate returns Block when trust score below threshold for production environment
|
||||
- [ ] Verify CI pipeline integration: use exit code in `if` statement to gate deployment
|
||||
@@ -1,50 +0,0 @@
|
||||
# ClaimScore Merger and Policy Gate Registry
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Implements a lattice-based ClaimScore merger with conflict penalization, plus four specialized policy gates (MinimumConfidenceGate, UnknownsBudgetGate, SourceQuotaGate, ReachabilityRequirementGate) registered through a PolicyGateRegistry. Distinct from existing "Policy Gates (G0-G4)" which is about gate levels; this is the trust lattice merge algebra and specific claim-score-aware gate implementations.
|
||||
|
||||
## Implementation Details
|
||||
- **ClaimScoreMerger**: `src/Policy/__Libraries/StellaOps.Policy/TrustLattice/ClaimScoreMerger.cs` -- `ClaimScoreMerger` (sealed class implements `IClaimScoreMerger`)
|
||||
- Sprint: SPRINT_7100_0002_0001_policy_gates_merge
|
||||
- `Merge(scoredClaims, policy, ct)` -- deterministic merge of scored VEX claims
|
||||
- Ordering: descending adjusted score -> descending specificity (if enabled) -> descending original score -> source ID (ordinal) -> insertion index
|
||||
- First claim in ordered list is the winner; all others marked non-accepted
|
||||
- Produces `MergeResult`: Status, Confidence (clamped 0-1), HasConflicts, AllClaims, WinningClaim, Conflicts, RequiresReplayProof
|
||||
- **ConflictPenalizer**: `src/Policy/__Libraries/StellaOps.Policy/TrustLattice/ConflictPenalizer.cs` -- applies conflict penalties
|
||||
- Default penalty: 0.25 -- applied to claims with conflicting VEX statuses
|
||||
- Detects conflicts when multiple distinct VEX statuses exist across claims
|
||||
- **MergePolicy**: configurable options for merge behavior
|
||||
- `ConflictPenalty` (double, default 0.25) -- score reduction for conflicting claims
|
||||
- `PreferSpecificity` (bool, default true) -- tiebreak by ScopeSpecificity
|
||||
- `RequireReplayProofOnConflict` (bool, default true) -- set RequiresReplayProof flag when conflicts detected
|
||||
- **VexClaim Model**: SourceId, VexStatus, ScopeSpecificity, IssuedAt, StatementDigest, Reason
|
||||
- **ClaimScoreResult Model**: Score, BaseTrust, StrengthMultiplier, FreshnessMultiplier
|
||||
- **ScoredClaim Model**: SourceId, Status, OriginalScore, AdjustedScore, ScopeSpecificity, Accepted, Reason
|
||||
- **ConflictRecord Model**: SourceId, Status, ConflictsWithSourceId, Reason
|
||||
- **PolicyGateEvaluator**: `src/Policy/StellaOps.Policy.Engine/Gates/PolicyGateEvaluator.cs` -- evaluates policy gates in sequence
|
||||
- Evidence Completeness Gate: requires DSSE-attested graphHash and path analysis for not_affected
|
||||
- Lattice State Gate: validates reachability lattice compatibility with requested VEX status
|
||||
- VEX Trust Gate: minimum composite score and signature verification per environment with configurable thresholds
|
||||
- Uncertainty Tier Gate: T1/T2/T3/T4 tier compatibility with VEX status transitions
|
||||
- Confidence Threshold Gate: warns below configurable minimum confidence
|
||||
- **VexTrustGate**: `src/Policy/StellaOps.Policy.Engine/Gates/VexTrustGate.cs` -- dedicated VEX trust gate with metrics
|
||||
- **StabilityDampingGate**: `src/Policy/StellaOps.Policy.Engine/Gates/StabilityDampingGate.cs` -- stability damping for gate decisions
|
||||
- **DriftGateEvaluator**: `src/Policy/StellaOps.Policy.Engine/Gates/DriftGateEvaluator.cs` -- drift-based gate evaluation
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Merge two claims with same VEX status; verify no conflicts and winning claim has highest score
|
||||
- [ ] Merge two claims with different VEX statuses; verify HasConflicts=true and ConflictPenalty applied to adjusted scores
|
||||
- [ ] Merge three claims with two conflicting statuses; verify penalty applied to minority-status claims
|
||||
- [ ] Merge with PreferSpecificity=true; verify higher ScopeSpecificity wins when scores are equal
|
||||
- [ ] Merge empty claims list; verify result has Status=UnderInvestigation, Confidence=0, no conflicts
|
||||
- [ ] Merge with RequireReplayProofOnConflict=true and conflicts present; verify RequiresReplayProof=true
|
||||
- [ ] Evaluate policy gate with passing evidence for not_affected; verify Allow decision
|
||||
- [ ] Evaluate policy gate with missing graphHash for not_affected; verify Block decision with suggestion to submit DSSE-attested call graph
|
||||
- [ ] Evaluate VEX Trust gate below threshold for production; verify Block; same score passes for development environment
|
||||
- [ ] Verify deterministic merge ordering: same inputs always produce same winner regardless of input order
|
||||
@@ -1,48 +0,0 @@
|
||||
# Comprehensive Testing Strategy (Epic 5100)
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
The testing strategy advisory was translated into Epic 5100 with 12 sprints covering run manifests, evidence indexes, offline bundles, golden corpus, canonicalization, replay runners, delta verdicts, SBOM interop, no-egress enforcement, unknowns budget CI gates, router chaos, and audit pack export/import. Implementation evidence exists for all major themes.
|
||||
|
||||
## Implementation Details
|
||||
- **Determinism Guards**: `src/Policy/StellaOps.Policy.Engine/DeterminismGuard/` -- determinism verification infrastructure
|
||||
- Ensures policy evaluation produces identical results given identical inputs
|
||||
- Hash-based comparison of evaluation outputs across runs
|
||||
- **Replay Infrastructure**: `src/Policy/__Libraries/StellaOps.Policy/Replay/` -- replay verdict evaluation
|
||||
- Knowledge snapshot capture and replay for deterministic verdict reproduction
|
||||
- Snapshot manifests for full evaluation state serialization
|
||||
- **Simulation Services**: `src/Policy/StellaOps.Policy.Engine/Simulation/` -- risk simulation with breakdowns
|
||||
- `RiskSimulationService`, `SimulationAnalyticsService`, `RiskSimulationBreakdownService`
|
||||
- Simulation comparison and trend analysis
|
||||
- **Delta Verdict Engine**: `src/Policy/StellaOps.Policy.Engine/Evaluation/` -- delta verdict computation
|
||||
- Incremental evaluation detecting changes between policy versions
|
||||
- **Unknowns Budget CI Gates**: `src/Policy/__Libraries/StellaOps.Policy.Unknowns/UnknownsBudgetEnforcer.cs`
|
||||
- Budget enforcement with Hot/Warm/Cold band thresholds
|
||||
- CI gate integration via exit code convention (0=pass, 1=warn, 2=block)
|
||||
- **Attestation Services**: `src/Policy/StellaOps.Policy.Engine/Attestation/` -- verdict attestation and proof generation
|
||||
- VerdictAttestationService, PolicyDecisionAttestationService
|
||||
- DSSE-signed attestation bundles
|
||||
- **Batch Evaluation**: `src/Policy/StellaOps.Policy.Engine/BatchEvaluation/` -- batch context and exception loading
|
||||
- `BatchEvaluationModels.cs`, `BatchExceptionLoader.cs`
|
||||
- **Console Export**: `src/Policy/StellaOps.Policy.Engine/ConsoleExport/` -- audit pack export/import
|
||||
- `ConsoleExportJobService`, `ConsoleExportModels`, `IConsoleExportJobStore`
|
||||
- **Verification Endpoints**: `src/Policy/StellaOps.Policy.Engine/Endpoints/VerifyDeterminismEndpoints.cs` -- determinism verification API
|
||||
- **CVSS Receipt Endpoints**: `src/Policy/StellaOps.Policy.Engine/Endpoints/CvssReceiptEndpoints.cs` -- CVSS scoring receipts
|
||||
- **Test Infrastructure**: `src/__Tests/` -- test projects covering policy evaluation, gates, simulation, and unknowns
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Run policy evaluation twice with identical inputs; verify determinism guard produces matching hashes
|
||||
- [ ] Capture a knowledge snapshot; replay it; verify verdict matches original evaluation
|
||||
- [ ] Run batch evaluation with multiple artifacts; verify all findings are processed and budget checked
|
||||
- [ ] Run simulation comparison between two policy versions; verify delta summary shows added/removed/regressed findings
|
||||
- [ ] Export audit pack via console export; re-import and verify all evidence artifacts are present
|
||||
- [ ] Run unknowns budget check with CI gate; verify exit code 0 when within budget, exit code 2 when exceeded
|
||||
- [ ] POST to determinism verification endpoint with two snapshots; verify diff report
|
||||
- [ ] Verify CVSS receipt endpoint returns scoring breakdown with attestation reference
|
||||
- [ ] Run delta verdict evaluation; verify only changed findings are re-evaluated
|
||||
- [ ] Verify offline bundle contains all evidence needed for air-gap verdict replay
|
||||
@@ -1,43 +0,0 @@
|
||||
# Console Simulation Diff (Shadow Gate Visual Output)
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Console-based simulation diff output for visual comparison of policy simulation results.
|
||||
|
||||
## Implementation Details
|
||||
- **ConsoleSimulationDiffService**: `src/Policy/StellaOps.Policy.Engine/Console/ConsoleSimulationDiffService.cs` -- `ConsoleSimulationDiffService` (internal sealed class)
|
||||
- Schema version: `console-policy-23-001` (POLICY-CONSOLE-23-002)
|
||||
- `Compute(ConsoleSimulationDiffRequest)` generates deterministic before/after comparison
|
||||
- Produces severity breakdown (critical/high/medium/low/unknown) for baseline and candidate policy versions
|
||||
- Delta summary: added, removed, and regressed (escalated severity) finding counts
|
||||
- Rule impact analysis: per-rule added/removed counts and severity shift tracking (e.g., "medium->high")
|
||||
- Explain samples: deterministic trace IDs for drill-down investigation
|
||||
- Budget caps: `MaxFindings` (1-50,000) and `MaxExplainSamples` (0-200) via `ConsoleDiffBudget`
|
||||
- Deterministic ID generation using SHA-256 hashing of policy version + artifact digest
|
||||
- All ordering is lexicographic by Ordinal for determinism
|
||||
- **ConsoleSimulationDiffModels**: `src/Policy/StellaOps.Policy.Engine/Console/ConsoleSimulationDiffModels.cs` -- request/response DTOs
|
||||
- `ConsoleSimulationDiffRequest`: BaselinePolicyVersion, CandidatePolicyVersion, ArtifactScope, Budget, EvaluationTimestamp
|
||||
- `ConsoleSimulationDiffResponse`: SchemaVersion, Summary (Before/After/Delta), RuleImpact, Samples, Provenance
|
||||
- `ConsoleArtifactScope`: ArtifactDigest, Purl, AdvisoryId
|
||||
- `ConsoleDiffDelta`: Added, Removed, Regressed
|
||||
- `ConsoleRuleImpact`: RuleId, Added, Removed, SeverityShifts
|
||||
- `ConsoleDiffProvenance`: BaselineVersion, CandidateVersion, EvaluationTimestamp
|
||||
- **SimulationAnalyticsService Integration**: Uses `SimulationAnalyticsService.ComputeDeltaSummary` for severity change detection (escalated counts)
|
||||
- **Console Simulation Endpoint**: `src/Policy/StellaOps.Policy.Engine/Endpoints/ConsoleSimulationEndpoint.cs` -- REST API for triggering console simulation diffs
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] POST to console simulation endpoint with baseline and candidate policy versions; verify response contains schema version, summary, rule impact, and samples
|
||||
- [ ] Verify severity breakdown: before and after both contain counts for all 5 severity levels (critical/high/medium/low/unknown)
|
||||
- [ ] Verify delta: added count equals findings in candidate but not baseline; removed count is the inverse
|
||||
- [ ] Verify rule impact: each rule entry shows added, removed, and severity shift details
|
||||
- [ ] Verify samples: explain trace IDs are deterministic (same inputs produce same trace IDs)
|
||||
- [ ] POST with MaxFindings=1; verify only 1 finding per policy version in the output
|
||||
- [ ] POST with MaxExplainSamples=0; verify samples section contains empty arrays
|
||||
- [ ] POST same request twice; verify identical response (deterministic output)
|
||||
- [ ] Verify provenance section contains both policy versions and evaluation timestamp
|
||||
- [ ] POST with multiple artifact scopes; verify findings are ordered by ArtifactDigest (ordinal)
|
||||
@@ -1,43 +0,0 @@
|
||||
# Counterfactual Engine (Policy Diff Analysis)
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Counterfactual engine that computes the difference between current and proposed policy configurations to show what would change.
|
||||
|
||||
## Implementation Details
|
||||
- **CounterfactualEngine**: `src/Policy/__Libraries/StellaOps.Policy/Counterfactuals/CounterfactualEngine.cs` -- `CounterfactualEngine` (sealed class implements `ICounterfactualEngine`)
|
||||
- `ComputeAsync(finding, verdict, document, scoringConfig, options?, ct)` computes counterfactual paths for a blocked finding
|
||||
- Returns `CounterfactualResult` with paths to pass when finding is currently blocked
|
||||
- Returns `AlreadyPassing` result when finding already has Pass verdict
|
||||
- Five counterfactual path types:
|
||||
- **VEX path**: simulates finding with `not_affected` VEX status; skipped if already not_affected
|
||||
- **Exception path**: computes exception effort based on severity (Critical=5, High=4, Medium=3, Low=2)
|
||||
- **Reachability path**: simulates finding with `reachability:no`; effort varies (2 if unknown, 4 if currently reachable)
|
||||
- **Version upgrade path**: uses `FixedVersionLookup` delegate to find fixed version; extracts current version from PURL
|
||||
- **Compensating control path**: suggests compensating controls (effort=4)
|
||||
- VEX and reachability paths use `PolicyEvaluation.EvaluateFinding` to simulate what-if verdicts
|
||||
- Tag-based signals: reads `vex:` and `reachability:` prefixed tags from finding
|
||||
- **CounterfactualOptions**: `src/Policy/__Libraries/StellaOps.Policy/Counterfactuals/CounterfactualEngine.cs` -- options record
|
||||
- `IncludeVexPaths`, `IncludeExceptionPaths`, `IncludeReachabilityPaths`, `IncludeVersionUpgradePaths`, `IncludeCompensatingControlPaths` (all default true)
|
||||
- `PolicyAllowsExceptions`, `PolicyConsidersReachability`, `PolicyAllowsCompensatingControls` (all default true)
|
||||
- `FixedVersionLookup` -- async delegate `(cve, purl, ct) => fixedVersion?` for version upgrade lookup
|
||||
- **CounterfactualResult**: `src/Policy/__Libraries/StellaOps.Policy/Counterfactuals/CounterfactualResult.cs` -- result model with finding ID and list of `CounterfactualPath`
|
||||
- **CounterfactualPath**: paths with type, description, and effort rating
|
||||
- Factory methods: `Vex(currentStatus, cve, effort)`, `Exception(cve, effort)`, `Reachability(current, findingId, effort)`, `VersionUpgrade(current, fixed, purl, effort)`, `CompensatingControl(findingId, effort)`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Compute counterfactuals for a blocked finding with VEX status=affected; verify VEX path suggests not_affected and simulated verdict would pass
|
||||
- [ ] Compute counterfactuals for a finding already passing; verify AlreadyPassing result with no paths
|
||||
- [ ] Compute counterfactuals with IncludeVexPaths=false; verify no VEX path in result
|
||||
- [ ] Compute counterfactuals for a finding with reachability=unknown; verify reachability path with effort=2
|
||||
- [ ] Compute counterfactuals for a finding with reachability=yes; verify reachability path with effort=4
|
||||
- [ ] Compute counterfactuals with FixedVersionLookup providing a fixed version; verify version upgrade path with current and fixed versions
|
||||
- [ ] Compute counterfactuals with FixedVersionLookup returning null; verify no version upgrade path
|
||||
- [ ] Verify exception path effort: Critical finding has effort=5, Low finding has effort=2
|
||||
- [ ] Compute counterfactuals with PolicyAllowsExceptions=false; verify no exception path
|
||||
- [ ] Verify all five path types are present when all options are enabled and applicable
|
||||
@@ -1,44 +0,0 @@
|
||||
# CVE-Aware Release Policy Gates (EPSS/KEV/Reachable/Delta/Aggregate)
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Five specialized CVE-aware policy gates (EpssThresholdGate, KevBlockerGate, ReachableCveGate, CveDeltaGate, ReleaseAggregateCveGate) that use real-time EPSS scores, KEV catalog membership, reachability status, and cross-release delta to make gate decisions. Distinct from existing generic "CVSS Threshold Gate" or "EPSS Threshold Policy Gate" because these are an integrated multi-gate system with OPA/Rego support.
|
||||
|
||||
## Implementation Details
|
||||
- **PolicyGateEvaluator**: `src/Policy/StellaOps.Policy.Engine/Gates/PolicyGateEvaluator.cs` -- orchestrates multi-gate evaluation
|
||||
- Evaluates gates in sequence: Evidence -> Lattice State -> VEX Trust -> Uncertainty Tier -> Confidence
|
||||
- Short-circuits on first Block; accumulates warnings from non-blocking gates
|
||||
- Override support with justification requirement
|
||||
- **VexTrustGate**: `src/Policy/StellaOps.Policy.Engine/Gates/VexTrustGate.cs` -- VEX trust-based gate with per-environment thresholds
|
||||
- `VexTrustGateOptions`: per-environment `VexTrustThresholds` with MinCompositeScore and RequireIssuerVerified
|
||||
- `MissingTrustBehavior`: Block, Warn, or Allow when trust data absent
|
||||
- Trust tiers: VeryHigh >= 0.9, High >= 0.7, Medium >= 0.5, Low >= 0.3, VeryLow < 0.3
|
||||
- **DriftGateEvaluator**: `src/Policy/StellaOps.Policy.Engine/Gates/DriftGateEvaluator.cs` -- drift-based gate for cross-release delta
|
||||
- `DriftGateOptions`: configurable via `DriftGateContext`
|
||||
- **StabilityDampingGate**: `src/Policy/StellaOps.Policy.Engine/Gates/StabilityDampingGate.cs` -- stability damping for flapping prevention
|
||||
- `StabilityDampingOptions`: configurable damping parameters
|
||||
- **PolicyGateDecision Model**: `src/Policy/StellaOps.Policy.Engine/Gates/PolicyGateDecision.cs`
|
||||
- Decision types: Allow, Warn, Block
|
||||
- Contains: GateId, Subject (VulnId/Purl/SymbolId/ScanId), Evidence (LatticeState/UncertaintyTier/GraphHash/RiskScore/Confidence), Gates array, Advisory, BlockedBy, BlockReason, Suggestion
|
||||
- **Reachability Lattice States**: U (Unknown), SR (StaticallyReachable), SU (StaticallyUnreachable), RO (RuntimeObserved), RU (RuntimeUnobserved), CR (ConfirmedReachable), CU (ConfirmedUnreachable), X (Contested)
|
||||
- **Uncertainty Tiers**: T1 (High), T2 (Medium), T3 (Low), T4 (Negligible)
|
||||
- **UnknownRanker Integration**: `src/Policy/__Libraries/StellaOps.Policy.Unknowns/Services/UnknownRanker.cs` -- exploit pressure factors (KEV +0.50, EPSS >= 0.90 +0.30, EPSS >= 0.50 +0.15, CVSS >= 9.0 +0.05)
|
||||
- **Scoring Integration**: `src/Policy/StellaOps.Policy.Engine/Scoring/` -- profile-aware scoring with EPSS/CVSS/KEV inputs
|
||||
- **Gate Endpoints**: `src/Policy/StellaOps.Policy.Engine/Endpoints/PolicyDecisionEndpoint.cs` -- REST API for gate evaluation
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Evaluate gate for not_affected with CU lattice state and T4 uncertainty; verify Allow decision
|
||||
- [ ] Evaluate gate for not_affected with CR lattice state; verify Block with suggestion to submit unreachability evidence
|
||||
- [ ] Evaluate gate for not_affected with missing graphHash; verify Block by EvidenceCompleteness gate
|
||||
- [ ] Evaluate gate with VEX trust score below production threshold; verify Block by VexTrust gate
|
||||
- [ ] Evaluate gate with VEX trust score above threshold but signature unverified; verify Block when RequireIssuerVerified=true
|
||||
- [ ] Evaluate gate with T1 uncertainty for not_affected and BlockT1ForNotAffected=true; verify Block by UncertaintyTier gate
|
||||
- [ ] Evaluate gate with KEV finding using UnknownRanker; verify exploit pressure includes +0.50 KEV factor
|
||||
- [ ] Evaluate gate with EPSS=0.95; verify exploit pressure includes +0.30 EPSS factor
|
||||
- [ ] Evaluate gate with override and valid justification; verify Block overridden to Warn with advisory
|
||||
- [ ] Evaluate gate with Contested (X) lattice state for not_affected; verify Block with suggestion to resolve through triage
|
||||
@@ -1,44 +0,0 @@
|
||||
# CVSS v4.0 Environmental Metrics Completion
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Completes CVSS v4.0 scoring with all Modified Attack/Impact environmental metrics (MAV, MAC, MAT, MPR, MUI, MVC, MVI, MVA, MSC, MSI, MSA). Extends the existing MacroVector scoring engine with environment-specific risk adjustments. Includes receipt-based deterministic scoring and REST endpoints.
|
||||
|
||||
## Implementation Details
|
||||
- **CvssV4Engine**: `src/Policy/StellaOps.Policy.Scoring/Engine/CvssV4Engine.cs` -- `CvssV4Engine` (sealed partial class implements `ICvssV4Engine`)
|
||||
- Sprint: SPRINT_1227_0013_0002_LB_cvss_v4_environmental
|
||||
- `ComputeScores(baseMetrics, threatMetrics?, environmentalMetrics?)` computes all score variants:
|
||||
- CVSS-B (base score only)
|
||||
- CVSS-BT (base + threat, when ExploitMaturity != NotDefined)
|
||||
- CVSS-BE (base + environmental, when modified metrics present)
|
||||
- CVSS-BTE (full: base + threat + environmental)
|
||||
- `DetermineEffectiveScore` selects the most specific score type available
|
||||
- MacroVector-based scoring per FIRST CVSS v4.0 specification
|
||||
- **CvssEnvironmentalMetrics**: Modified metrics covering all attack/impact dimensions:
|
||||
- Modified Attack metrics: MAV (Attack Vector), MAC (Attack Complexity), MAT (Attack Requirements), MPR (Privileges Required), MUI (User Interaction)
|
||||
- Modified Impact metrics: MVC (Confidentiality), MVI (Integrity), MVA (Availability), MSC (Subsequent Confidentiality), MSI (Subsequent Integrity), MSA (Subsequent Availability)
|
||||
- All values default to NotDefined (inherit base metric values)
|
||||
- **MacroVectorLookup**: `src/Policy/StellaOps.Policy.Scoring/Engine/MacroVectorLookup.cs` -- lookup table for macro vector scoring
|
||||
- **CvssScores Model**: BaseScore, ThreatScore, EnvironmentalScore, FullScore, EffectiveScore, EffectiveScoreType
|
||||
- **CvssScoreReceipt**: `src/Policy/StellaOps.Policy.Scoring/CvssScoreReceipt.cs` -- deterministic receipt with input hashes and policy references
|
||||
- **Receipts**: `src/Policy/StellaOps.Policy.Scoring/Receipts/` -- receipt persistence and generation
|
||||
- **CVSS Receipt Endpoints**: `src/Policy/StellaOps.Policy.Engine/Endpoints/CvssReceiptEndpoints.cs` -- REST API for scoring with receipts
|
||||
- **CvssMetrics**: `src/Policy/StellaOps.Policy.Scoring/CvssMetrics.cs` -- metric definitions with CVSS v4.0 enums
|
||||
- **CvssPolicy**: `src/Policy/StellaOps.Policy.Scoring/CvssPolicy.cs` -- policy-driven scoring thresholds
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Score a CVSS v4.0 vector with base metrics only; verify CVSS-B score matches FIRST specification
|
||||
- [ ] Score with environmental metrics (MAV=Network modified to MAV=Local); verify CVSS-BE score is lower than CVSS-B
|
||||
- [ ] Score with both threat (ExploitMaturity=Attacked) and environmental metrics; verify CVSS-BTE full score computed
|
||||
- [ ] Score with threat metrics only (no environmental); verify CVSS-BT computed and CVSS-BE is null
|
||||
- [ ] POST to CVSS receipt endpoint; verify receipt contains input hash, scoring policy reference, and deterministic score
|
||||
- [ ] Score same vector twice; verify identical scores and matching receipt hashes
|
||||
- [ ] Score with all Modified metrics set to NotDefined; verify environmental score equals base score
|
||||
- [ ] Score with MSI=Safety; verify maximum environmental impact applied
|
||||
- [ ] Verify effective score type selection: CVSS-BTE preferred when all metrics present
|
||||
- [ ] Verify CvssEngineFactory returns CvssV4Engine for v4.0 vectors
|
||||
@@ -1,48 +0,0 @@
|
||||
# CVSS v4.0 Scoring Engine (Multi-Version, Pipeline Integration, Receipts)
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Full CVSS v4.0 engine with macro vector lookup, multi-version support (v3.x + v4.0), environmental scoring, policy-driven pipeline integration, and threshold gate for blocking promotions. Deterministic receipt system with audit-grade reproducibility (input hashes, policy references, cryptographic binding). Postgres persistence for score receipts. Extensive test coverage.
|
||||
|
||||
## Implementation Details
|
||||
- **CVSS V4 Engine**: `src/Policy/StellaOps.Policy.Scoring/Engine/CvssV4Engine.cs` -- FIRST CVSS v4.0 specification implementation
|
||||
- MacroVector-based scoring with lookup table
|
||||
- Base, Threat, Environmental, and Full score computation
|
||||
- Effective score type selection (most specific available)
|
||||
- **CVSS V3 Engine**: `src/Policy/StellaOps.Policy.Scoring/Engine/CvssV3Engine.cs` -- CVSS v3.0/v3.1 scoring
|
||||
- **CVSS V2 Engine**: `src/Policy/StellaOps.Policy.Scoring/Engine/CvssV2Engine.cs` -- legacy CVSS v2.0 scoring
|
||||
- **CvssEngineFactory**: `src/Policy/StellaOps.Policy.Scoring/Engine/CvssEngineFactory.cs` -- version-aware engine selection
|
||||
- **CvssVectorInterop**: `src/Policy/StellaOps.Policy.Scoring/Engine/CvssVectorInterop.cs` -- cross-version vector parsing and conversion
|
||||
- **MacroVectorLookup**: `src/Policy/StellaOps.Policy.Scoring/Engine/MacroVectorLookup.cs` -- v4.0 macro vector distance lookup table
|
||||
- **CvssMetrics**: `src/Policy/StellaOps.Policy.Scoring/CvssMetrics.cs` -- base, threat, and environmental metric enums
|
||||
- **CvssPolicy**: `src/Policy/StellaOps.Policy.Scoring/CvssPolicy.cs` -- policy-driven scoring thresholds per environment
|
||||
- **CvssScoreReceipt**: `src/Policy/StellaOps.Policy.Scoring/CvssScoreReceipt.cs` -- deterministic receipt with input hashes
|
||||
- **Receipts**: `src/Policy/StellaOps.Policy.Scoring/Receipts/` -- receipt generation and persistence
|
||||
- **Receipt Endpoints**: `src/Policy/StellaOps.Policy.Engine/Endpoints/CvssReceiptEndpoints.cs` -- REST API for CVSS scoring with receipts
|
||||
- **Scoring Integration**: `src/Policy/StellaOps.Policy.Engine/Scoring/` -- policy engine scoring integration
|
||||
- `ScoringEngineFactory.cs` -- selects scoring engine based on configuration
|
||||
- `ProfileAwareScoringService.cs` -- profile-aware scoring
|
||||
- `ScorePolicyService.cs` -- policy-driven score evaluation
|
||||
- `SimpleScoringEngine.cs`, `AdvancedScoringEngine.cs`, `ProofAwareScoringEngine.cs` -- scoring engines
|
||||
- **Schemas**: `src/Policy/StellaOps.Policy.Scoring/Schemas/` -- JSON schemas for scoring models
|
||||
- **Policies**: `src/Policy/StellaOps.Policy.Scoring/Policies/` -- policy definitions for scoring
|
||||
- **Models**: `src/Policy/StellaOps.Policy.Scoring/Models/` -- scoring data models
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Score a CVSS v4.0 vector string; verify base score matches FIRST specification
|
||||
- [ ] Score a CVSS v3.1 vector string; verify base score matches NVD reference
|
||||
- [ ] Score a CVSS v2.0 vector string; verify backward compatibility
|
||||
- [ ] Use CvssEngineFactory with a v4.0 vector; verify CvssV4Engine is selected
|
||||
- [ ] Use CvssEngineFactory with a v3.1 vector; verify CvssV3Engine is selected
|
||||
- [ ] POST to CVSS receipt endpoint with v4.0 vector; verify receipt includes input hash, computed score, and policy reference
|
||||
- [ ] POST same vector twice; verify receipts have identical input hashes and scores (deterministic)
|
||||
- [ ] Score v4.0 vector with environmental metrics; verify CVSS-BE score differs from CVSS-B
|
||||
- [ ] Score v4.0 vector with threat metrics (ExploitMaturity=Attacked); verify CVSS-BT score higher than base
|
||||
- [ ] Verify CvssVectorInterop can parse both v3.x and v4.0 vector strings
|
||||
- [ ] Use ProfileAwareScoringService to score a finding; verify scoring profile weights are applied
|
||||
- [ ] Verify ProofAwareScoringEngine includes proof references in scoring output
|
||||
@@ -1,58 +0,0 @@
|
||||
# Declarative Multi-Modal Policy Engine
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Policy engine with 12+ gate types, trust lattice merge, OPA adapter integration, policy DSL, evidence-weighted scoring, and determinization gates covering CVSS, EPSS, VEX trust, reachability, unknowns, SBOM presence, and signature requirements.
|
||||
|
||||
## Implementation Details
|
||||
- **Policy Evaluator**: `src/Policy/StellaOps.Policy.Engine/Evaluation/PolicyEvaluator.cs` -- core policy evaluation with expression evaluation
|
||||
- `PolicyExpressionEvaluator.cs` -- evaluates policy expressions against findings
|
||||
- `PolicyEvaluationContext.cs` -- evaluation context with tenant, snapshot, and environment info
|
||||
- `VerdictSummary.cs` -- verdict summary generation
|
||||
- **Policy Gates**: `src/Policy/StellaOps.Policy.Engine/Gates/`
|
||||
- `PolicyGateEvaluator.cs` -- multi-gate orchestrator with 5 gate stages (Evidence, Lattice, VEX Trust, Uncertainty, Confidence)
|
||||
- `VexTrustGate.cs` -- VEX trust score and signature verification per environment
|
||||
- `DriftGateEvaluator.cs` -- drift-based gate for cross-release delta
|
||||
- `StabilityDampingGate.cs` -- stability damping to prevent flapping
|
||||
- `IDeterminizationGate.cs` -- interface for determinization gates
|
||||
- `Gates/Determinization/` -- determinization gate implementations
|
||||
- **Trust Lattice**: `src/Policy/__Libraries/StellaOps.Policy/TrustLattice/`
|
||||
- `TrustLatticeEngine.cs` -- K4 four-valued logic evaluation pipeline
|
||||
- `ClaimScoreMerger.cs` -- lattice-based merge with conflict penalization
|
||||
- VEX normalizers for CycloneDX, OpenVEX, CSAF formats
|
||||
- **Policy DSL**: `src/Policy/StellaOps.PolicyDsl/` -- declarative policy language compiler
|
||||
- Compiles YAML-based policy definitions into executable evaluation rules
|
||||
- **Scoring Engines**: `src/Policy/StellaOps.Policy.Engine/Scoring/`
|
||||
- `SimpleScoringEngine.cs`, `AdvancedScoringEngine.cs`, `ProofAwareScoringEngine.cs`
|
||||
- `EvidenceWeightedScore/` -- evidence-weighted scoring with proof integration
|
||||
- `ProfileAwareScoringService.cs` -- risk profile-driven scoring
|
||||
- `ScoringEngineFactory.cs` -- engine selection based on configuration
|
||||
- **CVSS Scoring**: `src/Policy/StellaOps.Policy.Scoring/` -- multi-version CVSS engine (v2, v3.x, v4.0)
|
||||
- **Determinism Guards**: `src/Policy/StellaOps.Policy.Engine/DeterminismGuard/`
|
||||
- `DeterminismGuardService.cs` -- runtime determinism enforcement
|
||||
- `ProhibitedPatternAnalyzer.cs` -- static analysis for non-deterministic patterns
|
||||
- `GuardedPolicyEvaluator.cs` -- wraps evaluator with determinism checks
|
||||
- **Policy Compilation**: `src/Policy/StellaOps.Policy.Engine/Compilation/` -- policy pack compilation
|
||||
- `PolicyCompilationService` -- compiles policy YAML into evaluation bundles
|
||||
- Endpoints: `PolicyCompilationEndpoints.cs`, `PolicyLintEndpoints.cs`
|
||||
- **Effective Decision Map**: `src/Policy/StellaOps.Policy.Engine/EffectiveDecisionMap/` -- materialized decision lookup
|
||||
- **Counterfactuals**: `src/Policy/__Libraries/StellaOps.Policy/Counterfactuals/` -- "what-if" analysis for blocked findings
|
||||
- **Simulation**: `src/Policy/StellaOps.Policy.Engine/Simulation/` -- risk simulation with breakdowns
|
||||
- **Unknowns Integration**: `src/Policy/__Libraries/StellaOps.Policy.Unknowns/` -- unknowns ranking and budget enforcement
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Compile a YAML policy with CVSS threshold, EPSS threshold, and VEX trust gates; verify compiled bundle is valid
|
||||
- [ ] Evaluate a finding against compiled policy; verify verdict includes gate decisions from all applicable gates
|
||||
- [ ] Evaluate with VEX trust gate; verify per-environment threshold enforcement (production stricter than development)
|
||||
- [ ] Evaluate with determinism guard enabled; verify GuardedPolicyEvaluator wraps evaluation and reports no violations
|
||||
- [ ] Submit policy YAML with wall-clock usage; verify ProhibitedPatternAnalyzer detects violation
|
||||
- [ ] Evaluate finding with evidence-weighted scoring; verify proof-aware score includes evidence references
|
||||
- [ ] Evaluate finding with ClaimScoreMerger; verify conflicting claims are penalized and winning claim selected
|
||||
- [ ] Use counterfactual engine on blocked finding; verify paths to pass are returned
|
||||
- [ ] POST policy lint endpoint with invalid YAML; verify lint errors returned
|
||||
- [ ] Compile and evaluate same policy+finding twice; verify deterministic verdict (identical results)
|
||||
@@ -1,27 +0,0 @@
|
||||
# Delta-If-Present Calculations for Missing Signals
|
||||
|
||||
## Status
|
||||
NOT_FOUND
|
||||
|
||||
## Description
|
||||
The advisory proposed computing "delta if present" values showing what would change if missing signals arrived (TSF-004). This was marked TODO and has not been implemented.
|
||||
|
||||
## Why Not Implemented
|
||||
- The specific "delta-if-present" calculation (TSF-004) for showing hypothetical score changes is not implemented as a standalone feature
|
||||
- However, related infrastructure exists in the Policy Determinization module:
|
||||
- `src/Policy/__Libraries/StellaOps.Policy.Determinization/Models/SignalGap.cs` -- models for missing/gap signals
|
||||
- `src/Policy/__Libraries/StellaOps.Policy.Determinization/Scoring/UncertaintyScoreCalculator.cs` -- calculates uncertainty from missing signals
|
||||
- `src/Policy/__Libraries/StellaOps.Policy.Determinization/Scoring/PriorDistribution.cs` -- prior distributions for gap handling
|
||||
- `src/Policy/__Libraries/StellaOps.Policy.Determinization/DeterminizationOptions.cs` -- configuration for determinization behavior
|
||||
- `src/Policy/StellaOps.Policy.Engine/Simulation/RiskSimulationBreakdown.cs` -- risk simulation with breakdown
|
||||
- Tests: `src/Policy/__Tests/StellaOps.Policy.Engine.Tests/Simulation/RiskSimulationBreakdownServiceTests.cs`
|
||||
- The Determinization module handles missing signals by computing uncertainty scores but does not project "what would change if signal X arrived" as a delta preview
|
||||
- Graph module also tracks missing signals: `src/Graph/__Libraries/StellaOps.Graph.Core/ICveObservationNodeRepository.cs`
|
||||
|
||||
## Source
|
||||
- Feature matrix scan
|
||||
|
||||
## Notes
|
||||
- Module: Policy
|
||||
- Modules referenced: `src/Policy`
|
||||
- Related: `src/Policy/__Libraries/StellaOps.Policy.Determinization/` (uncertainty scoring for gaps)
|
||||
@@ -1,48 +0,0 @@
|
||||
# Delta Verdict Engine
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Full delta verdict computation comparing two evaluation states, with signed delta JSON, API endpoints for delta generation, and verdict ID generation.
|
||||
|
||||
## Implementation Details
|
||||
- **WhatIfSimulationService**: `src/Policy/StellaOps.Policy.Engine/WhatIfSimulation/WhatIfSimulationService.cs` -- `WhatIfSimulationService` (internal sealed class)
|
||||
- `SimulateAsync(WhatIfSimulationRequest)` computes delta between baseline and simulated evaluation states
|
||||
- Supports SBOM diffs: add, remove, upgrade, downgrade operations
|
||||
- Computes `WhatIfDecisionChange`: status_changed, severity_changed, new, removed
|
||||
- Decision simulation: new components checked against advisory count, VEX override, reachability downgrade
|
||||
- Upgrade simulation: fixed-all -> allow, remaining advisories -> warn
|
||||
- Downgrade simulation: with advisories -> deny (higher priority 150)
|
||||
- `WhatIfSummary`: TotalEvaluated, TotalChanged, NewlyAffected, NoLongerAffected, StatusChanges, SeverityChanges, Impact
|
||||
- `WhatIfImpact`: risk delta (increased/decreased/unchanged), blocked/warning deltas, recommendation text
|
||||
- Simulation ID generation: `whatif-{SHA256(seed)[..16]}`
|
||||
- **WhatIfSimulationModels**: `src/Policy/StellaOps.Policy.Engine/WhatIfSimulation/WhatIfSimulationModels.cs` -- request/response DTOs
|
||||
- `WhatIfSimulationRequest`: TenantId, BaseSnapshotId, SbomDiffs, DraftPolicy, TargetPurls, IncludeExplanations, Limit, CorrelationId
|
||||
- `WhatIfSbomDiff`: Purl, Operation, OriginalVersion, NewVersion, AdvisoryIds, VexStatus, Reachability
|
||||
- `WhatIfDecision`: Status, Severity, RuleName, Priority, HasException
|
||||
- `WhatIfExplanation`: MatchedRules, Factors, VexEvidence, Reachability
|
||||
- **ConsoleSimulationDiffService**: `src/Policy/StellaOps.Policy.Engine/Console/ConsoleSimulationDiffService.cs` -- deterministic delta diff for console surface
|
||||
- Before/After severity breakdowns, delta (added/removed/regressed), rule impact, explain samples
|
||||
- **SimulationAnalyticsService**: `src/Policy/StellaOps.Policy.Engine/Simulation/SimulationAnalyticsService.cs` -- delta summary computation with severity change tracking
|
||||
- **Effective Decision Map**: `src/Policy/StellaOps.Policy.Engine/EffectiveDecisionMap/` -- materialized baseline decisions for delta comparison
|
||||
- **Simulation Endpoints**: `src/Policy/StellaOps.Policy.Engine/Endpoints/`
|
||||
- `ConsoleSimulationEndpoint.cs` -- console surface simulation diff
|
||||
- `OverlaySimulationEndpoint.cs` -- overlay-based simulation
|
||||
- `RiskSimulationEndpoints.cs` -- risk simulation with breakdowns
|
||||
- **Attestation**: `src/Policy/StellaOps.Policy.Engine/Attestation/` -- verdict attestation for signed delta output
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] POST what-if simulation with add component (3 advisories); verify deny decision with severity=high
|
||||
- [ ] POST what-if simulation with remove component; verify decision=allow and change_type=removed
|
||||
- [ ] POST what-if simulation with upgrade component fixing all CVEs; verify decision=allow
|
||||
- [ ] POST what-if simulation with downgrade component with advisories; verify decision=deny with priority 150
|
||||
- [ ] POST what-if simulation with VEX not_affected override; verify deny overridden to allow
|
||||
- [ ] POST what-if simulation with unreachable finding; verify deny downgraded to warn
|
||||
- [ ] Verify delta summary: TotalChanged matches actual number of decision changes
|
||||
- [ ] Verify impact: risk delta is "increased" when blocked count goes up, "decreased" when it goes down
|
||||
- [ ] POST with IncludeExplanations=true; verify explanations contain matched rules, SBOM factors, VEX evidence, and reachability
|
||||
- [ ] POST console simulation diff with two policy versions; verify deterministic before/after severity breakdowns and delta counts
|
||||
@@ -1,48 +0,0 @@
|
||||
# Determinism Guards (Runtime Enforcement)
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Runtime enforcement of determinism constraints during policy evaluation. Prohibited pattern analysis detects wall-clock, RNG, and network usage. A guarded evaluator wraps the policy engine.
|
||||
|
||||
## Implementation Details
|
||||
- **DeterminismGuardService**: `src/Policy/StellaOps.Policy.Engine/DeterminismGuard/DeterminismGuardService.cs` -- `DeterminismGuardService` (sealed class)
|
||||
- `AnalyzeSource(sourceCode, fileName?)` performs static analysis for determinism violations
|
||||
- `CreateScope(scopeId, evaluationTimestamp)` creates a guarded execution scope with frozen time
|
||||
- `ValidateContext<TContext>(context, contextName)` validates evaluation context for determinism
|
||||
- Combines static analysis (`ProhibitedPatternAnalyzer`) and runtime monitoring (`RuntimeDeterminismMonitor`)
|
||||
- `DeterminismGuardOptions.Default` provides default configuration
|
||||
- `EnforcementEnabled` controls whether violations cause failures or just warnings
|
||||
- `FailOnSeverity` threshold for when violations become blocking
|
||||
- **ProhibitedPatternAnalyzer**: `src/Policy/StellaOps.Policy.Engine/DeterminismGuard/ProhibitedPatternAnalyzer.cs` -- static code analysis
|
||||
- Regex-based pattern detection on source code lines
|
||||
- Detects: wall-clock access (DateTime.Now, DateTimeOffset.Now), RNG usage (Random, Guid.NewGuid), network calls, file I/O
|
||||
- Line-by-line scanning with line number tracking
|
||||
- Skips comments (// and /* ... */)
|
||||
- Reports: violation category, type, message, source file, line number, member context, severity, remediation
|
||||
- File exclusion via `ExcludePatterns` in options
|
||||
- `DeterminismViolationCategory`: WallClock, RandomNumber, NetworkAccess, FileSystem, Other
|
||||
- `DeterminismViolationSeverity` enumeration for graduated enforcement
|
||||
- **GuardedPolicyEvaluator**: `src/Policy/StellaOps.Policy.Engine/DeterminismGuard/GuardedPolicyEvaluator.cs` -- wraps policy evaluator with determinism checks
|
||||
- Pre-evaluation: validates context and checks for violations
|
||||
- Post-evaluation: verifies no runtime determinism violations occurred during evaluation
|
||||
- **DeterminismViolation**: `src/Policy/StellaOps.Policy.Engine/DeterminismGuard/DeterminismViolation.cs` -- violation model
|
||||
- Category, ViolationType, Message, SourceFile, LineNumber, MemberName, Severity, Remediation
|
||||
- **DeterminismAnalysisResult**: Passed (bool), Violations (ImmutableArray), CountBySeverity, AnalysisDurationMs, EnforcementEnabled
|
||||
- **Verification Endpoints**: `src/Policy/StellaOps.Policy.Engine/Endpoints/VerifyDeterminismEndpoints.cs` -- REST API for determinism verification
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Analyze source code with `DateTime.Now` usage; verify WallClock violation detected with line number and remediation suggestion
|
||||
- [ ] Analyze source code with `Random()` usage; verify RandomNumber violation detected
|
||||
- [ ] Analyze clean source code (using TimeProvider, IGuidProvider); verify no violations and Passed=true
|
||||
- [ ] Analyze source code with violations in comments; verify comments are skipped and no false positives
|
||||
- [ ] Create guarded scope with frozen timestamp; verify evaluation uses frozen time not wall clock
|
||||
- [ ] Evaluate with GuardedPolicyEvaluator; verify pre-evaluation and post-evaluation determinism checks pass
|
||||
- [ ] Set EnforcementEnabled=false; verify violations are reported but Passed=true
|
||||
- [ ] Set FailOnSeverity=Error; verify Warning-level violations do not cause failure
|
||||
- [ ] POST to determinism verification endpoint with policy source; verify analysis result with violation counts by severity
|
||||
- [ ] Analyze with ExcludePatterns matching test files; verify excluded files are skipped
|
||||
@@ -1,45 +0,0 @@
|
||||
# Deterministic Evaluation with Knowledge Snapshots
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Deterministic evaluation engine that pins all inputs via knowledge snapshot digests and can replay evaluations offline with identical results.
|
||||
|
||||
## Implementation Details
|
||||
- **Knowledge Snapshot Manifest**: `src/Policy/__Libraries/StellaOps.Policy/Snapshots/KnowledgeSnapshotManifest.cs` -- manifest containing all input digests
|
||||
- Captures: SBOM digest, advisory feed digest, policy bundle digest, VEX document digests, reachability graph digest
|
||||
- Content-addressed snapshot ID via `SnapshotIdGenerator.cs`
|
||||
- **SnapshotBuilder**: `src/Policy/__Libraries/StellaOps.Policy/Snapshots/SnapshotBuilder.cs` -- fluent builder for constructing knowledge snapshots
|
||||
- **SnapshotAwarePolicyEvaluator**: `src/Policy/__Libraries/StellaOps.Policy/Snapshots/SnapshotAwarePolicyEvaluator.cs` -- evaluator that pins inputs to snapshot
|
||||
- Evaluation uses frozen state from snapshot (no live data fetching)
|
||||
- Results are reproducible: same snapshot always produces same verdicts
|
||||
- **SnapshotIdGenerator**: `src/Policy/__Libraries/StellaOps.Policy/Snapshots/SnapshotIdGenerator.cs` -- deterministic ID from snapshot content
|
||||
- **KnowledgeSourceDescriptor**: `src/Policy/__Libraries/StellaOps.Policy/Snapshots/KnowledgeSourceDescriptor.cs` -- describes a knowledge source (type, URI, digest, timestamp)
|
||||
- **SnapshotService (Library)**: `src/Policy/__Libraries/StellaOps.Policy/Snapshots/SnapshotService.cs` -- snapshot lifecycle management
|
||||
- **SnapshotService (Engine)**: `src/Policy/StellaOps.Policy.Engine/Snapshots/SnapshotService.cs` -- engine-level snapshot operations
|
||||
- **SnapshotStore**: `src/Policy/StellaOps.Policy.Engine/Snapshots/SnapshotStore.cs` -- snapshot persistence
|
||||
- **SnapshotModels**: `src/Policy/StellaOps.Policy.Engine/Snapshots/SnapshotModels.cs` -- snapshot DTOs
|
||||
- **Replay Engine**: `src/Policy/__Libraries/StellaOps.Policy/Replay/ReplayEngine.cs` -- replays evaluation from snapshot
|
||||
- `ReplayRequest.cs` -- replay parameters including snapshot reference
|
||||
- `ReplayResult.cs` -- replay outcome with verdict comparison
|
||||
- `VerdictComparer.cs` -- compares original and replayed verdicts for drift detection
|
||||
- `ReplayReport.cs` -- detailed replay report with match/mismatch analysis
|
||||
- `KnowledgeSourceResolver.cs` -- resolves snapshot references to evaluation inputs
|
||||
- **Snapshot Endpoints**: `src/Policy/StellaOps.Policy.Engine/Endpoints/SnapshotEndpoint.cs`, `SnapshotEndpoints.cs`, `PolicySnapshotEndpoints.cs` -- REST API for snapshot CRUD
|
||||
- **Determinism Guards Integration**: `src/Policy/StellaOps.Policy.Engine/DeterminismGuard/` -- ensures no wall-clock or RNG leaks into snapshot-pinned evaluation
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Build a knowledge snapshot with SBOM, advisory feed, and policy bundle digests; verify snapshot ID is content-addressed
|
||||
- [ ] Evaluate finding using SnapshotAwarePolicyEvaluator with pinned snapshot; verify deterministic verdict
|
||||
- [ ] Re-evaluate same snapshot; verify identical verdict (byte-for-byte match)
|
||||
- [ ] Replay evaluation from snapshot using ReplayEngine; verify VerdictComparer shows no drift
|
||||
- [ ] Modify advisory feed and replay with original snapshot; verify replay uses original feed (not modified)
|
||||
- [ ] POST snapshot to snapshot endpoint; verify snapshot is persisted and retrievable by ID
|
||||
- [ ] Verify KnowledgeSourceDescriptor contains type, URI, digest, and timestamp for each source
|
||||
- [ ] Build snapshot with SnapshotBuilder; verify manifest contains all expected source descriptors
|
||||
- [ ] Replay evaluation with intentionally modified policy; verify VerdictComparer detects mismatch
|
||||
- [ ] Verify snapshot ID changes when any input digest changes
|
||||
@@ -1,51 +0,0 @@
|
||||
# Deterministic SBOM-to-VEX Pipeline with Signed State Transitions
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Full verdict pipeline determinism tests, SBOM determinism validation, determinism gate infrastructure, baseline store, and manifest writer for verifying byte-identical outputs from identical inputs.
|
||||
|
||||
## Implementation Details
|
||||
- **Determinization Gate**: `src/Policy/StellaOps.Policy.Engine/Gates/Determinization/DeterminizationGate.cs` -- determinization gate implementation
|
||||
- `ISignalSnapshotBuilder` interface for building signal snapshots
|
||||
- `SignalSnapshotBuilder.cs` -- builds signal snapshots for deterministic evaluation
|
||||
- `DeterminizationGateMetrics.cs` -- metrics tracking for determinization gates
|
||||
- **Determinism Guard Service**: `src/Policy/StellaOps.Policy.Engine/DeterminismGuard/DeterminismGuardService.cs`
|
||||
- Static analysis via `ProhibitedPatternAnalyzer` detects non-deterministic patterns
|
||||
- Runtime monitoring via `RuntimeDeterminismMonitor`
|
||||
- `GuardedPolicyEvaluator` wraps evaluation with pre/post determinism checks
|
||||
- **Determinization Library**: `src/Policy/__Libraries/StellaOps.Policy.Determinization/`
|
||||
- `DeterminizationOptions.cs` -- configuration for determinization behavior
|
||||
- `IDeterminizationConfigStore.cs` -- persisted configuration for reanalysis rules
|
||||
- `Evidence/` -- evidence models for determinization decisions
|
||||
- `Models/` -- determinization data models
|
||||
- `Scoring/` -- scoring models for determinization
|
||||
- **Knowledge Snapshot Pipeline**: `src/Policy/__Libraries/StellaOps.Policy/Snapshots/`
|
||||
- `KnowledgeSnapshotManifest.cs` -- pins all inputs (SBOM, feeds, policy) via digests
|
||||
- `SnapshotAwarePolicyEvaluator.cs` -- evaluates against frozen snapshot state
|
||||
- `SnapshotIdGenerator.cs` -- content-addressed snapshot IDs
|
||||
- **VEX State Transitions**: `src/Policy/StellaOps.Policy.Engine/Gates/PolicyGateEvaluator.cs`
|
||||
- Validates VEX status transitions (not_affected, affected, under_investigation, fixed)
|
||||
- Requires DSSE-attested graphHash and path analysis for not_affected transitions
|
||||
- **Attestation Services**: `src/Policy/StellaOps.Policy.Engine/Attestation/`
|
||||
- `VerdictAttestationService.cs` -- signs verdict decisions with DSSE
|
||||
- `PolicyDecisionAttestationService.cs` -- signs policy decisions
|
||||
- `ScoringDeterminismVerifier.cs` -- verifies scoring determinism
|
||||
- **Determinism Verification Endpoints**: `src/Policy/StellaOps.Policy.Engine/Endpoints/VerifyDeterminismEndpoints.cs`
|
||||
- **Determinization Config Endpoints**: `src/Policy/StellaOps.Policy.Engine/Endpoints/DeterminizationConfigEndpoints.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Run verdict pipeline twice with identical SBOM and advisory inputs; verify byte-identical output digests
|
||||
- [ ] Build signal snapshot using SignalSnapshotBuilder; verify snapshot captures all evaluation signals
|
||||
- [ ] Run determinism guard analysis on evaluation code; verify no prohibited patterns detected
|
||||
- [ ] Modify SBOM input and re-run pipeline; verify output digest changes
|
||||
- [ ] Verify VEX state transition from under_investigation to not_affected requires graphHash and pathAnalysis evidence
|
||||
- [ ] Sign verdict with VerdictAttestationService; verify DSSE envelope is valid
|
||||
- [ ] Verify ScoringDeterminismVerifier detects scoring drift when weights change
|
||||
- [ ] POST to determinization config endpoint; verify configuration is persisted and retrievable
|
||||
- [ ] Run determinization gate with signal snapshot; verify gate uses snapshot signals not live data
|
||||
- [ ] Verify knowledge snapshot manifest contains content-addressed IDs for all input sources
|
||||
@@ -1,57 +0,0 @@
|
||||
# Deterministic Trust Score Algebra and Vulnerability Scoring
|
||||
|
||||
## Module
|
||||
Policy (with Attestor TrustVerdict integration)
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Comprehensive scoring infrastructure exists across Policy and Attestor modules: EWS engine, Determinization system with 6-dimension normalizers (RCH/RTS/BKP/XPL/SRC/MIT), K4Lattice trust algebra (Belnap four-valued logic), TrustScoreAggregator with uncertainty penalty, DecayedConfidenceCalculator, ClaimScoreMerger with conflict penalization, ScorePolicy model with basis-point weights, TrustVerdictService with composite scoring, and BackportProofGenerator confidence calculations. The unified facade API composing all scoring subsystems and the Score.v1 predicate format are not yet built.
|
||||
|
||||
## What's Implemented
|
||||
- **TrustScoreAggregator**: `src/Policy/__Libraries/StellaOps.Policy.Determinization/Scoring/TrustScoreAggregator.cs` -- weighted-average aggregation of 6 signal types (VEX, EPSS, Reachability, Runtime, Backport, SBOMLineage) with uncertainty penalty: `adjustedScore = baseScore * (1.0 - entropy)`
|
||||
- **UncertaintyScoreCalculator**: `src/Policy/__Libraries/StellaOps.Policy.Determinization/Scoring/UncertaintyScoreCalculator.cs` -- entropy formula: `1.0 - (presentWeight / totalPossibleWeight)` with signal gap tracking
|
||||
- **SignalWeights**: `src/Policy/__Libraries/StellaOps.Policy.Determinization/Scoring/SignalWeights.cs` -- configurable 6-dimension weights: VEX=0.25, EPSS=0.15, Reachability=0.25, Runtime=0.15, Backport=0.10, SBOMLineage=0.10
|
||||
- **K4Lattice trust algebra**: `src/Policy/__Libraries/StellaOps.Policy/TrustLattice/K4Lattice.cs` -- Belnap four-valued logic: Unknown=0, True=1, False=2, Conflict=3; Join, Meet, LessOrEqual
|
||||
- **ClaimScoreMerger**: `src/Policy/__Libraries/StellaOps.Policy/TrustLattice/ClaimScoreMerger.cs` -- deterministic merge with conflict penalization (0.25 penalty), PreferSpecificity, RequireReplayProofOnConflict
|
||||
- **ScorePolicy model**: `src/Policy/__Libraries/StellaOps.Policy/Scoring/ScorePolicyModels.cs` -- 4-factor basis-points scoring: BaseSeverity=1000, Reachability=4500, Evidence=3000, Provenance=1500 (sum=10000)
|
||||
- **ConflictDetector**: `src/Policy/__Libraries/StellaOps.Policy.Determinization/Scoring/ConflictDetector.cs` (306 lines)
|
||||
- **DecayedConfidenceCalculator**: `src/Policy/__Libraries/StellaOps.Policy.Determinization/Scoring/DecayedConfidenceCalculator.cs` -- exponential decay: `max(floor, baseConfidence * exp(-ln(2) * ageDays / halfLifeDays))`
|
||||
- **Trust Verdict Service**: `src/Attestor/__Libraries/StellaOps.Attestor.TrustVerdict/Services/TrustVerdictService.cs` (with `.Scoring`, `.BuildPredicate`, `.Builders`, `.Generate`) -- trust scoring combining origin, freshness, reputation
|
||||
- **Trust Composite**: `TrustVerdict/Predicates/TrustComposite.cs` -- composite trust score model
|
||||
- **Backport Proof Confidence**: `Generators/BackportProofGenerator.Confidence.cs` -- deterministic confidence scoring (Tier1: 0.98, Tier2: 0.80-0.95, Tier3: 0.80-0.90, Tier4: 0.55-0.85)
|
||||
- **Evidence Summary**: `ProofChain/Generators/EvidenceSummary.cs` -- evidence count and type summary
|
||||
- **Reachability Witness Evidence**: `ProofChain/Predicates/MicroWitnessFunctionEvidence.cs` -- reachability evidence inputs for scoring
|
||||
|
||||
## What's Missing
|
||||
- **Unified facade API**: No single `ComputeTrustScore(artifact)` entry point composing TrustScoreAggregator + K4Lattice + ScorePolicy + TrustVerdictService into one deterministic pipeline (the "B+C+D composition" described in advisories)
|
||||
- **Score.v1 predicate format**: No standalone Score.v1 schema combining all scoring dimensions into a single DSSE-signable attestation format
|
||||
- **Basis-point fixed-point arithmetic**: Scoring uses floating-point doubles in some paths, not fixed-point basis-point representation for guaranteed bit-exact determinism across all dimensions
|
||||
- **ScoreGraph concept**: No graph-based score computation where each node contributes to a composite score with typed edges for score propagation
|
||||
- **Score replay verification**: No mechanism to replay a score computation with frozen inputs and verify it matches the original to the last basis point
|
||||
- **Score history and trending**: No persistence of score history for trend analysis over time
|
||||
- **Algebra verification tests**: No property-based tests proving commutativity, associativity, and idempotency of the trust score algebra
|
||||
- **Cross-scanner score normalization**: No normalization layer that maps different scanner confidence outputs to a unified scale
|
||||
- **Score attestation pipeline**: No pipeline producing DSSE-signed Score.v1 attestations as standalone evidence artifacts
|
||||
|
||||
## Implementation Plan
|
||||
- Create `TrustScoreAlgebraFacade` composing TrustScoreAggregator + K4Lattice + ScorePolicy into a single deterministic pipeline
|
||||
- Define Score.v1 predicate schema with basis-point fixed-point representation
|
||||
- Implement basis-point fixed-point arithmetic with determinism guarantees across all scoring paths
|
||||
- Add score replay verification using VerdictReceiptPayload
|
||||
- Add property-based tests proving algebraic invariants (commutativity of merge, idempotency of lattice join)
|
||||
- Create score attestation pipeline producing DSSE-signed Score.v1 attestations
|
||||
- Document the formal algebra specification in `docs/modules/policy/trust-score-algebra.md`
|
||||
- Implement score history persistence with PostgreSQL for trend analysis
|
||||
|
||||
## Related Documentation
|
||||
- Weight manifest: `etc/weights/v2026-01-22.weights.json`
|
||||
- Trust lattice engine: `src/Policy/__Libraries/StellaOps.Policy/TrustLattice/` (15 files)
|
||||
- Determinization library: `src/Policy/__Libraries/StellaOps.Policy.Determinization/`
|
||||
- TrustVerdict: `src/Attestor/__Libraries/StellaOps.Attestor.TrustVerdict/`
|
||||
|
||||
## Merged From
|
||||
- `attestor/deterministic-score-from-reachability-evidence-provenance.md` (deleted)
|
||||
- `attestor/deterministic-trust-score-and-vulnerability-scoring.md` (deleted)
|
||||
- `attestor/deterministic-vulnerability-scoring.md` (deleted)
|
||||
@@ -1,39 +0,0 @@
|
||||
# Determinization Reanalysis Configuration (Persisted Policy Config)
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Persisted configuration for the determinization reanalysis pipeline, controlling how grey-queue unknowns are re-evaluated (interval, thresholds, auto-promote rules). Includes API client and backend persistence for policy-driven reanalysis schedules.
|
||||
|
||||
## Implementation Details
|
||||
- **Determinization Config Store**: `src/Policy/__Libraries/StellaOps.Policy.Determinization/IDeterminizationConfigStore.cs` -- interface for persisted configuration
|
||||
- Sprint: SPRINT_20260112_012_POLICY_determinization_reanalysis_config
|
||||
- Stores reanalysis interval, scoring thresholds, and auto-promote rules
|
||||
- **DeterminizationOptions**: `src/Policy/__Libraries/StellaOps.Policy.Determinization/DeterminizationOptions.cs` -- configuration options
|
||||
- Reanalysis interval (how often grey-queue unknowns are re-evaluated)
|
||||
- Score thresholds for band transitions (Hot->Warm, Warm->Cold, Cold->Resolved)
|
||||
- Auto-promote rules for automatic resolution when criteria are met
|
||||
- **Determinization Evidence**: `src/Policy/__Libraries/StellaOps.Policy.Determinization/Evidence/` -- evidence models for reanalysis decisions
|
||||
- **Determinization Models**: `src/Policy/__Libraries/StellaOps.Policy.Determinization/Models/` -- data models for determinization state
|
||||
- **Determinization Scoring**: `src/Policy/__Libraries/StellaOps.Policy.Determinization/Scoring/` -- scoring models for reanalysis
|
||||
- **Determinization Gate**: `src/Policy/StellaOps.Policy.Engine/Gates/Determinization/DeterminizationGate.cs`
|
||||
- Uses persisted configuration to control gate behavior
|
||||
- Signal snapshot builder captures evaluation state for reproducibility
|
||||
- **Determinization Config Endpoints**: `src/Policy/StellaOps.Policy.Engine/Endpoints/DeterminizationConfigEndpoints.cs` -- REST API for configuration CRUD
|
||||
- GET/PUT configuration for reanalysis schedules
|
||||
- Configuration scoped per tenant
|
||||
- **Service Registration**: `src/Policy/__Libraries/StellaOps.Policy.Determinization/ServiceCollectionExtensions.cs` -- DI registration
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] GET determinization config endpoint; verify default configuration returned with reanalysis interval and thresholds
|
||||
- [ ] PUT determinization config with custom reanalysis interval; verify configuration is persisted
|
||||
- [ ] GET config after PUT; verify updated values are returned
|
||||
- [ ] Verify determinization gate uses persisted configuration (not hardcoded defaults)
|
||||
- [ ] Update auto-promote rules; verify unknowns meeting criteria are automatically promoted
|
||||
- [ ] Update score thresholds; verify band assignment uses new thresholds
|
||||
- [ ] Verify configuration is tenant-scoped: tenant A config does not affect tenant B
|
||||
- [ ] Verify DeterminizationOptions default values are applied when no config is persisted
|
||||
@@ -1,42 +0,0 @@
|
||||
# Diff-Aware Release Gates (Semantic Delta Computation)
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Full delta computation engine that computes semantic diffs across SBOMs, vulnerabilities, and risk scores. Includes component deltas, vulnerability status deltas, and risk score deltas.
|
||||
|
||||
## Implementation Details
|
||||
- **WhatIfSimulationService**: `src/Policy/StellaOps.Policy.Engine/WhatIfSimulation/WhatIfSimulationService.cs` -- computes delta between baseline and hypothetical states
|
||||
- SBOM diff operations: add, remove, upgrade, downgrade
|
||||
- Decision changes: status_changed, severity_changed, new, removed
|
||||
- Risk delta computation: increased/decreased/unchanged with blocked/warning deltas
|
||||
- VEX and reachability override handling in simulated decisions
|
||||
- **DriftGateEvaluator**: `src/Policy/StellaOps.Policy.Engine/Gates/DriftGateEvaluator.cs` -- drift-based gate for cross-release delta
|
||||
- `DriftGateContext.cs` -- drift evaluation context with base/target references
|
||||
- `DriftGateOptions.cs` -- configurable drift thresholds
|
||||
- Evaluates whether drift between releases exceeds acceptable thresholds
|
||||
- **ConsoleSimulationDiffService**: `src/Policy/StellaOps.Policy.Engine/Console/ConsoleSimulationDiffService.cs` -- deterministic delta diff
|
||||
- Before/After severity breakdown, delta (added/removed/regressed), rule impact analysis
|
||||
- **SimulationAnalyticsService**: `src/Policy/StellaOps.Policy.Engine/Simulation/SimulationAnalyticsService.cs` -- delta summary computation with severity escalation tracking
|
||||
- **RiskSimulationService**: `src/Policy/StellaOps.Policy.Engine/Simulation/RiskSimulationService.cs` -- `CompareProfilesWithBreakdown` for profile-level delta
|
||||
- Compares baseline and comparison risk profiles with trend analysis
|
||||
- Top movers analysis: identifies findings with greatest score change
|
||||
- **Effective Decision Map**: `src/Policy/StellaOps.Policy.Engine/EffectiveDecisionMap/` -- materialized baseline decisions for delta comparison
|
||||
- **Overlay Simulation**: `src/Policy/StellaOps.Policy.Engine/Endpoints/OverlaySimulationEndpoint.cs` -- overlay-based simulation
|
||||
- **Merge Preview**: `src/Policy/StellaOps.Policy.Engine/Endpoints/MergePreviewEndpoints.cs` -- merge preview for policy changes
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Run what-if simulation with SBOM upgrade; verify component delta shows version change and advisory resolution
|
||||
- [ ] Run what-if simulation with SBOM downgrade; verify new advisories detected and severity escalated
|
||||
- [ ] Evaluate drift gate with base and target digests; verify gate passes when drift is within threshold
|
||||
- [ ] Evaluate drift gate with excessive drift; verify gate blocks with explanation
|
||||
- [ ] Run console simulation diff; verify severity breakdown before and after policy change
|
||||
- [ ] Compare two risk profiles; verify trend analysis shows score deltas and top movers
|
||||
- [ ] Run overlay simulation; verify hypothetical overlay applied without persisting
|
||||
- [ ] Verify delta summary correctly counts: added, removed, regressed (escalated severity)
|
||||
- [ ] Run merge preview; verify predicted impact of policy merge
|
||||
- [ ] Verify what-if summary recommendation: "risk profile increases" when more blocks, "improves" when fewer
|
||||
@@ -1,37 +0,0 @@
|
||||
# Dry-Run Policy Application API
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Backend support for dry-run policy application with diff preview and rollback plan generation. Not yet implemented.
|
||||
|
||||
## Why Marked as Dropped (Correction)
|
||||
**FINDING: Policy simulation / dry-run IS implemented.** The following exist:
|
||||
- `src/Policy/StellaOps.Policy.Registry/Services/PolicySimulationService.cs` -- core simulation service
|
||||
- `src/Policy/StellaOps.Policy.Registry/Services/IPolicySimulationService.cs` -- interface
|
||||
- `src/Policy/StellaOps.Policy.Registry/Services/BatchSimulationOrchestrator.cs` -- batch simulation support
|
||||
- `src/Policy/StellaOps.Policy.Registry/Services/IBatchSimulationOrchestrator.cs` -- interface
|
||||
- `src/Policy/StellaOps.Policy.Registry/Testing/PolicyRegistryTestHarness.cs` -- test harness
|
||||
- Tools library: `src/__Libraries/StellaOps.Policy.Tools/PolicySimulationSmokeCommand.cs`, `PolicySimulationSmokeModels.cs`, `PolicySimulationSmokeApp.cs`
|
||||
- Web UI dry-run support: setup wizard includes dry-run functionality per `src/Web/StellaOps.Web/src/app/features/setup-wizard/`
|
||||
- Database migration support: `src/__Libraries/StellaOps.Infrastructure.Postgres/Migrations/MigrationRunner.cs` has dry-run mode
|
||||
|
||||
## Implementation Details
|
||||
- Simulation service: `src/Policy/StellaOps.Policy.Registry/Services/PolicySimulationService.cs`
|
||||
- Batch orchestrator: `src/Policy/StellaOps.Policy.Registry/Services/BatchSimulationOrchestrator.cs`
|
||||
- Smoke test tools: `src/__Libraries/StellaOps.Policy.Tools/PolicySimulationSmoke*.cs`
|
||||
- Test harness: `src/Policy/StellaOps.Policy.Registry/Testing/PolicyRegistryTestHarness.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- Verify policy simulation produces expected diff output
|
||||
- Test batch simulation across multiple policies
|
||||
- Validate dry-run mode prevents actual policy application
|
||||
|
||||
## Source
|
||||
- Feature matrix scan
|
||||
|
||||
## Notes
|
||||
- Module: Policy
|
||||
- Modules referenced: `src/Policy/StellaOps.Policy.Registry/`
|
||||
- **Status should be reclassified from NOT_FOUND to IMPLEMENTED**
|
||||
@@ -1,50 +0,0 @@
|
||||
# DSSE-signed reversible decisions (MUTE_REACH, MUTE_VEX, ACK, EXCEPTION)
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
VEX decision signing service produces DSSE-signed decisions; exception objects model scoped, time-boxed exceptions with evidence requirements.
|
||||
|
||||
## Implementation Details
|
||||
- **VerdictAttestationService**: `src/Policy/StellaOps.Policy.Engine/Attestation/VerdictAttestationService.cs` -- signs verdict decisions with DSSE envelopes
|
||||
- `IVerdictAttestationService` interface
|
||||
- `VerdictPredicate.cs` -- verdict predicate for attestation payload
|
||||
- `VerdictPredicateBuilder.cs` -- fluent builder for verdict predicates
|
||||
- `VerdictReasonCode.cs` -- reason codes for verdict decisions
|
||||
- **PolicyDecisionAttestationService**: `src/Policy/StellaOps.Policy.Engine/Attestation/PolicyDecisionAttestationService.cs` -- signs policy decisions
|
||||
- `IPolicyDecisionAttestationService` interface
|
||||
- `PolicyDecisionPredicate.cs` -- decision predicate payload
|
||||
- `PolicyDecisionAttestationOptions.cs` -- signing options
|
||||
- **Exception Objects**: `src/Policy/__Libraries/StellaOps.Policy.Exceptions/Models/ExceptionObject.cs` -- scoped, time-boxed exception model
|
||||
- Scope: CVE-level, package-level, or finding-level
|
||||
- Time-boxing: ExpiresAt, auto-expire enforcement
|
||||
- Evidence requirements: required evidence types per exception
|
||||
- Status: Active, Expired, Revoked
|
||||
- **Exception Application**: `src/Policy/__Libraries/StellaOps.Policy.Exceptions/Models/ExceptionApplication.cs` -- tracks when exceptions are applied to findings
|
||||
- **Exception Events**: `src/Policy/__Libraries/StellaOps.Policy.Exceptions/Models/ExceptionEvent.cs` -- audit trail of exception lifecycle events (create, apply, expire, revoke)
|
||||
- **Evidence Hooks**: `src/Policy/__Libraries/StellaOps.Policy.Exceptions/Models/EvidenceHook.cs` -- hooks for evidence validation on exception approval
|
||||
- **RecheckPolicy**: `src/Policy/__Libraries/StellaOps.Policy.Exceptions/Models/RecheckPolicy.cs` -- recheck policy for exception revalidation
|
||||
- **Exception Evaluator**: `src/Policy/__Libraries/StellaOps.Policy.Exceptions/Services/ExceptionEvaluator.cs` -- evaluates exception applicability
|
||||
- **Evidence Requirement Validator**: `src/Policy/__Libraries/StellaOps.Policy.Exceptions/Services/EvidenceRequirementValidator.cs` -- validates evidence requirements are met
|
||||
- **Recheck Evaluation Service**: `src/Policy/__Libraries/StellaOps.Policy.Exceptions/Services/RecheckEvaluationService.cs` -- periodic recheck of exception validity
|
||||
- **ExceptionRecheckGate**: `src/Policy/StellaOps.Policy.Engine/BuildGate/ExceptionRecheckGate.cs` -- build gate that rechecks exception validity
|
||||
- **RVA Service**: `src/Policy/StellaOps.Policy.Engine/Attestation/RvaService.cs` -- Risk Verdict Attestation service
|
||||
- `RvaBuilder.cs` -- builds RVA attestations
|
||||
- `RvaVerifier.cs` -- verifies RVA attestation integrity
|
||||
- `RvaPredicate.cs` -- RVA predicate model
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Create an exception with ExpiresAt in the future; verify exception is Active
|
||||
- [ ] Apply exception to a finding; verify DSSE-signed decision envelope is produced
|
||||
- [ ] Verify exception application is recorded in ExceptionEvent audit trail
|
||||
- [ ] Wait for exception expiry; verify ExceptionRecheckGate detects expiration and re-evaluates finding
|
||||
- [ ] Create exception with evidence requirements; verify EvidenceRequirementValidator blocks approval when evidence missing
|
||||
- [ ] Verify signed verdict predicate contains: finding ID, CVE, decision, reason code, timestamp
|
||||
- [ ] Verify PolicyDecisionAttestationService signs decisions with correct predicate payload
|
||||
- [ ] Revoke an active exception; verify finding is re-evaluated without exception
|
||||
- [ ] Run RecheckEvaluationService; verify exceptions past recheck policy interval are revalidated
|
||||
- [ ] Verify RvaService builds and verifies Risk Verdict Attestation with scoring determinism
|
||||
@@ -1,40 +0,0 @@
|
||||
# Earned Capacity Replenishment for Risk Budgets
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Extends Risk Budget Management with automated enforcement: BudgetLedger for tracking risk point consumption, BudgetConstraintEnforcer for policy gate integration, and EarnedCapacityReplenishment for automatically restoring budget when vulnerabilities are remediated. Includes PostgreSQL persistence and REST endpoints. Goes beyond the known "Risk Budget Management" (which covers configuration/dashboard) by adding the enforcement automation and earned capacity mechanism.
|
||||
|
||||
## Implementation Details
|
||||
- **Budget Ledger**: `src/Policy/StellaOps.Policy.Engine/Ledger/`
|
||||
- Sprint: SPRINT_20251226_002_BE_budget_enforcement
|
||||
- `LedgerModels.cs` -- ledger entry models for tracking risk point consumption and replenishment
|
||||
- `LedgerExportService.cs` -- export ledger data for audit
|
||||
- `LedgerExportStore.cs` -- persistence for ledger exports
|
||||
- **Budget Endpoints**: `src/Policy/StellaOps.Policy.Engine/Endpoints/BudgetEndpoints.cs` -- REST API for budget operations
|
||||
- Budget status, consumption tracking, and replenishment triggers
|
||||
- **Risk Budget Endpoints**: `src/Policy/StellaOps.Policy.Engine/Endpoints/RiskBudgetEndpoints.cs` -- risk budget management API
|
||||
- Budget configuration, threshold management, and earned capacity rules
|
||||
- **Unknowns Budget Enforcer**: `src/Policy/__Libraries/StellaOps.Policy.Unknowns/UnknownsBudgetEnforcer.cs` -- enforces budget constraints
|
||||
- Tracks Hot/Warm/Cold band consumption against budget limits
|
||||
- Blocks releases when budget is exceeded
|
||||
- **Unknown Budget Service**: `src/Policy/__Libraries/StellaOps.Policy.Unknowns/Services/UnknownBudgetService.cs` -- budget calculation and management
|
||||
- **Unknown Budget Model**: `src/Policy/__Libraries/StellaOps.Policy.Unknowns/Models/UnknownBudget.cs` -- budget configuration with per-band limits
|
||||
- **Verdict Budget Check**: `src/Policy/StellaOps.Policy.Engine/Attestation/VerdictBudgetCheck.cs` -- budget verification during verdict attestation
|
||||
- **Ledger Export Endpoint**: `src/Policy/StellaOps.Policy.Engine/Endpoints/LedgerExportEndpoint.cs` -- REST API for exporting ledger entries
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] GET risk budget status; verify budget shows total capacity, consumed points, and remaining capacity
|
||||
- [ ] Consume risk points by adding a new finding; verify budget consumption increases
|
||||
- [ ] Remediate a vulnerability; verify earned capacity replenishment restores budget points
|
||||
- [ ] Exceed budget limit; verify budget enforcer blocks the release gate
|
||||
- [ ] Verify budget enforcer integrates with policy gate: gate returns Block when budget exceeded
|
||||
- [ ] Export budget ledger; verify ledger contains all consumption and replenishment entries with timestamps
|
||||
- [ ] Configure per-band limits (Hot=10, Warm=25, Cold=100); verify enforcement respects band-specific limits
|
||||
- [ ] Verify verdict attestation includes budget check result
|
||||
- [ ] POST to risk budget endpoint to update capacity; verify new capacity takes effect
|
||||
- [ ] Verify earned capacity calculation: remediated critical finding replenishes more points than low finding
|
||||
@@ -1,36 +0,0 @@
|
||||
# EPSS Raw Feed Layer (Immutable Storage)
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
EPSS feed ingestion with CSV parsing, repository storage, and enrichment jobs. Database migrations exist for EPSS risk scores storage.
|
||||
|
||||
## Implementation Details
|
||||
- **UnknownRanker Integration**: `src/Policy/__Libraries/StellaOps.Policy.Unknowns/Services/UnknownRanker.cs` -- uses EPSS scores in exploit pressure calculation
|
||||
- EPSS >= 0.90: +0.30 exploit pressure factor
|
||||
- EPSS >= 0.50: +0.15 exploit pressure factor
|
||||
- `UnknownRankInput.EpssScore` (decimal 0.0-1.0) feeds into scoring
|
||||
- **Risk Scoring Integration**: `src/Policy/StellaOps.Policy.Engine/Scoring/` -- EPSS scores used in risk profile scoring
|
||||
- `ProfileAwareScoringService.cs` -- includes EPSS in profile-aware scoring
|
||||
- `RiskScoringModels.cs` -- risk scoring models with EPSS data
|
||||
- `RiskScoringTriggerService.cs` -- triggers re-scoring when EPSS data updates
|
||||
- **RiskSimulationService**: `src/Policy/StellaOps.Policy.Engine/Simulation/RiskSimulationService.cs` -- EPSS used as a signal in risk simulations
|
||||
- Categorical signal mapping: EPSS score mapped to signal weight contributions
|
||||
- **Policy Gate Integration**: `src/Policy/StellaOps.Policy.Engine/Gates/PolicyGateEvaluator.cs` -- EPSS thresholds used in gate evaluation
|
||||
- **Staleness Endpoints**: `src/Policy/StellaOps.Policy.Engine/Endpoints/StalenessEndpoints.cs` -- feed staleness monitoring
|
||||
- **Risk Profile Endpoints**: `src/Policy/StellaOps.Policy.Engine/Endpoints/RiskProfileEndpoints.cs` -- profiles include EPSS configuration
|
||||
- **Evidence Weighted Score**: `src/Policy/StellaOps.Policy.Engine/Scoring/EvidenceWeightedScore/` -- EPSS contributes to evidence-weighted scoring
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify EPSS score (0.95) contributes +0.30 exploit pressure factor in unknown ranking
|
||||
- [ ] Verify EPSS score (0.50) contributes +0.15 exploit pressure factor
|
||||
- [ ] Verify EPSS score (0.10) contributes 0 exploit pressure factor (below threshold)
|
||||
- [ ] Verify risk simulation includes EPSS as a signal with weight contribution
|
||||
- [ ] Verify risk scoring trigger fires when EPSS data updates
|
||||
- [ ] Check staleness endpoint for EPSS feed; verify freshness status is reported
|
||||
- [ ] Verify evidence-weighted score includes EPSS contribution
|
||||
- [ ] Verify policy gate evaluates EPSS threshold per configuration
|
||||
@@ -1,39 +0,0 @@
|
||||
# EPSS Threshold Policy Gate
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Policy gate that evaluates EPSS probability thresholds to block or allow releases based on configurable risk bands and delta thresholds.
|
||||
|
||||
## Implementation Details
|
||||
- **PolicyGateEvaluator**: `src/Policy/StellaOps.Policy.Engine/Gates/PolicyGateEvaluator.cs` -- multi-gate evaluation including EPSS-aware gates
|
||||
- EPSS thresholds integrated into evidence and confidence gate evaluation
|
||||
- Gate result types: Pass, PassWithNote, Warn, Block, Skip
|
||||
- **UnknownRanker EPSS Scoring**: `src/Policy/__Libraries/StellaOps.Policy.Unknowns/Services/UnknownRanker.cs` -- EPSS exploit pressure
|
||||
- EPSS >= 0.90: +0.30 (critical exploit likelihood)
|
||||
- EPSS >= 0.50: +0.15 (significant exploit likelihood)
|
||||
- CVSS >= 9.0: +0.05 (additional severity factor)
|
||||
- Combined with KEV status (+0.50) for total exploit pressure
|
||||
- Exploit pressure feeds into band assignment: Hot >= 75, Warm >= 50, Cold >= 25
|
||||
- **Risk Profile Scoring**: `src/Policy/StellaOps.Policy.Engine/Scoring/` -- EPSS as scoring signal
|
||||
- `ScoringProfileService.cs` -- profile configuration includes EPSS weights
|
||||
- `ScorePolicyService.cs` -- EPSS threshold evaluation per policy
|
||||
- `IScoringEngine.cs` interface with EPSS-aware implementations
|
||||
- **CVSS + EPSS Combined Scoring**: `src/Policy/StellaOps.Policy.Scoring/` -- CVSS and EPSS used together
|
||||
- CVSS provides severity; EPSS provides exploit probability
|
||||
- Combined score informs gate decisions
|
||||
- **Risk Budget Integration**: EPSS-driven unknowns affect budget consumption
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Configure EPSS threshold gate at 0.80; evaluate finding with EPSS=0.85; verify gate blocks
|
||||
- [ ] Configure EPSS threshold gate at 0.80; evaluate finding with EPSS=0.50; verify gate allows
|
||||
- [ ] Verify EPSS + KEV combination: KEV=true with EPSS=0.95 produces exploit pressure 0.80 (0.50+0.30)
|
||||
- [ ] Verify EPSS + KEV combination: KEV=true with EPSS=0.50 produces exploit pressure 0.65 (0.50+0.15)
|
||||
- [ ] Verify HOT band assignment for finding with total score >= 75 (high EPSS + high uncertainty)
|
||||
- [ ] Verify band transition from WARM to HOT when EPSS score increases above 0.90
|
||||
- [ ] Verify EPSS delta: finding with rising EPSS triggers re-evaluation
|
||||
- [ ] Verify scoring profile weights EPSS contribution correctly
|
||||
@@ -1,46 +0,0 @@
|
||||
# Evidence Freshness and Time-Decay Scoring
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Evidence freshness calculation with time-decay models and freshness-aware scoring service, matching the advisory's half-life decay model.
|
||||
|
||||
## Implementation Details
|
||||
- **EvidenceTtlEnforcer**: `src/Policy/__Libraries/StellaOps.Policy/Freshness/EvidenceTtlEnforcer.cs` -- `EvidenceTtlEnforcer` (sealed class implements `IEvidenceTtlEnforcer`)
|
||||
- `CheckFreshness(bundle, asOf)` checks freshness of all evidence in a bundle
|
||||
- Evidence types checked: Reachability (ComputedAt), CallStack (CapturedAt), VEX (Timestamp), SBOM/Provenance (BuildTime), Boundary (ObservedAt)
|
||||
- Freshness statuses: Fresh, Warning, Stale
|
||||
- Overall status: Stale if any stale, Warning if any warning, else Fresh
|
||||
- Configurable stale action: Warn or Block via `EvidenceTtlOptions.StaleAction`
|
||||
- `GetTtl(type)` returns TTL for specific evidence type
|
||||
- `ComputeExpiration(type, createdAt)` computes expiration timestamp
|
||||
- **EvidenceTtlOptions**: `src/Policy/__Libraries/StellaOps.Policy/Freshness/EvidenceTtlOptions.cs` -- TTL configuration per evidence type
|
||||
- Per-type TTL durations (e.g., reachability analysis valid for 7 days, VEX for 30 days)
|
||||
- Configurable staleness action (warn vs block)
|
||||
- **UnknownRanker Time Decay**: `src/Policy/__Libraries/StellaOps.Policy.Unknowns/Services/UnknownRanker.cs`
|
||||
- Decay buckets with basis points: 7d=100%, 30d=90%, 90d=75%, 180d=60%, 365d=40%, >365d=20%
|
||||
- Applied multiplicatively: `decayedScore = rawScore * decayFactor`
|
||||
- Configurable via `UnknownRankerOptions.DecayBuckets`
|
||||
- `ComputeDecayFactor(input)` selects bucket based on days since LastEvaluatedAt
|
||||
- **Evidence Weighted Score**: `src/Policy/StellaOps.Policy.Engine/Scoring/EvidenceWeightedScore/`
|
||||
- `EvidenceWeightedScoreEnricher.cs` -- enriches findings with evidence-weighted scores
|
||||
- `ConfidenceToEwsAdapter.cs` -- adapts confidence scores to evidence-weighted format
|
||||
- `DualEmitVerdictEnricher.cs` -- dual emission for migration period
|
||||
- `PolicyEvidenceWeightedScoreOptions.cs` -- configurable weights per evidence type
|
||||
- **Staleness Endpoints**: `src/Policy/StellaOps.Policy.Engine/Endpoints/StalenessEndpoints.cs` -- REST API for checking evidence freshness
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Check freshness with all evidence types within TTL; verify overall status is Fresh
|
||||
- [ ] Check freshness with reachability evidence older than TTL; verify overall status is Stale
|
||||
- [ ] Check freshness with VEX evidence approaching TTL; verify Warning status
|
||||
- [ ] Verify GetTtl returns configured TTL for each evidence type
|
||||
- [ ] Verify ComputeExpiration: evidence created now with 7-day TTL expires in 7 days
|
||||
- [ ] Rank unknown last evaluated 90 days ago; verify decay factor is 0.75 (7500 bps)
|
||||
- [ ] Rank unknown last evaluated 365 days ago; verify decay factor is 0.40 (4000 bps)
|
||||
- [ ] Verify decay disabled when EnableDecay=false (decay factor always 1.0)
|
||||
- [ ] GET staleness endpoint; verify freshness status for all evidence types
|
||||
- [ ] Verify evidence-weighted score includes freshness-adjusted confidence
|
||||
@@ -1,41 +0,0 @@
|
||||
# Evidence Hooks for Exception Approval
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Requires specific attestations before exception approval with 7 evidence types (feature flag disabled, backport merged, compensating control, security review, runtime mitigation, WAF rule deployed, custom attestation). Validates evidence freshness (MaxAge), trust score, DSSE signature verification, and schema compliance. Mandatory hooks block approval until satisfied.
|
||||
|
||||
## Implementation Details
|
||||
- **EvidenceHook Model**: `src/Policy/__Libraries/StellaOps.Policy.Exceptions/Models/EvidenceHook.cs`
|
||||
- Sprint: SPRINT_3900_0003_0002_recheck_policy_evidence_hooks
|
||||
- Evidence types: feature_flag_disabled, backport_merged, compensating_control, security_review, runtime_mitigation, waf_rule_deployed, custom_attestation
|
||||
- Mandatory flag: blocks exception approval until hook is satisfied
|
||||
- MaxAge: maximum evidence age for freshness validation
|
||||
- Trust score threshold: minimum trust score for evidence acceptance
|
||||
- DSSE signature verification: requires valid signature on evidence attestation
|
||||
- Schema compliance: validates evidence against expected schema
|
||||
- **EvidenceRequirementValidator**: `src/Policy/__Libraries/StellaOps.Policy.Exceptions/Services/EvidenceRequirementValidator.cs`
|
||||
- Validates all required evidence is present and valid
|
||||
- Checks freshness (evidence age vs MaxAge)
|
||||
- Checks trust score against threshold
|
||||
- Checks DSSE signature verification status
|
||||
- Returns validation result with per-hook pass/fail status
|
||||
- **ExceptionObject**: `src/Policy/__Libraries/StellaOps.Policy.Exceptions/Models/ExceptionObject.cs` -- contains evidence hook configuration
|
||||
- **ExceptionEvaluator**: `src/Policy/__Libraries/StellaOps.Policy.Exceptions/Services/ExceptionEvaluator.cs` -- evaluates exception with hooks
|
||||
- **RecheckPolicy**: `src/Policy/__Libraries/StellaOps.Policy.Exceptions/Models/RecheckPolicy.cs` -- recheck policy including evidence hook revalidation
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Configure exception with mandatory evidence hook (security_review); attempt approval without evidence; verify blocked
|
||||
- [ ] Provide security_review attestation; verify exception approval succeeds
|
||||
- [ ] Provide evidence with age exceeding MaxAge; verify freshness validation fails
|
||||
- [ ] Provide evidence with trust score below threshold; verify trust validation fails
|
||||
- [ ] Provide evidence without DSSE signature when signature required; verify signature validation fails
|
||||
- [ ] Configure 3 hooks (2 mandatory, 1 optional); satisfy mandatory hooks only; verify approval succeeds
|
||||
- [ ] Configure custom_attestation hook with schema; provide non-compliant evidence; verify schema validation fails
|
||||
- [ ] Verify all 7 evidence types are accepted by the validator
|
||||
- [ ] Recheck exception after evidence expires (MaxAge exceeded); verify recheck fails
|
||||
- [ ] Verify EvidenceRequirementValidator returns per-hook pass/fail status in result
|
||||
@@ -1,38 +0,0 @@
|
||||
# Evidence Requirement Validation for Exceptions
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Validates that exceptions include required evidence (attestation IDs, VEX notes, reachability proofs) before approval.
|
||||
|
||||
## Implementation Details
|
||||
- **EvidenceRequirementValidator**: `src/Policy/__Libraries/StellaOps.Policy.Exceptions/Services/EvidenceRequirementValidator.cs`
|
||||
- Validates all required evidence is present for exception approval
|
||||
- Checks: attestation IDs, VEX notes, reachability proofs, security review evidence
|
||||
- Evidence freshness validation: age vs MaxAge threshold
|
||||
- Trust score validation: minimum score for evidence acceptance
|
||||
- DSSE signature verification: validates signed evidence
|
||||
- Returns detailed validation result with per-requirement status
|
||||
- **ExceptionObject**: `src/Policy/__Libraries/StellaOps.Policy.Exceptions/Models/ExceptionObject.cs` -- exception model with evidence requirements
|
||||
- Required evidence types defined per exception scope
|
||||
- Scopes: CVE-level, package-level, finding-level
|
||||
- **EvidenceHook**: `src/Policy/__Libraries/StellaOps.Policy.Exceptions/Models/EvidenceHook.cs` -- evidence hook configuration
|
||||
- Mandatory flag, MaxAge, trust score threshold, DSSE requirement
|
||||
- **ExceptionEvaluator**: `src/Policy/__Libraries/StellaOps.Policy.Exceptions/Services/ExceptionEvaluator.cs` -- evaluates exception applicability with evidence checks
|
||||
- **ExceptionApplication**: `src/Policy/__Libraries/StellaOps.Policy.Exceptions/Models/ExceptionApplication.cs` -- tracks exception applications with evidence snapshot
|
||||
- **Exception Repositories**: `src/Policy/__Libraries/StellaOps.Policy.Exceptions/Repositories/` -- persistence for exceptions and evidence
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Create exception requiring attestation ID; verify validation fails when attestation ID is missing
|
||||
- [ ] Create exception requiring VEX note; provide valid VEX note; verify validation passes
|
||||
- [ ] Create exception requiring reachability proof; provide proof; verify validation passes
|
||||
- [ ] Validate evidence with expired MaxAge; verify freshness check fails
|
||||
- [ ] Validate evidence with trust score below minimum; verify trust check fails
|
||||
- [ ] Create exception with multiple required evidence types; provide all; verify validation passes
|
||||
- [ ] Create exception with multiple required evidence types; omit one; verify validation fails with specific missing requirement
|
||||
- [ ] Verify ExceptionApplication records the evidence snapshot at time of application
|
||||
- [ ] Verify exception evaluator checks evidence requirements before determining applicability
|
||||
@@ -1,65 +0,0 @@
|
||||
# Evidence-Weighted Score (EWS) Model (6-Dimension Scoring)
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Scoring infrastructure with policy-driven weights, profiles, and explanations exists. The advisory proposed a new unified 6-dimension model (RCH/RTS/BKP/XPL/SRC/MIT) to replace 4 independent scoring systems. Core normalizers and guardrails engine appear partially built; full unification is in progress.
|
||||
|
||||
## What's Implemented
|
||||
- **SignalWeights (6-dimension)**: `src/Policy/__Libraries/StellaOps.Policy.Determinization/Scoring/SignalWeights.cs`
|
||||
- 6 signal dimensions: VexWeight=0.25, EpssWeight=0.15, ReachabilityWeight=0.25, RuntimeWeight=0.15, BackportWeight=0.10, SbomLineageWeight=0.10
|
||||
- `TotalWeight` computed property, `IsNormalized(tolerance)` validation
|
||||
- **Weight manifest file**: `etc/weights/v2026-01-22.weights.json`
|
||||
- Legacy 6-dimension weights: RCH=0.30, RTS=0.25, BKP=0.15, XPL=0.15, SRC=0.10, MIT=0.10
|
||||
- Advisory 5-dimension weights: CVSS=0.25, EPSS=0.30, Reachability=0.20, ExploitMaturity=0.10, PatchProof=0.15
|
||||
- Guardrails: notAffectedCap (maxScore=15), runtimeFloor (minScore=60), speculativeCap (maxScore=45)
|
||||
- Buckets: actNowMin=90, scheduleNextMin=70, investigateMin=40
|
||||
- Subtractive dimensions: MIT, patchProof
|
||||
- **ScoringRulesSnapshot**: `src/Policy/__Libraries/StellaOps.Policy/Scoring/ScoringRulesSnapshot.cs`
|
||||
- 6-category ScoringWeights: Vulnerability=0.25, Exploitability=0.20, Reachability=0.20, Compliance=0.15, SupplyChain=0.10, Mitigation=0.10
|
||||
- GradeThresholds (A>=90, B>=80, C>=70, D>=60, F<60)
|
||||
- SeverityMultipliers: Critical=1.5, High=1.2, Medium=1.0, Low=0.8, Informational=0.5
|
||||
- FreshnessDecayConfig: sbomDecayStartHours=168, feedDecayStartHours=24, decayRatePerHour=0.001, minimumFreshness=0.5
|
||||
- CustomScoringRule support (Rego/SPL)
|
||||
- Content-addressed digest via SHA256
|
||||
- **ScoringProfile enum**: `src/Policy/__Libraries/StellaOps.Policy/Scoring/ScoringProfile.cs`
|
||||
- Simple (4-factor basis-points), Advanced (entropy + CVSS hybrid), Custom (user Rego)
|
||||
- **ScorePolicy (4-factor)**: `src/Policy/__Libraries/StellaOps.Policy/Scoring/ScorePolicyModels.cs`
|
||||
- WeightsBps: BaseSeverity=1000, Reachability=4500, Evidence=3000, Provenance=1500 (sum=10000)
|
||||
- ReachabilityPolicyConfig with HopBuckets and GateMultipliersBps
|
||||
- EvidencePolicyConfig with FreshnessBuckets (7d=100%, 30d=90%, 90d=70%, 180d=50%, 365d=30%, >1y=10%)
|
||||
- ProvenanceLevels: Unsigned=0, Signed=30, SignedWithSbom=60, SignedWithSbomAndAttestations=80, Reproducible=100
|
||||
- **ScorePolicyLoader**: `src/Policy/__Libraries/StellaOps.Policy/Scoring/ScorePolicyLoader.cs`
|
||||
- YAML loading with version validation ("score.v1"), weight sum validation (10000 bps)
|
||||
- **ScorePolicyValidator**: `src/Policy/__Libraries/StellaOps.Policy/Scoring/ScorePolicyValidator.cs`
|
||||
- JSON Schema validation against embedded score.v1 schema
|
||||
- **ScoreExplanation**: `src/Policy/__Libraries/StellaOps.Policy/Scoring/ScoreExplanation.cs`
|
||||
- Factor-based explanations: reachability (hops), evidence (points + freshness), provenance (level), baseSeverity (CVSS)
|
||||
- ScoreExplainBuilder with deterministic output (sorted by factor name)
|
||||
- **TrustSourceWeightService**: `src/Policy/__Libraries/StellaOps.Policy/Scoring/TrustSourceWeights.cs`
|
||||
- 14 KnownSources with per-source weights (NVD=0.90, CISA-KEV=0.98, OSV=0.75, etc.)
|
||||
- 7 SourceCategory weights (Government=0.95, Vendor=0.85, Distro=0.82, Community=0.70)
|
||||
- Modifiers: signed data boost (1.05x), stale data penalty (>7d: 0.95x, >30d: 0.90x)
|
||||
- Corroboration boost when multiple sources agree (1.1x per corroborating source, max 3)
|
||||
- WeightedMergeResult with weighted CVSS averaging
|
||||
|
||||
## What's Missing
|
||||
- **Unified 6-dimension RCH/RTS/BKP/XPL/SRC/MIT model**: The weight manifest defines both "legacy" (6D) and "advisory" (5D) weight sets, but there is no single unified normalizer that maps all signal inputs to the canonical 6-dimension space
|
||||
- **Dimension normalizers**: Individual signal-to-dimension normalization functions (e.g., raw EPSS probability -> XPL dimension score 0-100) are not formalized as pluggable normalizer interfaces
|
||||
- **Guardrails engine enforcement**: Weight manifest defines guardrails (notAffectedCap, runtimeFloor, speculativeCap) but the runtime engine that enforces these caps/floors during scoring is not confirmed as a standalone service
|
||||
- **Weight manifest loader integration**: `FileBasedWeightManifestLoader` exists in `src/Signals/StellaOps.Signals/EvidenceWeightedScore/` and `ScoringManifestVersioner` exists in `src/__Libraries/StellaOps.DeltaVerdict/Manifest/`, but neither is wired into the Policy scoring pipeline
|
||||
|
||||
## Implementation Plan
|
||||
- Create `EwsDimensionNormalizer` interface with implementations for each of the 6 dimensions
|
||||
- Build `GuardrailsEngine` that applies caps/floors from the weight manifest after scoring
|
||||
- Add `WeightManifestLoader` with version discovery, schema validation, and content-hash verification
|
||||
- Unify the two weight systems (legacy 6D + advisory 5D) into a single configurable scoring pipeline
|
||||
|
||||
## Related Documentation
|
||||
- Weight manifest: `etc/weights/v2026-01-22.weights.json`
|
||||
- Scoring rules snapshot: `src/Policy/__Libraries/StellaOps.Policy/Scoring/ScoringRulesSnapshot.cs`
|
||||
- Determinization scoring: `src/Policy/__Libraries/StellaOps.Policy.Determinization/Scoring/`
|
||||
@@ -1,36 +0,0 @@
|
||||
# Exception Application Audit Trail (policy.exception_applications)
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Records every instance of an exception being applied to a finding in a dedicated `policy.exception_applications` table, capturing exception ID, finding context, original and applied status, purl, vulnerability ID, and evaluation run ID. Exposed via ledger export for compliance.
|
||||
|
||||
## Implementation Details
|
||||
- **ExceptionApplication Model**: `src/Policy/__Libraries/StellaOps.Policy.Exceptions/Models/ExceptionApplication.cs`
|
||||
- Sealed record with fields: Id (Guid), TenantId, ExceptionId, FindingId, VulnerabilityId, OriginalStatus, AppliedStatus, EffectName, EffectType, EvaluationRunId, PolicyBundleDigest, AppliedAt, Metadata
|
||||
- `Create()` static factory method enforces non-null ExceptionId/FindingId, accepts deterministic applicationId and appliedAt timestamps
|
||||
- Metadata stored as `ImmutableDictionary<string, string>` for extensibility
|
||||
- **IExceptionApplicationRepository**: `src/Policy/__Libraries/StellaOps.Policy.Exceptions/Repositories/IExceptionApplicationRepository.cs`
|
||||
- `RecordAsync(application)` -- persists a single application record
|
||||
- `RecordBatchAsync(applications)` -- bulk persist for batch evaluation
|
||||
- Query by ExceptionId, FindingId, VulnerabilityId, EvaluationRunId, TimeRange
|
||||
- `GetStatisticsAsync(tenantId, filter?)` returns `ExceptionApplicationStatistics` (TotalApplications, UniqueExceptions, UniqueFindings, UniqueVulnerabilities, ByEffectType counts, ByAppliedStatus counts, EarliestApplication, LatestApplication)
|
||||
- `CountAsync(tenantId, filter?)` for total count with optional filter
|
||||
- `ExceptionApplicationFilter` record supports paging (Limit/Offset), date range (FromDate/ToDate), and field filters
|
||||
- **PostgresExceptionApplicationRepository**: `src/Policy/__Libraries/StellaOps.Policy.Exceptions/Repositories/PostgresExceptionApplicationRepository.cs` -- Postgres persistence for the `policy.exception_applications` table
|
||||
- **ExceptionEvaluator**: `src/Policy/__Libraries/StellaOps.Policy.Exceptions/Services/ExceptionEvaluator.cs` -- creates ExceptionApplication records when exceptions match findings during policy evaluation
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Apply exception to finding; query `GetByExceptionIdAsync(tenantId, exceptionId)`; verify record includes correct ExceptionId, FindingId, OriginalStatus, AppliedStatus, EffectName, EffectType
|
||||
- [ ] Apply exception with VulnerabilityId; query `GetByVulnerabilityIdAsync(tenantId, vulnId)`; verify record returned with correct VulnerabilityId
|
||||
- [ ] Apply exception during batch evaluation; verify EvaluationRunId is populated; query `GetByEvaluationRunIdAsync(tenantId, runId)` and verify all applications for that run
|
||||
- [ ] Apply exception; verify AppliedAt timestamp matches evaluation time (deterministic)
|
||||
- [ ] Apply exception with PolicyBundleDigest; verify digest is recorded in the application record
|
||||
- [ ] Call `RecordBatchAsync` with 5 applications; verify all 5 are persisted
|
||||
- [ ] Call `GetByTimeRangeAsync(tenantId, from, to)` with a range encompassing 3 applications; verify exactly 3 returned
|
||||
- [ ] Call `GetStatisticsAsync(tenantId)` after 10 applications across 3 exceptions and 5 findings; verify TotalApplications=10, UniqueExceptions=3, UniqueFindings=5, ByEffectType counts sum to 10
|
||||
- [ ] Call `CountAsync(tenantId, filter)` with EffectType="suppress" filter; verify count matches expected
|
||||
@@ -1,39 +0,0 @@
|
||||
# Exception Effect Registry (Type-to-Effect Mapping)
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Registry mapping (ExceptionType + ExceptionReason) pairs to policy effects (Suppress, Defer, RequireControl). Covers 11 predefined mappings including false_positive, wont_fix, vendor_pending, compensating_control, license_waiver, etc. Extensible via DI configuration with max-duration constraints.
|
||||
|
||||
## Implementation Details
|
||||
- **ExceptionEffectRegistry**: `src/Policy/StellaOps.Policy.Engine/Adapters/ExceptionEffectRegistry.cs` (sealed class implements `IExceptionEffectRegistry`)
|
||||
- Uses `FrozenDictionary<(ExceptionType, ExceptionReason), PolicyExceptionEffect>` for immutable O(1) lookups
|
||||
- `GetEffect(type, reason)` returns effect for type+reason pair; falls back to `defer-default` effect if unmapped
|
||||
- `GetAllEffects()` returns all registered effects
|
||||
- `GetEffectById(effectId)` returns effect by ID (case-insensitive lookup)
|
||||
- 8 distinct effect templates: suppress, defer, require-control, downgrade-low, downgrade-medium, defer-vendor, suppress-deprecation, suppress-license
|
||||
- 40 total mappings across 4 ExceptionTypes (Vulnerability, Policy, Unknown, Component) x 10 ExceptionReasons
|
||||
- `PolicyExceptionEffectType` enum: Suppress, Defer, Downgrade, RequireControl
|
||||
- MaxDurationDays per effect: suppress=365, defer=90, require-control=180, downgrade=365, defer-vendor=180, suppress-deprecation=90, suppress-license=365, defer-default=30
|
||||
- RoutingTemplate per effect for workflow routing (e.g., "deferred-review", "control-verification", "vendor-tracking", "legal-review", "manual-review")
|
||||
- **ExceptionType enum**: `src/Policy/__Libraries/StellaOps.Policy.Exceptions/Models/ExceptionObject.cs`
|
||||
- Vulnerability, Policy, Unknown, Component
|
||||
- **ExceptionReason enum**: same file
|
||||
- FalsePositive, AcceptedRisk, CompensatingControl, TestOnly, VendorNotAffected, ScheduledFix, DeprecationInProgress, RuntimeMitigation, NetworkIsolation, Other
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] `GetEffect(Vulnerability, FalsePositive)` returns effect with Id="suppress", Effect=Suppress, MaxDurationDays=365
|
||||
- [ ] `GetEffect(Vulnerability, CompensatingControl)` returns effect with Id="require-control", Effect=RequireControl, RequiredControlId="compensating-control-verification"
|
||||
- [ ] `GetEffect(Vulnerability, RuntimeMitigation)` returns effect with Id="downgrade-low", Effect=Downgrade, DowngradeSeverity=Low
|
||||
- [ ] `GetEffect(Vulnerability, NetworkIsolation)` returns effect with Id="downgrade-medium", DowngradeSeverity=Medium
|
||||
- [ ] `GetEffect(Vulnerability, ScheduledFix)` returns effect with Id="defer", Effect=Defer, MaxDurationDays=90
|
||||
- [ ] `GetEffect(Component, DeprecationInProgress)` returns effect with Id="suppress-deprecation", MaxDurationDays=90
|
||||
- [ ] `GetEffect(Component, Other)` returns effect with Id="suppress-license", RoutingTemplate="legal-review"
|
||||
- [ ] `GetEffect(Vulnerability, VendorNotAffected)` returns effect with Id="suppress"
|
||||
- [ ] `GetEffectById("require-control")` returns non-null effect with matching ID
|
||||
- [ ] `GetAllEffects()` returns exactly 8 distinct effects (suppress, defer, require-control, downgrade-low, downgrade-medium, defer-vendor, suppress-deprecation, suppress-license)
|
||||
- [ ] Unmapped type/reason pair (if any) returns defer-default with MaxDurationDays=30, RoutingTemplate="manual-review"
|
||||
@@ -1,34 +0,0 @@
|
||||
# Exception Recheck Build Gate
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
CI/CD build gate that evaluates recheck policies for all active exceptions on an artifact before deployment. Fails the pipeline if any Block-action conditions are triggered (e.g., EPSS exceeds threshold, KEV flagged). Returns warnings for non-blocking conditions.
|
||||
|
||||
## Implementation Details
|
||||
- **ExceptionRecheckGate**: `src/Policy/StellaOps.Policy.Engine/BuildGate/ExceptionRecheckGate.cs` (sealed class implements `IBuildGate`)
|
||||
- GateName: `"exception-recheck"`, Priority: 100
|
||||
- `EvaluateAsync(BuildGateContext)` evaluates all active exceptions for the artifact
|
||||
- Uses `IExceptionEvaluator` to find matching exceptions, then `IRecheckEvaluationService` to evaluate recheck conditions
|
||||
- Aggregates blockers (Block, Revoke, RequireReapproval actions) and warnings (Warn action)
|
||||
- Returns `BuildGateResult` with Passed=false if any blockers exist; Passed=true otherwise
|
||||
- Message includes blocker details: `"Recheck policy blocking: {details}"`
|
||||
- **IBuildGate interface**: defined in same file
|
||||
- `GateName` (string), `Priority` (int), `EvaluateAsync(BuildGateContext, CancellationToken)`
|
||||
- **BuildGateContext**: record with ArtifactDigest, Environment, Branch, PipelineId, TenantId, EvaluatedAt, and all recheck signal fields (ReachGraphChanged, EpssScore, CvssScore, UnknownsCount, NewCveInPackage, KevFlagged, VexStatusChanged, PackageVersionChanged)
|
||||
- **BuildGateResult**: record with Passed, GateName, Message, Blockers (`ImmutableArray<string>`), Warnings (`ImmutableArray<string>`)
|
||||
- **RecheckEvaluationService**: `src/Policy/__Libraries/StellaOps.Policy.Exceptions/Services/RecheckEvaluationService.cs` -- evaluates recheck conditions (see exception-recheck-policy-system feature)
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Create exception with RecheckPolicy containing EPSSAbove=0.80 (Block action); set EpssScore=0.85 in BuildGateContext; verify EvaluateAsync returns Passed=false with blocker message mentioning EPSS
|
||||
- [ ] Create exception with RecheckPolicy containing KEVFlagged (Block action); set KevFlagged=true; verify gate returns Passed=false
|
||||
- [ ] Create exception with no RecheckPolicy; verify gate returns Passed=true with message "All exception recheck policies satisfied"
|
||||
- [ ] Create exception with RecheckPolicy containing CVSSAbove=9.0 (Warn action); set CvssScore=9.5; verify gate returns Passed=true with 1 warning
|
||||
- [ ] Create 2 exceptions: one with Block condition triggered, one with Warn condition triggered; verify gate returns Passed=false with 1 blocker and 1 warning
|
||||
- [ ] Create exception with environment-scoped condition (prod only); evaluate in staging; verify condition does not trigger
|
||||
- [ ] Create exception with RequireReapproval action triggered; verify it is classified as a blocker (not a warning)
|
||||
- [ ] Verify gate includes exception ID in blocker/warning messages for traceability
|
||||
@@ -1,52 +0,0 @@
|
||||
# Exception Recheck Policy System
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Auto-invalidation policies for exceptions with 9 condition types (EPSS threshold, CVSS threshold, reachability graph change, unknowns budget, new CVE in package, KEV flagging, expiry proximity, VEX status change, package version change). Actions: Warn, RequireReapproval, Revoke, Block. Environment-scoped conditions with per-condition action overrides.
|
||||
|
||||
## Implementation Details
|
||||
- **RecheckPolicy**: `src/Policy/__Libraries/StellaOps.Policy.Exceptions/Models/RecheckPolicy.cs` (sealed record)
|
||||
- PolicyId, Name, Conditions (`ImmutableArray<RecheckCondition>`), DefaultAction, IsActive, CreatedAt
|
||||
- **RecheckCondition**: same file (sealed record)
|
||||
- Type (`RecheckConditionType`), Threshold (decimal?), EnvironmentScope (`ImmutableArray<string>`), Action (per-condition override, nullable), Description
|
||||
- **RecheckConditionType enum** (9 types):
|
||||
- `ReachGraphChange` -- reachability graph changes (new paths discovered)
|
||||
- `EPSSAbove` -- EPSS score exceeds threshold
|
||||
- `CVSSAbove` -- CVSS score exceeds threshold
|
||||
- `UnknownsAbove` -- unknown budget exceeds threshold
|
||||
- `NewCVEInPackage` -- new CVE added to same package
|
||||
- `KEVFlagged` -- KEV flag set
|
||||
- `ExpiryWithin` -- exception nearing expiry (days before)
|
||||
- `VEXStatusChange` -- VEX status changes
|
||||
- `PackageVersionChange` -- package version changes
|
||||
- **RecheckAction enum**: Warn (priority 1), RequireReapproval (priority 2), Revoke (priority 3), Block (priority 4)
|
||||
- **RecheckEvaluationService**: `src/Policy/__Libraries/StellaOps.Policy.Exceptions/Services/RecheckEvaluationService.cs` (sealed class implements `IRecheckEvaluationService`)
|
||||
- `EvaluateAsync(exception, context)` iterates conditions, checks environment scope, evaluates each condition type
|
||||
- Returns `RecheckEvaluationResult` with IsTriggered, TriggeredConditions, RecommendedAction (highest priority among triggered)
|
||||
- Environment scoping: condition applies only if EnvironmentScope is empty or contains the evaluation environment
|
||||
- Per-condition action override: uses condition.Action if set, otherwise falls back to policy DefaultAction
|
||||
- Action priority ordering: Block (4) > Revoke (3) > RequireReapproval (2) > Warn (1)
|
||||
- **RecheckEvaluationResult**: sealed record with IsTriggered, TriggeredConditions (`ImmutableArray<TriggeredCondition>`), RecommendedAction, EvaluatedAt, Summary
|
||||
- **TriggeredCondition**: record with Type, Description, CurrentValue, ThresholdValue, Action
|
||||
- **ExceptionObject integration**: `src/Policy/__Libraries/StellaOps.Policy.Exceptions/Models/ExceptionObject.cs`
|
||||
- `RecheckPolicy?` property on ExceptionObject
|
||||
- `LastRecheckResult?` and `LastRecheckAt?` for tracking last evaluation
|
||||
- `IsBlockedByRecheck` computed property (triggered + Block action)
|
||||
- `RequiresReapproval` computed property (triggered + RequireReapproval action)
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Configure RecheckPolicy with EPSSAbove=0.80 (Block); provide context with EpssScore=0.85; verify IsTriggered=true, RecommendedAction=Block, TriggeredConditions contains EPSSAbove with CurrentValue=0.85 and ThresholdValue=0.80
|
||||
- [ ] Configure RecheckPolicy with CVSSAbove=9.0 (Warn); provide context with CvssScore=8.5; verify IsTriggered=false
|
||||
- [ ] Configure RecheckPolicy with KEVFlagged (Revoke); provide context with KevFlagged=true; verify IsTriggered=true, RecommendedAction=Revoke
|
||||
- [ ] Configure RecheckPolicy with ExpiryWithin=7 days (Warn); exception expires in 5 days; verify triggered with CurrentValue~5 and ThresholdValue=7
|
||||
- [ ] Configure RecheckPolicy with 2 conditions: EPSSAbove=0.50 (Warn) and KEVFlagged (Block); trigger both; verify RecommendedAction=Block (highest priority)
|
||||
- [ ] Configure condition with EnvironmentScope=["prod"]; evaluate in "staging"; verify condition is NOT triggered
|
||||
- [ ] Configure condition with EnvironmentScope=["prod"]; evaluate in "prod"; verify condition IS triggered
|
||||
- [ ] Configure condition with per-condition Action=RequireReapproval overriding policy DefaultAction=Warn; verify triggered condition uses RequireReapproval
|
||||
- [ ] Configure RecheckPolicy with ReachGraphChange condition; provide context with ReachGraphChanged=true; verify triggered
|
||||
- [ ] Configure all 9 condition types; trigger each one individually; verify each produces correct TriggeredCondition type
|
||||
@@ -1,46 +0,0 @@
|
||||
# Exception System (API, Lifecycle, Policy Integration, Evidence-Backed Workflow)
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Full exception system: CRUD API with query by scope/owner/expiry/environment, auto-expiry with lifecycle state transitions and background workers, policy engine integration (deterministic outcome alteration with recheck gate), and auditable workflow with entity model (scope, subject, evidence refs, expiry), evidence requirement validation, and persistence (Postgres + in-memory).
|
||||
|
||||
## Implementation Details
|
||||
- **ExceptionObject**: `src/Policy/__Libraries/StellaOps.Policy.Exceptions/Models/ExceptionObject.cs` (sealed record)
|
||||
- Id format: `EXC-{ulid}`, Version (optimistic concurrency), Status, Type, Scope, OwnerId, RequesterId, ApproverIds, CreatedAt, UpdatedAt, ApprovedAt, ExpiresAt (required, max 1 year), ReasonCode, Rationale (min 50 chars), EvidenceRefs (sha256 or attestation URIs), EvidenceRequirements, CompensatingControls, Metadata, TicketRef, RecheckPolicyId, RecheckPolicy, LastRecheckResult, LastRecheckAt
|
||||
- `IsEffectiveAt(referenceTime)` -- Active status AND not expired
|
||||
- `HasExpiredAt(referenceTime)` -- referenceTime >= ExpiresAt
|
||||
- `IsBlockedByRecheck` / `RequiresReapproval` computed properties
|
||||
- **ExceptionStatus enum**: Proposed -> Approved -> Active -> Expired/Revoked (governed state machine)
|
||||
- **ExceptionType enum**: Vulnerability, Policy, Unknown, Component
|
||||
- **ExceptionReason enum**: FalsePositive, AcceptedRisk, CompensatingControl, TestOnly, VendorNotAffected, ScheduledFix, DeprecationInProgress, RuntimeMitigation, NetworkIsolation, Other
|
||||
- **ExceptionScope**: ArtifactDigest, PurlPattern (wildcards: `pkg:npm/lodash@*`), VulnerabilityId, PolicyRuleId, Environments, TenantId; AND logic for multiple constraints; `IsValid` checks at least one constraint
|
||||
- **ExceptionEvaluator**: `src/Policy/__Libraries/StellaOps.Policy.Exceptions/Services/ExceptionEvaluator.cs` (sealed class implements `IExceptionEvaluator`)
|
||||
- `EvaluateAsync(FindingContext)` -- queries active exceptions by scope, filters by context match (artifact, vuln, PURL pattern, policy rule, environment, tenant), orders by specificity
|
||||
- `EvaluateBatchAsync(contexts)` -- evaluates multiple findings
|
||||
- Specificity scoring: ArtifactDigest=100, exact PURL=50, PURL pattern=20, VulnerabilityId=40, PolicyRuleId=30, Environments=10
|
||||
- PURL wildcard matching via regex conversion
|
||||
- Returns `ExceptionEvaluationResult` with HasException, MatchingExceptions, PrimaryReason, PrimaryRationale, AllEvidenceRefs
|
||||
- **EvidenceRequirementValidator**: `src/Policy/__Libraries/StellaOps.Policy.Exceptions/Services/EvidenceRequirementValidator.cs` -- validates evidence hooks before approval
|
||||
- **RecheckEvaluationService**: `src/Policy/__Libraries/StellaOps.Policy.Exceptions/Services/RecheckEvaluationService.cs` -- 9 recheck condition types
|
||||
- **Repositories**:
|
||||
- `IExceptionRepository` / `PostgresExceptionRepository`: `src/Policy/__Libraries/StellaOps.Policy.Exceptions/Repositories/`
|
||||
- `IExceptionApplicationRepository` / `PostgresExceptionApplicationRepository`: same directory -- audit trail persistence
|
||||
- **ExceptionEffectRegistry**: `src/Policy/StellaOps.Policy.Engine/Adapters/ExceptionEffectRegistry.cs` -- 40 type+reason -> effect mappings
|
||||
- **ExceptionRecheckGate**: `src/Policy/StellaOps.Policy.Engine/BuildGate/ExceptionRecheckGate.cs` -- CI/CD build gate for recheck policies
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Create exception with Type=Vulnerability, Scope=(VulnerabilityId="CVE-2024-1234", PurlPattern="pkg:npm/lodash@*"), Reason=FalsePositive; verify Status=Proposed
|
||||
- [ ] Approve exception; verify Status transitions to Approved, ApprovedAt is set, ApproverIds populated
|
||||
- [ ] Activate exception; verify Status=Active; evaluate finding with matching CVE and PURL; verify HasException=true
|
||||
- [ ] Verify exception with PurlPattern="pkg:npm/lodash@*" matches "pkg:npm/lodash@4.17.21" but not "pkg:npm/underscore@1.0.0"
|
||||
- [ ] Create two exceptions for same finding: one with ArtifactDigest (specificity=100) and one with VulnerabilityId (specificity=40); verify most specific is PrimaryReason
|
||||
- [ ] Set exception ExpiresAt to past; call IsEffectiveAt(now); verify returns false; verify EvaluateAsync does not match
|
||||
- [ ] Create exception with EnvironmentScope=["prod"]; evaluate in "dev"; verify no match
|
||||
- [ ] Create exception with EvidenceRefs=["sha256:abc"]; verify AllEvidenceRefs in EvaluationResult contains the ref
|
||||
- [ ] Use EvaluateBatchAsync with 3 FindingContexts; verify dictionary contains entries for indices 0, 1, 2
|
||||
- [ ] Verify Scope.IsValid returns false when no constraints are set; returns true when VulnerabilityId is set
|
||||
@@ -1,42 +0,0 @@
|
||||
# Explainability Testing Framework
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Explainability testing framework with assertion helpers and verdict rationale rendering, ensuring decisions can be traced back to evidence and assumptions.
|
||||
|
||||
## Implementation Details
|
||||
- **VerdictRationaleRenderer**: `src/Policy/__Libraries/StellaOps.Policy.Explainability/VerdictRationaleRenderer.cs` (sealed class implements `IVerdictRationaleRenderer`)
|
||||
- `Render(VerdictRationaleInput)` produces structured 4-line rationale with content-addressed RationaleId
|
||||
- `RenderPlainText(rationale)` produces plain text output (4 lines)
|
||||
- `RenderMarkdown(rationale)` produces Markdown with headers (Evidence, Policy Clause, Attestations, Decision)
|
||||
- `RenderJson(rationale)` produces canonical JSON (RFC 8785) via `CanonJson.Serialize`
|
||||
- Content-addressed ID: `rat:sha256:{hash}` computed from SHA256 of canonical JSON (with empty RationaleId for self-referential hashing)
|
||||
- **VerdictRationale model**: `src/Policy/__Libraries/StellaOps.Policy.Explainability/VerdictRationale.cs`
|
||||
- 4-line template structure:
|
||||
- Line 1 (`RationaleEvidence`): CVE, Component (PURL, name, version, ecosystem), Reachability (vulnerable function, entry point, path summary)
|
||||
- Line 2 (`RationalePolicyClause`): ClauseId, RuleDescription, Conditions
|
||||
- Line 3 (`RationaleAttestations`): PathWitness, VexStatements, Provenance (each as AttestationReference with Id, Type, Digest, Summary)
|
||||
- Line 4 (`RationaleDecision`): Verdict, Score, Recommendation, Mitigation (Action, Details)
|
||||
- `RationaleInputDigests` for reproducibility: VerdictDigest, PolicyDigest, EvidenceDigest
|
||||
- SchemaVersion: "1.0"
|
||||
- **VerdictRationaleInput**: `src/Policy/__Libraries/StellaOps.Policy.Explainability/IVerdictRationaleRenderer.cs`
|
||||
- Full input record with VerdictRef, Cve, Component, Reachability, PolicyClauseId, PolicyRuleDescription, PolicyConditions, attestation references, Verdict, Score, Recommendation, Mitigation, GeneratedAt, digest fields
|
||||
- **Property-based tests**: `src/Policy/__Tests/StellaOps.Policy.Determinization.Tests/PropertyTests/DeterminismPropertyTests.cs` -- tests determinism of rationale rendering
|
||||
- **Explainability integration tests**: verify that `Render` followed by `RenderPlainText`, `RenderMarkdown`, and `RenderJson` all produce deterministic output for identical inputs
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Render rationale with CVE, component, reachability; verify Evidence.FormattedText contains CVE ID, component name, vulnerable function, entry point
|
||||
- [ ] Render rationale with policy clause; verify PolicyClause.FormattedText contains ClauseId and conditions
|
||||
- [ ] Render rationale with path witness and VEX statements; verify Attestations.FormattedText includes both references
|
||||
- [ ] Render rationale without attestations; verify FormattedText is "No attestations available."
|
||||
- [ ] Render rationale with score and mitigation; verify Decision.FormattedText includes score value and mitigation action
|
||||
- [ ] Render same input twice; verify RationaleId is identical (content-addressed determinism)
|
||||
- [ ] Render different inputs; verify RationaleIds differ
|
||||
- [ ] RenderMarkdown produces valid Markdown with ## headers for each section
|
||||
- [ ] RenderJson produces valid JSON parseable by standard JSON parser
|
||||
- [ ] Verify RationaleId format matches `rat:sha256:{64 hex chars}`
|
||||
@@ -1,38 +0,0 @@
|
||||
# Explainability with Proof Extracts
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Verdict rationale rendering with full explainability system, reachability explanation UI with "why" drawer for interactive proof browsing.
|
||||
|
||||
## Implementation Details
|
||||
- **VerdictRationaleRenderer**: `src/Policy/__Libraries/StellaOps.Policy.Explainability/VerdictRationaleRenderer.cs` (sealed class implements `IVerdictRationaleRenderer`)
|
||||
- 4-line template rendering with structured evidence, policy clause, attestations, and decision sections
|
||||
- Evidence section includes reachability details: vulnerable function symbol, entry point, path summary
|
||||
- Attestation section references: path witnesses (reachability proofs), VEX statements, provenance attestations
|
||||
- Each attestation includes Id, Type, Digest, and Summary for browsing
|
||||
- Content-addressed RationaleId (`rat:sha256:{hash}`) enables proof linking
|
||||
- Multi-format output: PlainText, Markdown, canonical JSON (RFC 8785)
|
||||
- **VerdictRationale model**: `src/Policy/__Libraries/StellaOps.Policy.Explainability/VerdictRationale.cs`
|
||||
- `RationaleEvidence` with ComponentIdentity (PURL, name, version, ecosystem) and ReachabilityDetail (VulnerableFunction, EntryPoint, PathSummary)
|
||||
- `RationaleAttestations` with PathWitness (reachability proof reference), VexStatements (list of VEX attestation references), Provenance
|
||||
- `RationaleInputDigests` with VerdictDigest, PolicyDigest, EvidenceDigest for full proof chain
|
||||
- **PolicyExplainTrace**: `src/Policy/StellaOps.Policy.Engine/Materialization/PolicyExplainTrace.cs` -- trace objects for materialized explanations
|
||||
- **Counterfactual paths**: `src/Policy/__Libraries/StellaOps.Policy/Counterfactuals/CounterfactualEngine.cs` -- "what would fix this" paths linked to rationale
|
||||
- **Verdict attestation**: `src/Policy/StellaOps.Policy.Engine/Attestation/VerdictAttestationService.cs` -- DSSE-signed verdicts that rationale references
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Render verdict rationale for finding with reachability proof; verify Evidence section includes vulnerable function symbol and entry point
|
||||
- [ ] Render rationale with path witness attestation; verify Attestations.PathWitness.Id and Digest are populated
|
||||
- [ ] Render rationale with 3 VEX statements; verify all 3 appear in Attestations.VexStatements
|
||||
- [ ] Render rationale with provenance attestation; verify Provenance.Type and Summary are set
|
||||
- [ ] Verify RenderMarkdown output includes clickable attestation IDs in Attestations section
|
||||
- [ ] Verify InputDigests.VerdictDigest matches the actual verdict's content digest
|
||||
- [ ] Verify InputDigests.EvidenceDigest matches the evidence bundle digest
|
||||
- [ ] Render rationale for finding without reachability; verify Evidence.Reachability is null and FormattedText omits reachability details
|
||||
- [ ] Verify RenderJson output can be re-parsed and matches original rationale structure
|
||||
- [ ] Verify content-addressed RationaleId is stable across serialization roundtrips
|
||||
@@ -1,43 +0,0 @@
|
||||
# Exponential Confidence Decay for Unknown Reachability (Half-Life Calculator)
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Exponential half-life decay of confidence scores implemented in DecayedConfidenceCalculator with formula exp(-ln(2) * ageDays / halfLifeDays), configurable half-life (default 14 days), floor value, and metrics emission. Includes ObservationDecay models, uncertainty scoring, signal state tracking, and property-based tests. Integrated into policy determinization gate.
|
||||
|
||||
## Implementation Details
|
||||
- **DecayedConfidenceCalculator**: `src/Policy/__Libraries/StellaOps.Policy.Determinization/Scoring/DecayedConfidenceCalculator.cs` (sealed class implements `IDecayedConfidenceCalculator`)
|
||||
- `Calculate(baseConfidence, ageDays, halfLifeDays=14.0, floor=0.1)` -- applies exponential decay: `max(floor, baseConfidence * exp(-ln(2) * ageDays / halfLifeDays))`
|
||||
- `CalculateDecayFactor(ageDays, halfLifeDays=14.0)` -- returns raw decay factor clamped to [0.0, 1.0]
|
||||
- Parameter validation: baseConfidence [0.0-1.0], ageDays >= 0, halfLifeDays > 0, floor [0.0-1.0]
|
||||
- Metrics emission: `stellaops_determinization_decay_multiplier` histogram with half_life_days and age_days tags
|
||||
- **ObservationDecay**: `src/Policy/__Libraries/StellaOps.Policy.Determinization/Models/ObservationDecay.cs` (sealed record)
|
||||
- ObservedAt, RefreshedAt, HalfLifeDays (default 14.0), Floor (default 0.35), StalenessThreshold (default 0.50)
|
||||
- `CalculateDecay(now)` computes current multiplier: `max(Floor, exp(-ln(2) * ageDays / HalfLifeDays))`
|
||||
- `CheckIsStale(now)` returns true if decay multiplier < StalenessThreshold
|
||||
- Factory methods: `Create(observedAt, refreshedAt?)`, `Fresh(now)`, `WithSettings(observedAt, refreshedAt, halfLifeDays, floor, stalenessThreshold)`
|
||||
- Pre-computed fields: AgeDays, DecayedMultiplier, IsStale, LastSignalUpdate
|
||||
- **DeterminizationOptions**: `src/Policy/__Libraries/StellaOps.Policy.Determinization/DeterminizationOptions.cs` -- global decay configuration
|
||||
- **DeterminizationContext**: `src/Policy/__Libraries/StellaOps.Policy.Determinization/Models/DeterminizationContext.cs` -- evaluation context with observation state
|
||||
- **DeterminizationResult**: `src/Policy/__Libraries/StellaOps.Policy.Determinization/Models/DeterminizationResult.cs` -- result including decayed confidence
|
||||
- **DeterminizationGate**: `src/Policy/StellaOps.Policy.Engine/Gates/Determinization/DeterminizationGate.cs` -- policy gate using DecayedConfidenceCalculator
|
||||
- **Property-based tests**: `src/Policy/__Tests/StellaOps.Policy.Determinization.Tests/PropertyTests/DecayPropertyTests.cs` -- FsCheck property tests for decay formula
|
||||
- **Unit tests**: `src/Policy/__Tests/StellaOps.Policy.Determinization.Tests/DecayedConfidenceCalculatorTests.cs`
|
||||
- **ObservationDecay tests**: `src/Policy/__Tests/StellaOps.Policy.Determinization.Tests/Models/ObservationDecayTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Calculate decay with baseConfidence=1.0, ageDays=0: verify result=1.0 (no decay)
|
||||
- [ ] Calculate decay with baseConfidence=1.0, ageDays=14.0, halfLifeDays=14.0: verify result~0.5 (one half-life)
|
||||
- [ ] Calculate decay with baseConfidence=1.0, ageDays=28.0, halfLifeDays=14.0: verify result~0.25 (two half-lives)
|
||||
- [ ] Calculate decay with baseConfidence=0.8, ageDays=100.0, halfLifeDays=14.0: verify result=floor (0.1)
|
||||
- [ ] Calculate decay with custom floor=0.3: verify result never drops below 0.3
|
||||
- [ ] CalculateDecayFactor with ageDays=7, halfLifeDays=14: verify factor~0.707
|
||||
- [ ] ObservationDecay.Create with observedAt 30 days ago: verify CheckIsStale(now)=true (decay < 0.50 staleness threshold)
|
||||
- [ ] ObservationDecay.Fresh(now): verify CalculateDecay(now)=1.0, CheckIsStale(now)=false
|
||||
- [ ] ObservationDecay.WithSettings(halfLifeDays=7, floor=0.2, stalenessThreshold=0.60): verify custom settings applied
|
||||
- [ ] Verify DeterminizationGate uses decayed confidence in gate evaluation; stale observation triggers gate warning or block
|
||||
- [ ] Verify `stellaops_determinization_decay_multiplier` histogram metric is recorded after Calculate() call
|
||||
@@ -1,36 +0,0 @@
|
||||
# Gate Bypass Audit Logging
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Dedicated gate bypass audit system that records who/when/why for any gate override, persisting actor identity, justification text, IP address, and CI context to an audit repository. Includes rate limiting support for bypass abuse prevention.
|
||||
|
||||
## Implementation Details
|
||||
- **PolicyGateEvaluator override support**: `src/Policy/StellaOps.Policy.Engine/Gates/PolicyGateEvaluator.cs`
|
||||
- Override mechanism integrated into multi-gate evaluation pipeline
|
||||
- Override requires justification string (non-empty)
|
||||
- Gate result types include PassWithNote for approved bypasses with audit trail
|
||||
- Each gate decision is logged with full context (gate name, decision, justification)
|
||||
- **PolicyGateOptions**: `src/Policy/StellaOps.Policy.Engine/Gates/PolicyGateOptions.cs` -- gate configuration including override policies
|
||||
- **ExceptionEffectRegistry**: `src/Policy/StellaOps.Policy.Engine/Adapters/ExceptionEffectRegistry.cs` -- maps exception types to effects with audit trail
|
||||
- **ExceptionApplication audit**: `src/Policy/__Libraries/StellaOps.Policy.Exceptions/Models/ExceptionApplication.cs`
|
||||
- Records every exception application with ExceptionId, FindingId, OriginalStatus, AppliedStatus, EffectName, EffectType, EvaluationRunId, PolicyBundleDigest, AppliedAt, Metadata
|
||||
- Metadata dictionary supports arbitrary context (IP address, CI pipeline ID, actor identity)
|
||||
- **IExceptionApplicationRepository**: `src/Policy/__Libraries/StellaOps.Policy.Exceptions/Repositories/IExceptionApplicationRepository.cs`
|
||||
- Query by ExceptionId, FindingId, EvaluationRunId, time range for audit review
|
||||
- Statistics: total applications, unique exceptions/findings/vulnerabilities, breakdowns by effect type and status
|
||||
- **VerdictAttestationService**: `src/Policy/StellaOps.Policy.Engine/Attestation/VerdictAttestationService.cs` -- DSSE-signed attestations for all verdict decisions including bypasses
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Apply gate override with justification; verify ExceptionApplication record includes justification in Metadata
|
||||
- [ ] Apply gate override; verify Metadata contains actor identity, IP address, and timestamp
|
||||
- [ ] Query `GetByExceptionIdAsync` for override exception; verify full audit trail returned
|
||||
- [ ] Apply 3 overrides in same evaluation run; query `GetByEvaluationRunIdAsync`; verify all 3 returned
|
||||
- [ ] Apply override with empty justification; verify override is rejected (justification required)
|
||||
- [ ] Query `GetStatisticsAsync` after multiple overrides; verify ByEffectType counts include override effects
|
||||
- [ ] Verify VerdictAttestationService creates DSSE-signed attestation for override decisions
|
||||
- [ ] Verify override decisions are included in `GetByTimeRangeAsync` query results for compliance export
|
||||
@@ -1,39 +0,0 @@
|
||||
# Gate Level Selection (G0-G4)
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Diff-aware release gate levels G0-G4 with automatic gate selection based on RRS score and budget status, exposed via API endpoints.
|
||||
|
||||
## Implementation Details
|
||||
- **PolicyGateEvaluator**: `src/Policy/StellaOps.Policy.Engine/Gates/PolicyGateEvaluator.cs`
|
||||
- Multi-gate evaluation pipeline with 5 sequential gates: Evidence Completeness, Lattice State, VEX Trust, Uncertainty Tier, Confidence Threshold
|
||||
- Gate result types: Pass, PassWithNote, Warn, Block, Skip
|
||||
- Short-circuits on first Block; accumulates warnings
|
||||
- Override support with justification requirements
|
||||
- Gate decision model: `PolicyGateDecision.cs` with overall decision and per-gate details
|
||||
- **PolicyGateOptions**: `src/Policy/StellaOps.Policy.Engine/Gates/PolicyGateOptions.cs` -- configurable gate thresholds and behaviors
|
||||
- **VexTrustGate**: `src/Policy/StellaOps.Policy.Engine/Gates/VexTrustGate.cs` -- per-environment trust thresholds (prod: 0.80, staging: 0.60, dev: 0.40)
|
||||
- **DeterminizationGate**: `src/Policy/StellaOps.Policy.Engine/Gates/Determinization/DeterminizationGate.cs` -- determinism verification gate using DecayedConfidenceCalculator
|
||||
- **StabilityDampingGate**: `src/Policy/StellaOps.Policy.Engine/Gates/StabilityDampingGate.cs` -- prevents oscillation in gate decisions
|
||||
- **DriftGateEvaluator**: `src/Policy/StellaOps.Policy.Engine/Gates/DriftGateEvaluator.cs` -- evaluates SBOM drift for diff-aware gating
|
||||
- **RiskSimulationService**: `src/Policy/StellaOps.Policy.Engine/Simulation/RiskSimulationService.cs` -- signal-based scoring that feeds gate selection
|
||||
- Severity mapping: Critical>=90, High>=70, Medium>=40, Low>=10
|
||||
- **WhatIfSimulationService**: `src/Policy/StellaOps.Policy.Engine/WhatIfSimulation/WhatIfSimulationService.cs` -- delta computation for diff-aware gates
|
||||
- **Gate endpoints**: `src/Policy/StellaOps.Policy.Engine/Endpoints/` -- REST API for gate evaluation results
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Evaluate artifact with all evidence present and high confidence; verify all gates pass (G0 level)
|
||||
- [ ] Evaluate artifact with missing VEX evidence; verify Evidence Completeness gate warns or blocks
|
||||
- [ ] Evaluate artifact with VEX trust score below production threshold (0.80); verify VexTrustGate blocks in prod
|
||||
- [ ] Evaluate artifact with VEX trust score 0.65 in staging; verify VexTrustGate passes (threshold 0.60)
|
||||
- [ ] Evaluate artifact with unknown reachability (U state); verify Lattice State gate applies appropriate action
|
||||
- [ ] Evaluate artifact with Uncertainty Tier T1 (high uncertainty); verify Uncertainty gate blocks
|
||||
- [ ] Evaluate artifact with confidence below threshold; verify Confidence gate blocks
|
||||
- [ ] Override a blocked gate with justification; verify PassWithNote result
|
||||
- [ ] Evaluate with DriftGateEvaluator detecting SBOM changes; verify drift-aware gating triggers
|
||||
- [ ] Verify StabilityDampingGate prevents rapid oscillation between Pass and Block
|
||||
@@ -1,45 +0,0 @@
|
||||
# Impact Scoring for Unknowns
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
The advisory proposed weighted impact scoring with factors like environment exposure, data sensitivity, fleet prevalence, SLA tier, and CVSS severity. UncertaintyScoreCalculator and TrustScoreAggregator with configurable SignalWeights exist in the Determinization library, and ReachabilityScoringService exists in Signals. The exact multi-factor impact formula (w_env * EnvExposure + w_data * DataSensitivity + ...) is partially reflected through the existing signal weights system, though the specific per-factor normalization described in the advisory is not confirmed.
|
||||
|
||||
## What's Implemented
|
||||
- **UncertaintyScoreCalculator**: `src/Policy/__Libraries/StellaOps.Policy.Determinization/Scoring/UncertaintyScoreCalculator.cs`
|
||||
- Entropy-based uncertainty: `1.0 - (presentSignalWeight / totalPossibleWeight)`
|
||||
- 6 signal gap categories: VEX, EPSS, Reachability, Runtime, Backport, SBOMLineage
|
||||
- OpenTelemetry histogram: `stellaops_determinization_uncertainty_entropy`
|
||||
- **SignalWeights**: `src/Policy/__Libraries/StellaOps.Policy.Determinization/Scoring/SignalWeights.cs`
|
||||
- Configurable per-signal weights (VEX=0.25, Reachability=0.25, EPSS=0.15, Runtime=0.15, Backport=0.10, SBOM=0.10)
|
||||
- **TrustScoreAggregator**: `src/Policy/__Libraries/StellaOps.Policy.Determinization/Scoring/TrustScoreAggregator.cs`
|
||||
- Weighted average of present signals with uncertainty penalty
|
||||
- No-signal fallback: `0.5 * (1.0 - entropy)`
|
||||
- **UnknownRanker** (from unchecked feature): scoring unknowns with two-factor formula `Uncertainty*50 + ExploitPressure*50`
|
||||
- Containment reduction (capped at 40%), band assignment (Hot>=75, Warm>=50, Cold>=25)
|
||||
- **DecayedConfidenceCalculator**: `src/Policy/__Libraries/StellaOps.Policy.Determinization/Scoring/DecayedConfidenceCalculator.cs`
|
||||
- Exponential decay applied to confidence based on observation age
|
||||
- **Weight manifest guardrails**: `etc/weights/v2026-01-22.weights.json`
|
||||
- Determinization thresholds: manualReviewEntropy=0.60, refreshEntropy=0.40
|
||||
|
||||
## What's Missing
|
||||
- **Multi-factor impact formula**: The advisory-specified formula `w_env * EnvExposure + w_data * DataSensitivity + w_fleet * FleetPrevalence + w_sla * SLATier + w_cvss * CVSSSeverity` is not implemented as a dedicated calculator
|
||||
- **Environment exposure scoring**: No service that maps environment type (production/staging/dev) to a normalized exposure score (0.0-1.0)
|
||||
- **Data sensitivity classification**: No integration with data sensitivity labels (PII, financial, healthcare) for impact scoring
|
||||
- **Fleet prevalence factor**: No calculator that determines what percentage of the fleet is affected by a given unknown
|
||||
- **SLA tier weighting**: No mapping from SLA tier (Gold/Silver/Bronze) to impact weight
|
||||
- **Per-factor normalization functions**: Individual normalizers for each impact factor are not implemented as pluggable components
|
||||
|
||||
## Implementation Plan
|
||||
- Create `ImpactScoreCalculator` with pluggable factor providers (EnvironmentExposure, DataSensitivity, FleetPrevalence, SLATier, CVSSSeverity)
|
||||
- Integrate with existing `UncertaintyScoreCalculator` to combine entropy-based uncertainty with multi-factor impact
|
||||
- Add environment exposure mapping service that reads from deployment metadata
|
||||
- Wire into `UnknownRanker` as an additional scoring dimension
|
||||
|
||||
## Related Documentation
|
||||
- Determinization scoring: `src/Policy/__Libraries/StellaOps.Policy.Determinization/Scoring/`
|
||||
- Unknowns ranking (unchecked): `docs/features/unchecked/policy/unknowns-ranking-algorithm.md`
|
||||
@@ -1,44 +0,0 @@
|
||||
# Jurisdiction-Specific VEX Trust Rules (US/EU/RU/CN)
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Configurable jurisdiction-specific trust rules for VEX statements, enabling different trust levels and source preferences for US, EU, Russia, and China regulatory contexts.
|
||||
|
||||
## Implementation Details
|
||||
- **VexTrustGate**: `src/Policy/StellaOps.Policy.Engine/Gates/VexTrustGate.cs` (implements `IVexTrustGate`)
|
||||
- `EvaluateAsync(VexTrustGateRequest)` evaluates trust score against per-environment thresholds
|
||||
- VexTrustStatus with TrustScore (0.0-1.0), PolicyTrustThreshold, MeetsPolicyThreshold, TrustBreakdown
|
||||
- Checks: composite score >= threshold, issuer verification, accuracy rate, freshness
|
||||
- **VexTrustGateOptions**: `src/Policy/StellaOps.Policy.Engine/Gates/VexTrustGateOptions.cs`
|
||||
- Per-environment thresholds: production (MinCompositeScore=0.80, RequireIssuerVerified=true, MinAccuracyRate=0.85, FailureAction=Block), staging (0.60, verified, Warn), development (0.40, unverified OK, Warn), default (0.70, verified, Warn)
|
||||
- `ApplyToStatuses`: ["not_affected", "fixed"]
|
||||
- `MissingTrustBehavior`: Allow, Warn, or Block when VEX trust data is absent
|
||||
- `TenantOverrides`: tenant-specific threshold overrides per environment
|
||||
- Acceptable freshness states per environment (prod: fresh only; dev: fresh, stale, superseded)
|
||||
- MaxAge per environment (optional time-based freshness)
|
||||
- FailureAction enum: Warn, Block
|
||||
- **TrustLatticeEngine**: `src/Policy/__Libraries/StellaOps.Policy/TrustLattice/TrustLatticeEngine.cs`
|
||||
- Three VEX normalizers for different formats: CycloneDX, OpenVEX, CSAF
|
||||
- Jurisdiction-aware VEX source trust via normalizer selection and claim scoring
|
||||
- ClaimScoreMerger with conflict penalization for multi-source VEX
|
||||
- **PolicyGateEvaluator VEX Trust gate**: `src/Policy/StellaOps.Policy.Engine/Gates/PolicyGateEvaluator.cs`
|
||||
- VEX Trust gate evaluates per-environment thresholds with MissingTrustBehavior fallback
|
||||
- Integrated into 5-gate sequential pipeline
|
||||
- **VexTrustGateMetrics**: `src/Policy/StellaOps.Policy.Engine/Gates/VexTrustGateMetrics.cs` -- OpenTelemetry metrics for gate decisions
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Configure production threshold MinCompositeScore=0.80; evaluate VEX with score 0.75; verify gate blocks
|
||||
- [ ] Configure staging threshold MinCompositeScore=0.60; evaluate VEX with score 0.65; verify gate passes
|
||||
- [ ] Configure production RequireIssuerVerified=true; evaluate unsigned VEX; verify gate blocks
|
||||
- [ ] Configure development RequireIssuerVerified=false; evaluate unsigned VEX; verify gate passes
|
||||
- [ ] Configure production MinAccuracyRate=0.85; evaluate issuer with 0.80 accuracy; verify gate warns/blocks
|
||||
- [ ] Configure production AcceptableFreshness=["fresh"]; evaluate stale VEX; verify gate blocks
|
||||
- [ ] Configure MissingTrustBehavior=Block; evaluate without VEX trust data; verify gate blocks
|
||||
- [ ] Configure MissingTrustBehavior=Allow; evaluate without VEX trust data; verify gate passes
|
||||
- [ ] Configure TenantOverrides with custom thresholds for tenant-A; verify tenant-A uses custom thresholds
|
||||
- [ ] Verify VexTrustGateMetrics records gate decisions with trust_score, environment, and decision tags
|
||||
@@ -1,46 +0,0 @@
|
||||
# Knowledge Snapshot Manifest
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Knowledge Snapshot Manifest as a content-addressed sealed record containing source descriptors with hashes/digests, policy IDs, engine versions, plugin versions, and trust anchor set hashes.
|
||||
|
||||
## Implementation Details
|
||||
- **KnowledgeSnapshotManifest**: `src/Policy/__Libraries/StellaOps.Policy/Snapshots/KnowledgeSnapshotManifest.cs` (sealed record)
|
||||
- SnapshotId: content-addressed `ksm:sha256:{hash}`
|
||||
- CreatedAt (UTC timestamp)
|
||||
- Engine: `EngineInfo` record (Name, Version, Commit)
|
||||
- Plugins: list of `PluginInfo` records (Name, Version, Type)
|
||||
- Policy: `PolicyBundleRef` record (PolicyId, Digest, Uri)
|
||||
- Scoring: `ScoringRulesRef` record (RulesId, Digest, Uri)
|
||||
- Trust: `TrustBundleRef` record (BundleId, Digest, Uri) -- optional
|
||||
- Sources: list of `KnowledgeSourceDescriptor` -- all knowledge inputs
|
||||
- Environment: `DeterminismProfile` record (TimezoneOffset, Locale, Platform, EnvironmentVars)
|
||||
- Signature: optional DSSE signature over the manifest
|
||||
- ManifestVersion: "1.0"
|
||||
- **KnowledgeSourceDescriptor**: `src/Policy/__Libraries/StellaOps.Policy/Snapshots/KnowledgeSourceDescriptor.cs` (sealed record)
|
||||
- Name, Type ("advisory-feed", "vex", "sbom", "reachability", "policy"), Epoch, Digest, Origin, LastUpdatedAt, RecordCount
|
||||
- InclusionMode: Referenced (digest only), Bundled (embedded), BundledCompressed
|
||||
- BundlePath for embedded sources
|
||||
- Well-known types in `KnowledgeSourceTypes` static class: AdvisoryFeed, Vex, Sbom, Reachability, Policy
|
||||
- **SnapshotBuilder**: `src/Policy/__Libraries/StellaOps.Policy/Snapshots/SnapshotBuilder.cs` -- fluent builder for constructing snapshots
|
||||
- **SnapshotIdGenerator**: `src/Policy/__Libraries/StellaOps.Policy/Snapshots/SnapshotIdGenerator.cs` -- content-addressed ID generation
|
||||
- **SnapshotService**: `src/Policy/__Libraries/StellaOps.Policy/Snapshots/SnapshotService.cs` -- snapshot lifecycle management
|
||||
- **SnapshotAwarePolicyEvaluator**: `src/Policy/__Libraries/StellaOps.Policy/Snapshots/SnapshotAwarePolicyEvaluator.cs` -- evaluates policy using pinned snapshot inputs
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Build snapshot with 3 knowledge sources (NVD advisory-feed, vendor VEX, SBOM); verify SnapshotId is content-addressed `ksm:sha256:...`
|
||||
- [ ] Build snapshot; change one source digest; rebuild; verify SnapshotId changes (content-addressed)
|
||||
- [ ] Build identical snapshot twice; verify SnapshotId is identical (deterministic)
|
||||
- [ ] Verify Engine field contains correct Name, Version, and Commit
|
||||
- [ ] Add 2 plugins to snapshot; verify Plugins list contains both with correct Name/Version/Type
|
||||
- [ ] Set Policy.Digest and Scoring.Digest; verify PolicyBundleRef and ScoringRulesRef are populated
|
||||
- [ ] Set Trust.BundleId and Trust.Digest; verify TrustBundleRef is populated
|
||||
- [ ] Add source with InclusionMode=Bundled; verify BundlePath is set
|
||||
- [ ] Add source with InclusionMode=Referenced; verify BundlePath is null
|
||||
- [ ] Set Environment DeterminismProfile; verify TimezoneOffset, Locale, Platform are captured
|
||||
- [ ] Use SnapshotAwarePolicyEvaluator with snapshot; verify evaluation uses pinned source data
|
||||
@@ -1,47 +0,0 @@
|
||||
# License Compliance Evaluation Engine
|
||||
|
||||
## Module
|
||||
Policy
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Full license compliance evaluation with SPDX expression parsing, license compatibility matrix checking against configurable allow/deny/copyleft lists, attribution report generation, and policy engine integration. While the known list has SPDX license expression parsers in the Attestor writers, this is a distinct policy-engine-integrated compliance evaluator with attribution generation capabilities.
|
||||
|
||||
## Implementation Details
|
||||
- **LicenseComplianceEvaluator**: `src/Policy/__Libraries/StellaOps.Policy/Licensing/LicenseComplianceEvaluator.cs` (sealed class implements `ILicenseComplianceEvaluator`)
|
||||
- `EvaluateAsync(components, policy)` evaluates license compliance for all components
|
||||
- SPDX expression parsing via `SpdxLicenseExpressionParser.Parse()`
|
||||
- License expression evaluation via `LicenseExpressionEvaluator` with compatibility checking
|
||||
- Exemption support: per-component pattern-based license exemptions
|
||||
- Obligation tracking: Attribution, SourceDisclosure, PatentGrant, TrademarkNotice
|
||||
- Overall status: Pass (no issues), Warn (missing/unknown licenses, obligations), Fail (prohibited, copyleft conflict, commercial restriction)
|
||||
- **LicenseComplianceReport**: `src/Policy/__Libraries/StellaOps.Policy/Licensing/LicenseComplianceModels.cs`
|
||||
- Inventory: LicenseUsage records with LicenseId, Expression, Category, Components list, Count; ByCategory counts; UnknownLicenseCount; NoLicenseCount
|
||||
- Findings: LicenseFinding records with Type, LicenseId, ComponentName, ComponentPurl, Category, Message
|
||||
- Conflicts: LicenseConflict records with conflicting LicenseIds and Reason
|
||||
- AttributionRequirements: ComponentName, LicenseId, Notices, IncludeLicenseText flag
|
||||
- **LicenseFindingType enum**: ProhibitedLicense, CopyleftInProprietaryContext, LicenseConflict, UnknownLicense, MissingLicense, AttributionRequired, SourceDisclosureRequired, PatentClauseRisk, CommercialRestriction, ConditionalLicenseViolation
|
||||
- **LicenseCategory enum**: Unknown, Permissive, WeakCopyleft, StrongCopyleft, Proprietary, PublicDomain
|
||||
- **Supporting classes**:
|
||||
- `LicenseKnowledgeBase`: `src/Policy/__Libraries/StellaOps.Policy/Licensing/LicenseKnowledgeBase.cs` -- license metadata database
|
||||
- `LicenseCompatibilityChecker`: `src/Policy/__Libraries/StellaOps.Policy/Licensing/LicenseCompatibilityChecker.cs` -- compatibility matrix
|
||||
- `LicenseExpressionEvaluator`: `src/Policy/__Libraries/StellaOps.Policy/Licensing/LicenseExpressionEvaluator.cs` -- evaluates parsed expressions
|
||||
- `ProjectContextAnalyzer`: `src/Policy/__Libraries/StellaOps.Policy/Licensing/ProjectContextAnalyzer.cs` -- project context for compatibility
|
||||
- `LicensePolicy` / `LicensePolicyLoader`: `src/Policy/__Libraries/StellaOps.Policy/Licensing/LicensePolicy.cs` / `LicensePolicyLoader.cs` -- policy configuration
|
||||
- `AttributionGenerator`: `src/Policy/__Libraries/StellaOps.Policy/Licensing/AttributionGenerator.cs` -- NOTICE file generation
|
||||
- `SpdxLicenseExpressionParser`: `src/Policy/__Libraries/StellaOps.Policy/Licensing/SpdxLicenseExpressionParser.cs` -- SPDX expression parsing
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Evaluate component with "MIT" license; verify OverallStatus=Pass, Category=Permissive
|
||||
- [ ] Evaluate component with "GPL-3.0-only" in proprietary context; verify finding type CopyleftInProprietaryContext, OverallStatus=Fail
|
||||
- [ ] Evaluate component with prohibited license (in deny list); verify finding type ProhibitedLicense, OverallStatus=Fail
|
||||
- [ ] Evaluate component with no license data; verify finding type MissingLicense, OverallStatus=Warn
|
||||
- [ ] Evaluate component with unparseable license expression; verify finding type UnknownLicense
|
||||
- [ ] Evaluate component with "Apache-2.0 OR MIT" dual license; verify parser resolves expression, one license selected
|
||||
- [ ] Evaluate 3 components: MIT, GPL-3.0, Apache-2.0; verify Inventory contains all 3 with correct categories and ByCategory counts
|
||||
- [ ] Evaluate with license requiring attribution; verify AttributionRequirements populated with ComponentName and Notices
|
||||
- [ ] Configure exemption for component pattern "internal-*" allowing GPL-3.0; verify ProhibitedLicense finding suppressed
|
||||
- [ ] Evaluate with UnknownLicenseHandling=Deny in policy; verify unknown licenses produce OverallStatus=Fail
|
||||
- [ ] Evaluate component with conflicting dual licenses; verify LicenseConflict finding with reason
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user