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

View File

@@ -0,0 +1,32 @@
# Micro-Witness Evidence (Function-Level)
## Module
Attestor
## Status
IMPLEMENTED
## Description
Complete micro-witness system with binary refs, CVE refs, function-level evidence, verdict models, and tooling metadata for fine-grained reachability proof.
## Implementation Details
- **Binary Micro-Witness Predicate**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Predicates/BinaryMicroWitnessPredicate.cs` -- complete micro-witness combining binary ref, CVE ref, function evidence, SBOM ref, tooling, and verdicts.
- **Binary Reference**: `Predicates/MicroWitnessBinaryRef.cs` -- identifies the binary artifact (name, version, digest, architecture).
- **CVE Reference**: `Predicates/MicroWitnessCveRef.cs` -- CVE identifier with CVSS score, affected function, and advisory URL.
- **Function Evidence**: `Predicates/MicroWitnessFunctionEvidence.cs` -- function-level evidence with call-stack depth, reachability status, and code location.
- **SBOM Reference**: `Predicates/MicroWitnessSbomRef.cs` -- links micro-witness to an SBOM component entry (component name, version, bom-ref).
- **Tooling Metadata**: `Predicates/MicroWitnessTooling.cs` -- captures the analysis tool (name, version, language, analysis type).
- **Verdicts**: `Predicates/MicroWitnessVerdicts.cs` -- per-function reachability verdicts (Reachable, Unreachable, Unknown) with confidence.
- **Micro-Witness Statement**: `Statements/BinaryMicroWitnessStatement.cs` -- in-toto statement wrapping the micro-witness predicate.
- **Reachability Witness**: `Statements/ReachabilityWitnessPayload.cs` (with `.Path`) -- witness payload with call path data. `ReachabilityWitnessStatement.cs` -- in-toto wrapper.
- **Call Path Nodes**: `Statements/WitnessCallPathNode.cs`, `WitnessPathNode.cs` -- individual nodes in the witness call path.
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/BinaryMicroWitnessPredicateTests.cs`
## E2E Test Plan
- [ ] Create a `BinaryMicroWitnessPredicate` with a `MicroWitnessBinaryRef`, `MicroWitnessCveRef`, and three `MicroWitnessFunctionEvidence` entries at different call-stack depths; verify the predicate is well-formed
- [ ] Create `MicroWitnessVerdicts` with Reachable, Unreachable, and Unknown verdicts for different functions and verify each verdict has a confidence score
- [ ] Verify `MicroWitnessTooling` captures language-specific analysis tools (e.g., Java call graph analyzer vs Python AST analyzer)
- [ ] Verify `MicroWitnessSbomRef` correctly links the witness to an SBOM component by bom-ref
- [ ] Build a `BinaryMicroWitnessStatement` and sign it into a DSSE envelope; verify the statement structure
- [ ] Create a `ReachabilityWitnessPayload` with a call path of 5 `WitnessCallPathNode` entries and verify path traversal from entrypoint to sink
- [ ] Verify function evidence at call-stack depth 0 (entrypoint) through depth N (vulnerable function) and confirm depth tracking is accurate

View File

@@ -0,0 +1,32 @@
# Minimal Reachability Subgraph Attestation
## Module
Attestor
## Status
IMPLEMENTED
## Description
Stores minimal call/data/control edge subgraphs connecting entrypoints to vulnerable sinks as attested evidence.
## Implementation Details
- **Reachability Subgraph Predicate**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Predicates/ReachabilitySubgraphPredicate.cs` -- predicate containing the minimal subgraph (nodes and edges) connecting entrypoints to vulnerable sinks.
- **Reachability Subgraph Statement**: `Statements/ReachabilitySubgraphStatement.cs` -- in-toto statement wrapping the subgraph predicate for DSSE signing.
- **Witness Path Nodes**: `Statements/WitnessPathNode.cs` -- individual node in the subgraph (function name, file, line, module).
- **Witness Call Path Nodes**: `Statements/WitnessCallPathNode.cs` -- call-graph node with caller/callee relationship.
- **Witness Gate Info**: `Statements/WitnessGateInfo.cs` -- gate (security check, validation) along the path.
- **Witness Evidence Metadata**: `Statements/WitnessEvidenceMetadata.cs` -- metadata about the analysis that produced the subgraph.
- **Proof Graph Subgraph**: `Graph/ProofGraphSubgraph.cs` -- generic subgraph extraction from the proof graph (used to extract minimal subgraphs).
- **Proof Graph Path**: `Graph/ProofGraphPath.cs` -- traversal path through the graph.
- **Reachability Witness Payload**: `Statements/ReachabilityWitnessPayload.cs` (with `.Path`) -- payload with the full witness including call path.
- **DSSE Signing**: `Signing/ProofChainSigner.cs` -- signs subgraph attestations into DSSE envelopes.
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/ReachabilitySubgraphTests.cs`
## E2E Test Plan
- [ ] Create a `ReachabilitySubgraphPredicate` with a minimal subgraph (entrypoint -> intermediate -> vulnerable sink) and verify all nodes and edges are present
- [ ] Build a `ReachabilitySubgraphStatement` and sign it via `ProofChainSigner`; verify the DSSE envelope is valid
- [ ] Create a subgraph with a `WitnessGateInfo` (e.g., input validation) along the path and verify the gate is captured
- [ ] Verify `WitnessEvidenceMetadata` captures the analysis tool, language, and confidence for the subgraph
- [ ] Extract a minimal subgraph from a larger `InMemoryProofGraphService` graph using `ProofGraphSubgraph` and verify it contains only the relevant path
- [ ] Create a subgraph with multiple paths to the same sink and verify all paths are captured
- [ ] Verify the subgraph predicate content-addressed ID is deterministic: same subgraph produces the same ID

View File

@@ -0,0 +1,39 @@
# Multi-tenant PostgreSQL with RLS and Schema Isolation
## Module
Attestor
## Status
IMPLEMENTED
## Description
Module-scoped PostgreSQL schemas with RLS policies, tenant-scoped tables with required columns (id, tenant_id, created_at, updated_at), JSONB-first patterns, and queue patterns (SKIP LOCKED).
## Implementation Details
- **DbContext**: `src/Attestor/__Libraries/StellaOps.Attestor.Persistence/ProofChainDbContext.cs` -- EF Core DbContext with tenant-scoped queries, RLS policy application, and schema isolation.
- **Entities**:
- `Entities/DsseEnvelopeEntity.cs` -- persisted DSSE envelope with tenant_id, created_at, updated_at.
- `Entities/RekorEntryEntity.cs` -- persisted Rekor log entry with tenant_id.
- `Entities/SbomEntryEntity.cs` -- persisted SBOM entry with tenant_id.
- `Entities/SpineEntity.cs` -- persisted proof spine with tenant_id.
- `Entities/TrustAnchorEntity.cs` -- persisted trust anchor with tenant_id.
- `Entities/VerdictLedgerEntry.cs` -- persisted verdict ledger entry with tenant_id.
- `Entities/AuditLogEntity.cs` -- audit log with tenant_id.
- **Repositories**:
- `Repositories/IProofChainRepository.cs` -- repository interface for proof chain entities.
- `Repositories/IVerdictLedgerRepository.cs` -- repository interface for verdict ledger.
- `Repositories/PostgresVerdictLedgerRepository.cs` -- PostgreSQL implementation with tenant-scoped queries.
- **Migrations**: `Migrations/` -- EF Core migrations defining schema, RLS policies, and indexes.
- **Queue**: `StellaOps.Attestor.Core/Queue/IRekorSubmissionQueue.cs` -- durable queue using SKIP LOCKED pattern for concurrent processing.
- **Services**: `__Libraries/StellaOps.Attestor.Persistence/Services/` -- data access services.
- **Performance**: `__Libraries/StellaOps.Attestor.Persistence/Perf/` -- performance-related configurations.
- **Tests**: `__Tests/StellaOps.Attestor.Persistence.Tests/`
## E2E Test Plan
- [ ] Create entities (DsseEnvelope, RekorEntry, Spine) for tenant A and verify they are not visible when querying as tenant B (RLS enforcement)
- [ ] Verify all entities have required columns: `id`, `tenant_id`, `created_at`, `updated_at`
- [ ] Create a `VerdictLedgerEntry` via `PostgresVerdictLedgerRepository` and verify it is persisted with correct tenant_id
- [ ] Submit items to `IRekorSubmissionQueue` from multiple tenants and verify SKIP LOCKED processing handles concurrent consumers without duplicates
- [ ] Verify JSONB columns store and retrieve complex predicate data correctly
- [ ] Run a migration against a fresh database and verify the schema is created with RLS policies enabled
- [ ] Verify `AuditLogEntity` captures creation/update events with tenant context

View File

@@ -0,0 +1,36 @@
# Native VEX Ingestion and Decisioning
## Module
Attestor
## Status
IMPLEMENTED
## Description
Full VEX pipeline with ingestion (Excititor), hub for VEX document management, lens for analysis, override system with DSSE-signed decisions, merge trace for conflict resolution, and multiple UI views (studio, hub, timeline).
## Implementation Details
- **VEX Override Predicate System**: `src/Attestor/__Libraries/StellaOps.Attestor.StandardPredicates/VexOverride/` -- complete VEX override system:
- `VexOverridePredicate.cs` -- VEX override predicate model.
- `VexOverrideDecision.cs` -- override decision (status, justification, impact statement).
- `VexOverridePredicateBuilder.cs` (with `.Build`, `.Serialize`, `.WithMethods`) -- fluent builder for constructing VEX overrides.
- `VexOverridePredicateParser.cs` (with `.ParsePredicate`, `.DecisionValidation`, `.FieldValidation`, `.ExtractMetadata`, `.Helpers`, `.Validation`) -- parser with comprehensive validation.
- `EvidenceReference.cs` -- links override decisions to supporting evidence.
- `ToolInfo.cs` -- metadata about the tool that produced the VEX data.
- **VEX Proof Integrator**: `__Libraries/StellaOps.Attestor.ProofChain/Generators/VexProofIntegrator.cs` (with `.Helpers`, `.Metadata`) -- integrates VEX decisions into proof chain with supporting evidence.
- **VEX Verdict Proof Payload**: `Generators/VexVerdictProofPayload.cs` -- combined VEX verdict + proof payload.
- **VEX Verdict Statement**: `__Libraries/StellaOps.Attestor.ProofChain/Statements/VexVerdictStatement.cs` -- in-toto statement wrapping VEX verdicts.
- **VEX Predicates**: `Predicates/VexDeltaChange.cs`, `VexDeltaStatement.cs`, `VexDeltaSummary.cs`, `VexDocumentReference.cs`, `VexMergeTrace.cs`, `VexStatusCounts.cs`, `VexVerdictSummary.cs` -- VEX delta tracking, merge traces, and summaries.
- **VEX Verdict ID**: `Identifiers/VexVerdictId.cs` -- content-addressed ID for VEX verdicts.
- **DSSE Signing**: `Signing/ProofChainSigner.cs` -- signs VEX decisions into DSSE envelopes.
- **Tests**: `__Tests/StellaOps.Attestor.StandardPredicates.Tests/VexOverrideTests.cs`, `__Tests/StellaOps.Attestor.ProofChain.Tests/VexProofIntegratorTests.cs`
## E2E Test Plan
- [ ] Build a VEX override via `VexOverridePredicateBuilder` with status "not_affected", justification, and evidence references; verify the predicate structure
- [ ] Parse a VEX override JSON via `VexOverridePredicateParser` and verify all fields (decision, evidence, tool info) are extracted
- [ ] Validate a VEX override decision via `.DecisionValidation` and verify it rejects invalid statuses
- [ ] Integrate a VEX verdict with proof chain evidence via `VexProofIntegrator` and verify the `VexVerdictProofPayload` combines both
- [ ] Create a `VexVerdictStatement` and sign it into a DSSE envelope; verify the envelope is valid
- [ ] Build a `VexMergeTrace` from two conflicting VEX documents and verify conflict resolution is recorded
- [ ] Verify `VexStatusCounts` correctly aggregates counts by VEX status (affected, not_affected, under_investigation, fixed)
- [ ] Round-trip: build a VEX override via builder, serialize, parse back, and verify semantic equivalence

View File

@@ -0,0 +1,28 @@
# OCI Attestation Attachment (Referrers API, ORAS, Cosign Compatible)
## Module
Attestor
## Status
IMPLEMENTED
## Description
OCI Distribution Spec 1.1 compliant attestation attacher using ORAS with referrers API support. Attaches verdict attestations, delta verdicts, evidence bundles, and SBOMs to container image digests. Supports cosign compatibility, attach/fetch/list operations, and OCI registry client for discovery.
## Implementation Details
- **ORAS Attestation Attacher**: `src/Attestor/__Libraries/StellaOps.Attestor.Oci/Services/OrasAttestationAttacher.cs` -- attaches DSSE-signed attestations to OCI image digests using ORAS and the OCI Referrers API. Implements `IOciAttestationAttacher.cs`.
- **OCI Registry Client**: `Services/IOciRegistryClient.cs` -- abstraction for OCI registry operations (push, pull, list referrers, discover).
- **SBOM OCI Publisher**: `Services/SbomOciPublisher.cs` -- publishes SBOMs as OCI artifacts attached to image digests. Implements `ISbomOciPublisher.cs`.
- **Trust Verdict OCI Attacher**: `__Libraries/StellaOps.Attestor.TrustVerdict/` -- attaches trust verdict attestations to OCI images as referrer artifacts.
- **Delta Verdict Predicates**: `__Libraries/StellaOps.Attestor.ProofChain/Predicates/DeltaVerdictPredicate.cs` -- delta verdict predicate model for OCI attachment.
- **DSSE Envelope**: `__Libraries/StellaOps.Attestor.ProofChain/Signing/DsseEnvelope.cs` -- envelope format for OCI-attached attestations.
- **Tests**: `__Tests/StellaOps.Attestor.Oci.Tests/`
## E2E Test Plan
- [ ] Attach a DSSE-signed verdict attestation to an OCI image digest via `OrasAttestationAttacher` and verify it appears in the referrers list
- [ ] Publish an SBOM via `SbomOciPublisher` as an OCI artifact and verify it is discoverable via the Referrers API
- [ ] List all attestation referrers for an image digest and verify correct artifact types are returned
- [ ] Fetch a previously attached attestation by digest and verify the DSSE envelope is intact
- [ ] Attach multiple attestation types (verdict, delta verdict, evidence bundle, SBOM) to the same image and verify all are listed
- [ ] Verify cosign compatibility: attach an attestation and verify it can be discovered using cosign-style media types
- [ ] Verify `IOciRegistryClient` handles authentication and registry errors gracefully

View File

@@ -0,0 +1,32 @@
# OCI Delta Attestation Service
## Module
Attestor
## Status
IMPLEMENTED
## Description
OCI-native delta attestation pipeline that computes security state deltas between image versions and attaches signed delta attestations as OCI referrers. Enables incremental security validation without full re-scan.
## Implementation Details
- **Delta Verdict Predicate**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Predicates/DeltaVerdictPredicate.cs` (with `.Budget`) -- predicate capturing the security state delta between two image versions (new findings, resolved findings, unchanged findings).
- **Delta Verdict Change**: `Predicates/DeltaVerdictChange.cs` -- individual change entry in a delta verdict.
- **Delta Finding Key**: `Predicates/DeltaFindingKey.cs` -- unique key identifying a finding across delta comparisons.
- **Delta Verdict Statement**: `Statements/DeltaVerdictStatement.cs` -- in-toto statement wrapping the delta verdict predicate.
- **Verdict Delta Summary**: `Predicates/VerdictDeltaSummary.cs` -- summary statistics for the delta (counts of new, resolved, changed findings).
- **Verdict Finding Change**: `Predicates/VerdictFindingChange.cs` -- detailed finding change with before/after states.
- **Verdict Rule Change**: `Predicates/VerdictRuleChange.cs` -- policy rule changes between versions.
- **OCI Attachment**: `__Libraries/StellaOps.Attestor.Oci/Services/OrasAttestationAttacher.cs` -- attaches signed delta attestations as OCI referrers to image digests.
- **Change Trace**: `__Libraries/StellaOps.Attestor.ProofChain/ChangeTrace/ChangeTraceAttestationService.cs` (with `.Helpers`, `.Mapping`) -- creates change trace attestations tracking modifications over time.
- **DSSE Signing**: `Signing/ProofChainSigner.cs` -- signs delta attestations into DSSE envelopes for OCI attachment.
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/DeltaVerdictTests.cs`
## E2E Test Plan
- [ ] Compute a delta verdict between two image versions with known finding changes and verify `DeltaVerdictPredicate` captures new, resolved, and unchanged findings
- [ ] Create a `DeltaVerdictStatement` and sign it; attach as OCI referrer via `OrasAttestationAttacher` and verify attachment
- [ ] Verify `VerdictDeltaSummary` correctly counts: 3 new, 2 resolved, 5 unchanged findings
- [ ] Verify `DeltaFindingKey` uniquely identifies findings across delta comparisons (same CVE + component = same key)
- [ ] Create a delta with `VerdictRuleChange` entries (policy rule added/removed) and verify rule changes are tracked
- [ ] Verify delta with `.Budget` partial: create a delta that exceeds the uncertainty budget and verify the budget violation is captured
- [ ] Verify incremental validation: fetch a previous delta attestation from OCI, compute a new delta from the previous state, and verify chain continuity

View File

@@ -0,0 +1,34 @@
# Offline Verification System (Rekor Mirror, Local Log, Sigstore Bundle)
## Module
Attestor
## Status
IMPLEMENTED
## Description
Offline Rekor receipt verification using local Merkle proof verification without network dependency. TileProxy provides local tile-based transparency log proxy with content-addressed storage. Sigstore bundle offline verifier with integration tests for air-gapped scenarios.
## Implementation Details
- **Offline Verifier**: `src/Attestor/__Libraries/StellaOps.Attestor.Offline/Services/OfflineVerifier.cs` -- verifies attestations offline using locally cached roots, Merkle proofs, and trust anchors. Implements `Abstractions/IOfflineVerifier.cs`.
- **Offline Root Store**: `Services/FileSystemRootStore.cs` -- stores trusted roots and checkpoint data on the local filesystem. Implements `Abstractions/IOfflineRootStore.cs`.
- **Rule Bundle Signature Verifier**: `Services/RuleBundleSignatureVerifier.cs` -- verifies signed policy rule bundles offline. Implements `Abstractions/IRuleBundleSignatureVerifier.cs`.
- **Offline Verification Result**: `Models/OfflineVerificationResult.cs` -- result model with pass/fail status and detailed check results.
- **TileProxy Service**: `src/Attestor/StellaOps.Attestor.TileProxy/Services/TileProxyService.cs` -- proxies and caches transparency log tiles for offline verification.
- **Content-Addressed Tile Store**: `StellaOps.Attestor.TileProxy/Services/ContentAddressedTileStore.cs` -- stores tiles by content hash for deduplication.
- **Tile Sync Job**: `StellaOps.Attestor.TileProxy/Jobs/TileSyncJob.cs` -- background job that syncs tiles from remote Rekor while online.
- **Tile Endpoints**: `StellaOps.Attestor.TileProxy/Endpoints/TileEndpoints.cs` -- HTTP endpoints for serving cached tiles.
- **Rekor Offline Receipt Verifier**: `StellaOps.Attestor.Core/Verification/RekorOfflineReceiptVerifier.cs` -- verifies Rekor receipts using locally cached data.
- **Merkle Proof Verifier**: `StellaOps.Attestor.Core/Verification/MerkleProofVerifier.cs` -- verifies Merkle inclusion proofs locally.
- **Sigstore Bundle Verifier**: `__Libraries/StellaOps.Attestor.Bundle/SigstoreBundleVerifier.cs` -- verifies Sigstore bundles offline.
- **Tests**: `__Tests/StellaOps.Attestor.Offline.Tests/`, `__Tests/StellaOps.Attestor.TileProxy.Tests/`
## E2E Test Plan
- [ ] Verify an attestation offline via `OfflineVerifier` using cached roots from `FileSystemRootStore` and confirm verification passes
- [ ] Simulate air-gap: disable network, verify an attestation using locally cached tiles via `TileProxyService`, and confirm success
- [ ] Sync tiles via `TileSyncJob` while online, then verify those tiles are accessible offline via `TileEndpoints`
- [ ] Verify a Rekor receipt offline via `RekorOfflineReceiptVerifier` using cached checkpoint and Merkle proof
- [ ] Verify a Sigstore bundle offline via `SigstoreBundleVerifier` and confirm certificate chain and signature are valid
- [ ] Verify `RuleBundleSignatureVerifier` rejects a tampered policy rule bundle offline
- [ ] Verify `ContentAddressedTileStore` deduplicates tiles: store the same tile twice and verify only one copy exists
- [ ] Test `OfflineVerificationResult` captures detailed check results for each verification step (root validity, Merkle proof, signature)

View File

@@ -0,0 +1,39 @@
# Patch-Aware Backport Detection with Proof-Carrying VEX (Tier1-4)
## Module
Attestor
## Status
IMPLEMENTED
## Description
Full backport proof pipeline from extractors through tiered proof generation (Tier1: advisory match, Tier2: source proof, Tier3: binary proof, Tier4: signature match) with VEX integration. Patch verification orchestrator handles distro backports correctly.
## Implementation Details
- **BackportProofGenerator**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Generators/BackportProofGenerator.cs` -- orchestrator for multi-tier backport detection with partials:
- `.Tier1` -- distro advisory matching (0.98 confidence)
- `.Tier2` -- advisory-level evidence (0.90-0.95 confidence)
- `.Tier3` -- changelog/patch header matching (0.80-0.85 confidence)
- `.Tier3Signature` -- HunkSig binary signature matching
- `.Tier4` -- binary fingerprint comparison (0.55-0.85 confidence)
- `.Confidence` -- confidence scoring with multi-source bonus
- `.CombineEvidence` -- evidence aggregation across all tiers
- `.Status` -- detection status tracking
- `.VulnerableUnknown` -- unknown vulnerability handling
- **Evidence Summary**: `Generators/EvidenceSummary.cs` -- aggregated evidence from all tiers with confidence and tier breakdown.
- **VEX Proof Integrator**: `Generators/VexProofIntegrator.cs` (with `.Helpers`, `.Metadata`) -- integrates backport detection evidence into VEX decisions, producing proof-carrying VEX.
- **VEX Verdict Proof Payload**: `Generators/VexVerdictProofPayload.cs` -- combined VEX verdict + backport proof payload.
- **Binary Fingerprint Evidence Generator**: `Generators/BinaryFingerprintEvidenceGenerator.cs` (with `.Helpers`) -- generates Tier 4 binary fingerprint evidence.
- **Fix Status Info**: `Predicates/FixStatusInfo.cs` -- tracks fix application status (patched, backported, unpatched).
- **FixChain Attestation**: `__Libraries/StellaOps.Attestor.FixChain/FixChainAttestationService.cs` -- creates attestations for confirmed fix applications.
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/BackportProofGeneratorTests.cs`
## E2E Test Plan
- [ ] Run Tier 1 detection with a known distro advisory (e.g., Debian DSA) and verify 0.98 confidence result
- [ ] Run Tier 3 detection with patch header + HunkSig and verify 0.85-0.90 confidence
- [ ] Run Tier 4 detection with binary fingerprint comparison and verify 0.55-0.85 confidence range
- [ ] Run all four tiers and verify `CombineEvidence` produces an aggregated `EvidenceSummary` with multi-source bonus
- [ ] Integrate backport evidence into a VEX decision via `VexProofIntegrator` with status "not_affected" (backport confirmed) and verify the `VexVerdictProofPayload`
- [ ] Test `VulnerableUnknown` handling: run detection with no evidence across all tiers and verify appropriate unknown status
- [ ] Create a `FixChainAttestationService` attestation for a confirmed backport and verify it links to the backport proof
- [ ] Verify confidence scoring with multi-source bonus: Tier1 + Tier3 evidence together produces higher confidence than either alone

View File

@@ -0,0 +1,33 @@
# Patch Oracle (Binary Diff for CVE Function Identification)
## Module
Attestor
## Status
IMPLEMENTED
## Description
Patch verification orchestration with patch signature storage and binary diff predicate building is implemented, enabling CVE function identification through patch comparison.
## Implementation Details
- **Binary Diff Predicate Builder**: `src/Attestor/__Libraries/StellaOps.Attestor.StandardPredicates/BinaryDiff/BinaryDiffPredicateBuilder.cs` (with `.Build`) -- builds binary diff predicates comparing patched vs unpatched binaries to identify CVE-affected functions. Implements `IBinaryDiffPredicateBuilder.cs`.
- **Binary Diff Predicate Serializer**: `BinaryDiff/BinaryDiffPredicateSerializer.cs` (with `.Normalize`) -- serializes binary diff predicates with deterministic normalization. Implements `IBinaryDiffPredicateSerializer.cs`.
- **Binary Diff Finding**: `BinaryDiff/BinaryDiffFinding.cs` -- individual diff finding (function added/removed/changed, offset, size).
- **Binary Diff Section Models**: `BinaryDiff/BinaryDiffSectionModels.cs` -- section-level diff models (text, data, rodata sections).
- **Binary Diff Metadata Builder**: `BinaryDiff/BinaryDiffMetadataBuilder.cs` -- builds metadata for binary diff comparisons (tool version, binary architecture, compiler info).
- **Binary Diff Schema**: `BinaryDiff/BinaryDiffSchema.SchemaJson.cs` -- embedded JSON schema for binary diff predicates.
- **Binary Diff Schema Validation**: `BinaryDiff/BinaryDiffSchemaValidationResult.cs` -- validation result model.
- **Binary Diff DSSE Verifier**: `BinaryDiff/BinaryDiffDsseVerifier.cs` (with `.Helpers`) -- verifies DSSE-signed binary diff attestations. Implements `IBinaryDiffDsseVerifier.cs`.
- **Backport Tier 3 Signature**: `__Libraries/StellaOps.Attestor.ProofChain/Generators/BackportProofGenerator.Tier3Signature.cs` -- uses binary diff/HunkSig for backport detection.
- **Binary Fingerprint Evidence**: `Generators/BinaryFingerprintEvidenceGenerator.cs` (with `.Helpers`) -- generates fingerprint evidence for binary comparison.
- **Tests**: `__Tests/StellaOps.Attestor.StandardPredicates.Tests/BinaryDiffTests.cs`
## E2E Test Plan
- [ ] Build a binary diff predicate via `BinaryDiffPredicateBuilder` comparing a patched and unpatched binary; verify the diff identifies changed functions
- [ ] Verify `BinaryDiffFinding` entries capture function name, offset, and change type (added/removed/modified)
- [ ] Serialize a binary diff predicate via `BinaryDiffPredicateSerializer` and verify deterministic output (same diff = same bytes)
- [ ] Validate a binary diff predicate against `BinaryDiffSchema` and verify schema compliance
- [ ] Sign a binary diff predicate into a DSSE envelope and verify it via `BinaryDiffDsseVerifier`
- [ ] Build metadata via `BinaryDiffMetadataBuilder` and verify tool version, architecture, and compiler info are captured
- [ ] Tamper with a signed binary diff attestation and verify `BinaryDiffDsseVerifier` rejects it
- [ ] Verify `BinaryDiffSectionModels` captures diffs at the section level (text, data, rodata)

View File

@@ -0,0 +1,33 @@
# Per-Finding Explainability (SBOM Node, Match Rule, VEX Gate, Reachability Trace)
## Module
Attestor
## Status
IMPLEMENTED
## Description
Finding summaries, verdict decisions with inputs/outputs, and policy decisions are modeled for per-finding explainability.
## Implementation Details
- **Finding Summary**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Predicates/FindingSummary.cs` -- summary of a single finding with CVE, component, severity, and explanation.
- **Verdict Decision**: `Statements/VerdictDecision.cs` -- the security decision (Pass/Fail/Warn) for a finding.
- **Verdict Inputs**: `Statements/VerdictInputs.cs` -- all inputs considered for the decision (scan results, SBOM data, reachability analysis, VEX statements).
- **Verdict Outputs**: `Statements/VerdictOutputs.cs` -- outputs produced (policy violations, applied exceptions, risk justifications).
- **Policy Decision**: `Predicates/PolicyDecision.cs` -- individual policy rule evaluation result for a finding. `PolicyDecisionPredicate.cs` -- full predicate model.
- **Reasoning Predicate**: `Predicates/ReasoningPredicate.cs` -- reasoning chain explaining why a decision was made. `Statements/ReasoningStatement.cs` -- in-toto wrapper.
- **Evidence Predicate**: `Predicates/EvidencePredicate.cs` -- evidence supporting the decision. `Statements/EvidenceStatement.cs` -- in-toto wrapper.
- **VEX Verdict Summary**: `Predicates/VexVerdictSummary.cs` -- VEX verdict explaining exploitability status for the finding.
- **Reachability Witness**: `Statements/ReachabilityWitnessPayload.cs` (with `.Path`) -- reachability trace from entrypoint to vulnerable function.
- **SBOM Reference**: `Predicates/SbomReference.cs` -- link to the SBOM node (component) for the finding.
- **Explanation Graph**: `Graph/InMemoryProofGraphService.cs` (with `.Queries`, `.Subgraph`) -- query explanation paths from verdict to evidence.
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/FindingSummaryTests.cs`
## E2E Test Plan
- [ ] Create a `FindingSummary` with CVE, component, and severity; verify all fields are populated
- [ ] Build a `VerdictDecision` with `VerdictInputs` (SBOM match, scan result, VEX statement) and `VerdictOutputs` (policy violation); verify the decision is explainable
- [ ] Create a `PolicyDecisionPredicate` with a matching rule name and verify the rule is linked to the finding
- [ ] Build a `ReasoningPredicate` explaining why a finding was marked "not_affected" and verify it references evidence IDs
- [ ] Link a finding to its SBOM node via `SbomReference` and verify the component name, version, and bom-ref are correct
- [ ] Create a reachability trace via `ReachabilityWitnessPayload` showing the call path to the vulnerable function and verify it is linked to the finding
- [ ] Query the explanation graph via `InMemoryProofGraphService.Queries` from a verdict node to all evidence nodes and verify the complete explanation chain

View File

@@ -0,0 +1,30 @@
# Per-Layer DSSE Attestations
## Module
Attestor
## Status
IMPLEMENTED
## Description
Layer-specific DSSE attestations with batch signing for efficiency, generating individual attestations per container image layer linked to layer-specific SBOM subjects.
## Implementation Details
- **DSSE Envelope Signing**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Signing/ProofChainSigner.cs` (with `.Verification`) -- signs per-layer attestations into DSSE envelopes. Supports batch signing for multi-layer images.
- **DSSE Envelope**: `Signing/DsseEnvelope.cs` -- envelope model with payload, payloadType, and signatures array.
- **DSSE Signature**: `Signing/DsseSignature.cs` -- individual signature within an envelope.
- **Statement Builder**: `Builders/StatementBuilder.cs` (with `.Extended`) -- builds in-toto statements with layer-specific subjects (layer digest as subject).
- **Proof Subject**: `Builders/ProofSubject.cs` -- subject model with name (layer digest) and digest map.
- **Attestation Bundler**: `__Libraries/StellaOps.Attestor.Bundling/AttestationBundler.cs` -- bundles per-layer attestations into a single container-level bundle.
- **OCI Attachment**: `__Libraries/StellaOps.Attestor.Oci/Services/OrasAttestationAttacher.cs` -- attaches per-layer attestations to container image digests via OCI Referrers API.
- **Signing Key Profile**: `Signing/SigningKeyProfile.cs` -- key profile used for signing (supports per-layer key selection).
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/DsseSigningTests.cs`
## E2E Test Plan
- [ ] Create per-layer in-toto statements for a 3-layer container image with layer digests as subjects and sign each via `ProofChainSigner`
- [ ] Verify each per-layer DSSE envelope has the correct layer digest in the subject
- [ ] Batch-sign all 3 layer attestations and verify all envelopes are produced efficiently
- [ ] Bundle per-layer attestations into a container-level bundle via `AttestationBundler` and verify the bundle references all layers
- [ ] Attach per-layer attestations to the container image via `OrasAttestationAttacher` and verify they are discoverable as referrers
- [ ] Verify each per-layer attestation signature independently via `ProofChainSigner.Verification`
- [ ] Create a per-layer attestation linking to a layer-specific SBOM and verify the SBOM subject reference

View File

@@ -0,0 +1,33 @@
# Periodic Rekor Verification Job
## Module
Attestor
## Status
IMPLEMENTED
## Description
Scheduled background job that periodically re-verifies Rekor transparency log entries to detect post-compromise tampering, with metrics emission, health check integration, and a dedicated Doctor plugin for verification status monitoring.
## Implementation Details
- **Rekor Verification Job**: `src/Attestor/StellaOps.Attestor/StellaOps.Attestor.Core/Verification/RekorVerificationJob.cs` -- scheduled background job that re-verifies Rekor entries on a configurable interval.
- **Rekor Verification Service**: `Verification/RekorVerificationService.cs` -- service that performs the actual verification (inclusion proof, checkpoint consistency). Implements `IRekorVerificationService.cs`.
- **Verification Metrics**: `Verification/RekorVerificationMetrics.cs` -- emits metrics: entries verified, failures detected, verification duration.
- **Health Check**: `Verification/RekorVerificationHealthCheck.cs` -- ASP.NET health check reporting Rekor verification status.
- **Checkpoint Divergence Detector**: `StellaOps.Attestor.Core/Rekor/CheckpointDivergenceDetector.cs` -- detects checkpoint divergence between local and remote Rekor log. Implements `ICheckpointDivergenceDetector.cs`.
- **Divergence Alert Publisher**: `Rekor/CheckpointDivergenceAlertPublisher.cs` -- publishes alerts when checkpoint divergence is detected.
- **Rekor Inclusion Verification**: `Rekor/RekorInclusionVerificationResult.cs` -- result of verifying a single entry's inclusion proof.
- **Merkle Proof Verifier**: `Verification/MerkleProofVerifier.cs` -- verifies Merkle inclusion proofs for Rekor entries.
- **Offline Receipt Verifier**: `Verification/RekorOfflineReceiptVerifier.cs` -- verifies Rekor receipts without network access.
- **Verification Report**: `Verification/VerificationReport.cs` -- aggregate report of all verification results for a run.
- **Tests**: `__Tests/StellaOps.Attestor.Core.Tests/RekorVerificationJobTests.cs`
## E2E Test Plan
- [ ] Run `RekorVerificationJob` against a set of persisted Rekor entries and verify all entries are re-verified successfully
- [ ] Tamper with a persisted Rekor entry's inclusion proof and verify the job detects the failure via `RekorVerificationService`
- [ ] Verify `RekorVerificationMetrics` emits correct counts: entries_verified, failures_detected, duration_ms
- [ ] Verify `RekorVerificationHealthCheck` reports Healthy when all entries verify and Unhealthy when failures are detected
- [ ] Simulate checkpoint divergence via `CheckpointDivergenceDetector` (local checkpoint ahead of remote) and verify `CheckpointDivergenceAlertPublisher` fires
- [ ] Verify `MerkleProofVerifier` correctly validates inclusion proofs for Rekor entries
- [ ] Verify `VerificationReport` contains a summary of all checks with pass/fail status per entry
- [ ] Run the verification job with network disabled and verify `RekorOfflineReceiptVerifier` handles offline mode

View File

@@ -0,0 +1,32 @@
# Policy Studio Copilot Attestation
## Module
Attestor
## Status
IMPLEMENTED
## Description
Policy draft attestation types for AI-generated lattice rules with test case generation and signed snapshots.
## Implementation Details
- **AI Policy Draft Statement**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Statements/AI/AIPolicyDraftStatement.cs` -- in-toto statement wrapping an AI-generated policy draft.
- **AI Policy Rule Draft**: `Predicates/AI/AIPolicyRuleDraft.cs` -- individual AI-generated policy rule with condition, action, and severity.
- **Policy Rule Type**: `Predicates/AI/PolicyRuleType.cs` -- enum of rule types (Gate, Advisory, Informational).
- **Policy Rule Test Case**: `Predicates/AI/PolicyRuleTestCase.cs` -- auto-generated test case for validating the drafted policy rule.
- **Policy Validation Result**: `Predicates/AI/PolicyValidationResult.cs` -- result of validating the drafted policy against test cases.
- **AI Authority Classifier**: `Predicates/AI/AIAuthorityClassifier.cs` (with `.PolicyDraft`, `.PolicyDraftScore`) -- classifies AI-generated policy drafts by authority level (Suggestion, EvidenceBacked, AuthorityThreshold).
- **AI Model Identifier**: `Predicates/AI/AIModelIdentifier.cs` -- identifies the AI model that generated the policy draft (provider, model, version, weights digest).
- **AI Decoding Parameters**: `Predicates/AI/AIDecodingParameters.cs` -- captures model parameters (temperature, top-p, max tokens) for reproducibility.
- **DSSE Signing**: `Signing/ProofChainSigner.cs` -- signs policy draft attestations for immutability.
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/AIPolicyDraftTests.cs`
## E2E Test Plan
- [ ] Create an `AIPolicyDraftStatement` with multiple `AIPolicyRuleDraft` entries and verify the statement structure
- [ ] Generate `PolicyRuleTestCase` entries for a drafted rule and verify they cover positive and negative scenarios
- [ ] Validate the drafted policy via `PolicyValidationResult` and verify it passes all generated test cases
- [ ] Classify the policy draft via `AIAuthorityClassifier.PolicyDraft` and verify the authority level based on evidence quality
- [ ] Verify `AIModelIdentifier` captures the model that generated the draft (e.g., provider="anthropic", model="claude-opus-4-6")
- [ ] Verify `AIDecodingParameters` captures reproducibility parameters (temperature, seed)
- [ ] Sign the policy draft statement via `ProofChainSigner` and verify the DSSE envelope is valid
- [ ] Create policy drafts of different `PolicyRuleType` (Gate, Advisory, Informational) and verify type-specific behavior

View File

@@ -0,0 +1,32 @@
# Predicate Schema Validation (including Delta Validators)
## Module
Attestor
## Status
IMPLEMENTED
## Description
Schema validation for all predicate types including SBOM deltas, VEX deltas, reachability witnesses, and delta verdicts.
## Implementation Details
- **Predicate Schema Validator**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Json/PredicateSchemaValidator.cs` -- core validator that validates predicate payloads against registered schemas.
- **Standard Validators**: `Json/PredicateSchemaValidator.Validators.cs` -- validators for standard predicate types: Evidence, Reasoning, VexVerdict, ProofSpine, SbomLinkage, Uncertainty, MicroWitness.
- **Delta Validators**: `Json/PredicateSchemaValidator.DeltaValidators.cs` -- validators for delta predicate types: DeltaVerdict, ChangeTrace, SbomDelta, VexDelta, ReachabilityDrift.
- **Schema Validation Result**: `Json/SchemaValidationResult.cs` -- result model with pass/fail status and validation errors list.
- **Schema Validation Error**: `Json/SchemaValidationError.cs` -- individual validation error with path, message, and severity.
- **SLSA Schema Validator**: `__Libraries/StellaOps.Attestor.StandardPredicates/Validation/SlsaSchemaValidator.cs` (with `.BuildDefinition`, `.Helpers`, `.Level`, `.RunDetails`) -- SLSA-specific schema validation. `SlsaValidationResult.cs` -- SLSA validation result.
- **Binary Diff Schema**: `__Libraries/StellaOps.Attestor.StandardPredicates/BinaryDiff/BinaryDiffSchema.SchemaJson.cs` -- embedded JSON schema for binary diff predicates. `BinaryDiffSchemaValidationResult.cs` -- validation result.
- **CycloneDX Validation**: `__Libraries/StellaOps.Attestor.StandardPredicates/Writers/CycloneDxWriter.Validation.cs` -- CycloneDX-specific validation.
- **SPDX Validation**: `Parsers/SpdxPredicateParser.Validation.cs` -- SPDX-specific validation.
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/PredicateSchemaValidatorTests.cs`
## E2E Test Plan
- [ ] Validate a well-formed Evidence predicate via `PredicateSchemaValidator` and verify it passes with no errors
- [ ] Validate a malformed Evidence predicate (missing required fields) and verify `SchemaValidationResult` contains specific `SchemaValidationError` entries with paths
- [ ] Validate all standard predicate types via `.Validators`: Evidence, Reasoning, VexVerdict, ProofSpine, SbomLinkage
- [ ] Validate all delta predicate types via `.DeltaValidators`: DeltaVerdict, ChangeTrace, SbomDelta, VexDelta, ReachabilityDrift
- [ ] Validate a SLSA provenance predicate via `SlsaSchemaValidator` and verify buildDefinition, runDetails, and level are checked
- [ ] Validate a binary diff predicate against `BinaryDiffSchema` and verify schema compliance
- [ ] Validate a CycloneDX predicate via `CycloneDxWriter.Validation` and verify BOM-specific rules are enforced
- [ ] Verify `SchemaValidationError` provides sufficient detail: JSON path, error message, and severity level

View File

@@ -0,0 +1,33 @@
# Private/Self-Hosted Rekor Support
## Module
Attestor
## Status
IMPLEMENTED
## Description
Enhanced Rekor proof builder supports configurable endpoints, enabling private/self-hosted Rekor instances for air-gap deployments.
## Implementation Details
- **Enhanced Rekor Proof Builder**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Rekor/EnhancedRekorProofBuilder.cs` (with `.Build`, `.Validate`) -- builds enhanced Rekor proofs supporting configurable Rekor endpoints (public or private/self-hosted).
- **Rekor Inclusion Proof**: `Rekor/RekorInclusionProof.cs` -- inclusion proof model with log index, tree size, root hash, and proof hashes.
- **Rekor Backend**: `StellaOps.Attestor.Core/Rekor/RekorBackend.cs` -- configurable backend supporting multiple Rekor instances (public, private, air-gapped).
- **Rekor Backend Resolver**: `Rekor/IRekorBackendResolver.cs` -- resolves which Rekor backend to use based on configuration.
- **Rekor Client**: `Rekor/IRekorClient.cs` -- abstraction for Rekor HTTP client supporting configurable base URL.
- **Rekor Tile Client**: `Rekor/IRekorTileClient.cs` -- client for fetching transparency log tiles from configurable endpoint.
- **Rekor Tile Cache**: `Rekor/IRekorTileCache.cs` -- caches tiles locally for offline access. `FileSystemRekorTileCache.cs` -- filesystem implementation.
- **Rekor Checkpoint Store**: `Rekor/IRekorCheckpointStore.cs` -- stores Rekor checkpoints for consistency verification.
- **Infrastructure Rekor**: `StellaOps.Attestor.Infrastructure/Rekor/` -- HTTP client implementation for Rekor communication.
- **TileProxy**: `StellaOps.Attestor.TileProxy/TileProxyService.cs` -- local tile proxy for self-hosted deployments.
- **Tests**: `__Tests/StellaOps.Attestor.Core.Tests/RekorBackendTests.cs`
## E2E Test Plan
- [ ] Configure a private Rekor endpoint via `RekorBackend` and verify `IRekorClient` submits entries to the private instance
- [ ] Submit an attestation to a self-hosted Rekor and verify `EnhancedRekorProofBuilder` generates an inclusion proof
- [ ] Validate the inclusion proof via `EnhancedRekorProofBuilder.Validate` against the private Rekor's checkpoint
- [ ] Resolve the correct backend via `IRekorBackendResolver` when multiple backends are configured (e.g., private for production, public for staging)
- [ ] Cache tiles from a private Rekor via `FileSystemRekorTileCache` and verify they are accessible offline
- [ ] Verify `TileProxyService` proxies tile requests to the configured private Rekor endpoint
- [ ] Test air-gap scenario: configure a fully offline Rekor backend with pre-seeded checkpoints and verify proof validation
- [ ] Verify checkpoint consistency: fetch checkpoints from a private Rekor at two different times and verify consistency proof

View File

@@ -0,0 +1,31 @@
# Proof Audit Trail / Transparency Log
## Module
Attestor
## Status
IMPLEMENTED
## Description
Generated proofs are stored in attestor.proof_blobs with tamper-evident hashing (proof_hash UNIQUE constraint). Each proof includes snapshot_id, evidence_count, confidence, and full payload JSONB. The ProofHashing.VerifyHash method allows verification that proof content has not been tampered with.
## Implementation Details
- **Audit Hash Logger**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Audit/AuditHashLogger.cs` (with `.Validation`) -- logs audit records with tamper-evident hashing. Records proof operations with content hashes for later verification.
- **Hash Audit Record**: `Audit/HashAuditRecord.cs` -- individual audit record containing operation type, content hash, timestamp, and actor.
- **Audit Artifact Types**: `Audit/AuditArtifactTypes.cs` -- enum of auditable artifact types (ProofBlob, DsseEnvelope, VerdictReceipt, SpineEntry, etc.).
- **Persistence**: `__Libraries/StellaOps.Attestor.Persistence/Entities/AuditLogEntity.cs` -- persisted audit log entry with tenant_id, created_at, updated_at, and JSONB payload.
- **Proof Chain Repository**: `__Libraries/StellaOps.Attestor.Persistence/Repositories/IProofChainRepository.cs` -- repository for proof chain entities including proof blobs.
- **Content-Addressed IDs**: `__Libraries/StellaOps.Attestor.ProofChain/Identifiers/ContentAddressedIdGenerator.cs` -- generates SHA-256 IDs for proof blobs ensuring hash uniqueness.
- **Rekor Integration**: `StellaOps.Attestor.Core/Rekor/RekorSubmissionService.cs` -- submits proof audit entries to Rekor for external transparency.
- **Verdict Ledger**: `__Libraries/StellaOps.Attestor.VerdictLedger/VerdictLedgerService.cs` -- append-only ledger for verdict decisions.
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/AuditHashLoggerTests.cs`
## E2E Test Plan
- [ ] Log a proof creation event via `AuditHashLogger` and verify the `HashAuditRecord` contains the correct content hash and operation type
- [ ] Verify tamper detection: modify a stored proof blob's content and verify `AuditHashLogger.Validation` detects the hash mismatch
- [ ] Create multiple audit records for different `AuditArtifactTypes` and verify each type is correctly categorized
- [ ] Persist audit records via `AuditLogEntity` and verify retrieval with correct tenant_id scoping
- [ ] Verify the proof_hash UNIQUE constraint: attempt to store two proof blobs with the same hash and verify the duplicate is rejected
- [ ] Submit an audit trail entry to Rekor and verify external transparency log integration
- [ ] Verify `VerdictLedgerService` creates append-only audit entries for verdict decisions
- [ ] Verify the full audit chain: create proof -> log audit -> persist -> retrieve -> verify hash integrity

View File

@@ -0,0 +1,32 @@
# Proof-Carrying Reachability Evidence
## Module
Attestor
## Status
IMPLEMENTED
## Description
Reachability evidence as portable, signed attestation bundles containing witness paths (call-path subgraphs from entrypoint to vulnerable node), gate conditions, and assumptions.
## Implementation Details
- **Reachability Witness Payload**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Statements/ReachabilityWitnessPayload.cs` (with `.Path`) -- witness payload containing the complete call path from entrypoint to vulnerable function.
- **Reachability Witness Statement**: `Statements/ReachabilityWitnessStatement.cs` -- in-toto statement wrapping the witness payload for DSSE signing.
- **Witness Call Path Node**: `Statements/WitnessCallPathNode.cs` -- individual node in the call path with function name, file, line number, and module.
- **Witness Path Node**: `Statements/WitnessPathNode.cs` -- generic path node in the reachability subgraph.
- **Witness Gate Info**: `Statements/WitnessGateInfo.cs` -- gate condition along the path (e.g., input validation, sanitization check, authentication guard).
- **Witness Evidence Metadata**: `Statements/WitnessEvidenceMetadata.cs` -- metadata about the analysis: tool, language, confidence, timestamp, assumptions.
- **Reachability Subgraph Predicate**: `Predicates/ReachabilitySubgraphPredicate.cs` -- minimal subgraph predicate for the reachability evidence.
- **Reachability Subgraph Statement**: `Statements/ReachabilitySubgraphStatement.cs` -- in-toto statement for subgraph attestation.
- **DSSE Signing**: `Signing/ProofChainSigner.cs` (with `.Verification`) -- signs reachability evidence into portable DSSE envelopes.
- **Attestation Bundler**: `__Libraries/StellaOps.Attestor.Bundling/AttestationBundler.cs` -- bundles reachability evidence with related attestations for portability.
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/ReachabilityWitnessTests.cs`
## E2E Test Plan
- [ ] Create a `ReachabilityWitnessPayload` with a 5-node call path (entrypoint -> service -> helper -> library -> vulnerable_func) and verify path structure
- [ ] Sign the witness as a `ReachabilityWitnessStatement` via `ProofChainSigner` and verify the DSSE envelope
- [ ] Add `WitnessGateInfo` entries for security checks along the path and verify gates are captured with condition descriptions
- [ ] Verify `WitnessEvidenceMetadata` captures analysis assumptions (e.g., "static analysis only, no runtime data")
- [ ] Bundle reachability evidence with related SBOM and VEX attestations via `AttestationBundler` and verify the bundle is self-contained
- [ ] Verify the signed bundle is portable: export, import to a different environment, and verify all signatures
- [ ] Create evidence for an unreachable path (no path from entrypoint to vulnerable function) and verify the witness payload captures the negative result

View File

@@ -0,0 +1,34 @@
# Proof-Carrying Security Decisions (Proof Chain)
## Module
Attestor
## Status
IMPLEMENTED
## Description
The ProofChain library is the core of the system with graph, signing, verification, merkle proofs, content-addressed IDs, DSSE, Rekor integration, predicates, statements, and a web service for querying. Every security decision carries linked proof.
## Implementation Details
- **Proof Graph**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Graph/InMemoryProofGraphService.cs` (with `.Mutation`, `.Queries`, `.Subgraph`) -- graph linking verdicts to reasoning to evidence nodes.
- **DSSE Signing**: `Signing/ProofChainSigner.cs` (with `.Verification`) -- signs all security decisions into DSSE envelopes.
- **Verification Pipeline**: `Verification/VerificationPipeline.cs` (with `.Verify`) -- multi-step verification pipeline for proof chains.
- **Verification Steps**: `Verification/DsseSignatureVerificationStep.cs`, `IdRecomputationVerificationStep.cs`, `RekorInclusionVerificationStep.cs`, `TrustAnchorVerificationStep.cs`, `AIArtifactVerificationStep.cs` -- individual verification steps.
- **Content-Addressed IDs**: `Identifiers/ContentAddressedIdGenerator.cs` (with `.Graph`), `ArtifactId.cs`, `EvidenceId.cs`, `ProofBundleId.cs`, `ReasoningId.cs`, `VexVerdictId.cs` -- SHA-256 IDs linking all artifacts.
- **Merkle Proofs**: `Merkle/DeterministicMerkleTreeBuilder.cs` (with `.Helpers`, `.Proof`) -- Merkle inclusion proofs for evidence chains.
- **Rekor Integration**: `Rekor/EnhancedRekorProofBuilder.cs` (with `.Build`, `.Validate`) -- Rekor transparency log integration.
- **Predicates**: 93+ predicate files in `Predicates/` -- all predicate types.
- **Statements**: 46 statement files in `Statements/` -- all in-toto statement types.
- **Web Service**: `StellaOps.Attestor.WebService/Controllers/ProofsController.cs`, `VerifyController.cs`, `BundlesController.cs`, `ChainController.cs` -- REST API for proof chain operations.
- **Receipts**: `Receipts/VerificationReceipt.cs`, `VerificationCheck.cs`, `VerificationContext.cs` -- machine-verifiable verification receipts.
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/`
## E2E Test Plan
- [ ] Create a complete proof chain: evidence -> reasoning -> verdict, sign each into DSSE envelopes, and verify the chain via `VerificationPipeline`
- [ ] Verify each step in the pipeline: `DsseSignatureVerificationStep` (signature valid), `IdRecomputationVerificationStep` (IDs match), `TrustAnchorVerificationStep` (anchor valid)
- [ ] Query the proof graph from a verdict to all supporting evidence via `InMemoryProofGraphService.Queries` and verify the complete chain
- [ ] Generate content-addressed IDs for all artifacts and verify they are deterministic and unique
- [ ] Build Merkle proofs for evidence in the chain and verify inclusion
- [ ] Submit the proof chain to Rekor and verify `RekorInclusionVerificationStep` passes
- [ ] Query proofs via `ProofsController` REST API and verify the response contains linked proof chains
- [ ] Verify via `VerifyController` and confirm a `VerificationReceipt` with all checks passing is returned

View File

@@ -0,0 +1,34 @@
# Proof Chain CLI Commands with Structured Exit Codes
## Module
Attestor
## Status
IMPLEMENTED
## Description
CLI commands for proof chain operations (`stellaops proof verify`, `stellaops proof spine`, `stellaops anchor`, `stellaops receipt`) with structured exit codes (0=success, 1=policy violation, 2=system error) enabling CI/CD integration.
## Implementation Details
- **Proof Chain Verification**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Verification/VerificationPipeline.cs` (with `.Verify`) -- verification pipeline invoked by CLI commands.
- **Verification Pipeline Request**: `Verification/VerificationPipelineRequest.cs` -- request model for CLI-initiated verification.
- **Verification Pipeline Result**: `Verification/VerificationPipelineResult.cs` -- result model with structured status for CLI exit code mapping.
- **Verification Step Result**: `Verification/VerificationStepResult.cs` -- individual step result for structured output.
- **Verification Pipeline Interfaces**: `Verification/VerificationPipelineInterfaces.cs` -- interfaces for pipeline steps.
- **Proof Spine Assembly**: `Assembly/ProofSpineRequest.cs`, `ProofSpineResult.cs` -- spine assembly for `stellaops proof spine` command.
- **Spine Verification**: `Assembly/SpineVerificationCheck.cs`, `SpineVerificationResult.cs` -- spine verification results.
- **Verification Receipt**: `Receipts/VerificationReceipt.cs` -- receipt generation for `stellaops receipt` command.
- **Trust Anchor Verification**: `Verification/TrustAnchorVerificationStep.cs` -- trust anchor verification for `stellaops anchor` command.
- **Verification Bundle Models**: `Verification/VerificationBundleModels.cs` -- bundle models for CLI input/output.
- **Web Service Endpoints**: `StellaOps.Attestor.WebService/Controllers/VerifyController.cs`, `ChainController.cs` -- REST endpoints backing CLI commands.
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/VerificationPipelineTests.cs`
## E2E Test Plan
- [ ] Run `stellaops proof verify` on a valid signed proof chain and verify exit code 0 (success)
- [ ] Run `stellaops proof verify` on a proof chain with a policy violation and verify exit code 1
- [ ] Run `stellaops proof verify` with an invalid input file and verify exit code 2 (system error)
- [ ] Run `stellaops proof spine` to assemble a proof spine and verify the output contains a Merkle root
- [ ] Run `stellaops anchor` to verify trust anchors and verify structured output with anchor status
- [ ] Run `stellaops receipt` to generate a verification receipt and verify the receipt JSON contains all checks
- [ ] Verify `VerificationPipelineResult` maps correctly to CLI exit codes: all steps pass -> 0, policy violation -> 1, exception -> 2
- [ ] Integrate `stellaops proof verify` into a CI pipeline and verify the exit code gates the pipeline correctly

View File

@@ -0,0 +1,39 @@
# Proof Chain Database Schema (PostgreSQL Persistence)
## Module
Attestor
## Status
IMPLEMENTED
## Description
PostgreSQL-backed persistence layer for proof chain data with 5 core tables (sbom_entries, dsse_envelopes, spines, trust_anchors, rekor_entries), EF Core entity mappings, and IProofChainRepository abstraction.
## Implementation Details
- **DbContext**: `src/Attestor/__Libraries/StellaOps.Attestor.Persistence/ProofChainDbContext.cs` -- EF Core DbContext with tenant-scoped queries, RLS policy application, and schema isolation.
- **Entities**:
- `Entities/DsseEnvelopeEntity.cs` -- persisted DSSE envelope with tenant_id, payload hash, created/updated timestamps.
- `Entities/RekorEntryEntity.cs` -- persisted Rekor log entry with log index, integrated time, inclusion proof.
- `Entities/SbomEntryEntity.cs` -- persisted SBOM entry with format, version, component count.
- `Entities/SpineEntity.cs` -- persisted proof spine with Merkle root, segment count, linked evidence IDs.
- `Entities/TrustAnchorEntity.cs` -- persisted trust anchor with key material, expiry, and trust level.
- `Entities/VerdictLedgerEntry.cs` -- persisted verdict ledger entry with decision, timestamp, and proof references.
- `Entities/AuditLogEntity.cs` -- audit log with operation type and content hash.
- **Repositories**:
- `Repositories/IProofChainRepository.cs` -- repository abstraction for CRUD operations on all proof chain entities.
- `Repositories/IVerdictLedgerRepository.cs` -- repository for verdict ledger queries (by subject, by time range).
- `Repositories/PostgresVerdictLedgerRepository.cs` -- PostgreSQL implementation with optimized queries and tenant scoping.
- **Migrations**: `Migrations/` -- EF Core migrations defining schema, indexes, RLS policies, and constraints.
- **Services**: `Services/` -- data access services for higher-level operations.
- **Performance**: `Perf/` -- performance configurations (connection pooling, query optimization).
- **Tests**: `__Tests/StellaOps.Attestor.Persistence.Tests/`
## E2E Test Plan
- [ ] Create and persist a `DsseEnvelopeEntity` via `IProofChainRepository` and verify retrieval by ID
- [ ] Persist a `RekorEntryEntity` with log index and inclusion proof; retrieve and verify all fields
- [ ] Persist a `SpineEntity` with Merkle root and verify the root hash is stored correctly
- [ ] Create a `TrustAnchorEntity` and verify it is retrievable by key fingerprint
- [ ] Create `VerdictLedgerEntry` records via `PostgresVerdictLedgerRepository` and query by subject digest; verify correct results
- [ ] Verify tenant isolation: create entities for tenant A and verify they are not visible to tenant B
- [ ] Run migrations on an empty database and verify all 5 tables are created with correct columns, indexes, and constraints
- [ ] Verify JSONB columns store and retrieve complex predicate payloads correctly

View File

@@ -0,0 +1,33 @@
# Proof Chain REST API (Backend Services)
## Module
Attestor
## Status
IMPLEMENTED
## Description
REST API endpoints for querying proof chains by subject digest, retrieving evidence chain graphs, and verifying proof integrity with DSSE signature and Rekor inclusion checks.
## Implementation Details
- **Proofs Controller**: `src/Attestor/StellaOps.Attestor/StellaOps.Attestor.WebService/Controllers/ProofsController.cs` -- CRUD operations for proof chain entries (submit, query by subject, list).
- **Verify Controller**: `Controllers/VerifyController.cs` -- verification endpoints running the full verification pipeline on submitted proof bundles.
- **Bundles Controller**: `Controllers/BundlesController.cs` -- retrieves attestation bundles (multiple related attestations grouped together).
- **Chain Controller**: `Controllers/ChainController.cs` -- traverses evidence chains from verdict to leaf evidence nodes.
- **Anchors Controller**: `Controllers/AnchorsController.cs` -- manages trust anchors (create, query, revoke).
- **Verdict Controller**: `Controllers/VerdictController.cs` -- verdict-specific endpoints for querying and managing verdicts.
- **Proof Chain Controller**: `Controllers/ProofChainController.cs` -- additional proof chain query endpoints.
- **Verification Pipeline**: `__Libraries/StellaOps.Attestor.ProofChain/Verification/VerificationPipeline.cs` (with `.Verify`) -- multi-step verification invoked by VerifyController.
- **Proof Graph Queries**: `__Libraries/StellaOps.Attestor.ProofChain/Graph/InMemoryProofGraphService.cs` (with `.Queries`) -- graph queries backing ChainController.
- **Composition Root**: `StellaOps.Attestor.WebService/AttestorWebServiceComposition.cs` -- DI registration for all API services.
- **Tests**: `__Tests/StellaOps.Attestor.WebService.Tests/`
## E2E Test Plan
- [ ] POST a proof chain entry via `ProofsController` and verify 201 Created with the entry ID
- [ ] GET a proof chain by subject digest via `ProofsController` and verify the response contains all linked attestations
- [ ] POST a verification request via `VerifyController` and verify the response contains step-by-step verification results
- [ ] GET an attestation bundle via `BundlesController` and verify it contains all related attestations (SBOM, VEX, verdict)
- [ ] GET an evidence chain via `ChainController` and verify traversal from verdict to leaf evidence
- [ ] POST a trust anchor via `AnchorsController` and verify it is stored and queryable
- [ ] GET a verdict via `VerdictController` by subject digest and verify the decision and linked proof IDs
- [ ] Verify error handling: submit invalid proof data and verify appropriate 400/422 error responses

View File

@@ -0,0 +1,34 @@
# Proof Graph (Node/Edge Types for Evidence Lineage and Integrity)
## Module
Attestor
## Status
IMPLEMENTED
## Description
In-memory proof graph service with typed nodes (Artifact, SbomDocument, DsseEnvelope, RekorEntry, VexStatement, Subject) and edges (DESCRIBED_BY, ATTESTED_BY, WRAPPED_BY, etc.) supporting mutation, queries, paths, and subgraph extraction.
## Implementation Details
- **In-Memory Proof Graph Service**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Graph/InMemoryProofGraphService.cs` -- core graph service with partials:
- `.Mutation` -- add/remove nodes and edges, update metadata.
- `.Queries` -- query nodes by type, find paths, search by content hash.
- `.Subgraph` -- extract subgraphs rooted at a specific node.
- **Node Types**: `Graph/ProofGraphNodeType.cs` -- Evidence, Verdict, Policy, Artifact (representing SbomDocument, DsseEnvelope, RekorEntry, VexStatement, etc.).
- **Edge Types**: `Graph/ProofGraphEdgeType.cs` -- relationship types (DependsOn, Produces, Validates, DescribedBy, AttestedBy, WrappedBy, etc.).
- **Graph Node**: `Graph/ProofGraphNode.cs` -- node with content-addressed ID, type, metadata, and content hash.
- **Graph Edge**: `Graph/ProofGraphEdge.cs` -- directed edge with source, target, type, and optional metadata.
- **Graph Path**: `Graph/ProofGraphPath.cs` -- ordered sequence of nodes representing a traversal path.
- **Subgraph**: `Graph/ProofGraphSubgraph.cs` -- extracted subgraph with nodes and edges for a specific evidence lineage.
- **Content-Addressed IDs**: `Identifiers/ContentAddressedIdGenerator.Graph.cs` -- generates graph-scoped content-addressed node/edge IDs.
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/ProofGraphTests.cs`
## E2E Test Plan
- [ ] Create a proof graph with Artifact, Evidence, Reasoning, and Verdict nodes and verify all node types are stored
- [ ] Add edges with different `ProofGraphEdgeType` values and verify edge traversal returns correct neighbors
- [ ] Query nodes by type via `.Queries` and verify filtering works (e.g., all Evidence nodes)
- [ ] Find the shortest path between a Verdict and an Evidence node and verify the `ProofGraphPath` is correct
- [ ] Extract a subgraph rooted at a Verdict via `.Subgraph` and verify it includes all Evidence and Reasoning descendants
- [ ] Add a node via `.Mutation`, then remove it, and verify cascading edge removal
- [ ] Verify content-addressed node IDs: same content produces the same node ID across insertions
- [ ] Build a complex graph with cycles (e.g., mutual dependencies) and verify query operations handle cycles correctly

View File

@@ -0,0 +1,35 @@
# Proof Spine System (Assembly, Segment Construction, Explainable Quiet Alerts)
## Module
Attestor
## Status
IMPLEMENTED
## Description
Proof spine builder producing chained segments (SBOM_SLICE, MATCH, REACHABILITY, GUARD_ANALYSIS, RUNTIME_OBSERVATION, POLICY_EVAL), each DSSE-signed with hash-linked predecessors. Chains evidence IDs, reasoning IDs, VEX verdict IDs into signed proof bundles with Merkle root computation. VexProofSpineService in Policy engine enables explainable quiet alerts.
## Implementation Details
- **Proof Spine Assembly**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Assembly/` -- proof spine assembly:
- `ProofSpineRequest.cs` -- request specifying subjects and evidence to include in the spine.
- `ProofSpineResult.cs` -- result containing assembled spine with Merkle root and linked segments.
- `ProofSpineSubject.cs` -- individual subject within a spine (artifact digest, type).
- `MerkleTree.cs` -- Merkle tree used for spine root computation.
- `SpineVerificationCheck.cs` -- individual verification check for a spine segment.
- `SpineVerificationResult.cs` -- aggregate verification result for the complete spine.
- **Proof Spine Statement**: `Statements/ProofSpineStatement.cs` -- in-toto statement wrapping a proof spine.
- **Proof Spine Predicate**: `Predicates/ProofSpinePredicate.cs` -- predicate containing Merkle root, segment list, evidence IDs, reasoning IDs, and VEX verdict IDs.
- **DSSE Signing**: `Signing/ProofChainSigner.cs` -- signs each spine segment into a DSSE envelope with hash-linked predecessor.
- **Content-Addressed Identifiers**: `Identifiers/EvidenceId.cs`, `ReasoningId.cs`, `VexVerdictId.cs` -- IDs chained in the spine.
- **Persistence**: `__Libraries/StellaOps.Attestor.Persistence/Entities/SpineEntity.cs` -- persists spine data.
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/ProofSpineTests.cs`
## E2E Test Plan
- [ ] Assemble a proof spine via `ProofSpineRequest` with 5 subjects and verify `ProofSpineResult` contains a valid Merkle root
- [ ] Verify each spine segment is DSSE-signed and hash-linked to its predecessor
- [ ] Create spine segments of different types (SBOM_SLICE, MATCH, REACHABILITY, POLICY_EVAL) and verify segment type metadata
- [ ] Chain evidence IDs, reasoning IDs, and VEX verdict IDs into the spine and verify all IDs are present in `ProofSpinePredicate`
- [ ] Verify the spine via `SpineVerificationCheck` for each segment and confirm `SpineVerificationResult` passes
- [ ] Build a `ProofSpineStatement` and sign it; verify the DSSE envelope wraps the complete spine
- [ ] Persist the spine via `SpineEntity` and retrieve it; verify data integrity
- [ ] Tamper with one segment's hash and verify spine verification detects the break in the hash chain

View File

@@ -0,0 +1,35 @@
# Provenance/Attestation Pipelines (End-to-End)
## Module
Attestor
## Status
IMPLEMENTED
## Description
End-to-end attestation pipeline covering build provenance (SLSA), SBOM attestation, VEX attestation, verdict attestation, OCI referrer attachment, and sealed audit pack export/import.
## Implementation Details
- **Pipeline Models**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Pipeline/` -- pipeline orchestration:
- `ProofChainRequest.cs` -- pipeline request with artifact digest, evidence sources, and options.
- `ProofChainResult.cs` -- pipeline result with generated attestations, proof spine, and Merkle root.
- `PipelineSubject.cs` -- subject being attested through the pipeline.
- `RekorEntry.cs` -- Rekor transparency log entry from pipeline output.
- **SLSA Provenance**: `__Libraries/StellaOps.Attestor.StandardPredicates/Parsers/SlsaProvenancePredicateParser.cs` (with `.ExtractMetadata`, `.Validation`) -- parses SLSA build provenance.
- **SPDX3 Build Attestation**: `__Libraries/StellaOps.Attestor.Spdx3/BuildAttestationMapper.cs` (with `.MapFromSpdx3`, `.MapToSpdx3`) -- maps build attestations.
- **VEX Integration**: `__Libraries/StellaOps.Attestor.ProofChain/Generators/VexProofIntegrator.cs` (with `.Helpers`, `.Metadata`) -- integrates VEX into pipeline.
- **Attestation Bundling**: `__Libraries/StellaOps.Attestor.Bundling/AttestationBundler.cs` -- bundles pipeline outputs.
- **OCI Attachment**: `__Libraries/StellaOps.Attestor.Oci/Services/OrasAttestationAttacher.cs` -- attaches pipeline outputs as OCI referrers.
- **Evidence Pack**: `__Libraries/StellaOps.Attestor.EvidencePack/ReleaseEvidencePackBuilder.cs` -- builds sealed audit packs from pipeline outputs.
- **Submission Service**: `StellaOps.Attestor.Core/Submission/IAttestorSubmissionService.cs` -- validates and routes pipeline submissions.
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/PipelineTests.cs`
## E2E Test Plan
- [ ] Run the full pipeline via `ProofChainRequest` with SBOM, scan results, and VEX data; verify `ProofChainResult` contains all attestations
- [ ] Verify SLSA provenance is parsed and included in the pipeline output
- [ ] Verify VEX attestation is integrated into the verdict via `VexProofIntegrator`
- [ ] Verify all pipeline attestations are signed into DSSE envelopes
- [ ] Verify pipeline outputs are bundled via `AttestationBundler` into a single verifiable bundle
- [ ] Attach pipeline outputs to an OCI image via `OrasAttestationAttacher` and verify referrer discovery
- [ ] Export pipeline outputs as a sealed evidence pack via `ReleaseEvidencePackBuilder` and verify manifest integrity
- [ ] Verify `AttestorSubmissionService` rejects invalid pipeline inputs with appropriate error messages

View File

@@ -0,0 +1,34 @@
# Reachability-Aware Vulnerability Prioritization (Competitive Differentiator)
## Module
Attestor
## Status
IMPLEMENTED
## Description
Reachability witness payload with path information, micro-witness function evidence and verdicts, DSSE-signed reachability witnesses, and ground-truth reachability datasets for validation.
## Implementation Details
- **Reachability Witness Payload**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Statements/ReachabilityWitnessPayload.cs` (with `.Path`) -- witness payload with call path from entrypoint to vulnerable function.
- **Reachability Witness Statement**: `Statements/ReachabilityWitnessStatement.cs` -- in-toto statement for DSSE signing.
- **Micro-Witness Function Evidence**: `Predicates/MicroWitnessFunctionEvidence.cs` -- function-level evidence with call-stack depth and reachability status.
- **Micro-Witness Verdicts**: `Predicates/MicroWitnessVerdicts.cs` -- per-function verdicts (Reachable, Unreachable, Unknown) with confidence scores.
- **Micro-Witness Binary Ref**: `Predicates/MicroWitnessBinaryRef.cs` -- binary artifact reference.
- **Micro-Witness CVE Ref**: `Predicates/MicroWitnessCveRef.cs` -- CVE reference with affected function.
- **Micro-Witness Tooling**: `Predicates/MicroWitnessTooling.cs` -- analysis tool metadata (language, tool name, version).
- **Binary Micro-Witness Predicate**: `Predicates/BinaryMicroWitnessPredicate.cs` -- complete micro-witness combining all references.
- **Witness Call Path Nodes**: `Statements/WitnessCallPathNode.cs` -- call path node. `WitnessPathNode.cs` -- generic path node.
- **Witness Gate Info**: `Statements/WitnessGateInfo.cs` -- security gates along the path.
- **VEX Integration**: `Generators/VexProofIntegrator.cs` -- uses reachability evidence to prioritize VEX decisions.
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/BinaryMicroWitnessPredicateTests.cs`, `ReachabilityWitnessTests.cs`
## E2E Test Plan
- [ ] Create a `ReachabilityWitnessPayload` with a reachable call path and verify it can prioritize a CVE as high-priority
- [ ] Create a `MicroWitnessVerdicts` entry with "Unreachable" for a critical CVE and verify it deprioritizes the finding
- [ ] Create function evidence with `MicroWitnessFunctionEvidence` at call-stack depth 0 through 5 and verify depth tracking
- [ ] Sign a `ReachabilityWitnessStatement` into a DSSE envelope and verify the signature
- [ ] Build a complete `BinaryMicroWitnessPredicate` with binary ref, CVE ref, function evidence, and SBOM ref; verify all fields
- [ ] Verify `MicroWitnessTooling` distinguishes between language-specific tools (Java call graph vs Python AST analyzer)
- [ ] Integrate reachability evidence into a VEX decision via `VexProofIntegrator`: unreachable function -> "not_affected" status
- [ ] Create witnesses for multiple CVEs on the same component and verify per-CVE prioritization

View File

@@ -0,0 +1,33 @@
# Reachability Drift Detection and Delta Evidence
## Module
Attestor
## Status
IMPLEMENTED
## Description
Reachability drift predicates tracking new/removed call paths to vulnerable functions with drift analysis metadata, delta summaries between baselines, and reachability status flip tracking between scans.
## Implementation Details
- **Reachability Drift Predicate**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Predicates/ReachabilityDriftPredicate.cs` -- predicate capturing reachability status changes between scans (new paths, removed paths, unchanged paths).
- **Drift Analysis Metadata**: `Predicates/DriftAnalysisMetadata.cs` -- metadata about the drift analysis (baseline scan ID, current scan ID, timestamp, tool). Also in `Statements/DriftAnalysisMetadata.cs`.
- **Drift Image Reference**: `Predicates/DriftImageReference.cs` -- image reference for the baseline and current scan.
- **Drift Predicate Summary**: `Predicates/DriftPredicateSummary.cs` -- summary of drift counts (new paths, removed paths, flipped statuses).
- **Drift Scanner Info**: `Predicates/DriftScannerInfo.cs` -- scanner that produced the drift data. Also in `Statements/DriftScannerInfo.cs`.
- **Drifted Sink Predicate Summary**: `Predicates/DriftedSinkPredicateSummary.cs` -- summary of drifted vulnerable sinks.
- **Reachability Drift Payload**: `Statements/ReachabilityDriftPayload.cs` -- in-toto payload for drift data.
- **Reachability Drift Statement**: `Statements/ReachabilityDriftStatement.cs` -- in-toto statement wrapping the drift payload.
- **Drift Summary**: `Statements/DriftSummary.cs` -- statement-level drift summary. `DriftedSinkSummary.cs` -- per-sink drift summary.
- **Change Trace**: `ChangeTrace/ChangeTraceAttestationService.cs` (with `.Helpers`, `.Mapping`) -- creates change trace attestations for drift events.
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/ReachabilityDriftTests.cs`
## E2E Test Plan
- [ ] Create a `ReachabilityDriftPredicate` with 2 new paths, 1 removed path, and verify the drift data is correct
- [ ] Verify `DriftAnalysisMetadata` captures baseline and current scan IDs, timestamps, and tool info
- [ ] Verify `DriftPredicateSummary` correctly counts new, removed, and unchanged paths
- [ ] Detect a reachability status flip (Unreachable -> Reachable) between scans and verify it is flagged in the drift
- [ ] Build a `ReachabilityDriftStatement` and sign it; verify the DSSE envelope contains the drift payload
- [ ] Create drift data for multiple sinks and verify `DriftedSinkPredicateSummary` tracks per-sink drift
- [ ] Create a `ChangeTraceAttestationService` attestation for the drift event and verify it links to baseline and current evidence
- [ ] Verify `DriftImageReference` correctly identifies the container image versions being compared

View File

@@ -0,0 +1,34 @@
# Reachability Graph Service (Slice and Replay)
## Module
Attestor
## Status
IMPLEMENTED
## Description
Full reachability graph service with slice extraction, deterministic replay, storage, and REST API.
## Implementation Details
- **Reachability Subgraph Predicate**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Predicates/ReachabilitySubgraphPredicate.cs` -- predicate for attested reachability subgraphs (slices).
- **Reachability Subgraph Statement**: `Statements/ReachabilitySubgraphStatement.cs` -- in-toto statement wrapping the subgraph slice.
- **Proof Graph Service**: `Graph/InMemoryProofGraphService.cs` (with `.Queries`, `.Subgraph`) -- graph service supporting subgraph extraction (slice).
- **Graph Path**: `Graph/ProofGraphPath.cs` -- path through the reachability graph.
- **Graph Subgraph**: `Graph/ProofGraphSubgraph.cs` -- extracted minimal subgraph.
- **Replay Manifest**: `Replay/AIArtifactReplayManifest.cs` -- manifest for deterministic replay of reachability analysis.
- **Replay Result**: `Replay/ReplayResult.cs` -- result of replaying a reachability analysis.
- **Replay Verification**: `Replay/ReplayVerificationResult.cs` -- verification of replay fidelity.
- **Replay Status**: `Replay/ReplayStatus.cs` -- enum tracking replay outcome.
- **Replay Input Artifact**: `Replay/ReplayInputArtifact.cs` -- input artifact for replay (graph data, configuration).
- **Witness Payload**: `Statements/ReachabilityWitnessPayload.cs` (with `.Path`) -- witness data for reachability paths.
- **REST API**: `StellaOps.Attestor.WebService/Controllers/ChainController.cs` -- API for querying reachability chains.
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/ReachabilitySubgraphTests.cs`
## E2E Test Plan
- [ ] Extract a reachability slice from a proof graph via `InMemoryProofGraphService.Subgraph` and verify the minimal subgraph
- [ ] Build a `ReachabilitySubgraphPredicate` from the extracted slice and sign it into a DSSE envelope
- [ ] Replay a reachability analysis via `AIArtifactReplayManifest` and verify `ReplayResult` matches the original
- [ ] Verify replay fidelity via `ReplayVerificationResult` and confirm the replayed graph matches the original
- [ ] Query a reachability chain via `ChainController` REST API and verify the response contains path data
- [ ] Store a reachability subgraph attestation and retrieve it by subject digest
- [ ] Create `ReplayInputArtifact` entries for a reachability analysis and verify all inputs are captured for replay

View File

@@ -0,0 +1,32 @@
# Reachability Witness Proofs (Attestation Predicates, Call-Graph Evidence, UI Panels)
## Module
Attestor
## Status
IMPLEMENTED
## Description
Full attestation predicates for reachability witness payloads including call paths, drift detection, and gate metadata. Entrypoint-to-vulnerable-symbol evidence trails as proof chain statements. UI evidence panels with E2E tests showing visual proof of reachability.
## Implementation Details
- **Reachability Witness Payload**: `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Statements/ReachabilityWitnessPayload.cs` (with `.Path`) -- witness payload with complete call path data.
- **Reachability Witness Statement**: `Statements/ReachabilityWitnessStatement.cs` -- in-toto statement for DSSE signing.
- **Witness Call Path Node**: `Statements/WitnessCallPathNode.cs` -- node in the call path (function, file, line, module).
- **Witness Path Node**: `Statements/WitnessPathNode.cs` -- generic path node with position metadata.
- **Witness Gate Info**: `Statements/WitnessGateInfo.cs` -- security gate along the path (sanitizer, validator, auth check).
- **Witness Evidence Metadata**: `Statements/WitnessEvidenceMetadata.cs` -- metadata about analysis tool, language, confidence, and assumptions.
- **Reachability Drift**: `Predicates/ReachabilityDriftPredicate.cs` -- drift detection predicate. `Statements/ReachabilityDriftStatement.cs` -- drift statement.
- **Drift Metadata**: `Predicates/DriftAnalysisMetadata.cs`, `DriftPredicateSummary.cs`, `DriftedSinkPredicateSummary.cs` -- drift analysis models.
- **Micro-Witness**: `Predicates/BinaryMicroWitnessPredicate.cs` -- function-level witness. `Predicates/MicroWitnessFunctionEvidence.cs` -- function evidence.
- **DSSE Signing**: `Signing/ProofChainSigner.cs` -- signs witness attestations.
- **Tests**: `__Tests/StellaOps.Attestor.ProofChain.Tests/ReachabilityWitnessTests.cs`
## E2E Test Plan
- [ ] Create a `ReachabilityWitnessPayload` with a 6-node call path from entrypoint to vulnerable symbol and verify path structure
- [ ] Add `WitnessGateInfo` entries (input validation gate, authentication gate) and verify gates are captured with pass/fail conditions
- [ ] Sign the witness as `ReachabilityWitnessStatement` and verify the DSSE envelope is valid
- [ ] Create a drift detection witness showing a new call path to a previously unreachable vulnerability and verify drift metadata
- [ ] Verify `WitnessEvidenceMetadata` captures analysis confidence (e.g., 0.95 for static analysis, 0.70 for heuristic)
- [ ] Create micro-witness function evidence for each node in the call path and verify call-stack depth tracking
- [ ] Build a complete evidence trail: SBOM -> call graph -> witness -> VEX verdict and verify the chain is traversable

View File

@@ -0,0 +1,32 @@
# Rekor Entry Events with Reanalysis Hints
## Module
Attestor
## Status
IMPLEMENTED
## Description
Deterministic Rekor entry events (EntryLogged, EntryQueued, InclusionVerified, EntryFailed) with reanalysis hints (CVE IDs, product keys, artifact digests, scope) for policy reanalysis triggers.
## Implementation Details
- **Rekor Entry Event**: `src/Attestor/StellaOps.Attestor/StellaOps.Attestor.Core/Rekor/RekorEntryEvent.cs` -- event model with type (EntryLogged, EntryQueued, InclusionVerified, EntryFailed), payload, and reanalysis hints (CVE IDs, product keys, artifact digests, scope).
- **Rekor Submission Response**: `Rekor/RekorSubmissionResponse.cs` -- response from Rekor submission containing log index and entry UUID.
- **Rekor Receipt**: `Rekor/RekorReceipt.cs` -- receipt from Rekor with verification data.
- **Rekor Proof Response**: `Rekor/RekorProofResponse.cs` -- proof response with inclusion proof data.
- **Rekor Sync Background Service**: `Rekor/RekorSyncBackgroundService.cs` -- background service that emits events during sync operations.
- **Checkpoint Divergence Detector**: `Rekor/CheckpointDivergenceDetector.cs` -- detects checkpoint divergence and emits failure events.
- **Rekor Inclusion Verification Result**: `Rekor/RekorInclusionVerificationResult.cs` -- result of verifying a Rekor entry's inclusion.
- **Queue**: `StellaOps.Attestor.Core/Queue/IRekorSubmissionQueue.cs` -- queue for managing entry submissions with event emission.
- **Persistence**: `__Libraries/StellaOps.Attestor.Persistence/Entities/RekorEntryEntity.cs` -- persisted Rekor entry with event history.
- **Tests**: `__Tests/StellaOps.Attestor.Core.Tests/RekorEntryEventTests.cs`
## E2E Test Plan
- [ ] Submit an attestation to Rekor and verify an `EntryLogged` event is emitted with the log index
- [ ] Queue a submission and verify an `EntryQueued` event is emitted before actual submission
- [ ] Verify inclusion of a Rekor entry and confirm an `InclusionVerified` event is emitted
- [ ] Simulate a submission failure and verify an `EntryFailed` event is emitted with error details
- [ ] Verify reanalysis hints contain CVE IDs, product keys, and artifact digests from the submitted attestation
- [ ] Verify the event scope field correctly narrows the reanalysis trigger (e.g., scope="component:openssl" only triggers reanalysis for openssl-related policies)
- [ ] Verify `RekorSyncBackgroundService` emits events during sync operations (new entries found, checkpoint updates)
- [ ] Persist events via `RekorEntryEntity` and verify event history is retrievable

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