save checkpoint
This commit is contained in:
master
40
docs/features/checked/advisoryai/advisoryai-orchestrator.md
Normal file
40
docs/features/checked/advisoryai/advisoryai-orchestrator.md
Normal file
@@ -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/checked/advisoryai/ai-action-policy-gate.md
Normal file
37
docs/features/checked/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 @@
|
||||
# AI Remedy Autopilot with Multi-SCM Pull Request Generation
|
||||
|
||||
## Module
|
||||
AdvisoryAI
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
AI-powered remediation service that generates fix plans (dependency bumps, base image upgrades, config changes, backport guidance), then creates PRs automatically across GitHub, GitLab, Azure DevOps, and Gitea via a unified SCM connector plugin architecture. Includes build verification, SBOM delta computation, signed delta verdicts, and fallback to "suggestion-only" when build/tests fail.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/AdvisoryAi/StellaOps.AdvisoryAI/Remediation/`, `src/AdvisoryAi/StellaOps.AdvisoryAI.Scm.Plugin.Unified/`
|
||||
- **Key Classes**:
|
||||
- `AiRemediationPlanner` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Remediation/AiRemediationPlanner.cs`) - AI-driven remediation plan generation
|
||||
- `RemediationDeltaService` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Remediation/RemediationDeltaService.cs`) - computes SBOM delta for remediation impact
|
||||
- `PrTemplateBuilder` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Remediation/PrTemplateBuilder.cs`) - builds PR descriptions with evidence and delta info
|
||||
- `GitHubPullRequestGenerator` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Remediation/GitHubPullRequestGenerator.cs`) - generates PRs on GitHub
|
||||
- `GitLabMergeRequestGenerator` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Remediation/GitLabMergeRequestGenerator.cs`) - generates MRs on GitLab
|
||||
- `AzureDevOpsPullRequestGenerator` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Remediation/AzureDevOpsPullRequestGenerator.cs`) - generates PRs on Azure DevOps
|
||||
- `GiteaScmConnector` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Remediation/ScmConnector/GiteaScmConnector.cs`) - Gitea SCM integration
|
||||
- `GitHubScmConnector` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Remediation/ScmConnector/GitHubScmConnector.cs`) - GitHub SCM integration
|
||||
- `GitLabScmConnector` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Remediation/ScmConnector/GitLabScmConnector.cs`) - GitLab SCM integration
|
||||
- `AzureDevOpsScmConnector` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Remediation/ScmConnector/AzureDevOpsScmConnector.cs`) - Azure DevOps SCM integration
|
||||
- `ScmConnectorCatalog` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Remediation/ScmConnector/ScmConnectorCatalog.cs`) - catalog of available SCM connectors
|
||||
- `ScmPluginAdapter` (`src/AdvisoryAi/StellaOps.AdvisoryAI.Scm.Plugin.Unified/ScmPluginAdapter.cs`) - unified plugin adapter for SCM operations
|
||||
- `ScmPluginAdapterFactory` (`src/AdvisoryAi/StellaOps.AdvisoryAI.Scm.Plugin.Unified/ScmPluginAdapterFactory.cs`) - factory for creating SCM plugin adapters
|
||||
- **Interfaces**: `IRemediationPlanner`, `IPullRequestGenerator`, `IScmConnector`, `IPackageVersionResolver`
|
||||
- **Source**: SPRINT_20251226_016_AI_remedy_autopilot.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Generate a remediation plan via `AiRemediationPlanner` for a known CVE and verify it includes dependency bump steps
|
||||
- [ ] Create a PR via `GitHubPullRequestGenerator` and verify `PrTemplateBuilder` populates the description with evidence
|
||||
- [ ] Verify `RemediationDeltaService` computes SBOM delta showing before/after dependency changes
|
||||
- [ ] Verify `ScmConnectorCatalog` resolves the correct connector (GitHub, GitLab, AzureDevOps, Gitea) based on repository URL
|
||||
- [ ] Verify `ScmPluginAdapter` creates branches, commits changes, and opens PRs through the unified plugin interface
|
||||
- [ ] Verify fallback to "suggestion-only" mode when build verification fails after applying the fix
|
||||
@@ -0,0 +1,35 @@
|
||||
# Chat Gateway with Quotas and Scrubbing
|
||||
|
||||
## Module
|
||||
AdvisoryAI
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Chat gateway with configurable options (quotas, budgets) and service-layer chat orchestration is implemented.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/`, `src/AdvisoryAi/StellaOps.AdvisoryAI.WebService/`
|
||||
- **Key Classes**:
|
||||
- `AdvisoryChatService` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/Services/AdvisoryChatService.cs`) - main chat service with quota enforcement
|
||||
- `AdvisoryChatQuotaService` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/Services/AdvisoryChatQuotaService.cs`) - per-user/tenant quota tracking and enforcement
|
||||
- `AdvisoryChatOptions` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/Options/AdvisoryChatOptions.cs`) - configurable chat options (quotas, budgets, limits)
|
||||
- `GroundingValidator` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/GroundingValidator.cs`) - validates AI responses are grounded in evidence
|
||||
- `ChatResponseStreamer` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/ChatResponseStreamer.cs`) - streams chat responses with progressive delivery
|
||||
- `ChatPromptAssembler` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/ChatPromptAssembler.cs`) - assembles prompts with scrubbing and context injection
|
||||
- `ConversationContextBuilder` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/ConversationContextBuilder.cs`) - builds conversation context with relevant data
|
||||
- `ChatEndpoints` (`src/AdvisoryAi/StellaOps.AdvisoryAI.WebService/Endpoints/ChatEndpoints.cs`) - REST API endpoints for chat gateway
|
||||
- `RateLimitsService` (`src/AdvisoryAi/StellaOps.AdvisoryAI.WebService/Services/RateLimitsService.cs`) - rate limiting for chat API calls
|
||||
- `AuthorizationService` (`src/AdvisoryAi/StellaOps.AdvisoryAI.WebService/Services/AuthorizationService.cs`) - authorization checks for chat access
|
||||
- **Interfaces**: `IAdvisoryChatInferenceClient`, `IAiConsentStore`
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Send chat messages and verify `AdvisoryChatQuotaService` enforces per-user quotas (reject after limit exceeded)
|
||||
- [ ] Configure quota limits via `AdvisoryChatOptions` and verify they are applied at runtime
|
||||
- [ ] Verify `ChatPromptAssembler` scrubs sensitive data (credentials, tokens) from prompts before sending to LLM
|
||||
- [ ] Verify `GroundingValidator` flags responses that lack evidence grounding
|
||||
- [ ] Verify `RateLimitsService` rate-limits excessive chat API calls
|
||||
- [ ] Verify `ChatResponseStreamer` delivers streaming responses with proper chunking
|
||||
- [ ] Verify `AuthorizationService` rejects chat requests from unauthorized users
|
||||
@@ -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`
|
||||
@@ -0,0 +1,38 @@
|
||||
# Evidence-First AI Outputs (Citations, Evidence Packs)
|
||||
|
||||
## Module
|
||||
AdvisoryAI
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Evidence bundle assembly with schema-validated JSON, data providers for citations, and evidence pack integration in chat responses is implemented.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/Assembly/`
|
||||
- **Key Classes**:
|
||||
- `EvidenceBundleAssembler` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/Assembly/EvidenceBundleAssembler.cs`) - assembles evidence bundles from multiple data providers
|
||||
- `EvidencePackChatIntegration` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/EvidencePackChatIntegration.cs`) - integrates evidence packs into chat responses
|
||||
- `AttestationIntegration` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/AttestationIntegration.cs`) - links evidence packs to attestation framework
|
||||
- `SbomDataProvider` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/Assembly/Providers/SbomDataProvider.cs`) - provides SBOM data for evidence bundles
|
||||
- `VexDataProvider` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/Assembly/Providers/VexDataProvider.cs`) - provides VEX data for evidence bundles
|
||||
- `ReachabilityDataProvider` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/Assembly/Providers/ReachabilityDataProvider.cs`) - provides reachability scoring data
|
||||
- `PolicyDataProvider` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/Assembly/Providers/PolicyDataProvider.cs`) - provides policy evaluation data
|
||||
- `ProvenanceDataProvider` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/Assembly/Providers/ProvenanceDataProvider.cs`) - provides provenance/SLSA data
|
||||
- `FixDataProvider` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/Assembly/Providers/FixDataProvider.cs`) - provides fix availability data
|
||||
- `BinaryPatchDataProvider` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/Assembly/Providers/BinaryPatchDataProvider.cs`) - provides binary patch analysis data
|
||||
- `ContextDataProvider` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/Assembly/Providers/ContextDataProvider.cs`) - provides contextual data
|
||||
- `OpsMemoryDataProvider` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/Assembly/Providers/OpsMemoryDataProvider.cs`) - provides OpsMemory historical decision data
|
||||
- `EvidencePackEndpoints` (`src/AdvisoryAi/StellaOps.AdvisoryAI.WebService/Endpoints/EvidencePackEndpoints.cs`) - REST endpoints for evidence pack access
|
||||
- **Interfaces**: `IEvidenceBundleAssembler`
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Assemble an evidence bundle via `EvidenceBundleAssembler` and verify all data providers contribute relevant sections
|
||||
- [ ] Verify `SbomDataProvider` includes component version and license data in the evidence bundle
|
||||
- [ ] Verify `VexDataProvider` includes VEX status (affected/not_affected/fixed) for referenced CVEs
|
||||
- [ ] Verify `ReachabilityDataProvider` includes reachability scores and call-path evidence
|
||||
- [ ] Verify `EvidencePackChatIntegration` attaches evidence pack references to chat responses
|
||||
- [ ] Verify `AttestationIntegration` signs evidence packs with attestation metadata
|
||||
- [ ] Access evidence packs via `EvidencePackEndpoints` and verify schema-validated JSON output
|
||||
@@ -0,0 +1,31 @@
|
||||
# Evidence-First Citations in Chat Responses
|
||||
|
||||
## Module
|
||||
AdvisoryAI
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Evidence bundle assembly with citations in chat responses and UI evidence drilldown is implemented.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/`, `src/AdvisoryAi/StellaOps.AdvisoryAI/Explanation/`
|
||||
- **Key Classes**:
|
||||
- `EvidenceAnchoredExplanationGenerator` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Explanation/EvidenceAnchoredExplanationGenerator.cs`) - generates explanations anchored to evidence citations
|
||||
- `EvidencePackChatIntegration` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/EvidencePackChatIntegration.cs`) - embeds evidence citations into chat responses
|
||||
- `GroundingValidator` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/GroundingValidator.cs`) - validates that AI claims are grounded in cited evidence
|
||||
- `ExplanationPromptTemplates` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Explanation/ExplanationPromptTemplates.cs`) - prompt templates for citation-rich explanations
|
||||
- `DefaultExplanationPromptService` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Explanation/DefaultExplanationPromptService.cs`) - assembles explanation prompts with citation instructions
|
||||
- `InMemoryExplanationStore` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Explanation/InMemoryExplanationStore.cs`) - stores explanation requests and results
|
||||
- `ActionProposalParser` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/ActionProposalParser.cs`) - parses action proposals from LLM responses with citation references
|
||||
- **Interfaces**: `IExplanationGenerator`, `IExplanationRequestStore`, `IEvidenceRetrievalService`
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Generate an explanation via `EvidenceAnchoredExplanationGenerator` and verify it contains citation references to evidence items
|
||||
- [ ] Verify `GroundingValidator` rejects explanations that make claims without corresponding evidence citations
|
||||
- [ ] Verify `EvidencePackChatIntegration` embeds clickable citation references in chat response markdown
|
||||
- [ ] Verify `ExplanationPromptTemplates` instruct the LLM to cite evidence sources in its output
|
||||
- [ ] Verify `InMemoryExplanationStore` persists explanation requests and results for later retrieval
|
||||
- [ ] Verify `ActionProposalParser` extracts cited evidence IDs from LLM-generated action proposals
|
||||
@@ -0,0 +1,31 @@
|
||||
# Immutable Audit Log for AI Interactions
|
||||
|
||||
## Module
|
||||
AdvisoryAI
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
DSSE-signed audit envelope builder for chat interactions with prompts, tool calls, and model fingerprints is implemented.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/Audit/`, `src/AdvisoryAi/StellaOps.AdvisoryAI.WebService/`
|
||||
- **Key Classes**:
|
||||
- `AdvisoryChatAuditEnvelopeBuilder` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/Audit/AdvisoryChatAuditEnvelopeBuilder.cs`) - builds DSSE-signed audit envelopes for chat interactions
|
||||
- `ChatAuditRecords` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/Audit/ChatAuditRecords.cs`) - audit record models (prompts, responses, tool calls, model fingerprints)
|
||||
- `PostgresAdvisoryChatAuditLogger` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/Services/PostgresAdvisoryChatAuditLogger.cs`) - persists audit records to PostgreSQL
|
||||
- `NullAdvisoryChatAuditLogger` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/Services/NullAdvisoryChatAuditLogger.cs`) - no-op audit logger for testing
|
||||
- `AttestationEndpoints` (`src/AdvisoryAi/StellaOps.AdvisoryAI.WebService/Endpoints/AttestationEndpoints.cs`) - REST endpoints for attestation/audit retrieval
|
||||
- `NullEvidencePackSigner` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Evidence/NullEvidencePackSigner.cs`) - no-op evidence pack signer for development
|
||||
- `AdvisoryPipelineMetrics` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Metrics/AdvisoryPipelineMetrics.cs`) - metrics collection for audit visibility
|
||||
- **Interfaces**: None (uses concrete audit pipeline)
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Send a chat message and verify `AdvisoryChatAuditEnvelopeBuilder` creates a DSSE-signed envelope containing the prompt, response, and model fingerprint
|
||||
- [ ] Verify `ChatAuditRecords` captures tool call invocations with parameters and results
|
||||
- [ ] Verify `PostgresAdvisoryChatAuditLogger` persists audit records and they are retrievable via `AttestationEndpoints`
|
||||
- [ ] Verify audit envelopes are immutable: attempting to modify a persisted record fails
|
||||
- [ ] Verify audit records include model identifier, temperature setting, and token counts
|
||||
- [ ] Verify audit log entries are queryable by user, session, and time range
|
||||
@@ -0,0 +1,28 @@
|
||||
# LLM Inference Response Caching
|
||||
|
||||
## Module
|
||||
AdvisoryAI
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
In-memory LLM inference cache that deduplicates identical prompt+model combinations. Reduces API costs and latency by caching deterministic responses keyed by content hash.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/AdvisoryAi/StellaOps.AdvisoryAI/Inference/LlmProviders/`
|
||||
- **Key Classes**:
|
||||
- `LlmInferenceCache` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Inference/LlmProviders/LlmInferenceCache.cs`) - in-memory cache keyed by content hash of prompt+model+parameters
|
||||
- `LlmProviderFactory` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Inference/LlmProviders/LlmProviderFactory.cs`) - factory that wraps providers with caching layer
|
||||
- `LlmProviderOptions` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Inference/LlmProviders/LlmProviderOptions.cs`) - provider options including cache TTL and size limits
|
||||
- `ProviderBasedAdvisoryInferenceClient` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Inference/ProviderBasedAdvisoryInferenceClient.cs`) - inference client that uses the caching layer
|
||||
- **Interfaces**: `ILlmProvider`
|
||||
- **Source**: SPRINT_20251226_019_AI_offline_inference.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Send identical prompts twice and verify `LlmInferenceCache` returns the cached response on the second call without hitting the LLM
|
||||
- [ ] Verify cache keys include model ID and parameters: same prompt with different temperature results in cache miss
|
||||
- [ ] Verify cache TTL: cached responses expire after configured duration
|
||||
- [ ] Verify cache size limits: when max entries are reached, oldest entries are evicted
|
||||
- [ ] Verify cache bypass: non-deterministic requests (temperature > 0) are not cached
|
||||
- [ ] Verify `ProviderBasedAdvisoryInferenceClient` correctly integrates caching with the provider pipeline
|
||||
@@ -0,0 +1,40 @@
|
||||
# LLM Provider Plugin Architecture (Multi-Provider Inference)
|
||||
|
||||
## Module
|
||||
AdvisoryAI
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Pluggable LLM provider architecture with ILlmProvider interface supporting OpenAI, Claude, Gemini, llama.cpp (LlamaServer), and Ollama backends. Includes LlmProviderFactory for runtime selection and configuration validation. Enables sovereign/offline inference by switching to local providers.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/AdvisoryAi/StellaOps.AdvisoryAI/Inference/LlmProviders/`, `src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/Inference/`, `src/AdvisoryAi/StellaOps.AdvisoryAI.Plugin.Unified/`
|
||||
- **Key Classes**:
|
||||
- `LlmProviderFactory` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Inference/LlmProviders/LlmProviderFactory.cs`) - factory for runtime LLM provider selection
|
||||
- `OpenAiLlmProvider` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Inference/LlmProviders/OpenAiLlmProvider.cs`) - OpenAI API provider
|
||||
- `ClaudeLlmProvider` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Inference/LlmProviders/ClaudeLlmProvider.cs`) - Anthropic Claude API provider
|
||||
- `GeminiLlmProvider` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Inference/LlmProviders/GeminiLlmProvider.cs`) - Google Gemini API provider
|
||||
- `LlamaServerLlmProvider` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Inference/LlmProviders/LlamaServerLlmProvider.cs`) - local llama.cpp server provider
|
||||
- `OllamaLlmProvider` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Inference/LlmProviders/OllamaLlmProvider.cs`) - Ollama local inference provider
|
||||
- `LlmProviderOptions` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Inference/LlmProviders/LlmProviderOptions.cs`) - provider configuration and validation
|
||||
- `ClaudeInferenceClient` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/Inference/ClaudeInferenceClient.cs`) - Claude-specific chat inference client
|
||||
- `OpenAIInferenceClient` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/Inference/OpenAIInferenceClient.cs`) - OpenAI-specific chat inference client
|
||||
- `OllamaInferenceClient` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/Inference/OllamaInferenceClient.cs`) - Ollama-specific chat inference client
|
||||
- `LocalInferenceClient` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/Inference/LocalInferenceClient.cs`) - local model inference client
|
||||
- `LlmPluginAdapter` (`src/AdvisoryAi/StellaOps.AdvisoryAI.Plugin.Unified/LlmPluginAdapter.cs`) - unified plugin adapter for LLM providers
|
||||
- `LlmPluginAdapterFactory` (`src/AdvisoryAi/StellaOps.AdvisoryAI.Plugin.Unified/LlmPluginAdapterFactory.cs`) - factory for creating LLM plugin adapters
|
||||
- `SystemPromptLoader` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/Inference/SystemPromptLoader.cs`) - loads system prompts for inference clients
|
||||
- **Interfaces**: `ILlmProvider`, `ILlmProviderPlugin`, `IAdvisoryChatInferenceClient`
|
||||
- **Source**: SPRINT_20251226_019_AI_offline_inference.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Configure `LlmProviderFactory` with multiple providers and verify runtime selection based on configuration
|
||||
- [ ] Verify `OpenAiLlmProvider` sends requests to OpenAI API with correct authentication and model parameters
|
||||
- [ ] Verify `ClaudeLlmProvider` sends requests to Claude API with correct authentication
|
||||
- [ ] Verify `OllamaLlmProvider` connects to local Ollama instance and performs inference
|
||||
- [ ] Verify `LlamaServerLlmProvider` connects to local llama.cpp server endpoint
|
||||
- [ ] Verify `LlmProviderOptions` validation rejects invalid configurations (missing API keys, invalid endpoints)
|
||||
- [ ] Verify `LlmPluginAdapter` provides health checks for configured LLM providers
|
||||
- [ ] Verify provider failover: when primary provider is unavailable, factory falls back to secondary
|
||||
@@ -0,0 +1,31 @@
|
||||
# Natural Language to Policy Rule Compiler (Policy Studio Copilot)
|
||||
|
||||
## Module
|
||||
AdvisoryAI
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
AI-powered natural language to lattice rule translation engine including PolicyIntentType parsing, LatticeRuleGenerator, property-based test synthesizer for generated rules, and PolicyBundleCompiler. Transforms plain-English policy descriptions into formal stella-dsl@1 rules with live preview and conflict visualization.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/AdvisoryAi/StellaOps.AdvisoryAI/PolicyStudio/`
|
||||
- **Key Classes**:
|
||||
- `AiPolicyIntentParser` (`src/AdvisoryAi/StellaOps.AdvisoryAI/PolicyStudio/AiPolicyIntentParser.cs`) - parses natural language into structured policy intents using LLM
|
||||
- `LatticeRuleGenerator` (`src/AdvisoryAi/StellaOps.AdvisoryAI/PolicyStudio/LatticeRuleGenerator.cs`) - generates K4 lattice rules from parsed policy intents
|
||||
- `PropertyBasedTestSynthesizer` (`src/AdvisoryAi/StellaOps.AdvisoryAI/PolicyStudio/PropertyBasedTestSynthesizer.cs`) - synthesizes property-based test cases for generated rules
|
||||
- `PolicyBundleCompiler` (`src/AdvisoryAi/StellaOps.AdvisoryAI/PolicyStudio/PolicyBundleCompiler.cs`) - compiles generated rules into a deployable policy bundle
|
||||
- `PolicyIntent` (`src/AdvisoryAi/StellaOps.AdvisoryAI/PolicyStudio/PolicyIntent.cs`) - policy intent model with type, constraints, and conditions
|
||||
- `InMemoryPolicyIntentStore` (`src/AdvisoryAi/StellaOps.AdvisoryAI/PolicyStudio/InMemoryPolicyIntentStore.cs`) - stores policy intents for iterative refinement
|
||||
- `NullPolicyIntentParser` (`src/AdvisoryAi/StellaOps.AdvisoryAI/PolicyStudio/NullPolicyIntentParser.cs`) - no-op parser for testing
|
||||
- **Interfaces**: `IPolicyIntentParser`, `IPolicyRuleGenerator`, `ITestCaseSynthesizer`
|
||||
- **Source**: SPRINT_20251226_017_AI_policy_copilot.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Submit a natural language policy description (e.g., "block critical CVEs without a fix") and verify `AiPolicyIntentParser` produces a structured `PolicyIntent`
|
||||
- [ ] Verify `LatticeRuleGenerator` translates the intent into valid stella-dsl@1 lattice rules
|
||||
- [ ] Verify `PropertyBasedTestSynthesizer` generates test cases that exercise the generated rule's accept/reject boundaries
|
||||
- [ ] Verify `PolicyBundleCompiler` compiles rules into a deployable bundle with correct schema version
|
||||
- [ ] Verify `InMemoryPolicyIntentStore` supports iterative refinement: modify an intent and regenerate rules
|
||||
- [ ] Verify conflict detection: generate two conflicting rules and verify the compiler reports the conflict
|
||||
@@ -0,0 +1,28 @@
|
||||
# OpsMemory-Chat Integration (Decision Memory in AI Conversations)
|
||||
|
||||
## Module
|
||||
AdvisoryAI
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Connects OpsMemory institutional decision memory to AdvisoryAI Chat, enabling the AI to surface relevant past decisions during conversations and automatically record new decisions with outcomes for feedback loop learning.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/`
|
||||
- **Key Classes**:
|
||||
- `OpsMemoryIntegration` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/OpsMemoryIntegration.cs`) - integrates OpsMemory decision retrieval into chat pipeline
|
||||
- `OpsMemoryLinkResolver` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/OpsMemoryLinkResolver.cs`) - resolves OpsMemory links referenced in chat context
|
||||
- `OpsMemoryDataProvider` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/Assembly/Providers/OpsMemoryDataProvider.cs`) - data provider that fetches relevant OpsMemory entries for evidence bundles
|
||||
- `ConversationContextBuilder` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/ConversationContextBuilder.cs`) - includes OpsMemory context in conversation history
|
||||
- **Interfaces**: None (uses concrete integration classes)
|
||||
- **Source**: SPRINT_20260109_011_002_BE_opsmemory_chat_integration.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Ask about a CVE that has a prior decision in OpsMemory and verify `OpsMemoryIntegration` surfaces the past decision in the response
|
||||
- [ ] Verify `OpsMemoryDataProvider` includes relevant past decisions in the evidence bundle for chat responses
|
||||
- [ ] Verify `OpsMemoryLinkResolver` resolves OpsMemory entry links to their full decision details
|
||||
- [ ] Verify `ConversationContextBuilder` enriches prompts with relevant OpsMemory context
|
||||
- [ ] Verify new decisions made during chat are recorded back into OpsMemory for future retrieval
|
||||
- [ ] Verify OpsMemory integration does not include stale decisions (respects TTL/validity windows)
|
||||
32
docs/features/checked/advisoryai/sanctioned-tool-registry.md
Normal file
32
docs/features/checked/advisoryai/sanctioned-tool-registry.md
Normal file
@@ -0,0 +1,32 @@
|
||||
# Sanctioned Tool Registry (Policy-Gated Tool Execution)
|
||||
|
||||
## Module
|
||||
AdvisoryAI
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Tool policy system with sanctioned tool registry controlling which AI tools can be invoked, with read-only defaults and confirmation-gated action tools.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/Settings/`, `src/AdvisoryAi/StellaOps.AdvisoryAI/Tools/`
|
||||
- **Key Classes**:
|
||||
- `AdvisoryChatToolPolicy` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/Settings/AdvisoryChatToolPolicy.cs`) - defines which tools are sanctioned, read-only, or require confirmation
|
||||
- `DeterministicToolset` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Tools/DeterministicToolset.cs`) - deterministic tool implementations (version analysis, dependency analysis)
|
||||
- `AdvisoryChatSettingsService` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/Settings/AdvisoryChatSettingsService.cs`) - manages chat settings including tool policies
|
||||
- `AdvisoryChatSettingsStore` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/Settings/AdvisoryChatSettingsStore.cs`) - persists chat settings and tool policies
|
||||
- `AdvisoryChatSettingsModels` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/Settings/AdvisoryChatSettingsModels.cs`) - settings models for tool access levels
|
||||
- `DependencyAnalysisResult` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Tools/DependencyAnalysisResult.cs`) - result model for dependency analysis tool
|
||||
- `SemanticVersion` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Tools/SemanticVersion.cs`) - semantic version parsing for version analysis tool
|
||||
- `SemanticVersionRange` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Tools/SemanticVersionRange.cs`) - version range matching for dependency tools
|
||||
- **Interfaces**: `IDeterministicToolset`
|
||||
- **Source**: Feature matrix scan
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Configure `AdvisoryChatToolPolicy` with sanctioned tools and verify only those tools can be invoked during chat
|
||||
- [ ] Attempt to invoke a non-sanctioned tool and verify it is rejected with an access denied response
|
||||
- [ ] Verify read-only tools execute without confirmation prompts
|
||||
- [ ] Verify action tools (write operations) require user confirmation before execution
|
||||
- [ ] Verify `DeterministicToolset` provides consistent results for version analysis and dependency analysis
|
||||
- [ ] Verify `AdvisoryChatSettingsService` persists tool policy changes via `AdvisoryChatSettingsStore`
|
||||
@@ -0,0 +1,35 @@
|
||||
# Sovereign/Offline AI Inference with Signed Model Bundles
|
||||
|
||||
## Module
|
||||
AdvisoryAI
|
||||
|
||||
## Status
|
||||
IMPLEMENTED
|
||||
|
||||
## Description
|
||||
Local LLM inference for air-gapped environments via a pluggable provider architecture supporting llama.cpp server, Ollama, OpenAI, Claude, and Gemini. DSSE-signed model bundle management with regional crypto support (eIDAS/FIPS/GOST/SM), digest verification at load time, deterministic output config (temperature=0, fixed seed), inference caching, benchmarking harness, and offline replay verification.
|
||||
|
||||
## Implementation Details
|
||||
- **Modules**: `src/AdvisoryAi/StellaOps.AdvisoryAI/Inference/`
|
||||
- **Key Classes**:
|
||||
- `SignedModelBundleManager` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Inference/SignedModelBundleManager.cs`) - manages DSSE-signed model bundles with digest verification at load time
|
||||
- `ModelBundle` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Inference/ModelBundle.cs`) - model bundle metadata including hash, signature, and regional crypto info
|
||||
- `LlamaCppRuntime` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Inference/LlamaCppRuntime.cs`) - llama.cpp local inference runtime
|
||||
- `OnnxRuntime` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Inference/OnnxRuntime.cs`) - ONNX runtime for local model inference
|
||||
- `AdvisoryInferenceClient` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Inference/AdvisoryInferenceClient.cs`) - main inference client with provider routing
|
||||
- `ProviderBasedAdvisoryInferenceClient` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Inference/ProviderBasedAdvisoryInferenceClient.cs`) - provider-based inference with caching
|
||||
- `LlmBenchmark` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Inference/LlmBenchmark.cs`) - benchmarking harness for inference performance
|
||||
- `LocalInferenceOptions` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Inference/LocalInferenceOptions.cs`) - configuration for local inference (temperature, seed, context size)
|
||||
- `LocalLlmConfig` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Inference/LocalLlmConfig.cs`) - local LLM configuration (model path, quantization, GPU layers)
|
||||
- `LocalChatInferenceClient` (`src/AdvisoryAi/StellaOps.AdvisoryAI/Chat/Services/LocalChatInferenceClient.cs`) - chat-specific local inference client
|
||||
- **Interfaces**: `ILocalLlmRuntime`
|
||||
- **Source**: SPRINT_20251226_019_AI_offline_inference.md
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Load a signed model bundle via `SignedModelBundleManager` and verify DSSE signature and digest are validated
|
||||
- [ ] Verify `SignedModelBundleManager` rejects a model bundle with a tampered digest
|
||||
- [ ] Run inference through `LlamaCppRuntime` with temperature=0 and fixed seed and verify deterministic output
|
||||
- [ ] Run `LlmBenchmark` and verify it measures tokens/second and latency metrics
|
||||
- [ ] Verify `OnnxRuntime` loads and runs inference with an ONNX model
|
||||
- [ ] Configure `LocalInferenceOptions` with air-gap settings and verify no external network calls are made
|
||||
- [ ] Verify `ProviderBasedAdvisoryInferenceClient` caches deterministic responses and returns cached results on repeat queries
|
||||
@@ -0,0 +1,42 @@
|
||||
# Attestation Bundle Verification
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Sigstore bundle verification with dedicated verifier and bundler services for validating attestation integrity.
|
||||
|
||||
## Implementation Details
|
||||
- **Sigstore Bundle Verifier**: `src/Attestor/__Libraries/StellaOps.Attestor.Bundle/Verification/SigstoreBundleVerifier.cs` -- verifies Sigstore bundles including signature validation and transparency log verification.
|
||||
- **Bundle Verification Result**: `BundleVerificationResult.cs` -- result model with pass/fail status and detailed error messages.
|
||||
- **Sigstore Bundle Model**: `src/Attestor/__Libraries/StellaOps.Attestor.Bundle/Models/SigstoreBundle.cs` -- represents a Sigstore bundle with `VerificationMaterial`, `TransparencyLogEntry`, and `InclusionProof`.
|
||||
- **Bundle Builder**: `src/Attestor/__Libraries/StellaOps.Attestor.Bundle/Builder/SigstoreBundleBuilder.cs` -- constructs Sigstore bundles from attestation components.
|
||||
- **Bundle Serializer**: `src/Attestor/__Libraries/StellaOps.Attestor.Bundle/Serialization/SigstoreBundleSerializer.cs` -- JSON serialization/deserialization of Sigstore bundles.
|
||||
- **Attestation Bundler**: `src/Attestor/__Libraries/StellaOps.Attestor.Bundling/Services/AttestationBundler.cs` -- high-level bundling service implementing `IAttestationBundler`. Aggregates multiple attestations into bundles.
|
||||
- **Bundle Aggregator**: `IBundleAggregator.cs` -- interface for aggregating attestations.
|
||||
- **Bundle Store**: `IBundleStore.cs` -- persistence interface for bundles.
|
||||
- **Org Key Signing**: `Signing/KmsOrgKeySigner.cs` -- signs bundles with organization-level KMS keys.
|
||||
- **Verification Engine**: `src/Attestor/StellaOps.Attestor.Verify/AttestorVerificationEngine.cs` -- top-level verification engine that orchestrates bundle and attestation verification.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.Bundle.Tests/SigstoreBundleVerifierTests.cs`, `SigstoreBundleBuilderTests.cs`, `SigstoreBundleSerializerTests.cs`, `__Tests/StellaOps.Attestor.Bundling.Tests/AttestationBundlerTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Build a Sigstore bundle via `SigstoreBundleBuilder` with a signed attestation, inclusion proof, and verification material, then verify it via `SigstoreBundleVerifier`
|
||||
- [ ] Serialize a `SigstoreBundle` to JSON via `SigstoreBundleSerializer`, deserialize it back, and verify round-trip fidelity
|
||||
- [ ] Tamper with the inclusion proof in a bundle and verify `SigstoreBundleVerifier` returns a failed `BundleVerificationResult` with error details
|
||||
- [ ] Use `AttestationBundler` to aggregate 3+ attestations into a single bundle and verify the bundle contains all attestation entries
|
||||
- [ ] Sign a bundle with `KmsOrgKeySigner` and verify the org-level signature is present in the output
|
||||
- [ ] Run `AttestorVerificationEngine` against a valid bundle and verify all verification checks pass
|
||||
- [ ] Run `AttestorVerificationEngine` against a bundle with an invalid signature and verify it reports the specific check that failed
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,40 @@
|
||||
# Attestation Determinism Testing
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Golden test vectors and determinism verification tests ensuring byte-for-byte reproducibility of attestations, DSSE envelopes, and policy engine evaluations.
|
||||
|
||||
## Implementation Details
|
||||
- **Golden Samples Tests**: `src/Attestor/__Tests/StellaOps.Attestor.Types.Tests/AttestationGoldenSamplesTests.cs` -- verifies attestations match golden test vectors byte-for-byte.
|
||||
- **Attestation Determinism Tests**: `__Tests/StellaOps.Attestor.Types.Tests/Determinism/AttestationDeterminismTests.cs` -- ensures repeated attestation generation produces identical output.
|
||||
- **DSSE Envelope Determinism**: `__Tests/StellaOps.Attestor.ProofChain.Tests/Envelope/DsseEnvelopeDeterminismTests.cs` -- verifies DSSE envelope serialization is deterministic.
|
||||
- **In-Toto Statement Snapshots**: `__Tests/StellaOps.Attestor.ProofChain.Tests/Statements/InTotoStatementSnapshotTests.cs` -- snapshot tests for in-toto statement serialization stability.
|
||||
- **Canonical JSON**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Json/Rfc8785JsonCanonicalizer.cs` (with `.DecimalPoint`, `.NumberSerialization`, `.StringNormalization`, `.WriteMethods` partials) -- RFC 8785 canonical JSON serialization ensuring deterministic output.
|
||||
- **CycloneDX Determinism**: `__Tests/StellaOps.Attestor.StandardPredicates.Tests/CycloneDxDeterminismTests.cs` -- verifies CycloneDX SBOM output is deterministic.
|
||||
- **SPDX Determinism**: `__Tests/StellaOps.Attestor.StandardPredicates.Tests/SpdxDeterminismTests.cs` -- verifies SPDX SBOM output is deterministic.
|
||||
- **Canonical JSON Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/JsonCanonicalizerTests.cs`, `__Tests/StellaOps.Attestor.StandardPredicates.Tests/JsonCanonicalizerTests.cs`
|
||||
- **Conformance Tests**: `__Tests/StellaOps.Attestor.Conformance.Tests/` -- `VerificationParityTests.cs`, `InclusionProofParityTests.cs`, `CheckpointParityTests.cs` verify cross-implementation consistency.
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Generate an attestation from identical inputs twice and compare SHA-256 hashes of the serialized output to verify byte-for-byte equality
|
||||
- [ ] Serialize a DSSE envelope, deserialize it, re-serialize, and verify the output bytes are identical (idempotent serialization)
|
||||
- [ ] Run the RFC 8785 canonicalizer on JSON with out-of-order keys, varied whitespace, and Unicode escapes, then verify the output matches the canonical form
|
||||
- [ ] Generate CycloneDX SBOM output from identical inputs on two separate runs and verify SHA-256 hash match
|
||||
- [ ] Generate SPDX SBOM output from identical inputs on two separate runs and verify SHA-256 hash match
|
||||
- [ ] Verify golden sample test vectors by comparing generated attestation against known-good fixtures stored in the test project
|
||||
- [ ] Run conformance parity tests to verify Attestor output matches reference implementations for checkpoint parsing, inclusion proofs, and verification
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,40 @@
|
||||
# Attestation Timestamp Pipeline with Time Correlation Validation
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Integration of RFC 3161 timestamps into the attestation pipeline with TST-Rekor time correlation validation that detects anti-backdating attempts by cross-referencing TST genTime against Rekor integratedTime. Includes CycloneDx/SPDX timestamp extensions and policy-gated timestamping. No direct match in known features list.
|
||||
|
||||
## Implementation Details
|
||||
- **Timestamp Service**: `src/Attestor/__Libraries/StellaOps.Attestor.Timestamping/AttestationTimestampService.cs` (with `.Helpers`, `.Timestamp`, `.Verify` partials) -- core RFC 3161 timestamp request/response pipeline.
|
||||
- **Time Correlation Validator**: `TimeCorrelationValidator.cs` (with `.Async`, `.GapChecks`, `.Validate` partials) -- cross-references TST genTime against Rekor integratedTime to detect anti-backdating. `TimeCorrelationPolicy.cs` defines acceptable drift windows. `TimeCorrelationResult.cs` and `TimeCorrelationStatus.cs` capture validation outcomes. `TimeConsistencyResult.cs` aggregates cross-source consistency.
|
||||
- **Timestamp Policy**: `TimestampPolicy.cs`, `TimestampPolicyEvaluator.cs`, `TimestampPolicyResult.cs` -- policy-gated timestamping determining when timestamps are required.
|
||||
- **CycloneDX Timestamp Extension**: `src/Attestor/__Libraries/StellaOps.Attestor.StandardPredicates/Writers/CycloneDxTimestampExtension.cs` (with `.Extract` partial) -- embeds timestamp tokens into CycloneDX output.
|
||||
- **SPDX Timestamp Extension**: `SpdxTimestampExtension.cs` (with `.Extract` partial) -- embeds timestamp tokens into SPDX output.
|
||||
- **Rekor Receipt**: `src/Attestor/__Libraries/StellaOps.Attestor.Timestamping/RekorReceipt.cs` -- Rekor receipt model with `integratedTime` for cross-reference.
|
||||
- **TSA Multi-Provider**: `src/Attestor/__Libraries/StellaOps.Attestor.Infrastructure/Timestamping/TsaMultiProvider.cs` -- fallback chain across TSA providers.
|
||||
- **Configuration**: `AttestationTimestampOptions.cs`, `AttestationTimestampServiceOptions.cs`, `AttestationTimestampVerificationOptions.cs`, `AttestationTimestampPolicyContext.cs`.
|
||||
- **Tests**: `StellaOps.Attestor.Tests/Timestamping/AttestationTimestampServiceTests.cs`, `AttestationTimestampPolicyTests.cs`, `TimeCorrelationValidatorTests.cs`, `__Tests/StellaOps.Attestor.StandardPredicates.Tests/TimestampExtensionTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Timestamp an attestation via `AttestationTimestampService`, retrieve the Rekor receipt, and verify `TimeCorrelationValidator` passes when TST genTime and Rekor integratedTime are within the configured drift window
|
||||
- [ ] Set a strict `TimeCorrelationPolicy` (e.g., max 5-second drift) and submit a timestamp where genTime differs from integratedTime by 10 seconds, verifying the validator returns a failure `TimeCorrelationStatus`
|
||||
- [ ] Evaluate `TimestampPolicyEvaluator` with a policy requiring timestamps for production artifacts and verify it gates appropriately
|
||||
- [ ] Generate a CycloneDX SBOM with `CycloneDxTimestampExtension` and verify the timestamp token is embedded in the output
|
||||
- [ ] Generate an SPDX SBOM with `SpdxTimestampExtension` and verify the timestamp token is embedded in the output
|
||||
- [ ] Extract timestamps from a CycloneDX document and verify the extracted `genTime` matches the original
|
||||
- [ ] Test `TsaMultiProvider` fallback by simulating primary TSA timeout and verifying secondary provider is used
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,40 @@
|
||||
# Attestor Conformance Test Suite
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Conformance test suite verifying Sigstore/Rekor verification parity against reference implementations. Tests inclusion proof verification, checkpoint parsing, and signature validation against known-good test vectors.
|
||||
|
||||
## Implementation Details
|
||||
- **Conformance Tests**: `src/Attestor/__Tests/StellaOps.Attestor.Conformance.Tests/` -- dedicated conformance test project:
|
||||
- `VerificationParityTests.cs` -- verifies attestation verification produces identical results to reference implementations
|
||||
- `InclusionProofParityTests.cs` -- verifies Merkle inclusion proof verification matches reference
|
||||
- `CheckpointParityTests.cs` -- verifies checkpoint parsing and validation matches reference
|
||||
- `ConformanceTestFixture.cs` -- shared fixture with known-good test vectors
|
||||
- **Checkpoint Verification**: `src/Attestor/StellaOps.Attestor/StellaOps.Attestor.Core/Verification/CheckpointSignatureVerifier.cs` -- checkpoint signature verification against reference. Tests: `StellaOps.Attestor.Core.Tests/Verification/CheckpointSignatureVerifierTests.cs`
|
||||
- **Merkle Proof Verifier**: `StellaOps.Attestor.Core/Verification/MerkleProofVerifier.cs` -- verifies Merkle inclusion proofs. Tests: `StellaOps.Attestor.Tests/MerkleProofVerifierTests.cs`
|
||||
- **Rekor Receipt Verification**: `StellaOps.Attestor.Core/Rekor/RekorReceipt.cs` -- receipt model. `StellaOps.Attestor.Core/Verification/RekorOfflineReceiptVerifier.cs` -- offline receipt verification. Tests: `StellaOps.Attestor.Core.Tests/RekorOfflineReceiptVerifierTests.cs`, `StellaOps.Attestor.Core.Tests/Rekor/RekorReceiptTests.cs`
|
||||
- **Checkpoint Divergence**: `StellaOps.Attestor.Core/Rekor/CheckpointDivergenceDetector.cs` -- detects split-world attacks. Tests: `StellaOps.Attestor.Core.Tests/Rekor/CheckpointDivergenceDetectorTests.cs`, `CheckpointDivergenceByzantineTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Run `VerificationParityTests` against known-good Sigstore verification test vectors and verify all pass
|
||||
- [ ] Run `InclusionProofParityTests` with reference Merkle proofs and verify computed roots match expected values
|
||||
- [ ] Run `CheckpointParityTests` with reference checkpoint data and verify signature validation matches expected outcomes
|
||||
- [ ] Verify `CheckpointSignatureVerifier` validates a signed checkpoint against a known public key and returns success
|
||||
- [ ] Verify `MerkleProofVerifier` validates an inclusion proof with correct sibling hashes and returns the correct root
|
||||
- [ ] Verify `RekorOfflineReceiptVerifier` validates a receipt without network access using embedded inclusion proof
|
||||
- [ ] Run `CheckpointDivergenceDetector` with two checkpoints from different Rekor instances showing divergent trees and verify detection
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,40 @@
|
||||
# Auditor Evidence Extraction (Audit Pack / Evidence Pack)
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Exportable evidence packs (audit bundles) containing RVA attestation, policy bundle, knowledge snapshot manifest, referenced evidence artifacts, and verification replay logs for auditor consumption.
|
||||
|
||||
## Implementation Details
|
||||
- **Evidence Pack Builder**: `src/Attestor/__Libraries/StellaOps.Attestor.EvidencePack/ReleaseEvidencePackBuilder.cs` -- constructs complete evidence packs containing all artifacts needed for audit verification.
|
||||
- **Evidence Pack Serializer**: `ReleaseEvidencePackSerializer.cs` -- serializes evidence packs to portable format.
|
||||
- **Evidence Pack Manifest**: `Models/ReleaseEvidencePackManifest.cs` -- manifest listing all artifacts in the pack with digests.
|
||||
- **Verification Replay Log**: `Models/VerificationReplayLog.cs` -- captures the sequence of verification steps for deterministic replay.
|
||||
- **Replay Log Builder**: `Services/VerificationReplayLogBuilder.cs` -- builds replay logs during verification. `ReplayLogSerializerContext.cs` -- serialization context.
|
||||
- **Archive Store**: `src/Attestor/StellaOps.Attestor/StellaOps.Attestor.Core/Storage/IAttestorArchiveStore.cs`, `AttestorArchiveBundle.cs` -- interface and model for archive storage. `Infrastructure/Storage/S3AttestorArchiveStore.cs`, `NullAttestorArchiveStore.cs` -- S3 and null implementations.
|
||||
- **Audit Records**: `StellaOps.Attestor.Core/Audit/AttestorAuditRecord.cs` -- audit record model. `StellaOps.Attestor.Core/Storage/IAttestorAuditSink.cs` -- sink interface.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.EvidencePack.Tests/ReleaseEvidencePackBuilderTests.cs`, `ReleaseEvidencePackManifestTests.cs`, `VerificationReplayLogBuilderTests.cs`
|
||||
- **Integration Tests**: `__Tests/StellaOps.Attestor.EvidencePack.IntegrationTests/` -- `EvidencePackGenerationTests.cs`, `OfflineVerificationTests.cs`, `ReproducibilityTests.cs`, `TamperDetectionTests.cs`, `SlsaStrictValidationTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Build a `ReleaseEvidencePackManifest` via `ReleaseEvidencePackBuilder` with SBOM, VEX, attestation, and provenance artifacts, then verify manifest contains entries for each artifact with correct SHA-256 digests
|
||||
- [ ] Serialize the evidence pack via `ReleaseEvidencePackSerializer` and verify the output can be deserialized back with all artifacts intact
|
||||
- [ ] Build a `VerificationReplayLog` capturing 5+ verification steps and verify the log contains each step in order with timestamps and results
|
||||
- [ ] Export the evidence pack, then replay verification using the replay log and verify identical outcomes (reproducibility)
|
||||
- [ ] Tamper with an artifact in the exported pack and verify that digest verification detects the modification
|
||||
- [ ] Archive an evidence pack to S3 via `S3AttestorArchiveStore` and retrieve it, verifying content integrity
|
||||
- [ ] Verify the evidence pack includes all required audit artifacts (attestation chain, policy bundle, knowledge snapshot)
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,41 @@
|
||||
# Auditor-Ready Evidence Export Packs (SBOM + VEX + Attestation + Provenance)
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Full audit pack export system with verdict replay attestation, evidence bundling, and export center with timeline integration and scheduling.
|
||||
|
||||
## Implementation Details
|
||||
- **Evidence Pack Builder**: `src/Attestor/__Libraries/StellaOps.Attestor.EvidencePack/ReleaseEvidencePackBuilder.cs` -- constructs export-ready evidence packs containing SBOM, VEX, attestation, and provenance artifacts.
|
||||
- **Evidence Pack Manifest**: `Models/ReleaseEvidencePackManifest.cs` -- manifest with digest-verified artifact listings.
|
||||
- **Evidence Pack Serializer**: `ReleaseEvidencePackSerializer.cs` -- portable serialization format.
|
||||
- **Verification Replay Log**: `Models/VerificationReplayLog.cs` -- captures verification steps for replay. `Services/VerificationReplayLogBuilder.cs` -- builds replay logs.
|
||||
- **Offline Kit Bundle**: `src/Attestor/__Libraries/StellaOps.Attestor.Bundling/Services/OfflineKitBundleProvider.cs` -- provides offline-ready bundles for air-gap scenarios.
|
||||
- **Attestation Bundler**: `AttestationBundler.cs` -- aggregates attestations. `IBundleStore.cs` -- persistence. `BundlingOptions.cs` -- configuration.
|
||||
- **Retention Policy**: `RetentionPolicyEnforcer.cs` -- enforces retention policies on exported packs.
|
||||
- **Archive Storage**: `StellaOps.Attestor.Core/Storage/IAttestorArchiveStore.cs` -- archive interface. `S3AttestorArchiveStore.cs` -- S3 implementation.
|
||||
- **Offline Bundle**: `StellaOps.Attestor.Core/Offline/AttestorOfflineBundle.cs`, `IAttestorBundleService.cs` -- offline bundle support.
|
||||
- **Integration Tests**: `__Tests/StellaOps.Attestor.EvidencePack.IntegrationTests/` -- `EvidencePackGenerationTests.cs`, `OfflineVerificationTests.cs`, `ReproducibilityTests.cs`, `TamperDetectionTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Build a complete evidence export pack containing SBOM (CycloneDX), VEX document, DSSE-signed attestation, and SLSA provenance via `ReleaseEvidencePackBuilder`
|
||||
- [ ] Serialize the pack and verify the manifest lists all four artifact types with correct SHA-256 digests
|
||||
- [ ] Export an offline kit via `OfflineKitBundleProvider` and verify all required artifacts are included for air-gap verification
|
||||
- [ ] Verify the replay log captures the full verification sequence and can be replayed to produce identical results
|
||||
- [ ] Test retention policy enforcement by creating a pack older than the retention window and verifying `RetentionPolicyEnforcer` marks it for cleanup
|
||||
- [ ] Archive a pack to S3 and retrieve it, verifying all artifacts are intact and digests match the manifest
|
||||
- [ ] Tamper with a single artifact in the pack and verify integrity validation detects the modification
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,38 @@
|
||||
# Auto-VEX Drafting Attestation
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
VEX draft generation attestation types for AI-generated VEX statements with justifications, enabling lattice-aware merge preview.
|
||||
|
||||
## Implementation Details
|
||||
- **AIVexDraftPredicate**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Predicates/AI/AIVexDraftPredicate.cs` -- extends `AIArtifactBasePredicate` with VEX-specific draft fields.
|
||||
- **AIVexStatementDraft**: `AIVexStatementDraft.cs` -- individual VEX statement draft with status, justification, and product/vulnerability references.
|
||||
- **AIVexJustification**: `AIVexJustification.cs` -- AI-generated justification for VEX status decisions.
|
||||
- **Classifier Integration**: `AIAuthorityClassifier.VexDraft.cs` and `AIAuthorityClassifier.VexDraftScore.cs` -- classifies VEX drafts into Suggestion/EvidenceBacked/AuthorityThreshold.
|
||||
- **Statement**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Statements/AIVexDraftStatement.cs` -- wraps VEX draft as in-toto statement.
|
||||
- **VEX Predicate**: `__Libraries/StellaOps.Attestor.ProofChain/Predicates/VexPredicate.cs` -- base VEX predicate. `VexAttestationPredicate.cs` -- VEX attestation predicate.
|
||||
- **VEX Override System**: `src/Attestor/__Libraries/StellaOps.Attestor.StandardPredicates/VexOverride/` -- `VexOverridePredicateBuilder.cs` (with `.Build`, `.Serialize`, `.WithMethods`), `VexOverridePredicateParser.cs` (with multiple partials) for building and parsing VEX overrides.
|
||||
- **VEX Proof Integration**: `__Libraries/StellaOps.Attestor.ProofChain/Generators/VexProofIntegrator.cs` (with `.Helpers`, `.Metadata`) and `VexVerdictProofPayload.cs` -- integrates VEX drafts into the proof chain.
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Create an `AIVexDraftPredicate` with multiple `AIVexStatementDraft` entries (not_affected, affected, under_investigation) and verify JSON serialization preserves all fields
|
||||
- [ ] Create a VEX draft with `AIVexJustification` containing evidence citations and classify via `AIAuthorityClassifier.VexDraft`, verifying EvidenceBacked authority when citations are sufficient
|
||||
- [ ] Wrap the VEX draft in `AIVexDraftStatement` and verify it produces a valid in-toto statement with correct predicate type
|
||||
- [ ] Build a `VexOverridePredicate` from an AI-generated draft via `VexOverridePredicateBuilder` and verify the override captures the draft's justification
|
||||
- [ ] Parse a serialized VEX override via `VexOverridePredicateParser` and verify all fields round-trip correctly
|
||||
- [ ] Integrate a VEX draft into the proof chain via `VexProofIntegrator` and verify the proof payload contains the draft evidence
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
44
docs/features/checked/attestor/backport-proof-service.md
Normal file
44
docs/features/checked/attestor/backport-proof-service.md
Normal file
@@ -0,0 +1,44 @@
|
||||
# Backport Proof Service
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
BackportProof library in Concelier and multi-tier BackportProofGenerator in Attestor with confidence scoring, evidence combining, and tier-based proof generation (Tier 1 through 4 plus signature variants).
|
||||
|
||||
## Implementation Details
|
||||
- **BackportProofGenerator**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Generators/BackportProofGenerator.cs` -- orchestrates multi-tier backport proof generation. Partials:
|
||||
- `BackportProofGenerator.Tier1.cs` -- Tier 1: exact version match proofs
|
||||
- `BackportProofGenerator.Tier2.cs` -- Tier 2: advisory-level evidence
|
||||
- `BackportProofGenerator.Tier3.cs` -- Tier 3: heuristic/pattern matching
|
||||
- `BackportProofGenerator.Tier3Signature.cs` -- Tier 3 signature variant with binary signature comparison
|
||||
- `BackportProofGenerator.Tier4.cs` -- Tier 4: lowest confidence, inference-based
|
||||
- `BackportProofGenerator.Confidence.cs` -- confidence scoring across tiers using proof-strength hierarchy
|
||||
- `BackportProofGenerator.CombineEvidence.cs` -- evidence aggregation from multiple tiers
|
||||
- `BackportProofGenerator.Status.cs` -- status tracking for proof generation progress
|
||||
- `BackportProofGenerator.VulnerableUnknown.cs` -- handling of unknown vulnerability status
|
||||
- **Evidence Summary**: `EvidenceSummary.cs` -- aggregated evidence output from proof generation.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/BackportProofGeneratorTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Generate a Tier 1 proof for a package with exact version match in advisory data and verify high confidence score (>= 0.9)
|
||||
- [ ] Generate a Tier 2 proof using advisory-level evidence (CVE matches package family) and verify moderate confidence score
|
||||
- [ ] Generate a Tier 3 proof using binary signature comparison and verify it includes signature match details
|
||||
- [ ] Generate a Tier 4 inference-based proof and verify it has the lowest confidence score among all tiers
|
||||
- [ ] Combine evidence from Tier 1 and Tier 2 via `CombineEvidence` and verify the combined confidence is higher than either individual tier
|
||||
- [ ] Generate a proof for a package with `VulnerableUnknown` status and verify the generator handles it with appropriate uncertainty indicators
|
||||
- [ ] Verify `EvidenceSummary` output contains entries from all applicable tiers with per-tier confidence scores
|
||||
- [ ] Generate proofs for the same package twice and verify deterministic output (same confidence scores and evidence)
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,41 @@
|
||||
# Binary Diff Predicate / DSSE Attestation for Patch Detection
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Complete BinaryDiff predicate implementation with DSSE signing/verification, schema validation, normalization, and serialization for patch detection attestations.
|
||||
|
||||
## Implementation Details
|
||||
- **BinaryDiff Predicate Builder**: `src/Attestor/__Libraries/StellaOps.Attestor.StandardPredicates/BinaryDiff/BinaryDiffPredicateBuilder.cs` (with `.Build` partial) -- implements `IBinaryDiffPredicateBuilder` to construct binary diff predicates from diff findings.
|
||||
- **BinaryDiff Predicate Serializer**: `BinaryDiffPredicateSerializer.cs` (with `.Normalize` partial) -- implements `IBinaryDiffPredicateSerializer` for deterministic serialization with normalization.
|
||||
- **DSSE Signing**: `BinaryDiffDsseSigner.cs` -- signs binary diff predicates as DSSE envelopes.
|
||||
- **DSSE Verification**: `BinaryDiffDsseVerifier.cs` (with `.Helpers` partial) -- implements `IBinaryDiffDsseVerifier` for verifying signed binary diff attestations.
|
||||
- **Schema Validation**: `BinaryDiffSchema.cs` (with `.SchemaJson` partial) -- JSON schema for binary diff predicates. `BinaryDiffSchemaValidationResult.cs` -- validation result model.
|
||||
- **Models**: `BinaryDiffModels.cs` -- core diff models. `BinaryDiffSectionModels.cs` -- section-level diff models (ELF/PE sections). `BinaryDiffFinding.cs` -- individual diff finding. `BinaryDiffOptions.cs` -- configuration.
|
||||
- **Metadata**: `BinaryDiffMetadataBuilder.cs` -- builds metadata for diff predicates.
|
||||
- **DI Registration**: `ServiceCollectionExtensions.cs` -- registers all BinaryDiff services.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.StandardPredicates.Tests/BinaryDiff/` -- `BinaryDiffPredicateBuilderTests.cs`, `BinaryDiffPredicateSerializerTests.cs`, `BinaryDiffDsseSignerTests.cs`, `BinaryDiffSchemaValidationTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Build a binary diff predicate from a set of `BinaryDiffFinding` entries via `BinaryDiffPredicateBuilder` and verify the predicate contains all findings
|
||||
- [ ] Serialize the predicate via `BinaryDiffPredicateSerializer` and verify normalization produces deterministic output (serialize twice, compare bytes)
|
||||
- [ ] Sign the serialized predicate via `BinaryDiffDsseSigner` and verify the DSSE envelope is well-formed
|
||||
- [ ] Verify the signed envelope via `BinaryDiffDsseVerifier` and confirm verification passes
|
||||
- [ ] Tamper with the signed envelope payload and verify `BinaryDiffDsseVerifier` returns failure
|
||||
- [ ] Validate a predicate against the JSON schema via `BinaryDiffSchema` and verify it passes
|
||||
- [ ] Create a predicate with section-level diffs (`BinaryDiffSectionModels`) for ELF `.text` and `.rodata` sections and verify section details are preserved
|
||||
- [ ] Create a predicate missing required fields and verify schema validation catches the error
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,42 @@
|
||||
# Binary Diff with Deterministic Signatures
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Binary diff analysis with DSSE-signed evidence output is implemented. The system compares binaries, produces deterministic diff signatures, serializes predicates, and integrates with VEX evidence linking. While the advisory specifically mentions B2R2 IR lifting, the implemented approach uses binary section-level diffing with DSSE attestation.
|
||||
|
||||
## Implementation Details
|
||||
- **BinaryDiff Predicate System**: `src/Attestor/__Libraries/StellaOps.Attestor.StandardPredicates/BinaryDiff/` -- full predicate lifecycle:
|
||||
- `BinaryDiffPredicateBuilder.cs` (with `.Build`) -- constructs predicates from diff findings
|
||||
- `BinaryDiffPredicateSerializer.cs` (with `.Normalize`) -- deterministic serialization via normalization
|
||||
- `BinaryDiffDsseSigner.cs` -- DSSE envelope signing for deterministic signatures
|
||||
- `BinaryDiffDsseVerifier.cs` (with `.Helpers`) -- signature verification
|
||||
- `BinaryDiffSectionModels.cs` -- section-level diff models for ELF/PE binaries
|
||||
- **Evidence Integration**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Generators/BinaryFingerprintEvidenceGenerator.cs` (with `.Helpers` partial) -- generates fingerprint evidence from binary analysis.
|
||||
- **Binary Identity**: `__Libraries/StellaOps.Attestor.ProofChain/Predicates/BinaryIdentityInfo.cs` -- binary identity model. `BinaryVulnMatchInfo.cs` -- vulnerability match details.
|
||||
- **Binary Fingerprint Predicate**: `BinaryFingerprintEvidencePredicate.cs` -- predicate for fingerprint evidence.
|
||||
- **VEX Integration**: `VexProofIntegrator.cs` links binary diff evidence to VEX decisions.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.StandardPredicates.Tests/BinaryDiff/` -- builder, serializer, signer, schema validation tests
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Perform a binary diff between two versions of a binary and produce a `BinaryDiffPredicateBuilder` output with section-level changes
|
||||
- [ ] Serialize the diff predicate via `BinaryDiffPredicateSerializer.Normalize` and verify byte-for-byte determinism across two invocations
|
||||
- [ ] Sign the normalized predicate via `BinaryDiffDsseSigner` and verify the DSSE envelope signature is valid
|
||||
- [ ] Verify the signed diff evidence via `BinaryDiffDsseVerifier` and confirm integrity
|
||||
- [ ] Generate binary fingerprint evidence via `BinaryFingerprintEvidenceGenerator` from a binary with known vulnerability matches and verify `BinaryVulnMatchInfo` is populated
|
||||
- [ ] Link binary diff evidence to a VEX decision via `VexProofIntegrator` and verify the proof chain includes the diff artifact
|
||||
- [ ] Create diff findings for both ELF and PE section types and verify `BinaryDiffSectionModels` handles both formats
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,39 @@
|
||||
# Binary Fingerprint Evidence for Reachability Proofs
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Binary fingerprint evidence generation with identity info, vulnerability match info, and micro-witness binary references provides cryptographic evidence for binary reachability claims.
|
||||
|
||||
## Implementation Details
|
||||
- **BinaryFingerprintEvidenceGenerator**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Generators/BinaryFingerprintEvidenceGenerator.cs` (with `.Helpers` partial) -- generates attestable fingerprint evidence segments from binary vulnerability findings.
|
||||
- **BinaryFingerprintEvidencePredicate**: `__Libraries/StellaOps.Attestor.ProofChain/Predicates/BinaryFingerprintEvidencePredicate.cs` -- predicate type for binary fingerprint evidence in proof bundles.
|
||||
- **BinaryIdentityInfo**: `Predicates/BinaryIdentityInfo.cs` -- captures binary identity (path, hash, format, architecture).
|
||||
- **BinaryVulnMatchInfo**: `Predicates/BinaryVulnMatchInfo.cs` -- vulnerability match details linking binary to CVE.
|
||||
- **Micro-Witness Models**: `MicroWitnessBinaryRef.cs` -- binary reference within micro-witness. `MicroWitnessCveRef.cs` -- CVE reference. `MicroWitnessFunctionEvidence.cs` -- function-level evidence. `MicroWitnessSbomRef.cs` -- SBOM cross-reference. `MicroWitnessTooling.cs` -- analysis tool info. `MicroWitnessVerdicts.cs` -- micro-witness verdicts.
|
||||
- **Binary Micro-Witness Predicate**: `BinaryMicroWitnessPredicate.cs` -- complete micro-witness predicate combining binary evidence with reachability data.
|
||||
- **Statement**: `__Libraries/StellaOps.Attestor.ProofChain/Statements/BinaryMicroWitnessStatement.cs` -- in-toto statement wrapper.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/BinaryMicroWitnessPredicateTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Generate binary fingerprint evidence via `BinaryFingerprintEvidenceGenerator` for a binary with known vulnerabilities and verify the output contains `BinaryIdentityInfo` with correct hash and format
|
||||
- [ ] Verify `BinaryVulnMatchInfo` correctly links a binary identity to a specific CVE with match confidence
|
||||
- [ ] Create a `BinaryMicroWitnessPredicate` with `MicroWitnessBinaryRef`, `MicroWitnessCveRef`, and `MicroWitnessFunctionEvidence` and verify all cross-references are populated
|
||||
- [ ] Verify `MicroWitnessSbomRef` correctly links the binary evidence to an SBOM component entry
|
||||
- [ ] Wrap the micro-witness predicate in `BinaryMicroWitnessStatement` and verify it produces a valid in-toto statement
|
||||
- [ ] Generate evidence for a binary with no vulnerability matches and verify the generator produces an empty/clean evidence set
|
||||
- [ ] Verify `MicroWitnessTooling` captures the analysis tool name and version used to generate the evidence
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,38 @@
|
||||
# Binary Fingerprint Evidence Generation
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Extensive binary fingerprinting with disassembly, delta signatures, fingerprint indexing, and attestable proof generation covering ELF/PE analysis.
|
||||
|
||||
## Implementation Details
|
||||
- **Evidence Generator**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Generators/BinaryFingerprintEvidenceGenerator.cs` (with `.Helpers` partial) -- generates attestable proof segments from binary fingerprint analysis. Produces `BinaryFingerprintEvidencePredicate` payloads.
|
||||
- **Binary Identity**: `__Libraries/StellaOps.Attestor.ProofChain/Predicates/BinaryIdentityInfo.cs` -- binary identity (path, hash, format: ELF/PE/Mach-O, architecture).
|
||||
- **Vulnerability Matching**: `BinaryVulnMatchInfo.cs` -- links binary identity to CVE matches with confidence.
|
||||
- **Micro-Witness Evidence**: `MicroWitnessBinaryRef.cs`, `MicroWitnessFunctionEvidence.cs` -- function-level evidence linking fingerprints to reachability. `MicroWitnessTooling.cs` -- tool metadata.
|
||||
- **Binary Diff Integration**: `src/Attestor/__Libraries/StellaOps.Attestor.StandardPredicates/BinaryDiff/` -- `BinaryDiffPredicateBuilder.cs`, `BinaryDiffSectionModels.cs` handle section-level diffing for delta signature computation.
|
||||
- **Content-Addressed Storage**: fingerprint evidence is content-addressed via `ContentAddressedIdGenerator` from `__Libraries/StellaOps.Attestor.ProofChain/Identifiers/`.
|
||||
- **Note**: Actual binary disassembly and fingerprint indexing lives in `src/BinaryIndex/` module; Attestor provides the attestation layer wrapping those results.
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Generate fingerprint evidence from a binary analysis result containing ELF section hashes and verify `BinaryFingerprintEvidencePredicate` captures all section fingerprints
|
||||
- [ ] Generate fingerprint evidence from PE binary analysis and verify format-specific sections (.text, .rdata, .rsrc) are represented
|
||||
- [ ] Verify the evidence generator produces content-addressed IDs for each fingerprint evidence artifact
|
||||
- [ ] Create delta signatures by running the generator on two binary versions and verify the diff captures added/removed/changed sections
|
||||
- [ ] Verify `MicroWitnessFunctionEvidence` links specific functions to their fingerprint evidence
|
||||
- [ ] Run the generator twice on identical inputs and verify deterministic output (same evidence IDs)
|
||||
- [ ] Verify the generated evidence can be embedded in a DSSE-signed attestation via the proof chain signing infrastructure
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,46 @@
|
||||
# Binary Fingerprint Store and Trust Scoring
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Binary analysis commands exist in the CLI with score gating, confidence calculation is implemented in the Policy engine, and a Doctor plugin for binary analysis health checks exists. A full binary fingerprint database with ELF/PE section hashing, trust scores, and golden set as described is partially implemented through the existing binary analysis infrastructure.
|
||||
|
||||
## What's Implemented
|
||||
- **Binary Fingerprint Evidence Generator**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Generators/BinaryFingerprintEvidenceGenerator.cs` (with `.Helpers`) -- generates binary fingerprint evidence from analyzed binaries.
|
||||
- **Binary Identity Info**: `Predicates/BinaryIdentityInfo.cs` -- binary identity information (hash, file path, architecture).
|
||||
- **Binary Vuln Match Info**: `Predicates/BinaryVulnMatchInfo.cs` -- vulnerability match data for binaries.
|
||||
- **Backport Proof Generator**: `Generators/BackportProofGenerator.cs` (with `.Confidence`, `.Tier1`-`.Tier4`) -- confidence scoring for binary-level backport detection.
|
||||
- **Trust Verdict Service**: `__Libraries/StellaOps.Attestor.TrustVerdict/Services/TrustVerdictService.cs` (with `.Scoring`) -- trust scoring infrastructure.
|
||||
- **Evidence Summary**: `Generators/EvidenceSummary.cs` -- evidence summarization for binary analysis results.
|
||||
|
||||
## What's Missing
|
||||
- **Dedicated binary fingerprint database**: No standalone fingerprint store with ELF/PE section-level hashing and content-addressed lookup. Current evidence is generated per-scan, not stored in a queryable fingerprint database.
|
||||
- **Golden set management**: No mechanism to define and maintain a "golden set" of known-good binary fingerprints for comparison.
|
||||
- **Section-level hashing**: ELF `.text`/`.rodata` section hashing and PE section-level fingerprinting are not distinctly implemented as reusable fingerprinting primitives.
|
||||
- **Trust score decay**: Binary trust scores do not decay over time based on staleness; current trust scoring is evaluation-time only.
|
||||
- **Fingerprint comparison API**: No REST endpoint for querying/comparing binary fingerprints against the golden set.
|
||||
|
||||
## Implementation Plan
|
||||
- Create a `BinaryFingerprintStore` service with content-addressed storage for section-level hashes
|
||||
- Implement ELF/PE section extraction and hashing as reusable utilities
|
||||
- Add golden set management (import, compare, drift detection)
|
||||
- Wire trust score decay into the `TrustVerdictService` scoring pipeline
|
||||
- Add REST endpoint for fingerprint queries and comparisons
|
||||
- Add tests for fingerprint store, section hashing, and golden set comparison
|
||||
|
||||
## Related Documentation
|
||||
- Source: See feature catalog
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
38
docs/features/checked/attestor/binary-fingerprinting.md
Normal file
38
docs/features/checked/attestor/binary-fingerprinting.md
Normal file
@@ -0,0 +1,38 @@
|
||||
# Binary Fingerprinting (TLSH + Instruction Hashing)
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Binary fingerprinting infrastructure with two methods: Simplified TLSH (locality-sensitive hashing) and Instruction Hash (normalized instruction sequence hashing). Both are proof-of-concept implementations noted as needing production-grade library integration. BinaryFingerprintEvidenceGenerator creates attestable proof segments from binary vulnerability findings.
|
||||
|
||||
## Implementation Details
|
||||
- **Evidence Generator**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Generators/BinaryFingerprintEvidenceGenerator.cs` (with `.Helpers`) -- attestation layer for binary fingerprint evidence. Creates `BinaryFingerprintEvidencePredicate` payloads from fingerprint analysis results.
|
||||
- **Fingerprint Evidence Predicate**: `__Libraries/StellaOps.Attestor.ProofChain/Predicates/BinaryFingerprintEvidencePredicate.cs` -- wraps fingerprint data (TLSH hash, instruction hash) as attestable predicate.
|
||||
- **Binary Identity**: `BinaryIdentityInfo.cs` -- captures binary metadata (path, SHA-256 hash, format, architecture).
|
||||
- **Micro-Witness Integration**: `MicroWitnessBinaryRef.cs` -- references specific binary in micro-witness evidence. `MicroWitnessFunctionEvidence.cs` -- function-level fingerprint evidence.
|
||||
- **Note**: The actual TLSH and instruction hashing algorithms live in `src/BinaryIndex/` (the binary analysis module). The Attestor module provides the attestation wrapper and proof-chain integration.
|
||||
- **Content Addressing**: Fingerprint evidence is stored with content-addressed IDs via `ContentAddressedIdGenerator`.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/BinaryMicroWitnessPredicateTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Generate a `BinaryFingerprintEvidencePredicate` from TLSH hash results and verify the predicate contains the locality-sensitive hash
|
||||
- [ ] Generate a predicate from instruction hash results and verify the normalized instruction sequence hash is captured
|
||||
- [ ] Verify `BinaryIdentityInfo` correctly captures binary format (ELF/PE/Mach-O) and architecture
|
||||
- [ ] Create micro-witness evidence linking a fingerprint to a specific function via `MicroWitnessFunctionEvidence` and verify the reference chain
|
||||
- [ ] Verify content-addressed IDs are generated deterministically for identical fingerprint evidence
|
||||
- [ ] Wrap fingerprint evidence in a DSSE-signed attestation and verify the signed envelope contains the correct predicate type
|
||||
- [ ] Generate fingerprint evidence for two versions of the same binary and verify the TLSH hashes differ but remain within expected similarity range
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,39 @@
|
||||
# Binary-Level SCA and Provenance
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Binary fingerprint evidence generation, binary identity and vulnerability matching info, and native binary hardening analysis for PE, ELF, and Mach-O formats.
|
||||
|
||||
## Implementation Details
|
||||
- **Binary Fingerprint Evidence**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Generators/BinaryFingerprintEvidenceGenerator.cs` (with `.Helpers`) -- generates attestable evidence from binary SCA results.
|
||||
- **Binary Identity**: `__Libraries/StellaOps.Attestor.ProofChain/Predicates/BinaryIdentityInfo.cs` -- captures binary identity: file path, SHA-256 digest, binary format (PE/ELF/Mach-O), architecture, and version info.
|
||||
- **Vulnerability Matching**: `BinaryVulnMatchInfo.cs` -- links binary identity to CVE matches with match type and confidence score.
|
||||
- **Binary Fingerprint Predicate**: `BinaryFingerprintEvidencePredicate.cs` -- attestable predicate wrapping binary SCA results.
|
||||
- **Micro-Witness Evidence**: `MicroWitnessBinaryRef.cs`, `MicroWitnessCveRef.cs`, `MicroWitnessFunctionEvidence.cs`, `MicroWitnessSbomRef.cs` -- fine-grained evidence linking binary analysis to SBOM components and CVEs.
|
||||
- **Binary Diff for Provenance**: `src/Attestor/__Libraries/StellaOps.Attestor.StandardPredicates/BinaryDiff/BinaryDiffSectionModels.cs` -- section-level diff models for PE (.text, .rdata) and ELF (.text, .rodata) sections.
|
||||
- **SLSA Provenance Integration**: `src/Attestor/__Libraries/StellaOps.Attestor.StandardPredicates/Parsers/SlsaProvenancePredicateParser.cs` -- parses SLSA provenance predicates that include build materials (binaries).
|
||||
- **Note**: Actual binary hardening analysis (DEP, ASLR, stack canaries, etc.) lives in `src/Scanner/` and `src/BinaryIndex/`.
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Generate binary SCA evidence for a PE binary and verify `BinaryIdentityInfo` captures format as PE with correct architecture
|
||||
- [ ] Generate evidence for an ELF binary and verify format detection
|
||||
- [ ] Create `BinaryVulnMatchInfo` linking a binary identity to a CVE and verify match details (CVE ID, confidence, match type)
|
||||
- [ ] Create micro-witness evidence with `MicroWitnessSbomRef` linking binary analysis results to SBOM component entries
|
||||
- [ ] Generate a binary diff between two binary versions and verify section-level changes are captured in `BinaryDiffSectionModels`
|
||||
- [ ] Verify binary fingerprint evidence integrates with SLSA provenance by including binary digests in build materials
|
||||
- [ ] Sign binary SCA evidence as a DSSE attestation and verify the signature covers the complete `BinaryFingerprintEvidencePredicate`
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,43 @@
|
||||
# Binary Reachability Proofs / Binary Diff Analysis
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Full binary diff analysis pipeline with schema validation, DSSE-verified predicates, normalization, and fingerprint evidence generation.
|
||||
|
||||
## Implementation Details
|
||||
- **BinaryDiff Pipeline**: `src/Attestor/__Libraries/StellaOps.Attestor.StandardPredicates/BinaryDiff/` -- complete pipeline:
|
||||
- `IBinaryDiffPredicateBuilder.cs` / `BinaryDiffPredicateBuilder.cs` (with `.Build`) -- constructs diff predicates
|
||||
- `IBinaryDiffPredicateSerializer.cs` / `BinaryDiffPredicateSerializer.cs` (with `.Normalize`) -- deterministic serialization
|
||||
- `IBinaryDiffDsseVerifier.cs` / `BinaryDiffDsseVerifier.cs` (with `.Helpers`) -- DSSE verification
|
||||
- `BinaryDiffDsseSigner.cs` -- DSSE signing
|
||||
- `BinaryDiffSchema.cs` (with `.SchemaJson`) -- JSON schema validation
|
||||
- `BinaryDiffSectionModels.cs` -- section-level models (ELF/PE)
|
||||
- `BinaryDiffFinding.cs` -- individual findings
|
||||
- `BinaryDiffMetadataBuilder.cs` -- metadata construction
|
||||
- **Fingerprint Evidence**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Generators/BinaryFingerprintEvidenceGenerator.cs` (with `.Helpers`) -- generates reachability-aware fingerprint evidence.
|
||||
- **Reachability Integration**: Binary diff evidence feeds into `ReachabilityWitnessPayload` (statements) and `BinaryMicroWitnessPredicate` (predicates) for reachability proof chains.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.StandardPredicates.Tests/BinaryDiff/` -- builder, serializer, signer, schema validation tests. `__Tests/StellaOps.Attestor.ProofChain.Tests/BinaryMicroWitnessPredicateTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Run the full binary diff pipeline: build predicate from findings, normalize/serialize, sign with DSSE, verify signature, validate against schema
|
||||
- [ ] Create diff findings for a patched vulnerability (binary changed in .text section) and verify the predicate captures the patch as a security-relevant change
|
||||
- [ ] Normalize the same diff predicate twice and verify byte-for-byte output equality
|
||||
- [ ] Validate a well-formed predicate against `BinaryDiffSchema` and verify it passes
|
||||
- [ ] Validate a predicate missing required fields and verify schema validation fails with specific error
|
||||
- [ ] Generate fingerprint evidence from a binary diff result and verify it links to the diff attestation
|
||||
- [ ] Feed binary diff evidence into a `BinaryMicroWitnessPredicate` and verify the reachability proof chain includes the diff evidence
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,39 @@
|
||||
# BinaryDiff/Binary SCA Attestation
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Binary diff predicate builder with DSSE signing/verification, section-level diff models, schema validation, and integration with evidence bundle exporter.
|
||||
|
||||
## Implementation Details
|
||||
- **Predicate Builder**: `src/Attestor/__Libraries/StellaOps.Attestor.StandardPredicates/BinaryDiff/BinaryDiffPredicateBuilder.cs` (with `.Build`) -- constructs binary diff predicates from `BinaryDiffFinding` entries.
|
||||
- **DSSE Signing/Verification**: `BinaryDiffDsseSigner.cs` signs predicates. `BinaryDiffDsseVerifier.cs` (with `.Helpers`) verifies signed envelopes.
|
||||
- **Serialization**: `BinaryDiffPredicateSerializer.cs` (with `.Normalize`) -- deterministic normalization and serialization.
|
||||
- **Schema Validation**: `BinaryDiffSchema.cs` (with `.SchemaJson`) -- embedded JSON schema. `BinaryDiffSchemaValidationResult.cs` -- validation output.
|
||||
- **Section Models**: `BinaryDiffSectionModels.cs` -- ELF/PE section-level diff models. `BinaryDiffModels.cs` -- core models.
|
||||
- **Evidence Bundle Integration**: Evidence packs (`src/Attestor/__Libraries/StellaOps.Attestor.EvidencePack/`) include binary diff attestations in export bundles. `ReleaseEvidencePackBuilder.cs` aggregates binary SCA evidence.
|
||||
- **DI**: `ServiceCollectionExtensions.cs` -- registers builder, serializer, signer, verifier.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.StandardPredicates.Tests/BinaryDiff/` -- `BinaryDiffPredicateBuilderTests.cs`, `BinaryDiffPredicateSerializerTests.cs`, `BinaryDiffDsseSignerTests.cs`, `BinaryDiffSchemaValidationTests.cs`, `BinaryDiffTestData.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Build a predicate from `BinaryDiffFinding` entries representing patched and unpatched sections, sign it, and verify the DSSE envelope
|
||||
- [ ] Validate the predicate against `BinaryDiffSchema` and verify it passes
|
||||
- [ ] Include the signed binary diff attestation in a `ReleaseEvidencePackBuilder` export and verify it appears in the evidence pack manifest
|
||||
- [ ] Serialize the predicate, modify a finding, re-serialize, and verify the normalized output differs
|
||||
- [ ] Create findings with ELF section changes (.text, .plt, .got) and verify `BinaryDiffSectionModels` captures each section
|
||||
- [ ] Verify DI registration via `ServiceCollectionExtensions` resolves all binary diff services correctly
|
||||
- [ ] Tamper with the DSSE envelope and verify `BinaryDiffDsseVerifier` rejects it
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
44
docs/features/checked/attestor/build-attestation-mapping.md
Normal file
44
docs/features/checked/attestor/build-attestation-mapping.md
Normal file
@@ -0,0 +1,44 @@
|
||||
# Build Attestation Mapping (SPDX 3.0.1 Build Profile)
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Build attestation mapping to/from SPDX 3.0.1 is implemented with bidirectional mappers, build material, metadata, and invocation models.
|
||||
|
||||
## Implementation Details
|
||||
- **BuildAttestationMapper**: `src/Attestor/__Libraries/StellaOps.Attestor.Spdx3/BuildAttestationMapper.cs` -- orchestrates bidirectional mapping. `IBuildAttestationMapper.cs` -- interface.
|
||||
- `BuildAttestationMapper.MapToSpdx3.cs` -- maps internal build attestation to SPDX 3.0.1 build profile format
|
||||
- `BuildAttestationMapper.MapFromSpdx3.cs` -- maps SPDX 3.0.1 build profile to internal format
|
||||
- **Build Attestation Payload**: `BuildAttestationPayload.cs` -- internal build attestation model.
|
||||
- **Build Material**: `BuildMaterial.cs` -- input materials (source code, dependencies, config files) with digests.
|
||||
- **Build Metadata**: `BuildMetadata.cs` -- build timestamp, build ID, reproducibility info.
|
||||
- **Build Invocation**: `BuildInvocation.cs` -- build command, parameters, environment.
|
||||
- **Builder Info**: `BuilderInfo.cs` -- builder identity (CI system, version).
|
||||
- **Config Source**: `ConfigSource.cs` -- build configuration source references.
|
||||
- **Build Relationships**: `BuildRelationshipBuilder.cs` (with `.Linking` partial) -- builds SPDX 3.0.1 relationships between build elements.
|
||||
- **DSSE Signing**: `DsseSpdx3Signer.cs` (with `.SignBuildProfile` partial) -- signs build profiles as DSSE envelopes.
|
||||
- **Combined Document**: `CombinedDocumentBuilder.cs` (with `.Build`, `.Attestation`, `.Profiles` partials) -- builds combined SPDX documents with build attestation profiles.
|
||||
- **Tests**: `__Libraries/__Tests/StellaOps.Attestor.Spdx3.Tests/BuildAttestationMapperTests.cs`, `BuildProfileValidatorTests.cs`, `CombinedDocumentBuilderTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Create a `BuildAttestationPayload` with materials, metadata, and invocation, map to SPDX 3.0.1 via `MapToSpdx3`, and verify the output contains correct build profile elements
|
||||
- [ ] Map an SPDX 3.0.1 document with build profile back to internal format via `MapFromSpdx3` and verify round-trip fidelity
|
||||
- [ ] Create build materials with SHA-256 digests and verify they appear as SPDX 3.0.1 build inputs with correct hash references
|
||||
- [ ] Create `BuildInvocation` with build command and parameters and verify they map to SPDX 3.0.1 build invocation fields
|
||||
- [ ] Use `BuildRelationshipBuilder` to link build elements and verify SPDX relationships are correctly typed
|
||||
- [ ] Sign a build profile via `DsseSpdx3Signer.SignBuildProfile` and verify the DSSE envelope is valid
|
||||
- [ ] Build a combined SPDX document with SBOM + build attestation profile via `CombinedDocumentBuilder` and verify both profiles are present
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,40 @@
|
||||
# Call-Stack Reachability Analysis
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Multi-language call-stack reachability analysis with symbol matching and canonicalization supporting .NET, Java, native (ELF), and scripting languages, plus benchmarking infrastructure with ground-truth validation.
|
||||
|
||||
## Implementation Details
|
||||
- **Reachability Witness Payload**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Statements/ReachabilityWitnessPayload.cs` (with `.Path` partial) -- captures call-stack paths from entry points to vulnerable functions.
|
||||
- **Witness Call Path Node**: `Statements/WitnessCallPathNode.cs` -- individual node in a call-stack path with function name, module, and language.
|
||||
- **Witness Path Node**: `Statements/WitnessPathNode.cs` -- simplified path node for witness evidence.
|
||||
- **Witness Evidence Metadata**: `Statements/WitnessEvidenceMetadata.cs` -- metadata about the analysis tool and language used.
|
||||
- **Witness Gate Info**: `Statements/WitnessGateInfo.cs` -- gate configuration for policy evaluation of reachability evidence.
|
||||
- **Reachability Witness Statement**: `Statements/ReachabilityWitnessStatement.cs` -- wraps payload as in-toto statement.
|
||||
- **Path Witness Predicate Types**: `src/Attestor/StellaOps.Attestor/StellaOps.Attestor.Core/PathWitnessPredicateTypes.cs` -- predicate type URIs for different path witness types.
|
||||
- **Micro-Witness Function Evidence**: `Predicates/MicroWitnessFunctionEvidence.cs` -- function-level evidence from call-stack analysis.
|
||||
- **Note**: Actual call-graph analysis and symbol matching lives in `src/ReachGraph/` and `src/Scanner/`; Attestor provides the attestation wrapper.
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Create a `ReachabilityWitnessPayload` with a call-stack path containing 5 nodes (entry -> intermediate -> intermediate -> intermediate -> vulnerable function) and verify all nodes are captured
|
||||
- [ ] Create `WitnessCallPathNode` entries with .NET namespaced symbols and verify symbol canonicalization preserves full type qualification
|
||||
- [ ] Create path nodes with Java package-style symbols and verify correct representation
|
||||
- [ ] Create `WitnessEvidenceMetadata` specifying the analysis tool and language, wrap in statement, and verify metadata persists
|
||||
- [ ] Verify `WitnessGateInfo` correctly captures policy gate thresholds for reachability evidence
|
||||
- [ ] Create `MicroWitnessFunctionEvidence` linking a specific function to call-stack evidence and verify the reference chain
|
||||
- [ ] Wrap a reachability witness in an in-toto statement and verify the predicate type matches `PathWitnessPredicateTypes`
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,39 @@
|
||||
# Canonical Graph Signature (CGS) / Deterministic Verdicts
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Deterministic Merkle tree builder, content-addressed IDs, and canonical JSON serialization produce same-inputs-same-output verdicts with verifiable digests.
|
||||
|
||||
## Implementation Details
|
||||
- **Deterministic Merkle Tree**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Merkle/DeterministicMerkleTreeBuilder.cs` (with `.Helpers`, `.Proof` partials) -- implements `IMerkleTreeBuilder`. Builds Merkle trees with deterministic leaf ordering for canonical graph signatures.
|
||||
- **Merkle Proof**: `MerkleProof.cs`, `MerkleProofStep.cs` -- inclusion proof model. `MerkleTreeWithProofs.cs` -- tree with generated proofs.
|
||||
- **Content-Addressed IDs**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Identifiers/ContentAddressedIdGenerator.cs` (with `.Graph` partial) -- generates deterministic SHA-256 IDs from content. Types: `ArtifactId.cs`, `EvidenceId.cs`, `ProofBundleId.cs`, `VexVerdictId.cs`, `ReasoningId.cs`, `GraphRevisionId.cs`.
|
||||
- **Canonical JSON**: `__Libraries/StellaOps.Attestor.ProofChain/Json/Rfc8785JsonCanonicalizer.cs` (with `.DecimalPoint`, `.NumberSerialization`, `.StringNormalization`, `.WriteMethods`) -- RFC 8785 JCS ensuring deterministic serialization.
|
||||
- **Verdict Receipt**: `Statements/VerdictReceiptPayload.cs`, `VerdictReceiptStatement.cs` -- verdict receipts with deterministic content.
|
||||
- **Verdict Decision**: `Statements/VerdictDecision.cs`, `VerdictInputs.cs`, `VerdictOutputs.cs` -- verdict computation model.
|
||||
- **Proof Hashing**: `__Libraries/StellaOps.Attestor.ProofChain/ProofHashing.cs` -- SHA-256 hashing utilities.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/MerkleTreeBuilderTests.cs`, `ContentAddressedIdTests.cs`, `ContentAddressedIdGeneratorTests.cs`, `JsonCanonicalizerTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Build a Merkle tree from 10 evidence items via `DeterministicMerkleTreeBuilder` and verify the root hash is deterministic (build twice, compare roots)
|
||||
- [ ] Generate an inclusion proof for a specific leaf and verify `MerkleProof` validates against the root
|
||||
- [ ] Generate `ContentAddressedId` for identical content twice and verify IDs match
|
||||
- [ ] Generate IDs for different content and verify they differ
|
||||
- [ ] Canonicalize a JSON object with out-of-order keys via `Rfc8785JsonCanonicalizer` and verify key ordering matches RFC 8785
|
||||
- [ ] Create a `VerdictReceiptPayload` from identical inputs twice and verify the serialized output is byte-for-byte identical
|
||||
- [ ] Build a `GraphRevisionId` from a proof graph state and verify it changes when graph content changes
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,44 @@
|
||||
# Canonicalization and Content Addressing
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
RFC 8785 JSON canonicalization, deterministic Merkle tree building, and content-addressed ID generation for all proof chain artifacts ensuring stable hashing.
|
||||
|
||||
## Implementation Details
|
||||
- **RFC 8785 Canonicalizer**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Json/Rfc8785JsonCanonicalizer.cs` -- implements `IJsonCanonicalizer`. Partials:
|
||||
- `.DecimalPoint` -- decimal point handling per RFC 8785
|
||||
- `.NumberSerialization` -- IEEE 754 number serialization
|
||||
- `.StringNormalization` -- Unicode escape and string normalization
|
||||
- `.WriteMethods` -- low-level write operations
|
||||
- **SBOM Canonicalizer**: `src/Attestor/__Libraries/StellaOps.Attestor.StandardPredicates/Canonicalization/SbomCanonicalizer.cs` (with `.Elements`) -- implements `ISbomCanonicalizer` for deterministic SBOM element ordering.
|
||||
- **Content-Addressed ID Generator**: `__Libraries/StellaOps.Attestor.ProofChain/Identifiers/ContentAddressedIdGenerator.cs` (with `.Graph`) -- `IContentAddressedIdGenerator` implementation. Generates SHA-256 content-addressed IDs.
|
||||
- **ID Types**: `ContentAddressedId.cs` (base), `GenericContentAddressedId.cs`, `ArtifactId.cs`, `EvidenceId.cs`, `ProofBundleId.cs`, `VexVerdictId.cs`, `ReasoningId.cs`, `SbomEntryId.cs`, `TrustAnchorId.cs`, `GraphRevisionId.cs`.
|
||||
- **SHA-256 Parser**: `Sha256IdParser.cs` -- parses `sha256:<hex>` formatted IDs.
|
||||
- **Proof Hashing**: `ProofHashing.cs` -- utility methods for proof chain hashing.
|
||||
- **Merkle Tree**: `Merkle/DeterministicMerkleTreeBuilder.cs` (with `.Helpers`, `.Proof`) -- deterministic tree construction.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/JsonCanonicalizerTests.cs`, `ContentAddressedIdTests.cs`, `ContentAddressedIdGeneratorTests.cs`, `MerkleTreeBuilderTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Canonicalize JSON with out-of-order keys and verify output has keys in lexicographic order per RFC 8785
|
||||
- [ ] Canonicalize JSON with Unicode escapes (e.g., `\u00e9`) and verify normalization to UTF-8
|
||||
- [ ] Canonicalize JSON with floating-point numbers and verify IEEE 754 serialization
|
||||
- [ ] Generate a content-addressed ID for a proof blob and verify it matches `sha256:<64-hex-chars>` format
|
||||
- [ ] Verify `Sha256IdParser` correctly parses valid IDs and rejects malformed ones
|
||||
- [ ] Canonicalize an SBOM document via `SbomCanonicalizer` and verify element ordering is deterministic
|
||||
- [ ] Build a Merkle tree from canonicalized artifacts and verify the root hash is stable across invocations
|
||||
- [ ] Generate `SbomEntryId` for identical SBOM component content and verify ID equality
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,47 @@
|
||||
# CAS for SBOM/VEX/Attestation Artifacts
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Content-addressed identifiers are implemented for proof chain artifacts. EvidenceLocker provides bundle building. Full OCI/MinIO CAS for SBOM/VEX blobs is not fully visible.
|
||||
|
||||
## What's Implemented
|
||||
- **Content-Addressed ID Generator**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Identifiers/` -- ArtifactId, EvidenceId, ProofBundleId, VexVerdictId, GenericContentAddressedId, ContentAddressedIdGenerator (with `.Graph`), Sha256IdParser.
|
||||
- **SBOM OCI Publisher**: `__Libraries/StellaOps.Attestor.Oci/Services/SbomOciPublisher.cs` -- publishes SBOMs to OCI registries.
|
||||
- **ORAS Attestation Attacher**: `Oci/Services/OrasAttestationAttacher.cs` -- attaches attestations to OCI images.
|
||||
- **Content-Addressed Tile Store**: `StellaOps.Attestor.TileProxy/Services/ContentAddressedTileStore.cs` -- content-addressed storage for tiles.
|
||||
- **Evidence Pack Builder**: `__Libraries/StellaOps.Attestor.EvidencePack/ReleaseEvidencePackBuilder.cs` -- builds evidence packs.
|
||||
- **Sigstore Bundle**: `__Libraries/StellaOps.Attestor.Bundle/Models/SigstoreBundle.cs` -- Sigstore bundle model.
|
||||
|
||||
## What's Missing
|
||||
- **Unified CAS for all artifact types**: No single content-addressed storage service that handles SBOM, VEX, and attestation blobs uniformly. Current CAS is per-domain (tiles, OCI, proof chain IDs).
|
||||
- **MinIO/S3 backend**: No MinIO or S3-compatible object storage backend for CAS. Current storage is either OCI registry or filesystem.
|
||||
- **Deduplication service**: No cross-artifact deduplication by content hash (e.g., same SBOM ingested twice should resolve to one stored blob).
|
||||
- **CAS garbage collection**: No garbage collection or retention policy for unreferenced CAS blobs.
|
||||
- **CAS REST API**: No unified REST API for CAS operations (store, retrieve, exists, list by prefix).
|
||||
|
||||
## Implementation Plan
|
||||
- Create a unified `IContentAddressedStore` interface with store/retrieve/exists operations
|
||||
- Implement MinIO/S3 backend and filesystem backend behind the interface
|
||||
- Add deduplication logic (check-before-store by content hash)
|
||||
- Implement garbage collection with configurable retention policies
|
||||
- Add REST endpoints for CAS operations
|
||||
- Migrate existing per-domain storage to use the unified CAS
|
||||
- Add tests for store/retrieve, deduplication, and GC
|
||||
|
||||
## Related Documentation
|
||||
- Source: See feature catalog
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,39 @@
|
||||
# Checkpoint Signature Verification
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Checkpoint divergence detection and alert publishing for Rekor transparency log verification.
|
||||
|
||||
## Implementation Details
|
||||
- **Checkpoint Signature Verifier**: `src/Attestor/StellaOps.Attestor/StellaOps.Attestor.Core/Verification/CheckpointSignatureVerifier.cs` -- verifies cryptographic signatures on Rekor checkpoints against known public keys.
|
||||
- **Checkpoint Divergence Detector**: `StellaOps.Attestor.Core/Rekor/CheckpointDivergenceDetector.cs` -- implements `ICheckpointDivergenceDetector`. Detects split-world attacks by comparing checkpoints from multiple Rekor instances.
|
||||
- **Alert Publisher**: `Rekor/CheckpointDivergenceAlertPublisher.cs` -- publishes alerts when checkpoint divergence is detected.
|
||||
- **Rekor Checkpoint Store**: `IRekorCheckpointStore.cs` -- interface for storing and retrieving checkpoints. `StellaOps.Attestor.Storage/Rekor/PostgresRekorCheckpointStore.cs` -- PostgreSQL implementation.
|
||||
- **Rekor Backend**: `Rekor/RekorBackend.cs` -- backend configuration. `IRekorBackendResolver.cs` -- resolves backend instances. `Infrastructure/Rekor/RekorBackendResolver.cs`, `ServiceMapAwareRekorBackendResolver.cs` -- implementations.
|
||||
- **Rekor Sync**: `Rekor/RekorSyncBackgroundService.cs` -- background service for checkpoint synchronization.
|
||||
- **Time Skew Validation**: `Verification/TimeSkewValidator.cs`, `InstrumentedTimeSkewValidator.cs` -- validates time consistency between checkpoints.
|
||||
- **Tests**: `StellaOps.Attestor.Core.Tests/Verification/CheckpointSignatureVerifierTests.cs`, `StellaOps.Attestor.Core.Tests/Rekor/CheckpointDivergenceDetectorTests.cs`, `CheckpointDivergenceByzantineTests.cs`, `__Tests/StellaOps.Attestor.Conformance.Tests/CheckpointParityTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify a checkpoint signature against a known Rekor public key via `CheckpointSignatureVerifier` and confirm success
|
||||
- [ ] Verify a checkpoint with an invalid signature and confirm the verifier rejects it
|
||||
- [ ] Feed two consistent checkpoints (same tree) to `CheckpointDivergenceDetector` and verify no divergence is detected
|
||||
- [ ] Feed two divergent checkpoints (different roots for same tree size) and verify divergence is detected and alert is published via `CheckpointDivergenceAlertPublisher`
|
||||
- [ ] Store checkpoints via `PostgresRekorCheckpointStore` and retrieve them, verifying data integrity
|
||||
- [ ] Verify `TimeSkewValidator` detects unacceptable time skew between checkpoint timestamps
|
||||
- [ ] Run `RekorSyncBackgroundService` and verify it periodically fetches and stores new checkpoints
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,42 @@
|
||||
# Confidence Scoring for Backport Detection
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Quantifiable confidence scoring (0.0-0.98) for backport detection. Uses highest individual tier confidence as base, adds multi-source bonus (0.05 for 2 sources, 0.08 for 3, 0.10 for 4+), capped at 0.98. Per-tier confidence values: DistroAdvisory=0.98, VersionComparison=0.95, BuildCatalog=0.90, PatchHeader=0.85, ChangelogMention=0.80, BinaryFingerprint=0.70.
|
||||
|
||||
## Implementation Details
|
||||
- **BackportProofGenerator.Confidence**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Generators/BackportProofGenerator.Confidence.cs` -- computes confidence scores using tier-based hierarchy with multi-source bonuses.
|
||||
- **Tier Implementations**: Each tier has specific confidence values:
|
||||
- `BackportProofGenerator.Tier1.cs` -- DistroAdvisory (0.98) and VersionComparison (0.95)
|
||||
- `BackportProofGenerator.Tier2.cs` -- BuildCatalog (0.90) and PatchHeader (0.85)
|
||||
- `BackportProofGenerator.Tier3.cs` -- ChangelogMention (0.80)
|
||||
- `BackportProofGenerator.Tier3Signature.cs` -- Binary signature variant
|
||||
- `BackportProofGenerator.Tier4.cs` -- BinaryFingerprint (0.70) and inference
|
||||
- **Evidence Combining**: `BackportProofGenerator.CombineEvidence.cs` -- aggregates evidence from multiple tiers, applying multi-source bonus (2 sources: +0.05, 3: +0.08, 4+: +0.10), capped at 0.98.
|
||||
- **Evidence Summary**: `EvidenceSummary.cs` -- aggregated output with per-tier confidence breakdown.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/BackportProofGeneratorTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Generate a Tier 1 proof with DistroAdvisory evidence and verify confidence score is 0.98
|
||||
- [ ] Generate a Tier 2 proof with BuildCatalog evidence and verify confidence score is 0.90
|
||||
- [ ] Generate a Tier 3 proof with ChangelogMention and verify confidence score is 0.80
|
||||
- [ ] Generate a Tier 4 proof with BinaryFingerprint and verify confidence score is 0.70
|
||||
- [ ] Combine evidence from 2 sources (Tier 1 + Tier 3) and verify multi-source bonus of 0.05 is applied
|
||||
- [ ] Combine evidence from 3 sources and verify bonus of 0.08 is applied
|
||||
- [ ] Combine evidence from 4+ sources and verify bonus of 0.10 is applied, with final score capped at 0.98
|
||||
- [ ] Verify `EvidenceSummary` contains per-tier breakdown showing individual and combined confidence scores
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,46 @@
|
||||
# Content-Addressed Identifiers (ArtifactId, EvidenceId, ProofBundleId)
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Full content-addressed ID system with types for ArtifactId, EvidenceId, ReasoningId, VexVerdictId, ProofBundleId, plus a content-addressed ID generator and SHA256 parser.
|
||||
|
||||
## Implementation Details
|
||||
- **ID Generator**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Identifiers/ContentAddressedIdGenerator.cs` (with `.Graph` partial) -- implements `IContentAddressedIdGenerator`. Generates SHA-256 content-addressed IDs from canonical JSON content.
|
||||
- **Base Types**: `ContentAddressedId.cs` -- base record type. `GenericContentAddressedId.cs` -- generic typed variant.
|
||||
- **Typed ID Records**:
|
||||
- `ArtifactId.cs` -- identifies attestation artifacts
|
||||
- `EvidenceId.cs` -- identifies evidence items
|
||||
- `ProofBundleId.cs` -- identifies proof bundles
|
||||
- `VexVerdictId.cs` -- identifies VEX verdicts
|
||||
- `ReasoningId.cs` -- identifies reasoning chains
|
||||
- `SbomEntryId.cs` -- identifies SBOM entries
|
||||
- `TrustAnchorId.cs` -- identifies trust anchors
|
||||
- `GraphRevisionId.cs` -- identifies graph revision state
|
||||
- **SHA-256 Parser**: `Sha256IdParser.cs` -- parses and validates `sha256:<64-hex-chars>` format.
|
||||
- **Proof Hashing**: `__Libraries/StellaOps.Attestor.ProofChain/ProofHashing.cs` -- SHA-256 hashing utilities.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/ContentAddressedIdTests.cs`, `ContentAddressedIdGeneratorTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Generate an `ArtifactId` from content via `ContentAddressedIdGenerator` and verify the output matches `sha256:<64-hex-chars>` format
|
||||
- [ ] Generate IDs for identical content twice and verify they are equal
|
||||
- [ ] Generate IDs for different content and verify they differ
|
||||
- [ ] Parse a valid `sha256:abc123...` string via `Sha256IdParser` and verify successful parsing
|
||||
- [ ] Attempt to parse an invalid ID (wrong prefix, wrong length) and verify parser rejects it
|
||||
- [ ] Generate `EvidenceId`, `ProofBundleId`, `VexVerdictId`, `ReasoningId` for same content and verify they produce the same hash but are distinct types
|
||||
- [ ] Generate a `GraphRevisionId` from a proof graph state, modify the graph, regenerate, and verify the ID changes
|
||||
- [ ] Verify `SbomEntryId` produces deterministic IDs for identical SBOM component content
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,37 @@
|
||||
# Content-Addressed IDs for SBOM Components (bom-ref)
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Content-addressed ID generator with SBOM entry IDs and CycloneDX subject extraction for deterministic component referencing.
|
||||
|
||||
## Implementation Details
|
||||
- **SbomEntryId**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Identifiers/SbomEntryId.cs` -- content-addressed ID type for SBOM entries, ensuring deterministic bom-ref values.
|
||||
- **Content-Addressed ID Generator**: `ContentAddressedIdGenerator.cs` -- generates SHA-256 based IDs from canonical SBOM component content.
|
||||
- **CycloneDX Subject Extractor**: `__Libraries/StellaOps.Attestor.ProofChain/Sbom/CycloneDxSubjectExtractor.cs` -- implements `ISbomSubjectExtractor`. Extracts subjects from CycloneDX SBOM for attestation.
|
||||
- **Component Ref Extractor**: `__Libraries/StellaOps.Attestor.ProofChain/Linking/ComponentRefExtractor.cs` (with `.Resolution`, `.Spdx` partials) -- extracts component references from SBOMs for cross-linking. `SbomExtractionResult.cs` -- extraction result model.
|
||||
- **SBOM Canonicalization**: `src/Attestor/__Libraries/StellaOps.Attestor.StandardPredicates/Canonicalization/SbomCanonicalizer.cs` (with `.Elements`) -- deterministic element ordering for stable ID generation.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/ContentAddressedIdTests.cs`, `ContentAddressedIdGeneratorTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Generate `SbomEntryId` for a CycloneDX component with name, version, and PURL and verify deterministic ID
|
||||
- [ ] Generate IDs for two components with same content but different field ordering and verify IDs match (canonicalization)
|
||||
- [ ] Extract subjects from a CycloneDX SBOM via `CycloneDxSubjectExtractor` and verify each component has a content-addressed subject ID
|
||||
- [ ] Extract component references via `ComponentRefExtractor` and verify bom-ref values are content-addressed
|
||||
- [ ] Extract SPDX component references via `ComponentRefExtractor.Spdx` and verify deterministic SPDX IDs
|
||||
- [ ] Canonicalize an SBOM via `SbomCanonicalizer`, generate content-addressed IDs, and verify stability across invocations
|
||||
- [ ] Modify a single component field and verify the `SbomEntryId` changes
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,41 @@
|
||||
# Content-Addressed Node and Edge Identifiers
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Content-addressed NodeId and EdgeId records with graph-aware ID generation, addressing the advisory's EdgeId gap.
|
||||
|
||||
## Implementation Details
|
||||
- **Graph-Aware ID Generation**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Identifiers/ContentAddressedIdGenerator.Graph.cs` -- extends `ContentAddressedIdGenerator` with graph-specific ID generation for nodes and edges.
|
||||
- **Proof Graph Node**: `__Libraries/StellaOps.Attestor.ProofChain/Graph/ProofGraphNode.cs` -- node record with content-addressed ID, type (`ProofGraphNodeType`), and payload.
|
||||
- **Proof Graph Edge**: `Graph/ProofGraphEdge.cs` -- edge record with content-addressed ID, source/target node references, and type (`ProofGraphEdgeType`).
|
||||
- **Node Types**: `ProofGraphNodeType.cs` -- enum: Evidence, Verdict, Policy, Artifact, etc.
|
||||
- **Edge Types**: `ProofGraphEdgeType.cs` -- enum: DependsOn, Supersedes, Aggregates, Produces, etc.
|
||||
- **Graph Path**: `ProofGraphPath.cs` -- path through the graph for traversal.
|
||||
- **Subgraph**: `ProofGraphSubgraph.cs` -- extracted subgraph with nodes and edges.
|
||||
- **Graph Revision**: `Identifiers/GraphRevisionId.cs` -- content-addressed ID for the entire graph state.
|
||||
- **Graph Service**: `Graph/InMemoryProofGraphService.cs` (with `.Mutation`, `.Queries`, `.Subgraph`) -- implements `IProofGraphService` with content-addressed node/edge management.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/ContentAddressedIdGeneratorTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Create a `ProofGraphNode` and verify its content-addressed ID is generated from node content via `ContentAddressedIdGenerator.Graph`
|
||||
- [ ] Create a `ProofGraphEdge` between two nodes and verify its edge ID is computed from source, target, and edge type
|
||||
- [ ] Add identical node content twice via `InMemoryProofGraphService` and verify deduplication (same node ID)
|
||||
- [ ] Add an edge between two nodes and verify the edge ID is deterministic
|
||||
- [ ] Modify node payload and verify the node ID changes
|
||||
- [ ] Compute `GraphRevisionId` for a graph state, add a node, recompute, and verify the revision ID changes
|
||||
- [ ] Extract a subgraph via `InMemoryProofGraphService.Subgraph` and verify all node/edge IDs in the subgraph are content-addressed
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,41 @@
|
||||
# Cross-Attestation Chain Linking (SBOM->VEX->Policy)
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Cross-attestation linking via in-toto layout references with link types (DependsOn/Supersedes/Aggregates), DAG validation with cycle detection, chain query API (GET /attestations?chain=true, upstream/downstream traversal with depth limit), and chain visualization endpoint supporting Mermaid/DOT/JSON formats.
|
||||
|
||||
## Implementation Details
|
||||
- **Attestation Chain Builder**: `src/Attestor/StellaOps.Attestor/StellaOps.Attestor.Core/Chain/AttestationChainBuilder.cs` -- builds attestation chains from link references.
|
||||
- **Attestation Chain Validator**: `Chain/AttestationChainValidator.cs` -- validates chain integrity including DAG validation and cycle detection.
|
||||
- **Attestation Link**: `Chain/AttestationLink.cs` -- represents a link between two attestations with link type.
|
||||
- **Attestation Link Resolver**: `Chain/AttestationLinkResolver.cs` -- implements `IAttestationLinkResolver`. Resolves upstream/downstream links with depth limits.
|
||||
- **In-Memory Link Store**: `Chain/InMemoryAttestationLinkStore.cs` -- in-memory storage for attestation links.
|
||||
- **Chain Model**: `Chain/AttestationChain.cs` -- full chain model for traversal.
|
||||
- **In-Toto Materials**: `Chain/InTotoStatementMaterials.cs` -- material references in in-toto statements for cross-linking.
|
||||
- **Chain Query Service**: `StellaOps.Attestor.WebService/Services/ChainQueryService.cs`, `IChainQueryService.cs` -- API service for chain queries.
|
||||
- **Chain API**: `WebService/Controllers/ChainController.cs` -- REST endpoints for chain traversal and visualization. `WebService/Models/ChainApiModels.cs` -- API models.
|
||||
- **Tests**: `StellaOps.Attestor.Core.Tests/Chain/AttestationChainBuilderTests.cs`, `AttestationChainValidatorTests.cs`, `AttestationLinkResolverTests.cs`, `ChainResolverDirectionalTests.cs`, `InMemoryAttestationLinkStoreTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Build an attestation chain SBOM -> VEX -> Policy via `AttestationChainBuilder` with DependsOn links and verify the chain connects all three
|
||||
- [ ] Validate the chain via `AttestationChainValidator` and verify DAG validation passes (no cycles)
|
||||
- [ ] Create a circular chain (A -> B -> C -> A) and verify `AttestationChainValidator` detects the cycle
|
||||
- [ ] Resolve upstream links from a Policy attestation via `AttestationLinkResolver` with depth limit 2 and verify VEX and SBOM are returned
|
||||
- [ ] Resolve downstream links from an SBOM attestation and verify VEX and Policy are returned
|
||||
- [ ] Query chain via `ChainController` GET endpoint with `chain=true` and verify the response contains the full chain
|
||||
- [ ] Request chain visualization in Mermaid format and verify valid Mermaid diagram output
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
54
docs/features/checked/attestor/crypto-sovereign-design.md
Normal file
54
docs/features/checked/attestor/crypto-sovereign-design.md
Normal file
@@ -0,0 +1,54 @@
|
||||
# Crypto-Sovereign Design (eIDAS/FIPS/GOST/SM/PQC)
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
SigningKeyProfile supports crypto-sovereign configurations. SM2 tests exist for Chinese crypto support. The signing key registry supports multiple profiles. Full eIDAS/GOST/PQC implementations appear to be partially supported through the profile system but not all crypto backends are fully implemented.
|
||||
|
||||
## What's Implemented
|
||||
- **Signing Key Profile**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Signing/SigningKeyProfile.cs` -- key profile supporting multiple algorithm families and sovereign configurations.
|
||||
- **ProofChain Signer**: `Signing/ProofChainSigner.cs` (with `.Verification`) -- signing with algorithm-agnostic interface.
|
||||
- **IProofChainKeyStore**: `Signing/IProofChainKeyStore.cs` -- key store interface supporting multiple key types.
|
||||
- **DSSE Signing**: `Signing/DsseEnvelope.cs`, `DsseSignature.cs`, `DssePreAuthenticationEncoding.cs` -- DSSE envelope signing.
|
||||
- **Attestor Signing Key Registry**: `StellaOps.Attestor.Infrastructure/Signing/AttestorSigningKeyRegistry.cs` -- registry for multiple signing key profiles.
|
||||
- **DSSE SPDX3 Signer**: `__Libraries/StellaOps.Attestor.Spdx3/DsseSpdx3Signer.cs` -- SPDX3-specific signing.
|
||||
- **DSSE Signing Provider**: `Spdx3/IDsseSigningProvider.cs` -- provider interface for crypto operations.
|
||||
|
||||
## Additional Implementation Found (Cryptography Plugins)
|
||||
The following crypto plugins exist under `src/Cryptography/` with a plugin architecture (`CryptoPluginBase.cs`, `MultiProfileSigner.cs`, `SignatureProfile.cs`):
|
||||
- **GOST**: `src/Cryptography/StellaOps.Cryptography.Plugin.Gost/GostPlugin.cs` -- GOST R 34.10-2012 support
|
||||
- **eIDAS**: `src/Cryptography/StellaOps.Cryptography.Plugin.Eidas/EidasPlugin.cs` -- includes ETSI conformance test vectors
|
||||
- **SM2/SM3**: `src/Cryptography/StellaOps.Cryptography.Plugin.Sm/` -- SM2/SM3 support
|
||||
- **FIPS**: `src/Cryptography/StellaOps.Cryptography.Plugin.Fips/` -- FIPS 140 compliance plugin
|
||||
- **HSM**: `src/Cryptography/StellaOps.Cryptography.Plugin.Hsm/` -- HSM integration plugin
|
||||
- **Tests**: `src/Cryptography/__Tests/` and `src/__Libraries/__Tests/StellaOps.Cryptography.Tests/`
|
||||
|
||||
## What's Missing
|
||||
- **Post-Quantum Cryptography (PQC)**: No CRYSTALS-Dilithium, SPHINCS+, or other PQC algorithm support. The profile system can model PQC keys but no backend implements them. This is the only major crypto profile gap.
|
||||
- **eIDAS qualified signature validation**: Plugin exists but validation that timestamps meet eIDAS Article 42 qualified timestamp requirements may not be complete.
|
||||
- **Crypto provider integration with Attestor SigningKeyProfile**: The Cryptography plugin system and the Attestor `SigningKeyProfile` are not fully bridged -- Attestor signing uses its own key profiles rather than the Cryptography plugin registry.
|
||||
- **Algorithm negotiation**: No cross-sovereign algorithm negotiation for interoperability between different crypto profiles.
|
||||
|
||||
## Implementation Plan
|
||||
- Implement PQC plugin (CRYSTALS-Dilithium, SPHINCS+) following the existing CryptoPluginBase pattern
|
||||
- Bridge Cryptography plugin registry with Attestor SigningKeyProfile for unified key management
|
||||
- Add eIDAS Article 42 qualified timestamp validation
|
||||
- Add algorithm negotiation for cross-sovereign interoperability
|
||||
- Verify ETSI conformance test vectors pass end-to-end for eIDAS plugin
|
||||
|
||||
## Related Documentation
|
||||
- Source: See feature catalog
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,39 @@
|
||||
# Cryptographic Proof Generation (SHA-256 hashing)
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Cryptographic proof generation using canonical JSON serialization and SHA-256 hashing. ProofBlobs are tamper-evident with computed hashes that can be verified. Note: The codebase uses SHA-256 through CanonJson utilities. The advisory mentioned BLAKE3-256 as well; the DB schema references BLAKE3-256 in comments but actual code uses SHA-256 via CanonJson.
|
||||
|
||||
## Implementation Details
|
||||
- **Proof Hashing**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/ProofHashing.cs` -- SHA-256 hashing utilities for proof chain artifacts.
|
||||
- **Proof Blob**: `__Libraries/StellaOps.Attestor.ProofChain/Models/ProofBlob.cs` -- tamper-evident proof container with computed SHA-256 hash.
|
||||
- **Canonical JSON**: `__Libraries/StellaOps.Attestor.ProofChain/Json/Rfc8785JsonCanonicalizer.cs` (with `.DecimalPoint`, `.NumberSerialization`, `.StringNormalization`, `.WriteMethods`) -- RFC 8785 canonicalization ensuring deterministic JSON for stable hashing.
|
||||
- **Content-Addressed IDs**: `Identifiers/ContentAddressedIdGenerator.cs` -- generates SHA-256 IDs from canonical content.
|
||||
- **Merkle Tree**: `Merkle/DeterministicMerkleTreeBuilder.cs` (with `.Helpers`, `.Proof`) -- Merkle tree construction using SHA-256 for proof aggregation. `MerkleProof.cs`, `MerkleProofStep.cs` -- inclusion proofs.
|
||||
- **DSSE Signing**: `Signing/ProofChainSigner.cs` (with `.Verification`) -- signs proof blobs in DSSE envelopes. `DssePreAuthenticationEncoding.cs` -- PAE for DSSE.
|
||||
- **Canonical JSON Serializer (Core)**: `StellaOps.Attestor.Core/Serialization/CanonicalJsonSerializer.cs` -- alternative canonical serializer in core.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/JsonCanonicalizerTests.cs`, `MerkleTreeBuilderTests.cs`, `Signing/ProofChainSignerTests.cs`, `StellaOps.Attestor.Core.Tests/Serialization/CanonicalJsonSerializerTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Create a `ProofBlob` from JSON content, compute its SHA-256 hash via `ProofHashing`, and verify the hash matches manual SHA-256 computation of the canonical JSON
|
||||
- [ ] Modify the proof blob content and verify the hash changes
|
||||
- [ ] Canonicalize identical JSON with different formatting via `Rfc8785JsonCanonicalizer`, hash both, and verify hashes match
|
||||
- [ ] Build a Merkle tree from 8 proof blobs and verify the root hash is deterministic
|
||||
- [ ] Generate an inclusion proof for a specific blob and verify it validates against the root
|
||||
- [ ] Sign a proof blob via `ProofChainSigner` and verify the DSSE envelope contains the correct hash
|
||||
- [ ] Verify a signed proof blob via `ProofChainSigner.Verification` and confirm integrity
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,43 @@
|
||||
# CVSS v4.0 + CycloneDX 1.7 + SLSA v1.2 Scanner Convergence
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Scanner stack supports CVSS v4.0 scoring, CycloneDX output (with crypto metadata), and SLSA provenance predicate types. The Signer module includes statement builder for SLSA provenance and integration tests.
|
||||
|
||||
## Implementation Details
|
||||
- **CycloneDX Writer**: `src/Attestor/__Libraries/StellaOps.Attestor.StandardPredicates/Writers/CycloneDxWriter.cs` -- comprehensive CycloneDX writer with 40+ partial files covering all elements:
|
||||
- `.Components`, `.Services`, `.Vulnerabilities` -- core SBOM elements
|
||||
- `.Crypto`, `.CryptoCertificates`, `.CryptoMaterial` -- crypto metadata support
|
||||
- `.Attestation Maps`, `.Claims`, `.Declarations` -- attestation elements
|
||||
- `.Formulation`, `.Evidence` -- build provenance and evidence
|
||||
- `.Validation` -- output validation
|
||||
- **CycloneDX Parser**: `Parsers/CycloneDxPredicateParser.cs` (with `.ExtractMetadata`, `.ExtractSbom`, `.Validation`, `.SerialNumber`) -- parses CycloneDX predicates.
|
||||
- **SLSA Provenance Parser**: `Parsers/SlsaProvenancePredicateParser.cs` (with `.ExtractMetadata`, `.Validation`) -- parses SLSA v1.x provenance predicates.
|
||||
- **SLSA Schema Validator**: `Validation/SlsaSchemaValidator.cs` (with `.BuildDefinition`, `.Helpers`, `.Level`, `.RunDetails`) -- validates SLSA provenance against schema.
|
||||
- **SPDX 3.0.1 Build Attestation**: `src/Attestor/__Libraries/StellaOps.Attestor.Spdx3/BuildAttestationMapper.cs` -- maps build attestation to SPDX 3.0.1.
|
||||
- **Standard Predicate Registry**: `StandardPredicateRegistry.cs` -- registers all supported predicate types including SLSA.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.StandardPredicates.Tests/` -- CycloneDX, SPDX, and SLSA tests. `Parsers/SlsaProvenancePredicateParserTests.cs`, `Validation/SlsaSchemaValidatorTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Write a CycloneDX SBOM with crypto metadata (algorithm properties, key material) and verify crypto elements are correctly serialized
|
||||
- [ ] Parse a CycloneDX SBOM with vulnerabilities containing CVSS v4.0 scores and verify score extraction
|
||||
- [ ] Parse an SLSA provenance predicate and verify build definition, run details, and materials are extracted
|
||||
- [ ] Validate an SLSA provenance predicate against `SlsaSchemaValidator` and verify it passes for a well-formed predicate
|
||||
- [ ] Validate an SLSA predicate missing required fields and verify schema validation reports specific errors
|
||||
- [ ] Map an SLSA provenance to SPDX 3.0.1 build attestation via `BuildAttestationMapper` and verify the mapping preserves build materials
|
||||
- [ ] Verify `StandardPredicateRegistry` returns correct parsers for CycloneDX, SPDX, and SLSA predicate types
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,51 @@
|
||||
# CycloneDX 1.6 and SPDX 3.0.1 Full SBOM Support (Parsers, Writers, Attestation)
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Comprehensive CycloneDX 1.6 and SPDX 3.0.1 parsers and writers supporting all major SBOM elements: components, services, vulnerabilities, crypto, attestation maps, declarations, evidence, formulation, and more. Includes predicate parsers with metadata extraction and validation, SPDX 3.0 build attestation mappers, and CycloneDX VEX normalizer. 40+ partial class files for CycloneDX alone.
|
||||
|
||||
## Implementation Details
|
||||
- **CycloneDX Writer**: `src/Attestor/__Libraries/StellaOps.Attestor.StandardPredicates/Writers/CycloneDxWriter.cs` -- 40+ partial files:
|
||||
- Core: `.Convert`, `.Validation`, `.Metadata`, `.SerialNumber`
|
||||
- Components: `.Components`, `.Dependencies`, `.Pedigree`, `.Swid`
|
||||
- Services: `.Services`
|
||||
- Vulnerabilities: `.Vulnerabilities`
|
||||
- Crypto: `.Crypto`, `.CryptoCertificates`, `.CryptoMaterial`
|
||||
- Attestation: `.AttestationMaps`, `.Claims`, `.Declarations`, `.DeclarationTargets`, `.Definitions`
|
||||
- Evidence: `.Evidence`, `.EvidenceOccurrences`
|
||||
- Formulation: `.Formulation`, `.InputsOutputs`, `.Tasks`
|
||||
- Compliance: `.Compositions`, `.Considerations`, `.Environmental`
|
||||
- DTOs: `.DtoBom`, `.DtoComponent`, `.DtoService`, `.DtoVulnerability`, `.DtoCrypto`, etc.
|
||||
- **SPDX Writer**: `SpdxWriter.cs` -- 50+ partial files covering all SPDX 3.0.1 profiles: `.Packages`, `.FileElement`, `.Snippets`, `.Relationships`, `.Licensing`, `.Vulnerabilities`, `.Builds`, `.Assessments`, `.AiPackage`, `.DatasetPackage`, `.Agents`, `.Signatures`, etc.
|
||||
- **CycloneDX Parser**: `Parsers/CycloneDxPredicateParser.cs` (with `.ExtractMetadata`, `.ExtractSbom`, `.Validation`, `.SerialNumber`)
|
||||
- **SPDX Parser**: `Parsers/SpdxPredicateParser.cs` (with `.ExtractMetadata`, `.ExtractSbom`, `.Validation`)
|
||||
- **SBOM Models**: `Models/` -- 106 model files: `SbomComponent`, `SbomService`, `SbomVulnerability`, `SbomDocument`, etc.
|
||||
- **SBOM Canonicalizer**: `Canonicalization/SbomCanonicalizer.cs` (with `.Elements`)
|
||||
- **License Expression Parser**: `Licensing/SpdxLicenseExpressionParser.cs` (with partials)
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.StandardPredicates.Tests/` -- 25+ test files including CycloneDx/SpdxDeterminismTests, SchemaValidationTests, ParserTests, WriterProfileTests
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Write a CycloneDX 1.6 SBOM with components, services, and vulnerabilities via `CycloneDxWriter.Convert` and verify all elements are present in the output
|
||||
- [ ] Write an SPDX 3.0.1 document with packages, files, snippets, and relationships via `SpdxWriter.Convert` and verify all profiles are populated
|
||||
- [ ] Parse a CycloneDX SBOM via `CycloneDxPredicateParser` and verify metadata extraction (serial number, version, timestamp)
|
||||
- [ ] Parse an SPDX SBOM via `SpdxPredicateParser` and verify package extraction with licensing info
|
||||
- [ ] Write a CycloneDX SBOM with crypto properties and verify crypto algorithm and certificate elements
|
||||
- [ ] Write an SPDX document with AI/ML profiles (AiPackage, DatasetPackage) and verify profile elements
|
||||
- [ ] Round-trip test: write CycloneDX -> parse -> write again and verify deterministic output
|
||||
- [ ] Round-trip test: write SPDX -> parse -> write again and verify deterministic output
|
||||
- [ ] Verify license expression parsing for complex SPDX expressions (e.g., `(MIT OR Apache-2.0) AND BSD-3-Clause`)
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,42 @@
|
||||
# Delta Verdict and Change Trace System
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Full delta computation engine with verdict predicates, change trace entries, budget tracking, VEX delta computation, attestation service, and smart diff with trust indicators. Frontend delta-verdict service and models consume the API. Delta-first comparison shows what changed since last trusted point.
|
||||
|
||||
## Implementation Details
|
||||
- **Delta Verdict Predicate**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Predicates/DeltaVerdictPredicate.cs` (with `.Budget` partial) -- predicate for delta verdict attestations with budget impact tracking.
|
||||
- **Delta Models**: `DeltaVerdictChange.cs` -- individual change entry. `DeltaFindingKey.cs` -- unique finding identifier for delta tracking. `VerdictDeltaSummary.cs` -- summary of all changes. `VerdictFindingChange.cs` -- per-finding change details. `VerdictRuleChange.cs` -- policy rule changes.
|
||||
- **Change Trace Service**: `__Libraries/StellaOps.Attestor.ProofChain/ChangeTrace/ChangeTraceAttestationService.cs` (with `.Helpers`, `.Mapping`) -- implements `IChangeTraceAttestationService`. Produces change trace attestations.
|
||||
- **Change Trace Predicate**: `Predicates/ChangeTracePredicate.cs`, `ChangeTracePredicateSummary.cs`, `ChangeTraceDeltaEntry.cs` -- change trace predicate models.
|
||||
- **VEX Delta**: `Predicates/VexDeltaPredicate.cs`, `VexDeltaChange.cs`, `VexDeltaStatement.cs`, `VexDeltaSummary.cs` -- VEX-specific delta tracking.
|
||||
- **SBOM Delta**: `Predicates/SbomDeltaPredicate.cs`, `SbomDeltaComponent.cs`, `SbomDeltaSummary.cs`, `SbomDeltaVersionChange.cs` -- SBOM diff tracking.
|
||||
- **Statements**: `Statements/DeltaVerdictStatement.cs`, `ChangeTraceStatement.cs` -- in-toto statement wrappers.
|
||||
- **Trust Delta**: `Predicates/TrustDeltaRecord.cs` -- trust score change tracking.
|
||||
- **Delta Attestation Service (Core)**: `StellaOps.Attestor.Core/Delta/DeltaAttestationService.cs`, `IDeltaAttestationService.cs`
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/Statements/DeltaVerdictStatementTests.cs`, `ChangeTrace/ChangeTracePredicateTests.cs`, `StellaOps.Attestor.Core.Tests/Delta/DeltaAttestationServiceTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Generate a delta verdict between two snapshots with added, removed, and changed findings and verify `DeltaVerdictPredicate` categorizes each correctly
|
||||
- [ ] Verify `VerdictDeltaSummary` counts (added, removed, changed, unchanged) match the actual changes
|
||||
- [ ] Generate a change trace via `ChangeTraceAttestationService` and verify `ChangeTraceDeltaEntry` entries capture timestamps and change types
|
||||
- [ ] Compute a VEX delta between two VEX documents and verify `VexDeltaSummary` tracks status changes
|
||||
- [ ] Compute an SBOM delta between two SBOMs and verify `SbomDeltaComponent` captures added/removed/changed components
|
||||
- [ ] Verify budget impact tracking in `DeltaVerdictPredicate.Budget` by adding findings that exceed budget thresholds
|
||||
- [ ] Verify `TrustDeltaRecord` captures trust score changes between snapshots
|
||||
- [ ] Wrap delta verdict in `DeltaVerdictStatement` and verify valid in-toto statement output
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,40 @@
|
||||
# Deterministic Evidence Graph with Hash-Addressed Nodes
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Content-addressed proof graph with typed nodes/edges, subgraph extraction, mutation operations, and content-addressed ID generation for all identifiers (ArtifactId, EvidenceId, ProofBundleId, VexVerdictId, etc.).
|
||||
|
||||
## Implementation Details
|
||||
- **Proof Graph Service**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Graph/InMemoryProofGraphService.cs` -- implements `IProofGraphService` with partials:
|
||||
- `.Mutation` -- add/remove nodes and edges
|
||||
- `.Queries` -- query nodes by type, find paths, get neighbors
|
||||
- `.Subgraph` -- extract subgraphs rooted at a specific node
|
||||
- **Graph Models**: `ProofGraphNode.cs` (typed via `ProofGraphNodeType`), `ProofGraphEdge.cs` (typed via `ProofGraphEdgeType`), `ProofGraphPath.cs`, `ProofGraphSubgraph.cs`
|
||||
- **Content-Addressed IDs**: `Identifiers/ContentAddressedIdGenerator.cs` (with `.Graph`) -- generates deterministic node/edge IDs from content. Types: `ArtifactId`, `EvidenceId`, `ProofBundleId`, `VexVerdictId`, `ReasoningId`, `GraphRevisionId`, `TrustAnchorId`, `SbomEntryId`.
|
||||
- **Graph Root Attestation**: `src/Attestor/__Libraries/StellaOps.Attestor.GraphRoot/` -- `GraphRootAttestor.cs` (implements `IGraphRootAttestor`), `Sha256MerkleRootComputer.cs` (implements `IMerkleRootComputer`). Models: `GraphRootAttestation.cs`, `GraphRootPredicate.cs`, `GraphRootResults.cs`.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/ContentAddressedIdGeneratorTests.cs`, `__Tests/StellaOps.Attestor.GraphRoot.Tests/GraphRootAttestorTests.cs`, `Sha256MerkleRootComputerTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Add 5 nodes of different types (Evidence, Verdict, Policy, Artifact) to `InMemoryProofGraphService` and verify each gets a unique content-addressed ID
|
||||
- [ ] Add edges between nodes and verify edge IDs are deterministic based on source, target, and type
|
||||
- [ ] Query nodes by type and verify correct filtering
|
||||
- [ ] Find a path between two nodes via graph queries and verify `ProofGraphPath` contains the correct sequence
|
||||
- [ ] Extract a subgraph rooted at an evidence node and verify it contains only reachable nodes and edges
|
||||
- [ ] Remove a node via mutation and verify all connected edges are also removed
|
||||
- [ ] Compute graph root attestation via `GraphRootAttestor` and verify `GraphRootPredicate` contains the Merkle root of all node IDs
|
||||
- [ ] Add identical content as a node twice and verify deduplication (same content-addressed ID)
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,42 @@
|
||||
# Deterministic SBOM Canonicalization (RFC 8785 JCS)
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Deterministic SBOM canonicalization using full RFC 8785 JSON Canonicalization Scheme with decimal point handling, number serialization, string normalization, and reproducible transforms between SPDX and CycloneDX. Verified by property-based determinism tests.
|
||||
|
||||
## Implementation Details
|
||||
- **SBOM Canonicalizer**: `src/Attestor/__Libraries/StellaOps.Attestor.StandardPredicates/Canonicalization/SbomCanonicalizer.cs` (with `.Elements` partial) -- implements `ISbomCanonicalizer`. Orders SBOM elements deterministically for stable hashing.
|
||||
- **RFC 8785 Canonicalizer**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Json/Rfc8785JsonCanonicalizer.cs` -- implements `IJsonCanonicalizer` with partials:
|
||||
- `.DecimalPoint` -- handles decimal point normalization
|
||||
- `.NumberSerialization` -- IEEE 754 number serialization per RFC 8785
|
||||
- `.StringNormalization` -- Unicode and string escape normalization
|
||||
- `.WriteMethods` -- low-level write methods
|
||||
- **JSON Canonicalizer (StandardPredicates)**: `__Libraries/StellaOps.Attestor.StandardPredicates/JsonCanonicalizer.cs` -- additional canonicalizer for standard predicates.
|
||||
- **JSON Canonicalizer (TrustVerdict)**: `__Libraries/StellaOps.Attestor.TrustVerdict/JsonCanonicalizer.cs` -- canonicalizer for trust verdict payloads.
|
||||
- **CycloneDX Determinism Tests**: `__Tests/StellaOps.Attestor.StandardPredicates.Tests/CycloneDxDeterminismTests.cs`
|
||||
- **SPDX Determinism Tests**: `SpdxDeterminismTests.cs`
|
||||
- **JSON Canonicalizer Tests**: `JsonCanonicalizerTests.cs` (in both ProofChain and StandardPredicates test projects)
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Canonicalize a CycloneDX SBOM via `SbomCanonicalizer`, hash the output, canonicalize again, and verify identical hashes
|
||||
- [ ] Canonicalize an SPDX SBOM, hash, re-canonicalize, and verify identical hashes
|
||||
- [ ] Apply `Rfc8785JsonCanonicalizer` to JSON with unordered keys and verify key order matches RFC 8785 (lexicographic)
|
||||
- [ ] Canonicalize JSON with floating-point edge cases (e.g., 1.0, -0.0, 1e10) and verify IEEE 754 normalization
|
||||
- [ ] Canonicalize JSON with Unicode escapes and verify normalization to shortest UTF-8 representation
|
||||
- [ ] Create two SBOMs with identical content but different component ordering, canonicalize both, and verify identical output
|
||||
- [ ] Verify CycloneDX and SPDX round-trip: parse -> write -> canonicalize produces stable output
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,40 @@
|
||||
# Deterministic verdict serialization (canonical JSON / JCS)
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
RFC 8785 (JCS) canonical JSON serializer ensures deterministic, byte-stable verdict serialization for reproducible signing.
|
||||
|
||||
## Implementation Details
|
||||
- **RFC 8785 Canonicalizer**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Json/Rfc8785JsonCanonicalizer.cs` -- full RFC 8785 implementation with partials for decimal, number, string, and write operations.
|
||||
- **Verdict Receipt Payload**: `__Libraries/StellaOps.Attestor.ProofChain/Statements/VerdictReceiptPayload.cs` -- verdict payload serialized canonically for signing.
|
||||
- **Verdict Decision**: `Statements/VerdictDecision.cs`, `VerdictInputs.cs`, `VerdictOutputs.cs` -- verdict computation components serialized deterministically.
|
||||
- **Verdict Summary**: `Predicates/VerdictSummary.cs` -- summary predicate for verdict output.
|
||||
- **Proof Chain Signer**: `Signing/ProofChainSigner.cs` -- signs canonical verdict payloads.
|
||||
- **DSSE Canonicalizer**: `StellaOps.Attestor.Core/Submission/IDsseCanonicalizer.cs`, `Infrastructure/Submission/DefaultDsseCanonicalizer.cs` -- canonicalizes DSSE payloads before signing.
|
||||
- **Canonical JSON Serializer (Core)**: `StellaOps.Attestor.Core/Serialization/CanonicalJsonSerializer.cs` -- core canonical JSON serializer.
|
||||
- **Verdict Ledger**: `__Libraries/StellaOps.Attestor.VerdictLedger/VerdictLedgerEntry.cs`, `VerdictLedgerService.cs` -- ledger entries use canonical serialization.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/JsonCanonicalizerTests.cs`, `__Tests/StellaOps.Attestor.Tests/VerdictLedgerHashTests.cs`, `StellaOps.Attestor.Core.Tests/Serialization/CanonicalJsonSerializerTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Serialize a `VerdictReceiptPayload` to canonical JSON and verify key ordering matches RFC 8785
|
||||
- [ ] Serialize the same verdict twice and verify byte-for-byte equality
|
||||
- [ ] Sign a canonical verdict via `ProofChainSigner` and verify the signature covers the canonical bytes
|
||||
- [ ] Verify a signed verdict: re-canonicalize the payload and confirm the hash matches the signed hash
|
||||
- [ ] Serialize a verdict with various data types (strings, numbers, booleans, nulls, arrays, objects) and verify each type follows RFC 8785 rules
|
||||
- [ ] Store a verdict in `VerdictLedgerService` and verify the ledger hash matches the canonical hash
|
||||
- [ ] Canonicalize via `DefaultDsseCanonicalizer` and verify it produces identical output to `Rfc8785JsonCanonicalizer`
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,43 @@
|
||||
# DSSE Attestation Bundling and Batch Publishing to Rekor
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Attestation bundling with configurable options, aggregation abstraction, and Rekor submission queue with retry worker and sync background service.
|
||||
|
||||
## Implementation Details
|
||||
- **Attestation Bundler**: `src/Attestor/__Libraries/StellaOps.Attestor.Bundling/Services/AttestationBundler.cs` -- implements `IAttestationBundler`. Aggregates multiple DSSE-signed attestations into bundles.
|
||||
- **Bundle Aggregator**: `Abstractions/IBundleAggregator.cs` -- interface for aggregating attestation bundles.
|
||||
- **Bundle Store**: `Abstractions/IBundleStore.cs` -- persistence interface. `Models/AttestationBundle.cs` -- bundle model.
|
||||
- **Bundling Options**: `Configuration/BundlingOptions.cs` -- configurable batch size, timeout, and bundling strategy.
|
||||
- **Rekor Submission Queue**: `src/Attestor/StellaOps.Attestor/StellaOps.Attestor.Core/Queue/IRekorSubmissionQueue.cs` -- queue interface. `RekorQueueItem.cs`, `RekorSubmissionStatus.cs`, `QueueDepthSnapshot.cs` -- queue models.
|
||||
- **PostgreSQL Queue**: `StellaOps.Attestor.Infrastructure/Queue/PostgresRekorSubmissionQueue.cs` -- durable PostgreSQL-backed queue with SKIP LOCKED.
|
||||
- **Retry Worker**: `Infrastructure/Workers/RekorRetryWorker.cs` -- retries failed Rekor submissions.
|
||||
- **Rekor Sync Service**: `StellaOps.Attestor.Core/Rekor/RekorSyncBackgroundService.cs` -- background service for batch Rekor publication.
|
||||
- **Rekor Client**: `Infrastructure/Rekor/HttpRekorClient.cs`, `ResilientRekorClient.cs` -- HTTP client with resilience. `IRekorClient.cs` -- interface.
|
||||
- **Verdict Rekor Publisher**: `__Libraries/StellaOps.Attestor.Infrastructure/Rekor/VerdictRekorPublisher.cs` -- publishes verdict attestations to Rekor.
|
||||
- **Tests**: `StellaOps.Attestor.Tests/RekorSubmissionQueueTests.cs`, `RekorRetryWorkerTests.cs`, `HttpRekorClientTests.cs`, `__Tests/StellaOps.Attestor.Bundling.Tests/AttestationBundlerTests.cs`, `BundleAggregatorTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Bundle 5 DSSE-signed attestations via `AttestationBundler` with a batch size of 5 and verify a single bundle is produced
|
||||
- [ ] Configure bundling with a batch size of 3 and submit 5 attestations, verifying 2 bundles are produced
|
||||
- [ ] Enqueue attestations to `PostgresRekorSubmissionQueue` and verify they are stored with `Pending` status
|
||||
- [ ] Process the queue and verify successful submissions are marked as `Completed`
|
||||
- [ ] Simulate a Rekor submission failure and verify `RekorRetryWorker` retries the failed item
|
||||
- [ ] Verify `QueueDepthSnapshot` reports correct counts of pending, processing, and completed items
|
||||
- [ ] Publish a verdict attestation via `VerdictRekorPublisher` and verify the Rekor receipt is stored
|
||||
- [ ] Test `ResilientRekorClient` circuit breaker by simulating repeated failures and verifying the circuit opens
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,44 @@
|
||||
# DSSE Envelope Signing for Attestations
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
DSSE envelope creation, signing, verification, and serialization are fully implemented across multiple Attestor libraries. The advisory proposed DSSE signing as part of a batch sweep experiment; the signing infrastructure is production-ready.
|
||||
|
||||
## Implementation Details
|
||||
- **Envelope Library**: `src/Attestor/StellaOps.Attestor.Envelope/` -- dedicated DSSE envelope library:
|
||||
- `DsseEnvelope.cs` -- envelope model with payload and signatures
|
||||
- `DsseSignature.cs` -- signature model with key ID and signature bytes
|
||||
- `DsseEnvelopeSerializer.cs` -- JSON serialization with options (`DsseEnvelopeSerializationOptions.cs`, `DsseEnvelopeSerializationResult.cs`)
|
||||
- `DssePreAuthenticationEncoding.cs` -- PAE (Pre-Authentication Encoding) per DSSE spec
|
||||
- `DsseCompressionAlgorithm.cs` -- payload compression support
|
||||
- `DsseDetachedPayloadReference.cs` -- detached payload references
|
||||
- `EnvelopeSignatureService.cs` -- signing service with key management (`EnvelopeKey.cs`, `EnvelopeKeyIdCalculator.cs`, `EnvelopeSignature.cs`, `EnvelopeSignatureResult.cs`)
|
||||
- **ProofChain Signing**: `__Libraries/StellaOps.Attestor.ProofChain/Signing/` -- `ProofChainSigner.cs` (with `.Verification`), `IProofChainSigner.cs`, `DsseEnvelope.cs`, `DsseSignature.cs`, `SignatureVerificationResult.cs`, `SigningKeyProfile.cs`
|
||||
- **Core Signing**: `StellaOps.Attestor.Core/Signing/DsseSigningService.cs`, `IAttestationSigningService.cs` -- core DSSE signing
|
||||
- **Attestation Library**: `src/Attestor/StellaOps.Attestation/` -- `DsseHelper.cs`, `DsseVerifier.cs`, `DsseEnvelopeExtensions.cs`
|
||||
- **Tests**: `StellaOps.Attestor.Envelope/__Tests/DsseEnvelopeSerializerTests.cs`, `EnvelopeSignatureServiceTests.cs`, `StellaOps.Attestation.Tests/DsseHelperTests.cs`, `DsseVerifierTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Create a DSSE envelope with a JSON payload via `EnvelopeSignatureService`, sign it, and verify the envelope contains the signature
|
||||
- [ ] Serialize the envelope via `DsseEnvelopeSerializer` and deserialize it, verifying round-trip fidelity
|
||||
- [ ] Verify the PAE (Pre-Authentication Encoding) matches the DSSE spec: `DSSEv1 <payloadType.length> <payloadType> <payload.length> <payload>`
|
||||
- [ ] Sign an envelope via `ProofChainSigner` and verify via `ProofChainSigner.Verification`
|
||||
- [ ] Sign an envelope via `DsseSigningService` in Core and verify via `DsseVerifier`
|
||||
- [ ] Tamper with the payload after signing and verify signature verification fails
|
||||
- [ ] Create an envelope with detached payload reference and verify the reference is correctly maintained
|
||||
- [ ] Sign with multiple keys and verify each signature is independently verifiable
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,62 @@
|
||||
# DSSE Envelope Size Management (Guardrails, Chunking, Gateway Awareness)
|
||||
|
||||
## Module
|
||||
Attestor (with CLI and Scanner integration)
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
DSSE envelope construction and Rekor submission exist, but no explicit size guardrails (70-100KB heuristic), automatic payload splitting/chunking, or gateway-aware sizing logic is implemented. The architecture stores full attestations internally and uses Rekor for hash-based inclusion proofs. Envelope size awareness exists in EPSS fetcher and delta-sig CLI commands, and bundling/queue options have configurable size limits.
|
||||
|
||||
## What's Implemented
|
||||
- **Enhanced Rekor Proof Builder**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Rekor/EnhancedRekorProofBuilder.cs` (with `.Build`, `.Validate`) -- builds and validates Rekor proofs for DSSE envelopes.
|
||||
- **DSSE Envelope**: `ProofChain/Signing/DsseEnvelope.cs`, `DsseSignature.cs` -- DSSE envelope models.
|
||||
- **Rekor Queue Options**: `StellaOps.Attestor.Core/Options/RekorQueueOptions.cs` -- configurable queue options.
|
||||
- **Rekor Submission Queue**: `Core/Queue/IRekorSubmissionQueue.cs` with `PostgresRekorSubmissionQueue.cs` -- submission queue.
|
||||
- **Resilient Rekor Client**: `Infrastructure/Rekor/ResilientRekorClient.cs` -- resilient HTTP client with retry and circuit breaker.
|
||||
- **Tile Proxy Options**: `StellaOps.Attestor.TileProxy/TileProxyOptions.cs` -- size-related configuration for tile caching.
|
||||
- **Delta-Sig Attestation CLI**: `src/Cli/StellaOps.Cli/Commands/Binary/DeltaSigCommandGroup.cs` -- uses DSSE envelope creation and Rekor submission.
|
||||
- **Bundle Export with DSSE**: `src/Cli/StellaOps.Cli/Commands/BundleExportCommand.cs` -- `--include-dsse` option for DSSE envelope inclusion.
|
||||
- **Bundle Verify with DSSE**: `src/Cli/StellaOps.Cli/Commands/BundleVerifyCommand.cs` -- DSSE signature verification.
|
||||
- **Witness DSSE**: `src/Cli/StellaOps.Cli/Commands/Witness/WitnessCoreCommandGroup.cs` -- `--format envelope` option.
|
||||
|
||||
## What's Missing
|
||||
- **Explicit size guardrails**: No pre-submission validation rejecting DSSE envelopes exceeding a configurable size limit (70-100KB) before Rekor submission.
|
||||
- **Hash-only mode fallback**: No automatic fallback to submitting only the payload hash (rather than full envelope) when size exceeds the limit.
|
||||
- **Payload chunking/splitting**: No mechanism to split large DSSE payloads into smaller chunks with a manifest linking them, or Merkle-based sharding.
|
||||
- **Per-predicate-type size budget**: No configurable size limits per predicate type (e.g., SBOM attestations can be larger than verdict attestations).
|
||||
- **Gateway-aware sizing**: No NGINX/WAF request body size coordination. Infrastructure teams must manually align `client_max_body_size` with attestation sizes.
|
||||
- **Streaming submission**: No chunked/streaming upload for large envelopes.
|
||||
- **Size metrics and alerting**: No telemetry tracking envelope sizes and alerting when they approach the threshold.
|
||||
- **Compression**: No optional payload compression (gzip) to reduce envelope size before submission.
|
||||
- **CLI size warnings**: No warning in CLI when a generated envelope exceeds Rekor's size limit, no `--max-envelope-size` option.
|
||||
|
||||
## Implementation Plan
|
||||
- Add size validation step in `EnhancedRekorProofBuilder.Validate` checking against configurable size limit (default 100KB)
|
||||
- Implement hash-only submission mode as automatic fallback for oversized envelopes
|
||||
- Add per-predicate-type size budget configuration
|
||||
- Implement `IEnvelopeShardingService` for Merkle-based sharding of large attestations
|
||||
- Add optional payload compression (gzip) for envelopes near the threshold
|
||||
- Collect size metrics via existing telemetry infrastructure
|
||||
- Add envelope size check to CLI attest/export commands with warning/error on oversized envelopes
|
||||
- Document gateway configuration requirements (NGINX/WAF body size limits)
|
||||
- Add tests for size validation, fallback behavior, chunking, and metrics collection
|
||||
|
||||
## Related Documentation
|
||||
- Source: See feature catalog
|
||||
|
||||
## Merged From
|
||||
- `attestor/dsse-envelope-size-awareness.md` (deleted)
|
||||
- `attestor/rekor-envelope-size-guardrails.md` (deleted)
|
||||
- `cli/dsse-envelope-size-management.md` (deleted)
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
38
docs/features/checked/attestor/dsse-for-every-artifact.md
Normal file
38
docs/features/checked/attestor/dsse-for-every-artifact.md
Normal file
@@ -0,0 +1,38 @@
|
||||
# DSSE (Dead Simple Signing Envelope) for Every Artifact
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Comprehensive DSSE signing implementation across ProofChain, Envelope, and Spdx3 libraries with verification, pre-authentication encoding, and determinism tests.
|
||||
|
||||
## Implementation Details
|
||||
- **Envelope Library**: `src/Attestor/StellaOps.Attestor.Envelope/` -- standalone DSSE envelope library with `DsseEnvelope`, `DsseSignature`, `DsseEnvelopeSerializer`, `DssePreAuthenticationEncoding`, `EnvelopeSignatureService`.
|
||||
- **ProofChain DSSE**: `__Libraries/StellaOps.Attestor.ProofChain/Signing/` -- `ProofChainSigner.cs` (with `.Verification`), `DsseEnvelope.cs`, `DsseSignature.cs`, `IProofChainSigner.cs`, `IProofChainKeyStore.cs`.
|
||||
- **SPDX3 DSSE**: `__Libraries/StellaOps.Attestor.Spdx3/` -- `DsseSpdx3Signer.cs` (with `.Encoding`, `.SignAsync`, `.SignBuildProfile`, `.Verify`), `DsseSpdx3Envelope.cs`, `DsseSpdx3Signature.cs`, `IDsseSpdx3Signer.cs`.
|
||||
- **BinaryDiff DSSE**: `__Libraries/StellaOps.Attestor.StandardPredicates/BinaryDiff/BinaryDiffDsseSigner.cs`, `BinaryDiffDsseVerifier.cs`.
|
||||
- **Core DSSE**: `StellaOps.Attestor.Core/Signing/DsseSigningService.cs`, `DssePreAuthenticationEncoding.cs`.
|
||||
- **Attestation DSSE**: `StellaOps.Attestation/DsseHelper.cs`, `DsseVerifier.cs`.
|
||||
- **Determinism Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/Envelope/DsseEnvelopeDeterminismTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Sign an SBOM artifact via `DsseSpdx3Signer` and verify the DSSE envelope wraps the SPDX3 payload
|
||||
- [ ] Sign a binary diff artifact via `BinaryDiffDsseSigner` and verify the envelope
|
||||
- [ ] Sign a proof chain artifact via `ProofChainSigner` and verify the envelope
|
||||
- [ ] Sign a core attestation via `DsseSigningService` and verify the envelope
|
||||
- [ ] Verify each signed artifact type with its corresponding verifier
|
||||
- [ ] Test determinism: sign the same payload twice and verify the PAE bytes are identical
|
||||
- [ ] Verify cross-library compatibility: create an envelope with `EnvelopeSignatureService`, verify with `DsseVerifier`
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,41 @@
|
||||
# DSSE/In-Toto Attestation Signing and Verification
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Full DSSE envelope signing service supporting ECDSA P-256, Ed25519, and RSA-PSS. Includes in-toto predicate types for proof chains, SPDX3 build attestations, and verification workflows.
|
||||
|
||||
## Implementation Details
|
||||
- **Signing Service**: `src/Attestor/StellaOps.Attestor/StellaOps.Attestor.Core/Signing/DsseSigningService.cs` -- core DSSE signing with multi-algorithm support.
|
||||
- **Key Management**: `Signing/FileKeyProvider.cs` -- file-based key provider. `IAttestationSigningService.cs` -- signing interface. `AttestationSignRequest.cs`, `AttestationSignResult.cs` -- sign request/result.
|
||||
- **Verification Report Signer**: `Signing/DsseVerificationReportSigner.cs`, `IVerificationReportSigner.cs` -- signs verification reports.
|
||||
- **In-Toto Statements**: `__Libraries/StellaOps.Attestor.ProofChain/Statements/InTotoStatement.cs` -- base in-toto statement. Statement types: `EvidenceStatement`, `ReasoningStatement`, `VexVerdictStatement`, `ProofSpineStatement`, `SbomLinkageStatement`, `VerdictReceiptStatement`, `ReachabilityWitnessStatement`, `AIExplanationStatement`, etc.
|
||||
- **Statement Builder**: `__Libraries/StellaOps.Attestor.ProofChain/Builders/StatementBuilder.cs` (with `.Extended`) -- fluent builder for in-toto statements. `IStatementBuilder.cs` -- interface.
|
||||
- **In-Toto Core**: `StellaOps.Attestor.Core/InToto/` -- `InTotoLink.cs`, `InTotoLinkPredicate.cs`, `LinkBuilder.cs`, `LinkRecorder.cs`, `LayoutVerifier.cs`, `ArtifactDigests.cs` -- in-toto link and layout verification.
|
||||
- **SPDX3 Signing**: `__Libraries/StellaOps.Attestor.Spdx3/DsseSpdx3Signer.cs` (with `.SignAsync`, `.Verify`, `.SignBuildProfile`, `.Encoding`).
|
||||
- **Signing Infrastructure**: `StellaOps.Attestor.Infrastructure/Signing/AttestorSigningService.cs`, `AttestorSigningKeyRegistry.cs`.
|
||||
- **Tests**: `StellaOps.Attestor.Core.Tests/InToto/InTotoGoldenTests.cs`, `InTotoLinkTests.cs`, `LinkBuilderTests.cs`, `LayoutVerifierTests.cs`, `Signing/DssePreAuthenticationEncodingTests.cs`, `VerificationReportSignerTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Sign an in-toto statement via `DsseSigningService` with ECDSA P-256 key and verify the signature
|
||||
- [ ] Sign with Ed25519 key and verify the signature
|
||||
- [ ] Build an in-toto statement via `StatementBuilder` with evidence predicate and verify statement structure
|
||||
- [ ] Create an in-toto link via `LinkBuilder` with materials and products, sign it, and verify
|
||||
- [ ] Verify a layout via `LayoutVerifier` with correct link chain
|
||||
- [ ] Sign an SPDX3 build attestation via `DsseSpdx3Signer` and verify
|
||||
- [ ] Sign a verification report via `DsseVerificationReportSigner` and verify the signed report
|
||||
- [ ] Run golden tests to verify signed attestation output matches known-good test vectors
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
39
docs/features/checked/attestor/dsse-in-toto-event-spine.md
Normal file
39
docs/features/checked/attestor/dsse-in-toto-event-spine.md
Normal file
@@ -0,0 +1,39 @@
|
||||
# DSSE + in-toto Event Spine (Attestation Pipeline)
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
DSSE envelope signing and verification across the pipeline. Scanner emits policy decision and human approval attestations; Attestor ProofChain provides DSSE envelope/signature models and verification.
|
||||
|
||||
## Implementation Details
|
||||
- **ProofSpine System**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Assembly/` -- `IProofSpineAssembler.cs`, `ProofSpineRequest.cs`, `ProofSpineResult.cs`, `ProofSpineSubject.cs`, `SpineVerificationCheck.cs`, `SpineVerificationResult.cs` -- assembles proof spines from multiple attestation events.
|
||||
- **Proof Spine Statement**: `Statements/ProofSpineStatement.cs` -- in-toto statement for proof spine. `Predicates/ProofSpinePredicate.cs` -- spine predicate model.
|
||||
- **Merkle Tree Assembly**: `Assembly/MerkleTree.cs` -- Merkle tree for spine root computation.
|
||||
- **DSSE Signing**: `Signing/ProofChainSigner.cs` (with `.Verification`) signs spine attestations.
|
||||
- **Policy Decision Predicate**: `Predicates/PolicyDecisionPredicate.cs`, `PolicyDecision.cs` -- policy decision attestation.
|
||||
- **Pipeline**: `Pipeline/IProofChainPipeline.cs`, `ProofChainRequest.cs`, `ProofChainResult.cs`, `PipelineSubject.cs`, `RekorEntry.cs` -- proof chain pipeline processing.
|
||||
- **Statement Builder**: `Builders/StatementBuilder.cs` (with `.Extended`) -- builds in-toto statements for pipeline events.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/ProofSpineAssemblyIntegrationTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Assemble a proof spine from 5 attestation events via `IProofSpineAssembler` and verify the spine root hash aggregates all events
|
||||
- [ ] Sign the proof spine via `ProofChainSigner` and verify the DSSE envelope
|
||||
- [ ] Verify the spine via `SpineVerificationCheck` and confirm all constituent attestations are valid
|
||||
- [ ] Create a `PolicyDecisionPredicate` for a pass/fail decision and include it in the spine
|
||||
- [ ] Process a `ProofChainRequest` through the pipeline and verify a `ProofChainResult` is produced with Rekor entry
|
||||
- [ ] Verify the Merkle tree root of the spine matches recomputation from individual event hashes
|
||||
- [ ] Build in-toto statements for each pipeline event via `StatementBuilder` and verify correct predicate types
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,46 @@
|
||||
# DSSE-Signed Exception Objects with Recheck Policy
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Policy exceptions framework with models, repositories, and services exists. DSSE signing infrastructure is available. Full UI exception modal with recheck policy enforcement is partially complete.
|
||||
|
||||
## What's Implemented
|
||||
- **Budget Exception Entry**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Statements/BudgetExceptionEntry.cs` -- exception entry model.
|
||||
- **Exception Ref**: `ProofChain/Services/ExceptionRef.cs` -- reference to an approved exception.
|
||||
- **VEX Override System**: `__Libraries/StellaOps.Attestor.StandardPredicates/VexOverride/` -- VexOverridePredicateBuilder (with `.Build`, `.Serialize`, `.WithMethods`), VexOverrideDecision, EvidenceReference -- structured override/exception with evidence.
|
||||
- **DSSE Signing Infrastructure**: `ProofChain/Signing/ProofChainSigner.cs`, `DsseEnvelope.cs` -- available DSSE signing.
|
||||
- **Policy Decision**: `Predicates/PolicyDecision.cs` -- policy decision referencing exceptions.
|
||||
|
||||
## What's Missing
|
||||
- **DSSE-signed exception objects**: Exceptions are not individually DSSE-signed as standalone attestation artifacts. They exist as records within larger predicates but are not independently verifiable.
|
||||
- **Recheck policy enforcement**: No automated recheck scheduling that re-evaluates exceptions at configured intervals (e.g., 30-day review cycle).
|
||||
- **Exception expiry enforcement**: No automated enforcement of exception expiry dates with re-approval workflow.
|
||||
- **Exception approval workflow**: No multi-party approval flow for exception creation (e.g., two approvers required for critical CVE exceptions).
|
||||
- **Exception audit trail**: No dedicated audit trail for exception lifecycle (created, approved, rechecked, expired, revoked).
|
||||
|
||||
## Implementation Plan
|
||||
- Create `DsseSignedException` model wrapping exception objects in DSSE envelopes
|
||||
- Implement recheck policy with configurable intervals (Scheduler integration)
|
||||
- Add exception expiry enforcement with notification before expiry
|
||||
- Build multi-party approval workflow for high-severity exceptions
|
||||
- Create exception audit trail using the existing AuditHashLogger infrastructure
|
||||
- Add UI exception modal with recheck policy configuration
|
||||
- Add tests for signing, recheck scheduling, and expiry enforcement
|
||||
|
||||
## Related Documentation
|
||||
- Source: See feature catalog
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
37
docs/features/checked/attestor/dsse-signed-path-witnesses.md
Normal file
37
docs/features/checked/attestor/dsse-signed-path-witnesses.md
Normal file
@@ -0,0 +1,37 @@
|
||||
# DSSE-Signed Path Witnesses
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Reachability witness payloads with path information and witness statements, plus path witness predicate type definitions.
|
||||
|
||||
## Implementation Details
|
||||
- **Reachability Witness Payload**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Statements/ReachabilityWitnessPayload.cs` (with `.Path` partial) -- witness payload with call-stack path information.
|
||||
- **Witness Statement**: `Statements/ReachabilityWitnessStatement.cs` -- in-toto statement wrapping the witness payload.
|
||||
- **Path Nodes**: `Statements/WitnessPathNode.cs` -- path node model. `WitnessCallPathNode.cs` -- call-stack path node with function/method details.
|
||||
- **Witness Metadata**: `Statements/WitnessEvidenceMetadata.cs` -- metadata about evidence source. `WitnessGateInfo.cs` -- gate info for policy.
|
||||
- **Predicate Types**: `src/Attestor/StellaOps.Attestor/StellaOps.Attestor.Core/PathWitnessPredicateTypes.cs` -- predicate type URI constants.
|
||||
- **DSSE Signing**: `__Libraries/StellaOps.Attestor.ProofChain/Signing/ProofChainSigner.cs` -- signs witness statements as DSSE envelopes.
|
||||
- **Proof Emitter**: `StellaOps.Attestor.Core/IProofEmitter.cs` -- emits signed path witness proofs.
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Create a `ReachabilityWitnessPayload` with a 4-node call path, wrap in `ReachabilityWitnessStatement`, sign via `ProofChainSigner`, and verify DSSE envelope
|
||||
- [ ] Verify the signed path witness via signature verification
|
||||
- [ ] Tamper with a path node in the signed witness and verify verification fails
|
||||
- [ ] Create path witnesses with different `PathWitnessPredicateTypes` and verify correct predicate type URIs
|
||||
- [ ] Verify `WitnessEvidenceMetadata` captures the analysis tool that generated the path
|
||||
- [ ] Create a path witness with `WitnessGateInfo` specifying policy thresholds and verify it serializes correctly
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
45
docs/features/checked/attestor/dsse-wrapped-reach-maps.md
Normal file
45
docs/features/checked/attestor/dsse-wrapped-reach-maps.md
Normal file
@@ -0,0 +1,45 @@
|
||||
# DSSE-Wrapped Reach-Maps
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Rich graphs and suppression witnesses exist with signing infrastructure available, but a specific "signed reach-map artifact" as a standalone DSSE-wrapped output is not distinctly implemented as described.
|
||||
|
||||
## What's Implemented
|
||||
- **Reachability Witness Payload**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Statements/ReachabilityWitnessPayload.cs` (with `.Path`) -- reachability witness data with call paths.
|
||||
- **Witness Path Nodes**: `Statements/WitnessCallPathNode.cs`, `WitnessPathNode.cs` -- call path node models.
|
||||
- **Micro Witness Evidence**: `Predicates/MicroWitnessFunctionEvidence.cs`, `MicroWitnessBinaryRef.cs`, `MicroWitnessCveRef.cs`, `MicroWitnessSbomRef.cs` -- function-level reachability evidence.
|
||||
- **DSSE Signing**: `Signing/ProofChainSigner.cs`, `DsseEnvelope.cs` -- available signing infrastructure.
|
||||
- **Proof Graph**: `Graph/InMemoryProofGraphService.cs` (with `.Mutation`, `.Queries`, `.Subgraph`) -- graph model for proof evidence.
|
||||
|
||||
## What's Missing
|
||||
- **Standalone reach-map artifact**: No dedicated reach-map document type that captures the full reachability graph (all functions, edges, and reachability status) as a single DSSE-wrapped artifact.
|
||||
- **Reach-map predicate type**: No registered predicate type URI (e.g., `https://stellaops.org/attestation/reachmap/v1`) for reach-map attestations.
|
||||
- **Full graph serialization**: Reachability evidence is captured per-CVE (micro-witness) not as a complete call graph that can be independently verified.
|
||||
- **Reach-map versioning**: No mechanism to version reach-maps and detect changes between scans.
|
||||
- **Reach-map OCI attachment**: No pipeline to attach DSSE-signed reach-maps to OCI images as referrers.
|
||||
|
||||
## Implementation Plan
|
||||
- Define a reach-map predicate type with full call graph serialization
|
||||
- Create a `ReachMapBuilder` that aggregates all micro-witness data into a single reach-map document
|
||||
- Implement DSSE signing for reach-map documents using existing `ProofChainSigner`
|
||||
- Add reach-map versioning with diff detection between scans
|
||||
- Wire OCI attachment via existing `OrasAttestationAttacher`
|
||||
- Add tests for reach-map building, signing, and versioning
|
||||
|
||||
## Related Documentation
|
||||
- Source: See feature catalog
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
40
docs/features/checked/attestor/durable-submission-queue.md
Normal file
40
docs/features/checked/attestor/durable-submission-queue.md
Normal file
@@ -0,0 +1,40 @@
|
||||
# Durable Submission Queue
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Durable Rekor submission queue with backend support, submission responses, and entry event tracking.
|
||||
|
||||
## Implementation Details
|
||||
- **Queue Interface**: `src/Attestor/StellaOps.Attestor/StellaOps.Attestor.Core/Queue/IRekorSubmissionQueue.cs` -- durable queue interface for Rekor submissions.
|
||||
- **Queue Models**: `RekorQueueItem.cs` -- queue item with payload, status, and retry metadata. `RekorSubmissionStatus.cs` -- status enum (Pending, Processing, Completed, Failed). `QueueDepthSnapshot.cs` -- queue depth metrics.
|
||||
- **PostgreSQL Queue**: `StellaOps.Attestor.Infrastructure/Queue/PostgresRekorSubmissionQueue.cs` -- PostgreSQL-backed durable queue using SKIP LOCKED for concurrent consumers.
|
||||
- **Retry Worker**: `Infrastructure/Workers/RekorRetryWorker.cs` -- background worker retrying failed submissions.
|
||||
- **Queue Options**: `StellaOps.Attestor.Core/Options/RekorQueueOptions.cs` -- queue configuration (batch size, retry interval, max retries).
|
||||
- **Rekor Submission Response**: `Rekor/RekorSubmissionResponse.cs` -- response model from Rekor API.
|
||||
- **Entry Events**: `Rekor/RekorEntryEvent.cs` -- events emitted on submission lifecycle changes.
|
||||
- **Tests**: `StellaOps.Attestor.Tests/RekorSubmissionQueueTests.cs`, `RekorRetryWorkerTests.cs`, `Integration/PostgresRekorSubmissionQueueIntegrationTests.cs`, `__Tests/StellaOps.Attestor.Core.Tests/Rekor/RekorEntryEventTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Enqueue 10 items to `PostgresRekorSubmissionQueue` and verify `QueueDepthSnapshot` shows 10 pending
|
||||
- [ ] Dequeue items using SKIP LOCKED and verify concurrent consumers do not process the same item
|
||||
- [ ] Process a queue item successfully and verify status changes to `Completed`
|
||||
- [ ] Simulate a submission failure and verify status changes to `Failed` with retry count incremented
|
||||
- [ ] Verify `RekorRetryWorker` picks up failed items after the retry interval and reprocesses them
|
||||
- [ ] Verify items exceeding max retries are not retried further
|
||||
- [ ] Verify `RekorEntryEvent` is emitted on each status transition
|
||||
- [ ] Verify queue survives process restart (items persist in PostgreSQL)
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
39
docs/features/checked/attestor/edge-level-attestations.md
Normal file
39
docs/features/checked/attestor/edge-level-attestations.md
Normal file
@@ -0,0 +1,39 @@
|
||||
# Edge-Level Attestations (DSSE-signed per dependency edge)
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Proof graph edge models with typed edges and a rich graph attestation service in Scanner for emitting per-edge attestation data.
|
||||
|
||||
## Implementation Details
|
||||
- **Proof Graph Edge**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Graph/ProofGraphEdge.cs` -- edge model with content-addressed ID, source/target node references, and typed semantics.
|
||||
- **Edge Types**: `ProofGraphEdgeType.cs` -- enum defining edge types: DependsOn, Supersedes, Aggregates, Produces, Consumes, etc.
|
||||
- **Proof Graph Node**: `ProofGraphNode.cs` -- node model with `ProofGraphNodeType`.
|
||||
- **Graph Service**: `InMemoryProofGraphService.cs` (with `.Mutation`, `.Queries`, `.Subgraph`) -- manages graph with per-edge operations.
|
||||
- **Content-Addressed Edge IDs**: `Identifiers/ContentAddressedIdGenerator.Graph.cs` -- generates edge IDs from source+target+type content.
|
||||
- **Graph Root Attestation**: `src/Attestor/__Libraries/StellaOps.Attestor.GraphRoot/GraphRootAttestor.cs` -- attests graph root including all edges.
|
||||
- **DSSE Signing**: Per-edge attestations are signed via `ProofChainSigner`.
|
||||
- **Note**: Scanner module (`src/Scanner/`) contains the graph attestation service that emits per-edge data; Attestor provides the models and signing.
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Add a DependsOn edge between two nodes via `InMemoryProofGraphService.Mutation` and verify edge ID is generated
|
||||
- [ ] Add edges of different types (Supersedes, Aggregates, Produces) and verify each gets a unique typed edge ID
|
||||
- [ ] Query edges by type via `InMemoryProofGraphService.Queries` and verify correct filtering
|
||||
- [ ] Sign an edge attestation via `ProofChainSigner` and verify the DSSE envelope
|
||||
- [ ] Attest the full graph root via `GraphRootAttestor` and verify it includes edge count and types
|
||||
- [ ] Remove a node and verify all connected edges are cleaned up
|
||||
- [ ] Extract a subgraph and verify only edges within the subgraph are included
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,42 @@
|
||||
# Enhanced Rekor Proof Building with Inclusion Proofs
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Full Rekor proof builder with build, validate, and inclusion proof types for transparency log verification.
|
||||
|
||||
## Implementation Details
|
||||
- **Enhanced Rekor Proof Builder**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Rekor/EnhancedRekorProofBuilder.cs` -- main builder class with partials:
|
||||
- `.Build` -- constructs Rekor proofs from transparency log entries
|
||||
- `.Validate` -- validates proof integrity
|
||||
- **Enhanced Rekor Proof**: `Rekor/EnhancedRekorProof.cs` -- proof model with inclusion proof and verification data.
|
||||
- **Rekor Inclusion Proof**: `Rekor/RekorInclusionProof.cs` -- Merkle inclusion proof for transparency log entries.
|
||||
- **Rekor Integration**: `Pipeline/RekorEntry.cs` -- Rekor entry in the proof chain pipeline.
|
||||
- **Merkle Proof Verifier**: `StellaOps.Attestor.Core/Verification/MerkleProofVerifier.cs` -- verifies Merkle inclusion proofs.
|
||||
- **Rekor Verification Service**: `StellaOps.Attestor.Core/Verification/RekorVerificationService.cs`, `IRekorVerificationService.cs` -- orchestrates Rekor verification.
|
||||
- **Offline Receipt Verifier**: `StellaOps.Attestor.Core/Verification/RekorOfflineReceiptVerifier.cs` -- verifies Rekor receipts offline.
|
||||
- **Verification Pipeline Step**: `__Libraries/StellaOps.Attestor.ProofChain/Verification/RekorInclusionVerificationStep.cs` -- pipeline step for inclusion proof verification.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.Types.Tests/Rekor/RekorInclusionProofTests.cs`, `StellaOps.Attestor.Core.Tests/Rekor/RekorReceiptTests.cs`, `__Tests/StellaOps.Attestor.Conformance.Tests/InclusionProofParityTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Build an enhanced Rekor proof via `EnhancedRekorProofBuilder.Build` from a transparency log entry and verify the proof contains an inclusion proof
|
||||
- [ ] Validate the proof via `EnhancedRekorProofBuilder.Validate` and verify it passes
|
||||
- [ ] Verify the inclusion proof via `MerkleProofVerifier` and confirm the computed root matches the checkpoint root
|
||||
- [ ] Verify a Rekor receipt offline via `RekorOfflineReceiptVerifier` using embedded inclusion proof
|
||||
- [ ] Run `RekorInclusionVerificationStep` in the verification pipeline and verify it passes for valid entries
|
||||
- [ ] Tamper with the inclusion proof sibling hashes and verify verification fails
|
||||
- [ ] Run conformance parity tests to verify inclusion proof verification matches reference implementation
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,41 @@
|
||||
# Enhanced Rekor Proof Persistence
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Enhanced Rekor proof persistence storing checkpoint signatures, checkpoint notes, entry body hashes, and verification timestamps for complete offline verification without Rekor connectivity.
|
||||
|
||||
## Implementation Details
|
||||
- **Rekor Entry Entity**: `src/Attestor/__Libraries/StellaOps.Attestor.Persistence/Entities/RekorEntryEntity.cs` -- database entity storing Rekor entries with inclusion proofs, checkpoint data, and verification timestamps.
|
||||
- **DSSE Envelope Entity**: `Entities/DsseEnvelopeEntity.cs` -- persists signed DSSE envelopes associated with Rekor entries.
|
||||
- **Spine Entity**: `Entities/SpineEntity.cs` -- persists proof spine data.
|
||||
- **Trust Anchor Entity**: `Entities/TrustAnchorEntity.cs` -- stores trust anchor data for offline verification.
|
||||
- **Proof Chain DB Context**: `ProofChainDbContext.cs` -- EF Core DbContext for proof chain persistence.
|
||||
- **Repositories**: `Repositories/IProofChainRepository.cs` -- repository interface. `IVerdictLedgerRepository.cs` -- verdict ledger repository.
|
||||
- **Trust Anchor Matcher**: `Services/TrustAnchorMatcher.cs` -- matches entries against persisted trust anchors.
|
||||
- **Rekor Checkpoint Store**: `src/Attestor/StellaOps.Attestor/StellaOps.Attestor.Storage/Rekor/PostgresRekorCheckpointStore.cs` -- PostgreSQL checkpoint persistence.
|
||||
- **Offline Receipt Verifier**: `StellaOps.Attestor.Core/Verification/RekorOfflineReceiptVerifier.cs` -- verifies receipts using persisted data.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.Persistence.Tests/ProofChainDbContextTests.cs`, `TrustAnchorMatcherTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Persist a Rekor entry with inclusion proof and checkpoint via `RekorEntryEntity` and retrieve it, verifying all fields
|
||||
- [ ] Persist a DSSE envelope via `DsseEnvelopeEntity` and verify association with its Rekor entry
|
||||
- [ ] Store a trust anchor via `TrustAnchorEntity` and verify `TrustAnchorMatcher` can match entries against it
|
||||
- [ ] Store checkpoint signatures via `PostgresRekorCheckpointStore` and retrieve them for offline verification
|
||||
- [ ] Verify a Rekor receipt offline using `RekorOfflineReceiptVerifier` with only persisted data (no network)
|
||||
- [ ] Persist a spine entity and verify it links to its constituent proof entries
|
||||
- [ ] Verify `ProofChainDbContext` migrations create correct schema with all required tables and indexes
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,40 @@
|
||||
# Evidence Chain / Proof Trail for Scores
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Score receipts and determinization system provide evidence trails with canonical input hashes, transform IDs, and policy digests. The ProofChain library supports full evidence chain construction.
|
||||
|
||||
## Implementation Details
|
||||
- **Verification Receipt**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Receipts/VerificationReceipt.cs` -- receipt capturing the verification outcome with evidence chain. `VerificationCheck.cs` -- individual check result. `VerificationContext.cs` -- context for verification. `VerificationResult.cs` -- overall result.
|
||||
- **Verdict Receipt Payload**: `Statements/VerdictReceiptPayload.cs` -- payload with canonical input hash, policy digest, and transform ID for deterministic score replay.
|
||||
- **Verdict Decision/Inputs/Outputs**: `Statements/VerdictDecision.cs`, `VerdictInputs.cs`, `VerdictOutputs.cs` -- capture the complete decision chain from inputs through to outputs.
|
||||
- **Evidence Statement**: `Statements/EvidenceStatement.cs` -- wraps evidence as in-toto statement. `Predicates/EvidencePredicate.cs` -- evidence predicate.
|
||||
- **Reasoning Statement**: `Statements/ReasoningStatement.cs` -- wraps reasoning as in-toto statement. `Predicates/ReasoningPredicate.cs` -- reasoning predicate.
|
||||
- **Evidence Summary**: `Generators/EvidenceSummary.cs` -- aggregated evidence summary with per-source scoring.
|
||||
- **Proof Graph**: `Graph/InMemoryProofGraphService.cs` -- links evidence nodes to verdict nodes via graph edges.
|
||||
- **Receipt Generator**: `Receipts/IReceiptGenerator.cs` -- interface for generating verification receipts.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/Statements/InTotoStatementSnapshotTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Generate a `VerdictReceiptPayload` with canonical input hash and policy digest, then verify the payload captures the complete evidence chain
|
||||
- [ ] Create an evidence trail: Evidence -> Reasoning -> Verdict via in-toto statements and verify each statement references its predecessor
|
||||
- [ ] Verify the canonical input hash in the receipt matches SHA-256 of the canonicalized inputs
|
||||
- [ ] Create a `VerificationReceipt` with multiple `VerificationCheck` entries and verify all checks are captured
|
||||
- [ ] Replay a score using the `VerdictReceiptPayload` (same inputs + same policy) and verify identical output
|
||||
- [ ] Link evidence, reasoning, and verdict nodes in the proof graph and verify the path is traversable
|
||||
- [ ] Generate an `EvidenceSummary` from multiple evidence sources and verify per-source scores are captured
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,47 @@
|
||||
# Evidence Coverage Score for AI Gating
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
The concept of gating AI output behind evidence quality exists via the AIAuthorityClassifier which scores explanation, remediation, VEX draft, and policy draft quality. The specific UX badge component and coverage scoring service described in the advisory are not implemented as standalone features.
|
||||
|
||||
## What's Implemented
|
||||
- **AI Authority Classifier**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Predicates/AI/AIAuthorityClassifier.cs` -- classifies AI artifacts by authority level (Suggestion, EvidenceBacked, AuthorityThreshold).
|
||||
- **AI Authority Scoring**: `AI/AIAuthorityClassifier.Explanation.cs`, `.ExplanationScore.cs`, `.Remediation.cs`, `.RemediationScore.cs`, `.VexDraft.cs`, `.VexDraftScore.cs`, `.PolicyDraft.cs`, `.PolicyDraftScore.cs` -- per-artifact-type scoring.
|
||||
- **AI Authority Thresholds**: `AI/AIAuthorityThresholds.cs` -- configurable thresholds for authority classification.
|
||||
- **AI Artifact Verification Step**: `Verification/AIArtifactVerificationStep.cs` (with `.Classify`, `.Execute`, `.Helpers`, `.Summary`, `.VerifyParse`, `.VerifyValidation`) -- verification step for AI-generated artifacts.
|
||||
- **AI Artifact Authority**: `AI/AIArtifactAuthority.cs` -- authority level model.
|
||||
- **AI Authority Classification Result**: `AI/AIAuthorityClassificationResult.cs` -- classification result model.
|
||||
|
||||
## What's Missing
|
||||
- **Evidence coverage scoring service**: No dedicated service that computes an overall evidence coverage score (0-100%) across all evidence types for a given subject.
|
||||
- **Coverage badge UX component**: No frontend badge component showing coverage level (e.g., green/yellow/red) based on evidence completeness.
|
||||
- **AI gating policy**: No policy that blocks AI outputs below a configurable coverage threshold from being promoted to verdicts.
|
||||
- **Coverage gap analysis**: No analysis identifying which evidence types are missing (e.g., "reachability evidence missing" or "no binary analysis") for a subject.
|
||||
- **Coverage scoring predicates**: No predicate type for attestable coverage scores.
|
||||
|
||||
## Implementation Plan
|
||||
- Create `EvidenceCoverageScorer` service computing coverage across all evidence types
|
||||
- Define coverage dimensions (reachability, binary analysis, SBOM completeness, VEX coverage, provenance)
|
||||
- Implement AI gating policy that requires minimum coverage before promoting AI outputs
|
||||
- Build coverage gap analysis reporting missing evidence types
|
||||
- Create coverage score predicate type for attestation
|
||||
- Add UX badge component with color-coded coverage level
|
||||
- Add tests for coverage scoring, gap analysis, and AI gating
|
||||
|
||||
## Related Documentation
|
||||
- Source: See feature catalog
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,41 @@
|
||||
# Evidence-First Security with DSSE Envelopes
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
All security findings are wrapped in DSSE envelopes; SmartDiff results are attested as delta verdicts and published to OCI registries.
|
||||
|
||||
## Implementation Details
|
||||
- **DSSE Envelope Signing**: Multiple signing layers across Attestor:
|
||||
- `src/Attestor/StellaOps.Attestor.Envelope/EnvelopeSignatureService.cs` -- core envelope signing
|
||||
- `__Libraries/StellaOps.Attestor.ProofChain/Signing/ProofChainSigner.cs` -- proof chain signing
|
||||
- `StellaOps.Attestor.Core/Signing/DsseSigningService.cs` -- core attestation signing
|
||||
- **Delta Verdict Attestation**: `Predicates/DeltaVerdictPredicate.cs` -- delta verdict wrapped in DSSE. `Statements/DeltaVerdictStatement.cs` -- in-toto statement.
|
||||
- **OCI Publication**: `src/Attestor/__Libraries/StellaOps.Attestor.Oci/Services/` -- `IOciAttestationAttacher.cs`, `OrasAttestationAttacher.cs` -- attaches DSSE-signed attestations to OCI images. `ISbomOciPublisher.cs`, `SbomOciPublisher.cs` -- publishes SBOMs to OCI.
|
||||
- **Trust Verdict OCI**: `__Libraries/StellaOps.Attestor.TrustVerdict/Oci/TrustVerdictOciAttacher.cs` (with `.Attach`, `.FetchList`) -- attaches trust verdicts to OCI artifacts.
|
||||
- **Evidence Predicate**: `Predicates/EvidencePredicate.cs` -- wraps security evidence in attestable predicate.
|
||||
- **Smart Diff**: `__Tests/StellaOps.Attestor.Types.Tests/SmartDiffSchemaValidationTests.cs` -- validates smart diff schema.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.Oci.Tests/OrasAttestationAttacherTests.cs`, `SbomOciPublisherTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Wrap a security finding in a DSSE envelope via `ProofChainSigner` and verify the evidence predicate is signed
|
||||
- [ ] Create a delta verdict from SmartDiff results and sign it as a DSSE envelope
|
||||
- [ ] Publish the signed delta verdict to an OCI registry via `OrasAttestationAttacher` and verify it is attached as a referrer
|
||||
- [ ] Publish an SBOM to OCI via `SbomOciPublisher` and verify the DSSE signature is attached
|
||||
- [ ] Attach a trust verdict to an OCI image via `TrustVerdictOciAttacher` and verify the referrer list includes it
|
||||
- [ ] Fetch the list of attestations for an OCI image via `TrustVerdictOciAttacher.FetchList` and verify all attached attestations are returned
|
||||
- [ ] Verify a retrieved DSSE envelope from OCI validates correctly
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
38
docs/features/checked/attestor/evidence-provenance-chip.md
Normal file
38
docs/features/checked/attestor/evidence-provenance-chip.md
Normal file
@@ -0,0 +1,38 @@
|
||||
# Evidence Provenance Chip (DSSE/Receipt with Export)
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
The advisory proposed a ProvenanceChipComponent showing Signed/Verified/Logged states with DSSE envelope viewing and export. The LineageProvenanceChipsComponent implements this concept as a standalone Angular component displaying attestation status, signature verification status, and Rekor transparency log links with expandable details. The backend DSSE and Rekor infrastructure is fully built in the Attestor module.
|
||||
|
||||
## Implementation Details
|
||||
- **Verification Receipt**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Receipts/VerificationReceipt.cs` -- receipt model with signed/verified/logged status. `VerificationCheck.cs`, `VerificationContext.cs`, `VerificationResult.cs`.
|
||||
- **Signature Verification**: `Signing/SignatureVerificationResult.cs` -- result of DSSE signature verification. `ProofChainSigner.Verification.cs` -- verification logic.
|
||||
- **Rekor Receipt**: `StellaOps.Attestor.Core/Rekor/RekorReceipt.cs` -- Rekor transparency log receipt with entry ID and inclusion proof.
|
||||
- **Evidence Pack Export**: `__Libraries/StellaOps.Attestor.EvidencePack/ReleaseEvidencePackBuilder.cs` -- builds exportable evidence packs. `ReleaseEvidencePackSerializer.cs` -- serialization.
|
||||
- **Transparency Status**: `StellaOps.Attestor.Core/Transparency/TransparencyStatus.cs`, `TransparencyStatusProvider.cs` -- provides transparency log status. `TransparencyWitnessObservation.cs` -- witness observation records.
|
||||
- **Frontend**: The Angular `LineageProvenanceChipsComponent` in `src/Web/` consumes this backend data.
|
||||
- **Tests**: `StellaOps.Attestor.Core.Tests/Transparency/TransparencyStatusProviderTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Create a `VerificationReceipt` with signed, verified, and logged statuses and verify all three states are captured
|
||||
- [ ] Verify DSSE signature via `ProofChainSigner.Verification` and confirm `SignatureVerificationResult` indicates valid
|
||||
- [ ] Retrieve `TransparencyStatus` via `TransparencyStatusProvider` for a logged attestation and verify it shows the Rekor entry ID
|
||||
- [ ] Build an evidence pack via `ReleaseEvidencePackBuilder` and export it via `ReleaseEvidencePackSerializer`
|
||||
- [ ] Verify the exported pack contains the DSSE envelope, verification receipt, and Rekor receipt
|
||||
- [ ] Create a `TransparencyWitnessObservation` and verify it captures the observation timestamp and witness identity
|
||||
- [ ] Verify the API endpoint returns provenance chip data consumable by the frontend component
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,46 @@
|
||||
# Evidence Subgraph UI Visualization
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Backend proof graph model is implemented (nodes, edges, subgraphs, paths). Evidence panel e2e tests exist. Full frontend visualization component status unclear from source search alone.
|
||||
|
||||
## What's Implemented
|
||||
- **Proof Graph Model**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Graph/InMemoryProofGraphService.cs` (with `.Mutation`, `.Queries`, `.Subgraph`) -- graph service with node/edge management, subgraph extraction, and path queries.
|
||||
- **Graph Node**: `Graph/ProofGraphNode.cs` -- node model with type and metadata.
|
||||
- **Graph Edge**: `Graph/ProofGraphEdge.cs` -- edge model with type linking nodes.
|
||||
- **Graph Node/Edge Types**: `Graph/ProofGraphNodeType.cs`, `Graph/ProofGraphEdgeType.cs` -- typed node and edge enumerations.
|
||||
- **Graph Path**: `Graph/ProofGraphPath.cs` -- path through the proof graph.
|
||||
- **Graph Subgraph**: `Graph/ProofGraphSubgraph.cs` -- extracted subgraph for a specific subject.
|
||||
|
||||
## What's Missing
|
||||
- **Frontend graph visualization component**: No Angular component rendering the proof graph as an interactive visualization (nodes as circles/rectangles, edges as arrows).
|
||||
- **Interactive exploration**: No click-to-expand, zoom, pan, or filter functionality for graph navigation in the UI.
|
||||
- **Subgraph API endpoint**: The WebService controllers do not expose a dedicated endpoint for fetching proof graph subgraphs for a given subject.
|
||||
- **Graph layout algorithm**: No force-directed or hierarchical layout algorithm for rendering the graph in 2D.
|
||||
- **Evidence node detail panel**: No side panel showing node details (attestation content, verification status) when a node is selected.
|
||||
|
||||
## Implementation Plan
|
||||
- Add a REST endpoint in `ProofChainController` for subgraph queries by subject
|
||||
- Create an Angular component using a graph visualization library (e.g., D3.js or Cytoscape.js)
|
||||
- Implement interactive exploration (zoom, pan, click-to-expand, filtering by node/edge type)
|
||||
- Add a node detail panel showing attestation content and verification status
|
||||
- Implement graph layout algorithm (hierarchical for proof chains, force-directed for evidence graphs)
|
||||
- Add e2e tests for graph rendering and interaction
|
||||
|
||||
## Related Documentation
|
||||
- Source: See feature catalog
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
44
docs/features/checked/attestor/evidence-types.md
Normal file
44
docs/features/checked/attestor/evidence-types.md
Normal file
@@ -0,0 +1,44 @@
|
||||
# Evidence types (SBOM_SLICE, VEX_DOC, CALLSTACK_SLICE, REACHABILITY_PROOF, etc.)
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Comprehensive evidence type system in ProofChain library and UI evidence panel components covering all listed evidence types.
|
||||
|
||||
## Implementation Details
|
||||
- **Evidence Predicate**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Predicates/EvidencePredicate.cs` -- base evidence predicate type.
|
||||
- **Evidence Statement**: `Statements/EvidenceStatement.cs` -- wraps evidence as in-toto statement.
|
||||
- **Audit Artifact Types**: `Audit/AuditArtifactTypes.cs` -- defines all auditable evidence artifact types.
|
||||
- **Specific Evidence Types**:
|
||||
- SBOM: `SbomLinkageStatement.cs`, `SbomLinkagePayload.cs`, `SbomDescriptor.cs`, `SbomReference.cs`
|
||||
- VEX: `VexVerdictStatement.cs`, `VexPredicate.cs`, `VexAttestationPredicate.cs`
|
||||
- Reachability: `ReachabilityWitnessStatement.cs`, `ReachabilityWitnessPayload.cs`
|
||||
- Binary: `BinaryMicroWitnessStatement.cs`, `BinaryFingerprintEvidencePredicate.cs`
|
||||
- Uncertainty: `UncertaintyStatement.cs`, `UncertaintyPayload.cs`, `UncertaintyEvidence.cs`
|
||||
- Drift: `ReachabilityDriftStatement.cs`, `ReachabilityDriftPayload.cs`
|
||||
- **Predicate Types**: `Predicates/` -- 93 predicate types covering all evidence categories.
|
||||
- **Statement Types**: `Statements/` -- 49 statement types wrapping predicates as in-toto statements.
|
||||
- **Media Types**: `MediaTypes/AIArtifactMediaTypes.cs` -- content-type constants for AI evidence.
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Create an `EvidenceStatement` for each major evidence type (SBOM, VEX, Reachability, Binary, Uncertainty) and verify correct predicate type URIs
|
||||
- [ ] Verify `AuditArtifactTypes` contains entries for all supported evidence types
|
||||
- [ ] Create an SBOM evidence slice via `SbomLinkageStatement` and verify it links to an SBOM descriptor
|
||||
- [ ] Create a VEX evidence document via `VexVerdictStatement` and verify it captures VEX status
|
||||
- [ ] Create a reachability proof via `ReachabilityWitnessStatement` and verify call-stack paths
|
||||
- [ ] Create binary evidence via `BinaryMicroWitnessStatement` with function-level details
|
||||
- [ ] Create uncertainty evidence via `UncertaintyStatement` with budget information
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
41
docs/features/checked/attestor/explanation-graph.md
Normal file
41
docs/features/checked/attestor/explanation-graph.md
Normal file
@@ -0,0 +1,41 @@
|
||||
# Explanation Graph (Verdict -> Reasoning -> Evidence)
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Proof graph provides the structural backbone linking verdicts to reasoning paths to evidence nodes. Edge explanations in ReachGraph and explainability KPIs in Metrics provide additional layers.
|
||||
|
||||
## Implementation Details
|
||||
- **Proof Graph**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Graph/InMemoryProofGraphService.cs` (with `.Mutation`, `.Queries`, `.Subgraph`) -- graph linking Verdict -> Reasoning -> Evidence nodes.
|
||||
- **Node Types**: `ProofGraphNodeType.cs` -- Evidence, Verdict, Policy, Artifact node types.
|
||||
- **Edge Types**: `ProofGraphEdgeType.cs` -- relationship types (DependsOn, Produces, etc.).
|
||||
- **Reasoning Predicate**: `Predicates/ReasoningPredicate.cs` -- reasoning node content. `Statements/ReasoningStatement.cs` -- in-toto wrapper.
|
||||
- **Evidence Predicate**: `Predicates/EvidencePredicate.cs` -- evidence node content. `Statements/EvidenceStatement.cs` -- in-toto wrapper.
|
||||
- **Verdict Summary**: `Predicates/VerdictSummary.cs` -- verdict node content.
|
||||
- **Reasoning ID**: `Identifiers/ReasoningId.cs` -- content-addressed ID for reasoning nodes.
|
||||
- **Evidence ID**: `Identifiers/EvidenceId.cs` -- content-addressed ID for evidence nodes.
|
||||
- **Graph Path**: `Graph/ProofGraphPath.cs` -- traversal path through explanation graph.
|
||||
- **Subgraph Extraction**: `Graph/ProofGraphSubgraph.cs` -- extract relevant subgraph for a specific verdict.
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Create a 3-layer explanation graph: Verdict -> Reasoning -> Evidence and verify traversal from verdict to evidence
|
||||
- [ ] Query the graph for all reasoning nodes linked to a specific verdict and verify correct results
|
||||
- [ ] Extract a subgraph rooted at a verdict and verify it contains all reasoning and evidence descendants
|
||||
- [ ] Create a verdict with multiple reasoning paths and verify both paths are traversable
|
||||
- [ ] Verify `ReasoningId` content-addressing: same reasoning content produces the same ID
|
||||
- [ ] Create a `ProofGraphPath` from verdict to evidence and verify path length and node types
|
||||
- [ ] Add a new evidence node to an existing reasoning node and verify the graph updates correctly
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,48 @@
|
||||
# Field-Level Ownership Map for Receipts and Bundles
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Rekor entry and receipt models exist with structured fields, but a formal field-level ownership map document (checklist page) linking fields to specific module responsibilities was not found as a standalone artifact.
|
||||
|
||||
## What's Implemented
|
||||
- **Verification Receipt**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Receipts/VerificationReceipt.cs` -- receipt model with structured fields.
|
||||
- **Verification Check**: `Receipts/VerificationCheck.cs` -- individual verification check within a receipt.
|
||||
- **Verification Context**: `Receipts/VerificationContext.cs` -- context for verification operations.
|
||||
- **Verification Result**: `Receipts/VerificationResult.cs` -- verification outcome.
|
||||
- **Sigstore Bundle**: `__Libraries/StellaOps.Attestor.Bundle/Models/SigstoreBundle.cs` -- Sigstore bundle model.
|
||||
- **Verification Material**: `Bundle/Models/VerificationMaterial.cs` -- material used for verification.
|
||||
- **Transparency Log Entry**: `Bundle/Models/TransparencyLogEntry.cs` -- log entry within bundles.
|
||||
- **Rekor Receipt**: `StellaOps.Attestor.Core/Rekor/RekorReceipt.cs` -- Rekor receipt model.
|
||||
|
||||
## What's Missing
|
||||
- **Field-level ownership map document**: No machine-readable or human-readable document mapping each field in receipts/bundles to the responsible module (e.g., "signature" -> Signing module, "inclusion_proof" -> Rekor module).
|
||||
- **Ownership validation**: No automated check that each field in a receipt/bundle is populated by its designated owner module.
|
||||
- **Ownership-aware serialization**: No serialization that tracks which module wrote each field for audit purposes.
|
||||
- **Ownership documentation generator**: No tool to auto-generate ownership documentation from code annotations.
|
||||
- **Cross-module field conflict detection**: No mechanism to detect when two modules attempt to populate the same field.
|
||||
|
||||
## Implementation Plan
|
||||
- Define a field-level ownership schema mapping fields to module responsibilities
|
||||
- Annotate receipt/bundle models with `[OwnedBy("ModuleName")]` attributes
|
||||
- Create a documentation generator that extracts ownership annotations into a readable map
|
||||
- Implement ownership validation ensuring fields are only populated by designated modules
|
||||
- Add conflict detection for duplicate field population
|
||||
- Add tests for ownership validation and documentation generation
|
||||
|
||||
## Related Documentation
|
||||
- Source: See feature catalog
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
42
docs/features/checked/attestor/fixchain-attestation.md
Normal file
42
docs/features/checked/attestor/fixchain-attestation.md
Normal file
@@ -0,0 +1,42 @@
|
||||
# FixChain Attestation (Backport Proof)
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
FixChain provides attestation-based proof that a backport or fix has been applied, with validation and policy gate integration.
|
||||
|
||||
## Implementation Details
|
||||
- **FixChain Attestation Service**: `src/Attestor/__Libraries/StellaOps.Attestor.FixChain/FixChainAttestationService.cs` -- creates fix chain attestations.
|
||||
- **FixChain Models**: `FixChainModels.cs` -- core models for fix chain data.
|
||||
- **FixChain Predicate**: `FixChainPredicate.cs` -- attestable predicate for fix chain proof.
|
||||
- **FixChain Statement Builder**: `FixChainStatementBuilder.cs` -- builds in-toto statements for fix chain attestations.
|
||||
- **FixChain Validator**: `FixChainValidator.cs` -- validates fix chain attestations.
|
||||
- **DI Registration**: `ServiceCollectionExtensions.cs` -- registers fix chain services.
|
||||
- **Fix Status Info**: `__Libraries/StellaOps.Attestor.ProofChain/Predicates/FixStatusInfo.cs` -- fix status tracking in proof chain.
|
||||
- **Tests**:
|
||||
- `__Libraries/__Tests/StellaOps.Attestor.FixChain.Tests/FixChainPredicateTests.cs`, `FixChainStatementBuilderTests.cs`, `FixChainValidatorTests.cs`
|
||||
- `__Tests/StellaOps.Attestor.FixChain.Tests/Unit/FixChainAttestationServiceTests.cs`, `FixChainStatementBuilderTests.cs`, `FixChainValidatorTests.cs`
|
||||
- `__Tests/StellaOps.Attestor.FixChain.Tests/Integration/FixChainAttestationIntegrationTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Create a fix chain attestation via `FixChainAttestationService` for a backported security patch and verify the attestation contains patch details
|
||||
- [ ] Build an in-toto statement via `FixChainStatementBuilder` and verify correct predicate type
|
||||
- [ ] Validate the fix chain attestation via `FixChainValidator` and verify it passes for a valid fix
|
||||
- [ ] Create a fix chain with invalid data (e.g., missing patch reference) and verify `FixChainValidator` rejects it
|
||||
- [ ] Verify `FixStatusInfo` in the proof chain tracks fix application status
|
||||
- [ ] Sign the fix chain statement and verify DSSE envelope integrity
|
||||
- [ ] Run integration tests to verify end-to-end fix chain attestation flow
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
40
docs/features/checked/attestor/four-layer-architecture.md
Normal file
40
docs/features/checked/attestor/four-layer-architecture.md
Normal file
@@ -0,0 +1,40 @@
|
||||
# Four-Layer Architecture (Edge, Control Plane, Evidence Plane, Data Plane)
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
The described four-layer architecture is realized with distinct modules for edge routing, control plane (policy/authority/attestor/scheduler), evidence plane (scanner/excititor/concelier), and data plane (workers/task runners).
|
||||
|
||||
## Implementation Details
|
||||
- **Attestor as Control Plane**: `src/Attestor/StellaOps.Attestor/StellaOps.Attestor.WebService/` -- HTTP endpoints:
|
||||
- `Controllers/ProofsController.cs`, `VerifyController.cs`, `BundlesController.cs`, `ChainController.cs`, `AnchorsController.cs`, `VerdictController.cs` -- control plane APIs
|
||||
- `Endpoints/VerdictEndpoints.cs`, `WatchlistEndpoints.cs` -- minimal API endpoints
|
||||
- **Evidence Plane Integration**: `__Libraries/StellaOps.Attestor.ProofChain/` -- evidence construction with 93 predicate types, 49 statement types
|
||||
- **Verification Pipeline**: `__Libraries/StellaOps.Attestor.ProofChain/Verification/VerificationPipeline.cs` (with `.Verify`) -- multi-step verification pipeline
|
||||
- **Submission Service**: `StellaOps.Attestor.Core/Submission/IAttestorSubmissionService.cs`, `AttestorSubmissionValidator.cs` -- validates and routes submissions
|
||||
- **Queue (Data Plane)**: `StellaOps.Attestor.Core/Queue/IRekorSubmissionQueue.cs` -- durable queue for asynchronous processing
|
||||
- **Background Services**: `StellaOps.Attestor.Core/Rekor/RekorSyncBackgroundService.cs` -- background processing
|
||||
- **Composition**: `StellaOps.Attestor.WebService/AttestorWebServiceComposition.cs` -- DI composition root
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Submit an attestation via `ProofsController` and verify it flows through the submission pipeline
|
||||
- [ ] Verify an attestation via `VerifyController` and confirm the verification pipeline executes all steps
|
||||
- [ ] Query attestation bundles via `BundlesController` and verify correct responses
|
||||
- [ ] Query attestation chains via `ChainController` and verify traversal works
|
||||
- [ ] Submit a batch of attestations and verify they are queued for Rekor publication
|
||||
- [ ] Verify the background sync service processes queued items
|
||||
- [ ] Verify `AttestorSubmissionValidator` rejects invalid submissions with appropriate error messages
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,45 @@
|
||||
# Four-Tier Backport Detection System
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
A four-tier evidence collection system for backport detection: Tier 1 (Distro Advisories, 0.98 confidence), Tier 2 (Changelog Mentions, 0.80), Tier 3 (Patch Headers + HunkSig, 0.85-0.90), Tier 4 (Binary Fingerprints, 0.55-0.85). BackportProofService orchestrates queries across all tiers and combines evidence into cryptographic ProofBlobs.
|
||||
|
||||
## Implementation Details
|
||||
- **BackportProofGenerator**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Generators/BackportProofGenerator.cs` -- orchestrator for multi-tier detection with partials:
|
||||
- `.Tier1` -- Distro advisory matching (0.98 confidence)
|
||||
- `.Tier2` -- Advisory-level evidence (0.90-0.95)
|
||||
- `.Tier3` -- Changelog/patch header matching (0.80-0.85)
|
||||
- `.Tier3Signature` -- HunkSig binary signature matching
|
||||
- `.Tier4` -- Binary fingerprint comparison (0.55-0.85)
|
||||
- `.Confidence` -- confidence scoring with multi-source bonus
|
||||
- `.CombineEvidence` -- evidence aggregation across tiers
|
||||
- `.Status` -- detection status tracking
|
||||
- `.VulnerableUnknown` -- unknown vulnerability handling
|
||||
- **Evidence Summary**: `Generators/EvidenceSummary.cs` -- aggregated evidence from all tiers.
|
||||
- **Proof Blob**: `Models/ProofBlob.cs` -- cryptographic proof container with SHA-256 hash.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/BackportProofGeneratorTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Run Tier 1 detection with a known distro advisory match and verify 0.98 confidence
|
||||
- [ ] Run Tier 2 detection with changelog evidence and verify 0.80 confidence
|
||||
- [ ] Run Tier 3 detection with patch header matching and verify 0.85-0.90 confidence
|
||||
- [ ] Run Tier 3 Signature detection with HunkSig binary comparison and verify confidence range
|
||||
- [ ] Run Tier 4 detection with binary fingerprint comparison and verify 0.55-0.85 confidence
|
||||
- [ ] Run all four tiers and verify `CombineEvidence` produces an aggregated result with multi-source bonus
|
||||
- [ ] Verify the combined evidence is wrapped in a cryptographic `ProofBlob` with valid SHA-256 hash
|
||||
- [ ] Test with a package having no backport evidence across all tiers and verify appropriate `VulnerableUnknown` handling
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,43 @@
|
||||
# Function-Level Reachability for VEX Decisions
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Multi-language call graph extraction (binary, Java, Python, Node, PHP, Ruby, JavaScript) is implemented with function-level evidence models (MicroWitness predicates, call path nodes, reachability witness payloads).
|
||||
|
||||
## Implementation Details
|
||||
- **MicroWitness Predicates**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Predicates/` -- function-level evidence:
|
||||
- `BinaryMicroWitnessPredicate.cs` -- complete micro-witness with binary, CVE, and function refs
|
||||
- `MicroWitnessBinaryRef.cs` -- binary reference
|
||||
- `MicroWitnessCveRef.cs` -- CVE reference
|
||||
- `MicroWitnessFunctionEvidence.cs` -- function-level evidence with call-stack position
|
||||
- `MicroWitnessSbomRef.cs` -- SBOM component cross-reference
|
||||
- `MicroWitnessTooling.cs` -- analysis tool metadata
|
||||
- `MicroWitnessVerdicts.cs` -- function-level verdicts
|
||||
- **Reachability Witness**: `Statements/ReachabilityWitnessPayload.cs` (with `.Path`) -- call paths. `ReachabilityWitnessStatement.cs` -- in-toto wrapper.
|
||||
- **Call Path Nodes**: `Statements/WitnessCallPathNode.cs`, `WitnessPathNode.cs` -- path nodes with function details.
|
||||
- **VEX Integration**: `Generators/VexProofIntegrator.cs` (with `.Helpers`, `.Metadata`) -- integrates reachability evidence into VEX decisions. `VexVerdictProofPayload.cs` -- combined VEX + reachability proof.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/BinaryMicroWitnessPredicateTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Create a `BinaryMicroWitnessPredicate` with function evidence showing a vulnerable function is reachable and verify the micro-witness is well-formed
|
||||
- [ ] Create function evidence with `MicroWitnessFunctionEvidence` at different call-stack depths and verify depth tracking
|
||||
- [ ] Link micro-witness evidence to a VEX decision via `VexProofIntegrator` with status "not_affected" (function unreachable) and verify the proof payload
|
||||
- [ ] Link micro-witness evidence to a VEX decision with status "affected" (function reachable) and verify
|
||||
- [ ] Create witnesses from multiple language call graphs and verify `MicroWitnessTooling` captures per-language analysis tools
|
||||
- [ ] Verify `MicroWitnessSbomRef` correctly links function evidence to SBOM component entries
|
||||
- [ ] Create `MicroWitnessVerdicts` for multiple functions and verify per-function reachability verdicts
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,41 @@
|
||||
# Graph Node/Edge Model with Overlays
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Graph module has core node/edge model with overlay services, query APIs, and analytics. ProofChain library in Attestor also maintains its own graph node/edge/subgraph types.
|
||||
|
||||
## Implementation Details
|
||||
- **Proof Graph Nodes**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Graph/ProofGraphNode.cs` -- typed graph node (Evidence, Verdict, Policy, Artifact) with content-addressed ID and metadata.
|
||||
- **Proof Graph Edges**: `Graph/ProofGraphEdge.cs` -- directed edge between nodes with `ProofGraphEdgeType.cs` (DependsOn, Produces, Validates, etc.).
|
||||
- **Node Types**: `Graph/ProofGraphNodeType.cs` -- enum: Evidence, Verdict, Policy, Artifact.
|
||||
- **Edge Types**: `Graph/ProofGraphEdgeType.cs` -- enum defining relationship semantics between graph nodes.
|
||||
- **In-Memory Graph Service**: `Graph/InMemoryProofGraphService.cs` (with `.Mutation`, `.Queries`, `.Subgraph`) -- full graph service supporting node/edge CRUD, traversal queries, and subgraph extraction.
|
||||
- **Subgraph Extraction**: `Graph/ProofGraphSubgraph.cs` -- extracts a subgraph rooted at a specific node (e.g., all evidence for a verdict).
|
||||
- **Graph Paths**: `Graph/ProofGraphPath.cs` -- represents a traversal path through the graph with ordered node sequence.
|
||||
- **Graph Root Attestor**: `__Libraries/StellaOps.Attestor.GraphRoot/GraphRootAttestor.cs` -- attests Merkle roots over graph structures. `IGraphRootAttestor.cs` -- interface.
|
||||
- **Graph Types**: `__Libraries/StellaOps.Attestor.GraphRoot/GraphType.cs` -- supported graph types (ResolvedExecutionGraph, ReachabilityGraph, DependencyGraph, ProofSpine, EvidenceGraph).
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/` -- graph service tests.
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Create nodes of each `ProofGraphNodeType` (Evidence, Verdict, Policy, Artifact) via `InMemoryProofGraphService` and verify they are retrievable by ID
|
||||
- [ ] Add edges of different `ProofGraphEdgeType` between nodes and verify edge traversal returns correct neighbors
|
||||
- [ ] Build a Verdict -> Reasoning -> Evidence chain and extract a `ProofGraphSubgraph` rooted at the verdict; verify all descendants are included
|
||||
- [ ] Query `ProofGraphPath` from a verdict to a leaf evidence node and verify path length and node type ordering
|
||||
- [ ] Add overlay edges (e.g., cross-linking two evidence nodes) and verify the mutation is reflected in subsequent queries
|
||||
- [ ] Delete a node via `.Mutation` and verify cascading edge removal
|
||||
- [ ] Verify content-addressed node IDs: adding two nodes with identical content produces the same ID
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
41
docs/features/checked/attestor/graph-revision-id.md
Normal file
41
docs/features/checked/attestor/graph-revision-id.md
Normal file
@@ -0,0 +1,41 @@
|
||||
# Graph Revision ID (Merkle root over SBOM + edges + policies + tool versions)
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Content-addressed graph revision IDs and Merkle root computation are implemented via the GraphRoot library with dedicated attestor, models, and SHA-256-based Merkle root computation.
|
||||
|
||||
## Implementation Details
|
||||
- **Merkle Root Computer**: `src/Attestor/__Libraries/StellaOps.Attestor.GraphRoot/Sha256MerkleRootComputer.cs` -- computes SHA-256 Merkle roots over sorted leaf hashes (SBOM components, edges, policies, tool versions). Implements `IMerkleRootComputer.cs`.
|
||||
- **Graph Root Attestor**: `GraphRootAttestor.cs` -- creates DSSE-signed in-toto attestations of computed Merkle roots. Implements `IGraphRootAttestor.cs`.
|
||||
- **Graph Root Predicate**: `Models/GraphRootPredicate.cs` -- in-toto predicate containing the Merkle root hash, graph type, leaf count, and computation timestamp.
|
||||
- **Attestation Request**: `Models/GraphRootAttestationRequest.cs` -- request model specifying which graph type and leaves to include.
|
||||
- **Attestation Result**: `Models/GraphRootResults.cs` -- result containing the signed attestation envelope and Merkle root.
|
||||
- **Graph Type**: `GraphType.cs` -- enum: ResolvedExecutionGraph, ReachabilityGraph, DependencyGraph, ProofSpine, EvidenceGraph.
|
||||
- **Options**: `GraphRootAttestorOptions.cs` -- configuration for signing key, predicate type URI.
|
||||
- **DI Registration**: `GraphRootServiceCollectionExtensions.cs` -- registers graph root services.
|
||||
- **Content-Addressed IDs**: `__Libraries/StellaOps.Attestor.ProofChain/Identifiers/ContentAddressedIdGenerator.Graph.cs` -- generates graph-scoped content-addressed IDs.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.GraphRoot.Tests/`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Compute a Merkle root via `Sha256MerkleRootComputer` over a set of SBOM component hashes and verify the root is deterministic (same inputs = same root)
|
||||
- [ ] Change one leaf hash and verify the Merkle root changes
|
||||
- [ ] Create a `GraphRootAttestationRequest` for a `ReachabilityGraph` and verify `GraphRootAttestor` produces a signed DSSE envelope with the correct predicate type
|
||||
- [ ] Verify `GraphRootPredicate` contains the expected Merkle root, leaf count, and graph type
|
||||
- [ ] Compute roots for two different `GraphType` values with the same leaves and verify the roots differ (graph type is included in hashing)
|
||||
- [ ] Recompute a Merkle root from the same inputs and verify it matches the attested value (offline verification)
|
||||
- [ ] Verify the DSSE envelope signature via the verification pipeline
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,41 @@
|
||||
# Graph Root DSSE Attestation Service
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Service for creating and verifying DSSE-wrapped in-toto attestations of Merkle graph roots. Supports multiple graph types (ResolvedExecutionGraph, ReachabilityGraph, DependencyGraph, ProofSpine, EvidenceGraph) with optional Rekor publication. Enables offline verification by comparing recomputed roots against attested values. Distinct from "Merkle Root Aggregation" and "Graph Revision IDs" which compute roots; this attests them as first-class DSSE-signed entities.
|
||||
|
||||
## Implementation Details
|
||||
- **Graph Root Attestor**: `src/Attestor/__Libraries/StellaOps.Attestor.GraphRoot/GraphRootAttestor.cs` -- creates DSSE-signed in-toto attestations wrapping Merkle roots. Implements `IGraphRootAttestor.cs`.
|
||||
- **Merkle Root Computer**: `Sha256MerkleRootComputer.cs` -- SHA-256 Merkle root computation over sorted leaf hashes. Implements `IMerkleRootComputer.cs`.
|
||||
- **Graph Root Predicate**: `Models/GraphRootPredicate.cs` -- in-toto predicate containing root hash, graph type, leaf count, timestamp.
|
||||
- **Attestation Request**: `Models/GraphRootAttestationRequest.cs` -- specifies graph type, leaves, and signing options.
|
||||
- **Attestation Result**: `Models/GraphRootResults.cs` -- contains the signed DSSE envelope and computed root.
|
||||
- **Graph Types**: `GraphType.cs` -- enum: ResolvedExecutionGraph, ReachabilityGraph, DependencyGraph, ProofSpine, EvidenceGraph.
|
||||
- **DSSE Signing**: `__Libraries/StellaOps.Attestor.ProofChain/Signing/ProofChainSigner.cs` (with `.Verification`) -- signs and verifies DSSE envelopes.
|
||||
- **Rekor Publication**: `StellaOps.Attestor.Core/Rekor/RekorSubmissionService.cs` -- publishes signed attestations to Rekor transparency log.
|
||||
- **DI Registration**: `GraphRootServiceCollectionExtensions.cs` -- registers all graph root services.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.GraphRoot.Tests/`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Create a `GraphRootAttestationRequest` for each supported `GraphType` and verify `GraphRootAttestor` produces valid DSSE envelopes
|
||||
- [ ] Verify the DSSE envelope contains a valid in-toto statement with predicate type matching the graph root schema
|
||||
- [ ] Verify the DSSE signature over the graph root attestation using `ProofChainSigner.Verification`
|
||||
- [ ] Recompute the Merkle root from the same leaves and verify it matches the root in the attested predicate (offline verification)
|
||||
- [ ] Submit a graph root attestation to Rekor via `RekorSubmissionService` and verify a log entry is created
|
||||
- [ ] Create attestations for two different graph types (e.g., ReachabilityGraph vs DependencyGraph) and verify they produce distinct predicates
|
||||
- [ ] Modify one leaf in the input set, recompute, and verify the attested root no longer matches (tamper detection)
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
40
docs/features/checked/attestor/hash-stable-proofs.md
Normal file
40
docs/features/checked/attestor/hash-stable-proofs.md
Normal file
@@ -0,0 +1,40 @@
|
||||
# Hash-stable proofs (deterministic attestation outputs)
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Determinism is enforced and tested at multiple levels: attestation type determinism, DSSE envelope determinism, canonical payload determinism, with dedicated benchmark harness.
|
||||
|
||||
## Implementation Details
|
||||
- **RFC 8785 Canonicalizer**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Json/Rfc8785JsonCanonicalizer.cs` (with `.DecimalPoint`, `.NumberSerialization`, `.StringNormalization`, `.WriteMethods`) -- deterministic JSON serialization per RFC 8785 (JCS). Ensures identical logical JSON always produces identical byte output.
|
||||
- **Content-Addressed ID Generator**: `Identifiers/ContentAddressedIdGenerator.cs` (with `.Graph`) -- generates SHA-256-based IDs from canonicalized content, guaranteeing hash stability.
|
||||
- **Deterministic Merkle Tree**: `Merkle/DeterministicMerkleTreeBuilder.cs` (with `.Helpers`, `.Proof`) -- builds Merkle trees with deterministic leaf ordering and hash computation.
|
||||
- **DSSE Envelope**: `Signing/DsseEnvelope.cs` -- deterministic envelope structure with canonical payload encoding.
|
||||
- **Proof Chain Signer**: `Signing/ProofChainSigner.cs` (with `.Verification`) -- deterministic signing ensuring same payload + key = same signature.
|
||||
- **Statement Builder**: `Builders/StatementBuilder.cs` (with `.Extended`) -- builds in-toto statements with deterministic field ordering.
|
||||
- **Predicate Schema Validator**: `Json/PredicateSchemaValidator.cs` (with `.Validators`, `.DeltaValidators`) -- validates predicates conform to schemas ensuring structural consistency.
|
||||
- **SBOM Canonicalizer**: `__Libraries/StellaOps.Attestor.StandardPredicates/Canonicalization/SbomCanonicalizer.Elements.cs` -- deterministic SBOM element ordering.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/DeterminismTests.cs`, `Rfc8785JsonCanonicalizerTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Serialize the same predicate twice via `Rfc8785JsonCanonicalizer` and verify byte-identical output
|
||||
- [ ] Generate a `ContentAddressedId` from a predicate, serialize/deserialize the predicate, regenerate the ID, and verify they match
|
||||
- [ ] Build two DSSE envelopes from the same payload and key, verify the envelopes are byte-identical
|
||||
- [ ] Build a `DeterministicMerkleTreeBuilder` tree from leaves in different insertion orders and verify the root hash is identical
|
||||
- [ ] Create an in-toto statement via `StatementBuilder`, serialize with JCS, re-parse, re-serialize, and verify byte-identical output
|
||||
- [ ] Canonicalize an SBOM via `SbomCanonicalizer` with components in random order and verify the output is sorted deterministically
|
||||
- [ ] Run the determinism benchmark harness and verify zero hash mismatches across 1000+ iterations
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
42
docs/features/checked/attestor/high-fidelity-sbom-support.md
Normal file
42
docs/features/checked/attestor/high-fidelity-sbom-support.md
Normal file
@@ -0,0 +1,42 @@
|
||||
# High-Fidelity SBOM Support (CycloneDX/SPDX)
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Comprehensive SBOM support with dedicated service, full CycloneDX and SPDX 2.x/3.x parsers and writers, plus UI for SBOM browsing. Extensive coverage of components, vulnerabilities, licensing, relationships, and more.
|
||||
|
||||
## Implementation Details
|
||||
- **CycloneDX Parser**: `src/Attestor/__Libraries/StellaOps.Attestor.StandardPredicates/Parsers/CycloneDxPredicateParser.cs` (with `.ExtractMetadata`, `.ExtractSbom`, `.SerialNumber`, `.Validation`) -- parses CycloneDX 1.6 BOMs into internal SBOM model.
|
||||
- **SPDX Parser**: `Parsers/SpdxPredicateParser.cs` (with `.ExtractMetadata`, `.ExtractSbom`, `.Validation`) -- parses SPDX 2.x/3.x documents into internal SBOM model.
|
||||
- **CycloneDX Writer**: `Writers/CycloneDxWriter.cs` (with 50+ partials: `.Components`, `.Vulnerabilities`, `.Dependencies`, `.Licensing`, `.Services`, `.Compositions`, `.Formulation`, `.Crypto`, `.Evidence`, `.Declarations`, `.ModelCard`, `.Pedigree`, `.ReleaseNotes`, `.Signature`, `.Metadata`, `.Validation`, etc.) -- comprehensive CycloneDX output.
|
||||
- **SPDX Writer**: `Writers/SpdxWriter.cs` (with 40+ partials: `.Packages`, `.Relationships`, `.Licensing`, `.Document`, `.Agents`, `.Builds`, `.Assessments`, `.Vulnerabilities`, `.Profiles`, `.Signatures`, `.Extensions`, `.Hashing`, etc.) -- comprehensive SPDX 3.0.1 output.
|
||||
- **SBOM Models**: `Models/SbomDocument.cs` (with `.Collections`) -- internal SBOM document model. `SbomService.cs` (with `.Collections`) -- service models.
|
||||
- **Licensing**: `Licensing/SpdxLicenseExpressionParser.cs` (with `.InnerTypes`, `.Token`, `.Validation`) -- full SPDX license expression parser. `SpdxLicenseExpressionRenderer.cs` -- renders license expressions back to string.
|
||||
- **SBOM Canonicalizer**: `Canonicalization/SbomCanonicalizer.Elements.cs` -- deterministic ordering for SBOM elements.
|
||||
- **SLSA Provenance Parser**: `Parsers/SlsaProvenancePredicateParser.cs` (with `.ExtractMetadata`, `.Validation`) -- parses SLSA provenance predicates.
|
||||
- **SPDX 3 Build Attestation**: `__Libraries/StellaOps.Attestor.Spdx3/BuildAttestationMapper.cs` (with `.MapFromSpdx3`, `.MapToSpdx3`) -- maps build attestations between SPDX 3 and internal models.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.StandardPredicates.Tests/`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Parse a CycloneDX 1.6 BOM via `CycloneDxPredicateParser` and verify all components, vulnerabilities, and dependencies are extracted
|
||||
- [ ] Parse an SPDX 3.0.1 document via `SpdxPredicateParser` and verify packages, relationships, and licensing are extracted
|
||||
- [ ] Round-trip: parse a CycloneDX BOM, write it back via `CycloneDxWriter`, re-parse, and verify semantic equivalence
|
||||
- [ ] Round-trip: parse an SPDX document, write it back via `SpdxWriter`, re-parse, and verify semantic equivalence
|
||||
- [ ] Parse a complex SPDX license expression (e.g., `(MIT OR Apache-2.0) AND GPL-3.0-only`) via `SpdxLicenseExpressionParser` and verify the parsed tree structure
|
||||
- [ ] Verify `CycloneDxWriter` handles all CycloneDX 1.6 sections: crypto, formulation, declarations, model cards, attestation maps
|
||||
- [ ] Parse a SLSA provenance predicate via `SlsaProvenancePredicateParser` and verify build materials and builder info are extracted
|
||||
- [ ] Canonicalize an SBOM via `SbomCanonicalizer` and verify deterministic output regardless of input element ordering
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,47 @@
|
||||
# Idempotent SBOM/Attestation APIs
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Content-addressed identification for artifacts is implemented. Full idempotent REST API endpoints (POST /sbom/ingest, POST /attest/verify) are not clearly visible as standalone web service endpoints.
|
||||
|
||||
## What's Implemented
|
||||
- **Content-Addressed IDs**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Identifiers/` -- ArtifactId, EvidenceId, ProofBundleId, GenericContentAddressedId, ContentAddressedIdGenerator (with `.Graph`), Sha256IdParser -- SHA-256 based content-addressed identification.
|
||||
- **Proof Chain REST API**: `StellaOps.Attestor.WebService/Controllers/ProofChainController.cs` -- existing proof chain API endpoints.
|
||||
- **Bundles Controller**: `WebService/Controllers/BundlesController.cs` -- bundle management endpoints.
|
||||
- **Verify Controller**: `WebService/Controllers/VerifyController.cs` -- verification endpoints.
|
||||
- **Chain Controller**: `WebService/Controllers/ChainController.cs` -- chain query endpoints.
|
||||
- **SBOM OCI Publisher**: `__Libraries/StellaOps.Attestor.Oci/Services/SbomOciPublisher.cs` -- publishes SBOMs to OCI registries.
|
||||
|
||||
## What's Missing
|
||||
- **Idempotent SBOM ingest endpoint**: No `POST /sbom/ingest` endpoint that accepts an SBOM and returns the same content-addressed ID on duplicate submissions without creating duplicate records.
|
||||
- **Idempotent attestation verify endpoint**: No `POST /attest/verify` endpoint that caches verification results by content hash for repeat submissions.
|
||||
- **Idempotency key support**: No HTTP idempotency key header (`Idempotency-Key`) support for POST endpoints.
|
||||
- **Content-addressed deduplication at API level**: Content-addressed IDs exist at the library level but API endpoints do not use them for deduplication (checking if content already exists before processing).
|
||||
- **Conditional response (ETag/304)**: No ETag-based conditional responses for GET endpoints to avoid re-fetching unchanged content.
|
||||
|
||||
## Implementation Plan
|
||||
- Add `POST /sbom/ingest` endpoint with content-hash-based deduplication
|
||||
- Add `POST /attest/verify` endpoint with cached verification results
|
||||
- Implement idempotency key support for all POST endpoints
|
||||
- Add content-addressed deduplication at the API layer (check-before-store)
|
||||
- Add ETag support for GET endpoints
|
||||
- Add tests for idempotency (duplicate submissions return same result)
|
||||
|
||||
## Related Documentation
|
||||
- Source: See feature catalog
|
||||
- Related: `scanner/idempotent-attestation-submission.md` (scanner-side submission idempotency)
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,49 @@
|
||||
# Immutable Evidence Storage and Regulatory Alignment (NIS2/DORA/ISO-27001)
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
The underlying evidence storage and proof chain infrastructure exists. Specific regulatory compliance mapping (NIS2, DORA, ISO-27001 report templates) not found as distinct modules.
|
||||
|
||||
## What's Implemented
|
||||
- **Append-Only Verdict Ledger**: `src/Attestor/__Libraries/StellaOps.Attestor.Persistence/Repositories/PostgresVerdictLedgerRepository.cs` -- append-only storage with hash chain integrity.
|
||||
- **Verdict Ledger Entry**: `Persistence/Entities/VerdictLedgerEntry.cs` -- ledger entry with previous hash.
|
||||
- **Audit Hash Logger**: `__Libraries/StellaOps.Attestor.ProofChain/Audit/AuditHashLogger.cs` (with `.Validation`) -- tamper-evident audit logging.
|
||||
- **Hash Audit Record**: `Audit/HashAuditRecord.cs` -- individual audit record.
|
||||
- **Evidence Pack Builder**: `__Libraries/StellaOps.Attestor.EvidencePack/ReleaseEvidencePackBuilder.cs` -- builds evidence packs for release decisions.
|
||||
- **Evidence Pack Serializer**: `EvidencePack/ReleaseEvidencePackSerializer.cs` -- serializes evidence packs.
|
||||
- **Merkle Tree Proofs**: `ProofChain/Merkle/DeterministicMerkleTreeBuilder.cs` -- Merkle binding of evidence.
|
||||
- **Trust Evidence Chain**: `__Libraries/StellaOps.Attestor.TrustVerdict/Evidence/TrustEvidenceChain.cs` -- evidence chain with Merkle proofs.
|
||||
|
||||
## What's Missing
|
||||
- **NIS2 compliance report template**: No report template mapping evidence artifacts to NIS2 requirements (incident reporting, risk management, supply chain security).
|
||||
- **DORA compliance report template**: No report template for DORA requirements (ICT risk management, incident classification, third-party risk).
|
||||
- **ISO-27001 control mapping**: No mapping of evidence artifacts to ISO-27001 Annex A controls.
|
||||
- **Retention policy enforcement**: No automated retention policy enforcing minimum evidence retention periods required by regulations.
|
||||
- **Evidence completeness checker**: No service verifying that all required evidence artifacts exist for a given regulatory framework.
|
||||
- **Regulatory export format**: No standardized export format for regulatory auditors (structured PDF/HTML reports with evidence links).
|
||||
|
||||
## Implementation Plan
|
||||
- Define regulatory control mappings (NIS2, DORA, ISO-27001) as configuration
|
||||
- Implement report templates that map stored evidence to regulatory controls
|
||||
- Add retention policy enforcement with configurable minimum periods per regulation
|
||||
- Create evidence completeness checker verifying all required artifacts exist
|
||||
- Build export service generating structured audit reports
|
||||
- Add tests for compliance mapping, retention enforcement, and report generation
|
||||
|
||||
## Related Documentation
|
||||
- Source: See feature catalog
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,53 @@
|
||||
# In-toto DSSE Attestations with Multiple Predicate Types
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Complete DSSE/in-toto attestation framework with build provenance, SBOM, scan results, policy evaluation, VEX, risk profile, AI predicates, and more.
|
||||
|
||||
## Implementation Details
|
||||
- **In-toto Statement**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Statements/InTotoStatement.cs` -- base in-toto statement with subject, predicate type, and predicate payload.
|
||||
- **Statement Builder**: `Builders/StatementBuilder.cs` (with `.Extended`) -- fluent builder for constructing in-toto statements with arbitrary predicate types. `IStatementBuilder.cs` -- interface.
|
||||
- **Predicate Types** (46 statement files in `Statements/`):
|
||||
- `EvidenceStatement.cs` -- evidence attestation
|
||||
- `ReasoningStatement.cs` -- reasoning chain attestation
|
||||
- `VexVerdictStatement.cs` -- VEX verdict attestation
|
||||
- `ProofSpineStatement.cs` -- proof spine with Merkle root
|
||||
- `SbomLinkageStatement.cs` -- SBOM-to-evidence linkage
|
||||
- `DeltaVerdictStatement.cs` -- verdict delta attestation
|
||||
- `ChangeTraceStatement.cs` -- change trace attestation
|
||||
- `UncertaintyStatement.cs` / `UncertaintyBudgetStatement.cs` -- uncertainty attestation
|
||||
- `ReachabilityWitnessStatement.cs` -- reachability witness attestation
|
||||
- `ReachabilityDriftStatement.cs` -- reachability drift attestation
|
||||
- `ReachabilitySubgraphStatement.cs` -- subgraph attestation
|
||||
- `VerdictReceiptStatement.cs` -- verdict receipt attestation
|
||||
- `BinaryMicroWitnessStatement.cs` -- micro-witness attestation
|
||||
- AI statements: `AIExplanationStatement.cs`, `AIPolicyDraftStatement.cs`, `AIRemediationPlanStatement.cs`, `AIVexDraftStatement.cs`
|
||||
- **DSSE Signing**: `Signing/ProofChainSigner.cs` (with `.Verification`) -- signs in-toto statements into DSSE envelopes. `DsseEnvelope.cs`, `DsseSignature.cs` -- envelope models.
|
||||
- **Predicate Models**: 93+ predicate files in `Predicates/` covering AI, VEX, delta, drift, budget, binary, reachability, and more.
|
||||
- **Core In-toto**: `StellaOps.Attestor.Core/InToto/InTotoLink.cs`, `InTotoLinkPredicate.cs`, `LinkBuilder.cs` -- in-toto link framework.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/StatementBuilderTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Create an in-toto statement for each major predicate type (Evidence, Reasoning, VexVerdict, ProofSpine, SbomLinkage, DeltaVerdict) via `StatementBuilder` and verify correct predicate type URIs
|
||||
- [ ] Sign each statement via `ProofChainSigner` into a DSSE envelope and verify the envelope structure (payloadType, payload, signatures)
|
||||
- [ ] Verify each DSSE envelope signature via `ProofChainSigner.Verification` and confirm verification passes
|
||||
- [ ] Create an AI predicate statement (AIExplanation) and verify the predicate contains model identifier, citations, and confidence score
|
||||
- [ ] Create a `ReachabilityWitnessStatement` with call path nodes and verify the statement captures function-level evidence
|
||||
- [ ] Build an `UncertaintyBudgetStatement` and verify it contains budget definitions and violation entries
|
||||
- [ ] Verify `StatementBuilder.Extended` supports custom predicate types not in the standard set
|
||||
- [ ] Create statements with multiple subjects and verify all subjects appear in the in-toto statement
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,53 @@
|
||||
# In-toto Link Attestation Capture
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
The attestation pipeline supports DSSE-wrapped statements and proof chains, which follow in-toto patterns. However, the specific per-step in-toto link capture with `in-toto-run` wrappers as described is not directly implemented.
|
||||
|
||||
## What's Implemented
|
||||
- **In-Toto Link Model**: `src/Attestor/StellaOps.Attestor/StellaOps.Attestor.Core/InToto/InTotoLink.cs` -- in-toto link data model.
|
||||
- **In-Toto Link Predicate**: `InToto/InTotoLinkPredicate.cs` -- link predicate with materials and products.
|
||||
- **Link Builder**: `InToto/LinkBuilder.cs` -- builder for constructing in-toto links.
|
||||
- **Link Recorder**: `InToto/LinkRecorder.cs` -- records link data during step execution. Implements `ILinkRecorder.cs`.
|
||||
- **In-Toto Link Emitter**: `InToto/IInTotoLinkEmitter.cs` -- interface for emitting captured links.
|
||||
- **In-Toto Link Signing Service**: `InToto/IInTotoLinkSigningService.cs` with `Infrastructure/InToto/InTotoLinkSigningService.cs` -- signs captured links.
|
||||
- **In-Toto Layout**: `InToto/Layout/InTotoLayout.cs` -- layout defining expected supply chain steps.
|
||||
- **Layout Verifier**: `InToto/Layout/LayoutVerifier.cs` -- verifies links against layout. Implements `ILayoutVerifier.cs`.
|
||||
- **Artifact Digests**: `InToto/ArtifactDigests.cs` -- input/output artifact digest tracking.
|
||||
- **Material Spec**: `InToto/MaterialSpec.cs` -- material specification for links.
|
||||
- **In-Toto Statement**: `__Libraries/StellaOps.Attestor.ProofChain/Statements/InTotoStatement.cs` -- generic in-toto statement.
|
||||
- **Link Contracts**: `WebService/Contracts/InTotoLinkContracts.cs` -- API contracts for link operations.
|
||||
- **Tests**: `Core.Tests/InToto/InTotoLinkTests.cs`, `InTotoGoldenTests.cs`, `ProofChain.Tests/Statements/InTotoStatementSnapshotTests.cs`
|
||||
|
||||
## What's Missing
|
||||
- **`in-toto-run` wrapper**: No CLI wrapper that automatically captures materials before and products after command execution (analogous to `in-toto-run` from the reference implementation).
|
||||
- **Automatic link capture in CI**: No CI integration that automatically records links for each pipeline step.
|
||||
- **Link storage and retrieval API**: No REST endpoint for storing and querying captured links by step name or functionary.
|
||||
- **Multi-functionary layout verification**: Layout verification exists but multi-functionary threshold verification (k-of-n) may not be fully wired.
|
||||
- **Link chain verification**: No end-to-end verification that all links in a layout chain are present and valid.
|
||||
|
||||
## Implementation Plan
|
||||
- Implement an `in-toto-run` CLI command wrapping command execution with automatic material/product capture
|
||||
- Add CI step link capture via webhook or plugin integration
|
||||
- Create REST endpoints for link storage and retrieval in `ProofChainController`
|
||||
- Complete multi-functionary threshold verification in `LayoutVerifier`
|
||||
- Implement end-to-end link chain verification
|
||||
- Add tests for CLI wrapper, CI capture, and chain verification
|
||||
|
||||
## Related Documentation
|
||||
- Source: See feature catalog
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,43 @@
|
||||
# In-toto Statement and Provenance System (SBOM, Evidence, Reasoning, VEX, SLSA)
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Full in-toto statement builder framework generating Evidence, Reasoning, VexVerdict, ProofSpine, and SbomLinkage statements with snapshot-based golden testing. In-toto/DSSE provenance attestation with SLSA provenance parsing, schema validation, layout verification, and SPDX3 build attestation mapping.
|
||||
|
||||
## Implementation Details
|
||||
- **Statement Builder**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Builders/StatementBuilder.cs` (with `.Extended`) -- fluent builder creating in-toto statements for all predicate types. `IStatementBuilder.cs` -- interface.
|
||||
- **Proof Subject**: `Builders/ProofSubject.cs` -- subject model with name and digest map for in-toto statements.
|
||||
- **Core In-toto Link**: `StellaOps.Attestor.Core/InToto/InTotoLink.cs` -- in-toto link with materials, products, and predicate. `LinkBuilder.cs` -- builds links with material/product specs. `InTotoLinkPredicate.cs` -- link predicate model.
|
||||
- **Layout Verification**: `StellaOps.Attestor.Core/InToto/Layout/` -- in-toto layout verification for supply chain steps.
|
||||
- **Link Recording**: `StellaOps.Attestor.Core/InToto/LinkRecorder.cs` -- records links during build. `ILinkRecorder.cs` -- interface.
|
||||
- **SLSA Provenance Parser**: `__Libraries/StellaOps.Attestor.StandardPredicates/Parsers/SlsaProvenancePredicateParser.cs` (with `.ExtractMetadata`, `.Validation`) -- parses SLSA v1 provenance predicates.
|
||||
- **SLSA Schema Validator**: `__Libraries/StellaOps.Attestor.StandardPredicates/Validation/SlsaSchemaValidator.cs` (with `.BuildDefinition`, `.Helpers`, `.Level`, `.RunDetails`) -- validates SLSA provenance against schema. `SlsaValidationResult.cs` -- result model.
|
||||
- **SPDX3 Build Attestation**: `__Libraries/StellaOps.Attestor.Spdx3/BuildAttestationMapper.cs` (with `.MapFromSpdx3`, `.MapToSpdx3`) -- maps between SPDX3 build profiles and internal attestation models. `BuildAttestationPayload.cs`, `BuildInvocation.cs`, `BuildMaterial.cs`, `BuildMetadata.cs` -- build attestation models.
|
||||
- **DSSE SPDX3 Signer**: `__Libraries/StellaOps.Attestor.Spdx3/DsseSpdx3Signer.cs` (with `.Encoding`, `.SignAsync`, `.SignBuildProfile`, `.Verify`) -- signs SPDX3 build attestations.
|
||||
- **Statement Types**: 46 statement files in `Statements/` -- Evidence, Reasoning, VexVerdict, ProofSpine, SbomLinkage, DeltaVerdict, ChangeTrace, Uncertainty, ReachabilityWitness, etc.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/StatementBuilderTests.cs`, `__Tests/StellaOps.Attestor.StandardPredicates.Tests/SlsaSchemaValidatorTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Build an Evidence statement via `StatementBuilder` with subject digests and verify the in-toto statement structure
|
||||
- [ ] Build a VexVerdict statement and verify it wraps the VEX predicate with correct predicate type URI
|
||||
- [ ] Build a ProofSpine statement and verify it contains the Merkle root and linked evidence IDs
|
||||
- [ ] Parse a SLSA v1 provenance JSON via `SlsaProvenancePredicateParser` and verify builder, build definition, and run details are extracted
|
||||
- [ ] Validate SLSA provenance via `SlsaSchemaValidator` and verify it passes for valid provenance and fails for invalid (e.g., missing buildDefinition)
|
||||
- [ ] Map a build attestation to SPDX3 via `BuildAttestationMapper.MapToSpdx3` and back via `.MapFromSpdx3`; verify round-trip fidelity
|
||||
- [ ] Sign an SPDX3 build attestation via `DsseSpdx3Signer.SignBuildProfile` and verify the DSSE envelope
|
||||
- [ ] Record an in-toto link via `LinkRecorder` with materials and products, then verify the link digest matches
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,41 @@
|
||||
# Knowledge Snapshots with Merkle-Root Sealing
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Replay manifests with feed snapshots, Merkle tree sealing, and policy snapshot storage provide sealed knowledge snapshots.
|
||||
|
||||
## Implementation Details
|
||||
- **AI Artifact Replay Manifest**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Replay/AIArtifactReplayManifest.cs` -- manifest capturing all inputs (prompts, evidence, model parameters) for deterministic replay of AI-generated artifacts.
|
||||
- **Replay Input Artifact**: `Replay/ReplayInputArtifact.cs` -- individual input artifact with content hash for inclusion in snapshots.
|
||||
- **Replay Prompt Template**: `Replay/ReplayPromptTemplate.cs` -- captures the exact prompt template used, with parameter bindings.
|
||||
- **Replay Result**: `Replay/ReplayResult.cs` -- result of a replay attempt with fidelity metrics. `ReplayStatus.cs` -- enum tracking replay outcome.
|
||||
- **Replay Verification**: `Replay/ReplayVerificationResult.cs` -- verification of replay fidelity against original output. `IAIArtifactReplayer.cs` -- interface for replay execution.
|
||||
- **Merkle Tree Sealing**: `Merkle/DeterministicMerkleTreeBuilder.cs` (with `.Helpers`, `.Proof`) -- builds Merkle trees over snapshot content for sealing. `MerkleTreeWithProofs.cs` -- tree with inclusion proofs.
|
||||
- **Merkle Proof**: `Merkle/MerkleProof.cs` -- proof of leaf inclusion in sealed snapshot. `MerkleProofStep.cs` -- individual proof step.
|
||||
- **Graph Root Sealing**: `__Libraries/StellaOps.Attestor.GraphRoot/Sha256MerkleRootComputer.cs` -- computes root hash over knowledge snapshot leaves.
|
||||
- **Proof Spine**: `Statements/ProofSpineStatement.cs` -- bundles multiple sealed snapshots into a single attested spine. `Predicates/ProofSpinePredicate.cs` -- predicate model.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/MerkleTreeTests.cs`, `ReplayManifestTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Create an `AIArtifactReplayManifest` with multiple `ReplayInputArtifact` entries and seal it with a Merkle root via `DeterministicMerkleTreeBuilder`
|
||||
- [ ] Verify the Merkle root is deterministic: building the tree from the same artifacts produces the same root
|
||||
- [ ] Generate a `MerkleProof` for a specific input artifact and verify inclusion in the sealed tree
|
||||
- [ ] Tamper with one input artifact hash and verify the Merkle proof fails
|
||||
- [ ] Create a `ReplayVerificationResult` by replaying the manifest and verify fidelity metrics are captured
|
||||
- [ ] Seal a policy snapshot and an evidence snapshot separately, then combine their roots into a `ProofSpineStatement`
|
||||
- [ ] Verify the sealed snapshot is verifiable offline by recomputing the Merkle root from the stored leaves
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,43 @@
|
||||
# Local Rekor-style Merkle Transparency Log
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Merkle tree construction with inclusion and consistency proofs is implemented, along with Rekor integration and local transparency log support for offline verification.
|
||||
|
||||
## Implementation Details
|
||||
- **Deterministic Merkle Tree Builder**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Merkle/DeterministicMerkleTreeBuilder.cs` (with `.Helpers`, `.Proof`) -- builds append-only Merkle trees with deterministic leaf ordering. `IMerkleTreeBuilder.cs` -- interface.
|
||||
- **Merkle Proof**: `Merkle/MerkleProof.cs` -- inclusion proof for a specific leaf. `MerkleProofStep.cs` -- individual step (left/right sibling hash).
|
||||
- **Merkle Tree with Proofs**: `Merkle/MerkleTreeWithProofs.cs` -- tree structure with pre-computed proofs for all leaves.
|
||||
- **Rekor Integration**: `StellaOps.Attestor.Core/Rekor/RekorSubmissionService.cs` -- submits attestations to Rekor log. `RekorEntryParser.cs` -- parses Rekor log entries.
|
||||
- **Rekor Sync**: `StellaOps.Attestor.Core/Rekor/RekorSyncBackgroundService.cs` -- background service syncing local log with remote Rekor.
|
||||
- **Enhanced Rekor Proof**: `__Libraries/StellaOps.Attestor.ProofChain/Rekor/EnhancedRekorProofBuilder.cs` (with `.Build`, `.Validate`) -- builds enhanced proofs with Rekor inclusion data. `RekorInclusionProof.cs` -- Rekor-specific inclusion proof model.
|
||||
- **Rekor Entry Model**: `Pipeline/RekorEntry.cs` -- local representation of a Rekor transparency log entry.
|
||||
- **Tile Proxy**: `StellaOps.Attestor.TileProxy/TileProxyService.cs` -- caches transparency log tiles for offline verification. `TileSyncJob.cs` -- periodic tile synchronization.
|
||||
- **Infrastructure**: `StellaOps.Attestor.Infrastructure/Rekor/` -- Rekor HTTP client, checkpoint parser, tree state management.
|
||||
- **Persistence**: `__Libraries/StellaOps.Attestor.Persistence/Entities/RekorEntryEntity.cs` -- persists Rekor entries locally.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/MerkleTreeTests.cs`, `RekorProofTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Build a Merkle tree via `DeterministicMerkleTreeBuilder` from a sequence of attestation hashes and verify the root hash
|
||||
- [ ] Generate a `MerkleProof` for a specific leaf and verify inclusion by recomputing the root from the proof steps
|
||||
- [ ] Append new leaves to the tree and verify consistency with the previous root (consistency proof)
|
||||
- [ ] Submit an attestation to Rekor via `RekorSubmissionService` and verify a `RekorEntry` is returned with log index
|
||||
- [ ] Build an `EnhancedRekorProofBuilder` proof combining local Merkle proof with Rekor inclusion proof and verify both proofs
|
||||
- [ ] Verify offline: use `TileProxyService` cached tiles to verify an inclusion proof without network access
|
||||
- [ ] Verify the background sync via `RekorSyncBackgroundService` fetches and persists new Rekor entries locally
|
||||
- [ ] Verify `RekorEntryEntity` persistence: submit, persist, retrieve, and verify the entry matches
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,44 @@
|
||||
# Machine-Verifiable DSSE Verdict Receipts
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Verification receipts with checks, context, and verdict receipt payloads are fully modeled and implemented.
|
||||
|
||||
## Implementation Details
|
||||
- **Verification Receipt**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Receipts/VerificationReceipt.cs` -- complete verification receipt containing checks, context, overall result, and timestamp. `IReceiptGenerator.cs` -- interface for generating receipts.
|
||||
- **Verification Check**: `Receipts/VerificationCheck.cs` -- individual check within a receipt (e.g., signature valid, predicate schema valid, Merkle proof valid) with pass/fail status and message.
|
||||
- **Verification Context**: `Receipts/VerificationContext.cs` -- context for the verification (subject ID, predicate type, verifier identity, timestamp).
|
||||
- **Verification Result**: `Receipts/VerificationResult.cs` -- aggregate result enum (Passed, Failed, Inconclusive).
|
||||
- **Verdict Receipt Payload**: `Statements/VerdictReceiptPayload.cs` -- in-toto predicate payload for verdict receipts containing decision, inputs, and outputs.
|
||||
- **Verdict Receipt Statement**: `Statements/VerdictReceiptStatement.cs` -- in-toto statement wrapping the verdict receipt payload.
|
||||
- **Verdict Decision**: `Statements/VerdictDecision.cs` -- the decision (Pass/Fail/Warn) within the receipt.
|
||||
- **Verdict Inputs**: `Statements/VerdictInputs.cs` -- inputs that were considered for the verdict.
|
||||
- **Verdict Outputs**: `Statements/VerdictOutputs.cs` -- outputs produced by the verdict (policy violations, exceptions applied, etc.).
|
||||
- **DSSE Signing**: `Signing/ProofChainSigner.cs` (with `.Verification`) -- signs verdict receipts into DSSE envelopes for machine verification.
|
||||
- **Signature Verification Result**: `Signing/SignatureVerificationResult.cs` -- result of DSSE signature verification.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/VerificationReceiptTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Generate a `VerificationReceipt` via `IReceiptGenerator` with multiple `VerificationCheck` entries and verify all checks are present
|
||||
- [ ] Create a receipt with all checks passing and verify `VerificationResult` is `Passed`
|
||||
- [ ] Create a receipt with one failing check and verify `VerificationResult` is `Failed`
|
||||
- [ ] Build a `VerdictReceiptStatement` with `VerdictDecision.Pass`, sign it via `ProofChainSigner`, and verify the DSSE envelope is well-formed
|
||||
- [ ] Verify the signed verdict receipt DSSE envelope via `ProofChainSigner.Verification` and confirm `SignatureVerificationResult` passes
|
||||
- [ ] Tamper with the verdict receipt payload after signing and verify signature verification fails
|
||||
- [ ] Create a `VerdictReceiptPayload` with `VerdictInputs` (scan results, policy rules) and `VerdictOutputs` (violations, exceptions) and verify all fields are captured
|
||||
- [ ] Verify `VerificationContext` captures subject ID, predicate type, and verifier identity correctly
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
43
docs/features/checked/attestor/merkle-tree-proof-system.md
Normal file
43
docs/features/checked/attestor/merkle-tree-proof-system.md
Normal file
@@ -0,0 +1,43 @@
|
||||
# Merkle Tree Proof System (Root Aggregation, ProofSpine Bundles, Evidence Chain Verification)
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Deterministic Merkle tree builder with proof generation, step-by-step inclusion proofs, tree-with-proofs assembly, and attestation Merkle root aggregation. ProofSpine bundles aggregate multiple proofs into a single verifiable root. Both generic ProofChain and TrustVerdict-specific Merkle builders exist.
|
||||
|
||||
## Implementation Details
|
||||
- **Deterministic Merkle Tree Builder**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Merkle/DeterministicMerkleTreeBuilder.cs` (with `.Helpers`, `.Proof`) -- builds balanced Merkle trees with deterministic leaf ordering, generates inclusion proofs. `IMerkleTreeBuilder.cs` -- interface.
|
||||
- **Merkle Proof**: `Merkle/MerkleProof.cs` -- inclusion proof containing ordered proof steps from leaf to root.
|
||||
- **Merkle Proof Step**: `Merkle/MerkleProofStep.cs` -- single step: sibling hash + position (left/right).
|
||||
- **Merkle Tree With Proofs**: `Merkle/MerkleTreeWithProofs.cs` -- complete tree structure with pre-computed proofs for every leaf.
|
||||
- **Proof Spine Assembly**: `Assembly/ProofSpineRequest.cs` -- request to assemble a proof spine. `ProofSpineResult.cs` -- result with Merkle root and linked proofs. `ProofSpineSubject.cs` -- individual subject within a spine.
|
||||
- **Spine Verification**: `Assembly/SpineVerificationCheck.cs` -- individual verification check for a spine entry. `SpineVerificationResult.cs` -- aggregate spine verification result.
|
||||
- **Proof Spine Statement**: `Statements/ProofSpineStatement.cs` -- in-toto statement wrapping a proof spine. `Predicates/ProofSpinePredicate.cs` -- predicate model.
|
||||
- **Assembly Merkle Tree**: `Assembly/MerkleTree.cs` -- Merkle tree model used in proof spine assembly.
|
||||
- **Graph Root Computer**: `__Libraries/StellaOps.Attestor.GraphRoot/Sha256MerkleRootComputer.cs` -- SHA-256 root computation over arbitrary leaves.
|
||||
- **Trust Evidence Merkle**: `__Libraries/StellaOps.Attestor.TrustVerdict/` -- trust-verdict-specific Merkle tree builders for evidence chains.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/MerkleTreeTests.cs`, `ProofSpineTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Build a Merkle tree from 8 evidence hashes via `DeterministicMerkleTreeBuilder` and verify the root hash
|
||||
- [ ] Generate `MerkleProof` for each leaf and verify every proof validates against the root
|
||||
- [ ] Build a `MerkleTreeWithProofs` and verify all leaves have valid pre-computed proofs
|
||||
- [ ] Assemble a `ProofSpineRequest` with 5 subjects, build the spine, and verify `ProofSpineResult` contains a valid Merkle root
|
||||
- [ ] Verify the proof spine via `SpineVerificationCheck` and confirm all checks pass
|
||||
- [ ] Build a `ProofSpineStatement` and sign it; verify the DSSE envelope wraps the spine predicate correctly
|
||||
- [ ] Add a new evidence hash to an existing tree and verify the root changes and old proofs are invalidated
|
||||
- [ ] Verify determinism: build the same tree twice with identical leaves and verify identical roots and proofs
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
42
docs/features/checked/attestor/micro-witness-evidence.md
Normal file
42
docs/features/checked/attestor/micro-witness-evidence.md
Normal file
@@ -0,0 +1,42 @@
|
||||
# Micro-Witness Evidence (Function-Level)
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Complete micro-witness system with binary refs, CVE refs, function-level evidence, verdict models, and tooling metadata for fine-grained reachability proof.
|
||||
|
||||
## Implementation Details
|
||||
- **Binary Micro-Witness Predicate**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Predicates/BinaryMicroWitnessPredicate.cs` -- complete micro-witness combining binary ref, CVE ref, function evidence, SBOM ref, tooling, and verdicts.
|
||||
- **Binary Reference**: `Predicates/MicroWitnessBinaryRef.cs` -- identifies the binary artifact (name, version, digest, architecture).
|
||||
- **CVE Reference**: `Predicates/MicroWitnessCveRef.cs` -- CVE identifier with CVSS score, affected function, and advisory URL.
|
||||
- **Function Evidence**: `Predicates/MicroWitnessFunctionEvidence.cs` -- function-level evidence with call-stack depth, reachability status, and code location.
|
||||
- **SBOM Reference**: `Predicates/MicroWitnessSbomRef.cs` -- links micro-witness to an SBOM component entry (component name, version, bom-ref).
|
||||
- **Tooling Metadata**: `Predicates/MicroWitnessTooling.cs` -- captures the analysis tool (name, version, language, analysis type).
|
||||
- **Verdicts**: `Predicates/MicroWitnessVerdicts.cs` -- per-function reachability verdicts (Reachable, Unreachable, Unknown) with confidence.
|
||||
- **Micro-Witness Statement**: `Statements/BinaryMicroWitnessStatement.cs` -- in-toto statement wrapping the micro-witness predicate.
|
||||
- **Reachability Witness**: `Statements/ReachabilityWitnessPayload.cs` (with `.Path`) -- witness payload with call path data. `ReachabilityWitnessStatement.cs` -- in-toto wrapper.
|
||||
- **Call Path Nodes**: `Statements/WitnessCallPathNode.cs`, `WitnessPathNode.cs` -- individual nodes in the witness call path.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/BinaryMicroWitnessPredicateTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Create a `BinaryMicroWitnessPredicate` with a `MicroWitnessBinaryRef`, `MicroWitnessCveRef`, and three `MicroWitnessFunctionEvidence` entries at different call-stack depths; verify the predicate is well-formed
|
||||
- [ ] Create `MicroWitnessVerdicts` with Reachable, Unreachable, and Unknown verdicts for different functions and verify each verdict has a confidence score
|
||||
- [ ] Verify `MicroWitnessTooling` captures language-specific analysis tools (e.g., Java call graph analyzer vs Python AST analyzer)
|
||||
- [ ] Verify `MicroWitnessSbomRef` correctly links the witness to an SBOM component by bom-ref
|
||||
- [ ] Build a `BinaryMicroWitnessStatement` and sign it into a DSSE envelope; verify the statement structure
|
||||
- [ ] Create a `ReachabilityWitnessPayload` with a call path of 5 `WitnessCallPathNode` entries and verify path traversal from entrypoint to sink
|
||||
- [ ] Verify function evidence at call-stack depth 0 (entrypoint) through depth N (vulnerable function) and confirm depth tracking is accurate
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,42 @@
|
||||
# Minimal Reachability Subgraph Attestation
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Stores minimal call/data/control edge subgraphs connecting entrypoints to vulnerable sinks as attested evidence.
|
||||
|
||||
## Implementation Details
|
||||
- **Reachability Subgraph Predicate**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Predicates/ReachabilitySubgraphPredicate.cs` -- predicate containing the minimal subgraph (nodes and edges) connecting entrypoints to vulnerable sinks.
|
||||
- **Reachability Subgraph Statement**: `Statements/ReachabilitySubgraphStatement.cs` -- in-toto statement wrapping the subgraph predicate for DSSE signing.
|
||||
- **Witness Path Nodes**: `Statements/WitnessPathNode.cs` -- individual node in the subgraph (function name, file, line, module).
|
||||
- **Witness Call Path Nodes**: `Statements/WitnessCallPathNode.cs` -- call-graph node with caller/callee relationship.
|
||||
- **Witness Gate Info**: `Statements/WitnessGateInfo.cs` -- gate (security check, validation) along the path.
|
||||
- **Witness Evidence Metadata**: `Statements/WitnessEvidenceMetadata.cs` -- metadata about the analysis that produced the subgraph.
|
||||
- **Proof Graph Subgraph**: `Graph/ProofGraphSubgraph.cs` -- generic subgraph extraction from the proof graph (used to extract minimal subgraphs).
|
||||
- **Proof Graph Path**: `Graph/ProofGraphPath.cs` -- traversal path through the graph.
|
||||
- **Reachability Witness Payload**: `Statements/ReachabilityWitnessPayload.cs` (with `.Path`) -- payload with the full witness including call path.
|
||||
- **DSSE Signing**: `Signing/ProofChainSigner.cs` -- signs subgraph attestations into DSSE envelopes.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/ReachabilitySubgraphTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Create a `ReachabilitySubgraphPredicate` with a minimal subgraph (entrypoint -> intermediate -> vulnerable sink) and verify all nodes and edges are present
|
||||
- [ ] Build a `ReachabilitySubgraphStatement` and sign it via `ProofChainSigner`; verify the DSSE envelope is valid
|
||||
- [ ] Create a subgraph with a `WitnessGateInfo` (e.g., input validation) along the path and verify the gate is captured
|
||||
- [ ] Verify `WitnessEvidenceMetadata` captures the analysis tool, language, and confidence for the subgraph
|
||||
- [ ] Extract a minimal subgraph from a larger `InMemoryProofGraphService` graph using `ProofGraphSubgraph` and verify it contains only the relevant path
|
||||
- [ ] Create a subgraph with multiple paths to the same sink and verify all paths are captured
|
||||
- [ ] Verify the subgraph predicate content-addressed ID is deterministic: same subgraph produces the same ID
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,49 @@
|
||||
# Monthly Bundle Rotation and Re-Signing
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
The attestation and signing infrastructure exists but the specific monthly bundle re-signing workflow is a planned sprint task.
|
||||
|
||||
## What's Implemented
|
||||
- **DSSE Signing**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Signing/ProofChainSigner.cs` (with `.Verification`) -- DSSE signing and verification.
|
||||
- **Signing Key Profile**: `Signing/SigningKeyProfile.cs` -- key profile with algorithm and key material.
|
||||
- **Attestor Signing Key Registry**: `StellaOps.Attestor.Infrastructure/Signing/AttestorSigningKeyRegistry.cs` -- multi-key registry.
|
||||
- **Sigstore Bundle Builder**: `__Libraries/StellaOps.Attestor.Bundle/Builder/SigstoreBundleBuilder.cs` -- builds Sigstore bundles.
|
||||
- **Sigstore Bundle Verifier**: `Bundle/Verification/SigstoreBundleVerifier.cs` -- verifies bundle integrity.
|
||||
- **Sigstore Bundle Serializer**: `Bundle/Serialization/SigstoreBundleSerializer.cs` -- serializes bundles.
|
||||
- **Timestamping Service**: `__Libraries/StellaOps.Attestor.Timestamping/AttestationTimestampService.cs` -- timestamping for re-signing evidence.
|
||||
|
||||
## What's Missing
|
||||
- **Monthly rotation scheduler**: No scheduled job that triggers bundle rotation on a monthly cadence.
|
||||
- **Re-signing workflow**: No workflow that takes existing bundles, verifies them with the old key, and re-signs with a new key.
|
||||
- **Key rotation ceremony**: No key rotation ceremony process (generate new key, sign transition attestation, update trust anchors).
|
||||
- **Bundle version tracking**: No mechanism to track bundle versions and maintain a history of re-signed bundles.
|
||||
- **Re-signing attestation**: No attestation type recording that a bundle was re-signed (old key ID, new key ID, rotation reason).
|
||||
- **Automated trust anchor update**: No automation to update trust anchors when keys rotate.
|
||||
|
||||
## Implementation Plan
|
||||
- Create a `BundleRotationJob` scheduled monthly via Scheduler integration
|
||||
- Implement re-signing workflow (verify old -> sign with new -> update references)
|
||||
- Define a re-signing attestation predicate recording rotation metadata
|
||||
- Add key rotation ceremony process with multi-party approval
|
||||
- Implement bundle version tracking with rotation history
|
||||
- Automate trust anchor updates on key rotation
|
||||
- Add tests for rotation workflow, re-signing, and trust anchor updates
|
||||
|
||||
## Related Documentation
|
||||
- Source: See feature catalog
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,49 @@
|
||||
# Multi-tenant PostgreSQL with RLS and Schema Isolation
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Module-scoped PostgreSQL schemas with RLS policies, tenant-scoped tables with required columns (id, tenant_id, created_at, updated_at), JSONB-first patterns, and queue patterns (SKIP LOCKED).
|
||||
|
||||
## Implementation Details
|
||||
- **DbContext**: `src/Attestor/__Libraries/StellaOps.Attestor.Persistence/ProofChainDbContext.cs` -- EF Core DbContext with tenant-scoped queries, RLS policy application, and schema isolation.
|
||||
- **Entities**:
|
||||
- `Entities/DsseEnvelopeEntity.cs` -- persisted DSSE envelope with tenant_id, created_at, updated_at.
|
||||
- `Entities/RekorEntryEntity.cs` -- persisted Rekor log entry with tenant_id.
|
||||
- `Entities/SbomEntryEntity.cs` -- persisted SBOM entry with tenant_id.
|
||||
- `Entities/SpineEntity.cs` -- persisted proof spine with tenant_id.
|
||||
- `Entities/TrustAnchorEntity.cs` -- persisted trust anchor with tenant_id.
|
||||
- `Entities/VerdictLedgerEntry.cs` -- persisted verdict ledger entry with tenant_id.
|
||||
- `Entities/AuditLogEntity.cs` -- audit log with tenant_id.
|
||||
- **Repositories**:
|
||||
- `Repositories/IProofChainRepository.cs` -- repository interface for proof chain entities.
|
||||
- `Repositories/IVerdictLedgerRepository.cs` -- repository interface for verdict ledger.
|
||||
- `Repositories/PostgresVerdictLedgerRepository.cs` -- PostgreSQL implementation with tenant-scoped queries.
|
||||
- **Migrations**: `Migrations/` -- EF Core migrations defining schema, RLS policies, and indexes.
|
||||
- **Queue**: `StellaOps.Attestor.Core/Queue/IRekorSubmissionQueue.cs` -- durable queue using SKIP LOCKED pattern for concurrent processing.
|
||||
- **Services**: `__Libraries/StellaOps.Attestor.Persistence/Services/` -- data access services.
|
||||
- **Performance**: `__Libraries/StellaOps.Attestor.Persistence/Perf/` -- performance-related configurations.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.Persistence.Tests/`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Create entities (DsseEnvelope, RekorEntry, Spine) for tenant A and verify they are not visible when querying as tenant B (RLS enforcement)
|
||||
- [ ] Verify all entities have required columns: `id`, `tenant_id`, `created_at`, `updated_at`
|
||||
- [ ] Create a `VerdictLedgerEntry` via `PostgresVerdictLedgerRepository` and verify it is persisted with correct tenant_id
|
||||
- [ ] Submit items to `IRekorSubmissionQueue` from multiple tenants and verify SKIP LOCKED processing handles concurrent consumers without duplicates
|
||||
- [ ] Verify JSONB columns store and retrieve complex predicate data correctly
|
||||
- [ ] Run a migration against a fresh database and verify the schema is created with RLS policies enabled
|
||||
- [ ] Verify `AuditLogEntity` captures creation/update events with tenant context
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,46 @@
|
||||
# Native VEX Ingestion and Decisioning
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Full VEX pipeline with ingestion (Excititor), hub for VEX document management, lens for analysis, override system with DSSE-signed decisions, merge trace for conflict resolution, and multiple UI views (studio, hub, timeline).
|
||||
|
||||
## Implementation Details
|
||||
- **VEX Override Predicate System**: `src/Attestor/__Libraries/StellaOps.Attestor.StandardPredicates/VexOverride/` -- complete VEX override system:
|
||||
- `VexOverridePredicate.cs` -- VEX override predicate model.
|
||||
- `VexOverrideDecision.cs` -- override decision (status, justification, impact statement).
|
||||
- `VexOverridePredicateBuilder.cs` (with `.Build`, `.Serialize`, `.WithMethods`) -- fluent builder for constructing VEX overrides.
|
||||
- `VexOverridePredicateParser.cs` (with `.ParsePredicate`, `.DecisionValidation`, `.FieldValidation`, `.ExtractMetadata`, `.Helpers`, `.Validation`) -- parser with comprehensive validation.
|
||||
- `EvidenceReference.cs` -- links override decisions to supporting evidence.
|
||||
- `ToolInfo.cs` -- metadata about the tool that produced the VEX data.
|
||||
- **VEX Proof Integrator**: `__Libraries/StellaOps.Attestor.ProofChain/Generators/VexProofIntegrator.cs` (with `.Helpers`, `.Metadata`) -- integrates VEX decisions into proof chain with supporting evidence.
|
||||
- **VEX Verdict Proof Payload**: `Generators/VexVerdictProofPayload.cs` -- combined VEX verdict + proof payload.
|
||||
- **VEX Verdict Statement**: `__Libraries/StellaOps.Attestor.ProofChain/Statements/VexVerdictStatement.cs` -- in-toto statement wrapping VEX verdicts.
|
||||
- **VEX Predicates**: `Predicates/VexDeltaChange.cs`, `VexDeltaStatement.cs`, `VexDeltaSummary.cs`, `VexDocumentReference.cs`, `VexMergeTrace.cs`, `VexStatusCounts.cs`, `VexVerdictSummary.cs` -- VEX delta tracking, merge traces, and summaries.
|
||||
- **VEX Verdict ID**: `Identifiers/VexVerdictId.cs` -- content-addressed ID for VEX verdicts.
|
||||
- **DSSE Signing**: `Signing/ProofChainSigner.cs` -- signs VEX decisions into DSSE envelopes.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.StandardPredicates.Tests/VexOverrideTests.cs`, `__Tests/StellaOps.Attestor.ProofChain.Tests/VexProofIntegratorTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Build a VEX override via `VexOverridePredicateBuilder` with status "not_affected", justification, and evidence references; verify the predicate structure
|
||||
- [ ] Parse a VEX override JSON via `VexOverridePredicateParser` and verify all fields (decision, evidence, tool info) are extracted
|
||||
- [ ] Validate a VEX override decision via `.DecisionValidation` and verify it rejects invalid statuses
|
||||
- [ ] Integrate a VEX verdict with proof chain evidence via `VexProofIntegrator` and verify the `VexVerdictProofPayload` combines both
|
||||
- [ ] Create a `VexVerdictStatement` and sign it into a DSSE envelope; verify the envelope is valid
|
||||
- [ ] Build a `VexMergeTrace` from two conflicting VEX documents and verify conflict resolution is recorded
|
||||
- [ ] Verify `VexStatusCounts` correctly aggregates counts by VEX status (affected, not_affected, under_investigation, fixed)
|
||||
- [ ] Round-trip: build a VEX override via builder, serialize, parse back, and verify semantic equivalence
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
48
docs/features/checked/attestor/noise-ledger.md
Normal file
48
docs/features/checked/attestor/noise-ledger.md
Normal file
@@ -0,0 +1,48 @@
|
||||
# Noise Ledger (Audit Log of Suppressions)
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Suppression witnesses and audit hash logging exist in the backend. CLI audit commands exist. A dedicated "Noise Ledger" UX component is not present, though the underlying audit/suppression infrastructure is in place.
|
||||
|
||||
## What's Implemented
|
||||
- **Audit Hash Logger**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Audit/AuditHashLogger.cs` (with `.Validation`) -- tamper-evident audit logging for all actions including suppressions.
|
||||
- **Hash Audit Record**: `Audit/HashAuditRecord.cs` -- individual audit record with hash chain.
|
||||
- **Audit Artifact Types**: `Audit/AuditArtifactTypes.cs` -- enumeration of auditable artifact types.
|
||||
- **VEX Override System**: `__Libraries/StellaOps.Attestor.StandardPredicates/VexOverride/` -- structured VEX overrides (suppressions) with evidence and justification.
|
||||
- **Change Trace Attestation Service**: `ProofChain/ChangeTrace/ChangeTraceAttestationService.cs` -- tracks changes including suppressions.
|
||||
- **VEX Delta Tracking**: `Predicates/VexDeltaPredicate.cs`, `VexDeltaChange.cs` -- tracks VEX status transitions.
|
||||
|
||||
## What's Missing
|
||||
- **Dedicated Noise Ledger service**: No standalone service aggregating all suppression/noise decisions into a queryable ledger.
|
||||
- **Noise Ledger UI component**: No frontend page showing a filterable, sortable list of all suppressions with justifications and evidence.
|
||||
- **Suppression statistics**: No aggregated statistics (suppressions per severity, per component, per time period).
|
||||
- **Suppression review workflow**: No periodic review workflow that surfaces suppressions due for re-evaluation.
|
||||
- **Suppression export**: No dedicated export format for suppression audit trail (e.g., for compliance reporting).
|
||||
- **Noise pattern detection**: No automated detection of noise patterns (e.g., same CVE suppressed across all environments).
|
||||
|
||||
## Implementation Plan
|
||||
- Create `NoiseLedgerService` aggregating suppressions from VEX overrides, audit logs, and change traces
|
||||
- Add REST endpoints for querying the noise ledger with filtering/pagination
|
||||
- Build Angular UI component showing suppression list with details, justification, and evidence links
|
||||
- Implement suppression statistics and trend analysis
|
||||
- Add periodic review workflow surfacing stale suppressions
|
||||
- Add export functionality for compliance auditors
|
||||
- Add tests for ledger aggregation, statistics, and review scheduling
|
||||
|
||||
## Related Documentation
|
||||
- Source: See feature catalog
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
38
docs/features/checked/attestor/oci-attestation-attachment.md
Normal file
38
docs/features/checked/attestor/oci-attestation-attachment.md
Normal file
@@ -0,0 +1,38 @@
|
||||
# OCI Attestation Attachment (Referrers API, ORAS, Cosign Compatible)
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
OCI Distribution Spec 1.1 compliant attestation attacher using ORAS with referrers API support. Attaches verdict attestations, delta verdicts, evidence bundles, and SBOMs to container image digests. Supports cosign compatibility, attach/fetch/list operations, and OCI registry client for discovery.
|
||||
|
||||
## Implementation Details
|
||||
- **ORAS Attestation Attacher**: `src/Attestor/__Libraries/StellaOps.Attestor.Oci/Services/OrasAttestationAttacher.cs` -- attaches DSSE-signed attestations to OCI image digests using ORAS and the OCI Referrers API. Implements `IOciAttestationAttacher.cs`.
|
||||
- **OCI Registry Client**: `Services/IOciRegistryClient.cs` -- abstraction for OCI registry operations (push, pull, list referrers, discover).
|
||||
- **SBOM OCI Publisher**: `Services/SbomOciPublisher.cs` -- publishes SBOMs as OCI artifacts attached to image digests. Implements `ISbomOciPublisher.cs`.
|
||||
- **Trust Verdict OCI Attacher**: `__Libraries/StellaOps.Attestor.TrustVerdict/` -- attaches trust verdict attestations to OCI images as referrer artifacts.
|
||||
- **Delta Verdict Predicates**: `__Libraries/StellaOps.Attestor.ProofChain/Predicates/DeltaVerdictPredicate.cs` -- delta verdict predicate model for OCI attachment.
|
||||
- **DSSE Envelope**: `__Libraries/StellaOps.Attestor.ProofChain/Signing/DsseEnvelope.cs` -- envelope format for OCI-attached attestations.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.Oci.Tests/`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Attach a DSSE-signed verdict attestation to an OCI image digest via `OrasAttestationAttacher` and verify it appears in the referrers list
|
||||
- [ ] Publish an SBOM via `SbomOciPublisher` as an OCI artifact and verify it is discoverable via the Referrers API
|
||||
- [ ] List all attestation referrers for an image digest and verify correct artifact types are returned
|
||||
- [ ] Fetch a previously attached attestation by digest and verify the DSSE envelope is intact
|
||||
- [ ] Attach multiple attestation types (verdict, delta verdict, evidence bundle, SBOM) to the same image and verify all are listed
|
||||
- [ ] Verify cosign compatibility: attach an attestation and verify it can be discovered using cosign-style media types
|
||||
- [ ] Verify `IOciRegistryClient` handles authentication and registry errors gracefully
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,42 @@
|
||||
# OCI Delta Attestation Service
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
OCI-native delta attestation pipeline that computes security state deltas between image versions and attaches signed delta attestations as OCI referrers. Enables incremental security validation without full re-scan.
|
||||
|
||||
## Implementation Details
|
||||
- **Delta Verdict Predicate**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Predicates/DeltaVerdictPredicate.cs` (with `.Budget`) -- predicate capturing the security state delta between two image versions (new findings, resolved findings, unchanged findings).
|
||||
- **Delta Verdict Change**: `Predicates/DeltaVerdictChange.cs` -- individual change entry in a delta verdict.
|
||||
- **Delta Finding Key**: `Predicates/DeltaFindingKey.cs` -- unique key identifying a finding across delta comparisons.
|
||||
- **Delta Verdict Statement**: `Statements/DeltaVerdictStatement.cs` -- in-toto statement wrapping the delta verdict predicate.
|
||||
- **Verdict Delta Summary**: `Predicates/VerdictDeltaSummary.cs` -- summary statistics for the delta (counts of new, resolved, changed findings).
|
||||
- **Verdict Finding Change**: `Predicates/VerdictFindingChange.cs` -- detailed finding change with before/after states.
|
||||
- **Verdict Rule Change**: `Predicates/VerdictRuleChange.cs` -- policy rule changes between versions.
|
||||
- **OCI Attachment**: `__Libraries/StellaOps.Attestor.Oci/Services/OrasAttestationAttacher.cs` -- attaches signed delta attestations as OCI referrers to image digests.
|
||||
- **Change Trace**: `__Libraries/StellaOps.Attestor.ProofChain/ChangeTrace/ChangeTraceAttestationService.cs` (with `.Helpers`, `.Mapping`) -- creates change trace attestations tracking modifications over time.
|
||||
- **DSSE Signing**: `Signing/ProofChainSigner.cs` -- signs delta attestations into DSSE envelopes for OCI attachment.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/DeltaVerdictTests.cs`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Compute a delta verdict between two image versions with known finding changes and verify `DeltaVerdictPredicate` captures new, resolved, and unchanged findings
|
||||
- [ ] Create a `DeltaVerdictStatement` and sign it; attach as OCI referrer via `OrasAttestationAttacher` and verify attachment
|
||||
- [ ] Verify `VerdictDeltaSummary` correctly counts: 3 new, 2 resolved, 5 unchanged findings
|
||||
- [ ] Verify `DeltaFindingKey` uniquely identifies findings across delta comparisons (same CVE + component = same key)
|
||||
- [ ] Create a delta with `VerdictRuleChange` entries (policy rule added/removed) and verify rule changes are tracked
|
||||
- [ ] Verify delta with `.Budget` partial: create a delta that exceeds the uncertainty budget and verify the budget violation is captured
|
||||
- [ ] Verify incremental validation: fetch a previous delta attestation from OCI, compute a new delta from the previous state, and verify chain continuity
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
@@ -0,0 +1,44 @@
|
||||
# Offline Verification System (Rekor Mirror, Local Log, Sigstore Bundle)
|
||||
|
||||
## Module
|
||||
Attestor
|
||||
|
||||
## Status
|
||||
VERIFIED
|
||||
|
||||
## Description
|
||||
Offline Rekor receipt verification using local Merkle proof verification without network dependency. TileProxy provides local tile-based transparency log proxy with content-addressed storage. Sigstore bundle offline verifier with integration tests for air-gapped scenarios.
|
||||
|
||||
## Implementation Details
|
||||
- **Offline Verifier**: `src/Attestor/__Libraries/StellaOps.Attestor.Offline/Services/OfflineVerifier.cs` -- verifies attestations offline using locally cached roots, Merkle proofs, and trust anchors. Implements `Abstractions/IOfflineVerifier.cs`.
|
||||
- **Offline Root Store**: `Services/FileSystemRootStore.cs` -- stores trusted roots and checkpoint data on the local filesystem. Implements `Abstractions/IOfflineRootStore.cs`.
|
||||
- **Rule Bundle Signature Verifier**: `Services/RuleBundleSignatureVerifier.cs` -- verifies signed policy rule bundles offline. Implements `Abstractions/IRuleBundleSignatureVerifier.cs`.
|
||||
- **Offline Verification Result**: `Models/OfflineVerificationResult.cs` -- result model with pass/fail status and detailed check results.
|
||||
- **TileProxy Service**: `src/Attestor/StellaOps.Attestor.TileProxy/Services/TileProxyService.cs` -- proxies and caches transparency log tiles for offline verification.
|
||||
- **Content-Addressed Tile Store**: `StellaOps.Attestor.TileProxy/Services/ContentAddressedTileStore.cs` -- stores tiles by content hash for deduplication.
|
||||
- **Tile Sync Job**: `StellaOps.Attestor.TileProxy/Jobs/TileSyncJob.cs` -- background job that syncs tiles from remote Rekor while online.
|
||||
- **Tile Endpoints**: `StellaOps.Attestor.TileProxy/Endpoints/TileEndpoints.cs` -- HTTP endpoints for serving cached tiles.
|
||||
- **Rekor Offline Receipt Verifier**: `StellaOps.Attestor.Core/Verification/RekorOfflineReceiptVerifier.cs` -- verifies Rekor receipts using locally cached data.
|
||||
- **Merkle Proof Verifier**: `StellaOps.Attestor.Core/Verification/MerkleProofVerifier.cs` -- verifies Merkle inclusion proofs locally.
|
||||
- **Sigstore Bundle Verifier**: `__Libraries/StellaOps.Attestor.Bundle/SigstoreBundleVerifier.cs` -- verifies Sigstore bundles offline.
|
||||
- **Tests**: `__Tests/StellaOps.Attestor.Offline.Tests/`, `__Tests/StellaOps.Attestor.TileProxy.Tests/`
|
||||
|
||||
## E2E Test Plan
|
||||
- [ ] Verify an attestation offline via `OfflineVerifier` using cached roots from `FileSystemRootStore` and confirm verification passes
|
||||
- [ ] Simulate air-gap: disable network, verify an attestation using locally cached tiles via `TileProxyService`, and confirm success
|
||||
- [ ] Sync tiles via `TileSyncJob` while online, then verify those tiles are accessible offline via `TileEndpoints`
|
||||
- [ ] Verify a Rekor receipt offline via `RekorOfflineReceiptVerifier` using cached checkpoint and Merkle proof
|
||||
- [ ] Verify a Sigstore bundle offline via `SigstoreBundleVerifier` and confirm certificate chain and signature are valid
|
||||
- [ ] Verify `RuleBundleSignatureVerifier` rejects a tampered policy rule bundle offline
|
||||
- [ ] Verify `ContentAddressedTileStore` deduplicates tiles: store the same tile twice and verify only one copy exists
|
||||
- [ ] Test `OfflineVerificationResult` captures detailed check results for each verification step (root validity, Merkle proof, signature)
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
|-------|--------|
|
||||
| Tier 0 - Source Verification | PASS |
|
||||
| Tier 1 - Build + Code Review | PASS |
|
||||
| Tier 2 - Behavioral Verification | PASS |
|
||||
| Verified Date | 2026-02-13 |
|
||||
| Run ID | run-001 |
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user