40 lines
2.1 KiB
Markdown
40 lines
2.1 KiB
Markdown
# AirGap Quarantine Investigation Runbook
|
||
|
||
## Purpose
|
||
Quarantine preserves failed bundle imports for offline forensic analysis. It keeps the original bundle and the verification context (reason + logs) so operators can diagnose tampering, trust-root drift, or packaging issues without re-running in an online environment.
|
||
|
||
## Location & Structure
|
||
Default root: `/updates/quarantine`
|
||
|
||
Per-tenant layout:
|
||
`/updates/quarantine/<tenantId>/<timestamp>-<reason>-<id>/`
|
||
|
||
Removal staging:
|
||
`/updates/quarantine/<tenantId>/.removed/<quarantineId>/`
|
||
|
||
## Files in a quarantine entry
|
||
- `bundle.tar.zst` - the original bundle as provided
|
||
- `manifest.json` - bundle manifest (when available)
|
||
- `verification.log` - validation step output (TUF/DSSE/Merkle/rotation/monotonicity, etc.)
|
||
- `failure-reason.txt` - human-readable failure summary (reason + timestamp + metadata)
|
||
- `quarantine.json` - structured metadata for listing/automation
|
||
|
||
## Investigation steps (offline)
|
||
1. Identify the tenant and locate the quarantine root on the importer host.
|
||
2. Pick the newest quarantine entry for the tenant (timestamp prefix).
|
||
3. Read `failure-reason.txt` first to capture the top-level reason and metadata.
|
||
4. Review `verification.log` for the precise failing step.
|
||
5. If needed, extract and inspect `bundle.tar.zst` in an isolated workspace (no network).
|
||
6. Decide whether the entry should be retained (for audit) or removed after investigation.
|
||
|
||
## Removal & Retention
|
||
- Removal requires a human-provided reason (audit trail). Implementations should use the quarantine service’s remove operation which moves entries under `.removed/`.
|
||
- Retention and quota controls are configured via `AirGap:Quarantine` settings (root, TTL, max size); TTL cleanup can remove entries older than the retention period.
|
||
|
||
## Common failure categories
|
||
- `tuf:*` - invalid/expired metadata or snapshot hash mismatch
|
||
- `dsse:*` - signature invalid or trust root mismatch
|
||
- `merkle-*` - payload entry set invalid or empty
|
||
- `rotation:*` - root rotation policy failure (dual approval, no-op rotation, etc.)
|
||
- `version-non-monotonic:*` - rollback prevention triggered (force activation requires a justification)
|