feat(handler): add partclone handler

[rxpha3l]

Partclone is a program similar to the well-known backup utility "Partition Image" a.k.a partimage. Partclone provides utilities to save and restore used blocks on a partition and is designed for higher compatibility of the file system by using existing libraries, e.g. e2fslibs is used to read and write the ext2 partition.
Partclone now supports ext2, ext3, ext4, hfs+, reiserfs, reiser4, btrfs, vmfs3, vmfs5, xfs, jfs, ufs, ntfs, fat(12/16/32), exfat, f2fs, nilfs.
Partclone has two version. This handler supports the second one and automatically checks the endian value.

Create partclone image:
partclone.[file_system] -F -c -s [source_file] -o [output.img] -L /dev/stdout[default=/var/log/partclone.log]

Restore partclone image:
partclone.restore -W -r -s [source_fiile.img] -o [restored.img] -L /dev/stdout[default=/var/log/partclone.log]

Notes

• It is worth to mention that a logfile -L should be used since it will lead in the most cases to errors
• Partclone has no standardized file extension but the official website uses .img
• The official documentation got the endian values wrong. Swapping them will solve this issue

The header has the following structure :

16 bytes : Magic
14 bytes : Partclone version
4 bytes : Image version in str
2 bytes : Endian
16 bytes : File system type
8 bytes : File system size
8 bytes : File system total block count
8 bytes : Used blocks based on superblock
8 bytes : Used blocks based on bitmap
4 bytes : Block size
4 bytes : Feature size
2 bytes : Image version in bin
2 bytes : Number of bits for CPU
2 bytes : Checksum mode
2 bytes : Checksum size
4 bytes : Blocks per checksum
1 byte : Reseed checksum
1 byte : Bitmap mode
4 bytes : CRC32 of previous 106 bytes

Unblob parses the header to determine the start and end offset by adding:

• Header
• Bitmap size + Checksum
• Data size
• Checksum per N bytes. This is calculated by multiplying Block size*Blocks per checksum. Each N-Bytes a 4 byte checksum will occur (min: 1)
  Finally the CRC32 value in the header does not the final XOR with 0xFFFFFFFF. This can lead to deviation if checked manually.

[Sources]
https://github.com/Thomas-Tsai/partclone
https://partclone.org/
https://wiki.osdev.org/Ext2
https://piazza.com/class_profile/get_resource/il71xfllx3l16f/inz4wsb2m0w2oz
https://www.science.smith.edu/~nhowe/262/oldlabs/ext2.html
https://www.science.smith.edu/~nhowe/262/oldlabs/kernel/ext2_fs.h

[qkaiser]

Good job :)

[qkaiser]

partclone is not available on OSX in nixpkg - https://github.com/onekey-sec/unblob/actions/runs/14124724723/job/39571274718?pr=1155

Would need to provide a patch for https://github.com/NixOS/nixpkgs/blob/e6057380b59bdf9a3693ca3ef45d67e6a95a0d66/pkgs/by-name/pa/partclone/package.nix.

Will look into it. It will take some time since I need to spin up some VMs.

[qkaiser]

I looked into partclone, it can't be built on OSX. It depends on libraries that are only available on Linux (e.g. e2fsprogs or nilfs) and the code needs header files that can only be found on Linux (e.g. malloc.h, features.h).

We need the ability to tag handlers as unsupported on OSX so their test is not run when testing on that platform. Ideas welcome.

[rxpha3l]

I found a python build in lib that can return information about the system:
import platform
platform.platform() # Prints system info

Could we not match on that and set the test on skip for OSX ? Maybe creating a sort of blacklist or adding an optional flag in the handler. If true, it will skip the test ?

[qkaiser]

We still need a way to mark the test as skipped if platform is not supported by the handler in test_all_handlers. Will look into it.

[e3krisztian]

There are CI failures (I remember commenting this, so my bad originally, the current code is both more verbose and not supported by earlier python versions):

Literal[2] | Literal[4]

should be

Literal[2, 4]

and also its test is failing the type check, and it will even after this fix, so take a look:

/home/runner/work/unblob/unblob/tests/test_file_utils.py:364:62 - error: Argument of type "int" cannot be assigned to parameter "endian_len" of type "Literal[2, 4]" in function "get_endian"
    Type "int" is not assignable to type "Literal[2, 4]"
      "int" is not assignable to type "Literal[2]"
      "int" is not assignable to type "Literal[4]" (reportArgumentType)
  /home/runner/work/unblob/unblob/tests/test_file_utils.py:390:48 - error: Argument of type "int" cannot be assigned to parameter "endian_len" of type "Literal[2, 4]" in function "get_endian"
    Type "int" is not assignable to type "Literal[2, 4]"

[e3krisztian]

Thanks for the work and revisions! :)