decbackup 0.1.0__tar.gz

decbackup-0.1.0/LICENSE

@@ -0,0 +1,191 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined in Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (as well as "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation of a Source form, including but not limited to
+      compiled object code, generated documentation, and conversions to
+      other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright
+      owner or by an individual or Legal Entity authorized to submit on
+      behalf of the copyright owner. For the purposes of this definition,
+      "submitted" means any form of electronic, verbal, or written
+      communication sent to the Licensor or its representatives, including
+      but not limited to communication on electronic mailing lists, source
+      code control systems, and issue tracking systems that are managed by,
+      or on behalf of, the Licensor for the purpose of discussing and
+      improving the Work, but excluding communication that is conspicuously
+      marked or otherwise designated in writing by the copyright owner as
+      "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2025-2026 fl0l0u
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

decbackup-0.1.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: decbackup
+Version: 0.1.0
+Summary: Python clone of Stormshield SNS's decbackup: decrypt and verify .bkup appliance backups without the device
+Author: fl0l0u
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/fl0l0u/decbackup
+Project-URL: Documentation, https://github.com/fl0l0u/decbackup#readme
+Project-URL: Repository, https://github.com/fl0l0u/decbackup.git
+Project-URL: Issues, https://github.com/fl0l0u/decbackup/issues
+Keywords: stormshield,sns,backup,decbackup,pkcs7,forensics
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: System :: Archiving
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=41
+Provides-Extra: dev
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Dynamic: license-file
+
+<h1 align="center">
+  <br>
+  decbackup
+  <br>
+</h1>
+
+<h4 align="center">Python clone of Stormshield SNS's backup decryption utility, built from a full reverse-engineering of decbackup + libncrypto.so</h4>
+
+<p align="center">
+  <a href="https://pypi.org/project/decbackup/">
+    <img src="https://img.shields.io/pypi/v/decbackup?style=flat-square" alt="PyPI">
+  </a>
+  <a href="LICENSE">
+    <img src="https://img.shields.io/badge/license-Apache--2.0-blue?style=flat-square" alt="License">
+  </a>
+  <img src="https://img.shields.io/badge/platform-any-lightgrey?style=flat-square" alt="Platform">
+  <img src="https://img.shields.io/badge/python-3.9%2B-yellow?style=flat-square" alt="Python">
+  <a href="https://github.com/fl0l0u/decbackup/actions">
+    <img src="https://img.shields.io/github/actions/workflow/status/fl0l0u/decbackup/ci.yml?style=flat-square&label=CI" alt="CI">
+  </a>
+</p>
+
+<p align="center">
+  <a href="#features">Features</a> •
+  <a href="#installation">Installation</a> •
+  <a href="#usage">Usage</a> •
+  <a href="#the-format">The Format</a> •
+  <a href="#development">Development</a> •
+  <a href="#license">License</a>
+</p>
+
+---
+
+**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](RECON.md)).
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| **Byte-exact format support** | `[BACKUP]` header, detached PKCS#7 trailer, AES-128-CBC payload |
+| **Both password schemes** | v2 (PBKDF2-HMAC-SHA256) and legacy v1 (salted-SHA1) key derivation |
+| **Full signature verification** | RSA over PKCS#7 authAttrs, messageDigest over header+payload, chain to the four CAs embedded in libncrypto, policy 1.3.6.1.4.1.11256.2.3, dates ignored (as on the device) |
+| **Original CLI parity** | same flags (`-i -o -p -P -d`), same messages, same numeric error codes (0/1/6/7/8/12/13/32) — validated against the real binary on device |
+| **Tiny dependency set** | `cryptography` only; DER/PKCS#7 parsing is in-tree (`decbackup/der.py`, `pkcs7.py`) |
+
+## Installation
+
+```bash
+pip install decbackup
+```
+
+Or from a checkout:
+
+```bash
+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)]
+```
+
+```bash
+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:
+
+```python
+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](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)
+```
+
+```bash
+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`).
+
+```bash
+git tag v0.1.0 && git push origin v0.1.0   # → PyPI
+```
+
+## License
+
+Apache License 2.0 — see [LICENSE](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.

decbackup-0.1.0/README.md

@@ -0,0 +1,155 @@
+<h1 align="center">
+  <br>
+  decbackup
+  <br>
+</h1>
+
+<h4 align="center">Python clone of Stormshield SNS's backup decryption utility, built from a full reverse-engineering of decbackup + libncrypto.so</h4>
+
+<p align="center">
+  <a href="https://pypi.org/project/decbackup/">
+    <img src="https://img.shields.io/pypi/v/decbackup?style=flat-square" alt="PyPI">
+  </a>
+  <a href="LICENSE">
+    <img src="https://img.shields.io/badge/license-Apache--2.0-blue?style=flat-square" alt="License">
+  </a>
+  <img src="https://img.shields.io/badge/platform-any-lightgrey?style=flat-square" alt="Platform">
+  <img src="https://img.shields.io/badge/python-3.9%2B-yellow?style=flat-square" alt="Python">
+  <a href="https://github.com/fl0l0u/decbackup/actions">
+    <img src="https://img.shields.io/github/actions/workflow/status/fl0l0u/decbackup/ci.yml?style=flat-square&label=CI" alt="CI">
+  </a>
+</p>
+
+<p align="center">
+  <a href="#features">Features</a> •
+  <a href="#installation">Installation</a> •
+  <a href="#usage">Usage</a> •
+  <a href="#the-format">The Format</a> •
+  <a href="#development">Development</a> •
+  <a href="#license">License</a>
+</p>
+
+---
+
+**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](RECON.md)).
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| **Byte-exact format support** | `[BACKUP]` header, detached PKCS#7 trailer, AES-128-CBC payload |
+| **Both password schemes** | v2 (PBKDF2-HMAC-SHA256) and legacy v1 (salted-SHA1) key derivation |
+| **Full signature verification** | RSA over PKCS#7 authAttrs, messageDigest over header+payload, chain to the four CAs embedded in libncrypto, policy 1.3.6.1.4.1.11256.2.3, dates ignored (as on the device) |
+| **Original CLI parity** | same flags (`-i -o -p -P -d`), same messages, same numeric error codes (0/1/6/7/8/12/13/32) — validated against the real binary on device |
+| **Tiny dependency set** | `cryptography` only; DER/PKCS#7 parsing is in-tree (`decbackup/der.py`, `pkcs7.py`) |
+
+## Installation
+
+```bash
+pip install decbackup
+```
+
+Or from a checkout:
+
+```bash
+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)]
+```
+
+```bash
+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:
+
+```python
+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](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)
+```
+
+```bash
+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`).
+
+```bash
+git tag v0.1.0 && git push origin v0.1.0   # → PyPI
+```
+
+## License
+
+Apache License 2.0 — see [LICENSE](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.

decbackup-0.1.0/decbackup/__init__.py

@@ -0,0 +1,10 @@
+"""decbackup — Python clone of the Stormshield SNS backup decryption utility.
+
+Reimplementation of ``/usr/Firewall/sbin/decbackup`` and the backup
+container handling of ``libncrypto.so`` from Stormshield SNS v5.1.4,
+derived by reverse engineering (see ``RECON.md``).
+"""
+
+__version__ = "0.1.0"
+
+from .backup import BackupError, decrypt_backup  # noqa: F401

decbackup-0.1.0/decbackup/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())