API Reference

unblob.models.Handler

Bases: ABC

A file type handler is responsible for searching, validating and "unblobbing" files from Blobs.

Source code in unblob/models.py

class Handler(abc.ABC):
    """A file type handler is responsible for searching, validating and "unblobbing" files from Blobs."""

    NAME: str
    PATTERNS: list[Pattern]
    # We need this, because not every match reflects the actual start
    # (e.g. tar magic is in the middle of the header)
    PATTERN_MATCH_OFFSET: int = 0

    EXTRACTOR: Optional[Extractor]

    @classmethod
    def get_dependencies(cls):
        """Return external command dependencies needed for this handler to work."""
        if cls.EXTRACTOR:
            return cls.EXTRACTOR.get_dependencies()
        return []

    @abc.abstractmethod
    def calculate_chunk(self, file: File, start_offset: int) -> Optional[ValidChunk]:
        """Calculate the Chunk offsets from the File and the file type headers."""

    def extract(self, inpath: Path, outdir: Path) -> Optional[ExtractResult]:
        if self.EXTRACTOR is None:
            logger.debug("Skipping file: no extractor.", path=inpath)
            raise ExtractError

        # We only extract every blob once, it's a mistake to extract the same blob again
        outdir.mkdir(parents=True, exist_ok=False)

        return self.EXTRACTOR.extract(inpath, outdir)

get_dependencies() classmethod

Return external command dependencies needed for this handler to work.

Source code in unblob/models.py

@classmethod
def get_dependencies(cls):
    """Return external command dependencies needed for this handler to work."""
    if cls.EXTRACTOR:
        return cls.EXTRACTOR.get_dependencies()
    return []

calculate_chunk(file, start_offset) abstractmethod

Calculate the Chunk offsets from the File and the file type headers.

Source code in unblob/models.py

@abc.abstractmethod
def calculate_chunk(self, file: File, start_offset: int) -> Optional[ValidChunk]:
    """Calculate the Chunk offsets from the File and the file type headers."""

extract(inpath, outdir)

Source code in unblob/models.py

def extract(self, inpath: Path, outdir: Path) -> Optional[ExtractResult]:
    if self.EXTRACTOR is None:
        logger.debug("Skipping file: no extractor.", path=inpath)
        raise ExtractError

    # We only extract every blob once, it's a mistake to extract the same blob again
    outdir.mkdir(parents=True, exist_ok=False)

    return self.EXTRACTOR.extract(inpath, outdir)

unblob.models.StructHandler

Bases: Handler

Source code in unblob/models.py

class StructHandler(Handler):
    C_DEFINITIONS: str
    # A struct from the C_DEFINITIONS used to parse the file's header
    HEADER_STRUCT: str

    def __init__(self):
        self._struct_parser = StructParser(self.C_DEFINITIONS)

    @property
    def cparser_le(self):
        return self._struct_parser.cparser_le

    @property
    def cparser_be(self):
        return self._struct_parser.cparser_be

    def parse_header(self, file: File, endian=Endian.LITTLE):
        header = self._struct_parser.parse(self.HEADER_STRUCT, file, endian)
        logger.debug("Header parsed", header=header, _verbosity=3)
        return header

parse_header(file, endian=Endian.LITTLE)

Source code in unblob/models.py

def parse_header(self, file: File, endian=Endian.LITTLE):
    header = self._struct_parser.parse(self.HEADER_STRUCT, file, endian)
    logger.debug("Header parsed", header=header, _verbosity=3)
    return header

unblob.models.DirectoryHandler

Bases: ABC

A directory type handler is responsible for searching, validating and "unblobbing" files from multiple files in a directory.

Source code in unblob/models.py

class DirectoryHandler(abc.ABC):
    """A directory type handler is responsible for searching, validating and "unblobbing" files from multiple files in a directory."""

    NAME: str

    EXTRACTOR: DirectoryExtractor

    PATTERN: DirectoryPattern

    @classmethod
    def get_dependencies(cls):
        """Return external command dependencies needed for this handler to work."""
        if cls.EXTRACTOR:
            return cls.EXTRACTOR.get_dependencies()
        return []

    @abc.abstractmethod
    def calculate_multifile(self, file: Path) -> Optional[MultiFile]:
        """Calculate the MultiFile in a directory, using a file matched by the pattern as a starting point."""

    def extract(self, paths: list[Path], outdir: Path) -> Optional[ExtractResult]:
        if self.EXTRACTOR is None:
            logger.debug("Skipping file: no extractor.", paths=paths)
            raise ExtractError

        # We only extract every blob once, it's a mistake to extract the same blob again
        outdir.mkdir(parents=True, exist_ok=False)

        return self.EXTRACTOR.extract(paths, outdir)

get_dependencies() classmethod

Return external command dependencies needed for this handler to work.

Source code in unblob/models.py

@classmethod
def get_dependencies(cls):
    """Return external command dependencies needed for this handler to work."""
    if cls.EXTRACTOR:
        return cls.EXTRACTOR.get_dependencies()
    return []

calculate_multifile(file) abstractmethod

Calculate the MultiFile in a directory, using a file matched by the pattern as a starting point.

Source code in unblob/models.py

@abc.abstractmethod
def calculate_multifile(self, file: Path) -> Optional[MultiFile]:
    """Calculate the MultiFile in a directory, using a file matched by the pattern as a starting point."""

extract(paths, outdir)

Source code in unblob/models.py

def extract(self, paths: list[Path], outdir: Path) -> Optional[ExtractResult]:
    if self.EXTRACTOR is None:
        logger.debug("Skipping file: no extractor.", paths=paths)
        raise ExtractError

    # We only extract every blob once, it's a mistake to extract the same blob again
    outdir.mkdir(parents=True, exist_ok=False)

    return self.EXTRACTOR.extract(paths, outdir)

unblob.models.Extractor

Bases: ABC

Source code in unblob/models.py

class Extractor(abc.ABC):
    def get_dependencies(self) -> list[str]:
        """Return the external command dependencies."""
        return []

    @abc.abstractmethod
    def extract(self, inpath: Path, outdir: Path) -> Optional[ExtractResult]:
        """Extract the carved out chunk.

        Raises ExtractError on failure.
        """

get_dependencies()

Return the external command dependencies.

Source code in unblob/models.py

def get_dependencies(self) -> list[str]:
    """Return the external command dependencies."""
    return []

extract(inpath, outdir) abstractmethod

Extract the carved out chunk.

Raises ExtractError on failure.

Source code in unblob/models.py

@abc.abstractmethod
def extract(self, inpath: Path, outdir: Path) -> Optional[ExtractResult]:
    """Extract the carved out chunk.

    Raises ExtractError on failure.
    """

unblob.models.DirectoryExtractor

Bases: ABC

Source code in unblob/models.py

class DirectoryExtractor(abc.ABC):
    def get_dependencies(self) -> list[str]:
        """Return the external command dependencies."""
        return []

    @abc.abstractmethod
    def extract(self, paths: list[Path], outdir: Path) -> Optional[ExtractResult]:
        """Extract from a multi file path list.

        Raises ExtractError on failure.
        """

get_dependencies()

Return the external command dependencies.

Source code in unblob/models.py

def get_dependencies(self) -> list[str]:
    """Return the external command dependencies."""
    return []

extract(paths, outdir) abstractmethod

Extract from a multi file path list.

Raises ExtractError on failure.

Source code in unblob/models.py

@abc.abstractmethod
def extract(self, paths: list[Path], outdir: Path) -> Optional[ExtractResult]:
    """Extract from a multi file path list.

    Raises ExtractError on failure.
    """