52 lines
2.7 KiB
Markdown
52 lines
2.7 KiB
Markdown
# Orchestrator → Findings Ledger Export Contract
|
|
|
|
Status: Available (2025-12-03)
|
|
Scope: defines the deterministic payload Orchestrator emits for job/run exports that Findings Ledger ingests for provenance (LEDGER-34-101).
|
|
|
|
## Payload shape
|
|
```jsonc
|
|
{
|
|
"runId": "uuid", // job/run correlation id
|
|
"jobType": "string", // e.g., mirror-build, policy-sim, scan
|
|
"artifactHash": "sha256:...", // CAS digest of primary artifact
|
|
"policyHash": "sha256:...", // optional; policy bundle hash
|
|
"startedAt": "2025-12-02T00:00:00Z",
|
|
"completedAt": "2025-12-02T00:05:30Z",
|
|
"status": "succeeded|failed|canceled",
|
|
"manifestPath": "cas://.../manifest.json", // DSSE or CAS path
|
|
"logsPath": "cas://.../logs.ndjson",
|
|
"tenantId": "string",
|
|
"environment": "prod|stage|dev",
|
|
"idempotencyKey": "sha256:...", // runId+artifactHash
|
|
"signatures": [ { "type": "dsse", "keyId": "...", "signature": "..." } ]
|
|
}
|
|
```
|
|
|
|
## Determinism & ordering
|
|
- Entries sorted by `runId` when streamed; pagination stable via `runId, startedAt` ascending.
|
|
- `idempotencyKey = sha256(runId + artifactHash + tenantId)`; duplicate submissions are rejected with 409.
|
|
- Timestamps UTC ISO-8601; no clock-skew correction performed by Ledger.
|
|
|
|
## Transport
|
|
- REST: `POST /internal/jobengine/exports` (Orchestrator) → Findings Ledger ingest queue.
|
|
- Events: `orchestrator.export.created` carries the same payload; consumers must verify DSSE before persistence.
|
|
|
|
## Validation rules (Ledger side)
|
|
- Require DSSE signature (Ed25519) when `signatures` present; fail closed if verification fails.
|
|
- Enforce presence of `runId`, `artifactHash`, `startedAt`, `status`.
|
|
- Hash fields must match `^sha256:[A-Fa-f0-9]{64}$`.
|
|
- Allowed status transitions: pending→running→succeeded/failed/canceled; replays only allowed when `idempotencyKey` matches existing record.
|
|
|
|
## Mapping to Findings Ledger
|
|
- Stored in collection/table `orchestrator_exports` with index `(artifactHash, runId)` and TTL optional on logs if configured.
|
|
- Timeline entry type `ledger_export` references `runId`, `artifactHash`, `policyHash`, `manifestPath`, `logsPath`, DSSE envelope digest, and `idempotencyKey`.
|
|
- Cross-links: `bundleId` (if mirror build) or `scanId` (if scan job) may be added as optional fields; Ledger treats them as opaque strings.
|
|
|
|
## Security / scopes
|
|
- Required scope: `orchestrator:exports:write` for producer; Ledger ingress validates tenant headers and scope.
|
|
- Max payload: 1 MiB; logs must be CAS/DSSE referenced, not inline.
|
|
|
|
## Offline/air-gap considerations
|
|
- CAS/DSSE paths must resolve within offline kit bundles; no external URIs permitted.
|
|
- Deterministic ordering + idempotency allow replay without side effects; Ledger rejects writes when DSSE or hash mismatch.
|