Module pychrysalide.arch
Class ArchInstruction
Class ArchOperand
Class ArchProcessor
Class ArchRegister
Class InstrIterator
Class ProcContext
Class mrange
Class vmpa
Module pychrysalide.arch
Documentation
Python module for Chrysalide.arch
Sub modules
- pychrysalide.arch.arm
- pychrysalide.arch.dalvik
- pychrysalide.arch.instructions
- pychrysalide.arch.operands
Classes
Class ArchInstruction
PyChrysalide instruction for a given architecture.
Hierarchy
builtins.object ╰── gi._gi.GObject ╰── pychrysalide.arch.ArchInstruction
Implements:
Known subclasses:
- pychrysalide.arch.arm.ArmInstruction
- pychrysalide.arch.dalvik.DalvikInstruction
- pychrysalide.arch.instructions.RawInstruction
- pychrysalide.arch.instructions.UndefInstruction
Methods
attach_operand(self, op)
Add a new operand to the instruction.
detach_operand(self, target)
Remove an operand from the instruction.
find_operand_path(self, target)
Compute the path leading to an instruction operand.
The target
has to be an instance of ArchOperand
included in the instruction.
The result is a string of the form 'n[:n:n:n]', where n is an internal index, or None if the target
is not found. This kind of path is aimed to be built for the find_operand_path()
function.
get_operand_from_path(self, path)
Retrieve an operand from an instruction by its path.
This path
is a string of the form 'n[:n:n:n]', where n is an internal index. Such a path is usually built by the find_operand_path()
function.
The result is an ArchOperand
instance, or None if no operand was found.
replace_operand(self, old, new)
Replace an old instruction operand by a another one.
Attributes
destinations
Provide the instructions list following the current instruction.
Each item of the resulting tuple is a pair of ArchInstruction
instance and InstructionLinkType
value.
keyword
le name of the assembly instruction.
operands
ide the list of instruction attached operands.
range
access to the memory range covered by the current instruction.
sources
Provide the instructions list driving to the current instruction.
Each item of the resulting tuple is a pair of ArchInstruction
instance and InstructionLinkType
value.
uid
ide the unique identification number given to this kind of instruction.
Constants
ArchInstrFlag
Flags for some instruction properties.
1 | = 0x1 |
2 | = 0x2 |
4 | = 0x4 |
8 | = 0x8 |
16 | = 0x10 |
128 | = 0x80 |
InstrProcessHook
Kind of hook for instruction processing after disassembling.
0 | = 0 |
1 | = 1 |
2 | = 2 |
3 | = 3 |
InstructionLinkType
Kind of link between two instructions.
0 | = 0 |
1 | = 1 |
2 | = 2 |
3 | = 3 |
4 | = 4 |
5 | = 5 |
6 | = 6 |
7 | = 7 |
8 | = 8 |
9 | = 9 |
Class ArchOperand
The ArchOperand object aims to get subclassed to create operands of any kind for new architectures.
Calls to the __init__
constructor of this abstract object expect no particular argument.
The following methods have to be defined for new classes:
Some extra method definitions are optional for new classes:
Chrysalide creates an internal glue to provide rich comparisons for operands based on the old-style __cmp__
function.
The object can be compared using rich methods (like <=
or !=
).
Hierarchy
builtins.object ╰── gi._gi.GObject ╰── pychrysalide.arch.ArchOperand
Implements:
Known subclasses:
- pychrysalide.arch.operands.ImmOperand
- pychrysalide.arch.operands.ProxyOperand
- pychrysalide.arch.operands.RegisterOperand
- pychrysalide.arch.operands.TargetOperand
Methods
__cmp__(self, other)
Abstract method used to compare the operand with another one. This second object is always an ArchOperand
instance.
This is the Python old-style comparison method, but Chrysalide provides a glue to automatically build a rich version of this function.
_find_inner_operand_path(self, target)
Abstract method used to compute the path leading to an inner operand.
The target
has to be an instance of ArchOperand
included in the operand.
The result is a string of the form 'n[:n:n:n]', where n is an internal index, or None if the target
is not found. This kind of path is aimed to be built for the find_operand_path()
function.
_get_inner_operand_from_path(self, path)
Abstract method used to retrieve an inner operand by its path.
This path
is a string of the form 'n[:n:n:n]', where n is an internal index. Such a path is usually built by the find_operand_path()
function.
The result is an ArchOperand
instance, or None if no operand was found.
_print(self, line)
Abstract method used to print the operand into a rendering line, which is a provided BufferLine
instance.
find_inner_operand_path(self, target)
Compute the path leading to an inner operand.
The target
has to be an instance of ArchOperand
included in the operand.
The result is a string of the form 'n[:n:n:n]', where n is an internal index, or None if the target
is not found. This kind of path is aimed to be built for the find_operand_path()
function.
get_inner_operand_from_path(self, path)
Retrieve an inner operand by its path.
This path
is a string of the form 'n[:n:n:n]', where n is an internal index. Such a path is usually built by the find_operand_path()
function.
The result is an ArchOperand
instance, or None if no operand was found.
Class ArchProcessor
The ArchProcessor object aims to get subclassed to create processors for new architectures.
Several items have to be defined as class attributes in the final class:
_key
: a string providing a small name used to identify the architecture;_desc
: a string for a human readable description of the new architecture;_memory_size
: size of the memory space, as aMemoryDataSize
value;_ins_min_size
: size of the smallest instruction, as aMemoryDataSize
value;_virtual_space
: a boolean value indicating if the architecture supports a virtual space.
Calls to the __init__
constructor of this abstract object expect the following arguments as keyword parameters:
endianness
: endianness to apply to the binary content to disassemble, as aSourceEndian
value.
Hierarchy
builtins.object ╰── gi._gi.GObject ╰── pychrysalide.arch.ArchProcessor
Implements: pychrysalide.analysis.storage.SerializableObject
Known subclasses:
Methods
add_error(self, type, addr, desc)
Extend the list of detected disassembling errors.
The type of error has to be one of the ArchProcessingError
flags. The location of the error is a vmpa
instance and a one-line description should give some details about what has failed.
disassemble(self, context, content, pos, format)
Disassemble a portion of binary content into one instruction.
find_instr_by_addr(self, addr)
Look for an instruction located at a given address.
get_context(self)
Provide a new disassembly context.
Attributes
desc
Provide a human readable description of the new architecture, as a simple string.
endianness
Provide the processor endianness, as a SourceEndian
value.
errors
List of all detected errors which occurred during the disassembling process.
The result is a tuple of (ArchProcessingError
, vmpa
, string) values, providing a location and a description for each error.
ins_min_size
Provide the minimal size of one processor instruction, as a MemoryDataSize
value.
instrs
access to the disassembled instructions run by the current processor.
key
Provide the small name used to identify the architecture, as a code string.
memory_size
Provide the size of the architecture memory address space, as a MemoryDataSize
value.
virtual_space
Tell if the processor provides a virtual address space. This status is a boolean value.
Constants
ArchProcessingError
Flags for error occurring while disassembling instructions.
1 | = 1 |
Class ArchRegister
The ArchRegister object aims to get subclassed to create registers suitable for new architectures.
Calls to the __init__
constructor of this abstract object expect no particular argument.
The following methods have to be defined for new classes:
Chrysalide creates an internal glue to provide rich comparisons for registers based on the old-style __cmp__
function.
The object can be compared using rich methods (like <=
or !=
).
Hierarchy
builtins.object ╰── gi._gi.GObject ╰── pychrysalide.arch.ArchRegister
Implements: pychrysalide.analysis.storage.SerializableObject
Methods
__cmp__(self, other)
Abstract method used to compare the register with another one. This second object is always an ArchRegister
instance.
This is the Python old-style comparison method, but Chrysalide provides a glue to automatically build a rich version of this function.
__hash__(self)
Abstract method used to produce a hash of the object. The result must be an integer value.
_is_base_pointer(self)
Abstract method used to tell if the register is handling a base pointer. The result must be a boolean value.
_is_stack_pointer(self)
Abstract method used to tell if the register is handling a stack pointer. The result must be a boolean value.
_print(self, line)
Abstract method used to print the register into a rendering line, which is a provided BufferLine
instance.
Attributes
is_base_pointer
Tell if the register is a base pointer or not.
is_stack_pointer
Tell if the register is a stack pointer or not.
Class InstrIterator
Iterator for Chrysalide instructions loaded in a given processor.
Hierarchy
builtins.object ╰── pychrysalide.arch.InstrIterator
Methods
__iter__(self)
Implement iter(self).
__next__(self)
Implement next(self).
restrict(self, range)
Limit the instruction iterator to a memory range.
Class ProcContext
The ProcContext object is a disassembling companion for architecture processors and is usually provided by the get_context()
method.
So each kind of processor should have its dedicated context.
The role of a ProcContext instance is to collect on demand next points to process during a disassembling operation.
The following method may be defined for new classes:
Calls to the __init__
constructor of this abstract object expect no particular argument.
Hierarchy
builtins.object ╰── gi._gi.GObject ╰── pychrysalide.format.PreloadInfo ╰── pychrysalide.arch.ProcContext
Methods
_push_drop_point(self, level, addr, extra=None)
Abstract method used to inject a new virtual address to disassemble during the disassembling process.
The priority of this point is given by the DisassPriorityLevel
value. Extra information may also be provided, as a Python object.
If this method is not defined, the default behavior is to inject the point without any further treatment, as if extra
does not carry any valuable information.
add_db_item(self, item)
Collect an extra item to include in the final disassembled content.
The item to consider has to be a DbItem
instance.
push_drop_point(self, level, addr, extra=None)
Inject a new virtual address to disassemble during the disassembling process.
The priority of this point is given by the DisassPriorityLevel
value. Extra information may also be provided, as a Python object.
push_new_symbol_at(self, addr)
Collect the location of a symbol for the disassembling process.
This location must be able to get converted into a vmpa
instance.
Constants
DisassPriorityLevel
Level of priority for a given point during the disassembling process.
1 | = 1 |
2 | = 2 |
4 | = 4 |
Class mrange
Python object for mrange_t.
The object can be compared using rich methods (like <=
or !=
) and produce an "informal" string representation of itself with a call to str()
.
Hierarchy
builtins.object ╰── pychrysalide.arch.mrange
Methods
contains(self, other)
Tell if the current range contains another given range or address.
Attributes
addr
access to the start location of the memory range.
end
ide the final external point of the memory range.
length
access to the length of the memory range.
Class vmpa
VMPA stands for Virtual Memory or Physical Address.
Thus vmpa objects are locations inside a binary content. Their coordinates are composed of a physical offset and a virtual address. Both of them can be undefined thanks to special values VmpaSpecialValue
.
Instances can be created using the following constructor:
vmpa(phys=NO_PHYSICAL, virt=NO_VIRTUAL)
Where phys and virt are the values of the physical and virtual positions for the location.
The object can be compared using rich methods (like <=
or !=
), has some methods suitable for number operations (such as &
or |
) and produce an "informal" string representation of itself with a call to str()
.
Hierarchy
builtins.object ╰── pychrysalide.arch.vmpa
Attributes
phys
access to the physical offset of the location.
virt
access to the virtual address of the location.
Constants
VmpaSpecialValue
Special values for memory locations.
18446744073709551615 | = 0xffffffffffffffff |
18446744073709551614 | = 0xfffffffffffffffe |