BackupScope

Start here: visual guide EN/RU · Русский: первый запуск

Download start.html and open it in your browser for installation, a failing demo, a passing comparison and next steps. Examples are synthetic and run locally.

Find Docker data paths missing from your restic snapshot before you need them.

You add a volume, move an application to a bind mount, or rename a stack. The backup job still succeeds. The new data may not be in the backup at all. BackupScope compares a redacted Docker mount inventory with an actual restic file listing and an explicit path-presence policy. It works alongside your existing backup tool, without a server, account or paid API. Check an exported listing offline, or capture a complete listing directly from your configured restic.

Version 0.2.1, an early release seeking real-world workflow feedback. No claim of universal backup coverage or production validation.

A reproducible reason to use it

The integration fixture creates a real restic repository, excludes one folder, and successfully runs restic check --read-data. BackupScope still catches the missing path. After a complete backup, the contract passes; the fixture then restores a generated file and compares its bytes. See validation.

The two checks answer different questions: repository integrity does not tell you whether every data source you intended to include was selected.

Try it

Python 3.11+; no runtime dependencies. From this source directory:

git clone https://github.com/HexCine/backupscope.git
cd backupscope
python -m pip install .
backupscope check --inventory examples/inventory.json --snapshot examples/missing.jsonl --policy examples/policy.json --at 2026-09-22T13:00:00Z

Expected exit 1: an absent documents mount and an old database dump. Replace missing.jsonl with present.jsonl for exit 0. --at freezes time for these fixtures; omit it for current operational checks.

For a portable report, add --format html --output coverage.html. The HTML has no scripts or remote assets and includes expandable JSON evidence. Output files are created exclusively; existing files are never overwritten by --output. The module form python -m backupscope is equivalent to the console command. An already generated example report is included; download or open it locally in a browser. It uses only the public synthetic fixtures.

Use your own Docker + restic setup

On a Docker host with Linux-container mount paths:

backupscope inventory --host homebox --output inventory.local.json
backupscope init --inventory inventory.local.json --output policy.local.json

Discovery uses only docker container ls and docker container inspect with a Name/Mounts projection. It includes stopped containers and read-only mounts; read-only application data can still need backup. --project NAME explicitly restricts discovery to that Compose project. Credentials, environment values, commands and Docker labels are not included in the exported inventory.

Review the generated policy. Use the exact restic snapshot hostname for host. Add tags identifying your backup stream. Adjust snapshot_path if restic runs in a container, or if a database volume maps to a logical dump. Automatic fallback is the exact host source path, never a guessed volume name.

With restic installed and your existing repository/password environment configured:

backupscope verify --inventory inventory.local.json --policy policy.local.json --latest --format html --output coverage.html

verify selects the latest snapshot for the policy's host and all required tags. It waits for the full, unfiltered restic ls --json command to exit 0 before checking any paths. A nonzero exit, timeout, malformed listing or size limit produces exit 2 without a report. A valid partial JSON prefix from a failed command is discarded. The report records the selected full snapshot ID and whether BackupScope observed successful capture completion.

For a reproducible incident report, replace --latest with --snapshot-id FULL_64_CHARACTER_ID. No short IDs or ID:/subdirectory filters are accepted. With an explicit ID, host and tags are still checked against the policy. Tags containing commas or surrounding whitespace require an explicit ID because restic's tag filter cannot preserve those exact values.

Credentials stay in your existing restic configuration, for example RESTIC_REPOSITORY and RESTIC_PASSWORD_FILE. Use --restic /path/to/restic if needed. The default restic timeout is 300 seconds; --timeout 600 changes it (maximum 3600). See direct verification and automation.

Offline check remains available if repository access belongs on another host:

restic ls --json --host homebox --tag daily latest > snapshot.local.jsonl
# Continue only after confirming that restic exited 0.
backupscope check --inventory inventory.local.json --snapshot snapshot.local.jsonl --policy policy.local.json --format html --output coverage.html

Do not filter paths, splice listings, or evaluate a partially written file. Offline reports explicitly say that restic completion was not observed by BackupScope. A supplied listing is not an authenticated or signed attestation.

BackupScope itself never reads backup file contents, performs a restore, stops containers, or mutates a backup repository. verify runs restic with --no-lock --no-cache; repository access and authentication belong to restic. Direct capture preserves bytes without shell redirection. For manual exports, use a shell that preserves native stdout as UTF-8.

What it checks

• Every discovered bind mount or named/anonymous volume has regular-file evidence at its exact mapped path, or an explicit ignore with a reason.
• Snapshot and inventory freshness, matching host identity and required tags.
• Optional minimum file/byte counts and required relative files, including dump size and modification-age requirements.
• New mounts, stale policy selectors, expired ignores and shared-volume users.
• Unknowns remain visible: symlinks, special mount types, empty directories, mismatched identities and missing freshness information never become green.

See policy and diagnostic reference. JSON report schema is 1.

Exit	Meaning
0	Supplied path-presence and freshness requirements met
1	Known missing paths, stale evidence or policy failures
2	Unknowns, malformed input or I/O error; reports retain known failures

Boundaries that matter

An observed path proves neither that all its current files were backed up, nor that their contents are intact. A root with one file can pass the default presence check even when another file was excluded. Add known required files and minimums, and retain restic check plus real restore drills. A recent snapshot containing an old SQL dump is caught only when you configure an mtime requirement. A nonempty SQL file does not prove database consistency.

Only one supplied snapshot/host is checked. Inventory excludes unmounted Docker volumes, container writable layers and undiscovered hosts. Scoped discovery has scoped coverage. Linux-container POSIX paths are supported, not native Windows container paths, UNC mounts or Kubernetes discovery. Full limits and caveats are in POLICY.md and SECURITY.md.

Existing tools and contribution

restic provides the storage and integrity engine. Backrest and Offen docker-volume-backup manage backups. Arkeep is a broader server/agent platform with a coverage-map roadmap; this idea is not unique. Databasus is a stronger fit if you need database backup scheduling and automated restore verification.

BackupScope's narrow choice is a small, read-only checker over snapshot listings with no migration to a new backup platform. If this proves more useful as an integration in an existing project, prefer that over duplicating an orchestrator. See research and the 30-day plan.

Development

python -m pip install -e . pytest==9.1.1 build==1.6.1
python -m pytest -q
python -m build
python scripts/verify_wheel.py
python scripts/restic_integration.py --restic /path/to/restic

The wheel verifier installs offline into a fresh environment and tests the CLI outside the source tree. The optional restic integration uses only disposable generated fixtures. CI covers Python 3.11/3.14 on three operating systems, plus Linux restic and Docker discovery integration. Actual execution results are in VALIDATION.md; configured jobs are not evidence of a run.

MIT licensed. See CONTRIBUTING, security and changelog.