feat(handler): add partclone handler

Partclone is a utility used for backing up and restoring partitions.
Many cloning tools (such as Clonezilla) rely on it to create block-level
images that include filesystem metadata.

Right now only partclone version 2 is supported. end offset is computed
from data available in partclone's super block.

Extraction is performed by `partclone.restore`, which is part of
`partclone` package on Debian based systems and Nix.

Author: rxpha3l

Diff for: docs/formats.md

@@ -22,6 +22,7 @@ unblob supports more than 30 formats. You can see their code in
 | CAB     | ❌         | ❌                 | ❌        | [archive/cab.py][cab-handler]         | [`7z`][cab-extractor]       |
 | CPIO    | ✅         | ✅                 | ✅        | [archive/cpio.py][cpio-handler]       | unblob extractor            |
 | DMG     | ❌         | ❌                 | ❌        | [archive/dmg.py][dmg-handler]         | [`7z`][dmg-extractor]       |
+| PARTCLONE | ✅       | ❌                 | ❌        | [archive/partclone.py][partclone-hanlder] | [`partclone`][partclone-extractor] |
 | RAR     | ❌         | ❌                 | ❌        | [archive/rar.py][rar-handler]         | [`unar`][rar-extractor]     |
 | 7ZIP    | ❌         | ❌                 | ❌        | [archive/sevenzip.py][7zip-handler]   | [`7z`][7zip-extractor]      |
 | StuffIt | ❌         | ❌                 | ❌        | [archive/stuffit.py][stuffit-handler] | [`unar`][stuffit-extractor] |
@@ -39,6 +40,8 @@ unblob supports more than 30 formats. You can see their code in
 [cpio-handler]: https://github.com/onekey-sec/unblob/blob/main/unblob/handlers/archive/cpio.py
 [dmg-handler]: https://github.com/onekey-sec/unblob/blob/main/unblob/handlers/archive/dmg.py
 [dmg-extractor]: https://github.com/onekey-sec/unblob/blob/3008039881a0434deb75962e7999b7e35aca8271/unblob/handlers/archive/dmg.py#L67-L69
+[partclone-handler]: https://github.com/onekey-sec/unblob/blob/main/unblob/handlers/archive/partclone.py
+[partclone-extractor]: https://github.com/onekey-sec/unblob/blob/b21b6dc291583af6b7ec9b7c3d63ee8302328841/python/unblob/handlers/archive/partclone.py#L44
 [rar-handler]: https://github.com/onekey-sec/unblob/blob/main/unblob/handlers/archive/rar.py
 [rar-extractor]: https://github.com/onekey-sec/unblob/blob/3008039881a0434deb75962e7999b7e35aca8271/unblob/handlers/archive/rar.py#L32
 [7zip-handler]: https://github.com/onekey-sec/unblob/blob/main/unblob/handlers/archive/sevenzip.py

Diff for: install-deps.sh

@@ -9,6 +9,7 @@ apt-get install --no-install-recommends -y \
     lziprecover \
     lzop \
     p7zip-full \
+    partclone \
     unar \
     xz-utils \
     libmagic1 \

Diff for: package.nix

@@ -9,6 +9,7 @@
   lziprecover,
   lzop,
   p7zip,
+  partclone,
   nix-filter,
   sasquatch,
   sasquatch-v4be,
@@ -28,6 +29,7 @@ let
     lziprecover
     lzop
     p7zip
+    partclone
     sasquatch
     sasquatch-v4be
     ubi_reader

Diff for: python/unblob/handlers/__init__.py

@@ -6,6 +6,7 @@
     cab,
     cpio,
     dmg,
+    partclone,
     rar,
     sevenzip,
     stuffit,
@@ -116,6 +117,7 @@
     zlib.ZlibHandler,
     engenius.EngeniusHandler,
     ecc.AutelECCHandler,
+    partclone.PartcloneHandler,
 )
 
 BUILTIN_DIR_HANDLERS: DirectoryHandlers = (

Diff for: python/unblob/handlers/archive/partclone.py

@@ -0,0 +1,81 @@
+import binascii
+import io
+from math import ceil
+from typing import Optional
+
+from unblob.extractors import Command
+from unblob.file_utils import File, InvalidInputFormat, get_endian
+from unblob.models import Regex, StructHandler, ValidChunk
+
+C_DEFINITIONS = r"""
+    typedef struct partclone_header{
+        char magic[16];
+        char partclone_version[14];
+        char image_version_txt[4];
+        char endian[2];
+        char fs_type[16];
+        uint64 fs_size;
+        uint64 fs_total_block_count;
+        uint64 fs_used_block_count_superblock;
+        uint64 fs_used_block_count_bitmap;
+        uint32 fs_block_size;
+        uint32 feature_size;
+        uint16 image_version;
+        uint16 number_of_bits_for_CPU;
+        uint16 checksum_mode;
+        uint16 checksum_size;
+        uint32 blocks_per_checksum;
+        uint8 reseed_checksum;
+        uint8 bitmap_mode;
+        uint32 crc32;
+    } partclone_header_t;
+"""
+
+HEADER_STRUCT = "partclone_header_t"
+BIG_ENDIAN_MAGIC = 0xC0DE
+ENDIAN_OFFSET = 34
+
+
+class PartcloneHandler(StructHandler):
+    NAME = "partclone"
+    PATTERNS = [Regex(r"partclone-image\x00\d+\.\d+\.\d+.*?0002(\xde\xc0|\xc0\xde)")]
+    HEADER_STRUCT = HEADER_STRUCT
+    C_DEFINITIONS = C_DEFINITIONS
+    EXTRACTOR = Command(
+        "partclone.restore",
+        "-W",
+        "-s",
+        "{inpath}",
+        "-o",
+        "{outdir}/partclone.restored",
+        "-L",
+        "/dev/stdout",
+    )
+
+    def is_valid_header(self, header) -> bool:
+        calculated_crc = binascii.crc32(header.dumps()[0:-4])
+        return (
+            header.crc32 ^ 0xFFFFFFFF
+        ) == calculated_crc  # partclone does not final XOR
+
+    def calculate_chunk(self, file: File, start_offset: int) -> Optional[ValidChunk]:
+        file.seek(start_offset + ENDIAN_OFFSET, io.SEEK_SET)  # go to endian
+        endian = get_endian(file, BIG_ENDIAN_MAGIC, endian_len=2)
+        file.seek(start_offset, io.SEEK_SET)  # go to beginning of file
+        header = self.parse_header(file, endian)
+
+        if not self.is_valid_header(header):
+            raise InvalidInputFormat("Invalid partclone header.")
+
+        end_offset = start_offset + len(header)  # header
+        end_offset += header.checksum_size  # checksum size
+        end_offset += ceil(header.fs_total_block_count / 8)  # bitmap, as bytes
+
+        if header.checksum_mode != 0:
+            checksum_blocks = ceil(
+                header.fs_used_block_count_bitmap / header.blocks_per_checksum
+            )
+            end_offset += checksum_blocks * header.checksum_size
+
+        end_offset += header.fs_used_block_count_bitmap * header.fs_block_size  # Data
+        return ValidChunk(start_offset=start_offset, end_offset=end_offset)

Diff for: tests/integration/archive/partclone/__input__/floppy-144m.img

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0e63b5b8ec0ab6dfc4a4254d72e26b8c1b7ee8b6ceb61fe67bea1105b0d60156
+size 69930

Diff for: tests/integration/archive/partclone/__input__/fs_dev0.partclone.img

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e8fb4fbc359454b017521504eddf0e2955c5808280337b73ad9f897a5f501285
+size 40123

Diff for: tests/integration/archive/partclone/__output__/floppy-144m.img_extract/partclone.restored

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6be413ccd078c706d4f7dd64d4e29fe917fd188f22202becf906b0b79aa9d645
+size 1474560

Diff for: tests/integration/archive/partclone/__output__/floppy-144m.img_extract/partclone.restored_extract/lost+found/.gitkeep

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:557ad6d9db9ea8ed1f749d8da063d661c78951e318f3d5f23e517b8b93a205d6
+size 565248