stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 1 Releases Wiki Activity
Files
1d962ee6fc98ad8c53715bbff6d513246f5b1361
git.stella-ops.org/docs/modules/attestor/payloads.md
master f98cea3bcf Add Authority Advisory AI and API Lifecycle Configuration 
- Introduced AuthorityAdvisoryAiOptions and related classes for managing advisory AI configurations, including remote inference options and tenant-specific settings.
- Added AuthorityApiLifecycleOptions to control API lifecycle settings, including legacy OAuth endpoint configurations.
- Implemented validation and normalization methods for both advisory AI and API lifecycle options to ensure proper configuration.
- Created AuthorityNotificationsOptions and its related classes for managing notification settings, including ack tokens, webhooks, and escalation options.
- Developed IssuerDirectoryClient and related models for interacting with the issuer directory service, including caching mechanisms and HTTP client configurations.
- Added support for dependency injection through ServiceCollectionExtensions for the Issuer Directory Client.
- Updated project file to include necessary package references for the new Issuer Directory Client library.
2025-11-02 13:50:25 +02:00

5.4 KiB
Raw Blame History

Attestor Payload Reference

StellaOps evidence predicates must remain reproducible, explainable, and portable across online and fully air-gapped deployments. This guide lists each predicate type, indicates where the canonical JSON Schema lives, highlights the producing service, and links to the matching golden samples.

Quick Reference

Type ID Predicate URI Schema file Produced by Primary consumers
StellaOps.BuildProvenance@1 https://schemas.stella-ops.org/attestations/build-provenance@1 src/Attestor/StellaOps.Attestor.Types/schemas/stellaops-build-provenance.v1.schema.json Build pipelines, Scanner SBOM bake stage Attestor, Export Center, Policy Engine
StellaOps.SBOMAttestation@1 https://schemas.stella-ops.org/attestations/sbom-attestation@1 src/Attestor/StellaOps.Attestor.Types/schemas/stellaops-sbom-attestation.v1.schema.json Scanner.Worker SBOM composer Policy Engine, CLI, Export Center
StellaOps.ScanResults@1 https://schemas.stella-ops.org/attestations/scan-results@1 src/Attestor/StellaOps.Attestor.Types/schemas/stellaops-scan-results.v1.schema.json Scanner.Worker analyzers Policy Engine, CLI, Orchestrator
StellaOps.PolicyEvaluation@1 https://schemas.stella-ops.org/attestations/policy-evaluation@1 src/Attestor/StellaOps.Attestor.Types/schemas/stellaops-policy-evaluation.v1.schema.json Policy Engine explain pipeline CLI, Notify, Export Center
StellaOps.VEXAttestation@1 https://schemas.stella-ops.org/attestations/vex-attestation@1 src/Attestor/StellaOps.Attestor.Types/schemas/stellaops-vex-attestation.v1.schema.json Excititor consensus service Policy Engine, CLI, Console
StellaOps.RiskProfileEvidence@1 https://schemas.stella-ops.org/attestations/risk-profile@1 src/Attestor/StellaOps.Attestor.Types/schemas/stellaops-risk-profile.v1.schema.json Policy Engine risk pipeline Console, Notify, Export Center
StellaOps.CustomEvidence@1 https://schemas.stella-ops.org/attestations/custom-evidence@1 src/Attestor/StellaOps.Attestor.Types/schemas/stellaops-custom-evidence.v1.schema.json CLI custom evidence workflows and partner integrations Policy Engine (policy hooks), Export Center

Golden JSON fixtures that double as contract tests live under src/Attestor/StellaOps.Attestor.Types/fixtures/v1/<predicate>.sample.json. TypeScript and Go clients consume the generated sources in src/Attestor/StellaOps.Attestor.Types/generated/ts and src/Attestor/StellaOps.Attestor.Types/generated/go.

Envelope Conventions

  • DSSE envelopes are signed over canonical JSON (sorted keys, UTF-8, no insignificant whitespace).
  • The subject array must include at least one SHA-256 digest and may attach annotations such as oci.reference or stellaops.asset.
  • predicateType uses the URI shown in the table; predicate.typeId mirrors the short identifier.
  • predicate.schemaVersion follows semantic versioning. Consumers reject mismatched major versions.
  • Optional metadata and materials sections follow the in-toto Statement format to maximise provenance portability.

Predicate Highlights

  • StellaOps.BuildProvenance@1 records builder identity, config source, materials, reproducibility flags, and the resulting artifact digests. Outputs must match the DSSE subject.
  • StellaOps.SBOMAttestation@1 links an artifact digest to a CycloneDX 1.6 or SBOM 3.0.0 document, tracking inventory counts and the generator metadata. Component graph hashes reference CAS entries emitted by Scanner.Worker.
  • StellaOps.ScanResults@1 captures deterministic findings from OS, language, and native analyzers. It reports summary counts, per-finding metadata (PURL, severity, exploitability), and the layer digests inspected.
  • StellaOps.PolicyEvaluation@1 documents lattice-based policy outcomes, including decision traces and evidence digests consumed during evaluation.
  • StellaOps.VEXAttestation@1 mirrors OpenVEX-aligned statements with justification, scope narrowing (package coordinates or component IDs), and issue timestamps.
  • StellaOps.RiskProfileEvidence@1 summarises exploitability, ticketing load, runtime coverage, and maturity for downstream dashboards.
  • StellaOps.CustomEvidence@1 allows regulated tenants to attach organisation-specific payloads referenced by a CAS-hosted schema while preserving provenance and retention controls.

Validation and Tooling

  • Run npm install once, then npm run docs:attestor:validate to validate JSON fixtures against their schemas, execute the generated TypeScript tests (npm test), and run go test ./... for the Go SDK. The command fails fast when any schema, fixture, or generated SDK drifts.
  • Regenerate schemas and SDKs after edits with dotnet run --project src/Attestor/StellaOps.Attestor.Types/Tools/StellaOps.Attestor.Types.Generator.
  • Offline Kit builds (ops/devops/offline-kit/) mirror schemas, fixtures, and SDK bundles so air-gapped operators can run the same validation stack.

Related Material

  • docs/modules/attestor/architecture.md — service topology, Rekor integration, caching model.
  • docs/modules/platform/architecture-overview.md — cross-module data flows and tenant boundaries.
  • docs/ingestion/aggregation-only-contract.md — guardrails for advisory feeds consumed by policy evaluation.
  • src/Attestor/StellaOps.Attestor.Types/samples/README.md — directory map for the golden evidence set referenced here.