3.7 KiB
3.7 KiB
Unknowns System (First-Class State, Budget Enforcement, Registry, Attestation Binding)
Module
Attestor
Status
VERIFIED
Description
Full unknowns tracking as first-class state: dedicated module with budget enforcement, ranking, taxonomy, budget-exceeded event publishing, IUnknownsAggregator interface, and UnknownItem records. Registry with trust-decay scoring, repository persistence, and ProofChain aggregation. Unknowns cryptographically bound to attestations via uncertainty statements, budget predicates, and JSON schemas. UI components for unknowns queue and budget widgets.
Implementation Details
- IUnknownsAggregator:
src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Services/IUnknownsAggregator.cs-- interface for aggregating unknown items across scan results and evidence gaps. - UnknownsAggregator:
Services/UnknownsAggregator.cs-- concrete implementation that collects, deduplicates, and ranks unknown items. - UnknownItem:
Services/UnknownItem.cs-- individual unknown item record with source, severity, category, and first-seen timestamp. - Budget Check Result:
Services/BudgetCheckResult.cs-- result of checking aggregated unknowns against budget thresholds. - Budget Violation:
Services/BudgetViolation.cs-- violation record when unknowns exceed budget limits. - Exception Ref:
Services/ExceptionRef.cs-- reference to an approved exception that excludes an unknown from budget enforcement. - Unknowns Budget Predicate:
Predicates/UnknownsBudgetPredicate.cs-- attestation predicate binding unknowns state to the proof chain. - Uncertainty Statement:
Statements/UncertaintyStatement.cs-- in-toto statement wrapping uncertainty evidence for attestation. - Uncertainty State Entry:
Statements/UncertaintyStateEntry.cs-- per-finding uncertainty state entry. - Uncertainty Evidence:
Statements/UncertaintyEvidence.cs-- evidence contributing to the uncertainty measurement. - Budget Definition:
Statements/BudgetDefinition.cs-- threshold definitions for unknowns budget enforcement. - Budget Observation:
Statements/BudgetObservation.cs-- observed unknowns counts at a point in time. - Budget Violation Entry:
Statements/BudgetViolationEntry.cs-- recorded violation when budget is exceeded. - Budget Exception Entry:
Statements/BudgetExceptionEntry.cs-- approved exception entry. - Predicate Schema Validator:
Json/PredicateSchemaValidator.cs-- validates unknowns predicates against JSON schemas. - Tests:
__Tests/StellaOps.Attestor.ProofChain.Tests/
E2E Test Plan
- Aggregate 10 unknown items via
UnknownsAggregatorfrom different sources and verify deduplication by source+CVE key - Verify unknowns ranking: add items with varying severities and confirm they are ordered by severity (critical first)
- Set a budget (max_critical=3) and aggregate 5 critical unknowns; verify
BudgetCheckResultreports violation - Register an
ExceptionReffor one critical unknown and verify budget count drops to 4 critical - Build an
UnknownsBudgetPredicatefrom aggregated unknowns and verify it contains correct item counts and budget status - Create an
UncertaintyStatementfrom unknowns and verify it is a valid in-toto statement with the correct predicate type URI - Validate the unknowns predicate against
PredicateSchemaValidatorand verify it passes schema validation - Aggregate unknowns from an empty scan and verify the aggregator returns zero items with a passing budget check
Verification
| Check | Result |
|---|---|
| Tier 0 - Source Verification | PASS |
| Tier 1 - Build + Code Review | PASS |
| Tier 2 - Behavioral Verification | PASS |
| Verified Date | 2026-02-13 |
| Run ID | run-001 |