@ -30,7 +30,7 @@ smoothing out rough edges and making them more user-friendly.
## Installation
## Installation
See [installation instructions](https://pwndbg.re/pwndbg/latest/setup).
See [installation instructions](https://pwndbg.re/latest/setup).
## What about ...?
## What about ...?
@ -80,7 +80,7 @@ Pwndbg ensures a consistent experience across both, so switching between them is
## Contributing
## Contributing
Pull requests are welcome ❤️. Check out the [Contributing Guide](https://pwndbg.re/pwndbg/dev/contributing/).
Pull requests are welcome ❤️. Check out the [Contributing Guide](https://pwndbg.re/dev/contributing/).
## Acknowledgements
## Acknowledgements
Pwndbg was originally created by [Zach Riggle](https://github.com/zachriggle), who is no longer with us. We want to thank Zach for all of his contributions to pwndbg and the wider security community.
Pwndbg was originally created by [Zach Riggle](https://github.com/zachriggle), who is no longer with us. We want to thank Zach for all of his contributions to pwndbg and the wider security community.
@ -41,7 +41,7 @@ We will cover the first four arguments now, and come back to the rest later.
If your command takes no arguments you can pass the description of the command as the first argument (`parser_or_desc`) to the constructor. Otherwise you will be passing an [`argparse.ArgumentParser`](https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser) object there.
If your command takes no arguments you can pass the description of the command as the first argument (`parser_or_desc`) to the constructor. Otherwise you will be passing an [`argparse.ArgumentParser`](https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser) object there.
The only other required argument is `category`. The `category` determines how commands are grouped together in the output of the [`pwndbg`](https://pwndbg.re/pwndbg/dev/commands/pwndbg/pwndbg/) command and in the [documentation](https://pwndbg.re/pwndbg/dev/commands/). Peruse the list of all commands inside a debugger (by running the `pwndbg` command) and decide in which category your command fits best. The enum of all command categories is defined at the top of the `pwndbg/commands/__init__.py` file.
The only other required argument is `category`. The `category` determines how commands are grouped together in the output of the [`pwndbg`](../commands/pwndbg/pwndbg.md) command and in the [documentation](../commands/index.md). Peruse the list of all commands inside a debugger (by running the `pwndbg` command) and decide in which category your command fits best. The enum of all command categories is defined at the top of the `pwndbg/commands/__init__.py` file.
### Picking a command name
### Picking a command name
Next, the `command_name` argument. It is optional because if it is not specified the command name will be the same as the function you used to define the command (except the underscores are replaced with dashes). As such, it is generally not needed to specify this argument.
Next, the `command_name` argument. It is optional because if it is not specified the command name will be the same as the function you used to define the command (except the underscores are replaced with dashes). As such, it is generally not needed to specify this argument.
@ -53,7 +53,7 @@ If the command name contains three or more words, you should use dashes to make
You provide aliases to a command by specifying a list of strings to the `aliases` argument. Again, you may provide aliases to help users transitioning from other tools/debuggers (e.g. `nearpc [pdisass, u]`).
You provide aliases to a command by specifying a list of strings to the `aliases` argument. Again, you may provide aliases to help users transitioning from other tools/debuggers (e.g. `nearpc [pdisass, u]`).
## The arguments your command will take
## The arguments your command will take
We are using [`argparse.ArgumentParser`](https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser) from the python standard library to define command arguments. Take a look at the python documentation to see how it works. Let's take a look at an example from the source (the [`setflag`](https://pwndbg.re/pwndbg/dev/commands/register/setflag/) command):
We are using [`argparse.ArgumentParser`](https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser) from the python standard library to define command arguments. Take a look at the python documentation to see how it works. Let's take a look at an example from the source (the [`setflag`](../commands/register/setflag.md) command):
```python
```python
parser = argparse.ArgumentParser(description="Modify the flags register.")
parser = argparse.ArgumentParser(description="Modify the flags register.")
@ -161,7 +161,7 @@ This command supports flags registers that are defined for architectures in the
def setflag(flag: str, value: int) -> None:
def setflag(flag: str, value: int) -> None:
# ....
# ....
```
```
When writing this (and the command description for that matter), you should consider what it will [look like in the documentation](https://pwndbg.re/pwndbg/dev/commands/register/setflag/) after being parsed as markdown.
When writing this (and the command description for that matter), you should consider what it will [look like in the documentation](../commands/register/setflag.md) after being parsed as markdown.
As for `only_debuggers` and `exclude_debuggers`, you must use (usually one of) them if your command does not work an all debuggers that Pwndbg supports. For instance, if it uses some features from `pwndbg.gdblib` (which should be avoided if at all possible). In such a case, you probably also need to conditionally import it in the `load_commands` function.
As for `only_debuggers` and `exclude_debuggers`, you must use (usually one of) them if your command does not work an all debuggers that Pwndbg supports. For instance, if it uses some features from `pwndbg.gdblib` (which should be avoided if at all possible). In such a case, you probably also need to conditionally import it in the `load_commands` function.
Note that the last two lines are automatically generated by Pwndbg.
Note that the last two lines are automatically generated by Pwndbg.
When writing this explanation, it is important to take into account how it will be displayed [in the documentation](https://pwndbg.re/pwndbg/dev/configuration/) after being parsed as markdown. See what `gdb-workaround-stop-event` looks like here: https://pwndbg.re/pwndbg/dev/configuration/config/#gdb-workaround-stop-event . If there wasn't an empty line between `Values explained:` and ``+ `disabled`..`` the list wouldn't have rendered properly.
When writing this explanation, it is important to take into account how it will be displayed [in the documentation](../configuration/index.md) after being parsed as markdown. See what `gdb-workaround-stop-event` looks like [here](../configuration/config.md#gdb-workaround-stop-event). If there wasn't an empty line between `Values explained:` and ``+ `disabled`..`` the list wouldn't have rendered properly.
## param_class
## param_class
This argument describes the type of the parameter. It will be used by GDB to perform input validation when the parameter is being set so it is important to set this to the correct value. The possible values are defined in `pwndbg/lib/config.py`, use the most restrictive one that fits:
This argument describes the type of the parameter. It will be used by GDB to perform input validation when the parameter is being set so it is important to set this to the correct value. The possible values are defined in `pwndbg/lib/config.py`, use the most restrictive one that fits:
```python
```python
@ -134,7 +134,7 @@ class Scope(Enum):
theme = 2
theme = 2
heap = 3
heap = 3
```
```
The parameters of each scope are printed using a different command. The `config` scope is printed with [`config`](https://pwndbg.re/pwndbg/dev/commands/pwndbg/config/), the `heap` scope is printed with [`heap-config`](https://pwndbg.re/pwndbg/dev/commands/pwndbg/heap-config/) and the `theme` scope is printed with [`theme`](https://pwndbg.re/pwndbg/dev/commands/pwndbg/theme/). The `config` and `theme` scopes also have corresponding [`configfile`](https://pwndbg.re/pwndbg/dev/commands/pwndbg/configfile/) and [`themefile`](https://pwndbg.re/pwndbg/dev/commands/pwndbg/themefile/) commands which export the values of all the parameters from those scopes.
The parameters of each scope are printed using a different command. The `config` scope is printed with [`config`](../commands/pwndbg/config.md), the `heap` scope is printed with [`heap-config`](../commands/pwndbg/heap-config.md) and the `theme` scope is printed with [`theme`](../commands/pwndbg/theme.md). The `config` and `theme` scopes also have corresponding [`configfile`](../commands/pwndbg/configfile.md) and [`themefile`](../commands/pwndbg/themefile.md) commands which export the values of all the parameters from those scopes.
### The `theme` scope
### The `theme` scope
You should never directly pass this scope to `pwndbg.config.add_param`. Instead use the `pwndbg.color.theme.add_param` and `pwndbg.color.theme.add_color_param` wrapper commands like this:
You should never directly pass this scope to `pwndbg.config.add_param`. Instead use the `pwndbg.color.theme.add_param` and `pwndbg.color.theme.add_color_param` wrapper commands like this:
Whatever you now do in the terminal will be "recorded" to the `my_thingy.tape` file. Exit the shell to save the recording. The tape probably isn't ready to use as-is. You will want to add some metadata and fixup some lines.
Whatever you now do in the terminal will be "recorded" to the `my_thingy.tape` file. Exit the shell to save the recording. The tape probably isn't ready to use as-is. You will want to add some metadata and fixup some lines.
??? example
??? example
This is the tape used to generate the gif at https://pwndbg.re/pwndbg/dev/commands/context/context/ :
This is the tape used to generate the gif at https://pwndbg.re/dev/commands/context/context/ :
pwndbg (/paʊnˈdiˌbʌɡ/) is a GDB plug-in that makes debugging with GDB suck less, with a focus on features needed by low-level software developers, hardware hackers, reverse-engineers and exploit developers.
pwndbg (/paʊnˈdiˌbʌɡ/) is a GDB plug-in that makes debugging with GDB suck less, with a focus on features needed by low-level software developers, hardware hackers, reverse-engineers and exploit developers.
"Pwndbg context displays where the program branches to thanks to emulating few instructions into the future. You can disable this with `set emulate off` which may also speed up debugging",
"Pwndbg context displays where the program branches to thanks to emulating few instructions into the future. You can disable this with `set emulate off` which may also speed up debugging",
"Use the `canary` command to see all stack canary/cookie values on the stack (based on the *usual* stack canary value initialized by glibc)",
"Use the `canary` command to see all stack canary/cookie values on the stack (based on the *usual* stack canary value initialized by glibc)",
"Use the `procinfo` command for better process introspection (than the GDB's `info proc` command)",
"Use the `procinfo` command for better process introspection (than the GDB's `info proc` command)",
"Want to display each context panel in a separate tmux window? See https://pwndbg.re/pwndbg/latest/tutorials/splitting-the-context/",
"Want to display each context panel in a separate tmux window? See https://pwndbg.re/latest/tutorials/splitting-the-context/",
'Use `$base("heap")` to get the start address of a [heap] memory page',
'Use `$base("heap")` to get the start address of a [heap] memory page',
"Use the `errno` (or `errno <number>`) command to see the name of the last or provided (libc) error",
"Use the `errno` (or `errno <number>`) command to see the name of the last or provided (libc) error",
"Pwndbg sets the SIGLARM, SIGBUS, SIGPIPE and SIGSEGV signals so they are not passed to the app; see `info signals` for full GDB signals configuration",
"Pwndbg sets the SIGLARM, SIGBUS, SIGPIPE and SIGSEGV signals so they are not passed to the app; see `info signals` for full GDB signals configuration",
k4lizen
1 month ago
committed by
GitHub