dissect.cstruct
¶
Subpackages¶
dissect.cstruct.types
dissect.cstruct.types.base
dissect.cstruct.types.bytesinteger
dissect.cstruct.types.chartype
dissect.cstruct.types.enum
dissect.cstruct.types.flag
dissect.cstruct.types.instance
dissect.cstruct.types.leb128
dissect.cstruct.types.packedtype
dissect.cstruct.types.pointer
dissect.cstruct.types.structure
dissect.cstruct.types.voidtype
dissect.cstruct.types.wchartype
Submodules¶
Package Contents¶
Classes¶
Implements a bit buffer that can read and write bit fields. |
|
Compiler for cstruct structures. Creates somewhat optimized parsing code. |
|
Expression parser for calculations in definitions. |
|
Implements a fixed or dynamically sized array type. |
|
Base class for cstruct type classes. |
|
Base class for raw types that have a name and size. |
|
Implements an integer type that can span an arbitrary amount of bytes. |
|
Implements a character type that can properly handle strings. |
|
Implements an Enum type. |
|
Implements a value instance of an Enum |
|
Implements a Flag type. |
|
Implements a value instance of a Flag |
|
Holds parsed structure data. |
|
Variable-length code compression to store an arbitrarily large integer in a small number of bytes. |
|
Implements a packed type that uses Python struct packing characters. |
|
Implements a pointer to some other type. |
|
Like the Instance class, but for structures referenced by a pointer. |
|
Holds a structure field. |
|
Type class for structures. |
|
Type class for unions |
|
Implements a void type. |
|
Implements a wide-character type. |
Functions¶
Create ctypes structures from cstruct structures. |
|
Dump a structure or parsed structure instance. |
|
Hexdump some data. |
|
Pack an 8 bit integer. |
|
Pack a 16 bit integer. |
|
Pack a 32 bit integer. |
|
Pack a 64 bit integer. |
|
Pack an integer value to a given bit size, endianness. |
|
Swap the endianness of an integer with a given bit size. |
|
Swap the endianness of a 16 bit integer. |
|
Swap the endianness of a 32 bit integer. |
|
Swap the endianness of a 64 bit integer. |
|
Unpack an 8 bit integer. |
|
Unpack a 16 bit integer. |
|
Unpack a 32 bit integer. |
|
Unpack a 64 bit integer. |
|
Unpack an integer value from a given bit size, endianness and sign. |
- class dissect.cstruct.BitBuffer(stream: BinaryIO, endian: str)¶
Implements a bit buffer that can read and write bit fields.
- read(field_type: dissect.cstruct.types.RawType, bits: int | bytes) int ¶
- write(field_type: dissect.cstruct.types.RawType, data: int, bits: int) None ¶
- flush() None ¶
- reset() None ¶
- class dissect.cstruct.Compiler(cstruct: Compiler.__init__.cstruct)¶
Compiler for cstruct structures. Creates somewhat optimized parsing code.
- TYPES = ()¶
- COMPILE_TEMPLATE = Multiline-String¶
Show Value
""" class {name}(Structure): def __init__(self, cstruct, structure, source=None): self.structure = structure self.source = source super().__init__(cstruct, structure.name, structure.fields, anonymous=structure.anonymous) def _read(self, stream, context=None): r = OrderedDict() sizes = {{}} bitreader = BitBuffer(stream, self.cstruct.endian) {read_code} return Instance(self, r, sizes) def add_field(self, name, type_, offset=None): raise NotImplementedError("Can't add fields to a compiled structure") def __repr__(self): return '<Structure {name} +compiled>' """
- compile(structure: dissect.cstruct.types.Structure) dissect.cstruct.types.Structure ¶
- gen_struct_class(name: str, structure: dissect.cstruct.types.Structure) str ¶
- gen_read_block(size: int, block: List[str]) str ¶
- gen_dynamic_block(field: dissect.cstruct.types.Field) str ¶
- class dissect.cstruct.cstruct(endian: str = '<', pointer: str | None = None)¶
Main class of cstruct. All types are registered in here.
- Parameters:
endian – The endianness to use when parsing.
pointer – The pointer type to use for Pointers.
- DEF_CSTYLE = 1¶
- DEF_LEGACY = 2¶
- __getattr__(attr: str) Any ¶
- addtype(name: str, type_: dissect.cstruct.types.BaseType, replace: bool = False) None ¶
Add a type or type reference.
- Parameters:
name – Name of the type to be added.
type – The type to be added. Can be a str reference to another type or a compatible type class.
- Raises:
ValueError – If the type already exists.
- load(definition: str, deftype: int = None, **kwargs) cstruct ¶
Parse structures from the given definitions using the given definition type.
Definitions can be parsed using different parsers. Currently, there’s only one supported parser - DEF_CSTYLE. Parsers can add types and modify this cstruct instance. Arguments can be passed to parsers using kwargs.
The CSTYLE parser was recently replaced with token based parser, instead of a strictly regex based one. The old parser is still available by using DEF_LEGACY.
- Parameters:
definition – The definition to parse.
deftype – The definition type to parse the definitions with.
**kwargs – Keyword arguments for parsers.
- loadfile(path: str, deftype: int = None, **kwargs) None ¶
Load structure definitions from a file.
The given path will be read and parsed using the .load() function.
- Parameters:
path – The path to load definitions from.
deftype – The definition type to parse the definitions with.
**kwargs – Keyword arguments for parsers.
- read(name: str, stream: BinaryIO) Any ¶
Parse data using a given type.
- Parameters:
name – Type name to read.
stream – File-like object or byte string to parse.
- Returns:
The parsed data.
- resolve(name: str) dissect.cstruct.types.BaseType ¶
Resolve a type name to get the actual type object.
Types can be referenced using different names. When we want the actual type object, we need to resolve these references.
- Parameters:
name – Type name to resolve.
- Returns:
The resolved type object.
- Raises:
ResolveError – If the type can’t be resolved.
- dissect.cstruct.ctypes(structure: dissect.cstruct.types.Structure) ctypes.Structure ¶
Create ctypes structures from cstruct structures.
- dissect.cstruct.ctypes_type(type_: dissect.cstruct.types.BaseType) Any ¶
- exception dissect.cstruct.Error¶
Bases:
Exception
Common base class for all non-exit exceptions.
- exception dissect.cstruct.NullPointerDereference¶
Bases:
Error
Common base class for all non-exit exceptions.
- class dissect.cstruct.Expression(cstruct: Expression.__init__.cstruct, expression: str)¶
Expression parser for calculations in definitions.
- operators¶
- precedence_levels¶
- __repr__() str ¶
Return repr(self).
- precedence(o1: str, o2: str) bool ¶
- evaluate_exp() None ¶
- is_number(token: str) bool ¶
- evaluate(context: dict[str, int] | None = None) int ¶
Evaluates an expression using a Shunting-Yard implementation.
- class dissect.cstruct.Array(cstruct: Array.__init__.cstruct, type_: BaseType, count: int)¶
Bases:
BaseType
Implements a fixed or dynamically sized array type.
Example
When using the default C-style parser, the following syntax is supported:
x[3] -> 3 -> static length. x[] -> None -> null-terminated. x[expr] -> expr -> dynamic length.
- __repr__() str ¶
Return repr(self).
- __len__() int ¶
- default() List[Any] ¶
Return a default value of this type.
- class dissect.cstruct.BaseType(cstruct: BaseType.__init__.cstruct)¶
Base class for cstruct type classes.
- __call__(*args, **kwargs) Any ¶
- reads(data: bytes) Any ¶
Parse the given data according to the type that implements this class.
- Parameters:
data – Byte string to parse.
- Returns:
The parsed value of this type.
- dumps(data: Any) bytes ¶
Dump the given data according to the type that implements this class.
- Parameters:
data – Data to dump.
- Returns:
The resulting bytes.
- Raises:
ArraySizeError – Raised when
len(data)
does not match the size of a statically sized array field.
- read(obj: BinaryIO, *args, **kwargs) Any ¶
Parse the given data according to the type that implements this class.
- Parameters:
obj – Data to parse. Can be a (byte) string or a file-like object.
- Returns:
The parsed value of this type.
- write(stream: BinaryIO, data: Any) int ¶
Write the given data to a writable file-like object according to the type that implements this class.
- Parameters:
stream – Writable file-like object to write to.
data – Data to write.
- Returns:
The amount of bytes written.
- Raises:
ArraySizeError – Raised when
len(data)
does not match the size of a statically sized array field.
- abstract default() Any ¶
Return a default value of this type.
- default_array(count: int) List[Any] ¶
Return a default array of this type.
- class dissect.cstruct.RawType(cstruct: RawType.__init__.cstruct, name: str = None, size: int = 0, alignment: int = None)¶
Bases:
BaseType
Base class for raw types that have a name and size.
- __len__() int ¶
- __repr__() str ¶
Return repr(self).
- abstract default() Any ¶
Return a default value of this type.
- class dissect.cstruct.BytesInteger(cstruct: BytesInteger.__init__.cstruct, name: str, size: int, signed: bool, alignment: int = None)¶
Bases:
dissect.cstruct.types.RawType
Implements an integer type that can span an arbitrary amount of bytes.
- static parse(buf: BinaryIO, size: int, count: int, signed: bool, endian: str) List[int] ¶
- default() int ¶
Return a default value of this type.
- default_array(count: int) List[int] ¶
Return a default array of this type.
- class dissect.cstruct.CharType(cstruct: CharType.__init__.cstruct)¶
Bases:
dissect.cstruct.types.RawType
Implements a character type that can properly handle strings.
- class dissect.cstruct.Enum(cstruct: Enum.__init__.cstruct, name: str, type_: dissect.cstruct.types.BaseType, values: Dict[str, int])¶
Bases:
dissect.cstruct.types.RawType
Implements an Enum type.
Enums can be made using any type. The API for accessing enums and their values is very similar to Python 3 native enums.
Example
When using the default C-style parser, the following syntax is supported:
- enum <name> [: <type>] {
<values>
};
For example, an enum that has A=1, B=5 and C=6 could be written like so:
- enum Testuint16 {
A, B=5, C
};
- __call__(value: int | BinaryIO) EnumInstance ¶
- __getitem__(attr: str) EnumInstance ¶
- __getattr__(attr: str) EnumInstance ¶
- __contains__(attr: str) bool ¶
- default() EnumInstance ¶
Return a default value of this type.
- default_array(count: int) List[EnumInstance] ¶
Return a default array of this type.
- class dissect.cstruct.EnumInstance(enum: Enum, value: int)¶
Implements a value instance of an Enum
- property name: str¶
- __eq__(value: int | EnumInstance) bool ¶
Return self==value.
- __ne__(value: int | EnumInstance) bool ¶
Return self!=value.
- __hash__() int ¶
Return hash(self).
- __str__() str ¶
Return str(self).
- __int__() int ¶
- __repr__() str ¶
Return repr(self).
- class dissect.cstruct.Flag(cstruct: Enum.__init__.cstruct, name: str, type_: dissect.cstruct.types.BaseType, values: Dict[str, int])¶
Bases:
dissect.cstruct.types.Enum
Implements a Flag type.
Flags can be made using any type. The API for accessing flags and their values is very similar to Python 3 native flags.
Example
When using the default C-style parser, the following syntax is supported:
- flag <name> [: <type>] {
<values>
};
For example, a flag that has A=1, B=4 and C=8 could be written like so:
- flag Testuint16 {
A, B=4, C
};
- __call__(value: int | BinaryIO) FlagInstance ¶
- class dissect.cstruct.FlagInstance(enum: Enum, value: int)¶
Bases:
dissect.cstruct.types.EnumInstance
Implements a value instance of a Flag
- property name: str¶
- __nonzero__¶
- __ror__¶
- __rand__¶
- __rxor__¶
- __bool__()¶
- __or__(other: int | FlagInstance) FlagInstance ¶
- __and__(other: int | FlagInstance) FlagInstance ¶
- __xor__(other: int | FlagInstance) FlagInstance ¶
- __invert__() FlagInstance ¶
- __str__() str ¶
Return str(self).
- __repr__() str ¶
Return repr(self).
- decompose() Tuple[List[str], int] ¶
- class dissect.cstruct.Instance(type_: dissect.cstruct.types.BaseType, values: Dict[str, Any], sizes: Dict[str, int] = None)¶
Holds parsed structure data.
- __slots__ = ('_type', '_values', '_sizes')¶
- __getattr__(attr: str) Any ¶
- __setattr__(attr: str, value: Any) None ¶
Implement setattr(self, name, value).
- __getitem__(item: str) Any ¶
- __contains__(attr: str) bool ¶
- __repr__() str ¶
Return repr(self).
- __len__() int ¶
- write(stream: BinaryIO) int ¶
Write this structure to a writable file-like object.
- Parameters:
fh – File-like objects that supports writing.
- Returns:
The amount of bytes written.
- class dissect.cstruct.LEB128(cstruct: LEB128.__init__.cstruct, name: str, size: int, signed: bool, alignment: int = 1)¶
Bases:
dissect.cstruct.types.base.RawType
Variable-length code compression to store an arbitrarily large integer in a small number of bytes.
See https://en.wikipedia.org/wiki/LEB128 for more information and an explanation of the algorithm.
- signed: bool¶
- default() int ¶
Return a default value of this type.
- default_array(count: int) list[int] ¶
Return a default array of this type.
- class dissect.cstruct.PackedType(cstruct: PackedType.__init__.cstruct, name: str, size: int, packchar: str, alignment: int = None)¶
Bases:
dissect.cstruct.types.RawType
Implements a packed type that uses Python struct packing characters.
- default() int ¶
Return a default value of this type.
- default_array(count: int) List[int] ¶
Return a default array of this type.
- class dissect.cstruct.Pointer(cstruct: Pointer.__init__.cstruct, target: dissect.cstruct.types.BaseType)¶
Bases:
dissect.cstruct.types.RawType
Implements a pointer to some other type.
- __repr__() str ¶
Return repr(self).
- class dissect.cstruct.PointerInstance(type_: dissect.cstruct.types.BaseType, stream: BinaryIO, addr: int, ctx: Dict[str, Any])¶
Like the Instance class, but for structures referenced by a pointer.
- __repr__() str ¶
Return repr(self).
- __str__() str ¶
Return str(self).
- __getattr__(attr: str) Any ¶
- __int__() int ¶
- __nonzero__() bool ¶
- __add__(other: int | PointerInstance) PointerInstance ¶
- __sub__(other: int | PointerInstance) PointerInstance ¶
- __mul__(other: int | PointerInstance) PointerInstance ¶
- __floordiv__(other: int | PointerInstance) PointerInstance ¶
- __mod__(other: int | PointerInstance) PointerInstance ¶
- __pow__(other: int | PointerInstance) PointerInstance ¶
- __lshift__(other: int | PointerInstance) PointerInstance ¶
- __rshift__(other: int | PointerInstance) PointerInstance ¶
- __and__(other: int | PointerInstance) PointerInstance ¶
- __xor__(other: int | PointerInstance) PointerInstance ¶
- __or__(other: int | PointerInstance) PointerInstance ¶
- __eq__(other: int | PointerInstance) bool ¶
Return self==value.
- dereference() Any ¶
- class dissect.cstruct.Field(name: str, type_: dissect.cstruct.types.BaseType, bits: int = None, offset: int = None)¶
Holds a structure field.
- __repr__()¶
Return repr(self).
- class dissect.cstruct.Structure(cstruct: Structure.__init__.cstruct, name: str, fields: List[Field] = None, align: bool = False, anonymous: bool = False)¶
Bases:
dissect.cstruct.types.BaseType
Type class for structures.
- __len__() int ¶
- __repr__() str ¶
Return repr(self).
- add_field(name: str, type_: dissect.cstruct.types.BaseType, bits: int = None, offset: int = None) None ¶
Add a field to this structure.
- Parameters:
name – The field name.
type – The field type.
bits – The bit of the field.
offset – The field offset.
- default() dissect.cstruct.types.Instance ¶
Create and return an empty Instance from this structure.
- Returns:
An empty Instance from this structure.
- show(indent: int = 0) None ¶
Pretty print this structure.
- class dissect.cstruct.Union(cstruct: Structure.__init__.cstruct, name: str, fields: List[Field] = None, align: bool = False, anonymous: bool = False)¶
Bases:
Structure
Type class for unions
- __repr__() str ¶
Return repr(self).
- abstract show(indent: int = 0) None ¶
Pretty print this structure.
- class dissect.cstruct.VoidType¶
Bases:
dissect.cstruct.types.RawType
Implements a void type.
- class dissect.cstruct.WcharType(cstruct)¶
Bases:
dissect.cstruct.types.RawType
Implements a wide-character type.
- property encoding: str¶
- default() str ¶
Return a default value of this type.
- default_array(count: int) str ¶
Return a default array of this type.
- dissect.cstruct.dumpstruct(obj, data: bytes = None, offset: int = 0, color: bool = True, output: str = 'print')¶
Dump a structure or parsed structure instance.
Prints a colorized hexdump and parsed structure output.
- Parameters:
obj – Structure or Instance to dump.
data – Bytes to parse the Structure on, if obj is not a parsed Instance.
offset – Byte offset of the hexdump.
output – Output format, can be ‘print’ or ‘string’.
- dissect.cstruct.hexdump(data: bytes, palette=None, offset: int = 0, prefix: str = '', output: str = 'print')¶
Hexdump some data.
- Parameters:
data – Bytes to hexdump.
palette – Colorize the hexdump using this color pattern.
offset – Byte offset of the hexdump.
prefix – Optional prefix.
output – Output format, can be ‘print’, ‘generator’ or ‘string’.
- dissect.cstruct.p8(value: int, endian: str = 'little') bytes ¶
Pack an 8 bit integer.
- Parameters:
value – Value to pack.
endian – Endianness to use (little, big, network, <, > or !)
- dissect.cstruct.p16(value: int, endian: str = 'little') bytes ¶
Pack a 16 bit integer.
- Parameters:
value – Value to pack.
endian – Endianness to use (little, big, network, <, > or !)
- dissect.cstruct.p32(value: int, endian: str = 'little') bytes ¶
Pack a 32 bit integer.
- Parameters:
value – Value to pack.
endian – Endianness to use (little, big, network, <, > or !)
- dissect.cstruct.p64(value: int, endian: str = 'little') bytes ¶
Pack a 64 bit integer.
- Parameters:
value – Value to pack.
endian – Endianness to use (little, big, network, <, > or !)
- dissect.cstruct.pack(value: int, size: int = None, endian: str = 'little') bytes ¶
Pack an integer value to a given bit size, endianness.
- Parameters:
value – Value to pack.
size – Integer size in bits.
endian – Endianness to use (little, big, network, <, > or !)
- dissect.cstruct.swap(value: int, size: int)¶
Swap the endianness of an integer with a given bit size.
- Parameters:
value – Integer to swap.
size – Integer size in bits.
- dissect.cstruct.swap16(value: int) int ¶
Swap the endianness of a 16 bit integer.
- Parameters:
value – Integer to swap.
- dissect.cstruct.swap32(value: int) int ¶
Swap the endianness of a 32 bit integer.
- Parameters:
value – Integer to swap.
- dissect.cstruct.swap64(value: int) int ¶
Swap the endianness of a 64 bit integer.
- Parameters:
value – Integer to swap.
- dissect.cstruct.u8(value: bytes, endian: str = 'little', sign: bool = False) int ¶
Unpack an 8 bit integer.
- Parameters:
value – Value to unpack.
endian – Endianness to use (little, big, network, <, > or !)
sign – Signedness of the integer.
- dissect.cstruct.u16(value: bytes, endian: str = 'little', sign: bool = False) int ¶
Unpack a 16 bit integer.
- Parameters:
value – Value to unpack.
endian – Endianness to use (little, big, network, <, > or !)
sign – Signedness of the integer.
- dissect.cstruct.u32(value: bytes, endian: str = 'little', sign: bool = False) int ¶
Unpack a 32 bit integer.
- Parameters:
value – Value to unpack.
endian – Endianness to use (little, big, network, <, > or !)
sign – Signedness of the integer.
- dissect.cstruct.u64(value: bytes, endian: str = 'little', sign: bool = False) int ¶
Unpack a 64 bit integer.
- Parameters:
value – Value to unpack.
endian – Endianness to use (little, big, network, <, > or !)
sign – Signedness of the integer.
- dissect.cstruct.unpack(value: bytes, size: int = None, endian: str = 'little', sign: bool = False) int ¶
Unpack an integer value from a given bit size, endianness and sign.
- Parameters:
value – Value to unpack.
size – Integer size in bits.
endian – Endianness to use (little, big, network, <, > or !)
sign – Signedness of the integer.