61 lines
3.6 KiB
Markdown
61 lines
3.6 KiB
Markdown
# Attestor Module — Agent Charter
|
|
|
|
## Mission
|
|
Manage the attestation and proof chain infrastructure for StellaOps:
|
|
- Accept DSSE-signed attestation bundles from Signer and other modules.
|
|
- Register attestations with Rekor v2 transparency log for tamper-evident anchoring.
|
|
- Provide verification APIs for proof chain validation (signature, payload, Rekor inclusion).
|
|
- Serve deterministic evidence bundles linking artifacts to SBOMs, VEX documents, and verdicts.
|
|
- Enable "Show Me The Proof" workflows with complete audit trails.
|
|
|
|
## Expectations
|
|
- Coordinate with Signer for cryptographic operations, Scanner/Excititor for attestation generation, and UI for proof visualization.
|
|
- Maintain deterministic serialization for reproducible verification outcomes.
|
|
- Support offline verification with bundled Rekor inclusion proofs.
|
|
- Provide REST APIs for proof chain queries, baseline selection, and trust indicators.
|
|
- Keep proof chain storage schema current with migrations.
|
|
|
|
## Key Components
|
|
- **StellaOps.Attestor**: Main attestation service and REST API endpoints
|
|
- **StellaOps.Attestor.Envelope**: DSSE envelope handling and serialization
|
|
- **StellaOps.Attestor.Types**: Core attestation models and schemas
|
|
- **StellaOps.Attestor.Verify**: Verification engine for signatures and Rekor proofs
|
|
- **__Libraries**: Shared attestation utilities and storage abstractions
|
|
- **__Tests**: Integration tests with Testcontainers for PostgreSQL
|
|
|
|
## Required Reading
|
|
- `docs/modules/attestor/README.md`
|
|
- `docs/modules/attestor/architecture.md`
|
|
- `docs/modules/attestor/implementation_plan.md`
|
|
- `docs/product/advisories/20-Dec-2025 - Stella Ops Reference Architecture.md`
|
|
- `docs/modules/platform/architecture-overview.md`
|
|
|
|
## Working Agreement
|
|
- 1. Update task status to `DOING`/`DONE` in both corresponding sprint file `/docs/implplan/SPRINT_*.md` and the local `TASKS.md` when you start or finish work.
|
|
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
|
|
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
|
|
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
|
|
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.
|
|
|
|
## Attestation Types
|
|
- **SBOM Attestations**: Link container images to SPDX/CycloneDX SBOMs
|
|
- **VEX Attestations**: Link OpenVEX statements to products
|
|
- **Verdict Attestations**: Link policy evaluation results to artifacts
|
|
- **Provenance Attestations**: SLSA provenance for build reproducibility
|
|
- **Reachability Attestations**: Link static analysis witness paths to findings
|
|
|
|
## Proof Chain Model
|
|
- **ProofNode**: Individual proof (SBOM, VEX, Verdict, Attestation) with digest and metadata
|
|
- **ProofEdge**: Relationship between nodes ("attests", "references", "supersedes")
|
|
- **ProofChain**: Complete directed graph from artifact to all linked evidence
|
|
- **ProofVerification**: Signature validation, payload hash check, Rekor inclusion proof
|
|
|
|
## Guardrails
|
|
- All attestations must use DSSE envelopes with multiple signature support.
|
|
- Rekor anchoring must be optional (support air-gapped deployments).
|
|
- Verification must work offline with bundled inclusion proofs.
|
|
- Proof chains must be deterministic (stable ordering, canonical serialization).
|
|
- Preserve determinism: sort outputs, normalize timestamps (UTC ISO-8601).
|
|
- Keep Offline Kit parity in mind—document air-gapped workflows for any new feature.
|
|
- Update runbooks/observability assets when operational characteristics change.
|