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.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. |
|
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) None #
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.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.