Metadata-Version: 2.4
Name: malstruct
Version: 3.0.20260518
Summary: A powerful declarative symmetric parser/builder for binary data
Author-email: "Cipher Tech Solutions, Inc" <opensource@ciphertechsolutions.com>
Maintainer-email: "Cipher Tech Solutions, Inc" <opensource@ciphertechsolutions.com>
License-Expression: MIT
Project-URL: Homepage, https://ciphertechsolutions.github.io/malstruct/
Project-URL: Source, https://github.com/ciphertechsolutions/malstruct
Project-URL: Documentation, https://ciphertechsolutions.github.io/malstruct/
Project-URL: Issues, https://github.com/ciphertechsolutions/malstruct/issues
Keywords: malstruct,construct,kaitai,declarative,data structure,struct,binary,symmetric,parser,builder,parsing,building,pack,unpack,packer,unpacker
Platform: any
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Code Generators
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: arrow>=1.4.0
Requires-Dist: cloudpickle>=3.1.2
Requires-Dist: lz4>=4.4.5
Requires-Dist: cryptography>=46.0.7
Requires-Dist: pyelftools
Requires-Dist: jinja2
Requires-Dist: pefile>=2019.4.18
Requires-Dist: lief
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-benchmark; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Provides-Extra: build
Requires-Dist: setuptools; extra == "build"
Requires-Dist: build; extra == "build"
Requires-Dist: twine; extra == "build"
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Dynamic: license-file

Malstruct
===================

Malstruct is a powerful **declarative** and **symmetrical** parser and builder for binary data that was forked from `construct <https://github.com/construct/construct>`_ as of release 2.10.70.

Instead of writing *imperative code* to parse a piece of data, you declaratively define a *data structure* that describes your data. As this data structure is not code, you can use it in one direction to *parse* data into Pythonic objects, and in the other direction, to *build* objects into binary data.

The library provides both simple, atomic constructs (such as integers of various sizes), as well as composite ones which allow you form hierarchical and sequential structures of increasing complexity. Construct features **bit and byte granularity**, easy debugging and testing, an **easy-to-extend subclass system**, and lots of primitive constructs to make your work easier:

* Fields: raw bytes or numerical types
* Structs and Sequences: combine simpler constructs into more complex ones
* Bitwise: splitting bytes into bit-grained fields
* Adapters: change how data is represented
* Arrays/Ranges: duplicate constructs
* Meta-constructs: use the context (history) to compute the size of data
* If/Switch: branch the computational path based on the context
* On-demand (lazy) parsing: read and parse only what you require
* Pointers: jump from here to there in the data stream
* Tunneling: prefix data with a byte count or compress it


Example
---------

A ``Struct`` is a collection of ordered, named fields::

    >>> format = Struct(
    ...     "signature" / Const(b"BMP"),
    ...     "width" / Int8ub,
    ...     "height" / Int8ub,
    ...     "pixels" / Array(this.width * this.height, Byte),
    ... )
    >>> format.build(dict(width=3,height=2,pixels=[7,8,9,11,12,13]))
    b'BMP\x03\x02\x07\x08\t\x0b\x0c\r'
    >>> format.parse(b'BMP\x03\x02\x07\x08\t\x0b\x0c\r')
    Container(signature=b'BMP')(width=3)(height=2)(pixels=[7, 8, 9, 11, 12, 13])

A ``Sequence`` is a collection of ordered fields, and differs from ``Array`` and ``GreedyRange`` in that those two are homogenous::

    >>> format = Sequence(PascalString(Byte, "utf8"), GreedyRange(Byte))
    >>> format.build([u"lalaland", [255,1,2]])
    b'\nlalaland\xff\x01\x02'
    >>> format.parse(b"\x004361789432197")
    ['', [52, 51, 54, 49, 55, 56, 57, 52, 51, 50, 49, 57, 55]]


Malware Analysis
----------------

Helpers and utilities have been added to Malstruct to aid in malware analysis and configuration parser development, from simple `windows structure extensions <https://github.com/ciphertechsolutions/malstruct/tree/master/src/malstruct/windows/structures.py>`_ to constructs/adapters to aid in processing binary file types (e.g. PE, ELF, and Mach-O).

For example, when attempting to extract a referenced string from a 64-bit PE file the following can assist::

    >>> spec = FocusLast(
        "re" / RegexSearch(
            re.compile(
                # test64.exe @ 0x14000101d
                br"""
                    \x45\x33\xc9                    # xor     r9d, r9d; lpNumberOfCharsWritten
                    \x41\xb8(?P<size>.{4})          # mov     r8d, 0Eh; nNumberOfCharsToWrite
                    \x48\x8d\x15(?P<ro>.{4})(?P<e>) # lea     rdx, aHelloWorld; "Hello, World!\n"
                    \x48\x8b\x4c\x24.               # mov     rcx, [rsp+48h+hConsoleOutput]; hConsoleOutput
                    \xff\x15.{4}                    # call    cs:WriteConsoleA
                    \x33\xc9                        # xor     ecx, ecx; uExitCode
                """,
                re.DOTALL | re.VERBOSE
            ),
            size=Int32ul,
            ro=Int32ul,
            e=Tell
        ),
        PEPointer64(this.re.ro, this.re.e, String(this.re.size))
    )
    >>> spec.parse(data, pe=pe)
    'Hello, World!\n'


Alternatively to using `PEPointer64`, users can leverage the `PEMemoryAddress` adapter to perform the internal memory conversion calculation as follows::

    >>> spec = FocusLast(
        "re" / RegexSearch(
            re.compile(
                # test64.exe @ 0x14000101d
                br"""
                    \x45\x33\xc9                    # xor     r9d, r9d; lpNumberOfCharsWritten
                    \x41\xb8(?P<size>.{4})          # mov     r8d, 0Eh; nNumberOfCharsToWrite
                    \x48\x8d\x15(?P<ro>.{4})(?P<e>) # lea     rdx, aHelloWorld; "Hello, World!\n"
                    \x48\x8b\x4c\x24.               # mov     rcx, [rsp+48h+hConsoleOutput]; hConsoleOutput
                    \xff\x15.{4}                    # call    cs:WriteConsoleA
                    \x33\xc9                        # xor     ecx, ecx; uExitCode
                """,
                re.DOTALL | re.VERBOSE
            ),
            size=Int32ul,
            ro=Int32ul,
            e=PEMemoryAddress(Tell)
        ),
        PEPointer(this.re.ro + this.re.e, String(this.re.size))
    )
    >>> spec.parse(data, pe=pe)
    'Hello, World!\n'



PEcon
-----
Included in malstruct is the `pecon` (PE file reconstruction utility) package. Please see the `pecon API documentation <https://malstruct.readthedocs.io/en/latest/api/pecon.html>`_ for more information.

Changelog
=========

The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.0.0/>`_\ ,
and this project adheres to `Calendar Versioning <https://calver.org/>`_ with the schema MAJOR.MINOR.YYYY0M0D.


3.0.20260518 - 2026-05-18
-------------------------

Added
^^^^^
- Alias `VarIntl` to `VarInt`
- Add `VarIntb` for big-endian parsing
- `PEImport`, `PEImportPointer`, and `PEImportSymbol` to process imported APIs from memory address references in PE files


3.0.20260429 - 2026-04-29
-------------------------

Changed
^^^^^^^
- Split out `core` functionality across `adapters`, `alignment`, `analysis`, `bytes_`, `conditional`, `exceptions`, `expr`, `helpers`, `integers`, `lazy`, `mappings`, `miscellaneous`, `stream`, `strings`, and `transforms`
- Moved binary file analysis to `malstruct.binaryfiles`
- Moved remaining `malstruct.utils` functionality to base level
- Added `pecon` utility as an installed package
- Move from "flat" layout to "src" layout
- Use `pyproject.toml` configuration file for packaging

Removed
^^^^^^^
- Removed usage of `__all__` in init
- Removed usage of compilation feature and benchmarks
- Removed `py3compat` functionality
- Removed `pefileutils` and `elffileutils`
- Removed functionality from `machoutils` unrelated to malstructs/adapters


2.10.71
-------

Changed
^^^^^^^
- Reverted default behavior changed by https://github.com/construct/construct/pull/1015
    - OffsettedEnd, Prefixed, FixedSize, NullTerminated, NullStriped, ProcessXor use offsets relative to the last occurrence of these subconstructs
    - To use offsets relative to the beginning of the stream set `absolute=True` when constructing these constructs
- Moved optional dependencies to required dependencies
