[falklindner]

Add a parser for the Acronis CyberBackup/CyberProtect TIBX ("archive3") backup format as a dissect.archive.tibx subpackage.

Closes #20

Proposed changes

The parser handles the full TIBX format:

• Page store: 4 KiB pages with CRC-32C verification, ARCH commit-root superblocks, live-root / commit-root selection
• LSM B-tree index: TLV directory, L-SB superblocks, LEAF/LDIR cell decoding, data_map / segment_map with mem-tree and on-disk ctree layers, tombstone masking for backup-version cleanup
• Compression: zstd and linked-LZ4 (dictionary-seeded block chain)
• Encryption: AES-CBC and AES-GCM (128, 192 and 256 bit) with PBKDF2 key derivation
• Chain reconstruction: full incremental/differential chain with recovery-point selection
• Volume reconstruction: NTFS, FAT32, exFAT, FAT12/16 and ext boot-sector detection for accurate volume sizing
• Archive variants: split archives (auto-stitched), version sets (TLV[18] file table with compacted bases), multi-disk archives

TIBX is materially more complex than VBK (page store + LSM index + crypto + chain reconstruction), so a subpackage is proposed rather than a flat module. Happy to consolidate if preferred.

Dependencies

pycryptodome and backports.zstd added to the full optional extra; LZ4 uses dissect.util 3.25.dev10 or later (fox-it/dissect.util#141).

Testing

Unit tests covering all parser layers (page store, LSM trees, segments, codecs, crypto, volume reconstruction, version sets, tombstone masking), on synthetic CRC-correct archives built by tests/_tools/tibx/_synth.py; tests/tibx/test_tibx_acronis.py checks the real Acronis samples in tests/_data/acronis/tibx (Git LFS).

Validated byte-for-byte against real Acronis True Image 2026 (Build 42980) output across: single-partition, multi-partition, whole-disk (MBR and GPT), multi-disk, split, incremental, differential, and encrypted archives; NTFS, FAT32, and exFAT volumes.

Also validated on Acronis Cyber Protect 15 (build 37414) archives, including AES-GCM encryption, and on 187 real-world Cyber Protect archives: see this comment.

Acknowledgments

Thanks to @mniedermaier for his contributions and support in developing this parser.

Checklist

• PR title is descriptive of the changes
• The description is descriptive of the changes
• Tests are included and pass
• Closes Add support for TIB and TIBX format (Acronis backup) #20

[yunzheng]

Very nice work, and thanks for sharing it! I haven't started reviewing yet, but I pushed a commit filling in a few of the unknown fields based on some of our own reversing efforts.

[yunzheng]

Regarding the last commit, can the TIBX encryption not be detected via the encr_alg in the superblock header?

[falklindner]

Regarding the last commit, can the TIBX encryption not be detected via the encr_alg in the superblock header?

Good point — checked against the full real-sample corpus (12 archives): encr_alg in the ARCH superblock agrees with the keymap detection everywhere (AES_256_CBC on the encrypted sample, NONE on the rest), so yes, it does indicate encryption.

The keymap scan answers a narrower question though: not "is this encrypted" but "does a password-wrapped data key exist" — which is what drives the password prompt / keychain lookup. Acronis also supports certificate-wrapped keys (format byte 0x02 next to the 0x01 we locate), where encr_alg would be set but asking for a password can't help. Detection via the keymap also can't disagree with unlock(), since both parse the same structure, and it doesn't depend on the superblock byte layout, which we've only verified for header_version 8.

The two compose nicely, and encr_alg is essentially free: happy to use encr_alg != NONE as the archive-level signal and the keymap scan to decide password vs. certificate — that would let a certificate-wrapped archive fail with "encrypted, but not password-protected" instead of a generic missing-password error.

[falklindner]

Is there anything I can do to support the PR?

[yunzheng]

Hi @falklindner, sorry for the late reply, but I was on holiday.

I left some general feedback.

Also, regarding the synthetic tests, while I do think that's awesome, I think nothing beats real data. It would be nice to add tibx archives created by Acronis itself, for example:

• simple tibx archive
• password protected archive
• full disk vs files
• other edge cases that we want to test

I'm also curious how much you're already using this implementation for your own needs.

[falklindner]

Two behaviour changes in 57fa473, both checked against acrocmd on real Cyber Protect 15 archives. recovery_points() now reads the slices tree, one entry per backup; counting commit roots gave too many. volumes() skips Acronis's own metadata streams, and streams() still lists everything. Older recovery points were verified file by file.

[falklindner]

Since then, volumes() also leaves out allocation bitmaps and the disk's bootstrap region, close() releases the index, and non-overlapping extents are resolved without a sweep. Test results: #30 (comment)

🤖 Generated with Claude Code

[falklindner]

segment_map records now go through segment_map_key / segment_map_value (9b05168). page_count stays the one little-endian field.

[falklindner]

The data_map and segment_map are now decoded in bulk into arrays instead of per-record cstruct objects; a test keeps the precompiled structs in step with c_tibx. segment_map runs are looked up run by run (keep-first) instead of merged. Test results: #30 (comment)

🤖 Generated with Claude Code

[falklindner]

AES-GCM segments (57fa473), as written by Cyber Protect 15; True Image 2026 used AES-CBC: the payload is IV || tag || ciphertext and is not PKCS#7-unpadded.

[falklindner]

A segment's header and continuation pages are now read in one I/O, sized by the segment_map's page count. Test results: #30 (comment)

🤖 Generated with Claude Code

[falklindner]

It would be nice to add tibx archives created by Acronis itself

Real samples are ready: 10 archives from Acronis Cyber Protect 15, covering your list (simple, password-protected, whole disk MBR/GPT vs. file-level) plus chains, stored and multi-volume. They're identity-scrubbed, about 6 MB gzipped in total. That's well above the existing tests/_data (534 KB), so: add them via LFS under tests/_data/, or would you prefer a subset?

[yunzheng]

It would be nice to add tibx archives created by Acronis itself

Real samples are ready: 10 archives from Acronis Cyber Protect 15, covering your list (simple, password-protected, whole disk MBR/GPT vs. file-level) plus chains, stored and multi-volume. They're identity-scrubbed, about 6 MB gzipped in total. That's well above the existing tests/_data (534 KB), so: add them via LFS under tests/_data/, or would you prefer a subset?

Nice! Can you put them in LFS under test/_data/acronis/tibx? The total size is fine.

[falklindner]

Updated with 18 commits after a test campaign on 187 real-world Acronis Cyber Protect archives (5.6 GiB to 1.27 TiB, up to 12.7M extents), on Windows, locally and over SMB: every archive opened, every volume read back and hashed, and target-query -f hostname run through the loader of fox-it/dissect.target#1882.

Result: all 187 archives open and every volume reads back, with the same bytes as the previous head wherever it could read them. Fixed along the way: index trees over 8,192 pages were silently truncated (7 volumes in 8 archives unreadable), and metadata streams were listed as volumes. Loading the index is ~9x faster, with up to 90% less memory.

Related PRs:

• Add LZ4 dictionary support dissect.util#141 (LZ4 dictionary): weak. Used when present; once released, the in-tree LZ4 decoder and the lz4 extra go.
• Borrow the input of native functions dissect.util#146 (native input borrowing): weak. With #141, ~15% faster index loading on the native module.
• Detect FAT boot sectors by their BPB dissect.volume#72 (FAT boot sectors): weak. Removes dissect.target's "Failed to detect" warnings on FAT system partitions.
• Add Acronis TIBX loader dissect.target#1882 (loader): depends on this PR.

The commits are meant to be squashed; each message has the details.

🤖 Generated with Claude Code

[falklindner]

1a4c4a2 fixes the two CI jobs this PR would turn red: the refcount test is skipped on PyPy, and the Raises: entries no longer give docs-build ambiguous cross-references.

🤖 Generated with Claude Code

[Schamper]

Type hinters unfortunately require all of these constants to also be defined in the .pyi file. For example: https://github.com/fox-it/dissect.fve/blob/0b3caf20c1e95136cb2eb4494303604e7629616b/dissect/fve/bde/c_bde.pyi#L816-L837

[falklindner]

Done in 8a0dce9.

[yunzheng]

@Schamper Could we add this to cstruct-stubgen? or at least create an issue for it?

[Schamper]

That's fine, our current setup is imperfect and requires manual addition anyway (see my other comment). For the time being, it's preferred that you just let this file be autoformatted by ruff.

[falklindner]

Done in 8a0dce9.

[yunzheng]

@Schamper maybe output some warning in cstruct-stubgen, that you should autoformat it using ruff manually.

[falklindner]

All five points are addressed in 8a0dce9 (stub), 7ca3ba0 (test layout) and 16095d6 (notices).

🤖 Generated with Claude Code

[falklindner]

Done in 8a0dce9.

[falklindner]

Done in 8a0dce9.

[codecov]

Codecov Report

❌ Patch coverage is 92.27437% with 107 lines in your changes missing coverage. Please review.
✅ Project coverage is 81.64%. Comparing base (e2f7b9f) to head (16095d6).

Files with missing lines	Patch %	Lines
dissect/archive/tibx/lsm.py	86.17%	34 Missing ⚠️
dissect/archive/tibx/tibx.py	94.67%	22 Missing ⚠️
dissect/archive/tibx/segment.py	82.75%	15 Missing ⚠️
dissect/archive/tibx/map.py	95.60%	12 Missing ⚠️
dissect/archive/tibx/crypto.py	91.34%	9 Missing ⚠️
dissect/archive/tibx/page.py	93.38%	8 Missing ⚠️
dissect/archive/tibx/codec.py	88.70%	7 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##             main      #30       +/-   ##
===========================================
+ Coverage   69.25%   81.64%   +12.39%     
===========================================
  Files           9       20       +11     
  Lines        1187     2572     +1385     
===========================================
+ Hits          822     2100     +1278     
- Misses        365      472      +107     

Flag	Coverage Δ
unittests	81.64% <92.27%> (+12.39%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[yunzheng]

I have some feedback regarding the Compression. See my inline comments.

The current tests are mostly synthetic, so it would be nice to have fixture-based tests for:

• a small real backup at “normal” (stored + Zstd), decoding every segment and checking the lengths
• a small backup at “low”, which should produce LZ4 segments (none of our current samples have them)

zlib can stay synthetic, since the current writer never produces it. Maybe some of the real tibx archives already meet this, but I haven't checked.

[yunzheng]

Fix indenting of ComprLvl, and added ComprAlg enums. (Zlib was added).

Suggested change

	enum ComprLvl : uint8 {
	NONE = 0, // "none"
	LOW = 1, // "low"
	NORMAL = 2, // "normal"
	HIGH = 3 // "high"
	};
	enum ComprLvl : uint8 {
	NONE = 0, // "none"
	LOW = 1, // "low"
	NORMAL = 2, // "normal"
	HIGH = 3 // "high"
	};
	enum ComprAlg : uint8 {
	NONE = 0,
	LZ4 = 1,
	ZLIB = 2,
	ZSTD = 3
	};

[yunzheng]

I think the compression should be just uint8, and the other uint8 is some flag.

Suggested change

	uint16 compression; /* see COMP_* */
	ComprAlg compression; /* compression codec */
	uint8 _kind; /* unknown, observed 0x00, 0x01, 0x02, 0x03 */

See my remarks on COMP_ in other comment

[yunzheng]

I think these definitions should go away, and solely use the ComprAlg enum.

I'm curious about the COMP_LZ4 = 0x0001, because I think that is incorrect, it should've been COMP_LZ4 = 0x0200. I wonder if some of these Compression codecs can be tested on the real Tibx test data.

It's possible that Zlib is legacy, as I don't see any writer for it in my version only a reader.

[yunzheng]

decompress() needs a refactor, my clanker came up with something like this, but I have not tested it:

import zlib


def decompress(raw: bytes, segment: Segment) -> bytes:
    """Decompress a segment's raw payload to exactly ``segment.length`` plaintext bytes.

    Dispatches only on the codec byte; ``segment.kind`` plays no part in decoding.
    """
    alg = segment.compression

    if alg == ComprAlg.NONE:
        if len(raw) != segment.length:
            raise CorruptArchiveError(
                f"stored segment at page {segment.page_index} has zlength {len(raw)} "
                f"!= length {segment.length}"
            )
        return raw

    try:
        match alg:
            case ComprAlg.LZ4:
                out = lz4_block_decompress(raw, segment.length)
            case ComprAlg.ZLIB:
                out = zlib.decompress(raw)
            case ComprAlg.ZSTD:
                out = decompress_zstd(raw, segment.length)
            case _:
                raise UnsupportedFormatError(
                    f"segment at page {segment.page_index} uses unknown compression "
                    f"{int(alg):#04x} (kind {segment.kind})"
                )
    except (CorruptArchiveError, UnsupportedFormatError):
        raise
    except Exception as exc:  # codec-library errors (LZ4BlockError, zlib.error, ZstdError, ...)
        raise CorruptArchiveError(
            f"{ComprAlg(alg).name} segment at page {segment.page_index} failed to decompress: {exc}"
        ) from exc

    if len(out) != segment.length:
        raise CorruptArchiveError(
            f"{alg.name} segment at page {segment.page_index} decoded {len(out)} bytes, "
            f"expected {segment.length}"
        )
    return out