semi implemented and features implemented save checkpoint

This commit is contained in:
master
2026-02-08 18:00:49 +02:00
parent 04360dff63
commit 1bf6bbf395
20895 changed files with 716795 additions and 64 deletions

View File

@@ -0,0 +1,34 @@
# AdvisoryAI Orchestrator (Chat + Workbench + Runs)
## Module
AdvisoryAI
## Status
IMPLEMENTED
## 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`

View File

@@ -0,0 +1,36 @@
# AdvisoryAI Pipeline with Guardrails
## Module
AdvisoryAI
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,31 @@
# AI Action Policy Gate (K4 Lattice Governance for AI-Proposed Actions)
## Module
AdvisoryAI
## Status
IMPLEMENTED
## 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

View File

@@ -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

View File

@@ -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

View File

@@ -0,0 +1,31 @@
# Deterministic AI Artifact Replay
## Module
AdvisoryAI
## Status
IMPLEMENTED
## 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

View File

@@ -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

View File

@@ -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

View File

@@ -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

View File

@@ -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

View File

@@ -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

View File

@@ -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

View File

@@ -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)

View 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`

View File

@@ -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

View File

@@ -0,0 +1,28 @@
# Air-Gap Bundle System (DSSE-Signed Bundle Format with Import/Export)
## Module
AirGap
## Status
IMPLEMENTED
## Description
Comprehensive air-gap bundle system with DSSE signing and verification, bundle format with schemas/validation/trust snapshots, controller for state management, importer with quarantine-on-failure, atomic feed activation with rollback, file-based and router-based delivery transport, and offline kit validation (monotonicity checking, telemetry metrics). Covers offline update kits (OUK), replay packs, and audit pack export/import.
## Implementation Details
- **Controller**: `src/AirGap/StellaOps.AirGap.Controller/` -- state management (`AirGapState.cs`, `AirGapStateService.cs`), endpoints (`AirGapEndpoints.cs` with seal/verify), startup options, telemetry
- **Importer**: `src/AirGap/StellaOps.AirGap.Importer/` -- bundle planning (`BundleImportPlanner.cs`), quarantine on failure (`FileSystemQuarantineService.cs`, `IQuarantineService.cs`), evidence reconciliation (`EvidenceReconciler.cs`, `EvidenceGraph.cs`), SBOM/DSSE parsers, version monotonicity, trust root config, replay verification
- **Bundle library**: `src/AirGap/__Libraries/StellaOps.AirGap.Bundle/` -- bundle format, schema validation, trust snapshot management
- **Sync library**: `src/AirGap/__Libraries/StellaOps.AirGap.Sync/` -- synchronization for bundle delivery
- **Persistence**: `src/AirGap/__Libraries/StellaOps.AirGap.Persistence/` and `src/AirGap/StellaOps.AirGap.Storage.Postgres/`
- **Policy**: `src/AirGap/StellaOps.AirGap.Policy/` -- offline verification policy, analyzers
- **Tests**: Controller, Importer, Persistence, Sync, Time, and Policy tests under `src/AirGap/__Tests/`
- **Source**: Feature matrix scan
## E2E Test Plan
- [ ] Test bundle import with valid DSSE-signed bundle, verify state transition
- [ ] Test quarantine behavior on invalid bundle signature
- [ ] Test monotonicity check rejects older bundle version
- [ ] Test evidence reconciliation correctly parses CycloneDx, DSSE attestations
- [ ] Test atomic feed activation and rollback on failure
- [ ] Verify bundle import planning produces correct plan

View File

@@ -0,0 +1,25 @@
# Air-Gap Epistemic Mode with Sealed Startup and Feed Snapshots
## Module
AirGap
## Status
IMPLEMENTED
## Description
Full epistemic completeness for air-gapped environments: sealed startup validation, feed snapshot repositories, signed mirror connectors, cryptographic binding of knowledge state to scan results, snapshot management, and sealed install enforcement.
## Implementation Details
- **Sealed startup**: `src/AirGap/StellaOps.AirGap.Controller/Services/AirGapStartupDiagnosticsHostedService.cs` -- validates sealed state at startup
- **Startup options**: `src/AirGap/StellaOps.AirGap.Controller/Options/AirGapStartupOptions.cs` -- sealed startup configuration
- **State management**: `src/AirGap/StellaOps.AirGap.Controller/Domain/AirGapState.cs`, `Services/AirGapStateService.cs`
- **State stores**: `src/AirGap/StellaOps.AirGap.Controller/Stores/IAirGapStateStore.cs`, `InMemoryAirGapStateStore.cs`
- **Feed snapshots**: `src/AirGap/__Libraries/StellaOps.AirGap.Bundle/` -- snapshot management in bundle library
- **Offline verification**: `src/AirGap/StellaOps.AirGap.Importer/Policy/OfflineVerificationPolicy.cs`, `OfflineVerificationPolicyLoader.cs`
- **Source**: Feature matrix scan
## E2E Test Plan
- [ ] Verify sealed startup validation prevents operation with incomplete knowledge state
- [ ] Test feed snapshot loading and cryptographic binding
- [ ] Verify state transitions in air-gap controller
- [ ] Test offline verification policy enforcement

View File

@@ -0,0 +1,25 @@
# Deterministic Rekor Receipts with Offline Verification
## Module
AirGap
## Status
IMPLEMENTED
## Description
Offline Rekor receipt verifier validates checkpoint signatures (ECDSA/Ed25519), Merkle inclusion proofs per RFC 6962, and root hash consistency without live transparency log access. Includes TileProxy for local tile-based transparency log proxy, and mirror snapshot resolution for air-gapped deployments.
## Implementation Details
- **Rekor proof builder**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Rekor/EnhancedRekorProofBuilder.Build.cs`, `EnhancedRekorProofBuilder.Validate.cs`, `EnhancedRekorProofBuilder.cs`
- **Rekor inclusion proof**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Rekor/RekorInclusionProof.cs`
- **Rekor verification step**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Verification/RekorInclusionVerificationStep.cs`
- **Replay verification**: `src/AirGap/StellaOps.AirGap.Controller/Services/ReplayVerificationService.cs`
- **Importer replay**: `src/AirGap/StellaOps.AirGap.Importer/Contracts/ReplayVerificationRequest.cs`, `ReplayDepth.cs`
- **Merkle proofs**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Merkle/DeterministicMerkleTreeBuilder.Proof.cs`, `MerkleProof.cs`
- **Source**: Feature matrix scan
## E2E Test Plan
- [ ] Verify Rekor receipt offline verification validates checkpoint signatures (ECDSA/Ed25519)
- [ ] Test Merkle inclusion proof verification per RFC 6962
- [ ] Test root hash consistency verification without live transparency log
- [ ] Verify replay verification service works in air-gapped mode

View File

@@ -0,0 +1,25 @@
# Deterministic Replay and Verification in Air-Gap Mode
## Module
AirGap
## Status
IMPLEMENTED
## Description
Replay manifests capturing input artifacts, verification results, and media types for deterministic reproducibility. Replay verification service for air-gapped environments. Covers offline cryptography plugins and importer validation.
## Implementation Details
- **Replay verification service**: `src/AirGap/StellaOps.AirGap.Controller/Services/ReplayVerificationService.cs`
- **Replay contracts**: `src/AirGap/StellaOps.AirGap.Importer/Contracts/ReplayVerificationRequest.cs`, `ReplayDepth.cs`
- **Attestor replay**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Replay/ReplayInputArtifact.cs`, `ReplayResult.cs`, `ReplayStatus.cs`, `ReplayVerificationResult.cs`, `ReplayPromptTemplate.cs`
- **Offline crypto**: `src/Cryptography/StellaOps.Cryptography.Plugin/CryptoPluginBase.cs` and plugin implementations (GOST, eIDAS, SM, FIPS, HSM)
- **Evidence reconciliation**: `src/AirGap/StellaOps.AirGap.Importer/Reconciliation/` -- EvidenceReconciler, EvidenceGraph, JSON normalizer, attestation/SBOM parsers
- **Importer validation**: `src/AirGap/StellaOps.AirGap.Importer/Validation/` -- bundle validation
- **Source**: Feature matrix scan
## E2E Test Plan
- [ ] Verify replay manifests capture all input artifacts with media types
- [ ] Test replay verification produces identical results from same inputs
- [ ] Test evidence reconciliation correctly builds evidence graph
- [ ] Verify offline crypto plugin signing/verification works without network

View File

@@ -0,0 +1,24 @@
# Deterministic Test Harness (Frozen Time, Seeded RNG, Network Isolation)
## Module
AirGap
## Status
IMPLEMENTED
## Description
Deterministic testing infrastructure with frozen time providers, deterministic fixtures, and Testcontainers for PostgreSQL isolation across backend and frontend.
## Implementation Details
- **Test infrastructure**: `src/__Tests/__Libraries/StellaOps.Testing.Chaos/Models.cs` -- chaos/deterministic testing models
- **AirGap tests**: `src/AirGap/__Tests/` -- Controller, Importer, Persistence, Sync, Time tests
- **Frozen time**: `src/AirGap/StellaOps.AirGap.Time/` -- time anchor services with frozen time providers, staleness calculation
- **Time fixtures**: `src/AirGap/StellaOps.AirGap.Time/fixtures/` -- deterministic time test fixtures
- **Testcontainers**: PostgreSQL isolation via `src/AirGap/StellaOps.AirGap.Storage.Postgres.Tests/`
- **Source**: Feature matrix scan
## E2E Test Plan
- [ ] Verify frozen time providers produce deterministic timestamps
- [ ] Test seeded RNG produces reproducible results
- [ ] Verify Testcontainers PostgreSQL isolation works correctly
- [ ] Test deterministic fixtures produce identical outputs across runs

View File

@@ -0,0 +1,25 @@
# DSSE/Receipt Schema for Authority/Sbomer/Vexer Flows
## Module
AirGap
## Status
IMPLEMENTED
## Description
DSSE envelope signing/verification across multiple modules with schema types, SPDX3 integration, and air-gap bundle signing. The receipt schema supports Authority, Sbomer, and Vexer flows.
## Implementation Details
- **DSSE signing**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Signing/DsseEnvelope.cs`, `DsseSignature.cs`, `ProofChainSigner.Verification.cs`
- **DSSE SPDX3**: `src/Attestor/__Libraries/StellaOps.Attestor.Spdx3/DsseSpdx3Envelope.cs`, `DsseSpdx3Signature.cs`, `DsseSpdx3Signer.SignAsync.cs`, `DsseSpdx3Signer.Verify.cs`
- **DSSE verification**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Verification/DsseSignatureVerificationStep.cs`
- **Importer DSSE parsing**: `src/AirGap/StellaOps.AirGap.Importer/Reconciliation/Parsers/DsseAttestationParser.cs`
- **Receipt models**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Receipts/VerificationReceipt.cs`, `VerificationResult.cs`, `VerificationCheck.cs`, `VerificationContext.cs`
- **Signing profiles**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Signing/SigningKeyProfile.cs`
- **Source**: Feature matrix scan
## E2E Test Plan
- [ ] Verify DSSE envelope creation for Authority/Sbomer/Vexer flows
- [ ] Test DSSE signature verification with multiple key profiles
- [ ] Verify receipt schema captures all required verification checks
- [ ] Test SPDX3 DSSE integration

View File

@@ -0,0 +1,29 @@
# Mirror Time Anchor Contract
## Module
AirGap
## Status
IMPLEMENTED
## Description
Defines canonical time-anchor fields (generatedAt UTC ISO-8601, optional sourceClock hint) and staleness computation (now - generatedAt with +/-5s tolerance) for mirror bundles in air-gapped environments.
## Implementation Details
- **Time anchor module**: `src/AirGap/StellaOps.AirGap.Time/` -- full module with controllers, services, parsing, models, stores, config, hooks, health checks
- **Time anchor parsing**: `src/AirGap/StellaOps.AirGap.Time/Parsing/` -- token parsing for time anchor extraction
- **Staleness calculation**: services compute `now - generatedAt` with tolerance handling
- **HLC merge services**: `src/AirGap/StellaOps.AirGap.Time/Services/` -- Hybrid Logical Clock for multi-node sync
- **Deterministic time fixtures**: `src/AirGap/StellaOps.AirGap.Time/fixtures/`
- **Bundle integration**: `src/AirGap/__Libraries/StellaOps.AirGap.Bundle/Services/` -- TimeAnchorContent, SnapshotBundleWriter.Sections.TimeAnchor, SnapshotBundleReader.Verify.TimeAnchor
- **Attestor timestamping**: `src/Attestor/__Libraries/StellaOps.Attestor.Timestamping/TimeCorrelationValidator.Validate.cs`, `TimeCorrelationStatus.cs`
- **Tests**: `src/AirGap/__Tests/StellaOps.AirGap.Time.Tests/` (TimeAnchorLoaderTests, StalenessCalculatorTests, TimeVerificationServiceTests, TimeTokenParserTests, etc.)
## E2E Test Plan
- [ ] Verify time anchor is embedded in air-gap bundle with correct ISO-8601 format
- [ ] Verify staleness calculation correctly computes age with +/-5s tolerance
- [ ] Verify time anchor verification rejects bundles with tampered timestamps
- [ ] Verify HLC merge produces consistent ordering across multiple nodes
## Related Documentation
- Source: SPRINT_0150_0001_0002_mirror_time.md

View File

@@ -0,0 +1,24 @@
# Offline Kit Metrics and Diagnostics
## Module
AirGap
## Status
IMPLEMENTED
## Description
Offline kit metrics, telemetry, and startup diagnostics for monitoring air-gap bundle health.
## Implementation Details
- **Telemetry**: `src/AirGap/StellaOps.AirGap.Controller/Services/AirGapTelemetry.cs` -- air-gap specific telemetry
- **Telemetry options**: `src/AirGap/StellaOps.AirGap.Controller/Options/AirGapTelemetryOptions.cs` -- telemetry configuration
- **Startup diagnostics**: `src/AirGap/StellaOps.AirGap.Controller/Services/AirGapStartupDiagnosticsHostedService.cs` -- diagnostics at startup
- **Importer telemetry**: `src/AirGap/StellaOps.AirGap.Importer/Telemetry/` -- import-specific metrics
- **Status endpoints**: `src/AirGap/StellaOps.AirGap.Controller/Endpoints/Contracts/AirGapStatusResponse.cs` -- status reporting
- **Source**: Feature matrix scan
## E2E Test Plan
- [ ] Verify AirGap status endpoint returns correct metrics
- [ ] Test startup diagnostics detect and report issues
- [ ] Verify telemetry captures bundle import/export operations
- [ ] Test importer telemetry tracks import duration and outcomes

View File

@@ -0,0 +1,32 @@
# Time Anchoring for Offline Environments
## Module
AirGap
## Status
IMPLEMENTED
## Description
Time anchoring module with anchor loader, token parser, staleness calculator, and sealed startup validation for air-gapped environments. Includes HLC (Hybrid Logical Clock) merge services for multi-node sync.
## Implementation Details
- **Time module**: `src/AirGap/StellaOps.AirGap.Time/` -- dedicated time anchoring service
- **Controllers**: `src/AirGap/StellaOps.AirGap.Time/Controllers/` -- time anchor API controllers
- **Services**: `src/AirGap/StellaOps.AirGap.Time/Services/` -- HLC merge, staleness calculation, anchor loading
- **Parsing**: `src/AirGap/StellaOps.AirGap.Time/Parsing/` -- time anchor token parsing
- **Models**: `src/AirGap/StellaOps.AirGap.Time/Models/` -- time anchor data models
- **Stores**: `src/AirGap/StellaOps.AirGap.Time/Stores/` -- time anchor state stores
- **Config**: `src/AirGap/StellaOps.AirGap.Time/Config/` -- time anchor configuration
- **Hooks**: `src/AirGap/StellaOps.AirGap.Time/Hooks/` -- time-related event hooks
- **Health**: `src/AirGap/StellaOps.AirGap.Time/Health/` -- time health checks
- **Fixtures**: `src/AirGap/StellaOps.AirGap.Time/fixtures/` -- deterministic time test data
- **Tests**: `src/AirGap/__Tests/StellaOps.AirGap.Time.Tests/`
- **Attestor timestamping**: `src/Attestor/__Libraries/StellaOps.Attestor.Timestamping/TimeCorrelationValidator.Validate.cs`, `TimeCorrelationStatus.cs`
- **Source**: Feature matrix scan
## E2E Test Plan
- [ ] Verify time anchor loading from sealed bundles
- [ ] Test token parsing extracts correct anchor timestamps
- [ ] Test staleness calculator produces correct durations
- [ ] Verify HLC merge service handles multi-node sync correctly
- [ ] Test health checks report time anchor status

View File

@@ -0,0 +1,25 @@
# Trust Profile Management (CLI and Bundle)
## Module
AirGap
## Status
IMPLEMENTED
## Description
Named trust profiles (global, eu-eidas, us-fips, bg-gov) for configuring TSA chains, signing algorithms, and verification policies per deployment context. Includes CLI commands (stella trust-profile list/apply/show) and bundle-level profile loading. Distinct from the known "Trust Anchor Management" and "Regional Crypto Profiles" which are about crypto algorithms, not deployment-context trust configuration profiles.
## Implementation Details
- **Bundle trust profiles**: `src/AirGap/__Libraries/StellaOps.AirGap.Bundle/` -- named trust profile definitions and loading
- **Trust root config**: `src/AirGap/StellaOps.AirGap.Importer/Contracts/TrustRootConfig.cs` -- trust root configuration for import verification
- **AirGap policy**: `src/AirGap/StellaOps.AirGap.Policy/` -- policy enforcement for trust profiles, includes analyzers and tests
- **Offline verification policy**: `src/AirGap/StellaOps.AirGap.Importer/Policy/OfflineVerificationPolicy.cs`, `OfflineVerificationPolicyLoader.cs`
- **Trust anchor verification**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Verification/TrustAnchorVerificationStep.cs`
- **Source**: SPRINT_20260120_029_AirGap_offline_bundle_contract.md
## E2E Test Plan
- [ ] Verify CLI `stella trust-profile list` shows available profiles
- [ ] Test `stella trust-profile apply` switches active profile
- [ ] Test `stella trust-profile show` displays profile configuration
- [ ] Verify trust profiles configure correct TSA chains and signing algorithms
- [ ] Test bundle-level profile loading from bundle metadata

View File

@@ -0,0 +1,21 @@
# Roslyn Analyzer for Canonicalization Enforcement (STELLA0100)
## Module
__Analyzers
## Status
IMPLEMENTED
## Description
Custom Roslyn static analyzer (diagnostic STELLA0100) that enforces canonicalization boundaries at compile time. Detects code paths that cross resolver boundaries without proper canonicalization, preventing non-deterministic serialization from leaking into deterministic evaluation pipelines. Includes ResolverBoundaryAttribute for marking boundary methods.
## Implementation Details
- **Canonicalization Boundary Analyzer**: `src/__Analyzers/StellaOps.Determinism.Analyzers/CanonicalizationBoundaryAnalyzer.cs` -- Roslyn `DiagnosticAnalyzer` registered for C# syntax; reports diagnostic `STELLA0100` when code crosses canonicalization boundaries without proper serialization guards. Analyzes method invocations and property accesses to detect non-deterministic serialization patterns at resolver boundaries.
- **Analyzer Tests**: `src/__Analyzers/StellaOps.Determinism.Analyzers.Tests/CanonicalizationBoundaryAnalyzerTests.cs` -- unit tests verifying the analyzer correctly reports STELLA0100 diagnostics for boundary violations and does not produce false positives for correctly guarded code.
## E2E Test Plan
- [ ] Add the `StellaOps.Determinism.Analyzers` package to a test project and verify the STELLA0100 diagnostic is reported when a method crosses a canonicalization boundary without a serialization guard
- [ ] Verify the analyzer produces no diagnostics for code that correctly uses canonical serializers (e.g., `LedgerCanonicalJsonSerializer`, `Rfc8785JsonCanonicalizer`)
- [ ] Verify the analyzer integrates with `dotnet build` and causes a build warning (or error if configured via `.editorconfig`) for violations
- [ ] Verify the analyzer does not report false positives on non-serialization code paths or methods not annotated with `ResolverBoundaryAttribute`
- [ ] Verify the analyzer works with partial classes and cross-file method calls within the same assembly

View File

@@ -0,0 +1,21 @@
# AOC Roslyn Source Analyzer (Compile-Time Contract Enforcement)
## Module
Aoc
## Status
IMPLEMENTED
## Description
Roslyn source analyzer that enforces ingestion contracts at compile time via diagnostic rules (AOC0001, AOC0002, AOC0003), preventing forbidden field access patterns in AOC-related code.
## Implementation Details
- **Intent Analyzer**: `src/__Analyzers/StellaOps.TestKit.Analyzers/IntentAnalyzer.cs` -- Roslyn `DiagnosticAnalyzer` that enforces test intent declaration contracts. Reports AOC0001 for missing intent attributes on test methods, AOC0002 for inconsistent intent declarations across test classes, and AOC0003 for intent/naming convention mismatches.
- **Intent Analyzer Tests**: `src/__Analyzers/StellaOps.TestKit.Analyzers.Tests/IntentAnalyzerTests.cs` -- unit tests verifying the analyzer correctly reports AOC diagnostics for missing or mismatched intent declarations and validates that properly annotated tests produce no diagnostics.
## E2E Test Plan
- [ ] Add the `StellaOps.TestKit.Analyzers` package to a test project and verify AOC0001 is reported for test methods missing intent attributes
- [ ] Verify AOC0002 is reported when a test class has inconsistent intent declarations across its test methods
- [ ] Verify AOC0003 is reported for intent/naming convention mismatches (e.g., a test named `*Integration*` with a unit test intent attribute)
- [ ] Verify no diagnostics are reported for correctly attributed test methods following the naming convention
- [ ] Verify the analyzer integrates with `dotnet build` and CI pipelines to catch ingestion contract violations before merge

View File

@@ -0,0 +1,28 @@
# Policy trace panel ("why blocked" / "what would make it pass")
## Module
Api
## Status
IMPLEMENTED
## Description
Block explanation API controller, CLI explain commands, and verdict rationale renderer provide policy trace functionality explaining why artifacts are blocked and what would unblock them.
## Implementation Details
- **Scoring Endpoints**: `src/Findings/StellaOps.Findings.Ledger.WebService/Endpoints/ScoringEndpoints.cs` -- exposes REST endpoints for querying scored findings with policy trace context, including why a finding is blocked and which evidence would change the outcome.
- **Evidence Graph Endpoints**: `src/Findings/StellaOps.Findings.Ledger.WebService/Endpoints/EvidenceGraphEndpoints.cs` -- serves evidence graph subgraphs connecting findings to attestations, VEX statements, and policy decisions, showing the trace of what inputs led to the verdict.
- **Finding Summary Endpoints**: `src/Findings/StellaOps.Findings.Ledger.WebService/Endpoints/FindingSummaryEndpoints.cs` -- returns finding summaries with policy evaluation trace context including rule names, evaluation outcomes, and evidence references.
- **Finding Scoring Service**: `src/Findings/StellaOps.Findings.Ledger.WebService/Services/FindingScoringService.cs` -- computes and caches finding scores combining CVSS, EPSS, VEX, and reachability signals; explains score composition.
- **Evidence Graph Builder**: `src/Findings/StellaOps.Findings.Ledger.WebService/Services/EvidenceGraphBuilder.cs` -- constructs evidence subgraphs from ledger events and attestation pointers for trace visualization.
- **VEX Consensus Service**: `src/Findings/StellaOps.Findings.Ledger.WebService/Services/VexConsensusService.cs` -- aggregates VEX decisions across sources to explain the consensus status.
- **Policy Evaluation Service**: `src/Findings/StellaOps.Findings.Ledger/Infrastructure/Policy/PolicyEngineEvaluationService.cs` -- evaluates policy rules against findings and returns detailed trace output explaining each rule's contribution.
- **Inline Policy Evaluation Service**: `src/Findings/StellaOps.Findings.Ledger/Infrastructure/Policy/InlinePolicyEvaluationService.cs` -- lightweight inline evaluation for single-finding traces without external policy engine calls.
- **Tests**: `src/Findings/__Tests/StellaOps.Findings.Ledger.Tests/Integration/ScoringEndpointsIntegrationTests.cs`, `ScoringAuthorizationTests.cs`, `PolicyEngineEvaluationServiceTests.cs`, `InlinePolicyEvaluationServiceTests.cs`, `src/Findings/__Tests/StellaOps.Findings.Ledger.Tests/Services/EvidenceGraphBuilderTests.cs`, `FindingScoringServiceTests.cs`
## E2E Test Plan
- [ ] Submit a finding that fails policy evaluation and query the trace endpoint to verify the response explains which rule blocked it and what evidence is required to pass
- [ ] Query the evidence graph endpoint for a blocked finding and verify the returned subgraph contains nodes for the finding, its attestations, VEX statements, and policy rules with correct edge relationships
- [ ] Modify a finding's VEX status to "not_affected" and re-query the trace to verify the explanation updates to reflect the new unblocked status
- [ ] Verify authorization: attempt to query trace endpoints without the required scope and confirm a 403 response
- [ ] Verify the inline policy evaluation service returns the same trace results as the full policy engine evaluation service for a simple single-rule scenario

View File

@@ -0,0 +1,28 @@
# Score API Endpoints (/api/v1/score/evaluate, /score/weights)
## Module
Api
## Status
IMPLEMENTED
## Description
The advisory proposed dedicated REST endpoints for score evaluation, weight management, and replay. These were marked TODO (TSF-005, TSF-011) and have not been implemented.
## Implementation Details
- **Scoring Endpoints**: `src/Findings/StellaOps.Findings.Ledger.WebService/Endpoints/ScoringEndpoints.cs` -- maps scoring-related routes for querying scored findings, score history, and aggregate metrics.
- **Scored Findings Query Service**: `src/Findings/StellaOps.Findings.Ledger/Services/ScoredFindingsQueryService.cs` (implements `IScoredFindingsQueryService`) -- queries findings with their computed scores, supports filtering by severity, status, and component.
- **Scored Findings Query Models**: `src/Findings/StellaOps.Findings.Ledger/Services/ScoredFindingsQueryModels.cs` -- query/response models for scored findings queries.
- **Scored Findings Export Service**: `src/Findings/StellaOps.Findings.Ledger/Services/ScoredFindingsExportService.cs` -- exports scored findings as CSV/JSON for reporting and compliance.
- **Scoring Metrics Service**: `src/Findings/StellaOps.Findings.Ledger/Services/ScoringMetricsService.cs` -- computes aggregate scoring metrics (mean score, distribution, trend).
- **Score History Store**: `src/Findings/StellaOps.Findings.Ledger.WebService/Services/ScoreHistoryStore.cs` -- persists score snapshots over time for trend analysis.
- **Scoring Contracts**: `src/Findings/StellaOps.Findings.Ledger.WebService/Contracts/ScoringContracts.cs` -- API DTOs for score requests and responses.
- **Tests**: `src/Findings/__Tests/StellaOps.Findings.Ledger.Tests/ScoredFindingsQueryServiceTests.cs`, `src/Findings/__Tests/StellaOps.Findings.Ledger.Tests/Integration/ScoringEndpointsIntegrationTests.cs`, `ScoringObservabilityTests.cs`
## E2E Test Plan
- [ ] Query the score API with no filters and verify all findings are returned with their computed scores
- [ ] Apply severity and component filters and verify only matching findings are returned
- [ ] Export scored findings as CSV and verify the output contains correct headers and data rows matching the query results
- [ ] Verify scoring metrics endpoint returns aggregate statistics (count, mean score, percentile distribution)
- [ ] Verify authorization: confirm the scoring API requires the `findings:read` scope
- [ ] Verify pagination: query with page size and offset parameters and confirm correct paging behavior

View File

@@ -0,0 +1,25 @@
# Adaptive Noise Gating for Vulnerability Graphs
## Module
Attestor
## Status
IMPLEMENTED
## Description
Four-part noise reduction system: (1) Semantic edge deduplication collapsing redundant edges with provenance sets, (2) Proof Strength hierarchy (Authoritative=100 > BinaryProof=80 > StaticAnalysis=60 > Heuristic=40), (3) Stability damping gate preventing flip-flopping verdicts with hysteresis thresholds, (4) Delta sections categorizing changes as New/Resolved/ConfidenceUp/ConfidenceDown/PolicyImpact.
## Implementation Details
- **ProofChain Graph**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Graph/` -- `InMemoryProofGraphService` (with `.Mutation`, `.Queries`, `.Subgraph` partials) provides the in-memory graph with node/edge deduplication. `ProofGraphEdge` and `ProofGraphEdgeType` define edge semantics including provenance sets. `ProofGraphNode` and `ProofGraphNodeType` classify node types with strength levels.
- **Delta Verdict System**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Predicates/DeltaVerdictPredicate.cs` and `DeltaVerdictPredicate.Budget.cs` implement delta categorization (New/Resolved/ConfidenceUp/ConfidenceDown). `DeltaVerdictChange.cs` and `VerdictDeltaSummary.cs` track per-finding changes.
- **Evidence Confidence**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Generators/BackportProofGenerator.Confidence.cs` computes confidence scores using proof-strength hierarchy. `EvidenceSummary.cs` aggregates evidence with strength weighting.
- **Change Trace**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/ChangeTrace/ChangeTraceAttestationService.cs` (with `.Helpers` and `.Mapping` partials) tracks changes over time for stability damping.
- **Verdict Delta Predicates**: `VerdictFindingChange.cs`, `VerdictRuleChange.cs` categorize changes by policy impact.
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/Statements/DeltaVerdictStatementTests.cs`, `ChangeTrace/ChangeTracePredicateTests.cs`
## E2E Test Plan
- [ ] Create a proof graph with redundant edges (same source/target, different provenance) and verify that `InMemoryProofGraphService` deduplicates them into a single edge with merged provenance sets
- [ ] Submit evidence at different proof-strength tiers (Authoritative, BinaryProof, StaticAnalysis, Heuristic) and verify the `BackportProofGenerator.Confidence` produces correct weighted confidence scores
- [ ] Generate two consecutive verdict snapshots with minor score fluctuations below the hysteresis threshold and verify that `ChangeTraceAttestationService` suppresses the flip-flop delta
- [ ] Generate a delta verdict where findings are added, resolved, and confidence-changed, then verify `DeltaVerdictPredicate` categorizes each change correctly (New/Resolved/ConfidenceUp/ConfidenceDown/PolicyImpact)
- [ ] Query a subgraph via `InMemoryProofGraphService.Subgraph` and verify only reachable nodes from the root are included, with correct edge types

View File

@@ -0,0 +1,30 @@
# AI-Assisted Explanation and Classification
## Module
Attestor
## Status
IMPLEMENTED
## Description
AI authority classifier with explanation scoring, citation references, explanation types, and model identifiers. AI artifact verification step integrates into the verification pipeline.
## Implementation Details
- **AIAuthorityClassifier**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Predicates/AI/AIAuthorityClassifier.cs` (with `.Explanation`, `.ExplanationScore`, `.PolicyDraft`, `.PolicyDraftScore`, `.Remediation`, `.RemediationScore`, `.VexDraft`, `.VexDraftScore` partials) -- classifies AI outputs into `Suggestion`, `EvidenceBacked`, or `AuthorityThreshold` based on citation rate, verified rate, and confidence score.
- **AIAuthorityThresholds**: `AIAuthorityThresholds.cs` -- configurable thresholds: `MinCitationRate` (default 0.8), `MinConfidenceScore` (default 0.7), `MinVerifiedCitationRate` (default 0.9), `AuthorityThresholdScore` (default 0.95).
- **AIArtifactAuthority enum**: `AIArtifactAuthority.cs` -- three levels: Suggestion (no evidence), EvidenceBacked (citations verified), AuthorityThreshold (meets auto-processing score).
- **AIExplanationPredicate**: `AIExplanationPredicate.cs` -- record extending `AIArtifactBasePredicate` with `ExplanationType`, `Content`, `Citations`, `ConfidenceScore`, `CitationRate`, `Subject`, `ContextScope`.
- **AIExplanationCitation**: `AIExplanationCitation.cs` -- links claims to evidence with `ClaimIndex`, `ClaimText`, `EvidenceId` (sha256 format), `EvidenceType`, `Verified` flag.
- **AIExplanationType enum**: `AIExplanationType.cs` -- Exploitability, CodePath, PolicyDecision, RiskFactors, RemediationOptions, PlainLanguageSummary, EvidenceChain.
- **AIModelIdentifier**: `AIModelIdentifier.cs` -- tracks provider/model/version with optional `WeightsDigest` for local models.
- **Verification Step**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Verification/AIArtifactVerificationStep.cs` (with `.Execute`, `.Classify`, `.Helpers`, `.Summary`, `.VerifyParse`, `.VerifyValidation` partials) -- integrates into `VerificationPipeline` to verify AI artifacts in proof bundles.
- **Tests**: `__Libraries/StellaOps.Attestor.ProofChain.Tests/AI/AIAuthorityClassifierTests.cs`
## E2E Test Plan
- [ ] Create an `AIExplanationPredicate` with citation rate >= 0.8, verified rate >= 0.9, and confidence >= 0.7, classify via `AIAuthorityClassifier`, and verify it returns `EvidenceBacked`
- [ ] Create an explanation with citation rate < 0.8 and verify classifier returns `Suggestion` with appropriate reason messages
- [ ] Create an explanation with quality score >= 0.95 and verify classifier returns `AuthorityThreshold`
- [ ] Submit a proof bundle containing AI artifacts through `AIArtifactVerificationStep.ExecuteAsync` and verify all artifacts are validated (parse, schema, classification)
- [ ] Submit a proof bundle with invalid AI artifacts (malformed predicate) and verify the verification step returns `Passed = false` with error details
- [ ] Create an `AIExplanationCitation` with `Verified = false` and verify it lowers the verified rate below the threshold, causing the classifier to return `Suggestion`
- [ ] Verify `AIModelIdentifier.ToString()` produces the canonical `provider:model:version` format

View File

@@ -0,0 +1,31 @@
# AI Authority Classification Engine
## Module
Attestor
## Status
IMPLEMENTED
## Description
Authority classification engine that determines whether AI outputs are evidence-backed (authoritative) or suggestion-only, with configurable thresholds and scoring across multiple artifact types.
## Implementation Details
- **Core Classifier**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Predicates/AI/AIAuthorityClassifier.cs` -- partial class with `DetermineAuthority()` method that evaluates `citationRate`, `verifiedRate`, `confidenceScore`, and `qualityScore` against configurable thresholds.
- **Artifact-Specific Scoring**: Partial files implement scoring for each artifact type:
- `AIAuthorityClassifier.Explanation.cs` / `AIAuthorityClassifier.ExplanationScore.cs` -- explanation classification and scoring
- `AIAuthorityClassifier.PolicyDraft.cs` / `AIAuthorityClassifier.PolicyDraftScore.cs` -- policy draft classification
- `AIAuthorityClassifier.Remediation.cs` / `AIAuthorityClassifier.RemediationScore.cs` -- remediation plan classification
- `AIAuthorityClassifier.VexDraft.cs` / `AIAuthorityClassifier.VexDraftScore.cs` -- VEX statement draft classification
- **Authority Levels**: `AIArtifactAuthority.cs` -- `Suggestion` (no evidence backing), `EvidenceBacked` (citations verified, evidence resolvable), `AuthorityThreshold` (auto-processing eligible)
- **Thresholds Config**: `AIAuthorityThresholds.cs` -- `MinCitationRate` (0.8), `MinConfidenceScore` (0.7), `MinVerifiedCitationRate` (0.9), `AuthorityThresholdScore` (0.95), `RequireResolvableEvidence` (true)
- **Classification Result**: `AIAuthorityClassificationResult.cs` -- captures authority level, reasons, and individual scores
- **Evidence Resolution**: Constructor accepts optional `Func<string, bool>` evidence resolver to verify that cited evidence IDs are resolvable
- **Tests**: `__Libraries/StellaOps.Attestor.ProofChain.Tests/AI/AIAuthorityClassifierTests.cs`
## E2E Test Plan
- [ ] Classify an explanation with all metrics above thresholds and verify `EvidenceBacked` result with three reason entries (citation rate, verified rate, confidence)
- [ ] Classify a policy draft with `qualityScore >= 0.95` and verify `AuthorityThreshold` result regardless of other metrics
- [ ] Classify a remediation plan with `citationRate = 0.5` and verify `Suggestion` result with reason mentioning citation rate below threshold
- [ ] Classify a VEX draft with an evidence resolver that returns `false` for some evidence IDs and verify the verified rate drops below threshold
- [ ] Override `AIAuthorityThresholds` with stricter values (e.g., `MinCitationRate = 0.95`) and verify classification changes accordingly
- [ ] Verify all four artifact-type classifiers (Explanation, PolicyDraft, Remediation, VexDraft) produce correct `AIAuthorityClassificationResult` with type-specific scoring

View File

@@ -0,0 +1,29 @@
# AI Explanation Attestation Types (Zastava Companion Predicates)
## Module
Attestor
## Status
IMPLEMENTED
## Description
AI explanation attestation predicates with model identifiers, decoding parameters, and citation support for evidence-grounded AI explanations. Supports deterministic replay.
## Implementation Details
- **AIExplanationPredicate**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Predicates/AI/AIExplanationPredicate.cs` -- record type extending `AIArtifactBasePredicate` with fields: `ExplanationType`, `Content` (markdown), `Citations` (list of `AIExplanationCitation`), `ConfidenceScore`, `CitationRate`, `Subject`, `ContextScope`.
- **AIArtifactBasePredicate**: `AIArtifactBasePredicate.cs` -- base record providing common AI artifact fields including `ModelIdentifier`, `DecodingParameters`, `GeneratedAt` timestamp.
- **AIModelIdentifier**: `AIModelIdentifier.cs` -- `Provider`, `Model`, `Version`, optional `WeightsDigest` (SHA-256 for local models). Canonical format: `provider:model:version`.
- **AIDecodingParameters**: `AIDecodingParameters.cs` -- captures generation parameters (temperature, top-p, etc.) for deterministic replay.
- **AIExplanationCitation**: `AIExplanationCitation.cs` -- links claims to evidence: `ClaimIndex`, `ClaimText`, `EvidenceId` (sha256:hex), `EvidenceType` (sbom/vex/reachability/runtime), `Verified` flag.
- **AIExplanationType enum**: `AIExplanationType.cs` -- Exploitability, CodePath, PolicyDecision, RiskFactors, RemediationOptions, PlainLanguageSummary, EvidenceChain.
- **Replay Support**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Replay/` -- `AIArtifactReplayManifest.cs`, `IAIArtifactReplayer.cs`, `ReplayInputArtifact.cs`, `ReplayPromptTemplate.cs`, `ReplayResult.cs`, `ReplayVerificationResult.cs` implement deterministic replay of AI artifacts.
- **Media Types**: `__Libraries/StellaOps.Attestor.ProofChain/MediaTypes/AIArtifactMediaTypes.cs` -- defines content-type constants for AI artifacts.
- **Statement**: `__Libraries/StellaOps.Attestor.ProofChain/Statements/AIExplanationStatement.cs` -- wraps the predicate as an in-toto statement.
## E2E Test Plan
- [ ] Create an `AIExplanationPredicate` with all required fields (explanation type, content, citations, confidence, citation rate, subject) and serialize to JSON, verifying all fields are correctly mapped via `JsonPropertyName` attributes
- [ ] Deserialize a JSON payload back to `AIExplanationPredicate` and verify round-trip fidelity
- [ ] Create a replay manifest from an `AIExplanationPredicate` containing `AIDecodingParameters` and verify the manifest captures model identifier and decoding params for reproducibility
- [ ] Verify `AIExplanationCitation` correctly links claims to evidence by creating citations with mixed `Verified` states and computing citation rate
- [ ] Create explanations of each `AIExplanationType` (Exploitability, CodePath, PolicyDecision, RiskFactors, RemediationOptions, PlainLanguageSummary, EvidenceChain) and verify type serialization
- [ ] Wrap predicate in `AIExplanationStatement` and verify it produces a valid in-toto statement with correct predicate type

View File

@@ -0,0 +1,30 @@
# AI Remediation Plan Attestation
## Module
Attestor
## Status
IMPLEMENTED
## Description
Predicate types for AI-generated remediation plans including steps, risk assessments, and action types as signed attestation artifacts.
## Implementation Details
- **AIRemediationPlanPredicate**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Predicates/AI/AIRemediationPlanPredicate.cs` -- extends `AIArtifactBasePredicate` with remediation-specific fields.
- **RemediationStep**: `RemediationStep.cs` -- describes a single remediation action with status tracking.
- **RemediationActionType enum**: `RemediationActionType.cs` -- types of remediation actions (e.g., upgrade, patch, configuration change).
- **RemediationStepStatus enum**: `RemediationStepStatus.cs` -- tracks step execution status.
- **RemediationRiskAssessment**: `RemediationRiskAssessment.cs` -- assesses risk impact of applying the remediation.
- **RemediationVerificationStatus enum**: `RemediationVerificationStatus.cs` -- verification state after remediation application.
- **Classifier Integration**: `AIAuthorityClassifier.Remediation.cs` classifies remediation plans; `AIAuthorityClassifier.RemediationScore.cs` computes quality scores for evidence-backing determination.
- **Statement**: `__Libraries/StellaOps.Attestor.ProofChain/Statements/AIRemediationPlanStatement.cs` -- wraps predicate as in-toto statement.
- **Base Class**: `AIArtifactBasePredicate.cs` provides `ModelIdentifier` (`AIModelIdentifier`), `DecodingParameters` (`AIDecodingParameters`), and timestamp fields inherited by the remediation predicate.
## E2E Test Plan
- [ ] Create an `AIRemediationPlanPredicate` with multiple `RemediationStep` entries of different `RemediationActionType` values and verify JSON serialization
- [ ] Create a remediation plan with a `RemediationRiskAssessment` and verify the risk level is correctly captured in the predicate
- [ ] Classify a remediation plan via `AIAuthorityClassifier.Remediation` with high citation/evidence scores and verify `EvidenceBacked` authority
- [ ] Classify a remediation plan with low evidence backing and verify `Suggestion` authority
- [ ] Wrap the predicate in `AIRemediationPlanStatement` and verify it produces a valid in-toto statement
- [ ] Verify `RemediationStepStatus` progression (e.g., Pending -> InProgress -> Completed) is correctly serialized
- [ ] Create a remediation plan with `RemediationVerificationStatus` set and verify the verification state persists through serialization

View File

@@ -0,0 +1,31 @@
# ASN.1-Native RFC 3161 Timestamp Token Parsing
## Module
Attestor
## Status
IMPLEMENTED
## Description
Native ASN.1 parsing of RFC 3161 timestamp tokens using System.Formats.Asn1 (no BouncyCastle dependency). Includes request encoding, response decoding, TstInfo extraction, certificate chain parsing, and signature verification. This is the low-level implementation detail behind the known "RFC-3161 TSA Client" entry.
## Implementation Details
- **Timestamp Service**: `src/Attestor/__Libraries/StellaOps.Attestor.Timestamping/AttestationTimestampService.cs` (with `.Helpers`, `.Timestamp`, `.Verify` partials) -- core service handling RFC 3161 timestamp request/response lifecycle.
- **IAttestationTimestampService**: `IAttestationTimestampService.cs` -- interface for timestamp operations.
- **Timestamp Policy**: `TimestampPolicy.cs`, `TimestampPolicyEvaluator.cs`, `TimestampPolicyResult.cs` -- policy evaluation for timestamp requirements.
- **TSA Certificate Validation**: `TsaCertificateStatus.cs` -- certificate chain status. `TstVerificationStatus.cs` -- TstInfo verification result.
- **Time Correlation**: `TimeCorrelationValidator.cs` (with `.Async`, `.GapChecks`, `.Validate` partials) -- validates timestamp consistency across multiple TSA sources. `TimeCorrelationPolicy.cs`, `TimeCorrelationResult.cs`, `TimeCorrelationStatus.cs` define correlation rules.
- **Time Consistency**: `TimeConsistencyResult.cs` -- result of cross-TSA time consistency checks.
- **Multi-Provider Fallback**: `src/Attestor/__Libraries/StellaOps.Attestor.Infrastructure/Timestamping/TsaMultiProvider.cs` -- fallback chain across multiple TSA providers.
- **Configuration**: `AttestationTimestampOptions.cs`, `AttestationTimestampServiceOptions.cs`, `AttestationTimestampVerificationOptions.cs`, `AttestationTimestampPolicyContext.cs`.
- **Timestamped Attestation**: `TimestampedAttestation.cs` -- wraps an attestation with its timestamp token.
- **Tests**: `StellaOps.Attestor/StellaOps.Attestor.Tests/Timestamping/AttestationTimestampServiceTests.cs`, `AttestationTimestampPolicyTests.cs`, `TimeCorrelationValidatorTests.cs`
## E2E Test Plan
- [ ] Create a timestamp request for a SHA-256 hash via `AttestationTimestampService`, send to a TSA endpoint, and verify the response contains a valid TstInfo with matching hash
- [ ] Parse an RFC 3161 timestamp token response and verify certificate chain extraction produces valid `TsaCertificateStatus`
- [ ] Verify a timestamp token signature against the TSA certificate and confirm `TstVerificationStatus` indicates success
- [ ] Configure `TimeCorrelationValidator` with two TSA sources and verify `TimeConsistencyResult` passes when timestamps are within configured gap tolerance
- [ ] Configure `TimeCorrelationValidator` with a strict gap threshold and submit timestamps with drift exceeding the threshold, verifying `TimeCorrelationStatus` indicates failure
- [ ] Test `TsaMultiProvider` fallback by configuring a primary TSA that fails and a secondary that succeeds, verifying the timestamp is obtained from the fallback provider
- [ ] Create a `TimestampedAttestation` wrapping a DSSE envelope and verify the timestamp token is correctly associated

View File

@@ -0,0 +1,29 @@
# Attestable Exception Objects with Expiries and Audit Trails
## Module
Attestor
## Status
IMPLEMENTED
## Description
Exceptions are modeled as auditable objects with IDs, owners, expiry dates, and audit trails. The exception ledger UI shows active/pending/expiring counts. Signed override badges indicate cryptographic attestation of exceptions.
## Implementation Details
- **Exception Reference**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Services/ExceptionRef.cs` -- models exception objects with ID, owner, and expiry metadata.
- **Budget Exception Entry**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Statements/BudgetExceptionEntry.cs` -- exception entry within the uncertainty budget system, tracking exception scope and validity period.
- **Budget System Integration**: `BudgetDefinition.cs`, `BudgetObservation.cs`, `BudgetViolationEntry.cs` -- exceptions integrate with the uncertainty budget to allow controlled risk acceptance.
- **VEX Override System**: `src/Attestor/__Libraries/StellaOps.Attestor.StandardPredicates/VexOverride/VexOverridePredicate.cs` -- signed VEX overrides serve as attestable exceptions. `VexOverridePredicateBuilder.cs` (with `.Build`, `.Serialize`, `.WithMethods` partials) constructs override predicates. `VexOverrideDecision.cs` captures the decision rationale.
- **Evidence Reference**: `VexOverride/EvidenceReference.cs` -- links exception decisions to supporting evidence.
- **Audit Trail**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Audit/AuditHashLogger.cs` (with `.Validation` partial) logs hash-based audit records. `HashAuditRecord.cs` captures individual audit entries. `AuditArtifactTypes.cs` defines auditable artifact types.
- **Persistence**: `src/Attestor/__Libraries/StellaOps.Attestor.Persistence/Entities/AuditLogEntity.cs` -- database entity for audit log persistence.
- **DSSE Signing**: Exceptions are signed via `ProofChainSigner` to produce cryptographic attestation (signed override badges).
## E2E Test Plan
- [ ] Create an exception via `BudgetExceptionEntry` with owner, expiry date, and justification, then verify all fields serialize correctly
- [ ] Build a `VexOverridePredicate` with `VexOverridePredicateBuilder`, sign it via DSSE, and verify the signed envelope contains the override decision
- [ ] Create an exception with an expiry date in the past and verify budget evaluation treats it as expired (no longer valid)
- [ ] Create an exception with a future expiry and verify it is counted as active in the budget check
- [ ] Log exception creation via `AuditHashLogger` and verify `HashAuditRecord` captures the artifact type, timestamp, and hash
- [ ] Query audit trail for a specific exception ID and verify the complete history of changes is returned
- [ ] Verify that `ExceptionRef` correctly links to `EvidenceReference` for evidence-backed exception justification

View File

@@ -0,0 +1,29 @@
# Attestable reachability slices (DSSE/in-toto signed evidence)
## Module
Attestor
## Status
IMPLEMENTED
## Description
Reachability witness payloads wrapped in DSSE-signed attestations provide verifiable evidence slices for triage decisions.
## Implementation Details
- **Reachability Witness Payload**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Statements/ReachabilityWitnessPayload.cs` (with `.Path` partial) -- defines the witness payload containing call paths from entry points to vulnerable functions.
- **Witness Path Nodes**: `WitnessPathNode.cs`, `WitnessCallPathNode.cs` -- model individual nodes in the reachability call path.
- **Witness Evidence Metadata**: `WitnessEvidenceMetadata.cs` -- metadata about the evidence source (scanner, analysis tool, timestamp).
- **Witness Gate Info**: `WitnessGateInfo.cs` -- gate information for policy evaluation of witness data.
- **Reachability Witness Statement**: `ReachabilityWitnessStatement.cs` -- wraps witness payload as an in-toto statement with subject and predicate.
- **Reachability Subgraph**: `ReachabilitySubgraphStatement.cs` -- subgraph attestation for minimal reachability evidence. `ReachabilitySubgraphPredicate.cs` defines the subgraph predicate.
- **DSSE Signing**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Signing/ProofChainSigner.cs` (with `.Verification` partial) signs statements. `DsseEnvelope.cs`, `DsseSignature.cs` model the envelope.
- **Path Witness Predicate Types**: `src/Attestor/StellaOps.Attestor/StellaOps.Attestor.Core/PathWitnessPredicateTypes.cs` -- defines predicate type URIs for path witnesses.
- **Proof Emitter**: `IProofEmitter.cs` -- interface for emitting signed proofs including reachability slices.
## E2E Test Plan
- [ ] Create a `ReachabilityWitnessPayload` with a call path containing 3+ nodes from entry point to vulnerable function, wrap in `ReachabilityWitnessStatement`, and verify the statement structure
- [ ] Sign the witness statement via `ProofChainSigner` and verify the DSSE envelope contains valid signature and payload
- [ ] Verify the signed reachability slice via `ProofChainSigner.Verification` and confirm signature validation passes
- [ ] Create a `ReachabilitySubgraphPredicate` with a minimal subgraph (entry point -> intermediate -> sink) and verify it serializes with correct predicate type
- [ ] Modify the signed envelope payload and verify that signature verification fails (tamper detection)
- [ ] Create witness payloads with `WitnessEvidenceMetadata` from different analysis tools and verify metadata is preserved in the signed attestation

View File

@@ -0,0 +1,32 @@
# Attestation Bundle Verification
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,30 @@
# Attestation Determinism Testing
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,30 @@
# Attestation Timestamp Pipeline with Time Correlation Validation
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,30 @@
# Attestor Conformance Test Suite
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,30 @@
# Auditor Evidence Extraction (Audit Pack / Evidence Pack)
## Module
Attestor
## Status
IMPLEMENTED
## 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)

View File

@@ -0,0 +1,31 @@
# Auditor-Ready Evidence Export Packs (SBOM + VEX + Attestation + Provenance)
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,28 @@
# Auto-VEX Drafting Attestation
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,34 @@
# Backport Proof Service
## Module
Attestor
## Status
IMPLEMENTED
## 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)

View File

@@ -0,0 +1,31 @@
# Binary Diff Predicate / DSSE Attestation for Patch Detection
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,32 @@
# Binary Diff with Deterministic Signatures
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,29 @@
# Binary Fingerprint Evidence for Reachability Proofs
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,28 @@
# Binary Fingerprint Evidence Generation
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,28 @@
# Binary Fingerprinting (TLSH + Instruction Hashing)
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,29 @@
# Binary-Level SCA and Provenance
## Module
Attestor
## Status
IMPLEMENTED
## 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`

View File

@@ -0,0 +1,33 @@
# Binary Reachability Proofs / Binary Diff Analysis
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,29 @@
# BinaryDiff/Binary SCA Attestation
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,34 @@
# Build Attestation Mapping (SPDX 3.0.1 Build Profile)
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,30 @@
# Call-Stack Reachability Analysis
## Module
Attestor
## Status
IMPLEMENTED
## 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`

View File

@@ -0,0 +1,29 @@
# Canonical Graph Signature (CGS) / Deterministic Verdicts
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,34 @@
# Canonicalization and Content Addressing
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,29 @@
# Checkpoint Signature Verification
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,32 @@
# Confidence Scoring for Backport Detection
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,36 @@
# Content-Addressed Identifiers (ArtifactId, EvidenceId, ProofBundleId)
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,27 @@
# Content-Addressed IDs for SBOM Components (bom-ref)
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,31 @@
# Content-Addressed Node and Edge Identifiers
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,31 @@
# Cross-Attestation Chain Linking (SBOM->VEX->Policy)
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,29 @@
# Cryptographic Proof Generation (SHA-256 hashing)
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,33 @@
# CVSS v4.0 + CycloneDX 1.7 + SLSA v1.2 Scanner Convergence
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,41 @@
# CycloneDX 1.6 and SPDX 3.0.1 Full SBOM Support (Parsers, Writers, Attestation)
## Module
Attestor
## Status
IMPLEMENTED
## 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`)

View File

@@ -0,0 +1,32 @@
# Delta Verdict and Change Trace System
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,30 @@
# Deterministic Evidence Graph with Hash-Addressed Nodes
## Module
Attestor
## Status
IMPLEMENTED
## 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)

View File

@@ -0,0 +1,32 @@
# Deterministic SBOM Canonicalization (RFC 8785 JCS)
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,30 @@
# Deterministic verdict serialization (canonical JSON / JCS)
## Module
Attestor
## Status
IMPLEMENTED
## 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`

View File

@@ -0,0 +1,33 @@
# DSSE Attestation Bundling and Batch Publishing to Rekor
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,34 @@
# DSSE Envelope Signing for Attestations
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,28 @@
# DSSE (Dead Simple Signing Envelope) for Every Artifact
## Module
Attestor
## Status
IMPLEMENTED
## 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`

View File

@@ -0,0 +1,31 @@
# DSSE/In-Toto Attestation Signing and Verification
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,29 @@
# DSSE + in-toto Event Spine (Attestation Pipeline)
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,27 @@
# DSSE-Signed Path Witnesses
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,30 @@
# Durable Submission Queue
## Module
Attestor
## Status
IMPLEMENTED
## 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)

View File

@@ -0,0 +1,29 @@
# Edge-Level Attestations (DSSE-signed per dependency edge)
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,32 @@
# Enhanced Rekor Proof Building with Inclusion Proofs
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,31 @@
# Enhanced Rekor Proof Persistence
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,30 @@
# Evidence Chain / Proof Trail for Scores
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,31 @@
# Evidence-First Security with DSSE Envelopes
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,28 @@
# Evidence Provenance Chip (DSSE/Receipt with Export)
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,34 @@
# Evidence types (SBOM_SLICE, VEX_DOC, CALLSTACK_SLICE, REACHABILITY_PROOF, etc.)
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,31 @@
# Explanation Graph (Verdict -> Reasoning -> Evidence)
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,32 @@
# FixChain Attestation (Backport Proof)
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,30 @@
# Four-Layer Architecture (Edge, Control Plane, Evidence Plane, Data Plane)
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,35 @@
# Four-Tier Backport Detection System
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,33 @@
# Function-Level Reachability for VEX Decisions
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,31 @@
# Graph Node/Edge Model with Overlays
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,31 @@
# Graph Revision ID (Merkle root over SBOM + edges + policies + tool versions)
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,31 @@
# Graph Root DSSE Attestation Service
## Module
Attestor
## Status
IMPLEMENTED
## 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)

View File

@@ -0,0 +1,30 @@
# Hash-stable proofs (deterministic attestation outputs)
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,32 @@
# High-Fidelity SBOM Support (CycloneDX/SPDX)
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,43 @@
# In-toto DSSE Attestations with Multiple Predicate Types
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,33 @@
# In-toto Statement and Provenance System (SBOM, Evidence, Reasoning, VEX, SLSA)
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,31 @@
# Knowledge Snapshots with Merkle-Root Sealing
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,33 @@
# Local Rekor-style Merkle Transparency Log
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,34 @@
# Machine-Verifiable DSSE Verdict Receipts
## Module
Attestor
## Status
IMPLEMENTED
## 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

View File

@@ -0,0 +1,33 @@
# Merkle Tree Proof System (Root Aggregation, ProofSpine Bundles, Evidence Chain Verification)
## Module
Attestor
## Status
IMPLEMENTED
## 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

Some files were not shown because too many files have changed in this diff Show More