Skip to content

disassembly ¤

Functionality for disassmebling code at an address, or at an address ± a few instructions.

Classes:

Functions:

Attributes:

CapstoneSyntax module-attribute ¤

CapstoneSyntax = {'intel': CS_OPT_SYNTAX_INTEL, 'att': CS_OPT_SYNTAX_ATT}

force_register_alias module-attribute ¤

force_register_alias = add_param(
    "disasm-reg-alias",
    False,
    "force the disassembly to use register aliases (e.g. aarch64 x29 -> fp)",
    param_class=PARAM_BOOLEAN,
    help_docstring="The register aliasing is done by capstone, see:\nhttps://github.com/capstone-engine/capstone/blob/next/docs/cs_v6_release_guide.md#:~:text=None.-,Register%20alias,-Register%20alias%20\n\nEnabling this may make disassembly slower.\n",
)

next_addresses_cache module-attribute ¤

next_addresses_cache: set[int] = set()

delay_slot_cache module-attribute ¤

delay_slot_cache: defaultdict[int, PwndbgInstruction | None] = defaultdict(
    lambda: None
)

linear_backward_cache module-attribute ¤

linear_backward_cache: defaultdict[int, int] = defaultdict(lambda: None)

instruction_sequence_linked_list_map module-attribute ¤

instruction_sequence_linked_list_map: defaultdict[
    int, InstructionSequenceNode | None
] = defaultdict(lambda: None)

fallback_backward_cache module-attribute ¤

fallback_backward_cache: defaultdict[int, int | None] = defaultdict(
    lambda: None
)

computed_instruction_cache module-attribute ¤

computed_instruction_cache: defaultdict[int, PwndbgInstruction | None] = (
    defaultdict(lambda: None)
)

emulated_arm_mode_cache module-attribute ¤

emulated_arm_mode_cache: defaultdict[int, int | None] = defaultdict(
    lambda: None
)

first_time_emulate module-attribute ¤

first_time_emulate = True

ALL_DISASSEMBLY_ASSISTANTS module-attribute ¤

ALL_DISASSEMBLY_ASSISTANTS: dict[
    PWNDBG_SUPPORTED_ARCHITECTURES_TYPE, Callable[[], DisassemblyAssistant]
] = {
    "aarch64": lambda: AArch64DisassemblyAssistant("aarch64"),
    "i386": lambda: X86DisassemblyAssistant("i386"),
    "x86-64": lambda: X86DisassemblyAssistant("x86-64"),
    "arm": lambda: ArmDisassemblyAssistant("arm", "cpsr"),
    "armcm": lambda: ArmDisassemblyAssistant("armcm", "xpsr"),
    "mips": lambda: MipsDisassemblyAssistant("mips"),
    "rv32": lambda: RISCVDisassemblyAssistant("rv32"),
    "rv64": lambda: RISCVDisassemblyAssistant("rv64"),
    "loongarch64": lambda: Loong64DisassemblyAssistant("loongarch64"),
    "powerpc": lambda: PowerPCDisassemblyAssistant("powerpc"),
    "sparc": lambda: SparcDisassemblyAssistant("sparc"),
}

InstructionSequenceNode dataclass ¤

InstructionSequenceNode(
    previous: InstructionSequenceNode | None, instruction: PwndbgInstruction
)

This is used to form a linked list that tracks the order of instructions execution at runtime

Attributes:

previous instance-attribute ¤

previous: InstructionSequenceNode | None

instruction instance-attribute ¤

instruction: PwndbgInstruction

InstructionSequenceSavePointer dataclass ¤

InstructionSequenceSavePointer(node: InstructionSequenceNode | None)

This allows preserving context across calls when disassembling backwards. It stores the node that we just processed internally.

This is like the saveptr parameter of strtok_r.

Attributes:

node instance-attribute ¤

node: InstructionSequenceNode | None

enhance_cache_listener ¤

enhance_cache_listener() -> None

clear_on_reg_mem_change ¤

clear_on_reg_mem_change() -> None

get_instruction_sequence_node ¤

get_instruction_sequence_node(
    address: int, saveptr: InstructionSequenceSavePointer
) -> InstructionSequenceNode | None

Return the node of the linked list at the given address, if it exists

get_previous_instruction ¤

get_previous_instruction(
    address: int,
    use_cache: bool,
    linear: bool,
    saveptr: InstructionSequenceSavePointer,
) -> PwndbgInstruction | None

Retrieve the instruction prior to the instruction at address.

get_disassembler ¤

get_disassembler(cs_info: tuple[int, int]) -> Cs

one ¤

one(
    address: int | None = None,
    emu: Emulator = None,
    enhance: bool = True,
    assistant: DisassemblyAssistant | None = None,
    from_cache: bool = False,
    put_cache: bool = False,
    put_backward_cache: bool = True,
    linear: bool = False,
) -> PwndbgInstruction | None

Return None on failure to fetch an instruction

one_raw ¤

one_raw(address=None) -> PwndbgInstruction | None

get ¤

get(
    address: int,
    instructions: int = 1,
    emu: Emulator | None = None,
    enhance: bool = True,
    assistant: DisassemblyAssistant | None = None,
    padding: int = 6,
) -> list[PwndbgInstruction]

get_one_instruction ¤

get_one_instruction(
    address: int,
    emu: Emulator | None = None,
    enhance: bool = True,
    assistant: DisassemblyAssistant | None = None,
    padding: int = 6,
) -> PwndbgInstruction | None

If passed an emulator, this will pass it to the DisassemblyAssistant which will single_step the emulator to determine the operand values before and after the instruction executes.

can_run_first_emulate ¤

can_run_first_emulate() -> bool

Disable the emulate config variable if we don't have enough memory to use it See #1534 And unicorn-engine/unicorn!1743

no_emulate_one ¤

no_emulate_one()

emulate_one ¤

emulate_one()

one_with_config ¤

one_with_config()

Returns a single Pwndbg Instruction at the current PC.

Emulation determined by the pwndbg.config.emulate setting.

set_visual_split ¤

set_visual_split(
    set_ins: PwndbgInstruction, check_ins: PwndbgInstruction, linear: bool
) -> None

Internal helper function to set the .split property for display purposes.

This should only be called when the callee knows that a split should be created.

set_ins is the instruction that we are modifying

checks_ins is the one used to check what type of split is necessary. The same as set_ins unless it's a delay slot.

near ¤

near(
    address: int,
    forward_count: int = 1,
    backward_count: int = 0,
    total_count: int | None = None,
    end_address: int | None = None,
    emulate=False,
    show_prev_insns=True,
    use_cache=False,
    linear=False,
) -> tuple[list[PwndbgInstruction], int]

Disassembles instructions near given address. Passing emulate makes use of unicorn engine to emulate instructions to predict branches that will be taken. show_prev_insns makes this show previously cached instructions

This allows us to maintain a context of surrounding instructions while single-stepping instructions.

Parameters:

  • forward_count (int, default: 1 ) –

    number of instructions forward from this instruction

  • backward_count (int, default: 0 ) –

    maximum number of previously executed instructions

  • total_count (int | None, default: None ) –

    if set, returns a list with this many instructions in total. The number of backward instructions is limited by backward_count. If this is set, forward_count is ignored.

  • end_address (int | None, default: None ) –

    determines the maximum address (non-inclusive) that can be disassembled.

get_disassembly_assistant_for_current_arch ¤

get_disassembly_assistant_for_current_arch() -> DisassemblyAssistant

arch_has_disassembly_assistant ¤

arch_has_disassembly_assistant(
    arch: PWNDBG_SUPPORTED_ARCHITECTURES_TYPE | None = None,
) -> bool