Skip to content

System Backup

System Backup is the admin-only V3 backup/export/import path for moving current hxEASM product state between installations. It exports a portable ZIP bundle, validates imports before applying them, and restores database state transactionally so integrity failures do not appear as successful restores.

System Backup is not a replacement for PostgreSQL and object-storage infrastructure backups. Large production installations should still use native PostgreSQL dumps/PITR and MinIO/S3 backup or replication.

API

Admin endpoints:

  • POST /api/v1/admin/backup/export
  • POST /api/v1/admin/backup/import/preview
  • POST /api/v1/admin/backup/import

Import endpoints accept a backup ZIP upload as multipart form field file.

V3 Format

Current exports use:

easm-backup-v3

The ZIP layout remains intentionally simple:

manifest.json
checksums.json
data/<table>.json
files/<file-id>/<object-name>

manifest.json records format version, creation time, export options, section flags, table counts, optional file object references, warnings, and non-secret runtime settings when requested.

checksums.json contains SHA-256 checksums for archive entries. Import preview and import verify checksums before reading table data.

Export Options

{
  "include_files": true,
  "include_scan_history": true,
  "include_settings": true
}

include_files includes file object bytes under files/. File metadata is still exported in data/files.json.

include_scan_history controls scan execution/history tables: scans, scan_jobs, asset_scan_snapshots, and asset_scan_changes.

When include_scan_history is false, always-restored rows such as asset_history, files, and exposure_changes have scan_id and scan_job_id nulled in the backup/import preparation so they cannot create dangling scan foreign keys.

include_settings writes non-secret application settings to the manifest.

Included Data

Backup V3 includes current non-secret product state:

  • organizations
  • scopes
  • assets
  • asset_edges
  • asset_history
  • threats
  • vulnerability_details
  • threat_events
  • threat_comments
  • threat_comment_mentions
  • reports
  • files
  • exposure_changes
  • scheduled_scans
  • custom_scan_profiles
  • plugin_settings
  • scan_settings

When scan history is requested, V3 also includes:

  • scans
  • scan_jobs
  • asset_scan_snapshots
  • asset_scan_changes

Asset System Changes are stored in asset_history and are part of V3. Asset Scan Changes are stored in asset_scan_changes and are included only when scan history is requested.

assets.managed_context and assets.metadata.asset_info are exported exactly as Asset JSON state. They are not reconstructed from other metadata.

Threat state includes risk_score on the current 0-100 scale, analyst_evidence, type_details, scanner evidence, metadata, vulnerability details, close reason, status, and threat events.

Excluded Data

Backup V3 intentionally excludes installation identity/security state:

  • audit_logs
  • password hashes
  • refresh tokens
  • API key hashes and cleartext API keys
  • 2FA settings, challenges, and recovery codes
  • webhook secrets
  • provider credentials
  • JWT secrets
  • MinIO/S3 access keys and secret keys
  • Telegram bot tokens
  • GitHub/update-center credentials

Audit Log represents operational/security history of the installation and is not transplanted as normal organization product state.

organization_members and sanitized users can be present in archives for visibility/future tooling, but users and memberships are not restored by V3.

User Identity Policy

Backup V3 does not recreate historical user accounts.

During import, required user references are rewritten to the importing admin where ownership/action attribution is needed. Nullable user references that are historical context, such as Asset criticality actor and Asset History actor UUID, are nulled when the user is not restored. Human-readable actor snapshots such as usernames remain where the table already stores them.

This avoids dangling user foreign keys while preserving current installation identity boundaries.

Organization Asset Restore

Each organization has exactly one canonical Organization Asset.

On clean restore, the exported Organization Asset UUID is preserved and dependent edges, threats, history, scan history, files, and exposure changes continue to reference it.

When importing into an installation that already has an Organization Asset for the same organization ID, V3 remaps references from the backup Organization Asset UUID to the existing canonical Organization Asset and skips inserting the duplicate Organization Asset row. It does not create a second Organization Asset.

Import Behavior

Import preview validates the archive and reports table counts, warnings, and errors.

Actual V3 import:

  • validates archive paths and checksums;
  • rejects unsupported legacy backup formats instead of silently reinterpreting them;
  • prepares rows for current user identity and scan-history options;
  • remaps existing Organization Asset references when needed;
  • imports database rows in an FK-safe order inside one database transaction;
  • treats FK violations, invalid row data, and impossible unique collisions as fatal import errors;
  • restores file objects inside the staged restore path and attempts cleanup if a transactional restore fails after object writes.

Expected conflicts, such as rows already present under skip_existing, are counted separately from fatal integrity failures.

Conflict Modes

skip_existing inserts rows that do not already exist by primary key and leaves existing rows unchanged. The singleton scan_settings row is treated as current configuration state and is updated from the backup even in this mode.

merge updates existing rows by primary key with imported row values.

overwrite_metadata_only updates metadata-like fields for supported tables and otherwise skips existing rows.

Files

File metadata is part of V3.

When include_files is true, the archive also includes stored object bytes. When it is false, metadata is restored without object bytes; operators should use infrastructure object-storage backup for full artifact disaster recovery.

Plugin Settings

V3 includes plugin settings, but sensitive header-like values are redacted on export for header names such as Authorization, Cookie, token, secret, and password fields.

Scan settings and custom/scheduled scan profiles contain non-secret product configuration and are backed up.

Legacy Formats

V3 is the canonical backup contract for the current development schema.

Legacy V1/V2 bundles are rejected by V3 import with a clear error. Create a fresh easm-backup-v3 export before restore.

Limitations

Current limitations:

  • no user/password/API key restore;
  • no organization membership restore;
  • no encrypted backup bundles;
  • no scheduled automatic backups;
  • no partial organization selection;
  • no backup retention policy;
  • file bytes are optional and can make browser-driven ZIP exports too large for very large installations.