`pypcode`¶

Pythonic interface to SLEIGH

class pypcode.Address¶

Bases: object

Low level machine byte address.

property offset¶: The offset within the space.

property space¶: The address space.

class pypcode.AddrSpace¶

Bases: object

A region where processor data is stored.

property name¶: The name of this address space.

class pypcode.Arch(name, ldefpath)[source]¶

Bases: object

Main class representing an architecture describing available languages.

Parameters:

name (str)
ldefpath (str)

archpath: str¶

archname: str¶

ldefpath: str¶

ldef: ElementTree¶

languages: Sequence[ArchLanguage]¶

classmethod enumerate()[source]¶

Enumerate all available architectures and languages.

Language definitions are sourced from definitions shipped with pypcode and can be found in processors/<architecture>/data/languages/<variant>.ldefs

Return type:: Generator[Arch, None, None]

class pypcode.ArchLanguage(archdir, ldef)[source]¶

Bases: object

A specific language for an architecture. Provides access to language, pspec, and cspecs.

Parameters:

archdir (str)
ldef (Element)

archdir: str¶

ldef: Element¶

property pspec_path: str¶

property slafile_path: str¶

property description: str¶

property pspec: Element | None¶

property cspecs: Mapping[Tuple[str, str], Element]¶

init_context_from_pspec(ctx)[source]¶

Return type:: None
Parameters:: ctx (Context)

classmethod from_id(langid)[source]¶

Return language with given id, or None if the language could not be found.

Return type:: Optional[ArchLanguage]
Parameters:: langid (str)

exception pypcode.BadDataError¶

Bases: Exception

args¶

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class pypcode.Context(language)[source]¶

Bases: Context

Context for translation.

Parameters:: language (ArchLanguage)

language: ArchLanguage¶

registers: Dict[str, Varnode]¶

disassemble¶

Disassemble and format machine code as assembly code.

In [1]: import pypcode
   ...: ctx = pypcode.Context("x86:LE:64:default")
   ...: dx = ctx.disassemble(b"\x48\x35\x78\x56\x34\x12\xc3")
   ...: for ins in dx.instructions:
   ...:     print(f"{ins.addr.offset:#x}/{ins.length}: {ins.mnem} {ins.body}")
   ...: 
0x0/6: XOR RAX,0x12345678
0x6/1: RET 

Instructions are decoded from buf and formatted in Instruction s:

the end of the buffer is reached,
max_bytes or max_instructions is reached, or
an exception occurs.

If an exception occurs following successful disassembly of at least one instruction, the exception is discarded and the successful disassembly is returned. If the exception occurs at disassembly of the first instruction, it will be raised. See below for possible exceptions.

Parameters:

buf (bytes) – Machine code to disassemble.
base_address (int) – Base address of the code at offset being decoded, 0 by default.
offset (int) – Offset into bytes to begin disassembly, 0 by default.
max_bytes (int) – Maximum number of bytes to disassemble, or 0 for no limit (default).
max_instructions (int) – Maximum number of instructions to disassemble, or 0 for no limit (default).

Returns:

The disassembled machine code. Instructions are accessible through Disassembly.instructions.

Return type:

Disassembly

Raises:

BadDataError – The instruction at base_address could be decoded.

getAllRegisters¶: Get a mapping of all register locations to their corresponding names.

getRegisterName¶

Get the name of a register.

Parameters:

space (AddrSpace) – The address space.
offset (int) – Offset within the address space.
size (int) – Size of the register, in bytes.

Returns:

The register name, or the empty string if the register could not be identified.

Return type:

str

reset¶: Reset the context.

setVariableDefault¶: Provide a default value for a context variable.

translate¶

Translate machine code to P-Code.

In [1]: import pypcode
   ...: ctx = pypcode.Context("x86:LE:64:default")
   ...: tx = ctx.translate(b"\x48\x35\x78\x56\x34\x12\xc3")  # xor rax, 0x12345678; ret
   ...: for op in tx.ops:
   ...:     print(pypcode.PcodePrettyPrinter.fmt_op(op))
   ...: 
IMARK ram[0:6]
CF = 0x0
OF = 0x0
RAX = RAX ^ 0x12345678
SF = RAX s< 0x0
ZF = RAX == 0x0
unique[15080:8] = RAX & 0xff
unique[15100:1] = popcount(unique[15080:8])
unique[15180:1] = unique[15100:1] & 0x1
PF = unique[15180:1] == 0x0
IMARK ram[6:1]
RIP = *[ram]RSP
RSP = RSP + 0x8
return RIP

Instructions are decoded from buf and translated to a sequence of PcodeOp s until:

the end of the buffer is reached,
max_bytes or max_instructions is reached,
if the BB_TERMINATING flag is set, an instruction which performs a branch is encountered, or
an exception occurs.

A PcodeOp with opcode OpCode.IMARK is used to identify machine instructions corresponding to a translation. OpCode.IMARK ops precede the corresponding P-Code translation, and will have one or more input Varnode s identifying the address and length in bytes of the source machine instruction(s). The number of input Varnode s depends on the number of instructions that were decoded for the translation of the particular instruction.

On architectures with branch delay slots, the effects of the delay slot instructions will be included in the translation of the branch instruction. For this reason, it is possible that more instructions than specified in max_instructions may be translated. The OpCode.IMARK op identifying the branch instruction will contain an input Varnode corresponding to the branch instruction, with additional input Varnode identifying corresponding delay slot instructions.

If an exception occurs following successful translation of at least one instruction, the exception is discarded and the successful translation is returned. If the exception occurs during translation of the first instruction, the exception will be raised. See below for possible exceptions.

Parameters:

buf (bytes) – Machine code to translate.
base_address (int) – Base address of the code at offset being decoded.
offset (int) – Offset into bytes to begin translation.
max_bytes (int) – Maximum number of bytes to translate.
max_instructions (int) – Maximum number of instructions to translate.
flags (int) – Flags controlling translation. See TranslateFlags.

Returns:

The P-Code translation of the input machine code. P-Code ops are accessible through Translation.ops.

Return type:

Translation

Raises:

BadDataError – The instruction at base_address could not be decoded.
UnimplError – The P-Code for instruction at base_address is not yet implemented.

exception pypcode.DecoderError¶

Bases: Exception

args¶

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class pypcode.Disassembly¶

Bases: object

Machine Code Disassembly.

property instructions¶: The disassembled instructions.

class pypcode.Instruction¶

Bases: object

Disassembled machine code instruction.

property addr¶: Address of this instruction.

property body¶: Operand string of this instruction.

property length¶: Length, in bytes, of this instruction.

property mnem¶: Mnemonic string of this instruction.

exception pypcode.LowlevelError¶

Bases: Exception

args¶

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class pypcode.OpCode(value)¶

Bases: Enum

OpCode defining a specific p-code operation.

IMARK = 0¶

COPY = 1¶

LOAD = 2¶

STORE = 3¶

BRANCH = 4¶

CBRANCH = 5¶

BRANCHIND = 6¶

CALL = 7¶

CALLIND = 8¶

CALLOTHER = 9¶

RETURN = 10¶

INT_EQUAL = 11¶

INT_NOTEQUAL = 12¶

INT_SLESS = 13¶

INT_SLESSEQUAL = 14¶

INT_LESS = 15¶

INT_LESSEQUAL = 16¶

INT_ZEXT = 17¶

INT_SEXT = 18¶

INT_ADD = 19¶

INT_SUB = 20¶

INT_CARRY = 21¶

INT_SCARRY = 22¶

INT_SBORROW = 23¶

INT_2COMP = 24¶

INT_NEGATE = 25¶

INT_XOR = 26¶

INT_AND = 27¶

INT_OR = 28¶

INT_LEFT = 29¶

INT_RIGHT = 30¶

INT_SRIGHT = 31¶

INT_MULT = 32¶

INT_DIV = 33¶

INT_SDIV = 34¶

INT_REM = 35¶

INT_SREM = 36¶

BOOL_NEGATE = 37¶

BOOL_XOR = 38¶

BOOL_AND = 39¶

BOOL_OR = 40¶

FLOAT_EQUAL = 41¶

FLOAT_NOTEQUAL = 42¶

FLOAT_LESS = 43¶

FLOAT_LESSEQUAL = 44¶

FLOAT_NAN = 46¶

FLOAT_ADD = 47¶

FLOAT_DIV = 48¶

FLOAT_MULT = 49¶

FLOAT_SUB = 50¶

FLOAT_NEG = 51¶

FLOAT_ABS = 52¶

FLOAT_SQRT = 53¶

FLOAT_INT2FLOAT = 54¶

FLOAT_FLOAT2FLOAT = 55¶

FLOAT_TRUNC = 56¶

FLOAT_CEIL = 57¶

FLOAT_FLOOR = 58¶

FLOAT_ROUND = 59¶

MULTIEQUAL = 60¶

INDIRECT = 61¶

PIECE = 62¶

SUBPIECE = 63¶

CAST = 64¶

PTRADD = 65¶

PTRSUB = 66¶

SEGMENTOP = 67¶

CPOOLREF = 68¶

NEW = 69¶

INSERT = 70¶

EXTRACT = 71¶

POPCOUNT = 72¶

LZCOUNT = 73¶

class pypcode.OpFormat[source]¶

Bases: object

General op pretty-printer.

static fmt_vn(vn)[source]¶

Return type:: str
Parameters:: vn (Varnode)

fmt(op)[source]¶

Return type:: str
Parameters:: op (PcodeOp)

class pypcode.OpFormatBinary(operator)[source]¶

Bases: OpFormat

General binary op pretty-printer.

Parameters:: operator (str)

operator¶

fmt(op)[source]¶

Return type:: str
Parameters:: op (PcodeOp)

static fmt_vn(vn)¶

Return type:: str
Parameters:: vn (Varnode)

class pypcode.OpFormatFunc(operator)[source]¶

Bases: OpFormat

Function-call style op pretty-printer.

Parameters:: operator (str)

operator¶

fmt(op)[source]¶

Return type:: str
Parameters:: op (PcodeOp)

static fmt_vn(vn)¶

Return type:: str
Parameters:: vn (Varnode)

class pypcode.OpFormatSpecial[source]¶

Bases: OpFormat

Specialized op pretty-printers.

fmt_BRANCH(op)[source]¶

Return type:: str
Parameters:: op (PcodeOp)

fmt_BRANCHIND(op)[source]¶

Return type:: str
Parameters:: op (PcodeOp)

fmt_CALL(op)[source]¶

Return type:: str
Parameters:: op (PcodeOp)

fmt_CALLIND(op)[source]¶

Return type:: str
Parameters:: op (PcodeOp)

static fmt_vn(vn)¶

Return type:: str
Parameters:: vn (Varnode)

fmt_CBRANCH(op)[source]¶

Return type:: str
Parameters:: op (PcodeOp)

fmt_LOAD(op)[source]¶

Return type:: str
Parameters:: op (PcodeOp)

fmt_RETURN(op)[source]¶

Return type:: str
Parameters:: op (PcodeOp)

fmt_STORE(op)[source]¶

Return type:: str
Parameters:: op (PcodeOp)

fmt(op)[source]¶

Return type:: str
Parameters:: op (PcodeOp)

class pypcode.OpFormatUnary(operator)[source]¶

Bases: OpFormat

General unary op pretty-printer.

Parameters:: operator (str)

operator¶

fmt(op)[source]¶

Return type:: str
Parameters:: op (PcodeOp)

static fmt_vn(vn)¶

Return type:: str
Parameters:: vn (Varnode)

class pypcode.PcodeOp¶

Bases: object

Low-level representation of a single P-Code operation.

property inputs¶: Input varnodes for this operation.

property opcode¶: Opcode for this operation.

property output¶: Output varnode for this operation.

class pypcode.PcodePrettyPrinter[source]¶

Bases: object

P-code pretty-printer.

DEFAULT_OP_FORMAT = <pypcode.OpFormat object>¶

OP_FORMATS = {OpCode.BOOL_AND: <pypcode.OpFormatBinary object>, OpCode.BOOL_NEGATE: <pypcode.OpFormatUnary object>, OpCode.BOOL_OR: <pypcode.OpFormatBinary object>, OpCode.BOOL_XOR: <pypcode.OpFormatBinary object>, OpCode.BRANCH: <pypcode.OpFormatSpecial object>, OpCode.BRANCHIND: <pypcode.OpFormatSpecial object>, OpCode.CALL: <pypcode.OpFormatSpecial object>, OpCode.CALLIND: <pypcode.OpFormatSpecial object>, OpCode.CBRANCH: <pypcode.OpFormatSpecial object>, OpCode.COPY: <pypcode.OpFormatUnary object>, OpCode.CPOOLREF: <pypcode.OpFormatFunc object>, OpCode.FLOAT_ABS: <pypcode.OpFormatFunc object>, OpCode.FLOAT_ADD: <pypcode.OpFormatBinary object>, OpCode.FLOAT_CEIL: <pypcode.OpFormatFunc object>, OpCode.FLOAT_DIV: <pypcode.OpFormatBinary object>, OpCode.FLOAT_EQUAL: <pypcode.OpFormatBinary object>, OpCode.FLOAT_FLOAT2FLOAT: <pypcode.OpFormatFunc object>, OpCode.FLOAT_FLOOR: <pypcode.OpFormatFunc object>, OpCode.FLOAT_INT2FLOAT: <pypcode.OpFormatFunc object>, OpCode.FLOAT_LESS: <pypcode.OpFormatBinary object>, OpCode.FLOAT_LESSEQUAL: <pypcode.OpFormatBinary object>, OpCode.FLOAT_MULT: <pypcode.OpFormatBinary object>, OpCode.FLOAT_NAN: <pypcode.OpFormatFunc object>, OpCode.FLOAT_NEG: <pypcode.OpFormatUnary object>, OpCode.FLOAT_NOTEQUAL: <pypcode.OpFormatBinary object>, OpCode.FLOAT_ROUND: <pypcode.OpFormatFunc object>, OpCode.FLOAT_SQRT: <pypcode.OpFormatFunc object>, OpCode.FLOAT_SUB: <pypcode.OpFormatBinary object>, OpCode.FLOAT_TRUNC: <pypcode.OpFormatFunc object>, OpCode.INT_2COMP: <pypcode.OpFormatUnary object>, OpCode.INT_ADD: <pypcode.OpFormatBinary object>, OpCode.INT_AND: <pypcode.OpFormatBinary object>, OpCode.INT_CARRY: <pypcode.OpFormatFunc object>, OpCode.INT_DIV: <pypcode.OpFormatBinary object>, OpCode.INT_EQUAL: <pypcode.OpFormatBinary object>, OpCode.INT_LEFT: <pypcode.OpFormatBinary object>, OpCode.INT_LESS: <pypcode.OpFormatBinary object>, OpCode.INT_LESSEQUAL: <pypcode.OpFormatBinary object>, OpCode.INT_MULT: <pypcode.OpFormatBinary object>, OpCode.INT_NEGATE: <pypcode.OpFormatUnary object>, OpCode.INT_NOTEQUAL: <pypcode.OpFormatBinary object>, OpCode.INT_OR: <pypcode.OpFormatBinary object>, OpCode.INT_REM: <pypcode.OpFormatBinary object>, OpCode.INT_RIGHT: <pypcode.OpFormatBinary object>, OpCode.INT_SBORROW: <pypcode.OpFormatFunc object>, OpCode.INT_SCARRY: <pypcode.OpFormatFunc object>, OpCode.INT_SDIV: <pypcode.OpFormatBinary object>, OpCode.INT_SEXT: <pypcode.OpFormatFunc object>, OpCode.INT_SLESS: <pypcode.OpFormatBinary object>, OpCode.INT_SLESSEQUAL: <pypcode.OpFormatBinary object>, OpCode.INT_SREM: <pypcode.OpFormatBinary object>, OpCode.INT_SRIGHT: <pypcode.OpFormatBinary object>, OpCode.INT_SUB: <pypcode.OpFormatBinary object>, OpCode.INT_XOR: <pypcode.OpFormatBinary object>, OpCode.INT_ZEXT: <pypcode.OpFormatFunc object>, OpCode.LOAD: <pypcode.OpFormatSpecial object>, OpCode.LZCOUNT: <pypcode.OpFormatFunc object>, OpCode.NEW: <pypcode.OpFormatFunc object>, OpCode.POPCOUNT: <pypcode.OpFormatFunc object>, OpCode.RETURN: <pypcode.OpFormatSpecial object>, OpCode.STORE: <pypcode.OpFormatSpecial object>}¶

classmethod fmt_op(op)[source]¶

Return type:: str
Parameters:: op (PcodeOp)

class pypcode.TranslateFlags(value)[source]¶

Bases: IntEnum

Flags that can be passed to Context::translate

BB_TERMINATING = 1¶

conjugate()¶: Returns self, the complex conjugate of any int.

bit_length()¶

Number of bits necessary to represent self in binary.

>>> bin(37)
'0b100101'
>>> (37).bit_length()
6

bit_count()¶

Number of ones in the binary representation of the absolute value of self.

Also known as the population count.

>>> bin(13)
'0b1101'
>>> (13).bit_count()
3

to_bytes(length, byteorder, *, signed=False)¶

Return an array of bytes representing an integer.

length: Length of bytes object to use. An OverflowError is raised if the integer is not representable with the given number of bytes.
byteorder: The byte order used to represent the integer. If byteorder is ‘big’, the most significant byte is at the beginning of the byte array. If byteorder is ‘little’, the most significant byte is at the end of the byte array. To request the native byte order of the host system, use `sys.byteorder’ as the byte order value.
signed: Determines whether two’s complement is used to represent the integer. If signed is False and a negative integer is given, an OverflowError is raised.

from_bytes(byteorder, *, signed=False)¶

Return the integer represented by the given array of bytes.

bytes: Holds the array of bytes to convert. The argument must either support the buffer protocol or be an iterable object producing bytes. Bytes and bytearray are examples of built-in objects that support the buffer protocol.
byteorder: The byte order used to represent the integer. If byteorder is ‘big’, the most significant byte is at the beginning of the byte array. If byteorder is ‘little’, the most significant byte is at the end of the byte array. To request the native byte order of the host system, use `sys.byteorder’ as the byte order value.
signed: Indicates whether two’s complement is used to represent the integer.

as_integer_ratio()¶

Return integer ratio.

Return a pair of integers, whose ratio is exactly equal to the original int and with a positive denominator.

>>> (10).as_integer_ratio()
(10, 1)
>>> (-10).as_integer_ratio()
(-10, 1)
>>> (0).as_integer_ratio()
(0, 1)

real¶: the real part of a complex number

imag¶: the imaginary part of a complex number

numerator¶: the numerator of a rational number in lowest terms

denominator¶: the denominator of a rational number in lowest terms

class pypcode.Translation¶

Bases: object

P-Code translation.

property ops¶: The translated sequence of P-Code ops.

exception pypcode.UnimplError¶

Bases: Exception

args¶

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class pypcode.Varnode¶

Bases: object

Data defining a specific memory location.

getRegisterName¶: Return the register name if this Varnode references a register, otherwise return the empty string.

getSpaceFromConst¶: Recover encoded address space from constant value.

property offset¶: The offset within the space.

property size¶: The number of bytes in the location.

property space¶: The address space.

pypcode¶

`pypcode`¶