From db03238abbeb36fc4b6da32f14dd267481b8af5f Mon Sep 17 00:00:00 2001 From: k4lizen <124312252+k4lizen@users.noreply.github.com> Date: Sun, 26 Oct 2025 16:42:25 +0100 Subject: [PATCH] update links (#3373) --- README.md | 10 +- .../developer/dev-dump-instruction.md | 2 +- docs/contributing/adding-a-command.md | 6 +- docs/contributing/adding-a-parameter.md | 4 +- docs/contributing/making-a-gif.md | 2 +- mkdocs.yml | 133 +++++++++--------- pwndbg/aglib/__init__.py | 2 +- pwndbg/commands/dev.py | 2 +- pwndbg/lib/tips.py | 2 +- setup-dev.sh | 2 +- setup.sh | 2 +- 11 files changed, 83 insertions(+), 84 deletions(-) diff --git a/README.md b/README.md index 06a80dc86..7a97b7b08 100644 --- a/README.md +++ b/README.md @@ -10,11 +10,11 @@ with a focus on features needed by low-level software developers, hardware hackers, reverse-engineers and exploit developers. -It has a boatload of features, see our [Features page](https://pwndbg.re/pwndbg/latest/features/) +It has a boatload of features, see our [Features page](https://pwndbg.re/latest/features/) and [CHEATSHEET][CHEATSHEET] (feel free to print it!). If you have any questions you may read the -[documentation](https://pwndbg.re/pwndbg/latest/) or asks us in our [Discord server](https://discord.gg/x47DssnGwm). +[documentation](https://pwndbg.re/latest/) or asks us in our [Discord server](https://discord.gg/x47DssnGwm). -[CHEATSHEET]: https://pwndbg.re/pwndbg/dev/CHEATSHEET.pdf +[CHEATSHEET]: https://pwndbg.re/dev/CHEATSHEET.pdf ## Why? @@ -30,7 +30,7 @@ smoothing out rough edges and making them more user-friendly. ## Installation -See [installation instructions](https://pwndbg.re/pwndbg/latest/setup). +See [installation instructions](https://pwndbg.re/latest/setup). ## What about ...? @@ -80,7 +80,7 @@ Pwndbg ensures a consistent experience across both, so switching between them is ## 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 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. diff --git a/docs/commands/developer/dev-dump-instruction.md b/docs/commands/developer/dev-dump-instruction.md index f48d2cee5..b8874e35a 100644 --- a/docs/commands/developer/dev-dump-instruction.md +++ b/docs/commands/developer/dev-dump-instruction.md @@ -9,7 +9,7 @@ usage: dev-dump-instruction [-h] [-e] [-n] [address] Dump internal PwndbgInstruction attributes. Useful for debugging the disassembly and annotation subsystems -in Pwndbg. See https://pwndbg.re/pwndbg/dev/contributing/improving-annotations/#bug-root-cause +in Pwndbg. See https://pwndbg.re/dev/contributing/improving-annotations/#bug-root-cause for more information. ### Positional arguments diff --git a/docs/contributing/adding-a-command.md b/docs/contributing/adding-a-command.md index 195ad0230..e633c223c 100644 --- a/docs/contributing/adding-a-command.md +++ b/docs/contributing/adding-a-command.md @@ -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. -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 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]`). ## 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 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: # .... ``` -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. ## Can your command be invoked all the time? diff --git a/docs/contributing/adding-a-parameter.md b/docs/contributing/adding-a-parameter.md index 53a306b1f..5b3ac1fad 100644 --- a/docs/contributing/adding-a-parameter.md +++ b/docs/contributing/adding-a-parameter.md @@ -93,7 +93,7 @@ Valid values: 'disabled', 'disabled-deadlock', 'enabled' ``` 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 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 @@ -134,7 +134,7 @@ class Scope(Enum): theme = 2 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 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: ```python diff --git a/docs/contributing/making-a-gif.md b/docs/contributing/making-a-gif.md index 6fdaa9f93..e353c12c7 100644 --- a/docs/contributing/making-a-gif.md +++ b/docs/contributing/making-a-gif.md @@ -14,7 +14,7 @@ vhs record > my_thingy.tape 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 - 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/ : ```bash # https://github.com/charmbracelet/vhs diff --git a/mkdocs.yml b/mkdocs.yml index 8e0779411..78f5a37d0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,7 +1,7 @@ # Make LSPs validate the mkdocs format # yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json -site_url: https://pwndbg.re/pwndbg/ +site_url: https://pwndbg.re/ site_name: Documentation site_description: >- 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. @@ -21,12 +21,12 @@ theme: text: Roboto code: Roboto Mono features: -# https://squidfunk.github.io/mkdocs-material/reference/code-blocks/ + # https://squidfunk.github.io/mkdocs-material/reference/code-blocks/ # A button to copy code snippets. # - content.code.copy # Enable annotations in code blocks. - content.code.annotate -# https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/ + # https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/ # Use XHR instead of fully reloading the page when navigating around. - navigation.instant # Progress bar on page load for slow connections (>400ms). @@ -47,17 +47,17 @@ theme: # - toc.integrate # A button that takes the user to the top of the page. - navigation.top -# https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/ + # https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/ # Press right arrow to accept search suggestion. - search.suggest # Highlight the search query on the chosen page. # - search.highlight # Add a "share" button to copy a link to the search query. - search.share -# https://squidfunk.github.io/mkdocs-material/setup/adding-a-git-repository/#code-actions + # https://squidfunk.github.io/mkdocs-material/setup/adding-a-git-repository/#code-actions # Adds an edit button to every page that links to the repository. # - content.action.edit -# Extra + # Extra # Sync the content tab selection across the whole site (based on label). - content.tabs.link palette: @@ -77,63 +77,63 @@ plugins: default_handler: python handlers: python: -# https://mkdocstrings.github.io/python/usage/ + # https://mkdocstrings.github.io/python/usage/ load_external_modules: false - paths: ['pwndbg'] + paths: ["pwndbg"] options: -# https://mkdocstrings.github.io/python/usage/configuration/general/ - # Allow importing modules to improve doc generation. - # We have to disable this since many modules can't be imported easily - # as they require gdb/lldb to be running. - allow_inspection: false - backlinks: tree - show_source: false - # Show the base classes of a class. - show_bases: true - extensions: -# https://mkdocstrings.github.io/griffe/extensions/ + # https://mkdocstrings.github.io/python/usage/configuration/general/ + # Allow importing modules to improve doc generation. + # We have to disable this since many modules can't be imported easily + # as they require gdb/lldb to be running. + allow_inspection: false + backlinks: tree + show_source: false + # Show the base classes of a class. + show_bases: true + extensions: + # https://mkdocstrings.github.io/griffe/extensions/ # E.g. converts union types from Union[A, B] to A | B. - - griffe_modernized_annotations -# https://mkdocstrings.github.io/python/usage/configuration/headings/ - heading_level: 1 - parameter_headings: false - show_root_heading: true - show_root_toc_entry: true - show_root_full_path: false - show_symbol_type_heading: true - show_symbol_type_toc: true -# https://mkdocstrings.github.io/python/usage/configuration/members - inherited_members: true - members_order: source - # WARN: Enabling this gives very flaky, hard-to-diagnose errors! Don't. - # filters: public - group_by_category: true - summary: true -# https://mkdocstrings.github.io/python/usage/configuration/docstrings/ - docstring_style: google - docstring_section_style: list - merge_init_into_class: true - relative_crossrefs: true - scoped_crossrefs: true - show_if_no_docstring: true - # All show_docstring_* options are enabled by default. -# https://mkdocstrings.github.io/python/usage/configuration/signatures/ - line_length: 80 - modernize_annotations: true - show_signature: true - separate_signature: true - show_signature_annotations: true - show_overloads: true - signature_crossrefs: true - docstring_options: -# https://mkdocstrings.github.io/griffe/reference/docstrings/#google-options - ignore_init_summary: true - trim_doctest_flags: true - warn_unknown_params: true + - griffe_modernized_annotations + # https://mkdocstrings.github.io/python/usage/configuration/headings/ + heading_level: 1 + parameter_headings: false + show_root_heading: true + show_root_toc_entry: true + show_root_full_path: false + show_symbol_type_heading: true + show_symbol_type_toc: true + # https://mkdocstrings.github.io/python/usage/configuration/members + inherited_members: true + members_order: source + # WARN: Enabling this gives very flaky, hard-to-diagnose errors! Don't. + # filters: public + group_by_category: true + summary: true + # https://mkdocstrings.github.io/python/usage/configuration/docstrings/ + docstring_style: google + docstring_section_style: list + merge_init_into_class: true + relative_crossrefs: true + scoped_crossrefs: true + show_if_no_docstring: true + # All show_docstring_* options are enabled by default. + # https://mkdocstrings.github.io/python/usage/configuration/signatures/ + line_length: 80 + modernize_annotations: true + show_signature: true + separate_signature: true + show_signature_annotations: true + show_overloads: true + signature_crossrefs: true + docstring_options: + # https://mkdocstrings.github.io/griffe/reference/docstrings/#google-options + ignore_init_summary: true + trim_doctest_flags: true + warn_unknown_params: true # Generate the whole Source page magically (hooks into mkdocstrings) - api-autonav: - modules: ['pwndbg'] + modules: ["pwndbg"] nav_section_title: "Source" # Documentation versioning @@ -146,11 +146,11 @@ plugins: - awesome-nav: - rss: -# https://squidfunk.github.io/mkdocs-material/tutorials/blogs/engage/#rss-feeds -# https://guts.github.io/mkdocs-rss-plugin/configuration/#plugin-options + # https://squidfunk.github.io/mkdocs-material/tutorials/blogs/engage/#rss-feeds + # https://guts.github.io/mkdocs-rss-plugin/configuration/#plugin-options feed_title: "pwndbg Blog" # Image doesn't support relative paths :(. - image: https://pwndbg.re/pwndbg/assets/favicon.ico + image: https://pwndbg.re/assets/favicon.ico match_path: blog/posts/.* date_from_meta: as_creation: date @@ -160,7 +160,7 @@ plugins: # Theme specific template values. extra: -# https://squidfunk.github.io/mkdocs-material/setup/setting-up-the-footer/ + # https://squidfunk.github.io/mkdocs-material/setup/setting-up-the-footer/ # The icons in the footer. social: - icon: fontawesome/brands/github @@ -183,7 +183,7 @@ extra_javascript: - js/prompt-highlighter.js markdown_extensions: -# https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/ + # https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/ - abbr - admonition - attr_list @@ -194,9 +194,9 @@ markdown_extensions: permalink: "¤" toc_depth: 3 - tables -# https://facelessuser.github.io/pymdown-extensions/ -# Officially supported are: -# https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/ + # https://facelessuser.github.io/pymdown-extensions/ + # Officially supported are: + # https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/ # Not enabled from the list^ : arithmatex, critic - pymdownx.betterem: smart_enable: all @@ -231,7 +231,7 @@ markdown_extensions: slugify: !!python/object/apply:pymdownx.slugs.slugify kwds: case: lower -# Not officially supported: + # Not officially supported: - pymdownx.magiclink: repo_url_shortener: true repo_url_shorthand: true @@ -239,6 +239,5 @@ markdown_extensions: user: pwndbg repo: pwndbg - pymdownx.tasklist - # We intentionally do not include `nav:` so that it gets autogenerated using # the folder structure. See also docs/.nav.yml diff --git a/pwndbg/aglib/__init__.py b/pwndbg/aglib/__init__.py index 74d2f57b9..5a5fbc02f 100644 --- a/pwndbg/aglib/__init__.py +++ b/pwndbg/aglib/__init__.py @@ -5,7 +5,7 @@ Takes the debugging primitives provided by the Debugger API and builds the more complex and interesting bits of functionality found in Pwndbg on top of them. -See https://pwndbg.re/pwndbg/dev/contributing/dev-notes/#aglib +See https://pwndbg.re/dev/contributing/dev-notes/#aglib for more information. """ diff --git a/pwndbg/commands/dev.py b/pwndbg/commands/dev.py index f559ae269..26784561e 100644 --- a/pwndbg/commands/dev.py +++ b/pwndbg/commands/dev.py @@ -13,7 +13,7 @@ parser = argparse.ArgumentParser( Dump internal PwndbgInstruction attributes. Useful for debugging the disassembly and annotation subsystems -in Pwndbg. See https://pwndbg.re/pwndbg/dev/contributing/improving-annotations/#bug-root-cause +in Pwndbg. See https://pwndbg.re/dev/contributing/improving-annotations/#bug-root-cause for more information. """ ) diff --git a/pwndbg/lib/tips.py b/pwndbg/lib/tips.py index 2de6aa96e..7d005ae42 100644 --- a/pwndbg/lib/tips.py +++ b/pwndbg/lib/tips.py @@ -34,7 +34,7 @@ PWNDBG_TIPS: List[str] = [ "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 `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 the `errno` (or `errno `) 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", diff --git a/setup-dev.sh b/setup-dev.sh index 4079e9c84..8bf113246 100755 --- a/setup-dev.sh +++ b/setup-dev.sh @@ -245,7 +245,7 @@ configure_venv() { if osx; then echo "Not supported on macOS. Please use one of the alternative methods listed at:" - echo "https://pwndbg.re/pwndbg/dev/contributing/setup-pwndbg-dev/" + echo "https://pwndbg.re/dev/contributing/setup-pwndbg-dev/" exit 1 fi diff --git a/setup.sh b/setup.sh index aa6831a08..2baf0d28d 100755 --- a/setup.sh +++ b/setup.sh @@ -122,7 +122,7 @@ PYTHON='' if osx; then echo "Not supported on macOS. Please use one of the alternative methods listed at:" - echo "https://pwndbg.re/pwndbg/dev/contributing/setup-pwndbg-dev/" + echo "https://pwndbg.re/dev/contributing/setup-pwndbg-dev/" exit 1 fi