{"id":9657,"library":"dissect-cstruct","title":"Dissect Cstruct","description":"dissect-cstruct is a Python library from the Dissect project designed for parsing C-like structures from binary data. It allows users to define structures using Python classes or C-like syntax and then parse byte streams into accessible Python objects. The current version is 4.7, and it is actively maintained with a regular release cadence.","status":"active","version":"4.7","language":"en","source_language":"en","source_url":"https://github.com/fox-it/dissect.cstruct","tags":["c-struct","parsing","binary-parsing","reverse-engineering","data-structures"],"install":[{"cmd":"pip install dissect-cstruct","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"The cstruct module is part of the 'dissect' namespace.","wrong":"import cstruct","symbol":"cstruct","correct":"from dissect.cstruct import cstruct"}],"quickstart":{"code":"from dissect.cstruct import cstruct\nimport struct\n\n# Initialize a cstruct context\nctx = cstruct()\n\n# Define a C-like structure using a multiline string\nctx.typedef(\n    \"\"\"\n    struct Header {\n        uint32_t magic;\n        uint16_t version;\n        char name[10];\n    };\n    \"\"\"\n)\n\n# Example binary data conforming to the structure\n# magic = 0xDEADBEEF (little endian)\n# version = 0x0100 (little endian)\n# name = \"TestHeader\" (10 chars)\n# Use struct.pack to ensure correct byte ordering for the example\nexample_data = struct.pack(\"<I H 10s\", 0xDEADBEEF, 0x0100, b\"TestHeader\")\n\n# Parse the data using the defined structure\nparsed_header = ctx.Header(example_data)\n\n# Access fields of the parsed structure\nprint(f\"Magic: {hex(parsed_header.magic)}\")\nprint(f\"Version: {parsed_header.version}\")\nprint(f\"Name: {parsed_header.name.decode('ascii')}\")\n\n# Assertions to verify correct parsing\nassert parsed_header.magic == 0xDEADBEEF\nassert parsed_header.version == 0x0100\nassert parsed_header.name == b\"TestHeader\"\n\nprint(\"Structure parsed successfully!\")","lang":"python","description":"This example demonstrates how to define a C-like structure using `typedef`, create a byte string, and then parse it into an accessible Python object using `dissect-cstruct`."},"warnings":[{"fix":"Update import statements to `from dissect.cstruct.types import Instance` where applicable.","message":"The `Instance` class was renamed from `dissect.cstruct.Instance` to `dissect.cstruct.types.Instance`.","severity":"breaking","affected_versions":"4.0.0 and later"},{"fix":"Review advanced type definitions and type hints. For `cstruct` definitions, ensure you are using the correct `cstruct.Type` or `cstruct.Context` parameterization if you were directly subclassing or referencing these generic types.","message":"The `Structure` and `Array` classes (e.g., used for type hints) now inherit from `typing.Generic` and are parameterized. They can no longer be used as bare types in a `cstruct` definition without proper parameterization.","severity":"breaking","affected_versions":"4.0.0 and later"},{"fix":"Ensure your project is running on Python 3.10 or newer.","message":"`dissect-cstruct` dropped support for Python 3.7 and 3.8.","severity":"breaking","affected_versions":"4.0.0 and later"},{"fix":"Always provide binary data. If you have a string representation, encode it first: `my_string.encode('utf-8')` (or another appropriate encoding).","message":"The `cstruct` parsing functions (e.g., `ctx.MyStruct(data)`) expect a bytes-like object (e.g., `bytes` or `bytearray`) for input. Passing a `str` will result in a `TypeError`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Use the correct import path: `from dissect.cstruct import cstruct`.","cause":"Attempting to import `cstruct` directly instead of from its location within the `dissect` package.","error":"ModuleNotFoundError: No module named 'cstruct'"},{"fix":"Ensure the input data is a `bytes` object. For example, use a byte literal (`b'some string'`) or encode a string (`'some string'.encode('ascii')`).","cause":"Passing a Python string to a `cstruct` type constructor (e.g., `ctx.MyStruct('some string')`) which expects bytes for parsing.","error":"TypeError: 'str' object cannot be interpreted as a byte-like object"},{"fix":"Update your import statement for `Instance` from `from dissect.cstruct import Instance` to `from dissect.cstruct.types import Instance`.","cause":"This often occurs when migrating from `dissect-cstruct` versions older than 4.0.0, where the `Instance` class was moved.","error":"AttributeError: type object 'Instance' has no attribute 'X'"}]}