Package: dissect.cstruct
dissect.cstructA Dissect module implementing a parser for C-like structures. Structure parsing in Python made easy. With cstruct, you
can write C-like structures and use them to parse binary data, either as file-like objects or bytestrings.Parsing binary data with cstruct feels familiar and easy. No need to learn a new syntax or the quirks of a new parsing
library before you can start parsing data. The syntax isn't strict C but it's compatible with most common structure
definitions. You can often use structure definitions from open-source C projects and use them out of the box with little
to no changes. Need to parse an EXT4 super block? Just copy the structure definition from the Linux kernel source code.
Need to parse some custom file format? Write up a simple structure and immediately start parsing data, tweaking the
structure as you go.By design cstruct is incredibly simple. No complex syntax, filters, pre- or post-processing steps. Just structure
parsing. For more information, please seethe documentation.RequirementsThis project is part of the Dissect framework and requires Python.Information on the supported Python versions can be found in the Getting Started section ofthe documentation.Installationdissect.cstructis available onPyPI.pipinstalldissect.cstructThis module is also automatically installed if you install thedissectpackage.Build and test instructionsThis project usestoxto build source and wheel distributions. Run the following command from the root folder to build
these:tox-ebuildThe build artifacts can be found in thedist/directory.toxis also used to run linting and unit tests in a self-contained environment. To run both linting and unit tests
using the default installed Python version, run:toxFor a more elaborate explanation on how to build and test the project, please seethe
documentation.ContributingThe Dissect project encourages any contribution to the codebase. To make your contribution fit into the project, please
refer tothe development guide.UsageAll 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.fromdissectimportcstruct# Default endianness is LE, but can be configured using a kwarg or setting the 'endian' attribute# e.g. cstruct.cstruct(endian='>') or cparser.endian = '>'cparser=cstruct.cstruct()cparser.load("""#define SOME_CONSTANT   5enum Example : uint16 {A, B = 0x5, C};struct some_struct {uint8   field_1;char    field_2[SOME_CONSTANT];char    field_3[field_1 & 1 * 5];  // Some random expression to calculate array lengthExample field_4[2];};""")data=b'\x01helloworld\x00\x00\x06\x00'result=cparser.some_struct(data)# Also accepts file-like objectsassertresult.field_1==0x01assertresult.field_2==b'hello'assertresult.field_3==b'world'assertresult.field_4==[cparser.Example.A,cparser.Example.C]assertcparser.Example.A==0assertcparser.Example.C==6assertcparser.Example(5)==cparser.Example.Bassertresult.dumps()==data# You can also instantiate structures from Python by using kwargs# Note that array sizes are not enforcedinstance=cparser.some_struct(field_1=5,field_2='lorem',field_3='ipsum',field_4=[cparser.Example.B,cparser.Example.A])assertinstance.dumps()==b'\x05loremipsum\x05\x00\x00\x00'By default, all structures are compiled into classes that provide optimised performance. You can disable this by passing acompiled=Falsekeyword argument to the.load()call. You can also inspect the resulting source code by accessing the source attribute of the structure:print(cparser.some_struct.source).More examples can be found in theexamplesdirectory.FeaturesStructure parsingWrite simple C-like structures and use them to parse binary data, as can be seen in the examples.Type parsingAside from loading structure definitions, any of the supported types can be used individually for parsing data. For example, the following is all supported:fromdissectimportcstructcs=cstruct.cstruct()# Default endianness is LE, but can be configured using a kwarg or setting the attribute# e.g. cstruct.cstruct(endian='>') or cs.endian = '>'assertcs.uint32(b'\x05\x00\x00\x00')==5assertcs.uint24[2](b'\x01\x00\x00\x02\x00\x00')==[1,2]# You can also parse arrays using list indexingassertcs.char[None](b'hello world!\x00')==b'hello world!'# A list index of None means null terminatedUnions and nested structuresUnions and nested structures are supported, both anonymous and named.cdef="""struct test_union {char magic[4];union {struct {uint32 a;uint32 b;} a;struct {char   b[8];} b;} c;};struct test_anonymous {char magic[4];struct {uint32 a;uint32 b;};struct {char   c[8];};};"""c=cstruct.cstruct()c.load(cdef)assertlen(c.test_union)==12a=c.test_union(b'ohaideadbeef')asserta.magic==b'ohai'asserta.c.a.a==0x64616564asserta.c.a.b==0x66656562asserta.c.b.b==b'deadbeef'asserta.dumps()==b'ohaideadbeef'b=c.test_anonymous(b'ohai\x39\x05\x00\x00\x28\x23\x00\x00deadbeef')assertb.magic==b'ohai'assertb.a==1337assertb.b==9000assertb.c==b'deadbeef'Parse bit fieldsBit fields are supported as part of structures. They are properly aligned to their boundaries.bitdef="""struct test {uint16  a:1;uint16  b:1;  # Read 2 bits from an uint16uint32  c;    # The next field is properly aligneduint16  d:2;uint16  e:3;};"""bitfields=cstruct.cstruct()bitfields.load(bitdef)d=b'\x03\x00\xff\x00\x00\x00\x1f\x00'a=bitfields.test(d)asserta.a==0b1asserta.b==0b1asserta.c==0xffasserta.d==0b11asserta.e==0b111asserta.dumps()==dEnumsThe API to access enum members and their values is similar to that of the native Enum type in Python 3. Functionally, it's best comparable to the IntEnum type.Custom typesYou can implement your own types by subclassingBaseTypeorRawType, and adding them to your cstruct instance withaddtype(name, type)Custom definition parsersDon't like the C-like definition syntax? Write your own syntax parser!Copyright and licenseDissect is released as open source by Fox-IT (https://www.fox-it.com) part of NCC Group Plc
(https://www.nccgroup.com).Developed by the Dissect Team (dissect@fox-it.com) and made available athttps://github.com/fox-it/dissect.License terms: Apache License 2.0 (https://www.apache.org/licenses/LICENSE-2.0). For more information, see the LICENSE file.