stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 3 Releases Wiki Activity
Files
8f0320edd57ca8a4e3899468d6c18c875aa606bc
git.stella-ops.org/src/Attestor/AGENTS.md
Codex Assistant 8f0320edd5 product advisories add change contiang folder
2026-01-08 09:06:03 +02:00

3.6 KiB
Raw Blame History

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.
    1. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
    1. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
    1. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
    1. 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.