Skip to content

System Backup

System Backup is an admin-only foundation for moving the main EASM application state between self-hosted installations. It is intentionally conservative: it exports a portable ZIP bundle, previews imports before applying them, and never performs a destructive full database restore.

API

Admin endpoints:

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

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

Export Options

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

include_files adds stored object contents under files/ in the archive. File metadata is exported in data/files.json.

include_users exports sanitized user identity records only. Password hashes, refresh tokens, API keys, and secrets are never exported by this MVP. User records are not imported yet; they are included only for future mapping workflows.

include_scan_history controls scans and scan_jobs export.

include_settings writes non-secret application settings to the manifest. Secret values are excluded.

ZIP Format

A backup bundle is a ZIP archive with this layout:

manifest.json
checksums.json
data/organizations.json
data/scopes.json
data/organization_members.json
data/assets.json
data/asset_edges.json
data/vulnerabilities.json
data/scans.json
data/scan_jobs.json
data/reports.json
data/files.json
data/exposure_changes.json
files/<file-id>/<object-name>

manifest.json contains the backup format version, creation time, export options, table counts, exported file object references, warnings, and non-secret settings when selected.

checksums.json contains SHA-256 checksums for every archive entry except itself. Import preview and import verify checksums before reading data.

Included Data

The MVP exports these application tables:

  • organizations
  • scopes
  • organization_members
  • assets
  • asset_edges
  • vulnerabilities
  • scans
  • scan_jobs
  • reports metadata
  • files metadata
  • exposure_changes

Excluded Data

The backup intentionally excludes secrets and authentication material:

  • password hashes
  • refresh tokens
  • JWT secrets
  • API key hashes and cleartext API keys
  • provider secrets
  • webhook secrets
  • Telegram bot tokens
  • MinIO/S3 access keys and secret keys
  • GitHub release check token

There is no include_secrets UI option. If a request sends include_secrets, the backend adds a warning and still excludes secrets.

Import Preview

Import preview validates the ZIP before applying anything:

  • checks manifest.json
  • rejects unsafe ZIP paths to prevent Zip Slip
  • verifies checksums.json
  • counts organizations, assets, vulnerabilities, files, and tables
  • returns warnings and validation errors

Preview does not modify PostgreSQL or object storage.

Conflict Modes

skip_existing inserts rows that do not already exist by primary key and leaves existing rows unchanged.

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

overwrite_metadata_only updates only metadata-like fields for supported tables and otherwise skips existing rows. For example, asset metadata can be refreshed without replacing the whole asset record.

Import Behavior

A real import is only triggered after the admin confirms the preview in Settings -> Administration -> System Backup.

This MVP does not restore users. Rows with required created_by references are reassigned to the importing admin. organization_members are skipped because safe restoration requires a future user mapping flow.

If file objects are present in the archive, the importer writes them to the current configured object storage using their original object keys, then imports file metadata.

Security Controls

  • Admin-only routes.
  • No shell commands are executed.
  • No Docker socket or host update mechanism is required.
  • No remote code is executed.
  • Import ZIP size is capped by the backend. The current application limit is 1 GB. The bundled frontend Nginx proxy also sets client_max_body_size 1g; any additional reverse proxy in front of the app must allow a matching request body size.
  • ZIP paths are validated before extraction.
  • Checksums are verified before import.
  • Secrets are excluded by default and not supported in the MVP.

Limitations

System Backup is not a replacement for PostgreSQL and S3/MinIO infrastructure backups. Use native database dumps, object storage replication, and volume backups for disaster recovery.

Current MVP limitations:

  • no destructive full database restore
  • no user/password/API key restore
  • no user identity mapping for organization memberships
  • no partial organization selection
  • no scheduled automatic backups
  • no encryption-at-rest for exported ZIP files
  • large installations may need infrastructure-native backups instead of browser-driven export/import, especially when file artifacts make ZIP bundles larger than the configured upload limit

Future Work

Potential future improvements:

  • user mapping during import
  • optional encrypted backup bundles
  • per-organization export
  • background export jobs for large installations
  • backup retention policies
  • scheduled exports to external object storage