`pypcode`¶

Pythonic interface to SLEIGH

class pypcode.Address¶

Bases: object

Low level machine byte address.

Address.offset -> int: The offset within the space.

Address.space -> AddrSpace: The address space.

class pypcode.AddrSpace¶

Bases: object

A region where processor data is stored.

AddrSpace.name -> str: 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: ET.ElementTree[ET.Element[str]]¶

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]

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:: ArchLanguage | None
Parameters:: langid (str)

exception pypcode.BadDataError¶

Bases: Exception

add_note()¶: Exception.add_note(note) – add a note to the 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)

disassemble(self, buf: bytes, base_address: int = 0, offset: int = 0, max_bytes: int = 0, max_instructions: int = 0) → pypcode.pypcode_native.Disassembly¶

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.

Args:
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:
Disassembly: The disassembled machine code. Instructions are accessible through Disassembly.instructions.

Raises:
BadDataError: The instruction at base_address could be decoded.

Return type:: Disassembly

getAllRegisters(self) → dict[pypcode.pypcode_native.Varnode, str]¶

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

Return type:: dict[Varnode, str]

getRegisterName(self, space: pypcode.pypcode_native.AddrSpace, offset: int, size: int) → str¶

Get the name of a register.

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

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

Return type:: str

reset(self) → None¶

Reset the context.

Return type:: None

setVariableDefault(self, name: str, value: int) → None¶

Provide a default value for a context variable.

Return type:: None

translate(self, buf: bytes, base_address: int = 0, offset: int = 0, max_bytes: int = 0, max_instructions: int = 0, flags: int = 0) → pypcode.pypcode_native.Translation¶

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
   ...: print(tx)
   ...: 
IMARK ram[0:6]
CF = 0x0
OF = 0x0
RAX = RAX ^ 0x12345678
SF = RAX s< 0x0
ZF = RAX == 0x0
unique[58300:8] = RAX & 0xff
unique[58400:1] = popcount(unique[58300:8])
unique[58500:1] = unique[58400:1] & 0x1
PF = unique[58500: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.

Args:
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:
Translation: The P-Code translation of the input machine code. P-Code ops are accessible through Translation.ops.

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

Return type:: Translation

language: ArchLanguage¶

registers: dict[str, Varnode]¶

exception pypcode.DecoderError¶

Bases: Exception

add_note()¶: Exception.add_note(note) – add a note to the exception

args¶

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

class pypcode.Disassembly¶

Bases: object

Machine Code Disassembly.

Disassembly.instructions -> List[Instruction]: The disassembled instructions.

class pypcode.Instruction¶

Bases: object

Disassembled machine code instruction.

Instruction.addr -> Address: Address of this instruction.

Instruction.body -> str: Operand string of this instruction.

Instruction.length -> int: Length, in bytes, of this instruction.

Instruction.mnem -> str: Mnemonic string of this instruction.

exception pypcode.LowlevelError¶

Bases: Exception

add_note()¶: Exception.add_note(note) – add a note to the exception

args¶

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

class pypcode.OpCode(*values)¶

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¶

ZPULL = 71¶

POPCOUNT = 72¶

LZCOUNT = 73¶

SPULL = 74¶

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)

fmt_CALLOTHER(op)[source]¶

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

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)

static fmt_vn(vn)¶

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

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.

PcodeOp.inputs -> List[Varnode]: Input varnodes for this operation.

PcodeOp.opcode -> OpCode: Opcode for this operation.

PcodeOp.output -> Optional[Varnode]: Output varnode for this operation.

class pypcode.PcodePrettyPrinter[source]¶

Bases: object

P-code pretty-printer.

DEFAULT_OP_FORMAT = <pypcode.printing.OpFormat object>¶

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

static fmt_op(op)[source]¶

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

static fmt_translation(tx)[source]¶

Return type:: str
Parameters:: tx (Translation)

class pypcode.TranslateFlags(*values)[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=1, byteorder='big', *, 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. Default is length 1.
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. Default is to use ‘big’.
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.

classmethod from_bytes(bytes, byteorder='big', *, 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. Default is to use ‘big’.
signed: Indicates whether two’s complement is used to represent the integer.

as_integer_ratio()¶

Return a pair of integers, whose ratio is equal to the original int.

The ratio is in lowest terms and has a positive denominator.

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

is_integer()¶: Returns True. Exists for duck type compatibility with float.is_integer.

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.

Translation.ops -> List[PcodeOp]: The translated sequence of P-Code ops.

exception pypcode.UnimplError¶

Bases: Exception

add_note()¶: Exception.add_note(note) – add a note to the exception

args¶

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

class pypcode.Varnode(*args, **kwargs)¶

Bases: object

Data defining a specific memory location.

getRegisterName(self) → str¶

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

Return type:: str

getSpaceFromConst(self) → pypcode.pypcode_native.AddrSpace¶

Recover encoded address space from constant value.

Return type:: AddrSpace

getUserDefinedOpName(self) → str¶

Get the name of a user defined operation.

Return type:: str

Varnode.offset -> int: The offset within the space.

Varnode.size -> int: The number of bytes in the location.

Varnode.space -> AddrSpace: The address space.

pypcode¶

`pypcode`¶