# Command Line Tools

pwntools comes with a handful of useful command-line utilities which serve as wrappers for some of the internal functionality.

If these tools do not appear to be installed, make sure that you have added `~/.local/bin` to your `$PATH` environment variable.

## pwn

Pwntools Command-line Interface

    usage: pwn [-h]
               {asm,checksec,constgrep,cyclic,debug,disasm,disablenx,elfdiff,elfpatch,errno,hex,libcdb,phd,pwnstrip,scramble,shellcraft,template,unhex,update,version}
               ...

-h, --help

  show this help message and exit

### pwn asm

Assemble shellcode into bytes

    usage: pwn asm [-h] [-f {raw,hex,string,elf}] [-o file] [-c context]
                   [-v AVOID] [-n] [-z] [-d] [-e ENCODER] [-i INFILE] [-r]
                   [line ...]

line

  Lines to assemble. If none are supplied, use stdin

-h, --help

  show this help message and exit

-f {raw,hex,string,elf}, --format {raw,hex,string,elf}

  Output format (defaults to hex for ttys, otherwise raw)

-o <file>, --output <file>

  Output file (defaults to stdout)

-c {16,32,64,android,baremetal,cgc,freebsd,linux,windows,powerpc64,aarch64,powerpc,riscv32,riscv64,sparc64,mips64,msp430,alpha,amd64,sparc,thumb,cris,i386,ia64,m68k,mips,s390,none,avr,arm,vax,little,big,be,eb,le,el}, --context {16,32,64,android,baremetal,cgc,freebsd,linux,windows,powerpc64,aarch64,powerpc,riscv32,riscv64,sparc64,mips64,msp430,alpha,amd64,sparc,thumb,cris,i386,ia64,m68k,mips,s390,none,avr,arm,vax,little,big,be,eb,le,el}

  The os/architecture/endianness/bits the shellcode will run in (default: linux/i386), choose from: [‘16’, ‘32’, ‘64’, ‘android’, ‘baremetal’, ‘cgc’, ‘freebsd’, ‘linux’, ‘windows’, ‘powerpc64’, ‘aarch64’, ‘powerpc’, ‘riscv32’, ‘riscv64’, ‘sparc64’, ‘mips64’, ‘msp430’, ‘alpha’, ‘amd64’, ‘sparc’, ‘thumb’, ‘cris’, ‘i386’, ‘ia64’, ‘m68k’, ‘mips’, ‘s390’, ‘none’, ‘avr’, ‘arm’, ‘vax’, ‘little’, ‘big’, ‘be’, ‘eb’, ‘le’, ‘el’]

-v <avoid>, --avoid <avoid>

  Encode the shellcode to avoid the listed bytes (provided as hex)

-n, --newline

  Encode the shellcode to avoid newlines

-z, --zero

  Encode the shellcode to avoid NULL bytes

-d, --debug

  Debug the shellcode with GDB

-e <encoder>, --encoder <encoder>

  Specific encoder to use

-i <infile>, --infile <infile>

  Specify input file

-r, --run

  Run output

### pwn checksec

Check binary security settings

    usage: pwn checksec [-h] [--file [elf ...]] [elf ...]

elf

  Files to check

-h, --help

  show this help message and exit

--file <elf>

  File to check (for compatibility with checksec.sh)

### pwn constgrep

Looking up constants from header files.

Example: constgrep -c freebsd -m ^PROT_ ‘3 + 4’

    usage: pwn constgrep [-h] [-e] [-i] [-m] [-c arch_or_os] regex [constant]

regex

  The regex matching constant you want to find

constant

  The constant to find

-h, --help

  show this help message and exit

-e, --exact

  Do an exact match for a constant instead of searching for a regex

-i, --case-insensitive

  Search case insensitive

-m, --mask-mode

  Instead of searching for a specific constant value, search for values not containing strictly less bits that the given value.

-c {16,32,64,android,baremetal,cgc,freebsd,linux,windows,powerpc64,aarch64,powerpc,riscv32,riscv64,sparc64,mips64,msp430,alpha,amd64,sparc,thumb,cris,i386,ia64,m68k,mips,s390,none,avr,arm,vax,little,big,be,eb,le,el}, --context {16,32,64,android,baremetal,cgc,freebsd,linux,windows,powerpc64,aarch64,powerpc,riscv32,riscv64,sparc64,mips64,msp430,alpha,amd64,sparc,thumb,cris,i386,ia64,m68k,mips,s390,none,avr,arm,vax,little,big,be,eb,le,el}

  The os/architecture/endianness/bits the shellcode will run in (default: linux/i386), choose from: [‘16’, ‘32’, ‘64’, ‘android’, ‘baremetal’, ‘cgc’, ‘freebsd’, ‘linux’, ‘windows’, ‘powerpc64’, ‘aarch64’, ‘powerpc’, ‘riscv32’, ‘riscv64’, ‘sparc64’, ‘mips64’, ‘msp430’, ‘alpha’, ‘amd64’, ‘sparc’, ‘thumb’, ‘cris’, ‘i386’, ‘ia64’, ‘m68k’, ‘mips’, ‘s390’, ‘none’, ‘avr’, ‘arm’, ‘vax’, ‘little’, ‘big’, ‘be’, ‘eb’, ‘le’, ‘el’]

### pwn cyclic

Cyclic pattern creator/finder

    usage: pwn cyclic [-h] [-a alphabet] [-n length] [-c context]
                      [-l lookup_value]
                      [count]

count

  Number of characters to print

-h, --help

  show this help message and exit

-a <alphabet>, --alphabet <alphabet>

  The alphabet to use in the cyclic pattern (defaults to all lower case letters)

-n <length>, --length <length>

  Size of the unique subsequences (defaults to 4).

-c {16,32,64,android,baremetal,cgc,freebsd,linux,windows,powerpc64,aarch64,powerpc,riscv32,riscv64,sparc64,mips64,msp430,alpha,amd64,sparc,thumb,cris,i386,ia64,m68k,mips,s390,none,avr,arm,vax,little,big,be,eb,le,el}, --context {16,32,64,android,baremetal,cgc,freebsd,linux,windows,powerpc64,aarch64,powerpc,riscv32,riscv64,sparc64,mips64,msp430,alpha,amd64,sparc,thumb,cris,i386,ia64,m68k,mips,s390,none,avr,arm,vax,little,big,be,eb,le,el}

  The os/architecture/endianness/bits the shellcode will run in (default: linux/i386), choose from: [‘16’, ‘32’, ‘64’, ‘android’, ‘baremetal’, ‘cgc’, ‘freebsd’, ‘linux’, ‘windows’, ‘powerpc64’, ‘aarch64’, ‘powerpc’, ‘riscv32’, ‘riscv64’, ‘sparc64’, ‘mips64’, ‘msp430’, ‘alpha’, ‘amd64’, ‘sparc’, ‘thumb’, ‘cris’, ‘i386’, ‘ia64’, ‘m68k’, ‘mips’, ‘s390’, ‘none’, ‘avr’, ‘arm’, ‘vax’, ‘little’, ‘big’, ‘be’, ‘eb’, ‘le’, ‘el’]

-l <lookup_value>, -o <lookup_value>, --offset <lookup_value>, --lookup <lookup_value>

  Do a lookup instead printing the alphabet

### pwn debug

Debug a binary in GDB

    usage: pwn debug [-h] [-x GDBSCRIPT] [--pid PID] [-c context]
                     [--exec EXECUTABLE] [--process PROCESS_NAME]
                     [--sysroot SYSROOT]

-h, --help

  show this help message and exit

-x <gdbscript>

  Execute GDB commands from this file.

--pid <pid>

  PID to attach to

-c {16,32,64,android,baremetal,cgc,freebsd,linux,windows,powerpc64,aarch64,powerpc,riscv32,riscv64,sparc64,mips64,msp430,alpha,amd64,sparc,thumb,cris,i386,ia64,m68k,mips,s390,none,avr,arm,vax,little,big,be,eb,le,el}, --context {16,32,64,android,baremetal,cgc,freebsd,linux,windows,powerpc64,aarch64,powerpc,riscv32,riscv64,sparc64,mips64,msp430,alpha,amd64,sparc,thumb,cris,i386,ia64,m68k,mips,s390,none,avr,arm,vax,little,big,be,eb,le,el}

  The os/architecture/endianness/bits the shellcode will run in (default: linux/i386), choose from: [‘16’, ‘32’, ‘64’, ‘android’, ‘baremetal’, ‘cgc’, ‘freebsd’, ‘linux’, ‘windows’, ‘powerpc64’, ‘aarch64’, ‘powerpc’, ‘riscv32’, ‘riscv64’, ‘sparc64’, ‘mips64’, ‘msp430’, ‘alpha’, ‘amd64’, ‘sparc’, ‘thumb’, ‘cris’, ‘i386’, ‘ia64’, ‘m68k’, ‘mips’, ‘s390’, ‘none’, ‘avr’, ‘arm’, ‘vax’, ‘little’, ‘big’, ‘be’, ‘eb’, ‘le’, ‘el’]

--exec <executable>

  File to debug

--process <process_name>

  Name of the process to attach to (e.g. “bash”)

--sysroot <sysroot>

  GDB sysroot path

### pwn disablenx

Disable NX for an ELF binary

    usage: pwn disablenx [-h] elf [elf ...]

elf

  Files to check

-h, --help

  show this help message and exit

### pwn disasm

Disassemble bytes into text format

    usage: pwn disasm [-h] [-c arch_or_os] [-a address] [--color] [--no-color]
                      [hex ...]

hex

  Hex-string to disassemble. If none are supplied, then it uses stdin in non-hex mode.

-h, --help

  show this help message and exit

-c {16,32,64,android,baremetal,cgc,freebsd,linux,windows,powerpc64,aarch64,powerpc,riscv32,riscv64,sparc64,mips64,msp430,alpha,amd64,sparc,thumb,cris,i386,ia64,m68k,mips,s390,none,avr,arm,vax,little,big,be,eb,le,el}, --context {16,32,64,android,baremetal,cgc,freebsd,linux,windows,powerpc64,aarch64,powerpc,riscv32,riscv64,sparc64,mips64,msp430,alpha,amd64,sparc,thumb,cris,i386,ia64,m68k,mips,s390,none,avr,arm,vax,little,big,be,eb,le,el}

  The os/architecture/endianness/bits the shellcode will run in (default: linux/i386), choose from: [‘16’, ‘32’, ‘64’, ‘android’, ‘baremetal’, ‘cgc’, ‘freebsd’, ‘linux’, ‘windows’, ‘powerpc64’, ‘aarch64’, ‘powerpc’, ‘riscv32’, ‘riscv64’, ‘sparc64’, ‘mips64’, ‘msp430’, ‘alpha’, ‘amd64’, ‘sparc’, ‘thumb’, ‘cris’, ‘i386’, ‘ia64’, ‘m68k’, ‘mips’, ‘s390’, ‘none’, ‘avr’, ‘arm’, ‘vax’, ‘little’, ‘big’, ‘be’, ‘eb’, ‘le’, ‘el’]

-a <address>, --address <address>

  Base address

--color

  Color output

--no-color

  Disable color output

### pwn elfdiff

Compare two ELF files

    usage: pwn elfdiff [-h] a b

a

b

-h, --help

  show this help message and exit

### pwn elfpatch

Patch an ELF file

    usage: pwn elfpatch [-h] elf offset bytes

elf

  File to patch

offset

  Offset to patch in virtual address (hex encoded)

bytes

  Bytes to patch (hex encoded)

-h, --help

  show this help message and exit

### pwn errno

Prints out error messages

    usage: pwn errno [-h] error

error

  Error message or value

-h, --help

  show this help message and exit

### pwn hex

Hex-encodes data provided on the command line or stdin

    usage: pwn hex [-h] [-p prefix] [-s separator] [data ...]

data

  Data to convert into hex

-h, --help

  show this help message and exit

-p <prefix>, --prefix <prefix>

  Insert a prefix before each byte

-s <separator>, --separator <separator>

  Add a separator between each byte

### pwn libcdb

Print various information about a libc binary

    usage: pwn libcdb [-h] {lookup,hash,file} ...

-h, --help

  show this help message and exit

### pwn libcdb file

Dump information about a libc binary

    usage: pwn libcdb file [-h] [-s [symbols ...]] [-o offset] [--unstrip]
                           files [files ...]

files

  Libc binary to dump

-h, --help

  show this help message and exit

-s <symbols>, --symbols <symbols>

  List of symbol offsets to dump in addition to the common ones

-o <offset>, --offset <offset>

  Display all offsets relative to this symbol

--unstrip

  Attempt to unstrip the libc binary inplace with debug symbols from a debuginfod server

### pwn libcdb hash

Display information of a libc version given an unique hash

    usage: pwn libcdb hash [-h] [-t [{id,buildid,md5,sha1,sha256}]]
                           [--download-libc] [--unstrip] [--no-unstrip]
                           hash_value [hash_value ...]

hash_value

  Hex encoded hash value

-h, --help

  show this help message and exit

-t {id,buildid,md5,sha1,sha256}, --hash_type {id,buildid,md5,sha1,sha256}

  The type of the provided hash value. Supported hashtypes: id, buildid, md5, sha1, sha256

--download-libc

  Attempt to download the matching libc.so

--unstrip

  Attempt to unstrip the libc binary with debug symbols from a debuginfod server

--no-unstrip

  Do NOT attempt to unstrip the libc binary with debug symbols from a debuginfod server

### pwn libcdb lookup

Lookup a libc version by function offsets

    usage: pwn libcdb lookup [-h] [--download-libc] [--unstrip] [--no-unstrip]
                             symbol_offset_pairs [symbol_offset_pairs ...]

symbol_offset_pairs

  Symbol and offset pairs to lookup matching libc version. Can be any number of pairs to narrow the search. Example: “read 3e0 write 520”

-h, --help

  show this help message and exit

--download-libc

  Attempt to download the matching libc.so

--unstrip

  Attempt to unstrip the libc binary with debug symbols from a debuginfod server

--no-unstrip

  Do NOT attempt to unstrip the libc binary with debug symbols from a debuginfod server

### pwn phd

Pretty hex dump

    usage: pwn phd [-h] [-w WIDTH] [-l [HIGHLIGHT ...]] [-s SKIP] [-c COUNT]
                   [-o OFFSET] [--color [{always,never,auto}]]
                   [file]

file

  File to hexdump. Reads from stdin if missing.

-h, --help

  show this help message and exit

-w <width>, --width <width>

  Number of bytes per line.

-l <highlight>, --highlight <highlight>

  Byte to highlight.

-s <skip>, --skip <skip>

  Skip this many initial bytes.

-c <count>, --count <count>

  Only show this many bytes.

-o <offset>, --offset <offset>

  Addresses in left hand column starts at this address.

--color {always,never,auto}

  Colorize the output. When ‘auto’ output is colorized exactly when stdout is a TTY. Default is ‘auto’.

### pwn pwnstrip

Strip binaries for CTF usage

    usage: pwn pwnstrip [-h] [-b] [-p FUNCTION] [-o OUTPUT] file

file

-h, --help

  show this help message and exit

-b, --build-id

  Strip build ID

-p <function>, --patch <function>

  Patch function

-o <output>, --output <output>

### pwn scramble

Shellcode encoder

    usage: pwn scramble [-h] [-f {raw,hex,string,elf}] [-o file] [-c context] [-p]
                        [-v AVOID] [-n] [-z] [-d]

-h, --help

  show this help message and exit

-f {raw,hex,string,elf}, --format {raw,hex,string,elf}

  Output format (defaults to hex for ttys, otherwise raw)

-o <file>, --output <file>

  Output file (defaults to stdout)

-c {16,32,64,android,baremetal,cgc,freebsd,linux,windows,powerpc64,aarch64,powerpc,riscv32,riscv64,sparc64,mips64,msp430,alpha,amd64,sparc,thumb,cris,i386,ia64,m68k,mips,s390,none,avr,arm,vax,little,big,be,eb,le,el}, --context {16,32,64,android,baremetal,cgc,freebsd,linux,windows,powerpc64,aarch64,powerpc,riscv32,riscv64,sparc64,mips64,msp430,alpha,amd64,sparc,thumb,cris,i386,ia64,m68k,mips,s390,none,avr,arm,vax,little,big,be,eb,le,el}

  The os/architecture/endianness/bits the shellcode will run in (default: linux/i386), choose from: [‘16’, ‘32’, ‘64’, ‘android’, ‘baremetal’, ‘cgc’, ‘freebsd’, ‘linux’, ‘windows’, ‘powerpc64’, ‘aarch64’, ‘powerpc’, ‘riscv32’, ‘riscv64’, ‘sparc64’, ‘mips64’, ‘msp430’, ‘alpha’, ‘amd64’, ‘sparc’, ‘thumb’, ‘cris’, ‘i386’, ‘ia64’, ‘m68k’, ‘mips’, ‘s390’, ‘none’, ‘avr’, ‘arm’, ‘vax’, ‘little’, ‘big’, ‘be’, ‘eb’, ‘le’, ‘el’]

-p, --alphanumeric

  Encode the shellcode with an alphanumeric encoder

-v <avoid>, --avoid <avoid>

  Encode the shellcode to avoid the listed bytes

-n, --newline

  Encode the shellcode to avoid newlines

-z, --zero

  Encode the shellcode to avoid NULL bytes

-d, --debug

  Debug the shellcode with GDB

### pwn shellcraft

Microwave shellcode – Easy, fast and delicious

    usage: pwn shellcraft [-h] [-?] [-o file] [-f format] [-d] [-b] [-a]
                          [-v AVOID] [-n] [-z] [-r] [--color] [--no-color]
                          [--syscalls] [--address ADDRESS] [-l] [-s]
                          [shellcode] [arg ...]

shellcode

  The shellcode you want

arg

  Argument to the chosen shellcode

-h, --help

  show this help message and exit

-?, --show

  Show shellcode documentation

-o <file>, --out <file>

  Output file (default: stdout)

-f {r,raw,s,str,string,c,h,hex,a,asm,assembly,p,i,hexii,e,elf,d,escaped,default}, --format {r,raw,s,str,string,c,h,hex,a,asm,assembly,p,i,hexii,e,elf,d,escaped,default}

  Output format (default: hex), choose from {e}lf, {r}aw, {s}tring, {c}-style array, {h}ex string, hex{i}i, {a}ssembly code, {p}reprocssed code, escape{d} hex string

-d, --debug

  Debug the shellcode with GDB

-b, --before

  Insert a debug trap before the code

-a, --after

  Insert a debug trap after the code

-v <avoid>, --avoid <avoid>

  Encode the shellcode to avoid the listed bytes

-n, --newline

  Encode the shellcode to avoid newlines

-z, --zero

  Encode the shellcode to avoid NULL bytes

-r, --run

  Run output

--color

  Color output

--no-color

  Disable color output

--syscalls

  List syscalls

--address <address>

  Load address

-l, --list

  List available shellcodes, optionally provide a filter

-s, --shared

  Generated ELF is a shared library

### pwn template

Generate an exploit template

    usage: pwn template [-h] [--host HOST] [--port PORT] [--user USER]
                        [--pass PASSWORD] [--libc LIBC] [--path PATH] [--quiet]
                        [--color {never,always,auto}] [--template TEMPLATE]
                        [exe]

exe

  Target binary

-h, --help

  show this help message and exit

--host <host>

  Remote host / SSH server

--port <port>

  Remote port / SSH port

--user <user>

  SSH Username

--pass <password>, --password <password>

  SSH Password

--libc <libc>

  Path to libc binary to use

--path <path>

  Remote path of file on SSH server

--quiet

  Less verbose template comments

--color {never,always,auto}

  Print the output in color

--template <template>

  Path to a custom template. Tries to use ‘~/.config/pwntools/templates/pwnup.mako’, if it exists. Check ‘pwnlib/data/templates/pwnup.mako’ for the default template shipped with pwntools.

### pwn unhex

Decodes hex-encoded data provided on the command line or via stdin.

    usage: pwn unhex [-h] [hex ...]

hex

  Hex bytes to decode

-h, --help

  show this help message and exit

### pwn update

Check for pwntools updates

    usage: pwn update [-h] [--install] [--pre]

-h, --help

  show this help message and exit

--install

  Install the update automatically.

--pre

  Check for pre-releases.

### pwn version

Pwntools version

    usage: pwn version [-h]

-h, --help

  show this help message and exit