{"id":13725011,"url":"https://github.com/fox-it/dissect.cstruct","last_synced_at":"2025-05-07T19:32:22.761Z","repository":{"id":62568291,"uuid":"515984737","full_name":"fox-it/dissect.cstruct","owner":"fox-it","description":"A Dissect module implementing a parser for C-like structures.","archived":false,"fork":false,"pushed_at":"2024-04-22T19:50:39.000Z","size":204,"stargazers_count":35,"open_issues_count":12,"forks_count":15,"subscribers_count":12,"default_branch":"main","last_synced_at":"2024-04-23T09:16:52.275Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fox-it.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-07-20T13:03:26.000Z","updated_at":"2024-04-25T09:30:21.819Z","dependencies_parsed_at":"2023-02-18T07:01:14.319Z","dependency_job_id":"54d18f9d-b7db-4e54-9128-0a4d3dcd734c","html_url":"https://github.com/fox-it/dissect.cstruct","commit_stats":{"total_commits":27,"total_committers":11,"mean_commits":"2.4545454545454546","dds":0.6666666666666667,"last_synced_commit":"5b4e10a9aa14cb11ef2930c9ed053a60f7091aed"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fox-it%2Fdissect.cstruct","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fox-it%2Fdissect.cstruct/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fox-it%2Fdissect.cstruct/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fox-it%2Fdissect.cstruct/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fox-it","download_url":"https://codeload.github.com/fox-it/dissect.cstruct/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224645169,"owners_count":17346090,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T01:02:09.775Z","updated_at":"2024-11-14T15:30:36.594Z","avatar_url":"https://github.com/fox-it.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# dissect.cstruct\n\nA Dissect module implementing a parser for C-like structures. Structure parsing in Python made easy. With cstruct, you\ncan write C-like structures and use them to parse binary data, either as file-like objects or bytestrings.\n\nParsing binary data with cstruct feels familiar and easy. No need to learn a new syntax or the quirks of a new parsing\nlibrary before you can start parsing data. The syntax isn't strict C but it's compatible with most common structure\ndefinitions. You can often use structure definitions from open-source C projects and use them out of the box with little\nto no changes. Need to parse an EXT4 super block? Just copy the structure definition from the Linux kernel source code.\nNeed to parse some custom file format? Write up a simple structure and immediately start parsing data, tweaking the\nstructure as you go.\n\nBy design cstruct is incredibly simple. No complex syntax, filters, pre- or post-processing steps. Just structure\nparsing. For more information, please see [the documentation](https://docs.dissect.tools/en/latest/projects/dissect.cstruct/index.html).\n\n## Requirements\n\nThis project is part of the Dissect framework and requires Python.\n\nInformation on the supported Python versions can be found in the Getting Started section of [the documentation](https://docs.dissect.tools/en/latest/index.html#getting-started).\n\n## Installation\n\n`dissect.cstruct` is available on [PyPI](https://pypi.org/project/dissect.cstruct/).\n\n```bash\npip install dissect.cstruct\n```\n\nThis module is also automatically installed if you install the `dissect` package.\n\n## Build and test instructions\n\nThis project uses `tox` to build source and wheel distributions. Run the following command from the root folder to build\nthese:\n\n```bash\ntox -e build\n```\n\nThe build artifacts can be found in the `dist/` directory.\n\n`tox` is also used to run linting and unit tests in a self-contained environment. To run both linting and unit tests\nusing the default installed Python version, run:\n\n```bash\ntox\n```\n\nFor a more elaborate explanation on how to build and test the project, please see [the\ndocumentation](https://docs.dissect.tools/en/latest/contributing/tooling.html).\n\n## Contributing\n\nThe Dissect project encourages any contribution to the codebase. To make your contribution fit into the project, please\nrefer to [the development guide](https://docs.dissect.tools/en/latest/contributing/developing.html).\n\n## Usage\nAll you need to do is instantiate a new cstruct instance and load some structure definitions in there. After that you can start using them from your Python code.\n\n```python\nfrom dissect.cstruct import cstruct\n\n# Default endianness is LE, but can be configured using a kwarg or setting the 'endian' attribute\n# e.g. cstruct(endian='\u003e') or c_parser.endian = '\u003e'\nparser_def = \"\"\"\n#define SOME_CONSTANT   5\n\nenum Example : uint16 {\n    A, B = 0x5, C\n};\n\nstruct some_struct {\n    uint8   field_1;\n    char    field_2[SOME_CONSTANT];\n    char    field_3[(field_1 \u0026 1) * 5];  // Some random expression to calculate array length\n    Example field_4[2];\n};\n\"\"\"\nc_parser = cstruct().load(parser_def)\n\ndata = b\"\\x01helloworld\\x00\\x00\\x06\\x00\"\nresult = c_parser.some_struct(data)  # Also accepts file-like objects\nassert result.field_1 == 0x01\nassert result.field_2 == b\"hello\"\nassert result.field_3 == b\"world\"\nassert result.field_4 == [c_parser.Example.A, c_parser.Example.C]\n\nassert c_parser.Example.A == 0\nassert c_parser.Example.C == 6\nassert c_parser.Example(5) == c_parser.Example.B\n\nassert result.dumps() == data\n\n# You can also instantiate structures from Python by using kwargs\n# Note that array sizes are not enforced\ninstance = c_parser.some_struct(\n    field_1=5, field_2=\"lorem\", field_3=\"ipsum\", field_4=[c_parser.Example.B, c_parser.Example.A]\n)\nassert instance.dumps() == b\"\\x05loremipsum\\x05\\x00\\x00\\x00\"\n\n```\n\nBy default, all structures are compiled into classes that provide optimised performance. You can disable this by passing a `compiled=False` keyword argument to the `.load()` call. You can also inspect the resulting source code by accessing the source attribute of the structure: `print(c_parser.some_struct.source)`.\n\nMore examples can be found in the `examples` directory.\n\n## Features\n### Structure parsing\nWrite simple C-like structures and use them to parse binary data, as can be seen in the examples.\n\n### Type parsing\nAside from loading structure definitions, any of the supported types can be used individually for parsing data. For example, the following is all supported:\n\n```python\nfrom dissect.cstruct import cstruct\n\ncs = cstruct()\n# Default endianness is LE, but can be configured using a kwarg or setting the attribute\n# e.g. cstruct(endian='\u003e') or cs.endian = '\u003e'\nassert cs.uint32(b\"\\x05\\x00\\x00\\x00\") == 5\nassert cs.uint24[2](b\"\\x01\\x00\\x00\\x02\\x00\\x00\") == [1, 2]  # You can also parse arrays using list indexing\nassert cs.char[None](b\"hello world!\\x00\") == b\"hello world!\"  # A list index of None means null terminated\n```\n\n### Unions and nested structures\nUnions and nested structures are supported, both anonymous and named.\n\n```python\nfrom dissect.cstruct import cstruct\n\nc_def = \"\"\"\nstruct test_union {\n    char magic[4];\n    union {\n        struct {\n            uint32 a;\n            uint32 b;\n        } a;\n        struct {\n            char   b[8];\n        } b;\n    } c;\n};\n\nstruct test_anonymous {\n    char magic[4];\n    struct {\n        uint32 a;\n        uint32 b;\n    };\n    struct {\n        char   c[8];\n    };\n};\n\"\"\"\n# Default endianness is LE, but can be configured using a kwarg or setting the attribute\n# e.g. cstruct(endian='\u003e') or cs.endian = '\u003e'\nc = cstruct().load(c_def)\n\nassert len(c.test_union) == 12\n\na = c.test_union(b\"ohaideadbeef\")\nassert a.magic == b\"ohai\"\nassert a.c.a.a == 0x64616564\nassert a.c.a.b == 0x66656562\nassert a.c.b.b == b\"deadbeef\"\n\nassert a.dumps() == b\"ohaideadbeef\"\n\nb = c.test_anonymous(b\"ohai\\x39\\x05\\x00\\x00\\x28\\x23\\x00\\x00deadbeef\")\nassert b.magic == b\"ohai\"\nassert b.a == 1337\nassert b.b == 9000\nassert b.c == b\"deadbeef\"\n\n```\n\n### Parse bit fields\nBit fields are supported as part of structures. They are properly aligned to their boundaries.\n\n```python\nfrom dissect.cstruct import cstruct\n\nbit_def = \"\"\"\nstruct test {\n    uint16  a:1;\n    uint16  b:1;  // Read 2 bits from an uint16\n    uint32  c;    // The next field is properly aligned\n    uint16  d:2;\n    uint16  e:3;\n};\n\"\"\"\nbitfields = cstruct().load(bit_def)\n\nd = b\"\\x03\\x00\\xff\\x00\\x00\\x00\\x1f\\x00\"\na = bitfields.test(d)\n\nassert a.a == 0b1\nassert a.b == 0b1\nassert a.c == 0xFF\nassert a.d == 0b11\nassert a.e == 0b111\nassert a.dumps() == d\n```\n\n### Enums and Flags\nThe API to access enum and flag members and their values in the same way as the native Enum types in Python 3. Functionally, it's best comparable to the IntEnum or IntFlag type.\n\n### Custom types\nYou can implement your own types by subclassing `BaseType`, and adding them to your cstruct instance with `add_custom_type(name, type, size, alignment, ...)`\n\n### Custom definition parsers\nDon't like the C-like definition syntax? Write your own syntax parser!\n\n## Copyright and license\n\nDissect is released as open source by Fox-IT (\u003chttps://www.fox-it.com\u003e) part of NCC Group Plc\n(\u003chttps://www.nccgroup.com\u003e).\n\nDeveloped by the Dissect Team (\u003cdissect@fox-it.com\u003e) and made available at \u003chttps://github.com/fox-it/dissect\u003e.\n\nLicense terms: Apache License 2.0 (\u003chttps://www.apache.org/licenses/LICENSE-2.0\u003e). For more information, see the LICENSE file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffox-it%2Fdissect.cstruct","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffox-it%2Fdissect.cstruct","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffox-it%2Fdissect.cstruct/lists"}