decbackup

Python clone of Stormshield SNS's backup decryption utility, built from a full reverse-engineering of decbackup + libncrypto.so

Features • Installation • Usage • The Format • Development • License

decbackup decrypts and verifies Stormshield Network Security (SNS) backup files (.bkup) — no appliance required. It is a faithful Python reimplementation of /usr/Firewall/sbin/decbackup and the backup container code of libncrypto.so, derived from SNS v5.1.4 by static analysis plus an empirical error-code matrix against a live device (see RECON.md).

Features

Installation

pip install decbackup

Or from a checkout:

pip install .

The wheel bundles everything needed at runtime: the package code, the four CA certificates extracted from libncrypto.so (decbackup/certs/), and a decbackup console script. The only dependency is cryptography.

Usage

Usage : () -i <backup> -o <output archive>
                    [-p <password>] [-d : dump backup header]
                    [-P : prompt for password]
                    [--no-verify : skip signature verification (clone extension)]

decbackup -i firewall.bkup -o archive.tar -p 's3cret'
tar tf archive.tar

Success is silent (exit 0), exactly like the original; failure prints decrypt and/or verify backup failed (%d) with the appliance's own error code. -d prints the decoded header block after a successful run.

--no-verify has no counterpart on the device: it skips trailer parsing and signature/chain checks to rescue backups whose signature region is corrupted. It prints a warning and the output is unauthenticated — decryption alone proves the password was right, not that the backup came from a genuine appliance.

Library use:

from decbackup import decrypt_backup, BackupError
try:
    header = decrypt_backup("firewall.bkup", "archive.tar", "s3cret")
    print(header["model"], header["date"])
except BackupError as e:
    print("failed:", e.code)

The Format

0x000   0x400   [BACKUP] key=value header, NUL-terminated, zero-padded
0x400   4       be32 X — PKCS#7 trailer length
0x404   X       detached PKCS#7 SignedData (device cert + CA intermediate)
0x404+X 4       be32 Y — payload length
0x408+X Y       AES-128-CBC ciphertext (PBKDF2-SHA256 key, PKCS#7 padding)

The signature covers the full 0x400-byte header block plus the decrypted payload; it chains device cert → Stormshield Network Security Products CA → Stormshield Products Root CA (embedded). Expired device certificates still verify — the appliance ignores dates, so backups stay readable forever. Full details in RECON.md.

Development

decbackup/        the package (cli, backup format, crypto, pkcs7, der, trust, certs/)
analysis/         RE tooling: disassembler, strings, symbol lists, the device
                  extraction script and the empirical error-code matrix
tests/vectors/    real encbackup-produced backups + expected payloads
                  (created on an SNS 5.1.4 device, cross-validated against
                  the stock decbackup)
legacy/           the earlier single-file iteration (kept for reference)

python tests/test_decbackup.py        # exit code = number of failures
python analysis/probes.py             # real-vs-clone error-code parity table
python analysis/fuzz.py 30000         # robustness contract fuzzer

Releasing

Tagged pushes (v*) build an sdist + wheel, smoke-test the wheel against the bundled device vectors, and publish to PyPI via trusted publishing (see .github/workflows/release.yml). Pushes and PRs run lint + the error-code parity suite on Python 3.9–3.13 (.github/workflows/ci.yml).

git tag v0.1.0 && git push origin v0.1.0   # → PyPI

License

Apache License 2.0 — see LICENSE. The patent grant and patent-retaliation clauses of Apache-2.0 apply.

Stormshield is a trademark of Stormshield. This project is unaffiliated with Stormshield; it exists so that backups you own remain readable.