---
title: "Release Evidence Handoff Runbook"
editUrl: false
description: "Export internal evidence and customer-safe handoff summaries from the scan history ledger."
---

Use this runbook when a release owner, design partner, or pilot reviewer needs a
compact evidence bundle after a staged scan run.

## Goal

Produce reviewer-ready evidence from the shared scan history ledger without
turning the OSS core into a compliance reporting product.

The handoff should answer four questions:

- what release, pilot, or handoff this evidence belongs to
- which target or artifact window was included
- whether the run included scan evidence and report evidence
- whether warnings block or qualify sign-off

## Preconditions

- `zap_scan_history_list` returns recent scan history entries.
- Postgres-backed scan history is enabled when evidence must survive restart,
  failover, or handoff.
- Postgres-backed scan-job state is enabled when queued jobs are part of release
  or pilot evidence, because `scan_job` evidence is projected from the queue
  store.
- The operator has `zap:scan:read` scope.
- The staged run already exercised the scan path being reviewed.

## Recommended Flow

1. Run the staged scan or pilot proof path.
2. Wait for queued scan jobs to reach a terminal state when the handoff is for
   final release sign-off.
3. Generate a report artifact.
4. Check the ledger window:

```text
Tool: zap_scan_history_list
Inputs:
- evidenceType: null
- status: null
- target: <target host or artifact substring>
- limit: 20
```

5. Export the internal evidence bundle:

```text
Tool: zap_scan_history_release_evidence
Inputs:
- releaseName: <release, pilot, or handoff label>
- target: <target host or artifact substring>
- limit: 100
```

6. Generate the customer-facing summary:

```text
Tool: zap_scan_history_customer_handoff
Inputs:
- handoffName: <release, pilot, or customer handoff label>
- target: <evidence-window selector; use a public target host/path where possible>
- limit: 100
```

7. Review the internal `summary` block before accepting the evidence window.
8. Review the customer summary `Acceptance Checklist`. A customer-facing package
   is not ready unless the checklist shows scan evidence, report evidence,
   at least one target with both scan and report evidence, terminal queued scan
   evidence, no direct-only scan targets, no unfinished queued scans, a non-empty
   evidence window, and no export-limit truncation risk. If any item is unchecked,
   fix the evidence window or record a named caveat in the internal handoff
   record.
9. Review the `Customer-Safe Redaction Contract` in the customer summary. It
   should confirm that raw ledger IDs, backend scan references, internal tenancy
   IDs, artifact paths, raw metadata, idempotency keys, and internal selectors
   are excluded from the customer artifact.
10. Review every `warnings` item and either fix the run or record an accepted
   caveat.
11. Attach the raw JSON bundle to the internal release or pilot record.
12. Attach the curated summary to customer-facing packages by default. Attach
    raw JSON only after explicit review and redaction approval for internal
    fields such as `clientId`, `workspaceId`, `backendReference`,
    `artifactLocation`, idempotency keys, and truncated errors. The curated
    summary never prints the raw selector used for filtering.

## Warning Interpretation

| Warning | Meaning | Expected action |
| --- | --- | --- |
| No scan history entries matched | The filter window is empty or the ledger is not recording. | Check target filter, retention, backend, and `zap_scan_history_list`. |
| No scan evidence entries were included | The bundle has no `scan_job` or `scan_run` evidence. | Run or queue a scan before sign-off. |
| No report artifact entries were included | A reviewer cannot tie the run to a generated report. | Generate a report and export again. |
| Queued scan jobs are not terminal | The bundle includes queued/running work. | Wait for completion, cancel/retry intentionally, or record the caveat. |
| Evidence entry count reached the export limit | The selected window may be truncated. | Increase `limit` or narrow the target filter. |

## Minimum Handoff Record

- release or pilot label
- source commit or deployed image tag
- environment name
- target filter used for internal export
- export time
- customer handoff summary generated by `zap_scan_history_customer_handoff`
- acceptance checklist result
- redaction contract reviewed
- `entryCount`
- `targets`
- `warnings`
- report artifact location
- accepted caveats, if any
- reviewer and sign-off decision

## Pass / Caveat / Fail

- `Pass`: scan evidence exists, report artifact exists, no non-terminal queued
  jobs are included, and warnings are empty or irrelevant after review.
- `Pass with caveat`: evidence is useful, but a warning is accepted and written
  down with owner, reason, and follow-up.
- `Fail`: scan evidence is missing, report artifact is missing for a release
  sign-off, the evidence window is empty, or the operator cannot explain the
  warnings.

## Sign-Off Template

```text
Release / pilot evidence handoff

Label:
Environment:
Source commit or image:
Target filter:
Exported at:
Evidence bundle:
Customer handoff summary:
Acceptance checklist:
Redaction contract reviewed:

Summary:
- entryCount:
- targets:
- hasScanEvidence:
- hasReportArtifact:
- nonTerminalScanJobs:

Warnings:
- none / listed warnings with accepted caveats

Result:
- pass / pass with caveat / fail

Reviewer:
Date:
```

## Related Docs

- [Scan History Ledger](./scan-history-ledger/)
- [Production Readiness Checklist](./production-checklist/)
- [Production Simulation Runbook](./production-simulation-runbook/)
