up

docs/airgap/runbooks/import-verify.md

@@ -1,30 +1,40 @@
-# AirGap Import & Verify (runbook outline)
+# Offline Kit Import Verification Runbook
 
-Related advisory: `docs/product-advisories/25-Nov-2025 - Air‑gap deployment playbook for StellaOps.md` (AG1–AG12). Implements AIRGAP-VERIFY-510-014.
+This runbook supports AIRGAP-MANIFEST-510-010/014. It validates bundle integrity before import, fully offline.
 
-## Prerequisites
-- `offline-kit/manifest.json` + `manifest.dsse` and `mirror.manifest` present.
-- Trust roots: Rekor/TUF roots, Authority signing roots, AV/YARA public keys.
-- Tools: `cosign` (or Stella verifier), `sha256sum`, `yara`, `python3`.
+## Inputs
+- Manifest: `offline-kit/manifest.json`
+- Bundle archive: e.g., `offline-kit/bundle.tar.gz`
+- Optional DSSE/JWS signature + public key for the manifest.
 
-## Steps
-1) Verify manifest signature
-   - `cosign verify-blob --key trust-roots/manifest.pub --signature manifest.dsse manifest.json`
-   - Sample helper: `scripts/airgap/verify-offline-kit.sh <kit-root>`
-2) Check staleness and policy/graph hashes
-   - Compare `feeds[*].snapshot` dates to allowed window; ensure `policyHash`/`graphHash` match target site config; fail closed on mismatch unless override signed.
-3) Verify chunks and Merkle root
-   - For each chunk listed in manifest, `sha256sum -c`; recompute Merkle root per manifest recipe; compare to `rootHash` field.
-4) AV/YARA validation
-   - Run `yara -r rules/offline-kit.yar kit/`; confirm `avReport.sha256` matches signed report in manifest; block on any detection.
-5) Replay depth selection
-   - Modes: `hash-only` (default), `full-recompute`, `policy-freeze`. Select via `--replay-mode`; enforce exit codes 0=pass, 3=stale, 4=hash-drift, 5=av-fail.
-6) Ingress/egress receipts
-   - Generate DSSE receipt `{hash, operator, time, decision}`; store in Proof Graph; verify incoming receipts before import.
+## Quick steps (offline)
+
+```bash
+src/AirGap/scripts/verify-manifest.sh offline-kit/manifest.json offline-kit/bundle.tar.gz \
+  offline-kit/manifest.sig offline-kit/manifest.pub.pem
+```
+
+What it does:
+1. Computes SHA-256 of manifest and bundle, compares with `hashes.manifestSha256` and `hashes.bundleSha256`.
+2. If signature + pubkey are provided, verifies the manifest signature with OpenSSL.
+
+## Expected manifest fields
+- `tools[]`, `feeds[]`, `policies[]` with SHA-256.
+- `chunks[]` entries for every payload file (path, sha256, size, kind).
+- `stalenessWindowHours` and `avScan` status.
+- `hashes.manifestSha256` and `hashes.bundleSha256` must match the files on disk.
+- Optional `signatures[]` (dsse/jws-detached) with `envelopeDigest`.
+
+## Failure handling
+- Hash mismatch → stop; regenerate bundle.
+- Signature failure → stop; re-validate trust roots.
+- Missing AV scan → treat as policy violation; rerun scans and update manifest.
 
 ## Outputs
-- Exit code per replay mode outcome.
-- Receipt DSSE stored at `receipts/{tenant}/{timestamp}.dsse`.
-- Optional report `verify-report.json` summarizing checks.
+- Exit 0 when all checks pass.
+- Exit 2–5 for missing tools/hash/signature verification issues (see script).
 
-> Expand with concrete scripts once tasks 510-010..014 land.
+## References
+- Schema: `docs/airgap/manifest.schema.json`
+- Sample: `docs/airgap/samples/offline-kit-manifest.sample.json`
+- Script: `src/AirGap/scripts/verify-manifest.sh`