From 7fd94ab532b6edbb58a3f30f04b7f2a891db0873 Mon Sep 17 00:00:00 2001 From: Grazfather Date: Tue, 18 Jul 2023 14:02:08 -0400 Subject: [PATCH] Wrap docs (#962) * Wrap docs to 100 columns * Add editorconfig for markdown --- .editorconfig | 3 + docs/api.md | 93 ++++++++++-------- docs/commands/aliases.md | 26 +++-- docs/commands/aslr.md | 6 +- docs/commands/canary.md | 7 +- docs/commands/checksec.md | 5 +- docs/commands/config.md | 21 ++-- docs/commands/context.md | 98 +++++++++---------- docs/commands/dereference.md | 31 +++--- docs/commands/edit-flags.md | 15 ++- docs/commands/elf-info.md | 7 +- docs/commands/entry-break.md | 16 ++- docs/commands/eval.md | 4 +- docs/commands/format-string-helper.md | 9 +- docs/commands/functions.md | 25 ++--- docs/commands/gef-remote.md | 45 ++++++--- docs/commands/gef.md | 49 +++++----- docs/commands/got.md | 7 +- docs/commands/heap-analysis-helper.md | 49 ++++------ docs/commands/heap.md | 116 ++++++++++------------ docs/commands/hexdump.md | 11 +-- docs/commands/highlight.md | 9 +- docs/commands/hijack-fd.md | 3 +- docs/commands/ksymaddr.md | 6 +- docs/commands/memory.md | 19 ++-- docs/commands/name-break.md | 14 ++- docs/commands/nop.md | 7 +- docs/commands/pattern.md | 30 +++--- docs/commands/pcustom.md | 54 +++++++---- docs/commands/pie.md | 45 ++++----- docs/commands/print-format.md | 17 ++-- docs/commands/process-search.md | 20 ++-- docs/commands/process-status.md | 6 +- docs/commands/registers.md | 7 +- docs/commands/scan.md | 16 ++- docs/commands/search-pattern.md | 26 +++-- docs/commands/shellcode.md | 6 +- docs/commands/stub.md | 21 ++-- docs/commands/theme.md | 26 ++--- docs/commands/tmux-setup.md | 27 +++--- docs/commands/trace-run.md | 13 ++- docs/commands/version.md | 7 +- docs/commands/vmmap.md | 13 ++- docs/commands/xfiles.md | 6 +- docs/commands/xinfo.md | 15 ++- docs/commands/xor-memory.md | 3 +- docs/config.md | 21 ++-- docs/deprecated.md | 5 +- docs/faq.md | 134 +++++++++++++++----------- docs/functions/base.md | 4 +- docs/functions/bss.md | 1 - docs/functions/got.md | 1 - docs/functions/heap.md | 1 - docs/functions/stack.md | 2 - docs/index.md | 68 ++++++++----- docs/install.md | 60 ++++++++---- docs/screenshots.md | 21 ++-- docs/testing.md | 30 +++--- 58 files changed, 725 insertions(+), 682 deletions(-) diff --git a/.editorconfig b/.editorconfig index 30d459c4d..afce7e399 100644 --- a/.editorconfig +++ b/.editorconfig @@ -19,3 +19,6 @@ indent_style = tab [*.yml] indent_style = space indent_size = 2 + +[*.md] +max_line_length=100 diff --git a/docs/api.md b/docs/api.md index 8a5f83bd0..3b23b4500 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,16 +1,15 @@ # Extending GEF -`GEF` intends to provide a battery-included, quickly installable and crazy fast -debugging environment sitting on top of GDB. +`GEF` intends to provide a battery-included, quickly installable and crazy fast debugging +environment sitting on top of GDB. -But it most importantly provides all the primitives required to allow hackers to -quickly create their own commands. This page intends to summarize how to -create advanced GDB commands in moments using `GEF` as a library. +But it most importantly provides all the primitives required to allow hackers to quickly create +their own commands. This page intends to summarize how to create advanced GDB commands in moments +using `GEF` as a library. -A [dedicated repository](https://github.com/hugsy/gef-extras) was born to host -[external scripts](https://github.com/hugsy/gef-extras/tree/main/scripts). This -repo is open to all for contributions, no restrictions and the most valuable -ones will be integrated into `gef.py`. +A [dedicated repository](https://github.com/hugsy/gef-extras) was born to host [external +scripts](https://github.com/hugsy/gef-extras/tree/main/scripts). This repo is open to all for +contributions, no restrictions and the most valuable ones will be integrated into `gef.py`. ## Quick start @@ -51,17 +50,15 @@ Yes, that's it! Check out [the complete API](api/gef.md) to see what else GEF of ## Detailed explanation -Our new command must be a class that inherits from GEF's `GenericCommand`. The -*only* requirements are: +Our new command must be a class that inherits from GEF's `GenericCommand`. The *only* requirements are: - * a `_cmdline_` attribute (the command to type on the GDB prompt). - * a `_syntax_` attribute, which GEF will use to auto-generate the help menu. - * a method `do_invoke(self, args)` which will be executed when the command - is invoked. `args` is a list of the command line args provided when invoked. +* a `_cmdline_` attribute (the command to type on the GDB prompt). +* a `_syntax_` attribute, which GEF will use to auto-generate the help menu. +* a method `do_invoke(self, args)` which will be executed when the command is invoked. `args` is a + list of the command line args provided when invoked. -We make GEF aware of this new command by registering it in the `__main__` -section of the script, by invoking the global function -`register_external_command()`. +We make GEF aware of this new command by registering it in the `__main__` section of the script, by +invoking the global function `register_external_command()`. Now you have a new GEF command which you can load, either from cli: ```bash @@ -75,9 +72,8 @@ $ echo source /path/to/newcmd.py >> ~/.gdbinit ## Customizing context panes -Sometimes you want something similar to a command to run on each break-like -event and display itself as a part of the GEF context. Here is a simple example -of how to make a custom context pane: +Sometimes you want something similar to a command to run on each break-like event and display itself +as a part of the GEF context. Here is a simple example of how to make a custom context pane: ```python __start_time__ = int(time.time()) @@ -96,26 +92,25 @@ Loading it in `GEF` is as easy as loading a command gef➤ source /path/to/custom_context_pane.py ``` -It can even be included in the same file as a Command. -Now on each break you will notice a new pane near the bottom of the context. -The order can be modified in the `GEF` context config. +It can even be included in the same file as a Command. Now on each break you will notice a new pane +near the bottom of the context. The order can be modified in the `GEF` context config. ### Context Pane API The API demonstrated above requires very specific argument types: `register_external_context_pane(pane_name, display_pane_function, pane_title_function)` --`pane_name`: a string that will be used as the panes setting name --`display_pane_function`: a function that uses `gef_print()` to print content -in the pane --`pane_title_function`: a function that returns the title string or None to hide the title +* `pane_name`: a string that will be used as the panes setting name +* `display_pane_function`: a function that uses `gef_print()` to print content in the pane +* `pane_title_function`: a function that returns the title string or None to hide the title ## API -Some of the most important parts of the API for creating new commands are -mentioned (but not limited to) below. To see the full help of a function, open -GDB and GEF, and use the embedded Python interpreter's `help` command. For -example: +Some of the most important parts of the API for creating new commands are mentioned (but not limited +to) below. To see the full help of a function, open GDB and GEF, and use the embedded Python +interpreter's `help` command. + +For example: ```bash gef➤ pi help(Architecture) @@ -130,14 +125,14 @@ $ gdb -q -ex 'pi help(hexdump)' -ex quit The GEF API aims to provide a simpler and more Pythonic approach to GDB's. Some basic examples: - - read the memory +- read the memory ```python gef ➤ pi print(hexdump( gef.memory.read(parse_address("$pc"), length=0x20 ))) 0x0000000000000000 f3 0f 1e fa 31 ed 49 89 d1 5e 48 89 e2 48 83 e4 ....1.I..^H..H.. 0x0000000000000010 f0 50 54 4c 8d 05 66 0d 01 00 48 8d 0d ef 0c 01 .PTL..f...H..... ``` - - get access to the memory layout +- get access to the memory layout ``` gef ➤ pi print('\n'.join([ f"{x.page_start:#x} -> {x.page_end:#x}" for x in gef.memory.maps])) 0x555555554000 -> 0x555555558000 @@ -155,9 +150,9 @@ gef ➤ pi print('\n'.join([ f"{x.page_start:#x} -> {x.page_end:#x}" for x in ge The API also offers a number of decorators to simplify the creation of new/existing commands, such as: - - `@only_if_gdb_running` to execute only if a GDB session is running. - - `@only_if_gdb_target_local` to check if the target is local i.e. not debugging using GDB `remote`. - - and many more... +- `@only_if_gdb_running` to execute only if a GDB session is running. +- `@only_if_gdb_target_local` to check if the target is local i.e. not debugging using GDB `remote`. +- and many more... ### Reference @@ -171,9 +166,18 @@ For a complete reference of the API offered by GEF, visit [`docs/api/gef.md`](ap @parse_arguments( {"required_argument_1": DefaultValue1, ...}, {"--optional-argument-1": DefaultValue1, ...} ) ``` -This decorator aims to facilitate the argument passing to a command. If added, it will use the `argparse` module to parse arguments, and will store them in the `kwargs["arguments"]` of the calling function (therefore the function **must** have `*args, **kwargs` added to its signature). Argument type is inferred directly from the default value **except** for boolean, where a value of `True` corresponds to `argparse`'s `store_true` action. For more details on `argparse`, refer to its Python documentation. +This decorator aims to facilitate the argument passing to a command. If added, it will use the +`argparse` module to parse arguments, and will store them in the `kwargs["arguments"]` of the +calling function (therefore the function **must** have `*args, **kwargs` added to its signature). +Argument type is inferred directly from the default value **except** for boolean, where a value of +`True` corresponds to `argparse`'s `store_true` action. For more details on `argparse`, refer to its +Python documentation. -Values given for the parameters also allow list of arguments being past. This can be useful in the case where the number of exact option values is known in advance. This can be achieved simply by using a type of `tuple` or `list` for the default value. `parse_arguments` will determine the type of what to expect based on the first default value of the iterable, so make sure it's not empty. For instance: +Values given for the parameters also allow list of arguments being past. This can be useful in the +case where the number of exact option values is known in advance. This can be achieved simply by +using a type of `tuple` or `list` for the default value. `parse_arguments` will determine the type +of what to expect based on the first default value of the iterable, so make sure it's not empty. For +instance: ```python @@ -216,16 +220,21 @@ args.blah --> True # set to True because user input declared the option (would h ### Adding new architectures -Support for new architectures can be added by inheriting from the `Architecture` class. To register the new architecture with gef, the decorator `@register_architecture` has to be added to the class. Examples can be found in [gef-extras](https://github.com/hugsy/gef-extras/tree/dev/archs). +Support for new architectures can be added by inheriting from the `Architecture` class. Examples can +be found in [gef-extras](https://github.com/hugsy/gef-extras/tree/dev/archs). -Sometimes architectures can more precisely determine whether they apply to the current target by looking at the architecture determined by gdb. For these cases the custom architecture may implement the `supports_gdb_arch()` static function to signal that they should be used instead of the default. The function receives only one argument: +Sometimes architectures can more precisely determine whether they apply to the current target by +looking at the architecture determined by gdb. For these cases the custom architecture may implement +the `supports_gdb_arch()` static function to signal that they should be used instead of the default. +The function receives only one argument: - `gdb_str` (of type `str`) which is the architecture name as reported by GDB. The function **must** return: - `True` if the current `Architecture` class supports the target binary; `False` otherwise. - `None` to simply ignore this check and let GEF try to determine the architecture. -One example is the ARM Cortex-M architecture which in some cases should rather be used than the generic ARM one: +One example is the ARM Cortex-M architecture which in some cases should be used over the generic ARM +one: ```python @staticmethod diff --git a/docs/commands/aliases.md b/docs/commands/aliases.md index 8afac4e84..8cbe0002b 100644 --- a/docs/commands/aliases.md +++ b/docs/commands/aliases.md @@ -9,9 +9,9 @@ aliases (add|rm|list) ### Adding/Removing Aliases -`GEF` defines its own aliasing mechanism which overrides the traditional -alias that GDB provides through the built-in command `alias`. To add a new alias, -simply use the `aliases add` command. The "command" parameter may contain spaces. +`GEF` defines its own aliasing mechanism which overrides the traditional alias that GDB provides +through the built-in command `alias`. To add a new alias, simply use the `aliases add` command. The +"command" parameter may contain spaces. ``` aliases add [alias] [command] @@ -25,8 +25,8 @@ aliases rm [alias] ### Listing Aliases -One can list aliases by using the `aliases ls` command. Some sample output of this -command is seen below. +One can list aliases by using the `aliases ls` command. Some sample output of this command is seen +below. ``` [+] Aliases defined: @@ -46,9 +46,8 @@ ps → process-search ### Using the Configuration File -Users can also create/modify/delete aliases by editing the `GEF` configuration file, -by default located at `~/.gef.rc`. The aliases must be in the `aliases` section -of the configuration file. +Users can also create/modify/delete aliases by editing the `GEF` configuration file, by default +located at `~/.gef.rc`. The aliases must be in the `aliases` section of the configuration file. Creating a new alias is as simple as creating a new entry in this section: @@ -61,8 +60,8 @@ my-new-alias = gdb-or-gef-command #### Bringing some PEDA and WinDBG flavours into GEF -For example, for those (like me) who use WinDBG and like its bindings, they can -be integrated into GDB via GEF aliases like this: +For example, for those (like me) who use WinDBG and like its bindings, they can be integrated into +GDB via GEF aliases like this: ``` $ nano ~/.gef.rc @@ -90,8 +89,7 @@ g = gef run uf = disassemble ``` -Or here are some `PEDA` aliases for people used to using `PEDA` who made the -smart move to `GEF`. +Or here are some `PEDA` aliases for people used to using `PEDA` who made the smart move to `GEF`. ``` # some peda aliases @@ -103,8 +101,8 @@ kp = info stack findmem = search-pattern ``` -The aliases will be loaded next time you load GDB (and `GEF`). Or you can force -`GEF` to reload the settings with the command: +The aliases will be loaded next time you load GDB (and `GEF`). Or you can force `GEF` to reload the +settings with the command: ``` gef➤ gef restore diff --git a/docs/commands/aslr.md b/docs/commands/aslr.md index 39a8ac7ed..54e4c9e5c 100644 --- a/docs/commands/aslr.md +++ b/docs/commands/aslr.md @@ -22,6 +22,6 @@ gef➤ aslr off [+] Disabling ASLR ``` -**Note**: This command cannot affect a process that has already been loaded, to -which GDB attached to later. The only way to disable this randomization is by -setting the kernel setting `/proc/sys/kernel/randomize_va_space` to 0.. +**Note**: This command cannot affect a process that has already been loaded, to which GDB attached +to later. The only way to disable this randomization is by setting the kernel setting +`/proc/sys/kernel/randomize_va_space` to 0.. diff --git a/docs/commands/canary.md b/docs/commands/canary.md index abb33ec08..9bbbd2755 100644 --- a/docs/commands/canary.md +++ b/docs/commands/canary.md @@ -1,9 +1,8 @@ ## Command `canary` -If the currently debugged process was compiled with the Smash Stack Protector -(SSP) - i.e. the `-fstack-protector` flag was passed to the compiler, this -command will display the value of the canary. This makes it convenient to avoid -manually searching for this value in memory. +If the currently debugged process was compiled with the Smash Stack Protector (SSP) - i.e. the +`-fstack-protector` flag was passed to the compiler, this command will display the value of the +canary. This makes it convenient to avoid manually searching for this value in memory. The command `canary` does not take any arguments. ``` diff --git a/docs/commands/checksec.md b/docs/commands/checksec.md index 4a7938e9f..a1aa97a9c 100644 --- a/docs/commands/checksec.md +++ b/docs/commands/checksec.md @@ -1,8 +1,7 @@ ## Command `checksec` ## -The `checksec` command is inspired from -[`checksec.sh`](https://www.trapkit.de/tools/checksec.html). It provides a -convenient way to determine which security protections are enabled in a binary. +The `checksec` command is inspired from [`checksec.sh`](https://www.trapkit.de/tools/checksec.html). +It provides a convenient way to determine which security protections are enabled in a binary. You can use the command on the currently debugged process: ``` diff --git a/docs/commands/config.md b/docs/commands/config.md index 3e94f5996..b10cf8670 100644 --- a/docs/commands/config.md +++ b/docs/commands/config.md @@ -1,8 +1,8 @@ ## Command `gef config` ## -`gef` reads its config from a file which is by default located at `~/.gef.rc`, but which -can also be specified via the `GEF_RC` environment variable. In addition, `gef` can also -be configured at runtime with the `gef config` command. +`gef` reads its config from a file which is by default located at `~/.gef.rc`, but which can also be +specified via the `GEF_RC` environment variable. In addition, `gef` can also be configured at +runtime with the `gef config` command. To view all settings for all commands loaded: ``` @@ -15,21 +15,21 @@ Or to get one setting value: gef➤ gef config pcustom.struct_path ``` -Of course you can edit the values. For example, if you want the screen to be -cleared before displaying the current context when reaching a breakpoing: +Of course you can edit the values. For example, if you want the screen to be cleared before +displaying the current context when reaching a breakpoing: ``` gef➤ gef config context.clear_screen 1 ``` -To save the current settings for `GEF` to the file system to have those options -persist across all your future `GEF` sessions, simply run: +To save the current settings for `GEF` to the file system to have those options persist across all +your future `GEF` sessions, simply run: ``` gef➤ gef save [+] Configuration saved to '/home/vagrant/.gef.rc' ``` -Upon startup, if `$GEF_RC` points to an existing file, or otherwise if -`${HOME}/.gef.rc` exists, `gef` will automatically load its values. +Upon startup, if `$GEF_RC` points to an existing file, or otherwise if `${HOME}/.gef.rc` exists, +`gef` will automatically load its values. To reload the settings during the session, just run: ``` @@ -37,5 +37,4 @@ gef➤ gef restore [+] Configuration from '/home/hugsy/.gef.rc' restored ``` -You can tweak this configuration file outside your `gdb` session to suit your -needs. +You can tweak this configuration file outside your `gdb` session to suit your needs. diff --git a/docs/commands/context.md b/docs/commands/context.md index baae9b9be..7c08eac05 100644 --- a/docs/commands/context.md +++ b/docs/commands/context.md @@ -3,38 +3,32 @@ ![gef-context](https://i.imgur.com/aZiG8Yb.png) -`gef` (not unlike `PEDA` or `fG! famous gdbinit`) provides comprehensive context -menu when hitting a breakpoint. +`gef` (not unlike `PEDA` or `fG! famous gdbinit`) provides comprehensive context menu when hitting a +breakpoint. -* The register context box displays current register values. Values in red - indicate that this register has had its value changed since the last - time execution stopped. It makes it convenient to track values. Register - values can be also accessed and/or dereferenced through the `reg` command. - -* The stack context box shows the 10 (by default but can be tweaked) entries in - memory pointed by the stack pointer register. If those values are pointers, - they are successively dereferenced. - -* The code context box shows the 10 (by default but can be tweaked) next - instructions to be executed. +* The register context box displays current register values. Values in red indicate that this + register has had its value changed since the last time execution stopped. It makes it convenient + to track values. Register values can be also accessed and/or dereferenced through the `reg` + command. +* The stack context box shows the 10 (by default but can be tweaked) entries in memory pointed by + the stack pointer register. If those values are pointers, they are successively dereferenced. +* The code context box shows the 10 (by default but can be tweaked) next instructions to be executed. ### Adding custom context panes ### -As well as using the built-in context panes, you can add your own custom pane that -will be displayed at each `break`-like event with all the other panes. Custom panes -can be added using the API: +As well as using the built-in context panes, you can add your own custom pane that will be displayed +at each `break`-like event with all the other panes. Custom panes can be added using the API: ```python register_external_context_pane(pane_name, display_pane_function, pane_title_function) ``` -Check the [API](../api.md) documentation to see a full usage of the -registration API. +Check the [API](../api.md) documentation to see a full usage of the registration API. ### Editing context layout ### -`gef` allows you to configure your own setup for the display, by re-arranging -the order with which contexts will be displayed. +`gef` allows you to configure your own setup for the display, by re-arranging the order with which +contexts will be displayed. ``` gef➤ gef config context.layout @@ -42,21 +36,20 @@ gef➤ gef config context.layout There are currently 6 sections that can be displayed: - * `legend` : a text explanation of the color code - * `regs` : the state of registers - * `stack` : the content of memory pointed by `$sp` register - * `code` : the code being executed - * `args` : if stopping at a function calls, print the call arguments - * `source` : if compiled with source, this will show the corresponding line - of source code - * `threads` : all the threads - * `trace` : the execution call trace - * `extra` : if an automatic behavior is detected (vulnerable format string, - heap vulnerability, etc.) it will be displayed in this pane - * `memory` : peek into arbitrary memory locations +* `legend` : a text explanation of the color code +* `regs` : the state of registers +* `stack` : the content of memory pointed by `$sp` register +* `code` : the code being executed +* `args` : if stopping at a function calls, print the call arguments +* `source` : if compiled with source, this will show the corresponding line of source code +* `threads` : all the threads +* `trace` : the execution call trace +* `extra` : if an automatic behavior is detected (vulnerable format string, heap vulnerability, + etc.) it will be displayed in this pane +* `memory` : peek into arbitrary memory locations -To hide a section, simply use the `context.layout` setting, and prepend the -section name with `-` or just omit it. +To hide a section, simply use the `context.layout` setting, and prepend the section name with `-` or +just omit it. ``` gef➤ gef config context.layout "-legend regs stack code args -source -threads -trace extra memory" @@ -70,32 +63,29 @@ The `memory` pane will display the content of all locations specified by the gef➤ memory watch $sp 0x40 byte ``` -will print a hexdump version of 0x40 bytes of the stack. This command makes it -convenient for tracking the evolution of arbitrary locations in memory. Tracked -locations can be removed one by one using `memory unwatch`, or altogether with -`memory reset`. +will print a hexdump version of 0x40 bytes of the stack. This command makes it convenient for +tracking the evolution of arbitrary locations in memory. Tracked locations can be removed one by one +using `memory unwatch`, or altogether with `memory reset`. The size of most sections are also customizable: * `nb_lines_stack` configures how many lines of the stack to show. * `nb_lines_backtrack` configures how many lines of the backtrace to show. -* `nb_lines_code` and `nb_lines_code_prev` configure how many lines to show - after and before the PC, respectively. -* `context.nb_lines_threads` determines the number of lines to display inside - the thread pane. This is convenient when debugging heavily multi-threaded - applications (apache2, firefox, etc.). It receives an integer as value: if - this value is `-1` then all threads state will be displayed. Otherwise, if the - value is set to `N`, then at most `N` thread states will be shown. +* `nb_lines_code` and `nb_lines_code_prev` configure how many lines to show after and before the PC, + respectively. +* `context.nb_lines_threads` determines the number of lines to display inside the thread pane. This + is convenient when debugging heavily multi-threaded applications (apache2, firefox, etc.). It + receives an integer as value: if this value is `-1` then all threads state will be displayed. + Otherwise, if the value is set to `N`, then at most `N` thread states will be shown. -To have the stack displayed with the largest stack addresses on top (i.e., grow the -stack downward), enable the following setting: +To have the stack displayed with the largest stack addresses on top (i.e., grow the stack downward), +enable the following setting: ``` gef➤ gef config context.grow_stack_down True ``` -If the saved instruction pointer is not within the portion of the stack being displayed, -then a section is created that includes the saved ip and depending on the architecture -the frame pointer. +If the saved instruction pointer is not within the portion of the stack being displayed, then a +section is created that includes the saved ip and depending on the architecture the frame pointer. ``` 0x00007fffffffc9e8│+0x00: 0x00007ffff7a2d830 → <__main+240> mov edi, eax ($current_frame_savedip) 0x00007fffffffc9e0│+0x00: 0x00000000004008c0 → <__init+0> push r15 ← $rbp @@ -112,12 +102,10 @@ the frame pointer. ### Redirecting context output to another tty/file ### -By default, the `gef` context will be displayed on the current TTY. This can be -overridden by setting `context.redirect` variable to have the context sent to -another section. +By default, the `gef` context will be displayed on the current TTY. This can be overridden by +setting `context.redirect` variable to have the context sent to another section. -To do so, select the TTY/file/socket/etc. you want the context redirected to -with `gef config`. +To do so, select the TTY/file/socket/etc. you want the context redirected to with `gef config`. Enter the command `tty` in the prompt: ``` diff --git a/docs/commands/dereference.md b/docs/commands/dereference.md index 406919951..69e528cc8 100644 --- a/docs/commands/dereference.md +++ b/docs/commands/dereference.md @@ -1,16 +1,14 @@ ## Command `dereference` -The `dereference` command (also aliased `telescope` for PEDA former users) aims -to simplify the dereferencing of an address in GDB to determine the content it -actually points to. +The `dereference` command (also aliased `telescope` for PEDA former users) aims to simplify the +dereferencing of an address in GDB to determine the content it actually points to. -It is a useful convienence function to spare to process of manually tracking -values with successive `x/x` in GDB. +It is a useful convienence function to spare to process of manually tracking values with successive +`x/x` in GDB. -`dereference` takes three optional arguments, a start address (or symbol or -register, etc) to dereference (by default, `$sp`), the number of consecutive -addresses to dereference (by default, `10`) and the base location for offset -calculation (by default the same as the start address): +`dereference` takes three optional arguments, a start address (or symbol or register, etc) to +dereference (by default, `$sp`), the number of consecutive addresses to dereference (by default, +`10`) and the base location for offset calculation (by default the same as the start address): ``` gef➤ dereference @@ -40,11 +38,11 @@ gef➤ telescope $rbp+0x10 -l 8 0x00007fffffffdf78│+0x0038: 0x0000000000000000 ``` -It also optionally accepts a second argument, the number of consecutive -addresses to dereference (by default, `10`). +It also optionally accepts a second argument, the number of consecutive addresses to dereference (by +default, `10`). -For example, if you want to dereference all the stack entries inside a function -context (on a 64bit architecture): +For example, if you want to dereference all the stack entries inside a function context (on a 64bit +architecture): ``` gef➤ p ($rbp - $rsp)/8 @@ -57,8 +55,7 @@ gef➤ dereference -l 5 0x00007fffffffe190│+0x0020: 0x0000000000400690 → push r15 ← $rbp ``` -It is possible to change the offset calculation to use a different address than -the start address: +It is possible to change the offset calculation to use a different address than the start address: ``` gef➤ dereference $sp -l 7 -r $rbp @@ -71,8 +68,8 @@ gef➤ dereference $sp -l 7 -r $rbp 0x00007ffe6ddaa410│+0x0000: 0x0000000000000000 ← $rbp ``` -Just like with `x`, you can pass a negative number of addresses to dereference, to examine memory backwards -from the start address: +Just like with `x`, you can pass a negative number of addresses to dereference, to examine memory +backwards from the start address: ``` gef➤ dereference $sp -l 3 0x00007fffffffcf90│+0x0010: 0x00007ffff7f5aaa0 → 0x0000000000000000 diff --git a/docs/commands/edit-flags.md b/docs/commands/edit-flags.md index 9b80b125b..e507cc0b1 100644 --- a/docs/commands/edit-flags.md +++ b/docs/commands/edit-flags.md @@ -1,19 +1,18 @@ ## Command `edit-flags` -The `edit-flags` command (alias: `flags`) provides a quick and comprehensible -way to view and edit the flag register for the architectures that support it. -Without argument, the command will simply return a human-friendly display of the -register flags. +The `edit-flags` command (alias: `flags`) provides a quick and comprehensible way to view and edit +the flag register for the architectures that support it. Without argument, the command will simply +return a human-friendly display of the register flags. One or many arguments can be provided, following the syntax below: ``` gef➤ flags [(+|-|~)FLAGNAME ...] ``` -Where `FLAGNAME` is the name of the flag (case insensitive), and `+|-|~` indicates -the action on whether to set, unset, or toggle the flag. +Where `FLAGNAME` is the name of the flag (case insensitive), and `+|-|~` indicates the action on +whether to set, unset, or toggle the flag. -For instance, on x86 architecture, if we don't want to take a conditional jump -(e.g. a `jz` instruction), but we want to have the Carry flag set, simply go with: +For instance, on x86 architecture, if we don't want to take a conditional jump (e.g. a `jz` +instruction), but we want to have the Carry flag set, simply go with: ``` gef➤ flags -ZERO +CARRY diff --git a/docs/commands/elf-info.md b/docs/commands/elf-info.md index 687174704..16ae78f6f 100644 --- a/docs/commands/elf-info.md +++ b/docs/commands/elf-info.md @@ -1,7 +1,6 @@ ## Command `elf-info` -`elf-info` (alias `elf`) provides some basic information on the currently -loaded ELF binary: +`elf-info` (alias `elf`) provides some basic information on the currently loaded ELF binary: ``` gef➤ elf @@ -65,8 +64,8 @@ Entry point : 0x0000000000400750 [28] .shstrtab STRTAB 0x0 0x20ac 0xfc 0x0 0x0 0x0 0x1 ``` -Optionally a filepath to another ELF binary can be provided to view the basic -information for that binary instead. +Optionally a filepath to another ELF binary can be provided to view the basic information for that +binary instead. ``` gef➤ elf-info --filename /path/to/elf/executable diff --git a/docs/commands/entry-break.md b/docs/commands/entry-break.md index 14139a844..3796fe45d 100644 --- a/docs/commands/entry-break.md +++ b/docs/commands/entry-break.md @@ -1,17 +1,15 @@ ## Command `entry-break` -The `entry-break` (alias `start`) command's goal is to find and break at the -most obvious entry point available in the binary. Since the binary will start -running, some of the `PLT` entries will also be resolved, making further -debugging easier. +The `entry-break` (alias `start`) command's goal is to find and break at the most obvious entry +point available in the binary. Since the binary will start running, some of the `PLT` entries will +also be resolved, making further debugging easier. It will perform the following actions: 1. Look up a `main` symbol. If found, set a temporary breakpoint and go. -2. Otherwise, it will look up for `__libc_start_main`. If found, set a -temporary breakpoint and go. -3. Finally, if the previous two symbols are not found, it will get the entry -point from the ELF header, set a breakpoint and run. This case should never -fail if the ELF binary has a valid structure. +2. Otherwise, it will look up for `__libc_start_main`. If found, set a temporary breakpoint and go. +3. Finally, if the previous two symbols are not found, it will get the entry point from the ELF + header, set a breakpoint and run. This case should never fail if the ELF binary has a valid + structure. ![entry-break-example](https://i.imgur.com/zXSERMh.png) diff --git a/docs/commands/eval.md b/docs/commands/eval.md index 56c35dcf1..72a096451 100644 --- a/docs/commands/eval.md +++ b/docs/commands/eval.md @@ -2,8 +2,8 @@ The `$` command attempts to mimic WinDBG `?` command. -When provided one argument, it will evaluate the expression, and try to display -the result with various formats: +When provided one argument, it will evaluate the expression, and try to display the result with +various formats: ``` gef➤ $ $pc+1 diff --git a/docs/commands/format-string-helper.md b/docs/commands/format-string-helper.md index f4b7ba0a5..17d7164e5 100644 --- a/docs/commands/format-string-helper.md +++ b/docs/commands/format-string-helper.md @@ -1,8 +1,7 @@ ## Command `format-string-helper` -The `format-string-helper` command will create a `GEF` specific type of -breakpoints dedicated to detecting potentially insecure format string when -using the GlibC library. +The `format-string-helper` command will create a `GEF` specific type of breakpoints dedicated to +detecting potentially insecure format string when using the GlibC library. It will use this new breakpoint against several targets, including: @@ -25,8 +24,8 @@ Then start the binary execution. gef➤ r ``` -If a potentially insecure entry is found, the breakpoint will trigger, stop the -process execution, display the reason for trigger and the associated context. +If a potentially insecure entry is found, the breakpoint will trigger, stop the process execution, +display the reason for trigger and the associated context. ![fmtstr-helper-example](https://i.imgur.com/INU3KGn.png) diff --git a/docs/commands/functions.md b/docs/commands/functions.md index 94a323da5..c13562436 100644 --- a/docs/commands/functions.md +++ b/docs/commands/functions.md @@ -1,23 +1,16 @@ ## Command `functions` -The `functions` command will list all of -the [convenience functions](https://sourceware.org/gdb/onlinedocs/gdb/Convenience-Funs.html) -provided by GEF. +The `functions` command will list all of the [convenience +functions](https://sourceware.org/gdb/onlinedocs/gdb/Convenience-Funs.html) provided by GEF. -- `$_base([filepath])` -- Return the matching file's base address plus an - optional offset. Defaults to the current file. Note that quotes need to be - escaped. -- `$_bss([offset])` -- Return the current bss base address plus the given - offset. -- `$_got([offset])` -- Return the current bss base address plus the given - offset. -- `$_heap([offset])` -- Return the current heap base address plus an - optional offset. -- `$_stack([offset])` -- Return the current stack base address plus an - optional offset. +- `$_base([filepath])` -- Return the matching file's base address plus an optional offset. + Defaults to the current file. Note that quotes need to be escaped. +- `$_bss([offset])` -- Return the current bss base address plus the given offset. +- `$_got([offset])` -- Return the current bss base address plus the given offset. +- `$_heap([offset])` -- Return the current heap base address plus an optional offset. +- `$_stack([offset])` -- Return the current stack base address plus an optional offset. -These functions can be used as arguments to other commands to dynamically -calculate values. +These functions can be used as arguments to other commands to dynamically calculate values. ``` gef➤ deref -l 4 $_heap() diff --git a/docs/commands/gef-remote.md b/docs/commands/gef-remote.md index 46982ab1d..756cf8d68 100644 --- a/docs/commands/gef-remote.md +++ b/docs/commands/gef-remote.md @@ -1,20 +1,31 @@ ## Command `gef-remote` -[`target remote`](https://sourceware.org/gdb/onlinedocs/gdb/Remote-Debugging.html#Remote-Debugging) is the traditional GDB way of debugging process or system remotely. However this command by itself does a limited job (80's bandwith FTW) to collect more information about the target, making the process of debugging more cumbersome. GEF greatly improves that state with the `gef-remote` command. +[`target remote`](https://sourceware.org/gdb/onlinedocs/gdb/Remote-Debugging.html#Remote-Debugging) +is the traditional GDB way of debugging process or system remotely. However this command by itself +does a limited job (80's bandwith FTW) to collect more information about the target, making the +process of debugging more cumbersome. GEF greatly improves that state with the `gef-remote` command. -📝 **Note**: If using GEF, `gef-remote` **must** be your way or debugging remote processes, never `target remote`. Maintainers will not provide support or help if you decide to use the traditional `target remote` command. For many reasons, you **cannot** use `target remote` alone with GEF. +📝 **Note**: If using GEF, `gef-remote` **must** be your way or debugging remote processes, never +`target remote`. Maintainers will not provide support or help if you decide to use the traditional +`target remote` command. For many reasons, you **cannot** use `target remote` alone with GEF. `gef-remote` can function in 2 ways: - - `remote` which is meant to enrich use of GDB `target remote` command, when connecting to a "real" gdbserver instance - - `qemu-mode` when connecting to GDB stab of either `qemu-user` or `qemu-system`. +- `remote` which is meant to enrich use of GDB `target remote` command, when connecting to a "real" + gdbserver instance +- `qemu-mode` when connecting to GDB stab of either `qemu-user` or `qemu-system`. -The reason for this difference being that Qemu provides *a lot* less information that GEF can extract to enrich debugging. Whereas GDBServer allows to download remote file (therefore allowing to create a small identical environment), GDB stub in Qemu does not support file transfer. As a consequence, in order to use GEF in qemu mode, it is required to provide the binary being debugged. GEF will create a mock (limited) environment so that all its most useful features are available. +The reason for this difference being that Qemu provides *a lot* less information that GEF can +extract to enrich debugging. Whereas GDBServer allows to download remote file (therefore allowing to +create a small identical environment), GDB stub in Qemu does not support file transfer. As a +consequence, in order to use GEF in qemu mode, it is required to provide the binary being debugged. +GEF will create a mock (limited) environment so that all its most useful features are available. ### Remote mode #### `remote` -If you want to remotely debug a binary that you already have, you simply need to tell to `gdb` where to find the debug information. +If you want to remotely debug a binary that you already have, you simply need to tell to `gdb` where +to find the debug information. For example, if we want to debug `uname`, we do on the server: @@ -26,7 +37,8 @@ Listening on port 1234 ![gef-remote-1](https://i.imgur.com/Zc4vnBd.png) -On the client, when the original `gdb` would use `target remote`, GEF's syntax is roughly similar (shown running in debug mode for more verbose output, but you don't have to): +On the client, when the original `gdb` would use `target remote`, GEF's syntax is roughly similar +(shown running in debug mode for more verbose output, but you don't have to): ``` $ gdb -ex 'gef config gef.debug 1' @@ -62,19 +74,25 @@ And finally breaking into the program, showing the current context: ![gef-remote](https://i.imgur.com/IfsRDvK.png) -You will also notice the prompt has changed to indicate the debugging mode is now "remote". Besides that, all of GEF features are available: +You will also notice the prompt has changed to indicate the debugging mode is now "remote". Besides +that, all of GEF features are available: ![gef-remote-command](https://i.imgur.com/05epyX6.png) #### `remote-extended` -Extended mode works the same as `remote`. Being an extended session, gdbserver has not spawned or attached to any process. Therefore, all that's required is to add the `--pid` flag when calling `gef-remote`, along with the process ID of the process to debug. +Extended mode works the same as `remote`. Being an extended session, gdbserver has not spawned or +attached to any process. Therefore, all that's required is to add the `--pid` flag when calling +`gef-remote`, along with the process ID of the process to debug. ### Qemu mode -Qemu mode of `gef-remote` allows to connect to the [Qemu GDB stub](https://qemu-project.gitlab.io/qemu/system/gdb.html) which allows to live debug into either a binary (`qemu-user`) or even the kernel (`qemu-system`), of any architecture supported by GEF, which makes now even more sense 😉 And using it is very straight forward. +Qemu mode of `gef-remote` allows to connect to the [Qemu GDB +stub](https://qemu-project.gitlab.io/qemu/system/gdb.html) which allows to live debug into either a +binary (`qemu-user`) or even the kernel (`qemu-system`), of any architecture supported by GEF, which +makes now even more sense 😉 And using it is very straight forward. #### `qemu-user` @@ -84,15 +102,12 @@ Qemu mode of `gef-remote` allows to connect to the [Qemu GDB stub](https://qemu- ![qemu-user](https://user-images.githubusercontent.com/590234/175072835-e276ab6c-4f75-4313-9e66-9fe5a3fd220e.png) - #### `qemu-system` -To test locally, you can use the mini image linux x64 vm [here](https://mega.nz/file/ldQCDQiR#yJWJ8RXAHTxREKVmR7Hnfr70tIAQDFeWSYj96SvPO1k). +To test locally, you can use the mini image linux x64 vm +[here](https://mega.nz/file/ldQCDQiR#yJWJ8RXAHTxREKVmR7Hnfr70tIAQDFeWSYj96SvPO1k). 1. Run `./run.sh` 2. Use `--qemu-user` and `--qemu-binary vmlinuz` when starting `gef-remote` ![qemu-system](https://user-images.githubusercontent.com/590234/175071351-8e06aa27-dc61-4fd7-9215-c345dcebcd67.png) - - - diff --git a/docs/commands/gef.md b/docs/commands/gef.md index e1314838a..5f687786d 100644 --- a/docs/commands/gef.md +++ b/docs/commands/gef.md @@ -20,7 +20,9 @@ bytearray -- BytearrayCommand: Generate a bytearray to be compar ### GEF Missing Command -GEF is fully battery-included. However in some rare cases, it is possible that not all commands be loaded. If that's the case the command `gef missing` will detail which command failed to load, along with a (likely) reason. Read the documentation for a solution, or reach out on the Discord. +GEF is fully battery-included. However in some rare cases, it is possible that not all commands be +loaded. If that's the case the command `gef missing` will detail which command failed to load, along +with a (likely) reason. Read the documentation for a solution, or reach out on the Discord. ``` gef➤ gef missing @@ -30,11 +32,10 @@ gef➤ gef missing ### GEF Config Command -Allows the user to set/view settings for the current debugging session. For -making the changes persistent see the `gef save` entry. +Allows the user to set/view settings for the current debugging session. For making the changes +persistent see the `gef save` entry. -Using `gef config` by itself just shows all of the available settings and their -values. +Using `gef config` by itself just shows all of the available settings and their values. ``` gef➤ gef config @@ -64,8 +65,8 @@ theme.default_title_message (str) = "cyan" ``` -You can use `gef config [setting] [value]` to set a setting for the current -session (see example below). +You can use `gef config [setting] [value]` to set a setting for the current session (see example +below). ``` gef➤ gef config theme.address_stack blue @@ -73,8 +74,8 @@ gef➤ gef config theme.address_stack blue ### GEF Save Command -The `gef save` command saves the current settings (set with `gef config`) to -the user's `~/.gef.rc` file (making the changes persistent). +The `gef save` command saves the current settings (set with `gef config`) to the user's `~/.gef.rc` +file (making the changes persistent). ``` gef➤ gef save @@ -83,9 +84,9 @@ gef➤ gef save ### GEF Restore Command -Using `gef restore` loads and applies settings from the `~/.gef.rc` file to the -current session. This is useful if you are modifying your GEF configuration -file and want to see the changes without completely reloading GEF. +Using `gef restore` loads and applies settings from the `~/.gef.rc` file to the current session. +This is useful if you are modifying your GEF configuration file and want to see the changes without +completely reloading GEF. ``` gef➤ gef restore @@ -94,9 +95,8 @@ gef➤ gef restore ### GEF Set Command -The GEF set command allows the user to use GEF context within GDB set commands. -This is useful when you want to make a convenient variable which can be set and -referenced later. +The GEF set command allows the user to use GEF context within GDB set commands. This is useful when +you want to make a convenient variable which can be set and referenced later. ``` gef➤ gef set $a=1 @@ -104,8 +104,8 @@ gef➤ gef set $a=1 ### GEF Run Command -The GEF run command is a wrapper around GDB's run command, allowing the user to -use GEF context within the command. +The GEF run command is a wrapper around GDB's run command, allowing the user to use GEF context +within the command. ``` gef➤ gef run ./binary @@ -114,13 +114,15 @@ gef➤ gef run ./binary ### GEF Install Command -`gef install` allows to install one (or more) specific script(s) from `gef-extras`. The new scripts will be downloaded and sourced to be used immediately after by GEF. The syntax is straight forward: +`gef install` allows to install one (or more) specific script(s) from `gef-extras`. The new scripts +will be downloaded and sourced to be used immediately after by GEF. The syntax is straight forward: ``` gef➤ gef install SCRIPTNAME1 [SCRIPTNAME2...] ``` -Where `SCRIPTNAME1` ... are the names of script from the [`gef-extras` repository](https://github.com/hugsy/gef-extras/tree/main/scripts/). +Where `SCRIPTNAME1` ... are the names of script from the [`gef-extras` +repository](https://github.com/hugsy/gef-extras/tree/main/scripts/). ``` @@ -134,11 +136,12 @@ gef➤ gef install remote windbg stack gef➤ ``` -This makes it easier to deploy new functionalities in limited environment. By default, the command looks up for script names in the `main` branch of `gef-extras`. However you can change specify a different branch through the `gef.default_branch` configuration setting: - +This makes it easier to deploy new functionalities in limited environment. By default, the command +looks up for script names in the `main` branch of `gef-extras`. However you can change specify a +different branch through the `gef.default_branch` configuration setting: ``` gef➤ gef config gef.default_branch dev ``` -The files will be dowloaded in the path configured in the `gef.extra_plugins_dir` setting, allowing to reload it easily without having to re-download. - +The files will be dowloaded in the path configured in the `gef.extra_plugins_dir` setting, allowing +to reload it easily without having to re-download. diff --git a/docs/commands/got.md b/docs/commands/got.md index cd8867387..25b129a84 100644 --- a/docs/commands/got.md +++ b/docs/commands/got.md @@ -2,16 +2,15 @@ Display the current state of GOT table of the running process. -The `got` command optionally takes function names and filters -the output displaying only the matching functions. +The `got` command optionally takes function names and filters the output displaying only the +matching functions. ``` gef➤ got ``` ![gef-got](https://i.imgur.com/554ebM3.png) -The applied filter partially matches the name of the functions, so -you can do something like this. +The applied filter partially matches the name of the functions, so you can do something like this. ``` gef➤ got str gef➤ got print diff --git a/docs/commands/heap-analysis-helper.md b/docs/commands/heap-analysis-helper.md index a66294098..65a74fbd4 100644 --- a/docs/commands/heap-analysis-helper.md +++ b/docs/commands/heap-analysis-helper.md @@ -2,16 +2,15 @@ Please note: This feature is still under development, expect bugs and unstability. -`heap-analysis-helper` command aims to help the process of idenfitying Glibc -heap inconsistencies by tracking and analyzing allocations and deallocations of -chunks of memory. +`heap-analysis-helper` command aims to help the process of idenfitying Glibc heap inconsistencies by +tracking and analyzing allocations and deallocations of chunks of memory. Currently, the following issues can be tracked: - * NULL free - * Use-after-Free - * Double Free - * Heap overlap +- NULL free +- Use-after-Free +- Double Free +- Heap overlap The helper can simply be activated by running the command `heap-analysis-helper`. @@ -24,34 +23,29 @@ gef➤ heap-analysis [+] To disable, clear the malloc/free breakpoints (`delete breakpoints`) and restore hardware breakpoints (`set can-use-hw-watchpoints 1`) ``` -The helper will create specifically crafted breakoints to keep tracks of -allocation, which allows to discover *potential* vulnerabilities. Once -activated, one can disable the heap analysis breakpoints simply by clearing the -`__GI___libc_free()` et `__GI___libc_malloc()`. It is also possible to +The helper will create specifically crafted breakoints to keep tracks of allocation, which allows to +discover *potential* vulnerabilities. Once activated, one can disable the heap analysis breakpoints +simply by clearing the `__GI___libc_free()` et `__GI___libc_malloc()`. It is also possible to enable/disable manually punctual checks via the `gef config` command. The following settings are accepted: - * `check_null_free`: to break execution when a free(NULL) is encountered - (disabled by default); - * `check_double_free`: to break execution when a double free is encountered; +* `check_null_free`: to break execution when a free(NULL) is encountered (disabled by default); +* `check_double_free`: to break execution when a double free is encountered; ![double-free](https://i.imgur.com/S7b4FJa.png) - * `check_weird_free`: to execution when `free()` is called against a - non-tracked pointer; - * `check_uaf`: to break execution when a possible Use-after-Free condition is - found. +* `check_weird_free`: to execution when `free()` is called against a non-tracked pointer; +* `check_uaf`: to break execution when a possible Use-after-Free condition is found. ![uaf](https://i.imgur.com/NfV5Cu9.png) -Just like the format string vulnerability helper, the `heap-analysis-helper` -can fail to detect complex heap scenarios and/or provide some false positive -alerts. Each finding must of course be ascertained manually. +Just like the format string vulnerability helper, the `heap-analysis-helper` can fail to detect +complex heap scenarios and/or provide some false positive alerts. Each finding must of course be +ascertained manually. -The `heap-analysis-helper` can also be used to simply track allocation and -liberation of chunks of memory. One can simply enable the tracking by setting -all the configurations stated above to False: +The `heap-analysis-helper` can also be used to simply track allocation and liberation of chunks of +memory. One can simply enable the tracking by setting all the configurations stated above to False: ``` gef➤ gef config heap-analysis-helper.check_double_free False @@ -60,13 +54,12 @@ gef➤ gef config heap-analysis-helper.check_weird_free False gef➤ gef config heap-analysis-helper.check_uaf False ``` -Then `gef` will not notify you of any inconsistency detected, but simply display -a clear message when a chunk is allocated/freed. +Then `gef` will not notify you of any inconsistency detected, but simply display a clear message +when a chunk is allocated/freed. ![heap-track](https://i.imgur.com/68NGTvw.png) -To get information regarding the currently tracked chunks, use the `show` -subcommand: +To get information regarding the currently tracked chunks, use the `show` subcommand: ``` gef➤ heap-analysis-helper show diff --git a/docs/commands/heap.md b/docs/commands/heap.md index 170a3b5d5..ab85fb6e0 100644 --- a/docs/commands/heap.md +++ b/docs/commands/heap.md @@ -1,9 +1,9 @@ ## Command `heap` -The `heap` command provides information on the heap chunk specified as argument. For -the moment, it only supports GlibC heap format (see -[this link](https://code.woboq.org/userspace/glibc/malloc/malloc.c.html#malloc_chunk) -for `malloc` structure information). Syntax to the subcommands is straight forward: +The `heap` command provides information on the heap chunk specified as argument. For the moment, it +only supports GlibC heap format (see [this +link](https://code.woboq.org/userspace/glibc/malloc/malloc.c.html#malloc_chunk) for `malloc` +structure information). Syntax to the subcommands is straight forward: ``` gef➤ heap @@ -11,24 +11,24 @@ gef➤ heap ## `main_arena` symbol ### -If the linked glibc of the target program does not have debugging symbols it -might be tricky for GEF to find the address of the `main_arena` which is needed -for most of the `heap` subcommands. If you know the offset of this symbol from -the glibc base address you can use GEF's config to provide said value: +If the linked glibc of the target program does not have debugging symbols it might be tricky for GEF +to find the address of the `main_arena` which is needed for most of the `heap` subcommands. If you +know the offset of this symbol from the glibc base address you can use GEF's config to provide said +value: ``` gef➤ gef config gef.main_arena_offset ``` -If you do not know this offset and you want GEF to try and find it via bruteforce -when executing a `heap` command the next time, you can try this instead: +If you do not know this offset and you want GEF to try and find it via bruteforce when executing a +`heap` command the next time, you can try this instead: ``` gef➤ gef config gef.bruteforce_main_arena True ``` -Note that this might take a few seconds to complete. If GEF does find the symbol -you can then calculate the offset to the libc base address and save it in the config. +Note that this might take a few seconds to complete. If GEF does find the symbol you can then +calculate the offset to the libc base address and save it in the config. ### `heap chunks` command ### @@ -41,8 +41,8 @@ gef➤ heap chunks ![heap-chunks](https://i.imgur.com/y90SfKH.png) -To select from which arena to display chunks either use the `heap set-arena` -command or provide the base address of the other arena like this: +To select from which arena to display chunks either use the `heap set-arena` command or provide the +base address of the other arena like this: ``` gef➤ heap chunks [arena_address] @@ -58,17 +58,15 @@ gef➤ heap chunks -a ![heap-chunks-all](https://i.imgur.com/pTjRJFo.png) -Because usually the heap chunks are aligned to a certain number of bytes in -memory GEF automatically re-aligns the chunks data start addresses to match -Glibc's behavior. To be able to view unaligned chunks as well, you can disable -this with the `--allow-unaligned` flag. Note that this might result in -incorrect output. +Because usually the heap chunks are aligned to a certain number of bytes in memory GEF automatically +re-aligns the chunks data start addresses to match Glibc's behavior. To be able to view unaligned +chunks as well, you can disable this with the `--allow-unaligned` flag. Note that this might result +in incorrect output. ### `heap chunk` command ### -This command gives visual information of a Glibc malloc-ed chunked. Simply -provide the address to the user memory pointer of the chunk to show the -information related to a specific chunk: +This command gives visual information of a Glibc malloc-ed chunked. Simply provide the address to +the user memory pointer of the chunk to show the information related to a specific chunk: ``` gef➤ heap chunk [address] @@ -76,14 +74,13 @@ gef➤ heap chunk [address] ![heap-chunk](https://i.imgur.com/WXpHR58.png) -Because usually the heap chunks are aligned to a certain number of bytes in -memory GEF automatically re-aligns the chunks data start addresses to match -Glibc's behavior. To be able to view unaligned chunks as well, you can disable -this with the `--allow-unaligned` flag. Note that this might result in -incorrect output. +Because usually the heap chunks are aligned to a certain number of bytes in memory GEF automatically +re-aligns the chunks data start addresses to match Glibc's behavior. To be able to view unaligned +chunks as well, you can disable this with the `--allow-unaligned` flag. Note that this might result +in incorrect output. - -There is an optional `number` argument, to specify the number of chunks printed by this command. To do so, simply provide the `--number` argument: +There is an optional `number` argument, to specify the number of chunks printed by this command. To +do so, simply provide the `--number` argument: ``` gef➤ heap chunk --number 6 0x4e5400 @@ -98,35 +95,31 @@ Chunk(addr=0x4e6760, size=0x4c0, flags=PREV_INUSE) ### `heap arenas` command ### -Multi-threaded programs have different arenas, and the knowledge of the -`main_arena` is not enough. `gef` therefore provides the `arena` sub-commands -to help you list all the arenas allocated in your program **at the moment you -call the command**. +Multi-threaded programs have different arenas, and the knowledge of the `main_arena` is not enough. +`gef` therefore provides the `arena` sub-commands to help you list all the arenas allocated in your +program **at the moment you call the command**. ![heap-arenas](https://i.imgur.com/RUTiADa.png) ### `heap set-arena` command ### -In cases where the debug symbol are not present (e.g. statically stripped -binary), it is possible to instruct GEF to find the `main_arena` at a different -location with the command: +In cases where the debug symbol are not present (e.g. statically stripped binary), it is possible to +instruct GEF to find the `main_arena` at a different location with the command: ``` gef➤ heap set-arena [address] ``` -If the arena address is correct, all `heap` commands will be functional, and use -the specified address for `main_arena`. +If the arena address is correct, all `heap` commands will be functional, and use the specified +address for `main_arena`. ### `heap bins` command ### -Glibc uses bins for keeping tracks of `free`d chunks. This is because making -allocations through `sbrk` (requiring a syscall) is costly. Glibc uses those -bins to remember formerly allocated chunks. Because bins are structured in -single or doubly linked list, I found that quite painful to always interrogate -`gdb` to get a pointer address, dereference it, get the value chunk, etc... So -I decided to implement the `heap bins` sub-command, which allows to get info -on: +Glibc uses bins for keeping tracks of `free`d chunks. This is because making allocations through +`sbrk` (requiring a syscall) is costly. Glibc uses those bins to remember formerly allocated chunks. +Because bins are structured in single or doubly linked list, I found that quite painful to always +interrogate `gdb` to get a pointer address, dereference it, get the value chunk, etc... So I decided +to implement the `heap bins` sub-command, which allows to get info on: - `fastbins` - `bins` @@ -137,13 +130,12 @@ on: #### `heap bins fast` command #### -When exploiting heap corruption vulnerabilities, it is sometimes convenient to -know the state of the `fastbinsY` array. +When exploiting heap corruption vulnerabilities, it is sometimes convenient to know the state of the +`fastbinsY` array. -The `fast` sub-command helps by displaying the list of fast chunks in this -array. Without any other argument, it will display the info of the `main_arena` -arena. It accepts an optional argument, the address of another arena (which you -can easily find using `heap arenas`). +The `fast` sub-command helps by displaying the list of fast chunks in this array. Without any other +argument, it will display the info of the `main_arena` arena. It accepts an optional argument, the +address of another arena (which you can easily find using `heap arenas`). ``` gef➤ heap bins fast @@ -159,26 +151,24 @@ Fastbins[idx=6, size=0x80] 0x00 #### Other `heap bins X` command #### -All the other subcommands (with the exception of `tcache`) for the `heap bins` -work the same way as `fast`. If no argument is provided, `gef` will fall back -to `main_arena`. Otherwise, it will use the address pointed as the base of the -`malloc_state` structure and print out information accordingly. +All the other subcommands (with the exception of `tcache`) for the `heap bins` work the same way as +`fast`. If no argument is provided, `gef` will fall back to `main_arena`. Otherwise, it will use the +address pointed as the base of the `malloc_state` structure and print out information accordingly. #### `heap bins tcache` command #### -Modern versions of `glibc` use `tcache` bins to speed up multithreaded -programs. Unlike other bins, `tcache` bins are allocated on a per-thread -basis, so there is one set of `tcache` bins for each thread. +Modern versions of `glibc` use `tcache` bins to speed up multithreaded programs. Unlike other bins, +`tcache` bins are allocated on a per-thread basis, so there is one set of `tcache` bins for each +thread. ``` gef➤ heap bins tcache [all] [thread_ids...] ``` -Without any arguments, `heap bins tcache` will display the `tcache` for the -current thread. `heap bins tcache all` will show the `tcache`s for every -thread, or you can specify any number of thread ids to see the `tcache` for -each of them. For example, use the following command to show the `tcache` bins -for threads 1 and 2. +Without any arguments, `heap bins tcache` will display the `tcache` for the current thread. `heap +bins tcache all` will show the `tcache`s for every thread, or you can specify any number of thread +ids to see the `tcache` for each of them. For example, use the following command to show the +`tcache` bins for threads 1 and 2. ``` gef➤ heap bins tcache 1 2 diff --git a/docs/commands/hexdump.md b/docs/commands/hexdump.md index 3c8e41f8a..2bd409b76 100644 --- a/docs/commands/hexdump.md +++ b/docs/commands/hexdump.md @@ -5,14 +5,13 @@ Imitation of the WinDBG command. This command takes 4 optional arguments: - The format for representing the data (by default, byte) -- A value/address/symbol used as the location to print the hexdump from (by - default, $sp) -- The number of qword/dword/word/bytes to display (by default, 64 if the format - is byte, 16 otherwise) +- A value/address/symbol used as the location to print the hexdump from (by default, $sp) +- The number of qword/dword/word/bytes to display (by default, 64 if the format is byte, 16 + otherwise) - The direction of output lines (by default, from low to high addresses) -`hexdump byte` will also try to display the ASCII character values if the byte -is printable (similarly to the `hexdump -C` command on Linux). +`hexdump byte` will also try to display the ASCII character values if the byte is printable +(similarly to the `hexdump -C` command on Linux). The syntax is as following: diff --git a/docs/commands/highlight.md b/docs/commands/highlight.md index dfe962f5f..81b8989c0 100644 --- a/docs/commands/highlight.md +++ b/docs/commands/highlight.md @@ -10,7 +10,7 @@ highlight (add|remove|list|clear) Alias: - - `hl` +- `hl` ## Adding matches @@ -71,11 +71,10 @@ highlight.regex (bool) = True ## Performance -_**NOTE:** Adding many matches may slow down debugging while using GEF. -This includes enabling RegEx support._ +_**NOTE:** Adding many matches may slow down debugging while using GEF. This includes enabling RegEx +support._ ## Colors -To find a list of supported colors, check the -[theme](./theme.md#changing-colors) documentation. +To find a list of supported colors, check the [theme](./theme.md#changing-colors) documentation. diff --git a/docs/commands/hijack-fd.md b/docs/commands/hijack-fd.md index ee8bf48e1..7b4fd9222 100644 --- a/docs/commands/hijack-fd.md +++ b/docs/commands/hijack-fd.md @@ -16,7 +16,8 @@ Will modify the current process file descriptors to redirect STDOUT to `/dev/null`. -This command also supports connecting to an ip:port if it is provided as an argument. For example +This command also supports connecting to an ip:port if it is provided as an +argument. For example ``` gef➤ hijack-fd 0 localhost:8888 ``` diff --git a/docs/commands/ksymaddr.md b/docs/commands/ksymaddr.md index aa0545280..e6ffea221 100644 --- a/docs/commands/ksymaddr.md +++ b/docs/commands/ksymaddr.md @@ -19,6 +19,6 @@ gef➤ ksymaddr commit_creds [*] Found partial match for 'commit_creds' at 0xffffffff8fc9bfcd (type=r): __kstrtab_commit_creds ``` -Note that the debugging process needs to have the correct permissions for this -command to show kernel addresses. For more information see -also [this stackoverflow post](https://stackoverflow.com/a/55592796). \ No newline at end of file +Note that the debugging process needs to have the correct permissions for this command to show +kernel addresses. For more information see also [this stackoverflow +post](https://stackoverflow.com/a/55592796). diff --git a/docs/commands/memory.md b/docs/commands/memory.md index 56bbb8075..676065629 100644 --- a/docs/commands/memory.md +++ b/docs/commands/memory.md @@ -1,11 +1,13 @@ ## Command `memory` -As long as the 'memory' section is enabled in your context layout (which it is -by default), you can register addresses, lengths, and grouping size. +As long as the 'memory' section is enabled in your context layout (which it is by default), you can +register addresses, lengths, and grouping size. ![memory watch](https://i.imgur.com/NXYwSwW.png) -_Note_: this command **shoud NOT** be mistaken with the [GDB `watch` command](https://sourceware.org/gdb/current/onlinedocs/gdb/Set-Watchpoints.html) meant to set breakpoints on memory access (read,write,exec). +_Note_: this command **shoud NOT** be mistaken with the [GDB `watch` +command](https://sourceware.org/gdb/current/onlinedocs/gdb/Set-Watchpoints.html) meant to set +breakpoints on memory access (read,write,exec). ### Adding a watch @@ -17,10 +19,14 @@ Syntax: memory watch
[SIZE] [(qword|dword|word|byte|pointers)] ``` -If the format specified is `pointers`, then the output will be similar to executing the command `dereference $address`. -For all other format, the output will be an hexdump of the designated location. +If the format specified is `pointers`, then the output will be similar to executing the command +`dereference $address`. For all other format, the output will be an hexdump of the designated +location. -Note that the address format is a GDB therefore a symbol can be passed to it. It also supports [GEF functions format](https://www.technovelty.org/linux/plt-and-got-the-key-to-code-sharing-and-dynamic-libraries.html) allowing to easily track commonly used addresses: +Note that the address format is a GDB therefore a symbol can be passed to it. It also supports [GEF +functions +format](https://www.technovelty.org/linux/plt-and-got-the-key-to-code-sharing-and-dynamic-libraries.html) +allowing to easily track commonly used addresses: For example, to watch the first 5 entries of the [GOT]() as pointers: @@ -64,4 +70,3 @@ Syntax: ``` memory reset ``` - diff --git a/docs/commands/name-break.md b/docs/commands/name-break.md index 804b3301a..c0c6175f4 100644 --- a/docs/commands/name-break.md +++ b/docs/commands/name-break.md @@ -1,17 +1,15 @@ ## Command `name-break` -The command `name-break` (alias `nb`) can be used to set a breakpoint on -a location with a name assigned to it. +The command `name-break` (alias `nb`) can be used to set a breakpoint on a location with a name +assigned to it. -Every time this breakpoint is hit, the specified name will also be shown -in the `extra` section to make it easier to keep an overview when using -multiple breakpoints in a stripped binary. +Every time this breakpoint is hit, the specified name will also be shown in the `extra` section to +make it easier to keep an overview when using multiple breakpoints in a stripped binary. `name-break name [address]` -`address` may be a linespec, address, or explicit location, same as specified -for `break`. If `address` isn't specified, it will create the breakpoint at the -current instruction pointer address. +`address` may be a linespec, address, or explicit location, same as specified for `break`. If +`address` isn't specified, it will create the breakpoint at the current instruction pointer address. Examples: diff --git a/docs/commands/nop.md b/docs/commands/nop.md index d519c290f..8f8b75c76 100644 --- a/docs/commands/nop.md +++ b/docs/commands/nop.md @@ -6,9 +6,10 @@ The `nop` command allows you to easily patch instructions with nops. nop [LOCATION] [--n NUM_ITEMS] [--b] ``` -`LOCATION` address/symbol to patch +`LOCATION` address/symbol to patch -`--n NUM_ITEMS` Instead of writing one instruction/nop, patch the specified number of instructions/nops (full instruction size by default) +`--n NUM_ITEMS` Instead of writing one instruction/nop, patch the specified number of +instructions/nops (full instruction size by default) `--b` Instead of writing full instruction size, patch the specified number of nops @@ -19,4 +20,4 @@ gef➤ nop --n 2 $pc+3 gef➤ nop --b gef➤ nop --b $pc+3 gef➤ nop --b --n 2 $pc+3 -``` \ No newline at end of file +``` diff --git a/docs/commands/pattern.md b/docs/commands/pattern.md index f5ba7be92..687f05036 100644 --- a/docs/commands/pattern.md +++ b/docs/commands/pattern.md @@ -1,13 +1,11 @@ ## Command `pattern` -This command will create or search a [De -Bruijn](https://en.wikipedia.org/wiki/De_Bruijn_sequence) cyclic pattern to -facilitate determining offsets in memory. The sequence consists of a number of +This command will create or search a [De Bruijn](https://en.wikipedia.org/wiki/De_Bruijn_sequence) +cyclic pattern to facilitate determining offsets in memory. The sequence consists of a number of unique substrings of a chosen length. -It should be noted that for better compatibility, the algorithm implemented in -`GEF` is the same as the one in `pwntools`, and can therefore be used in -conjunction. +It should be noted that for better compatibility, the algorithm implemented in `GEF` is the same as +the one in `pwntools`, and can therefore be used in conjunction. ### `pattern create` ### @@ -15,10 +13,9 @@ conjunction. pattern create [-h] [-n N] [length] ``` -The sub-command `create` allows one create a new De Bruijn sequence. The -optional argument `n` determines the length of unique subsequences. Its default -value matches the currently loaded architecture. The `length` argument sets the -total length of the whole sequence. +The sub-command `create` allows one create a new De Bruijn sequence. The optional argument `n` +determines the length of unique subsequences. Its default value matches the currently loaded +architecture. The `length` argument sets the total length of the whole sequence. ``` gef➤ pattern create -n 4 128 @@ -40,14 +37,13 @@ p = cyclic(128, n=8) pattern search [-h] [-n N] [--max-length MAX_LENGTH] [pattern] ``` -The `search` sub-command seeks the `pattern` given as argument, trying to find -its offset in the De Bruijn sequence. The optional argument `n` determines the -length of unique subsequences, and it should usually match the length of -`pattern`. Using `MAX_LENGTH` the maximum length of the sequence to search in -can be adjusted. +The `search` sub-command seeks the `pattern` given as argument, trying to find its offset in the De +Bruijn sequence. The optional argument `n` determines the length of unique subsequences, and it +should usually match the length of `pattern`. Using `MAX_LENGTH` the maximum length of the sequence +to search in can be adjusted. -Note that the `pattern` can be passed as a GDB symbol (such as a register name), -a string or a hexadecimal value +Note that the `pattern` can be passed as a GDB symbol (such as a register name), a string or a +hexadecimal value ``` gef➤ pattern search 0x6161616161616167 diff --git a/docs/commands/pcustom.md b/docs/commands/pcustom.md index 0694ab4f7..d7d3a4666 100644 --- a/docs/commands/pcustom.md +++ b/docs/commands/pcustom.md @@ -1,8 +1,13 @@ ## Command `pcustom` -`gef` provides a way to create and apply to the currently debugged environment, any new structure (in the C-struct way). On top of simply displaying known and user-defined structures, it also allows to apply those structures to the current context. It intends to mimic the very useful [WinDBG `dt`](https://msdn.microsoft.com/en-us/library/windows/hardware/ff542772(v=vs.85).aspx) command. +`gef` provides a way to create and apply to the currently debugged environment, any new structure +(in the C-struct way). On top of simply displaying known and user-defined structures, it also allows +to apply those structures to the current context. It intends to mimic the very useful [WinDBG +`dt`](https://msdn.microsoft.com/en-us/library/windows/hardware/ff542772(v=vs.85).aspx) command. -This is achieved via the command `pcustom` (for `print custom`), or you can use its alias, `dt` (in reference to the WinDBG command) as provided by the [`WinDbg compatibility extension`](https://github.com/hugsy/gef-extras/blob/main/scripts/windbg.py) +This is achieved via the command `pcustom` (for `print custom`), or you can use its alias, `dt` (in +reference to the WinDBG command) as provided by the [`WinDbg compatibility +extension`](https://github.com/hugsy/gef-extras/blob/main/scripts/windbg.py) ### Configuration @@ -11,7 +16,8 @@ New structures can be stored in the location given by the configuration setting: ``` gef➤ gef config pcustom.struct_path ``` -By default, this location is in `$TEMP/gef/structs` (e.g. `/tmp/user/1000/gef/structs`). The structure can be created as a simple `ctypes` structure, in a file called `.py`. +By default, this location is in `$TEMP/gef/structs` (e.g. `/tmp/user/1000/gef/structs`). The +structure can be created as a simple `ctypes` structure, in a file called `.py`. You can naturally set this path to a new location ``` @@ -36,14 +42,17 @@ gef➤ pcustom list [...] ``` -To create or edit a structure, use `pcustom edit ` to spawn your EDITOR with the targeted structure. If the file does not exist, `gef` will nicely create the tree and file, and fill it with a `ctypes` template that you can use straight away! +To create or edit a structure, use `pcustom edit ` to spawn your EDITOR with the +targeted structure. If the file does not exist, `gef` will nicely create the tree and file, and fill +it with a `ctypes` template that you can use straight away! ``` gef➤ pcustom new mystruct_t [+] Creating '/tmp/gef/structs/mystruct_t.py' from template ``` -If the structure already exists, GEF will open the text editor to edit the known structure. This is equivalent to: +If the structure already exists, GEF will open the text editor to edit the known structure. This is +equivalent to: ``` gef➤ pcustom edit elf32_t @@ -84,7 +93,8 @@ class person_t(Structure): ] ``` -`pcustom` requires at least one argument, which is the name of the structure. With only one argument, `pcustom` will dump all the fields of this structure. +`pcustom` requires at least one argument, which is the name of the structure. With only one +argument, `pcustom` will dump all the fields of this structure. ``` gef➤ dt person_t @@ -93,9 +103,8 @@ gef➤ dt person_t +0104 id c_int /* size=0x4 */ ``` - - -By providing an address or a GDB symbol, `gef` will apply this user-defined structure to the specified address: +By providing an address or a GDB symbol, `gef` will apply this user-defined structure to the +specified address: ![gef-pcustom-with-address](https://i.imgur.com/vWGnu5g.png) @@ -105,19 +114,25 @@ For a full demo, watch the following tutorial: [![yt-gef-pcustom](https://img.youtube.com/vi/pid2aW7Bt_w/0.jpg)](https://www.youtube.com/watch?v=pid2aW7Bt_w) -Additionally, if you have successfully configured your IDA settings, you can also directly import the structure(s) that was(were) reverse-engineered in IDA directly in your GDB session: +Additionally, if you have successfully configured your IDA settings, you can also directly import +the structure(s) that was(were) reverse-engineered in IDA directly in your GDB session: ![ida-structure-examples](https://i.imgur.com/Tnsf6nt.png) - (see `gef-extras/ida-rpyc`, which is the new improved version of `ida-interact`) #### Dynamic `ctypes.Structure`-like classes -`pcustom` also supports the use of class factories to create a `ctypes.Structure` class whose structure will be adjusted based on the runtime information we provide (information about the currently debugged binary, the architecture, the size of a pointer and more). +`pcustom` also supports the use of class factories to create a `ctypes.Structure` class whose +structure will be adjusted based on the runtime information we provide (information about the +currently debugged binary, the architecture, the size of a pointer and more). -The syntax is relatively close to the way we use to create static classes (see above), but instead we define a function that will generate the class. The requirements for this class factory are: - - take a single [`Gef`](https://github.com/hugsy/gef/blob/dev/docs/api/gef.md#class-gef) positional argument - - End the function name with `_t` +The syntax is relatively close to the way we use to create static classes (see above), but instead +we define a function that will generate the class. The requirements for this class factory are: +- take a single [`Gef`](https://github.com/hugsy/gef/blob/dev/docs/api/gef.md#class-gef) positional + argument +- End the function name with `_t` -To continue the `person_t` function we defined in the example above, we could modify the static class as a dynamic one very easily: +To continue the `person_t` function we defined in the example above, we could modify the static +class as a dynamic one very easily: ```python import ctypes @@ -136,7 +151,8 @@ def person_t(gef: Optional["Gef"]=None): return person_cls ``` -Thanks to the `gef` parameter, the structure can be transparently adjusted so that GEF will parse it differently with its runtime information. For example, we can add constraints to the example above: +Thanks to the `gef` parameter, the structure can be transparently adjusted so that GEF will parse it +differently with its runtime information. For example, we can add constraints to the example above: ```python import ctypes @@ -166,7 +182,8 @@ def person_t(gef: Optional["Gef"]==None): ### Public repository of structures -A community contributed repository of structures can be found in [`gef-extras`](https://github.com/hugsy/gef-extras). To deploy it: +A community contributed repository of structures can be found in +[`gef-extras`](https://github.com/hugsy/gef-extras). To deploy it: In bash: ``` @@ -179,7 +196,8 @@ gef➤ gef config pcustom.struct_path /path/to/gef-extras/structs gef➤ gef save ``` -Then either close GDB or `gef reload`. You can confirm the structures were correctly loaded in GEF's prompt: +Then either close GDB or `gef reload`. You can confirm the structures were correctly loaded in GEF's +prompt: ``` gef➤ pcustom list diff --git a/docs/commands/pie.md b/docs/commands/pie.md index 22e232d71..2acb61966 100644 --- a/docs/commands/pie.md +++ b/docs/commands/pie.md @@ -1,21 +1,17 @@ ## Command `pie` ## -The `pie` command is handy when working with position-independent executables. -At runtime, it can automatically resolve addresses for breakpoints that are not -static. +The `pie` command is handy when working with position-independent executables. At runtime, it can +automatically resolve addresses for breakpoints that are not static. -Note that you need to use the **entire `pie` command series** to support PIE -breakpoints, especially the "`pie` run commands", like `pie attach`, `pie run`, -etc. +Note that you need to use the **entire `pie` command series** to support PIE breakpoints, especially +the "`pie` run commands", like `pie attach`, `pie run`, etc. ### `pie breakpoint` command ### -This command sets a new PIE breakpoint. It can be used like the normal -`breakpoint` command in gdb. The argument for the command is the offset from -the base address or a symbol. The breakpoints will not be set immediately after -this command. Instead, it will be set when you use `pie attach`, `pie run` or -`pie remote` to actually attach to a process, so it can resolve the right base -address. +This command sets a new PIE breakpoint. It can be used like the normal `breakpoint` command in gdb. +The argument for the command is the offset from the base address or a symbol. The breakpoints will +not be set immediately after this command. Instead, it will be set when you use `pie attach`, `pie +run` or `pie remote` to actually attach to a process, so it can resolve the right base address. Usage: @@ -25,8 +21,8 @@ gef➤ pie breakpoint OFFSET ### `pie info` command ### -Since a PIE breakpoint is not a real breakpoint, this command provides a way to -observe the state of all PIE breakpoints. +Since a PIE breakpoint is not a real breakpoint, this command provides a way to observe the state of +all PIE breakpoints. This works just like `info breakpoint` in gdb. @@ -36,8 +32,8 @@ VNum Num Addr 1 N/A 0xdeadbeef ``` -VNum stands for virtual number and is used to enumerate the PIE breakpoints. -Num is the number of the associated real breakpoints at runtime in GDB. +VNum stands for virtual number and is used to enumerate the PIE breakpoints. Num is the number of +the associated real breakpoints at runtime in GDB. You can omit the VNum argument to get info on all PIE breakpoints. @@ -60,25 +56,22 @@ gef➤ pie delete [VNum] ### `pie attach` command ### -This command behaves like GDB's `attach` command. Always use this command -instead of `attach` if you have PIE breakpoints. This will convert the PIE -breakpoints to real breakpoints at runtime. +This command behaves like GDB's `attach` command. Always use this command instead of `attach` if you +have PIE breakpoints. This will convert the PIE breakpoints to real breakpoints at runtime. The usage is just the same as `attach`. ### `pie remote` command ### -This command behaves like GDB's `remote` command. Always use this command -instead of `remote` if you have PIE breakpoints. Behind the scenes this will -connect to the remote target using `gef remote` and then convert the PIE -breakpoints to real breakpoints at runtime. +This command behaves like GDB's `remote` command. Always use this command instead of `remote` if you +have PIE breakpoints. Behind the scenes this will connect to the remote target using `gef remote` +and then convert the PIE breakpoints to real breakpoints at runtime. The usage is just the same as `remote`. ### `pie run` command ### -This command behaves like GDB's `run` command. Always use this command instead -of `run` if you have PIE breakpoints. This will convert the PIE breakpoints to -real breakpoints at runtime. +This command behaves like GDB's `run` command. Always use this command instead of `run` if you have +PIE breakpoints. This will convert the PIE breakpoints to real breakpoints at runtime. The usage is just the same as `run`. diff --git a/docs/commands/print-format.md b/docs/commands/print-format.md index de5585b33..1401e3992 100644 --- a/docs/commands/print-format.md +++ b/docs/commands/print-format.md @@ -1,13 +1,14 @@ ## Command `print-format` -The command `print-format` (alias `pf`) will dump an arbitrary location as an array of bytes following the format specified. Currently, the output formats supported are - - - Python (`py` - default) - - C (`c`) - - Assembly (`asm`) - - Javascript (`js`) - - Hex string (`hex`) - - For patch byte command or GDB $_gef[N] byte access (`bytearray`) +The command `print-format` (alias `pf`) will dump an arbitrary location as an array of bytes +following the format specified. Currently, the output formats supported are + +- Python (`py` - default) +- C (`c`) +- Assembly (`asm`) +- Javascript (`js`) +- Hex string (`hex`) +- For patch byte command or GDB $_gef[N] byte access (`bytearray`) ``` diff --git a/docs/commands/process-search.md b/docs/commands/process-search.md index 9f051a22c..62a24e675 100644 --- a/docs/commands/process-search.md +++ b/docs/commands/process-search.md @@ -1,9 +1,8 @@ ## Command `process-search` -`process-search` (aka `ps`) is a convenience command to list and filter process -on the host. It is aimed at making the debugging process a little easier when -targeting forking process (such as tcp/listening daemon that would fork upon -`accept()`). +`process-search` (aka `ps`) is a convenience command to list and filter process on the host. It is +aimed at making the debugging process a little easier when targeting forking process (such as +tcp/listening daemon that would fork upon `accept()`). Without argument, it will return all processes reachable by user: @@ -34,20 +33,19 @@ Note: Use "\\" for escaping and "\\\\" for a literal backslash" in the pattern. `ps` also accepts options: -* `--smart-scan` will filter out probably less relevant processes (belonging to - different users, pattern matched to arguments instead of the commands - themselves, etc.) +* `--smart-scan` will filter out probably less relevant processes (belonging to different users, + pattern matched to arguments instead of the commands themselves, etc.) * `--attach` will automatically attach to the first process found -So, for example, if your targeted process is called `/home/foobar/plop`, but -the existing instance is used through `socat`, like +So, for example, if your targeted process is called `/home/foobar/plop`, but the existing instance +is used through `socat`, like ``` $ socat tcp-l:1234,fork,reuseaddr exec:/home/foobar/plop ``` -Then every time a new connection is opened to tcp/1234, `plop` will be forked, -and GEF can easily attach to it with the command +Then every time a new connection is opened to tcp/1234, `plop` will be forked, and GEF can easily +attach to it with the command ``` gef➤ ps --attach --smart-scan plop diff --git a/docs/commands/process-status.md b/docs/commands/process-status.md index fb14904a6..b024126f3 100644 --- a/docs/commands/process-status.md +++ b/docs/commands/process-status.md @@ -2,9 +2,9 @@ > This command replaces the old commands `pid` and `fd`. -`process-status` provides an exhaustive description of the current running -process, by extending the information provided by GDB `info proc` command, with -all the information from the `procfs` structure. +`process-status` provides an exhaustive description of the current running process, by extending the +information provided by GDB `info proc` command, with all the information from the `procfs` +structure. ``` gef➤ ps --smart-scan zsh diff --git a/docs/commands/registers.md b/docs/commands/registers.md index 31c5f19b0..5c08d37ce 100644 --- a/docs/commands/registers.md +++ b/docs/commands/registers.md @@ -1,7 +1,6 @@ ## Command `registers` -The `registers` command will print all the registers and dereference any -pointers. +The `registers` command will print all the registers and dereference any pointers. Example on a MIPS host: @@ -51,8 +50,8 @@ $gp : 0x00418b20 ### Filtering registers ### -If one or more register names are passed to the `registers` command as optional -arguments, then only those will be shown: +If one or more register names are passed to the `registers` command as optional arguments, then only +those will be shown: ``` gef➤ reg $rax $rip $rsp diff --git a/docs/commands/scan.md b/docs/commands/scan.md index ffa9d0858..ebb744b3e 100644 --- a/docs/commands/scan.md +++ b/docs/commands/scan.md @@ -1,7 +1,7 @@ ## Command `scan` -`scan` searches for addresses of one memory region (needle) inside another -region (haystack) and lists all results. +`scan` searches for addresses of one memory region (needle) inside another region (haystack) and +lists all results. Usage: @@ -9,10 +9,9 @@ Usage: gef➤ scan NEEDLE HAYSTACK ``` -`scan` requires two arguments, the first is the memory section that will be -searched and the second is what will be searched for. The arguments are grepped -against the process's memory mappings (just like [vmmap](./vmmap.md)) to -determine the memory ranges to search. +`scan` requires two arguments, the first is the memory section that will be searched and the second +is what will be searched for. The arguments are grepped against the process's memory mappings (just +like [vmmap](./vmmap.md)) to determine the memory ranges to search. ``` gef➤ scan stack libc @@ -27,8 +26,7 @@ gef➤ scan stack libc ### Advanced Needle/Haystack syntax ### -To check mappings without a path associated, an address range (start-end) can -be used. Note that ranges don't include whitespaces. +To check mappings without a path associated, an address range (start-end) can be used. Note that +ranges don't include whitespaces. ![scan-address](https://i.imgur.com/ExJC2p7.png) - diff --git a/docs/commands/search-pattern.md b/docs/commands/search-pattern.md index beeb981b2..dc5044a82 100644 --- a/docs/commands/search-pattern.md +++ b/docs/commands/search-pattern.md @@ -1,21 +1,18 @@ ## Command `search-pattern` -`gef` allows you to search for a specific pattern at runtime in all the segments -of your process memory layout. The command `search-pattern`, alias `grep`, aims -to be straight-forward to use: +`gef` allows you to search for a specific pattern at runtime in all the segments of your process +memory layout. The command `search-pattern`, alias `grep`, aims to be straight-forward to use: ``` gef➤ search-pattern MyPattern ``` ![grep](https://i.imgur.com/YNzsFvk.png) -It will provide an easily understandable to spot occurrences of the specified -pattern, including the section it/they was/were found, and the permission -associated to that section. +It will provide an easily understandable to spot occurrences of the specified pattern, including the +section it/they was/were found, and the permission associated to that section. -`search-pattern` can also be used to search for addresses. To do so, simply -ensure that your pattern starts with `0x` and is a valid hex address. For -example: +`search-pattern` can also be used to search for addresses. To do so, simply ensure that your pattern +starts with `0x` and is a valid hex address. For example: ``` gef➤ search-pattern 0x4005f6 @@ -23,18 +20,19 @@ gef➤ search-pattern 0x4005f6 ![grep-address](https://i.imgur.com/dg1gUB5.png) -The `search-pattern` command can also be used as a way to search for -cross-references to an address. For this reason, the alias `xref` also points -to the command `search-pattern`. Therefore the command above is equivalent to -`xref 0x4005f6` which makes it more intuitive to use. +The `search-pattern` command can also be used as a way to search for cross-references to an address. +For this reason, the alias `xref` also points to the command `search-pattern`. Therefore the +command above is equivalent to `xref 0x4005f6` which makes it more intuitive to use. ### Searching in a specific range ### -Sometimes, you may need to search for a very common pattern. To limit the search space, you can also specify an address range or the section to be checked. +Sometimes, you may need to search for a very common pattern. To limit the search space, you can also +specify an address range or the section to be checked. ``` gef➤ search-pattern 0x4005f6 little libc gef➤ search-pattern 0x4005f6 little 0x603100-0x603200 ``` + ### Searching in a specific range using regex ### Sometimes, you may need an advanced search using regex. Just use --regex arg. diff --git a/docs/commands/shellcode.md b/docs/commands/shellcode.md index 1310b8188..f2d70b47b 100644 --- a/docs/commands/shellcode.md +++ b/docs/commands/shellcode.md @@ -1,8 +1,8 @@ ## Command `shellcode` -`shellcode` is a command line client for @JonathanSalwan shellcodes database. It -can be used to search and download directly via `GEF` the shellcode you're -looking for. Two primitive subcommands are available, `search` and `get` +`shellcode` is a command line client for @JonathanSalwan shellcodes database. It can be used to +search and download directly via `GEF` the shellcode you're looking for. Two primitive subcommands +are available, `search` and `get` ``` gef➤ shellcode search arm diff --git a/docs/commands/stub.md b/docs/commands/stub.md index cc23fa895..61ab0edb3 100644 --- a/docs/commands/stub.md +++ b/docs/commands/stub.md @@ -1,24 +1,21 @@ ## Command `stub` -The `stub` command allows you stub out functions, optionally specifying the -return value. +The `stub` command allows you stub out functions, optionally specifying the return value. ``` gef➤ stub [-h] [--retval RETVAL] [address] ``` -`address` indicates the address of the function to bypass. If not -specified, `GEF` will consider the instruction at the program counter to be the -start of the function. +`address` indicates the address of the function to bypass. If not specified, `GEF` will consider the +instruction at the program counter to be the start of the function. -If `--retval RETVAL` is provided, `GEF` will set the return value to the -provided value. Otherwise, it will set the return value to 0. +If `--retval RETVAL` is provided, `GEF` will set the return value to the provided value. Otherwise, +it will set the return value to 0. -For example, it is trivial to bypass `fork()` calls. Since the return value is -set to 0, it will in fact drop us into the "child" process. It must be noted -that this is a different behaviour from the classic `set follow-fork-mode -child` since here we do not spawn a new process, we only trick the parent -process into thinking it has become the child. +For example, it is trivial to bypass `fork()` calls. Since the return value is set to 0, it will in +fact drop us into the "child" process. It must be noted that this is a different behaviour from the +classic `set follow-fork-mode child` since here we do not spawn a new process, we only trick the +parent process into thinking it has become the child. ### Example ### diff --git a/docs/commands/theme.md b/docs/commands/theme.md index 22b62e8ec..0e3e19c0e 100644 --- a/docs/commands/theme.md +++ b/docs/commands/theme.md @@ -14,25 +14,25 @@ xinfo_title_message : blue bold ### Changing colors -You have the possibility to change the coloring properties of `GEF` display with -the `theme` command. The command accepts 2 arguments, the name of the property -to update, and its new coloring value. +You have the possibility to change the coloring properties of `GEF` display with the `theme` +command. The command accepts 2 arguments, the name of the property to update, and its new coloring +value. Colors can be one of the following: - - red - - green - - blue - - yellow - - gray - - pink +- red +- green +- blue +- yellow +- gray +- pink Color also accepts the following attributes: - - bold - - underline - - highlight - - blink +- bold +- underline +- highlight +- blink Any other will value simply be ignored. diff --git a/docs/commands/tmux-setup.md b/docs/commands/tmux-setup.md index 7d49fc158..cb9ce55ff 100644 --- a/docs/commands/tmux-setup.md +++ b/docs/commands/tmux-setup.md @@ -1,14 +1,14 @@ ## Command `tmux-setup` -In the purpose of always making debugging sessions easier while being more -effective, `GEF` integrates two commands: +In the purpose of always making debugging sessions easier while being more effective, `GEF` +integrates two commands: * `tmux-setup` * `screen-setup` -Those commands will check whether GDB is being spawn from inside a `tmux` -(resp. `screen`) session, and if so, will split the pane vertically, and -configure the context to be redirected to the new pane, looking something like: +Those commands will check whether GDB is being spawn from inside a `tmux` (resp. `screen`) session, +and if so, will split the pane vertically, and configure the context to be redirected to the new +pane, looking something like: ![](https://i.imgur.com/Khk3xGl.png) @@ -18,15 +18,14 @@ To set it up, simply enter gef➤ tmux-setup ``` -**Note**: Although `screen-setup` provides a similar setup, the structure of -`screen` does not allow a very clean way to do this. Therefore, if possible, it -would be recommended to use the `tmux-setup` command instead. +**Note**: Although `screen-setup` provides a similar setup, the structure of `screen` does not allow +a very clean way to do this. Therefore, if possible, it would be recommended to use the `tmux-setup` +command instead. ### Possible color issues with tmux ### -On Linux tmux only supports 8 colors with some terminal capabilities (`$TERM` -environment variable). This can mess up your color themes when using GEF with -tmux. To remedy this if your terminal supports more colors you can either set -the variable to something like `TERM=screen-256color` or if you don't want or -can't change that variable you can start `tmux` with the `-2` flag to force -tmux to use 256 colors. +On Linux tmux only supports 8 colors with some terminal capabilities (`$TERM` environment variable). +This can mess up your color themes when using GEF with tmux. To remedy this if your terminal +supports more colors you can either set the variable to something like `TERM=screen-256color` or if +you don't want or can't change that variable you can start `tmux` with the `-2` flag to force tmux +to use 256 colors. diff --git a/docs/commands/trace-run.md b/docs/commands/trace-run.md index fe35b48b9..1b30977dd 100644 --- a/docs/commands/trace-run.md +++ b/docs/commands/trace-run.md @@ -1,12 +1,11 @@ ## Command `trace-run` -The `trace-run` command is meant to be provide a visual appreciation directly -in IDA disassembler of the path taken by a specific execution. It should be -used with the IDA script +The `trace-run` command is meant to be provide a visual appreciation directly in IDA disassembler of +the path taken by a specific execution. It should be used with the IDA script [`ida_color_gdb_trace.py`](https://github.com/hugsy/stuff/blob/main/ida_scripts/ida_color_gdb_trace.py) -It will trace and store all values taken by `$pc` during the execution flow, -from its current value, until the value provided as argument. +It will trace and store all values taken by `$pc` during the execution flow, from its current value, +until the value provided as argument. ``` gef> trace-run @@ -14,8 +13,8 @@ gef> trace-run ![trace-run-1](https://i.imgur.com/yaOGste.png) -By using the script `ida_color_gdb_trace.py` on the text file generated, it -will color the path taken: +By using the script `ida_color_gdb_trace.py` on the text file generated, it will color the path +taken: ![trace-run-2](https://i.imgur.com/oAGoSMQ.png) diff --git a/docs/commands/version.md b/docs/commands/version.md index c32ec0667..3739d8a0c 100644 --- a/docs/commands/version.md +++ b/docs/commands/version.md @@ -25,12 +25,11 @@ GDB: 9.2 GDB-Python: 3.8 ``` -The `Blob Hash` can be used to easily find the git commit(s) matching -this file revision. +The `Blob Hash` can be used to easily find the git commit(s) matching this file revision. ``` git log --oneline --find-object ``` -If this command does not return anything then the file was most likely -modified and cannot be matched to a specific git commit. +If this command does not return anything then the file was most likely modified and cannot be +matched to a specific git commit. diff --git a/docs/commands/vmmap.md b/docs/commands/vmmap.md index 84b42a609..76e3bc868 100644 --- a/docs/commands/vmmap.md +++ b/docs/commands/vmmap.md @@ -4,14 +4,13 @@ ![vmmap](https://i.imgur.com/V9zMLUt.png) -Interestingly, it helps finding secret gems: as an aware reader might have -seen, memory mapping differs from one architecture to another (this is one of -the main reasons I started `GEF` in a first place). For example, you can learn -that ELF running on SPARC architectures always have their `.data` and `heap` -sections set as Read/Write/Execute. +Interestingly, it helps finding secret gems: as an aware reader might have seen, memory mapping +differs from one architecture to another (this is one of the main reasons I started `GEF` in a first +place). For example, you can learn that ELF running on SPARC architectures always have their `.data` +and `heap` sections set as Read/Write/Execute. -`vmmap` accepts one argument, either a pattern to match again mapping names, -or an address to determine which section it belongs to. +`vmmap` accepts one argument, either a pattern to match again mapping names, or an address to +determine which section it belongs to. ![vmmap-grep](https://i.imgur.com/ZFF4QVf.png) diff --git a/docs/commands/xfiles.md b/docs/commands/xfiles.md index d1a01fed1..7b0dfe29e 100644 --- a/docs/commands/xfiles.md +++ b/docs/commands/xfiles.md @@ -1,7 +1,7 @@ ## Command `xfiles` -`xfiles` is a more convenient representation of the GDB native command, `info -files` allowing you to filter by pattern given in argument. For example, if you -only want to show the code sections (i.e. `.text`): +`xfiles` is a more convenient representation of the GDB native command, `info files` allowing you to +filter by pattern given in argument. For example, if you only want to show the code sections (i.e. +`.text`): ![xfiles-example](https://i.imgur.com/lelnJ5B.png) diff --git a/docs/commands/xinfo.md b/docs/commands/xinfo.md index af5ba1327..0c31a89dd 100644 --- a/docs/commands/xinfo.md +++ b/docs/commands/xinfo.md @@ -1,14 +1,11 @@ ## Command `xinfo` -`xinfo` displays all the information known to `gef` about the specific address -given as argument: +`xinfo` displays all the information known to `gef` about the specific address given as argument: ![xinfo-example](https://i.imgur.com/x0KTAxz.png) -**Important note** : For performance reasons, `gef` caches certain results. -`gef` will try to automatically refresh its own cache to avoid relying on -obsolete information of the debugged process. However, in some dodgy scenario, -`gef` might fail detecting some new events making its cache partially obsolete. -If you notice an inconsistency on your memory mapping, you might want to force -`gef` flushing its cache and fetching brand new data, by running the command -`reset-cache`. +**Important note** : For performance reasons, `gef` caches certain results. `gef` will try to +automatically refresh its own cache to avoid relying on obsolete information of the debugged +process. However, in some dodgy scenario, `gef` might fail detecting some new events making its +cache partially obsolete. If you notice an inconsistency on your memory mapping, you might want to +force `gef` flushing its cache and fetching brand new data, by running the command `reset-cache`. diff --git a/docs/commands/xor-memory.md b/docs/commands/xor-memory.md index 279d33462..3c252611a 100644 --- a/docs/commands/xor-memory.md +++ b/docs/commands/xor-memory.md @@ -9,7 +9,8 @@ xor-memory
The first argument (`display` or `patch`) is the action to perform: -1. `display` will only show an hexdump of the result of the XOR-ed memory block, without writing the debuggee's memory. +1. `display` will only show an hexdump of the result of the XOR-ed memory block, without writing the + debuggee's memory. gef➤ xor display $rsp 16 1337 [+] Displaying XOR-ing 0x7fff589b67f8-0x7fff589b6808 with '1337' diff --git a/docs/config.md b/docs/config.md index 658f38677..21ee2dcf8 100644 --- a/docs/config.md +++ b/docs/config.md @@ -1,16 +1,23 @@ ## Configuring GEF -GEF comes with its own configuration and customization system, allowing fine tweaking. The configuration file is located under `~/.gef.rc` by default, and is automatically loaded when GEF is loaded by GDB. -If not configuration file is found, GEF will simply use the default settings. +GEF comes with its own configuration and customization system, allowing fine +tweaking. The configuration file is located under `~/.gef.rc` by default, and +is automatically loaded when GEF is loaded by GDB. If not configuration file is +found, GEF will simply use the default settings. -The configuration file is a Python [`configparser`](https://docs.python.org/3/library/configparser.html). To create a basic file with all settings and their default values, simply run +The configuration file is a Python +[`configparser`](https://docs.python.org/3/library/configparser.html). To +create a basic file with all settings and their default values, simply run ```bash gdb -ex 'gef save' -ex quit ``` You can now explore the configuration file under `~/.gef.rc`. -Once in GEF, the configuration settings can be set/unset/modified by the [command `gef config`](/docs/commands/config.md). Without argument the command will simply dump all known settings: + +Once in GEF, the configuration settings can be set/unset/modified by the +[command `gef config`](/docs/commands/config.md). Without argument the command +will simply dump all known settings: ![gef-config](https://i.imgur.com/bd2ZqsU.png) @@ -20,10 +27,12 @@ To update, follow the syntax gef➤ gef config . ``` -Any setting updated this way will be specific to the current GDB session. To make permanent, use the following command +Any setting updated this way will be specific to the current GDB session. To +make permanent, use the following command ``` gef➤ gef save ``` -Refer to the [`gef config` command documentation](/docs/commands/config.md) for complete explanation. +Refer to the `gef config` [command documentation](/docs/commands/config.md) for +complete explanation. diff --git a/docs/deprecated.md b/docs/deprecated.md index dda1fa699..64da93e39 100644 --- a/docs/deprecated.md +++ b/docs/deprecated.md @@ -1,7 +1,8 @@ # Deprecated commands -GEF is in itself a large file, but to avoid it to be out of control some commands once part of GEF were either moved to [GEF-Extras](https://github.com/hugsy/gef-extras) or even simply removed. -This page aims to track those changes. +GEF is in itself a large file, but to avoid it to be out of control some commands once part of GEF +were either moved to [GEF-Extras](https://github.com/hugsy/gef-extras) or even simply removed. This +page aims to track those changes. | Command | Status | Since | Link (if Applicable) | Notes | |--|--|--|--|--| diff --git a/docs/faq.md b/docs/faq.md index e7f623854..b065907cf 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -3,40 +3,58 @@ ## Why use GEF over PEDA? ## -[PEDA](https://github.com/longld/peda) is a fantastic tool that provides similar commands to make the exploitation development process smoother. +[PEDA](https://github.com/longld/peda) is a fantastic tool that provides similar commands to make +the exploitation development process smoother. -However, PEDA suffers from a major drawbacks, which the code is too fundamentally linked to Intel architectures (x86-32 and x86-64). On the other hand, GEF not only supports all the architecture supported by GDB (currently x86, ARM, AARCH64, MIPS, PowerPC, SPARC) but is designed to integrate new architectures very easily as well! +However, PEDA suffers from a major drawbacks, which the code is too fundamentally linked to Intel +architectures (x86-32 and x86-64). On the other hand, GEF not only supports all the architecture +supported by GDB (currently x86, ARM, AARCH64, MIPS, PowerPC, SPARC) but is designed to integrate +new architectures very easily as well! -Also, PEDA development has been quite idle for a few years now, and many new interesting features a debugger can provide simply do not exist. +Also, PEDA development has been quite idle for a few years now, and many new interesting features a +debugger can provide simply do not exist. ## What if my GDB is < 8.0 ? ## -GDB was introduced with its Python support early 2011 with the release of GDB 7. A (very) long way has gone since and the Python API has been massively improved, and GEF is taking advantage of them to provide the coolest features with as little performance impact as possible. +GDB was introduced with its Python support early 2011 with the release of GDB 7. A (very) long way +has gone since and the Python API has been massively improved, and GEF is taking advantage of them +to provide the coolest features with as little performance impact as possible. -Currently, GEF is optimized for running against GDB version 8.0+, and Python 3.6+. This allows for a best performance and best use of the GDB Python API. However, GEF can run on older versions too, check out [the version compatibility matrix](compat.md). For really older versions of GDB, you can use [`gef-legacy`](https://github.com/hugsy/gef-legacy) which supports a lot of older GDB, and a Python 2/3 compatibility layer. +Currently, GEF is optimized for running against GDB version 8.0+, and Python 3.6+. This allows for a +best performance and best use of the GDB Python API. However, GEF can run on older versions too, +check out [the version compatibility matrix](compat.md). For really older versions of GDB, you can +use [`gef-legacy`](https://github.com/hugsy/gef-legacy) which supports a lot of older GDB, and a +Python 2/3 compatibility layer. -Therefore, it is highly recommended to run GEF with the latest version of GDB. However, all functions should work on a GDB 8.0 and up. If not, send a [bug report](https://github.com/hugsy/gef/issues) and provide as much details as possible. +Therefore, it is highly recommended to run GEF with the latest version of GDB. However, all +functions should work on a GDB 8.0 and up. If not, send a [bug +report](https://github.com/hugsy/gef/issues) and provide as much details as possible. If you are running an obsolete version, GEF will show a error and message and exit. -Some pre-compiled static binaries for both recent GDB and GDBServer can be downloaded from the [`gdb-static`](https://github.com/hugsy/gdb-static) repository. +Some pre-compiled static binaries for both recent GDB and GDBServer can be downloaded from the +[`gdb-static`](https://github.com/hugsy/gdb-static) repository. ## I cannot get GEF setup!! ## -GEF will work on any GDB 8+ compiled with Python 3.6+ support. You can view that commands that failed to load using `gef missing`, but this will not affect GEF generally. +GEF will work on any GDB 8+ compiled with Python 3.6+ support. You can view that commands that +failed to load using `gef missing`, but this will not affect GEF generally. -If you experience problems setting it up on your host, first go to the [Discord channel](https://discord.gg/HCS8Hg7) for that. You will find great people there willing to help. +If you experience problems setting it up on your host, first go to the [Discord +channel](https://discord.gg/HCS8Hg7) for that. You will find great people there willing to help. -Note that the GitHub issue section is to be used to **report bugs** and **GEF issues** (like unexpected crash, improper error handling, weird edge case, etc.), not a place to ask for help. +Note that the GitHub issue section is to be used to **report bugs** and **GEF issues** (like +unexpected crash, improper error handling, weird edge case, etc.), not a place to ask for help. -All recent distributions ship packaged GDB that should be ready-to-go, with a GDB >= 8.0 and Python 3.6+. Any version higher or equal will work just fine. So you might actually only need to run `apt install gdb` to get the full-force of GEF. +All recent distributions ship packaged GDB that should be ready-to-go, with a GDB >= 8.0 and Python +3.6+. Any version higher or equal will work just fine. So you might actually only need to run `apt +install gdb` to get the full-force of GEF. ## I get a SegFault when starting GDB with GEF ## -A long standing bug in the `readline` library can make `gef` crash GDB -when displaying certain characters (SOH/ETX). As a result, this would SIGSEGV -GDB as `gef` is loading, a bit like this: +A long standing bug in the `readline` library can make `gef` crash GDB when displaying certain +characters (SOH/ETX). As a result, this would SIGSEGV GDB as `gef` is loading, a bit like this: ``` root@debian-aarch64:~# gdb -q ./test-bin-aarch64 @@ -48,8 +66,8 @@ Reading symbols from ./bof-aarch64...(no debugging symbols found)...done. Segmentation fault (core dumped) ``` -If so, this can be fixed easily by setting the `gef.readline_compat` variable to -`True` in the `~/.gef.rc` file. Something like this: +If so, this can be fixed easily by setting the `gef.readline_compat` variable to `True` in the +`~/.gef.rc` file. Something like this: ``` root@debian-aarch64:~# nano ~/.gef.rc @@ -58,13 +76,14 @@ root@debian-aarch64:~# nano ~/.gef.rc readline_compat = True ``` -You can now use all features of `gef` even on versions of GDB compiled against -old `readline` library. +You can now use all features of `gef` even on versions of GDB compiled against old `readline` +library. ## Does GEF prevent the use of other GDB plugins? ## -Definitely not! You can use any other GDB plugin on top of it for an even better debugging experience. +Definitely not! You can use any other GDB plugin on top of it for an even better debugging +experience. Some interesting plugins highly recommended too: @@ -78,25 +97,22 @@ Src: [@rick2600: terminator + gdb + gef + voltron cc: @snare @_hugsy_](https://t ## I want to contribute, where should I head first? ## -I would suggest thoroughly reading this documentation, just having a look to -the -[CONTRIBUTE](https://github.com/hugsy/gef/blob/main/.github/CONTRIBUTING.md) -file of the project to give you pointers. +I would suggest thoroughly reading this documentation, just having a look to the +[CONTRIBUTE](https://github.com/hugsy/gef/blob/main/.github/CONTRIBUTING.md) file of the project to +give you pointers. -Also a good thing would be to join our [Discord -channel](https://discord.gg/HCS8Hg7) to get in touch with the people -involved/using it. +Also a good thing would be to join our [Discord channel](https://discord.gg/HCS8Hg7) to get in touch +with the people involved/using it. ## I think I've found a bug, how can I help fixing it? ## -`gef` is only getting better through people (like you!) using it, but most -importantly reporting unexpected behavior. +`gef` is only getting better through people (like you!) using it, but most importantly reporting +unexpected behavior. -In most locations, Python exceptions will be properly intercepted. If not, `gef` -wraps all commands with a generic exception handler, to disturb as little as -possible your debugging session. If it happens, you'll only get to see a message -like this: +In most locations, Python exceptions will be properly intercepted. If not, `gef` wraps all commands +with a generic exception handler, to disturb as little as possible your debugging session. If it +happens, you'll only get to see a message like this: ![gef-exception](https://i.imgur.com/J7dUnXV.png) By switching to debug mode, `gef` will give much more information: @@ -106,26 +122,23 @@ gef➤ gef config gef.debug 1 ![gef-debug](https://i.imgur.com/SGe8oFF.png) If you think fixing it is in your skills, then send a [Pull -Request](https://github.com/hugsy/gef/pulls) with your patched version, -explaining your bug, and what was your solution for it. +Request](https://github.com/hugsy/gef/pulls) with your patched version, explaining your bug, and +what was your solution for it. -Otherwise, you can open an [issue](https://github.com/hugsy/gef/issues), give a -thorough description of your bug and copy/paste the content from above. This -will greatly help for solving the issue. +Otherwise, you can open an [issue](https://github.com/hugsy/gef/issues), give a thorough description +of your bug and copy/paste the content from above. This will greatly help for solving the issue. ## I get weird issues/characters using GDB + Python3, what's up? ## Chances are you are not using UTF-8. Python3 is [highly relying on -UTF-8](https://www.diveintopython3.net/strings.html) to display correctly -characters of any alphabet and [also some cool -emojis](https://unicode.org/emoji/charts/full-emoji-list.html). When GDB is -compiled with Python3, GEF will assume that your current charset is UTF-8 (for -instance, `en_US.UTF-8`). Use your `$LANG` environment variable to tweak this -setting. +UTF-8](https://www.diveintopython3.net/strings.html) to display correctly characters of any alphabet +and [also some cool emojis](https://unicode.org/emoji/charts/full-emoji-list.html). When GDB is +compiled with Python3, GEF will assume that your current charset is UTF-8 (for instance, +`en_US.UTF-8`). Use your `$LANG` environment variable to tweak this setting. -In addition, some unexpected results were observed when your local is not set to -English. If you aren't sure, simply run `gdb` like this: +In addition, some unexpected results were observed when your local is not set to English. If you +aren't sure, simply run `gdb` like this: ``` $ LC_ALL=en_US.UTF-8 gdb /path/to/your/binary @@ -133,8 +146,8 @@ $ LC_ALL=en_US.UTF-8 gdb /path/to/your/binary ## GDB crashes on ARM memory corruption with `gdb_exception_RETURN_MASK_ERROR` ## -This issue is **NOT** GEF related, but GDB's, or more precisely some versions of -GDB packaged with Debian/Kali for ARM +This issue is **NOT** GEF related, but GDB's, or more precisely some versions of GDB packaged with +Debian/Kali for ARM > > Original Issue and Mitigation @@ -156,13 +169,12 @@ GDB packaged with Debian/Kali for ARM > version, 8.1 as of this writing. > -**Do not file an issue**, again it is **NOT** a bug from GEF, or neither from GDB -Python API. Therefore, there is nothing GEF's developers can do about that. The -correct solution as mentioned above is to recompile your GDB with a newer -(better) version. +**Do not file an issue**, again it is **NOT** a bug from GEF, or neither from GDB Python API. +Therefore, there is nothing GEF's developers can do about that. The correct solution as mentioned +above is to recompile your GDB with a newer (better) version. -The whole topic was already internally discussed, so please refer to -the [issue #206](https://github.com/hugsy/gef/issues/206) for the whole story. +The whole topic was already internally discussed, so please refer to the [issue +#206](https://github.com/hugsy/gef/issues/206) for the whole story. ## I still don't have my answer... Where can I go? @@ -170,13 +182,19 @@ Discord is your answer: join and talk to us by clicking here [![Discord](https://img.shields.io/badge/Discord-GDB--GEF-yellow)](https://discord.gg/HCS8Hg7) -If you cannot find the answer to your problem here or on the Discord, then go to the project [Issues page](https://github.com/hugsy/gef/issues) and fill up the forms with as much information as you can! +If you cannot find the answer to your problem here or on the Discord, then go to the project [Issues +page](https://github.com/hugsy/gef/issues) and fill up the forms with as much information as you +can! ## How can I use GEF to debug a process in a container? -GEF can attach to a process running in a container using `gdb --pid=$PID`, where `$PID` is the ID of the running process *on the host*. To find this, you can use `docker top -o pid | awk '!/PID/' | xargs -I'{}' pstree -psa {}` to view the process tree for the container. +GEF can attach to a process running in a container using `gdb --pid=$PID`, where `$PID` is the ID of +the running process *on the host*. To find this, you can use `docker top -o pid | awk +'!/PID/' | xargs -I'{}' pstree -psa {}` to view the process tree for the container. -`sudo` may be required to attach to the process, which will depend on your system's security settings. - -Please note that cross-container debugging may have unexpected issues. Installing gdb and GEF inside the container, or using [the official GEF docker image](https://hub.docker.com/r/crazyhugsy/gef) may improve results. +`sudo` may be required to attach to the process, which will depend on your system's security +settings. +Please note that cross-container debugging may have unexpected issues. Installing gdb and GEF inside +the container, or using [the official GEF docker image](https://hub.docker.com/r/crazyhugsy/gef) may +improve results. diff --git a/docs/functions/base.md b/docs/functions/base.md index 897c02c49..ec442adef 100644 --- a/docs/functions/base.md +++ b/docs/functions/base.md @@ -1,6 +1,7 @@ # Function `$_base()` -Return the matching file's base address plus an optional offset. Defaults to current file. Note that quotes need to be escaped. +Return the matching file's base address plus an optional offset. Defaults to current file. Note that +quotes need to be escaped. _Note_: a debugging session must be active @@ -12,4 +13,3 @@ Example: ``` gef➤ p $_base(\"/usr/lib/ld-2.33.so\") ``` - diff --git a/docs/functions/bss.md b/docs/functions/bss.md index edcc37211..055f34d7a 100644 --- a/docs/functions/bss.md +++ b/docs/functions/bss.md @@ -12,4 +12,3 @@ Example: ``` gef➤ p $_bss(0x20) ``` - diff --git a/docs/functions/got.md b/docs/functions/got.md index 494427872..cb2ff95d7 100644 --- a/docs/functions/got.md +++ b/docs/functions/got.md @@ -12,4 +12,3 @@ Example: ``` gef➤ p $_got(0x20) ``` - diff --git a/docs/functions/heap.md b/docs/functions/heap.md index 2bf4394e1..a7ae27269 100644 --- a/docs/functions/heap.md +++ b/docs/functions/heap.md @@ -12,4 +12,3 @@ Example: ``` gef➤ p $_heap(0x20) ``` - diff --git a/docs/functions/stack.md b/docs/functions/stack.md index 56625737b..de825136d 100644 --- a/docs/functions/stack.md +++ b/docs/functions/stack.md @@ -12,5 +12,3 @@ Example: ``` gef➤ p $_stack(0x20) ``` - - diff --git a/docs/index.md b/docs/index.md index fece54116..f063bd161 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,41 +2,51 @@ [![Docs](https://img.shields.io/badge/Documentation-blue.svg)](https://hugsy.github.io/gef/) [![Coverage](https://img.shields.io/badge/Coverage-purple.svg)](https://hugsy.github.io/gef/coverage/) [![MIT](https://img.shields.io/packagist/l/doctrine/orm.svg?maxAge=2592000?style=plastic)](https://github.com/hugsy/gef/blob/main/LICENSE) [![Python 3](https://img.shields.io/badge/Python-3-green.svg)](https://github.com/hugsy/gef/) [![Discord](https://img.shields.io/badge/Discord-GDB--GEF-yellow)](https://discord.gg/HCS8Hg7) -`GEF` (pronounced ʤɛf - "Jeff") is a kick-ass set of commands for X86, ARM, -MIPS, PowerPC and SPARC to make GDB cool again for exploit dev. It is aimed to -be used mostly by exploit developers and reverse-engineers, to provide -additional features to GDB using the Python API to assist during the process of -dynamic analysis and exploit development. +`GEF` (pronounced ʤɛf - "Jeff") is a kick-ass set of commands for X86, ARM, MIPS, PowerPC and SPARC +to make GDB cool again for exploit dev. It is aimed to be used mostly by exploit developers and +reverse-engineers, to provide additional features to GDB using the Python API to assist during the +process of dynamic analysis and exploit development. -It requires Python 3, but [`gef-legacy`](https://github.com/hugsy/gef-legacy) can be used if Python 2 support is needed. +It requires Python 3, but [`gef-legacy`](https://github.com/hugsy/gef-legacy) can be used if Python +2 support is needed. ![gef-context](https://i.imgur.com/E3EuQPs.png) ## GDB Made Easy - * **One** single GDB script - * Entirely **architecture agnostic**, **NO** dependencies: `GEF` is battery-included and [is installable instantly](https://hugsy.github.io/gef/#setup) - * **Fast** limiting the number of dependencies and optimizing code to make the commands as fast as possible - * Provides a great variety of commands to drastically change your debugging experience in GDB. - * [**Easily** extensible](https://hugsy.github.io/gef/api/) to create other commands by providing more comprehensible layout to GDB Python API. - * Full Python3 support ([Python2 support was dropped in 2020.03](https://github.com/hugsy/gef/releases/tag/2020.03)) - check out [`gef-legacy`](https://github.com/hugsy/gef-legacy) for a Python2 compatible version, and [the compatibility matrix](/docs/compat.md) for a complete rundown of version support. - * Built around an architecture abstraction layer, so all commands work in any GDB-supported architecture such as x86-32/64, ARMv5/6/7, AARCH64, SPARC, MIPS, PowerPC, etc. - * Suited for real-life debugging, exploit development, just as much as for CTFs - -Check out the [showroom page](https://hugsy.github.io/gef/screenshots/) for more | or [try it online yourself!](https://demo.gef.blah.cat) (user:`gef`/password:`gef-demo`) +* **One** single GDB script +* Entirely **architecture agnostic**, **NO** dependencies: `GEF` is battery-included and [is + installable instantly](https://hugsy.github.io/gef/#setup) +* **Fast** limiting the number of dependencies and optimizing code to make the commands as fast as + possible +* Provides a great variety of commands to drastically change your debugging experience in GDB. +* [**Easily** extensible](https://hugsy.github.io/gef/api/) to create other commands by providing + more comprehensible layout to GDB Python API. +* Full Python3 support ([Python2 support was dropped in + 2020.03](https://github.com/hugsy/gef/releases/tag/2020.03)) - check out + [`gef-legacy`](https://github.com/hugsy/gef-legacy) for a Python2 compatible version, and [the + compatibility matrix](/docs/compat.md) for a complete rundown of version support. +* Built around an architecture abstraction layer, so all commands work in any GDB-supported + architecture such as x86-32/64, ARMv5/6/7, AARCH64, SPARC, MIPS, PowerPC, etc. +* Suited for real-life debugging, exploit development, just as much as for CTFs + +Check out the [showroom page](https://hugsy.github.io/gef/screenshots/) for more | or [try it online +yourself!](https://demo.gef.blah.cat) (user:`gef`/password:`gef-demo`) ## Quick start ### Automated installation -GEF has no dependencies, is fully battery-included and works out of the box. You can get started with GEF in a matter of seconds, by simply running: +GEF has no dependencies, is fully battery-included and works out of the box. You can get started +with GEF in a matter of seconds, by simply running: ```bash bash -c "$(curl -fsSL https://gef.blah.cat/sh)" ``` -For more details and other ways to install GEF please see [installation page](https://hugsy.github.io/gef/install/). +For more details and other ways to install GEF please see [installation +page](https://hugsy.github.io/gef/install/). ### Run @@ -65,23 +75,30 @@ gef➤ gef-remote -t your.ip.address:1234 -p 666 ## Bugs & Feedbacks ## -To discuss `gef`, `gdb`, exploitation or other topics, feel free to join our [Discord channel](https://discord.gg/HCS8Hg7). +To discuss `gef`, `gdb`, exploitation or other topics, feel free to join our [Discord +channel](https://discord.gg/HCS8Hg7). -For bugs or feature requests, just go [here](https://github.com/hugsy/gef/issues) and provide a thorough description if you want help. +For bugs or feature requests, just go [here](https://github.com/hugsy/gef/issues) and provide a +thorough description if you want help. -_Side Note_: `GEF` fully relies on the GDB API and other Linux-specific sources of information (such as `/proc/`). As a consequence, some of the features might not work on custom or hardened systems such as GrSec. +_Side Note_: `GEF` fully relies on the GDB API and other Linux-specific sources of information (such +as `/proc/`). As a consequence, some of the features might not work on custom or hardened +systems such as GrSec. ## Contribution ## -`gef` was created and maintained by myself, [`@_hugsy_`](https://twitter.com/_hugsy_), but kept fresh thanks to [all the contributors](https://github.com/hugsy/gef/graphs/contributors). +`gef` was created and maintained by myself, [`@_hugsy_`](https://twitter.com/_hugsy_), but kept +fresh thanks to [all the contributors](https://github.com/hugsy/gef/graphs/contributors). [ ![contributors-img](https://contrib.rocks/image?repo=hugsy/gef) ](https://github.com/hugsy/gef/graphs/contributors) -Or if you just like the tool, feel free to drop a simple *"thanks"* on Discord, Twitter or other, it is **always** very appreciated. +Or if you just like the tool, feel free to drop a simple *"thanks"* on Discord, Twitter or other, it +is **always** very appreciated. ## Sponsors ## -We would like to thank in particular the following people who've been sponsoring GEF allowing us to dedicate more time and resources to the project: +We would like to thank in particular the following people who've been sponsoring GEF allowing us to +dedicate more time and resources to the project: [](https://github.com/nkaretnikov) [](https://github.com/r3zk0n) @@ -95,8 +112,7 @@ We would like to thank in particular the following people who've been sponsoring ## Extra Credits - - The GEF logo was designed by [TheZakMan](https://twitter.com/thezakman) +- The GEF logo was designed by [TheZakMan](https://twitter.com/thezakman) ## 🍺 Happy hacking ! - diff --git a/docs/install.md b/docs/install.md index 2eb3c8c35..eac4d8fad 100644 --- a/docs/install.md +++ b/docs/install.md @@ -4,11 +4,15 @@ ### GDB -Only [GDB 8 and higher](https://www.gnu.org/s/gdb) is required. It must be compiled with Python 3.6 or higher support. For most people, simply using your distribution package manager should be enough. +Only [GDB 8 and higher](https://www.gnu.org/s/gdb) is required. It must be compiled with Python 3.6 +or higher support. For most people, simply using your distribution package manager should be enough. -As of January 2020, GEF officially doesn't support Python 2 any longer, due to Python 2 becoming officially deprecated. +As of January 2020, GEF officially doesn't support Python 2 any longer, due to Python 2 becoming +officially deprecated. -GEF will then only work for Python 3. If you absolutely require GDB + Python 2, please use [GEF-Legacy](https://github.com/hugsy/gef-legacy) instead. Note that `gef-legacy` won't provide new features, and only functional bugs will be handled. +GEF will then only work for Python 3. If you absolutely require GDB + Python 2, please use +[GEF-Legacy](https://github.com/hugsy/gef-legacy) instead. Note that `gef-legacy` won't provide new +features, and only functional bugs will be handled. You can verify it with the following command: @@ -28,16 +32,20 @@ $ gdb -nx -ex 'pi print(sys.version)' -ex quit There are **none**: `GEF` works out of the box! -GEF itself provides most (if not all 🤯) features required for typical sessions. However, GEF can be easily extended via - - community-built scripts, functions and architectures in the repo `gef-extras` (see below) - - your own script which can leverage the GEF API for the heavy lifting +GEF itself provides most (if not all 🤯) features required for typical sessions. However, GEF can be +easily extended via +- community-built scripts, functions and architectures in the repo + `gef-extras` (see below) +- your own script which can leverage the GEF API for the heavy lifting ## Standalone ### Quick install -The quickest way to get started with GEF is through the installation script available. Simply make sure you have [GDB 8.0 or higher](https://www.gnu.org/s/gdb), compiled with Python 3.6 or higher, and run +The quickest way to get started with GEF is through the installation script available. Simply make +sure you have [GDB 8.0 or higher](https://www.gnu.org/s/gdb), compiled with Python 3.6 or higher, +and run ```bash bash -c "$(curl -fsSL https://gef.blah.cat/sh)" @@ -55,7 +63,8 @@ $ gdb -q (gdb) pi import urllib.request as u, tempfile as t; g=t.NamedTemporaryFile(suffix='-gef.py'); open(g.name, 'wb+').write(u.urlopen('https://tinyurl.com/gef-main').read()); gdb.execute('source %s' % g.name) ``` -That's it! GEF is installed and correctly set up. You can confirm it by checking the `~/.gdbinit` file and see a line that sources (i.e. loads) GEF. +That's it! GEF is installed and correctly set up. You can confirm it by checking the `~/.gdbinit` +file and see a line that sources (i.e. loads) GEF. ```bash $ cat ~/.gdbinit @@ -65,14 +74,16 @@ source ~/.gdbinit-gef.py ### Update -If your host/VM is connected to the Internet, you can update `gef` easily to the latest version (even without `git` installed). with `python /path/to/gef.py --update` +If your host/VM is connected to the Internet, you can update `gef` easily to the latest version +(even without `git` installed). with `python /path/to/gef.py --update` ```bash $ python ~/.gdbinit-gef.py --update Updated ``` -This will deploy the latest version of `gef`'s _main_ branch from Github. If no updates are available, `gef` will respond `No update` instead. +This will deploy the latest version of `gef`'s _main_ branch from Github. If no +updates are available, `gef` will respond `No update` instead. ## Using git @@ -83,20 +94,24 @@ $ git clone --branch dev https://github.com/hugsy/gef.git $ echo source `pwd`/gef/gef.py >> ~/.gdbinit ``` -GEF is in very active development, so the default branch is `dev`. This is the branch you must use if you intend to submit pull requests. +GEF is in very active development, so the default branch is `dev`. This is the +branch you must use if you intend to submit pull requests. -However if you prefer a more stable life, you can then switch to the `main` branch: +However if you prefer a more stable life, you can then switch to the `main` +branch: ```bash $ git checkout main ``` -The `main` branch gets only updated for new releases, or also when critical fixes occur and need to be patched urgently. - +The `main` branch gets only updated for new releases, or also when critical +fixes occur and need to be patched urgently. ## Community repository: GEF-Extras -GEF was built to also provide a solid base for external scripts. The repository [`gef-extras`](https://github.com/hugsy/gef-extras) is an open repository where anyone can freely submit their own commands to extend GDB via GEF's API. +GEF was built to also provide a solid base for external scripts. The repository +[`gef-extras`](https://github.com/hugsy/gef-extras) is an open repository where +anyone can freely submit their own commands to extend GDB via GEF's API. To benefit from it: ```bash @@ -127,7 +142,8 @@ There, you're now fully equipped epic pwnage with **all** GEF's goodness!! ## Prevent script loading -GDB provides the `-nx` command line flag to disable the commands from the `~/.gdbinit` to be executed. +GDB provides the `-nx` command line flag to disable the commands from the +`~/.gdbinit` to be executed. ```text gdb -nx @@ -135,7 +151,8 @@ gdb -nx ## Disable GEF -To disable GEF without removing it, go to editing `~/.gdbinit`, spot the line that sources GEF, and comment / delete that line: +To disable GEF without removing it, go to editing `~/.gdbinit`, spot the line +that sources GEF, and comment / delete that line: So: @@ -150,7 +167,8 @@ $ cat ~/.gdbinit # source /my/path/to/gef.py ``` -Restart GDB, GEF is gone. Note that you can also load GEF at any moment during your GDB session as such: +Restart GDB, GEF is gone. Note that you can also load GEF at any moment during +your GDB session as such: ```text $ gdb @@ -159,8 +177,10 @@ $ gdb ## Remove GEF -GEF is a one-file GDB script. Therefore, to remove GEF simply spot the location it was installed (for example, by using `~/.gdbinit`) and delete the file. -If a configuration file was created, it will be located as `~/.gef.rc` and can also be deleted: +GEF is a one-file GDB script. Therefore, to remove GEF simply spot the location +it was installed (for example, by using `~/.gdbinit`) and delete the file. If a +configuration file was created, it will be located as `~/.gef.rc` and can also +be deleted: ```text $ cat ~/.gdbinit diff --git a/docs/screenshots.md b/docs/screenshots.md index 981702fb5..fff73a5d3 100644 --- a/docs/screenshots.md +++ b/docs/screenshots.md @@ -6,28 +6,31 @@ This page illustrates a few of the possibilities available to you when using `GE ## Multi-architecture support -`GEF` was designed to support any architecture supported by GDB via an easily extensible architecture API. +`GEF` was designed to support any architecture supported by GDB via an easily +extensible architecture API. Currently `GEF` supports the following architectures: - - Intel x86 (32b & 64b) - - ARM (v6/v7) - - AARCH64 - - MIPS/MIPS64 - - PowerPC - - SPARC/SPARCv9 +- Intel x86 (32b & 64b) +- ARM (v6/v7) +- AARCH64 +- MIPS/MIPS64 +- PowerPC +- SPARC/SPARCv9 ## Features ### Embedded hexdump view -To this day, GDB doesn't come with a hexdump-like view. Well `GEF` fixes that for you via the `hexdump` command: +To this day, GDB doesn't come with a hexdump-like view. Well `GEF` fixes that for you via the +`hexdump` command: ![hexdump](https://i.imgur.com/qt77lFQ.png) ### Dereferencing data or registers -No more endless manual pointer dereferencing `x/x` style. Just use `dereference` for that. Or for a comprehensive view of the registers, `registers` might become your best friend: +No more endless manual pointer dereferencing `x/x` style. Just use `dereference` for that. Or for a +comprehensive view of the registers, `registers` might become your best friend: ![mipsel-deref-regs](https://i.imgur.com/f5ZaWDC.png) diff --git a/docs/testing.md b/docs/testing.md index 29273d2c5..3f21625dd 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -1,7 +1,7 @@ ## Testing GEF -This page describes how GEF testing is done. Any new command/functionality must receive adequate testing to be merged. Also PR failing CI (test + linting) won't be merged either. - +This page describes how GEF testing is done. Any new command/functionality must receive adequate +testing to be merged. Also PR failing CI (test + linting) won't be merged either. ### Prerequisites @@ -13,10 +13,8 @@ python -m pip install -r tests/requirements.txt --user -U is enough to get started. - ### Running tests - #### Basic `pytest` For testing GEF on the architecture on the host running the tests (most cases), simply run @@ -26,13 +24,15 @@ cd /root/of/gef python3 -m pytest -v -k "not benchmark" tests ``` -Note that to ensure compatibility, tests must be executed with the same Python version GDB was compiled against. To obtain this version, you can execute the following command: +Note that to ensure compatibility, tests must be executed with the same Python version GDB was +compiled against. To obtain this version, you can execute the following command: ```bash gdb -q -nx -ex "pi print('.'.join(map(str, sys.version_info[:2])))" -ex quit ``` -At the end, a summary of explanation will be shown, clearly indicating the tests that have failed, for instance: +At the end, a summary of explanation will be shown, clearly indicating the tests that have failed, +for instance: ```text =================================== short test summary info ================================== @@ -47,9 +47,11 @@ You can then use `pytest` directly to help you fix each error specifically. #### Using `pytest` -GEF entirely relies on [`pytest`](https://pytest.org) for its testing. Refer to the project documentation for details. +GEF entirely relies on [`pytest`](https://pytest.org) for its testing. Refer to the project +documentation for details. -Adding a new command __requires__ for extensive testing in a new dedicated test module that should be located in `/root/of/gef/tests/commands/my_new_command.py` +Adding a new command __requires__ for extensive testing in a new dedicated test module that should +be located in `/root/of/gef/tests/commands/my_new_command.py` A skeleton of a test module would look something like: @@ -77,21 +79,25 @@ class MyCommandCommand(GefUnitTestGeneric): self.assertIn("Hello World", res) ``` -When running your test, you can summon `pytest` with the `--pdb` flag to enter the python testing environment to help you get more information about the reason of failure. +When running your test, you can summon `pytest` with the `--pdb` flag to enter the python testing +environment to help you get more information about the reason of failure. -One of the most convenient ways to test `gef` properly is using the `pytest` integration of modern editors such as VisualStudio Code or PyCharm. Without proper tests, new code will not be integrated. +One of the most convenient ways to test `gef` properly is using the `pytest` integration of modern +editors such as VisualStudio Code or PyCharm. Without proper tests, new code will not be integrated. ### Linting GEF -You can use the Makefile at the root of the project to get the proper linting settings. For most cases, the following command is enough: +You can use the Makefile at the root of the project to get the proper linting settings. For most +cases, the following command is enough: ```bash cd /root/of/gef python3 -m pylint --rcfile .pylintrc ``` -Note that to ensure compatibility, tests must be executed with the same Python version GDB was compiled against. To obtain this version, you can execute the following command: +Note that to ensure compatibility, tests must be executed with the same Python version GDB was +compiled against. To obtain this version, you can execute the following command: ```bash gdb -q -nx -ex "pi print('.'.join(map(str, sys.version_info[:2])))" -ex quit