# 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,baremetal,freebsd,windows,android,darwin,linux,cgc,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,baremetal,freebsd,windows,android,darwin,linux,cgc,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’, ‘baremetal’, ‘freebsd’, ‘windows’, ‘android’, ‘darwin’, ‘linux’, ‘cgc’, ‘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,baremetal,freebsd,windows,android,darwin,linux,cgc,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,baremetal,freebsd,windows,android,darwin,linux,cgc,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’, ‘baremetal’, ‘freebsd’, ‘windows’, ‘android’, ‘darwin’, ‘linux’, ‘cgc’, ‘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,baremetal,freebsd,windows,android,darwin,linux,cgc,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,baremetal,freebsd,windows,android,darwin,linux,cgc,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’, ‘baremetal’, ‘freebsd’, ‘windows’, ‘android’, ‘darwin’, ‘linux’, ‘cgc’, ‘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,baremetal,freebsd,windows,android,darwin,linux,cgc,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,baremetal,freebsd,windows,android,darwin,linux,cgc,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’, ‘baremetal’, ‘freebsd’, ‘windows’, ‘android’, ‘darwin’, ‘linux’, ‘cgc’, ‘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,baremetal,freebsd,windows,android,darwin,linux,cgc,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,baremetal,freebsd,windows,android,darwin,linux,cgc,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’, ‘baremetal’, ‘freebsd’, ‘windows’, ‘android’, ‘darwin’, ‘linux’, ‘cgc’, ‘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,baremetal,freebsd,windows,android,darwin,linux,cgc,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,baremetal,freebsd,windows,android,darwin,linux,cgc,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’, ‘baremetal’, ‘freebsd’, ‘windows’, ‘android’, ‘darwin’, ‘linux’, ‘cgc’, ‘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] [--delim DELIM]
                          [-b] [-a] [-v AVOID] [-n] [-z] [-r] [--color]
                          [--no-color] [--syscalls] [--address ADDRESS] [-l] [-s]
                          [shellcode ...]

shellcode

  The shellcodes you want. shellcode [args …] [+ shellcode [args …]]

-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

--delim <delim>

  Set the delimiter between multilple shellcodes

-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. If no arguments are given, the current directory is searched for an executable binary and libc. If only one binary is found, it is assumed to be the challenge binary.

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

exe

  Target binary. If not given, the current directory is searched for an executable 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. If not given, the current directory is searched for a libc binary.

--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.

--no-auto

  Do not automatically detect missing binaries

### 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