Adding a Configuration Option¤
Configuration options are also called "parameters" in the source. Let's take a look at an existing parameter gdb-workaround-stop-event
defined in pwndbg/gdblib/events.py
.
DISABLED = "disabled"
DISABLED_DEADLOCK = "disabled-deadlock"
ENABLED = "enabled"
gdb_workaround_stop_event = config.add_param(
"gdb-workaround-stop-event",
DISABLED,
"asynchronous stop events to improve 'commands' functionality",
help_docstring=f"""
Note that this may cause unexpected behavior with Pwndbg or gdb.execute.
Values explained:
+ `{DISABLED}` - Disable the workaround (default).
+ `{DISABLED_DEADLOCK}` - Disable only deadlock detection; deadlocks may still occur.
+ `{ENABLED}` - Enable asynchronous stop events; gdb.execute may behave unexpectedly (asynchronously).
""",
param_class=pwndbg.lib.config.PARAM_ENUM,
enum_sequence=[DISABLED, DISABLED_DEADLOCK, ENABLED],
)
Config.add_param
function defined in pwndbg/lib/config.py
: def add_param(
self,
name: str,
default: Any,
set_show_doc: str,
*,
help_docstring: str = "",
param_class: int | None = None,
enum_sequence: Sequence[str] | None = None,
scope: Scope = Scope.config,
) -> Parameter:
# ...
set_show_doc¤
The third argument is a very brief description of what the parameter is for. The argument is called set_show_doc
due to how it is used in GDB.
pwndbg> set gdb-workaround-stop-event enabled
Set asynchronous stop events to improve 'commands' functionality to 'enabled'.
|------------------------------------------------------------|
pwndbg> show gdb-workaround-stop-event
Asynchronous stop events to improve 'commands' functionality is 'enabled'. [...]
|-----------------------------------------------------------|
The set_show_doc
argument should be short because it is displayed with the config
family of commands.
pwndbg> config
Name Documentation Value (Default)
----------------------------------------------------------------------------------------------------------------------------
ai-anthropic-api-key Anthropic API key ''
ai-history-size maximum number of questions and answers to keep in the prompt 3
ai-max-tokens the maximum number of tokens to return in the response 100
ai-model the name of the large language model to query 'gpt-3.5-turbo'
ai-ollama-endpoint Ollama API endpoint ''
ai-openai-api-key OpenAI API key ''
ai-show-usage whether to show how many tokens are used with each OpenAI API call off
ai-stack-depth rows of stack context to include in the prompt for the ai command 16
ai-temperature the temperature specification for the LLM query 0
attachp-resolution-method how to determine the process to attach when multiple candidates exists 'ask'
auto-explore-auxv stack exploration for AUXV information; it may be really slow 'warn'
auto-explore-pages whether to try to infer page permissions when memory maps are missing 'warn'
auto-explore-stack stack exploration; it may be really slow 'warn'
auto-save-search automatically pass --save to "search" command off
bn-autosync whether to automatically run bn-sync every step off
[...]
set_show_doc
string should be lowercase (unless the first word is a name or an abbreviation) and there should be no punctuation at the end. This way, Pwndbg and GDB can more easily modify the string to fit it into these contexts. help_docstring¤
While help_docstring
is not mandatory, it is highly recommended to use it. Put a detailed explanation of what the parameter does here, and explain any caveats. This string does not have a size limit and is shown with the following command in GDB and LLDB:
pwndbg> help set gdb-workaround-stop-event
Set asynchronous stop events to improve 'commands' functionality.
Note that this may cause unexpected behavior with Pwndbg or gdb.execute.
Values explained:
+ `disabled` - Disable the workaround (default).
+ `disabled-deadlock` - Disable only deadlock detection; deadlocks may still occur.
+ `enabled` - Enable asynchronous stop events; gdb.execute may behave unexpectedly (asynchronously).
Default: 'disabled'
Valid values: 'disabled', 'disabled-deadlock', 'enabled'
When writing this explanation, it is important to take into account how it will be displayed in the documentation 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.
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:
# Boolean value. True or False, same as in Python.
PARAM_BOOLEAN = 0
# Boolean value, or 'auto'.
PARAM_AUTO_BOOLEAN = 1
# Signed integer value. Disallows zero.
PARAM_INTEGER = 2
# Signed integer value.
PARAM_ZINTEGER = 3
# Unsigned integer value. Disallows zero.
PARAM_UINTEGER = 4
# Unsigned integer value.
PARAM_ZUINTEGER = 5
# Unlimited ZUINTEGER.
PARAM_ZUINTEGER_UNLIMITED = 6
# String value. Accepts escape sequences.
PARAM_STRING = 7
# String value, accepts only one of a number of possible values, specified at
# parameter creation.
PARAM_ENUM = 8
# String value corresponding to the name of a file, if present.
PARAM_OPTIONAL_FILENAME = 9
None
or "unlimited"
mean) see https://sourceware.org/gdb/current/onlinedocs/gdb.html/Parameters-In-Python.html . enum_sequence¤
If the param_class
is set to pwndbg.lib.config.PARAM_ENUM
then the enum_sequence
argument must be supplied as well. It should constitute an array of legal values. GDB and (our) LLDB (driver) won't allow setting the parameter to any other value. The legal values will be automatically displayed at the end of help_docstring
as previously shown.
If it isn't immediately obvious what the enum values do, explain them in help_docstring
using same format that gdb-workaround-stop-event
uses.
scope¤
The scope
argument has the default value of pwndbg.lib.config.Scope.config
and is used to group parameters. The legal values are:
class Scope(Enum):
# If you want to add another scope here, don't forget to add
# a command which prints it!
config = 1
theme = 2
heap = 3
config
scope is printed with config
, the heap
scope is printed with heap-config
and the theme
scope is printed with theme
. The config
and theme
scopes also have corresponding configfile
and themefile
commands which export the values of all the parameters from those scopes. 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:
# pwndbg/aglib/nearpc.py
nearpc_branch_marker = pwndbg.color.theme.add_param(
"nearpc-branch-marker", " ↓", "branch marker line for nearpc command"
)
# pwndbg/color/context.py
config_highlight_color = theme.add_color_param(
"highlight-color", "green,bold", "color added to highlights like source/pc"
)
Using the parameter in code¤
Usually when a parameter is defined its value is also set to a variable, for instance gdb_workaround_stop_event = ...
in the initial example. This isn't necessary, as all registered parameters are available as pwndbg.config.<parameter_name_except_with_underscores>
so in our example, we could also access the gdb-workaround-stop-event
parameter as pwndbg.config.gdb_workaround_stop_event
.
That being said, defining the variable can reduce code verbosity:
# pwndbg/aglib/godbg.py
line_width = pwndbg.config.add_param(
"go-dump-line-width", 80, "the soft line width for go-dump pretty printing"
)
godbg.py
file, its name can be short, and we don't have to write pwndbg.config.go_dump_line_width
every time. Using color parameters¤
Note that the theme.add_color_param()
function returns a ColorParameter
object instead of a Parameter
. The parameter should be used via its color_function()
method:
# pwndbg/aglib/godbg.py
def fmt_debug(self, val: str, default: str = "") -> str:
if self.debug:
return debug_color.color_function(val)
else:
return default
generateColorFunction(debug_color)(val)
being used in the code to the same effect.