Skip to content

emulator ¤

Emulation assistance from Unicorn.

Classes:

Functions:

Attributes:

arch_to_UC module-attribute ¤

arch_to_UC = {
    "i386": UC_ARCH_X86,
    "x86-64": UC_ARCH_X86,
    "mips": UC_ARCH_MIPS,
    "sparc": UC_ARCH_SPARC,
    "arm": UC_ARCH_ARM,
    "armcm": UC_ARCH_ARM,
    "aarch64": UC_ARCH_ARM64,
    "rv32": UC_ARCH_RISCV,
    "rv64": UC_ARCH_RISCV,
    "s390x": UC_ARCH_S390X,
}

arch_to_UC_consts module-attribute ¤

arch_to_UC_consts = {
    "i386": parse_consts(x86_const),
    "x86-64": parse_consts(x86_const),
    "mips": parse_consts(mips_const),
    "sparc": parse_consts(sparc_const),
    "arm": parse_consts(arm_const),
    "armcm": parse_consts(arm_const),
    "aarch64": parse_consts(arm64_const),
    "rv32": parse_consts(riscv_const),
    "rv64": parse_consts(riscv_const),
    "s390x": parse_consts(s390x_const),
}

arch_to_reg_const_map module-attribute ¤

arch_to_reg_const_map = {
    "i386": create_reg_to_const_map(arch_to_UC_consts["i386"]),
    "x86-64": create_reg_to_const_map(
        arch_to_UC_consts["x86-64"],
        {"FSBASE": UC_X86_REG_FS_BASE, "GSBASE": UC_X86_REG_GS_BASE},
    ),
    "mips": create_reg_to_const_map(arch_to_UC_consts["mips"]),
    "sparc": create_reg_to_const_map(arch_to_UC_consts["sparc"]),
    "arm": create_reg_to_const_map(arch_to_UC_consts["arm"]),
    "armcm": create_reg_to_const_map(arch_to_UC_consts["armcm"]),
    "aarch64": create_reg_to_const_map(
        arch_to_UC_consts["aarch64"], {"CPSR": UC_ARM64_REG_NZCV}
    ),
    "rv32": create_reg_to_const_map(arch_to_UC_consts["rv32"]),
    "rv64": create_reg_to_const_map(arch_to_UC_consts["rv64"]),
    "s390x": create_reg_to_const_map(arch_to_UC_consts["s390x"]),
}

enable_virtual_tlb module-attribute ¤

enable_virtual_tlb = {'s390x': True}

DEBUG module-attribute ¤

DEBUG = NO_DEBUG

arch_to_SYSCALL module-attribute ¤

arch_to_SYSCALL = {
    UC_ARCH_X86: [
        X86_INS_SYSCALL,
        X86_INS_SYSENTER,
        X86_INS_SYSEXIT,
        X86_INS_SYSRET,
        X86_INS_IRET,
        X86_INS_IRETD,
        X86_INS_IRETQ,
        X86_INS_INT,
        X86_INS_INT1,
        X86_INS_INT3,
    ],
    UC_ARCH_MIPS: [MIPS_INS_SYSCALL],
    UC_ARCH_SPARC: [SPARC_INS_T],
    UC_ARCH_ARM: [ARM_INS_SVC],
    UC_ARCH_ARM64: [AARCH64_INS_SVC],
    UC_ARCH_PPC: [PPC_INS_SC],
    UC_ARCH_RISCV: [RISCV_INS_ECALL],
}

ARM_BANNED_INSTRUCTIONS module-attribute ¤

ARM_BANNED_INSTRUCTIONS = {
    ARM_INS_MRC,
    ARM_INS_MRRC,
    ARM_INS_MRC2,
    ARM_INS_MRRC2,
}

BANNED_INSTRUCTIONS module-attribute ¤

BANNED_INSTRUCTIONS = {
    "mips": {MIPS_INS_RDHWR},
    "arm": ARM_BANNED_INSTRUCTIONS,
    "armcm": ARM_BANNED_INSTRUCTIONS,
    "aarch64": {AARCH64_INS_MRS},
}

blacklisted_regs module-attribute ¤

blacklisted_regs = ['ip', 'cs', 'ds', 'es', 'fs', 'gs', 'ss']

e = pwndbg.emu.emulator.Emulator() e.until_jump()

InstructionExecutedResult ¤

Bases: NamedTuple

Attributes:

address instance-attribute ¤

address: int

size instance-attribute ¤

size: int

Emulator ¤

Emulator()

Methods:

Attributes:

arch instance-attribute ¤

arch = name

const_regs instance-attribute ¤

const_regs = arch_to_reg_const_map[arch]

uc_mode instance-attribute ¤

uc_mode = get_uc_mode()

uc instance-attribute ¤

uc = Uc(arch_to_UC[arch], uc_mode)

regs instance-attribute ¤

regs: RegisterSet = current

valid instance-attribute ¤

valid = True

last_pc instance-attribute ¤

last_pc = None

last_single_step_result instance-attribute ¤

last_single_step_result = InstructionExecutedResult(None, None)

last_step_succeeded property ¤

last_step_succeeded: bool

read_register ¤

read_register(name: str)

read_memory ¤

read_memory(address: int, size: int) -> bytes | None

telescope ¤

telescope(address: int, limit: int, read_size: int = None) -> list[int]

format_telescope ¤

format_telescope(address: int, limit: int) -> str

format_telescope_list ¤

format_telescope_list(
    chain: list[int], limit: int, enhance_string_len: int = None
) -> str

telescope_enhance ¤

telescope_enhance(
    value: int, code: bool = True, enhance_string_len: int = None
)

memory_read_string ¤

memory_read_string(
    address: int, max_string_len=None, max_read=None
) -> str | None

__getattr__ ¤

__getattr__(name: str)

update_pc ¤

update_pc(pc=None) -> None

read_thumb_bit ¤

read_thumb_bit() -> int

Return 0 or 1, representing the status of the Thumb bit in the current Arm architecture

This reads from the emulator itself, meaning this can be read to determine a state transitions between non-Thumb and Thumb mode

Return None if the Thumb bit is not relevent to the current architecture

Mimics the read_thumb_bit function defined in aglib/arch.py

get_uc_mode ¤

get_uc_mode()

Retrieve the mode used by Unicorn for the current architecture.

map_page ¤

map_page(page) -> bool

hook_mem_invalid ¤

hook_mem_invalid(uc, access, address, size: int, value, user_data) -> bool

hook_intr ¤

hook_intr(uc, intno, user_data) -> None

We never want to emulate through an interrupt. Just stop.

get_reg_enum ¤

get_reg_enum(reg: str) -> int | None

Returns the Unicorn Emulator enum code for the named register.

Also supports general registers like 'sp' and 'pc'.

hook_add ¤

hook_add(*a, **kw)

hook_del ¤

hook_del(*a, **kw)

emu_start ¤

emu_start(*a, **kw)

emu_stop ¤

emu_stop(*a, **kw)

emulate_with_hook ¤

emulate_with_hook(hook, count=512) -> None

mem_read ¤

mem_read(*a, **kw)

until_jump ¤

until_jump(pc: int = None)

Emulates instructions starting at the specified address until the program counter is set to an address which does not linearly follow the previously-emulated instruction.

Parameters:

  • pc (int, default: None ) –

    Address to start at. If None, uses the current instruction.

Return

Returns a tuple containing the address of the jump instruction, and its target in the format (address, target).

If emulation is forced to stop (e.g., because of a syscall or invalid memory access) then address is the instruction which could not be emulated through, and target will be None.

Notes

This routine does not consider 'call $+5'

until_jump_hook_code ¤

until_jump_hook_code(_uc, address, instruction_size: int, _user_data) -> None

until_call ¤

until_call(pc=None)

until_syscall ¤

until_syscall(pc=None)

Emulates instructions starting at the specified address until the program counter points at a syscall instruction (int 0x80, svc, etc.).

until_syscall_hook_code ¤

until_syscall_hook_code(uc, address, size: int, user_data) -> None

single_step ¤

single_step(pc=None) -> tuple[int, int]

Steps one instruction.

Yields:

  • int –

    Each iteration, yields a tuple of (address_just_executed, instruction_size).

  • int –

    Returns (None, None) upon failure to execute the instruction

single_step_iter ¤

single_step_iter(pc=None)

single_step_hook_code ¤

single_step_hook_code(
    _uc, address: int, instruction_size: int, _user_data
) -> None

dumpregs ¤

dumpregs() -> None

trace_hook ¤

trace_hook(_uc, address, instruction_size: int, _user_data) -> None

__repr__ ¤

__repr__() -> str

parse_consts ¤

parse_consts(u_consts) -> dict[str, int]

Unicorn "consts" is a python module consisting of a variable definition for each known entity. We repack it here as a dict for performance.

Maps "UC_*" -> integer value of the constant

create_reg_to_const_map ¤

create_reg_to_const_map(
    base_consts: dict[str, int], additional_mapping: dict[str, int] = None
) -> dict[str, int]

debug ¤

debug(debug_type, fmt, args=()) -> None