repl ¤

The Pwndbg REPL that is the interface to all debugging on LLDB.

Pwndbg has an event system that allows it to react to events in the process being debugged, such as when new executable modules get added to the its address space, when the value of memory and registers change, and pretty much all possible changes to its execution state. We'd like to have the event system work the same way under LLDB as it does under GDB.

Fortunately for us, the events types that are native to LLDB map really well to the event types in GDB and Pwndbg. Very, very unfortunately for us, however, that's basically where our luck ends.

LLDB, as of version 18, only provides two ways to capture events: registering directly with the broadcaster, or registering globally. The former is not available to us in the standard LLDB REPL, as we don't get access to the process object until after it's been launched1. Likewise for the latter, as the interactive debugger will register to receive the global process state change events before everyone else, and LLDB doesn't allow for multiple listeners for the same event bits in the same event class2.

This leaves us with handling process management ourselves as the only option we really have to implement event dispatch in Pwndbg. Easy, right? We can just hijack the commands that deal with target and process creation, and leave everything else untouched. Unfortunately for us, again, shadowing builtin commands is simply not allowed3.

So, really, all that's left for us is either implement our own REPL, or get rid of the event system.

Modules:

• io –

  For our REPL, we need to drive our own I/O with the process being debugged. This

• proc –
• readline –

  Readline interface for the Pwndbg LLDB REPL.

Classes:

• EventRelay –

  The event system that is sensible for the REPL process driver to use isn't

• YieldExecDirect –

  Execute the given command directly, on behalf of the user.

• YieldInteractive –

  Prompt the user for the next command.

• PwndbgController –

  Class providing interfaces for a client to control the behavior of Pwndbg

Functions:

• lex_args –

  Splits the arguments, respecting quotation marks.

• show_greeting –

  Show the Pwndbg greeting, the same way the GDB version of Pwndbg would. This

• run –

  Runs the Pwndbg CLI through the given asynchronous controller.

• exec_repl_command –

  Parses and runs the given command, returning whether the event loop should continue.

• parse –

  Parses a list of string arguments into an object containing the parsed

• run_ipython_shell –
• target_create –

  Creates a new target, registers it with the Pwndbg LLDB implementation, and

• process_launch –

  Launches a process with the given arguments.

• process_attach –

  Attaches to a process with the given arguments.

• attach –

  Attaches to a process with the given name or pid based on regex match.

• process_connect –

  Connects to the given remote process.

• gdb_remote –

  Like process_connect, but more lenient with the remote URL format.

• continue_process –

  Continues the execution of a process.

Attributes:

• show_tip –
• LLDB_EXCLUSIVE –
• target_create_ap –
• target_create_unsupported –
• process_launch_ap –
• process_launch_unsupported –
• process_attach_ap –
• process_attach_unsupported –
• process_connect_ap –
• gdb_remote_ap –
• continue_ap –
• continue_unsupported –

show_tip = add_param(
    "show-tips", True, "whether to display the tip of the day on startup"
)

LLDB_EXCLUSIVE = [
    ("script", lambda cmd: startswith("sc") and startswith(cmd)),
    ("expression", lambda cmd: startswith("e") and startswith(cmd)),
]

target_create_ap = ArgumentParser(add_help=False)

target_create_unsupported = [
    "build",
    "core",
    "no-dependents",
    "remote-file",
    "symfile",
    "version",
]

process_launch_ap = ArgumentParser(add_help=False)

process_launch_unsupported = [
    "disable-aslr",
    "script-class",
    "environment",
    "plugin",
    "shell-expand-args",
    "arch",
    "shell",
    "stderr",
    "stdin",
    "structured-data-key",
    "no-stdio",
    "stdout",
    "tty",
    "structured-data-value",
    "working-dir",
]

process_attach_ap = ArgumentParser(add_help=False)

process_attach_unsupported = [
    "python-class",
    "plugin",
    "structured-data-key",
    "structured-data-value",
]

process_connect_ap = ArgumentParser(add_help=False)

gdb_remote_ap = ArgumentParser(add_help=False)

continue_ap = ArgumentParser(add_help=False)

continue_unsupported = ['ignore-count']

EventRelay(dbg: LLDB)

dbg = dbg

ignore_resumed = 0

created()

suspended()

resumed()

exited()

modules_loaded()

YieldExecDirect(command: str, capture: bool, prompt_silent: bool)

interactive() -> Awaitable[None]

execute(command: str) -> Awaitable[None]

execute_and_capture(command: str) -> Awaitable[bytes]

lex_args(args: str) -> list[str]

show_greeting() -> None

run(
    controller: Callable[[PwndbgController], Coroutine[Any, Any, None]],
    debug: bool = False,
) -> None

exec_repl_command(
    line: str,
    lldb_out_target: BinaryIO,
    dbg: LLDB,
    driver: ProcessDriver,
    relay: EventRelay,
) -> bool

parse(
    args: list[str], parser: ArgumentParser, unsupported: list[str]
) -> Any | None

run_ipython_shell()

target_create(args: list[str], dbg: LLDB) -> None

process_launch(
    driver: ProcessDriver, relay: EventRelay, args: list[str], dbg: LLDB
) -> None

process_attach(
    driver: ProcessDriver, relay: EventRelay, args: list[str], dbg: LLDB
) -> None

attach(
    driver: ProcessDriver, relay: EventRelay, args: list[str], dbg: LLDB
) -> None

process_connect(
    driver: ProcessDriver, relay: EventRelay, args: list[str], dbg: LLDB
) -> None

gdb_remote(
    driver: ProcessDriver, relay: EventRelay, args: list[str], dbg: LLDB
) -> None

continue_process(driver: ProcessDriver, args: list[str], dbg: LLDB) -> None