Offline audit snapshots

Snapshots capture the safe collected inputs used by the rule engine. They are not saved reports: offline replay still executes the current rule engine and policy against captured collector state.

Single-project and portfolio snapshots use separate versioned contracts.

Single-project export

gitlab-project-audit audit group/project \
  --save-snapshot audit.snapshot.json

Replay fully offline with the same effective rule selection:

gitlab-project-audit audit group/project \
  --config .gitlab-project-audit.yml \
  --snapshot audit.snapshot.json \
  --format json

Portfolio export

Explicit projects:

gitlab-project-audit audit group/a group/b \
  --save-snapshot portfolio.snapshot.json

Filtered group:

gitlab-project-audit audit --group group \
  --topic python \
  --visibility private \
  --save-snapshot portfolio.snapshot.json

The portfolio container stores one safe project snapshot for every successfully collected project. If collection fails for one project, the portfolio snapshot records that project-level error instead of dropping it.

Portfolio offline replay

Replay explicit project targets:

gitlab-project-audit audit group/a group/b \
  --config .gitlab-project-audit.yml \
  --snapshot portfolio.snapshot.json \
  --format json

Or replay the saved selection in group mode:

gitlab-project-audit audit --group group \
  --config .gitlab-project-audit.yml \
  --snapshot portfolio.snapshot.json

The replay path does not construct a GitLab client and makes zero network requests.

When explicit project paths are supplied during replay, they must match the saved portfolio selection exactly.

Group metadata filters such as --topic, --visibility, --include-project, --exclude-project, and --include-archived cannot be combined with --snapshot. The saved portfolio is already a frozen selection, and offline replay does not re-query GitLab metadata.

Safety boundary

Snapshots serialize typed collector snapshots after sanitization. In particular, CI/CD variable values have already been discarded; only safe metadata such as variable key, masking, protection, hidden state, scope, and type can be exported.

This safety boundary applies to every embedded project snapshot inside a portfolio snapshot.

Compatibility

Single-project snapshots use schema version 1.1 and snapshot-1.1.schema.json.

Portfolio snapshots use schema version 1.1 and portfolio-snapshot-1.1.schema.json.

Unsupported versions and malformed embedded project snapshots fail explicitly.

Every embedded project snapshot records the stable rule IDs selected when it was captured. Replay requires the same effective rule selection. Configuration mismatch therefore fails rather than running rules against incomplete captured context.

Snapshots also persist audit provenance. Loading legacy 1.0 snapshots remains supported; those artifacts simply have no provenance metadata.