Data module

Represents location in program which may be absolute or relative.

class ocgraph.internal.data.address.Address(abs_addr: int | None = None, base: str | None = None, offset: int | None = None)

Bases: object

Address Class.

__init__(abs_addr: int | None = None, base: str | None = None, offset: int | None = None) → None

is_absolute() → bool

Return if Address is absolute.

Examples

>>> Address(abs_addr=0x1234).is_absolute()
True
>>> Address(base="fn").is_absolute()
False

is_relative() → bool

Return if Address is relative.

>>> Address(abs_addr=0x1234).is_relative()
False
>>> Address(base="fn").is_relative()
True

Basic Block Class.

class ocgraph.internal.data.basic_block.BasicBlock(key: Any)

Bases: object

Class to represent an object code basic block as node in CFG.

__init__(key: Any) → None

add_instruction(instruction: Instruction) → None: Add instruction to this block.

add_jump_edge(basic_block_key: Any) → None: Add jump target block to this block.

add_no_jump_edge(basic_block_key: Any) → None: Add no jump target block to this block.

Encoding Class.

class ocgraph.internal.data.encoding.Encoding(bites: list[int])

Bases: object

Encoding represents a sequence of bytes for instruction encoding.

E.g. the ‘31 c0’ in:

‘16bd3: 31 c0 xor %eax,%eax’

__init__(bites: list[int]) → None

Represents a function with an address.

class ocgraph.internal.data.function_header.FunctionHeader(name: str, addr: int)

Bases: object

FunctionHeader Class.

__init__(name: str, addr: int) → None: Create a new FunctionHeader.

Represents a single assembly instruction with its operands, location and optional branch target.

class ocgraph.internal.data.instruction.Coverage(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Enumeration for coverage records.

JUMP_BOTH = 'both taken': Indicates, if branch is both jumped and passed

JUMP_PASS = 'skipped': Indicates, if branch is just passed and not jumped

JUMP_TAKEN = 'jumped': Indicates, if branch is just jumped and not passed

LINE_TAKEN = 'taken': Indicates instruction is executed

MISS = 'missed': Indicates instruction is not executed

class ocgraph.internal.data.instruction.Instruction(lineno: int, address: Address, opcode: str, ops: list[str], target: Address | None)

Bases: object

Instruction Class.

__init__(lineno: int, address: Address, opcode: str, ops: list[str], target: Address | None) → None

address: Address | None = None: Computed address of the instruction

assert_coverage(is_branch: bool = False) → None

Assert if the coverage and branch information of the instruction are plausible.

Parameters:: is_branch – Flag whether the instruction associated to the coverage value should be interpreted as a branch

branch_taken: bool | None = None

coverage: Coverage = 'missed': If line is executed on test

lineno: int | None = None: Line number in the file

opcode: str | None = None: Disassembled opcode

ops: list[str] = []: Disassembled operands of the instruction

returns: set[int] = {}: Stores addresses of sink instructions like return

target: Address | None = None: Optional target of the instruction (branch)

update_coverage(addresses: set[int], is_branch: bool = False) → None

Update the coverage information of the instruction.

Parameters:

addresses – Set of addresses executed after this instruction, used to determine whether a branch was taken or not.
is_branch – Flag whether the instruction should be interpreted as a branch

Holds info about branch sources and destinations in asm function.

class ocgraph.internal.data.jump_table.JumpTable(instructions: list[Instruction])

Bases: object

JumpTable Class.

__init__(instructions: list[Instruction]) → None

get_target(addr: Address) → Address | None: Return the target of a branch.

is_jump_target(addr: Address) → bool: Return if address is a destination.