zupt/THREAT_MODEL.md

ZUPT 5.2.8 threat model

This document defines the security boundary of the ZUPT archive tool. It is not a certification, a guarantee against every hostile input, or a substitute for reviewing the exact source and binary used for important data.

Intended use

ZUPT is intended for at-rest backup archives created and restored on machines controlled by the user. It can be used when the storage provider or physical medium is not trusted, provided encryption is enabled and credentials remain secret.

It is not a network protocol, a full-disk encryption system, a multi-party or threshold scheme, a password manager, or a way to make an archive's existence plausibly deniable.

Baseline considered here

The upstream baseline is built from the 5.2.8 source with:

make WITH_SDK=0 WITH_PQBOX=0

It contains the native password, ML-KEM-768 + X25519 hybrid --pq, and ML-KEM-768-only --pq-only modes. It does not load a precompiled library from the repository and does not download a dependency while building.

WITH_SDK=1 and WITH_PQBOX=1 add separately installed system libraries and change the assessed code boundary. The SDK and PQBOX integrations must be reviewed with their exact packaged source and version; success of the baseline tests is not evidence for them.

Textual assembly under jasmin/ is a separate WITH_JASMIN=1 option for supported x86_64 compiler targets. The directory contains both generated and separately identified hand-written assembly. Portable C is the default. Architecture portability is a source property, not evidence that an unexecuted architecture passed.

Assets

The assets ZUPT tries to protect are:

• archived file contents and encrypted index data;
• the integrity and ordering of encrypted archive blocks and current global metadata covered by the archive integrity trailer;
• private keys, passwords, and derived encryption/MAC keys while held by the trusted caller;
• safe placement of extracted entries within the requested destination.

The archive's existence, total byte length, magic, encryption/framing flags, and some size/structure information are observable. Plain archives provide corruption detection, not cryptographic protection against an active attacker.

Adversaries considered

The design considers an adversary who can read, copy, truncate, reorder, or modify stored archive bytes but cannot read the encryption endpoint's memory or credentials. It also considers accidental corruption and malicious archive entry paths during extraction.

The following adversaries are outside the protection boundary:

• malware, a keylogger, or an administrator on the source or restore endpoint;
• an attacker who obtains the password or matching private key;
• a malicious compiler, kernel, CPU, firmware, or random-number generator;
• an attacker with unrestricted side-channel observation of a shared machine;
• an attacker allowed unbounded CPU, memory, or storage denial of service.

Security properties

Encrypted archive confidentiality

Password and native PQ modes encrypt blocks with AES-256-CTR and authenticate them with HMAC-SHA256. Confidentiality depends on unique nonces, correct implementations, OS randomness, and credential secrecy. In password mode it also depends on password entropy; PBKDF2-SHA256 slows but cannot prevent offline guessing of a weak password.

Prefer --password-prompt, --pass-file, or --pass-fd. A password supplied through -p/--password can be visible through process inspection or shell history. A password file is protected only by the caller's filesystem choices; ZUPT does not validate its ownership or permission bits. A descriptor is trusted input inherited from the caller. Both non-interactive forms read one line and reject empty, NUL-containing, or overlong values. The descriptor form duplicates but shares the underlying stream/offset and may buffer beyond the line, so callers should provide a descriptor dedicated to that password read. On POSIX, handled prompt interruptions restore the saved terminal state before termination; an exact-candidate PTY regression is required before release. On Windows, a prompt is entered only for a real console input handle; redirected input and console EOF fail instead of blocking in _getch.

Native private-key generation uses no-replace creation with POSIX mode 0600 or a Windows current-user-only DACL. A failed write, flush/fsync, or close leaves the incomplete or durability-uncertain exclusive file for manual review and removal instead of risking an unlink-after-close race against a replacement pathname. ZKEY and ZPQK inputs are accepted only after checksum, version, flags, reserved bytes, exact size, and public/private role validation. This prevents role confusion and partial/trailing-key acceptance; it does not protect a key after endpoint or account compromise.

When the optional system SDK is enabled, the in-repository adapter copies a key through the core atomic publisher, applies POSIX mode through the already-open temporary descriptor, and publishes only after copy/close checks succeed. Its sdk-test regression preserves existing symlink/hardlink targets and verifies private/public modes. This narrows the adapter boundary; it does not extend the baseline assessment to the external SDK implementation.

Encrypted archive integrity

Current encrypted archives authenticate ciphertext, canonical block metadata, and each frame's logical position. DATA and DEDUP_REF frames both receive this positional AAD. A reference is authenticated at its own position and carries the authenticated source position needed to verify the referenced DATA frame, so exchanging otherwise equivalent frames is not accepted.

Current archives carry an archive-integrity trailer for global metadata. The extract, list, test, and disk restore paths refuse any no-AIT layout by default without relying on an unauthenticated header flag. --allow-legacy-no-ait is a narrowly scoped, warning-producing recovery option for those commands when the caller already trusts a pre-AIT archive. Selecting it for attacker-controlled storage removes the header/footer authentication assumption and is outside this threat model. info is an unauthenticated framing inspection that reports apparent AIT presence but validates neither the trailer nor archive contents. These checks do not prevent deletion of the entire archive, rollback to an older valid archive, or storage-layer replay.

Archive comments remain untrusted presentation data even when they are authenticated. Display paths render control bytes without emitting raw terminal control sequences, limiting terminal-output injection while leaving the stored and authenticated comment bytes unchanged.

New 5.2.2 encrypted+dedup archives authenticate each reference offset. New encrypted disk archives also authenticate an index that binds image size, block count, and a chained XXH64 hash of the complete restored stream. The writer's additional SHA-256/128 comparison is only an in-memory collision guard before deduplication; it is not an on-disk cryptographic hash. XXH64 is not cryptographic, so a writer who controls a plain archive can recompute it.

Plain archives use non-cryptographic checksums. A writer who controls a plain archive can recompute them.

Native hybrid post-quantum mode

The --pq mode combines an ML-KEM-768 shared secret and an X25519 shared secret as implemented in 5.2.2:

hybrid_ikm  = ml_ss XOR x25519_ss
archive_key = SHA3-512(hybrid_ikm || ml_ct || ephemeral_pk ||
                       "ZUPT-HYBRID-v1")

Its goal is harvest-now/decrypt-later resistance if ML-KEM-768 remains secure, with X25519 as a classical hedge under the combiner assumptions. This is not session forward secrecy: compromise of the recipient's long-term private key can compromise previously captured archives encrypted to it.

The native --pq-only mode removes X25519 and derives a key from ML-KEM-768 alone. Use it only when a policy specifically excludes the classical component; it loses the hybrid hedge.

The in-tree ML-KEM code has project tests, including known-answer vectors and a conditional OpenSSL 3.5 interoperability test. It has not been independently audited or formally verified as a whole implementation.

Extraction containment

The reader rejects absolute paths, traversal components, control characters, ambiguous trailing dot/space components, NTFS alternate-stream syntax, and reserved Windows device names. POSIX extraction resolves every parent below a pinned destination descriptor with no-follow operations after canonicalizing the user-selected root once. Windows extraction uses handle-relative traversal, rejects reparse-point parents, and publishes the final name by handle without replacing an existing leaf. A checked path is not re-resolved through a mutable parent.

Decoded bytes are first written to a private, exclusively created temporary file. The final name is published only after the expected decoded size and chained checksum match and the stream closes successfully; failures remove the temporary through its descriptor or handle. These controls reduce traversal, link, race, and partial-output risks, but do not establish that no parser or filesystem bug can exist.

Benchmark scratch data lives in a random private directory. Cleanup resolves POSIX components without following links and deletes relative to pinned descriptors. On Windows it retains no-delete-sharing ancestor handles, refuses reparse-point recursion, then reopens each emptied directory relative to its pinned parent and verifies its filesystem identity before handle-based deletion. An attacker who inserts a link can cause cleanup failure, but the cleanup must not traverse to the link target.

The Windows handle-relative boundary in 5.2.8 covers normal local Win32 paths. Win32 extended-length and device-namespace paths, raw UNC output roots, and mapped/network-drive output are not supported. Cross-build and Wine results are not a substitute for the required native windows-latest Unicode package gate. Restore locally before moving verified output to network storage.

Disk restore copies the measured compacted archive into one exclusively created, auto-deleted scratch file. Preflight and restoration consume that same open snapshot. An explicit ZUPT_TMPDIR selects an existing scratch directory; failure there does not fall back to consuming the mutable source pathname. On POSIX, the destination is opened once without truncation or final-symlink following, classified with fstat, and the same raw-device descriptor is retained for supported Linux, macOS, and FreeBSD capacity checks and writes. Regular-file output retains atomic publication. A raw target is rejected before writing if its capacity is unknown or smaller than the image. These controls reduce source exchange, target exchange, and immediate overrun risk but do not protect against a compromised kernel/device, a wrongly selected sufficiently large device, power loss, or hardware failure.

The SDK publication, POSIX disk-target, and benchmark-cleanup changes address CodeQL High #5, #6, and #7 respectively. Their source review and regressions alone are project evidence, not independent certification. Exact-tag run 33456209269 subsequently passed all 15 hosted jobs at ebb9ab3aa1d42c50030ca02883f6162dc4771fe1; final release-commit CodeQL run 33456049125 completed successfully with zero open alerts.

For an untrusted archive:

1. use a new empty destination outside sensitive trees;
2. run as a dedicated unprivileged user, never root;
3. apply a container, sandbox, resource limits, and a storage quota when available;
4. inspect extracted paths, types, permissions, and content before moving them;
5. never restore a disk image to a device without independently confirming both source and destination.

Non-goals and residual risks

ZUPT does not claim to provide:

• resistance to cache, power, EM, acoustic, speculative-execution, or all compiler-introduced timing side channels;
• bounded resource consumption for every malformed archive;
• confidentiality of archive size or complete framing metadata;
• protection against compression-length oracles when secret and attacker-controlled data are compressed together;
• rollback detection across multiple valid versions of a backup;
• forward-secure sessions, remote authentication, replay protection, or secure transport;
• automatic key rotation, recovery, escrow, threshold access, or secure deletion;
• preservation of every operating-system ACL, ownership attribute, extended attribute, or special-file semantic;
• safe operation on a compromised host.

Credential handling

• Generate PQ keys on a trusted system using the OS CSPRNG.
• Keep private keys separate from the archive and from release/package inputs.
• Store an offline recovery copy and test recovery before relying on a backup.
• Use a distinct high-entropy credential where compromise isolation matters.
• Re-encrypt under a new credential after suspected disclosure; there is no in-place key rotation.
• Never include credentials or sensitive archives in bug reports or CI logs.

Supply-chain boundary

Git and upstream source archives are source-only. They must pass scripts/check-source-only.sh and must not contain executable code artifacts, objects, shared/static libraries, distribution packages, unsafe symlinks, or Git LFS pointers.

Nested inspection is itself an untrusted-input boundary. The release scanner must cap recursion depth, archive members, per-entry expansion, and total expanded bytes and fail closed when a cap is reached. Commit ff99770 passed all 39 source-only scanner cases, including GNU thin archives, scanner-bomb limits, and safe diagnostic cases.

DEB, binary RPM, SRPM, notice-bearing Linux tar.xz, source-only portable GUI ZIP, Windows ZIP, and macOS DMG files can be published separately from the tagged source. Each artifact extends the trust boundary to its builder, toolchain, runner image, and packaging scripts. Treat it as validated only when the exact target has a recorded build, content/package inspection, extracted or installed smoke test, and applicable archive round trip. An AppImage is not promoted for 5.2.8; bare Linux and Windows executables are also excluded.

For 5.2.8, that gated artifact scope covers the CLI files plus the exact GUI DEB, noarch/source RPM, and source-only portable ZIP named in the README. The portable ZIP contains no compiled runtime and crosses the release boundary only after source scans and an exact safe-member check. AppDir and Flatpak bundles and GUI platform installers remain excluded; Windows ZIP and macOS DMG outputs remain CLI-only.

The immutable, non-promoted 5.2.2 candidate at ff99770 passed the full local make release-check: packaging reported PASS=49 FAIL=0 SKIP=0; strict GCC, strict Clang, GCC -fanalyzer, the 9/9 tool-enabled static-analysis run, ASan/UBSan/LSan, and 1,000 mutation-fuzz iterations passed. Earlier off-screen GUI smoke evidence is retained separately. Post-tag CI integration failures prevented 5.2.2 promotion. This upstream self-review is not an independent certification and is not 5.2.8 evidence. The immutable 5.2.3 candidate was not promoted because its source-policy test assumed LF for a Windows .bat checkout that correctly used CRLF. The immutable v5.2.4 candidate was not promoted after exact-tag GitHub Actions run 33431386002: 12 jobs succeeded, the sole openSUSE service-harness job failed because its standalone executor did not enter the service directory, and dependent Windows/macOS jobs were skipped. A local Tumbleweed reproduction established that the explicit refs/tags/v5.2.4 revision works and that os.chdir(service_dir) completes the source-service chain. This narrows the failure to release/test integration; it changes no product, archive, cryptographic, codec, or SDK ABI boundary and supplies no automatic 5.2.8 evidence. The immutable v5.2.5 candidate was not promoted after exact-tag GitHub Actions run 33434986357: 13 jobs succeeded, but native Windows and macOS failed on fixture-byte preservation and Darwin/Bash 3.2 portability respectively. The corresponding 5.2.6 corrections were followed by exact-tag run 33442264243: 13 jobs succeeded, while native macOS failed on x86-only SHA-NI helper declarations unused on arm64 under -Werror, and native Windows aborted during safe UTF-8 fixture argv transcoding. The v5.2.6 tag was not promoted. Version 5.2.7 corrected those two boundaries, but its exact-tag run 33445470664 concluded cancelled at 2026-08-31T23:11:19Z, with 13 successful jobs, one failed macOS job after raw-C1 filename creation returned EILSEQ, and one cancelled Windows job after the hosted job stalled in make check; a MinGW/Wine reproduction isolated the cause to a redirected password prompt entering _getch. The corresponding 5.2.8 fixture and prompt corrections alone did not establish a result. Exact-tag run 33456209269 then passed 15/15 jobs, including sdk-test, native Windows/macOS, the pinned local OBS source-service chain, and the package/source gates. Promotion run 33457868306 published the exact 13 tested assets. Official authenticated OBS/Factory acceptance, the full automatic debug-package result, and untested architectures remain unclaimed; the earlier debugsource rpmlint no-binary finding remains unresolved and unsuppressed.

Historical compatibility notes

These are historical facts about earlier releases, retained to support recovery:

• Releases through 4.1.0 could reuse an AES-CTR nonce in encrypted --dedup archives. Release 4.2.0 changed to fresh random per-block nonces. Re-encrypt affected older archives.
• Releases through 4.2.1 used round-3 CRYSTALS-Kyber semantics in the native PQ path. Release 5.0.0 corrected the implementation to FIPS 203 ML-KEM-768, changing native PQ key/archive compatibility. See CHANGELOG.md before planning cross-version restoration.
• Pre-AIT archive layouts now fail closed by default. The explicit --allow-legacy-no-ait read option is only for recovery from a known, trusted historical archive and leaves its header/footer metadata outside the current authenticated boundary.
• The 5.2.2 reader retains compatibility parsers for the fixed-width disk index and encrypted-dedup linear AAD sequence published through 5.2.1. An actual v5.2.1 password-encrypted DATA/DATA/REF/DATA disk fixture is stored as hexadecimal text with source and hash provenance. The candidate lists, tests, extracts, and restores it byte-exact, with a warning that the legacy index has no whole-image hash; the full local Linux gate passed on commit ff99770. Older readers are not claimed to accept new flag-gated 5.2.2 records, and untested historical mode combinations remain unclaimed.

Historical test counts in the changelog describe those releases. They do not automatically become 5.2.8 results; current outcomes belong in the release validation record, with unavailable environments marked SKIP. In particular, runs made before the final positional-AAD and mandatory-AIT changes are not final release gates for the resulting candidate.

Reporting security issues

Email zupt@riseup.net with [security] in the subject. Include the version, platform, impact, and a minimal non-sensitive reproducer. Do not disclose the issue publicly until a coordinated timeline has been agreed.

Document version: 5.2.8, 2026-08-31.