Note

This issue is not in the usual format but more an overview of things to look at that I found when doing a manual functional (and probably not complete) review of GEF.

One thing that was generally observed a lot is especially syntax discrepancies between help messages, error messages and the documentation. Currently all commands can display help messages using the help command but some have an additional -h help. Together with errors messages and the documentation that is 4 different places to update things when a command gets new features or the syntax gets updated in any other way. This should probably be reduced somehow to avoid this from happening.

Also with the new argparse syntax for some commands it might be useful to display additional info messages for these commands for a few releases whenever an error occurs that hint to the syntax change.

Environment used

• OS: Ubuntu 20.04 focal
• Kernel: x86_64 Linux 5.4.0-80-generic

GEF: rev:77889d8d2307ffb1b6077a2dd2dbcf21a75df821 (Git - clean)
SHA1(/vagrant/thegef/gef.py): 4b26a1175abcd8314d4816f97fdf908b3837c779
GDB: 9.2
GDB-Python: 3.8

Observed Results

• kysmaddr
  • command seems to be currently broken: return 0 for each result
• functions
  • docs for $_base() don't match help msg
• pattern
  • add instructions on how to change the pattern length to help msg, -h usage instructions and docs (for search and create)
  • IMO: --period is not a very intuitive flag, especially when not explained. Maybe this could be changed to -n to match pwntools?
  • help msg and -h msg do not match
  • pattern search: more explanation needed for --length argument in this context (why does it actually exist?)
• reset-cache
  • ???
• stub
  • don't show error message when executing stub -h
  • help and -h dont match (ADDRESS vs LOCATION)
  • docs need to be updated to include --retval syntax
  • command currently broken: gdb exiting whenever stub is hit (didn't have time to investigate yet if it is my setup though)
• pcustom
  • Doesn't support -h
  • Doesn't use the parse_arguments decorator.
• aslr:
  • help msg should be aslr [(on|off)] instead of aslr (on|off)) because they are optional
• assemble:
  • docs need to be updated to new syntax (incl. screenshots)
  • help msg needs to be updated to new syntax
  • more of an observation: it would be helpful to be able to list supported architectures and modes so one doesn't have to guess
• capstone-disassemble
  • docs need to be updated to new syntax (incl. screenshots)
  • help msg needs to be updated to new syntax
  • currently resolving of LOCATIONs does not work, only addresses (so e.g. $pc is not accepted)
  • more of an observation: is the new --location flag really needed or should the location remain a positional argument like before?
• elf-info
  • add to docs that it can also run on filepath instead of currently loaded executable
• gef-remote
  • docs need to be updated to new syntax (incl. screenshots) e.g. for --qemu-mode
  • undocumented args (--update-solib, --download-everything, --download-lib, --is-extended-remote) should be documented
• heap-analysis-helper
  • add warning to the top of documentation about is current experimental state (which is BTW currently not working at all for all binaries I tested it on)
• heap
  • heap set-arena subcommand is missing in syntax help message when e.g. just entering heap alone
  • heap chunks is currently not working on (all) x86 binaries (see heap chunks does not work with (all) x86 executables #689)
  • heap chunks is currently not working with LOCATION as the optional arg: throws error
  • heap chunks is currently not even working with ADDRESS as the optional arg: it simply does not print anything even when it should
  • heap bins fast example output in docs is outdated
• help
  • probably I'm a exaggerating a bit on this one: clarify in docs that it is gef help and not help before the screenshot (and maybe update the screenshot)
• hexdump
  • the "default" aliases dq, dd, dw, db aliases described in docs are missing (not sure if that is just for me though?)
  • docs need to be updated to new syntax

• memory
  • docs memory clear has to be updated to memory reset

• name-break

  • command seems to be currently broken: LOCATION (e.g. $pc+1) does not work

• nop

  • help msg needs to be updated to new syntax
  • docs need to be updated to new syntax (-b to --nb)

• patch

  • the "default" aliases eb, ew, ed, eq aliases described in docs are missing (not sure if that is just for me though?)
  • add cmd syntax to docs: patch (byte|word|dword|qword|string) [-h] [LOCATION] [value [value ...]]
  • help msg needs to be updated to new syntax
  • furthermore the command does not seem to work currently

• pie breakpoint

  • clarify in docs that it does not take a LOCATION but an OFFSET as an argument

• process-search

  • docs need to be updated to new syntax (e.g. -a and -s)
  • help message is missing --attach and --smart-scan arguments

• process-status

  • update example in docs from ps -s zsh to ps --smart-scan zsh

• registers

  • filtering by register like described in help msg is not currently possible
  • docs need to be updated from "it does not take any argument" to include the supposed filtering capabilites

• ropper

  • dont show error message when executing ropper --help

• scan

  • more of an observation: the capability of using memory ranges instead of paths is not very prominent in the docs. It would be nice to have clear definitions of NEEDLE and HAYSTACK syntax.

• search-pattern

  • IMO: in help msg the example with small should be changed to little to better match little endian instead of the opposite of big.

• set-permission

  • more of an observation: docs and help messages should include a hint on what PERMISSION should look like (int bitmask with r=1,w=2,x=4)

• tmux-setup

  • color for separating lines and past instructions suddenly changes (to black for me). If this is expected behavior this should be added to the documentation

• unicorn-emulate

  • don't show error message when executing unicorn-emulate -h
  • currently not working with LOCATIONs but only ADDRESSes (therefore examples also can't be reproduced)
  • e.g. emulate 2 currently doesn't emulate 2 instructions but 3.

  I'm not sure if in the documentation LOCATION and ADDRESS are always used the same way. From my understanding of gef LOCATION should be everything from an ADDRESS to e.g. $pc+0x10, *main etc. Maybe these terms should be used more consequently to prevent misunderstandings?

TODO:

• test these commands:
  • trace-run
  • syscall-args