Skip to main content

Attestation Vault API

FleetForge stores every attestation (runs, steps, artifacts, policies, capability tokens) inside an append-only vault so teams can verify evidence even outside the runtime. The Attestation Vault API exposes that store with portable envelopes compatible with in-toto and SLSA predicates.

Why it exists​

  • Portability: Export attestations and receipts to external auditors, partner systems, or regulators without replaying runs.
  • Transparency: Hook directly into the SCITT writer so every exported envelope can be anchored in a transparency log.
  • Vendor-neutral verification: The same envelopes work with standard in-toto inspectors, SLSA verifiers, and W3C VC tooling.

API surface​

EndpointDescription
GET /v1/attestations/{id}Fetch a single envelope by attestation UUID. Returns the predicate, subject, capability chain, and signature metadata.
POST /v1/attestations/queryFilter attestations by subject (run/step/artifact), policy pack, capability token, or time window. Supports pagination and streaming filters.
POST /v1/attestations/exportBundle multiple envelopes plus referenced artifacts into a tarball suitable for offline verification. Optionally enqueue SCITT postings.
POST /v1/attestations/scittPush an envelope to the configured SCITT backend. The response includes the transparency receipt and log position.

All responses include:

  • predicate_type / predicate – in-toto/SLSA-compatible payload.
  • capability_tokens – Biscuit/W3C VC projections (when enabled) so downstream systems can verify scope/authority without calling FleetForge.
  • c2pa_manifest_ref – optional pointer to the manifest that stapled the attestation.
  • transparency – SCITT receipt metadata when a log entry exists.

Append-only guarantees​

The vault enforces:

  • Monotonic IDs: Attestation IDs are UUIDv7; inserts happen in order and are immutable.
  • Digest anchoring: Each envelope stores a SHA-256 digest of the predicate and signature envelope so clients can detect tampering.
  • Transparency hooks: Whenever FLEETFORGE_TRANSPARENCY_WRITER=1, new attestations enqueue SCITT jobs. The API exposes the job ID and final receipt.

Verification workflow​

  1. Query or export the relevant attestation set.
  2. Verify the signature envelope (either FleetForge’s signer or your BYOK key).
  3. Validate the predicate using in-toto/SLSA tooling.
  4. Optionally check the attached Biscuit/VC capability chain to confirm who approved the step.
  5. Verify the transparency receipt via the SCITT backend.

The fleetforge-ctl verify and fleetforge-ctl attestation export commands wrap these calls, but the API exists so customers can integrate verification into their own supply-chain pipelines.