Release 3.13.0

Merge branch 'stable' into beta
Reduce cache filename length on rop.py (fix #1180 ) (#1204 )
2026-11-08 08:06:05 -10:00 · 2019-11-05 18:39:55 +01:00 · 2019-11-05 10:40:48 +01:00 · 2019-11-04 17:11:16 +01:00 · 2019-10-30 15:49:06 +01:00 · 2019-10-30 15:46:22 +01:00
1012 changed files with 105211 additions and 14743 deletions
@@ -0,0 +1,8 @@
+[run]
+branch = True
+omit =
+    */constants/*
+source =
+    pwn
+    pwnlib
+    ~/.pwntools-cache/
@@ -0,0 +1,14 @@
+# Pwntools Issue Template
+
+Thanks for contributing to Pwntools!
+
+When reporting an issue, be sure that you are running the latest released version of pwntools (`pip install --upgrade pwntools`).
+
+Please verify that your issue occurs on 64-bit Ubuntu 14.04.  You can use the Dockerfile on `docker.io` for quick testing.
+
+```
+$ docker pull pwntools/pwntools:stable
+$ docker run -it pwntools/pwntools:stable
+```
+
+If possible, provide a proof-of-concept which demonstrates the problem.  Include any binaries or scripts necessary to reproduce the issue, and please include the full debug output via setting the environment variable `PWNLIB_DEBUG=1`.
@@ -0,0 +1,27 @@
+# Pwntools Pull Request
+
+Thanks for contributing to Pwntools!  Take a moment to look at [`CONTRIBUTING.md`][contributing] to make sure you're familiar with Pwntools development.
+
+Please provide a high-level explanation of what this pull request is for.
+
+## Testing
+
+Pull Requests that introduce new code should try to add doctests for that code.  See [`TESTING.md`][testing] for more information.
+
+## Target Branch
+
+Depending on what the PR is for, it needs to target a different branch.
+
+You can always [change the branch][change] after you create the PR if it's against the wrong branch.
+
+| Branch   | Type of PR                                                       |
+| -------- | ---------------------------------------------------------------- |
+| `dev`    | New features, and enhancements
+| `dev`    | Documentation fixes and new tests
+| `stable` | Bug fixes that affect the current `stable` branch
+| `beta`   | Bug fixes that affect the current `beta` branch, but not `stable`
+| `dev`    | Bug fixes for code that has never been released
+
+[contributing]: https://github.com/Gallopsled/pwntools/blob/dev/CONTRIBUTING.md
+[testing]: https://github.com/Gallopsled/pwntools/blob/dev/TESTING.md
+[change]: https://github.com/blog/2224-change-the-base-branch-of-a-pull-request
@@ -2,6 +2,8 @@
 *.hi
 *.pyc
 *~
+*.swp
+.ropeproject
 *.pdf
 */auto/*
 */bin/*
@@ -9,4 +11,7 @@ docs/build
 build
 MANIFEST
 dist
-pwntools.egg-info
+*.egg-info
+*.core
+.coverage
+.tox
@@ -0,0 +1,4 @@
+[settings]
+indent='    '
+not_skip = __init__.py
+force_single_line = 1
@@ -0,0 +1,7 @@
+{
+    "default_encoding": "UTF-8",
+    "ensure_newline_at_eof_on_save": true,
+    "tab_size": 4,
+    "translate_tabs_to_spaces": true,
+    "trim_trailing_white_space_on_save": true
+}
@@ -1,15 +1,52 @@
+dist: xenial
 language: python
+addons:
+  apt:
+    packages:
+    - gcc-multilib
+    - lib32stdc++6
+    - ash
+    - bash
+    - dash
+    - ksh
+    - mksh
+    - zsh
+    - pandoc
+    - gdb
+    - binutils
+    - qemu-user-static
+    - binutils-multiarch
+    - binutils-aarch64-linux-gnu
+    - binutils-arm-linux-gnueabihf
+    - binutils-mips-linux-gnu
+    - binutils-powerpc-linux-gnu
+cache:
+    - pip
+    - directories:
+        - usr
+        - /home/travis/virtualenv/python2.7.15/lib/python2.7/site-packages/
+        - /home/travis/virtualenv/python2.7.15/bin/
+sudo: required
 python:
-  - "2.7"
-branches:
-  only:
-    - master
+  - "2.7.15"
+before_install:
+  - echo $-
+  - source travis/install.sh
+  - source travis/ssh_setup.sh
+  - echo $-
 install:
-  - source .travis_install.sh
-  - source .travis_ssh_setup.sh
-  - python -c 'from pwn import *; print pwnlib.term.term_mode' NOTERM
-  - python -c 'from pwn import *; print pwnlib.term.term_mode' NOTERM
-  - python -c 'from pwn import *; print pwnlib.term.term_mode' NOTERM
-  - python -c 'from pwn import *; print pwnlib.term.term_mode' NOTERM
-
-script: make -C docs doctest
+  - pip install --upgrade pip
+  - pip install --upgrade appdirs # https://github.com/ActiveState/appdirs/issues/89#issuecomment-282326570
+  - python setup.py egg_info      # pypa/pip#6275
+  - pip install --upgrade --editable .
+  - pip install --upgrade --requirement docs/requirements.txt
+before_script:
+  - PWNLIB_NOTERM=1 python -c 'from pwn import *; print pwnlib.term.term_mode'
+  - PWNLIB_NOTERM=1 python -c 'from pwn import *; print pwnlib.term.term_mode'
+  - PWNLIB_NOTERM=1 python -c 'from pwn import *; print pwnlib.term.term_mode'
+  - PWNLIB_NOTERM=1 python -c 'from pwn import *; print pwnlib.term.term_mode'
+script:
+  - PWNLIB_NOTERM=1 coverage run -m sphinx -b doctest docs/source docs/build/doctest
+after_success:
+  - coveralls
+  - source travis/update_demo.sh
@@ -1,29 +0,0 @@
-#!/usr/bin/env bash
-
-setup_linux()
-{
-    sudo apt-get update
-    sudo apt-get install software-properties-common pwgen
-    sudo apt-add-repository --yes ppa:pwntools/binutils
-    sudo apt-get update
-    sudo apt-get install binutils-arm-linux-gnu binutils-mips-linux-gnu binutils-powerpc-linux-gnu
-    wget -nc http://www.capstone-engine.org/download/2.1.2/capstone-2.1.2_amd64.deb
-    (echo "a30bcb58fd82d32b135eec978eaa22230c44e722 *capstone-2.1.2_amd64.deb" | sha1sum -c) || exit
-    sudo dpkg -i *.deb
-}
-
-setup_osx()
-{
-    brew update
-    brew install binutils
-    brew install capstone
-}
-
-case $(uname) in
-Darwin) setup_osx   ;;
-Linux)  setup_linux ;;
-esac
-
-pip install -r requirements.txt
-pip install -r docs/requirements.txt
-pip install .
@@ -1,18 +0,0 @@
-#!/usr/bin/env bash
-#
-# Install a demo user for SSH purposes
-#
-U=demouser
-H=/home/$U
-
-sudo useradd -m $U
-ssh-keygen -t rsa -f /tmp/$U -N ''
-
-eval $(ssh-agent -s)
-ssh-add    /tmp/$U
-
-sudo -u $U mkdir $H/.ssh
-sudo -u $U cp    /tmp/$U.pub $H/.ssh/authorized_keys
-sudo chmod -R 700 $H
-
-(echo -n "$U:"; pwgen 100 1) | sudo chpasswd
@@ -3,7 +3,626 @@
 This changelog only includes added major features and changes. Bugfixes and
 minor changes are omitted.

-## 2.2.0 - 2014-08-28 (pre)
+## Release History
+
+The table below shows which release corresponds to each branch, and what date the version was released.
+
+| Version          | Branch   | Release Date           |
+| ---------------- | -------- | ---------------------- |
+| [4.1.0](#410)    | `dev`    | Jan 20, 2020 (planned)
+| [4.0.0](#400)    | `beta`   | Dec 20, 2019 (planned)
+| [3.13.0](#3130)  | `stable` | Nov 5, 2019
+| [3.12.0](#3120)  |          | Feb 22, 2018
+| [3.11.0](#3110)  |          | Jan 3, 2018
+| [3.10.0](#3100)  |          | Oct 25, 2017
+| [3.9.2](#392)    |          | Oct 5, 2017
+| [3.9.1](#391)    |          | Sep 28, 2017
+| [3.9.0](#390)    |          | Sep 11, 2017
+| [3.8.0](#380)    |          | Jul 29, 2017
+| [3.7.1](#371)    |          | Jul 14, 2017
+| [3.7.0](#370)    |          | Jun 19, 2017
+| [3.6.1](#361)    |          | May 12, 2017
+| [3.6.0](#360)    |          | May 8, 2017
+| [3.5.1](#351)    |          | Apr 15, 2017
+| [3.5.0](#350)    |          | Mar 26, 2017
+| [3.4.1](#341)    |          | Feb 17, 2017
+| [3.4.0](#340)    |          | Feb 13, 2017
+| [3.3.4](#334)    |          | Jan 12, 2016
+| [3.3.3](#333)    |          | Jan 10, 2016
+| [3.3.2](#332)    |          | Jan 10, 2016
+| [3.3.1](#331)    |          | Jan 10, 2016
+| [3.3.0](#330)    |          | Dec 24, 2016
+| [3.2.1](#321)    |          | Dec 24, 2016
+| [3.2.0](#320)    |          | Nov 12, 2016
+| [3.1.1](#311)    |          | Oct 23, 2016
+| [3.1.0](#310)    |          | Oct 2, 2016
+| [3.0.4](#304)    |          | Sept 19, 2016
+| [3.0.3](#303)    |          | Sept 18, 2016
+| [3.0.2](#302)    |          | Sept 6, 2016
+| [3.0.1](#301)    |          | Aug 20, 2016
+| [3.0.0](#300)    |          | Aug 20, 2016
+| [2.2.0](#220)    |          | Jan 5, 2015
+
+## 4.1.0
+
+To be released on Jan 20, 2020.
+
+## 4.0.0
+
+To be released on Dec 20, 2019.
+
+- **Python 3 support! <3**
+- [#1317][1317] Tubes with `context.encoding`
+- [#1216][1216] Improve format string generator
+- [#1285][1285] Add freebsd generic syscall templates
+- [76413f][76413f] Add pwnlib.adb.bootimg for 'ANDROID!' format boot.img images
+- [#1202][1202] Docker: Kill 14 layers in pwntools base images
+- [#1182][1182] shellcraft.dupio() for mips
+
+[1317]: https://github.com/Gallopsled/pwntools/pulls/1317
+[1285]: https://github.com/Gallopsled/pwntools/pulls/1285
+[1216]: https://github.com/Gallopsled/pwntools/pulls/1216
+[1202]: https://github.com/Gallopsled/pwntools/pulls/1202
+[1182]: https://github.com/Gallopsled/pwntools/pulls/1182
+[76413f]: https://github.com/Gallopsled/pwntools/commit/76413f
+
+## 3.13.0
+
+- [#1204][1204] Reduce ROP cache filename length
+- [#1175][1175] Fix nested SSH connectors
+- [#1355][1355] Fix 'break' syscall
+- [#1277][1277] Fix timeout parameter passing in sendlineafter and other similar functions
+- [#1292][1292] Provide correct arch name to gdb for sparc64
+
+[1175]: https://github.com/Gallopsled/pwntools/pulls/1175
+[1204]: https://github.com/Gallopsled/pwntools/pulls/1355
+[1277]: https://github.com/Gallopsled/pwntools/pulls/1277
+[1292]: https://github.com/Gallopsled/pwntools/pulls/1292
+[1355]: https://github.com/Gallopsled/pwntools/pulls/1355
+
+## 3.12.1
+
+- [#1104][1104] Add `DynELF.dump()` for dumping remote ELF files
+- [#1101][1101] Set `context.os` via `context.binary`, useful for Android exploitation
+- [5fdc08][5fdc08] Work around broken `pidof` on Android
+- [63dfed][63dfed] Print warning when Corefile deletion fails instead of throwing an exception
+- [#1094][1094] Make hexdump output alignment more consistent
+- [#1096][1096] `flat()` and `fit()` are now the same function
+
+[1104]: https://github.com/Gallopsled/pwntools/pull/1104
+[1101]: https://github.com/Gallopsled/pwntools/pull/1101
+[1094]: https://github.com/Gallopsled/pwntools/pull/1094
+[1096]: https://github.com/Gallopsled/pwntools/pull/1096
+[5fdc08]: https://github.com/Gallopsled/pwntools/commit/5fdc08
+[63dfed]: https://github.com/Gallopsled/pwntools/commit/63dfed
+
+## 3.12.0
+
+- [#1083][1083] Better error messages for `gdb` when `LD_PRELOAD` is incorrect
+- [#1085][1085] Add support for extracting Android `BOOTLDR!` images
+- [#1075][1075] Add support for detecting GNU Screen for `run_in_new_terminal`
+- [#1074][1074] Add support for running `pwntools-gdb` wrapper script instead of `gdb`
+- [#1068][1068] Work around very old OpenSSL versions which don't have sha256 support *AND* don't exit with an error code when trying to use it
+- [#1067][1067] Add `pwnlib.tubes.server` module, which adds a reusable `server` listener
+- [#1063][1063] Add support for labels in `fit()`, allowing dynamic contents to be injected.  (This feature is really cool, check out the pull request!)
+
+[1083]: https://github.com/Gallopsled/pwntools/pull/1083
+[1085]: https://github.com/Gallopsled/pwntools/pull/1085
+[1075]: https://github.com/Gallopsled/pwntools/pull/1075
+[1074]: https://github.com/Gallopsled/pwntools/pull/1074
+[1068]: https://github.com/Gallopsled/pwntools/pull/1068
+[1067]: https://github.com/Gallopsled/pwntools/pull/1067
+[1063]: https://github.com/Gallopsled/pwntools/pull/1063
+
+## 3.11.0
+
+- [#1044][1044] Enhancements to ROP
+    + Much better support for 64-bit Intel (amd64) ROP
+    + ROP gadget selection is optimized to favor multi-pops instead of multiple single-pop gadgets
+    + Added support for blacklisting byte values in ROP gadget addresses
+- [#1049][1049] Enhancements to `cyclic`
+    + `context` now has two additional attributes, `cyclic_alphabet` and `cyclic_length`, which correspond to the arguments `alphabet` and `n` to `cyclic()` and `cyclic_find()` and related routines.
+    + The motivation for this change is to allow setting the `alphabet` globally, so that any padding / patterns generated internally to pwntools can be controlled.  The specific motivation is blacklisting values in ROP padding.
+- [#1052][1052] Enhancements for detecting `QEMU_LD_PREFIX` used by QEMU user-mode emulation for sysroots
+- [#1035][1035] Minor documentation changes
+- [#1032][1032] Enhancements to `pwn template`
+- [#1031][1031] More accurate `Coredump.fault_addr` on amd64
+- [#1084][1084] Fix broken tests due to `ftp.debian.org` going down
+
+[1044]: https://github.com/Gallopsled/pwntools/pull/1044
+[1049]: https://github.com/Gallopsled/pwntools/pull/1049
+[1052]: https://github.com/Gallopsled/pwntools/pull/1052
+[1035]: https://github.com/Gallopsled/pwntools/pull/1035
+[1032]: https://github.com/Gallopsled/pwntools/pull/1032
+[1031]: https://github.com/Gallopsled/pwntools/pull/1031
+[1084]: https://github.com/Gallopsled/pwntools/pull/1084
+
+## 3.10.0
+
+- [#1007][1007] Add support for setting a `gdbinit` file in the context
+- [#1055][1055] Fixes for `Corefile` stack parsing, speed up `ELF.string()`
+- [#1057][1057] Fix a variable name typo in `DynELF` logging which results in an exception being thrown
+- [#1058][1058] Fix an edge case in `ssh_process.exe`
+
+[1007]: https://github.com/Gallopsled/pwntools/pull/1007
+[1055]: https://github.com/Gallopsled/pwntools/pull/1055
+[1057]: https://github.com/Gallopsled/pwntools/pull/1057
+[1058]: https://github.com/Gallopsled/pwntools/pull/1058
+
+## 3.9.2
+
+- [#1043][1043] Do not attempt to populate the libraries used by statically-linked binaries
+
+[1043]: https://github.com/Gallopsled/pwntools/pull/1043
+
+## 3.9.1
+
+- [#1038][1038] Fix an issue with `process()` where glibc would buffer data internally, causing a hang on `select()`
+- [#1036][1036] Fix Travis CI logging verbosity
+- [#1029][1029] Fix some `unicode` issues when using the `readline` command history in `tube.interactive()`
+
+[1038]: https://github.com/Gallopsled/pwntools/pull/1038
+[1036]: https://github.com/Gallopsled/pwntools/pull/1036
+[1029]: https://github.com/Gallopsled/pwntools/pull/1029
+
+## 3.9.0
+
+- [#1003][1003] Make `concat_all` faster while also simplifying it's logic
+- [#1014][1014] Fix for overwritten env when parsing core file
+- [#1023][1023] Fixes to Travis CI
+
+[1003]: https://github.com/Gallopsled/pwntools/pull/1003
+[1014]: https://github.com/Gallopsled/pwntools/pull/1014
+[1023]: https://github.com/Gallopsled/pwntools/pull/1023
+
+## 3.8.0
+
+- [#981][981] Fixed RELRO detection logic
+- [#986][986] Enhancements to DynELF for controlling usage of LibcDB
+- A few documentation fixes
+- A few fixes for the Docker image
+
+[981]: https://github.com/Gallopsled/pwntools/pull/981
+[986]: https://github.com/Gallopsled/pwntools/pull/986
+
+## 3.7.1
+
+- [#998][998] Fix a bug where integer values could not be set in `.pwn.conf`.
+
+[998]: https://github.com/Gallopsled/pwntools/pull/998
+
+## 3.7.0
+
+- [#933][933] DynELF works better with different base addresses
+- [#952][952] A few small fixes were made to `pwn template`, and the CRC database was updated.
+- [5c72d62c][5c72d62c] Updated the CRC database
+
+[933]: https://github.com/Gallopsled/pwntools/pull/933
+[952]: https://github.com/Gallopsled/pwntools/pull/952
+[5c72d62c]: https://github.com/Gallopsled/pwntools/commit/5c72d62c
+
+## 3.6.1
+
+- [#979][979]+[1a4a1e1][1a4a1e1] Fixed [#974][974], a bug related to the terminal handling and numlock.
+- [#980][980] Fixed the `pwn template` command.
+
+[974]: https://github.com/Gallopsled/pwntools/issues/974
+[979]: https://github.com/Gallopsled/pwntools/pull/979
+[980]: https://github.com/Gallopsled/pwntools/pull/980
+[1a4a1e1]: https://github.com/Gallopsled/pwntools/commit/1a4a1e1
+
+## 3.6.0
+
+- [#895][895] Added a Dockerfile to simplify testing setup and allow testing on OSX
+- [#897][897] Fixed some incorrect AArch64 syscals
+- [#893][893] Added the `pwnlib.config` module
+    + Configuration options can now be set in `~/.pwn.conf`
+    + This replaces the old, **undocumented** mechanism for changing logging colors.  Only @br0ns and @ebeip90 were likely using this.
+    + More information is available in the documentation [here](http://docs.pwntools.com/en/dev/config.html).
+- [#899][899] Pwntools now uses Unicorn Engine to emulate PLT instructions to ensure correct mapping of PIE / RELRO binaries.
+- [#904][904] Enhancements to the accuracy of the `pwn checksec` command.
+- [#905][905] Added a `pwn debug` command-line utility which automates the process of `gdb.attach(process(...))` to spawn GDB
+    + More information is available in the documentation [here](http://docs.pwntools.com/en/dev/commandline.html#pwn-debug)
+- [#919][919] Added a `pwn template` command-line utility to simplify the process of bootstrapping a new exploit.
+    + More information is available in the documentation [here](http://docs.pwntools.com/en/dev/commandline.html#pwn-template).
+- [#948][948] Fix unnecessary warning for Core files
+- [#954][954] Fix list processing in `~/.pwn.conf`
+- [#967][967] Respect `TERM_PROGRAM` for `run_in_new_terminal`
+- [#970][970] Fix overly-aggressive corefile caching
+
+[947]: https://github.com/Gallopsled/pwntools/pull/947
+[948]: https://github.com/Gallopsled/pwntools/pull/948
+[954]: https://github.com/Gallopsled/pwntools/pull/954
+[960]: https://github.com/Gallopsled/pwntools/pull/960
+[967]: https://github.com/Gallopsled/pwntools/pull/967
+[968]: https://github.com/Gallopsled/pwntools/pull/968
+[970]: https://github.com/Gallopsled/pwntools/pull/970
+
+[895]: https://github.com/Gallopsled/pwntools/pull/895
+[897]: https://github.com/Gallopsled/pwntools/pull/897
+[893]: https://github.com/Gallopsled/pwntools/pull/893
+[899]: https://github.com/Gallopsled/pwntools/pull/899
+[904]: https://github.com/Gallopsled/pwntools/pull/904
+[905]: https://github.com/Gallopsled/pwntools/pull/905
+[919]: https://github.com/Gallopsled/pwntools/pull/919
+
+## 3.5.1
+
+- [#945][945] Speed up ssh via caching checksec results (fixes [#944][944])
+- [#950][950] Fixes a bug where setting `context.arch` does not have an effect on `adb.compile()` output architecture
+
+[944]: https://github.com/Gallopsled/pwntools/issues/944
+[945]: https://github.com/Gallopsled/pwntools/pull/945
+[950]: https://github.com/Gallopsled/pwntools/pull/950
+
+## 3.5.0
+
+- [b584ca3][b584ca3] Fixed an issue running `setup.py` on ARM
+- [#822][822] Enabled relative leaks with `MemLeak`
+    + This should be useful for e.g. heap-relative leaks
+- [#832][832] Changed all internal imports to use absolute imports (no functional changes)
+- [a12d0b6][a12d0b6] Move `STDOUT`, `PIPE`, `PTY` constants to globals
+    + `process(..., stdin=process.PTY)` --> `process(..., stdin=PTY)`
+- [#828][828] Use `PR_SET_PTRACER` for all `process()` and `ssh.process()` instances
+    + This simplifies debugging on systems with YAMA ptrace enabled
+- Various documentation enhancements
+    + In particular, the [gdb][gdb], [elf][elf], and [ssh][ssh] docs are much better
+- [#833][833] Performance enhancements for `adb` module
+- [d0267f3][d0267f3] `packing.fit()` now treats large offsets as cyclic patterns (e.g. `0x61616161` behaves the same as `"aaaa"`)
+- [#835][835] Added `ssh.checksec`
+    + Reports the kernel version and other relevant information on connection
+- [#857][857] Slightly shortened `execve` shellcode
+- [300f8e0][300f8e0] Slightly speed up processing of large ELF files
+- [#861][861] Adds support for extracting `IKCONFIG` configs from Linux kernel images, and extends `checksec` to report on any insecure configurations discovered
+- [#871][871] Moves all of the basic syscall templates to `shellcraft/common` and exposes them via symlinks.  Closed [#685][685]
+    + Should not have any visible effects from any documented APIs
+    + `shellcraft.arch.os.syscall_function()` still works the same
+    + We now have the ability to differentiate between the `connect` syscall, and a TCP `connect` helper
+- [#887][887] `sh_string` now returns a quoted empty string `''` rather than just an empty string
+- [#839][839] Exposes a huge amount of functionality via corefiles which was not previously availble.  See the [docs][corefile_docs] for examples.
+    + `process().corefile` will automatically instantiate a Corefile for the process
+    + QEMU-emulated processes are supported
+    + Native processes are supported, including extraction of coredumps from `apport` crash logs
+    + Native processes can be dumped *while running*, in a manner similar to `GDB`'s `gcore` script
+- [#875][857] Added [documentation][aarch64] (and tests) for AArch64 shellcode
+- [#882][882] The `ROP` class now respects `context.bytes` instead of using the hard-coded value of `4` (fixed [#879][879])
+- [#869][869] Added several fields to the `process` class (`uid`, `gid`, `suid`, `sgid`) which are recorded at execution time, based on the file permissions
+- [#868][868] Changed the way that `ssh.process()` works internally, and it now returns a more specialized class, `ssh_process`.
+    + Added `ssh_process.corefile` for fetching remote corefiles
+    + Added `ssh_process.ELF` for getting an ELF of the remote executable
+    + The `uid`, `gid`, and `suid`, and `sgid` which are recorded at execution time, based on the file permissions
+- [#865][865] Fixes `ELF.read` to support contiguous memory reads across non-contiguous file-backed segments
+- [#862][862] Adds a `symlink=` argument to `ssh.set_working_directory`, which will automatically symlink all of the files in the "old" working directory into the "new" working directory
+
+[ssh]: http://docs.pwntools.com/en/dev/tubes/ssh.html
+[gdb]: http://docs.pwntools.com/en/dev/gdb.html
+[elf]: http://docs.pwntools.com/en/dev/elf.html
+[corefile_docs]: http://docs.pwntools.com/en/dev/elf/corefile.html
+[aarch64]: http://docs.pwntools.com/en/dev/shellcraft/aarch64.html
+
+[685]: https://github.com/Gallopsled/pwntools/pull/685
+[822]: https://github.com/Gallopsled/pwntools/pull/822
+[828]: https://github.com/Gallopsled/pwntools/pull/828
+[832]: https://github.com/Gallopsled/pwntools/pull/832
+[833]: https://github.com/Gallopsled/pwntools/pull/833
+[835]: https://github.com/Gallopsled/pwntools/pull/835
+[839]: https://github.com/Gallopsled/pwntools/pull/839
+[857]: https://github.com/Gallopsled/pwntools/pull/857
+[861]: https://github.com/Gallopsled/pwntools/pull/861
+[862]: https://github.com/Gallopsled/pwntools/pull/862
+[865]: https://github.com/Gallopsled/pwntools/pull/865
+[868]: https://github.com/Gallopsled/pwntools/pull/868
+[869]: https://github.com/Gallopsled/pwntools/pull/869
+[871]: https://github.com/Gallopsled/pwntools/pull/871
+[875]: https://github.com/Gallopsled/pwntools/pull/857
+[879]: https://github.com/Gallopsled/pwntools/issues/879
+[882]: https://github.com/Gallopsled/pwntools/pull/882
+[887]: https://github.com/Gallopsled/pwntools/pull/887
+
+
+[b584ca3]: https://github.com/Gallopsled/pwntools/commit/b584ca3
+[a12d0b6]: https://github.com/Gallopsled/pwntools/commit/a12d0b6
+[d0267f3]: https://github.com/Gallopsled/pwntools/commit/d0267f3
+[300f8e0]: https://github.com/Gallopsled/pwntools/commit/300f8e0
+
+## 3.4.1
+
+- [#894][894] Fix a bug when using `gdb.debug()` over ssh.
+- [e021f57][e021f57] Fix a bug ([#891][891]) in `rop` when needing to insert padding to fix alignment
+
+[e021f57]: https://github.com/Gallopsled/pwntools/commit/e021f57
+[894]: https://github.com/Gallopsled/pwntools/pull/894
+[891]: https://github.com/Gallopsled/pwntools/issues/891
+
+## 3.4.0
+
+- [#800][800] Add `shell=` option to `ssh.process()`
+- [#806][806] Add `context.buffer_size` for fine-tuning `tube` performance
+    + Also adds `buffer_fill_size=` argument for all tubes
+- [b83a6c7][b83a6c7] Fix undocumented `process.leak` function
+- [546061e][546061e] Modify `coredump_filter` of all spawned processes, so that core dumps are more complete
+- [#809][809] Add several functions to `adb` (`unlink`, `mkdir`, `makedirs`, `isdir`, `exists`)
+- [#817][817] Make disconnection detection more robust
+
+[800]: https://github.com/Gallopsled/pwntools/pull/800
+[806]: https://github.com/Gallopsled/pwntools/pull/806
+[809]: https://github.com/Gallopsled/pwntools/pull/809
+[817]: https://github.com/Gallopsled/pwntools/pull/817
+[5d9792f]: https://github.com/Gallopsled/pwntools/commit/5d9792f
+[b83a6c7]: https://github.com/Gallopsled/pwntools/commit/b83a6c7
+[546061e]: https://github.com/Gallopsled/pwntools/commit/546061e
+
+## 3.3.4
+
+- [#850][850] and [#846][846] fix issues with `hexdump` and the `phd` command-line utility, when using pipes (e.g. `echo foo | phd`)
+- [#852][852] Fixes register ordering in `regsort`
+- [#853][853] Fixes the registers restored in `shellcraft.amd64.popad`
+
+[846]: https://github.com/gallopsled/pwntools/pull/846
+[850]: https://github.com/gallopsled/pwntools/pull/850
+[852]: https://github.com/gallopsled/pwntools/pull/852
+[853]: https://github.com/gallopsled/pwntools/pull/853
+
+## 3.3.3
+
+- [#843][843] fixed a bug in `amd64.mov`.
+
+[843]: https://github.com/gallopsled/pwntools/pull/843
+
+## 3.3.2
+
+- [#840][840] fixed a regression introduced by [#837][837].
+
+[840]: https://github.com/gallopsled/pwntools/pull/840
+
+## 3.3.1
+
+- [#833][833] Fixed a performance-impacting bug in the adb module.
+- [#837][837] Fixed a bug([#836][836]) causing `hexdump(cyclic=True)` to throw an exception.
+
+[833]: https://github.com/Gallopsled/pwntools/pull/833
+[837]: https://github.com/Gallopsled/pwntools/pull/837
+[836]: https://github.com/Gallopsled/pwntools/issues/836
+
+## 3.3.0
+
+- [b198ec8][b198ec8] Added `tube.stream()` function, which is like `tube.interact()` without a prompt or keyboard input.
+    + Effectively, this is similar to `cat file` and just prints data as fast as it is received.
+- [aec3fa6][aec3fa6] Disable update checks against GitHub
+    + These checks frequently broke due to GitHub query limits
+- [#757][757] Fixed `adb.wait_for_device()` re-use of the same connection
+- [f9133b1][f9133b1] Add a `STDERR` magic argument to make logging go to `stderr` instead of `stdout`
+    + Usage is e.g. `python foo.py STDERR` or `PWNLIB_STDERR=1 python foo.py`
+    + Also adds `context.log_console` to log to any file or terminal
+- [67e11a9][67e11a9] Add faster error checking to `cyclic()` when provided very large values
+- [5fda658][5fda658] Expose BitPolynom in `globals()`
+- [#765][765] Added `-d` option for hex-escaped output for `shellcraft` command-line tool
+- [#772][772] Fixed bash completion regressions
+- [30c34b7][30c34b7] Fix `ROP.call()` with `Function` objects from `ELF.functions`
+- [fa402ce][fa402ce] Add `adb.uptime` and `adb.boot_time`
+- [82312ba][82312ba] Add `cyclic_metasploit` and `cyclic_metasploit_find`
+
+[757]: https://github.com/Gallopsled/pwntools/pull/757
+[765]: https://github.com/Gallopsled/pwntools/pull/765
+[772]: https://github.com/Gallopsled/pwntools/pull/772
+[b198ec8]: https://github.com/Gallopsled/pwntools/commit/b198ec8
+[aec3fa6]: https://github.com/Gallopsled/pwntools/commit/aec3fa6
+[f9133b1]: https://github.com/Gallopsled/pwntools/commit/f9133b1
+[67e11a9]: https://github.com/Gallopsled/pwntools/commit/67e11a9
+[5fda658]: https://github.com/Gallopsled/pwntools/commit/5fda658
+[30c34b7]: https://github.com/Gallopsled/pwntools/commit/30c34b7
+[fa402ce]: https://github.com/Gallopsled/pwntools/commit/fa402ce
+[82312ba]: https://github.com/Gallopsled/pwntools/commit/82312ba
+
+## 3.2.1
+
+Multiple bug fixes.
+
+- [#783][783] Fix `adb.uninstall` typo
+- [#787][787] Added error handling for `ssh.process` argument `preexec_fn`
+- [#793][793] Fixed progress message in `remote()` when connections failed
+- [#802][802] Fixed partition listing in `adb.partitions`, which accidentally shelled out to the `adb` binary
+- [#804][804] Fix error message for 32-bit distributions
+- [#805][805] Fix exception in `Core.segments` when a segment has no name
+- [#811][811] Fixes and performance improvements for `adb.wait_for_device()`
+- [#813][813] Fixed a release script
+- [#814][814] Fixed exceptions thrown if the `$HOME` directory is not writable
+- [#815][815] Properly handle `None` in `MemLeak`
+
+[783]: https://github.com/Gallopsled/pwntools/pull/783
+[787]: https://github.com/Gallopsled/pwntools/pull/787
+[793]: https://github.com/Gallopsled/pwntools/pull/793
+[802]: https://github.com/Gallopsled/pwntools/pull/802
+[804]: https://github.com/Gallopsled/pwntools/pull/804
+[805]: https://github.com/Gallopsled/pwntools/pull/805
+[811]: https://github.com/Gallopsled/pwntools/pull/811
+[813]: https://github.com/Gallopsled/pwntools/pull/813
+[814]: https://github.com/Gallopsled/pwntools/pull/814
+[815]: https://github.com/Gallopsled/pwntools/pull/815
+
+## 3.2.0
+
+- [#695][695] Fixed a performance regression in `phd`.
+- [452605e][452605e] Fixed [#629][629] related to correct removal of temporary files.
+- [ea94ee4][ea94ee4] Disallows semi-colons in for the `run_in_terminal` function, since it did not work properly in all cases.
+- [6376d07][6376d07] Added the mips shellcode `pushstr_array`.
+- [#700][700] Added missing MIPS shellcode documentation to readthedocs, and enabled unit tests
+- [#701][701] Command line tools refactored to have a common `pwn` entry point.
+    + Added an option to *not* install the traditional `asm`, `disasm`, `checksec`, etc scripts
+    + All existing tools can be accessed from the `pwn` command (e.g. `pwn asm nop`).
+- [#704][704] The `process` object has a new, optional argument `alarm` for setting a `SIGALRM` timeout for processes.
+- [#705][705] Added the Android Emulator to the test suite and Travis CI.
+    + Android Emulator is now required for the full test suite
+    + Android Emulator tests are skipped if no Android-related changes are detected
+- [#711][711] `DynELF` has a new attribute, `heap`, which leaks the current `brk` address (heap base).  This is useful for finding heap allocations with dlmalloc-derived allocators like those used by Glibc.
+- [#717][717] `sh_string` was rewritten to emit more compact and compatible strings
+    + This was achieved by embedding single-quoted non-printable literals
+    + Much more testing was added
+    + Emitted strings are no longer copy-paste compatible, but work fine with e.g. `tubes` module and the default `subprocess` module
+- [#709][709] The `adb` module now directly talks to the `adb` server process via a new module, `adb.protocol`
+    + Removes the need to shell out to `adb`
+    + Avoids version-compatibility issues with `adb` server vs. client
+- [#703][703] Added new methods to `adb`
+    + `install` - Installs an APK
+    + `uninstall` - Uninstalls a package
+    + `packages` - Lists installed packages
+- [4893819][4893819] Modified `shellcraft.sh` on all platforms to provide `argv[0]` and set `argc==1`
+    + This is needed for systems which have Busybox or other minimal shell for `/bin/sh` which does not behave well with `argc==0` or `argv[0]==NULL`.
+- [1e414af][1e414af] Added `connect()` alias for `remote()`
+    + For example, `io=connect('google.com', 80)`
+    + This also works with `tcp(...)` and `udp(...)` aliases
+- [869ec42][869ec42] Added `ssh.read()` and `ssh.write()` aliases
+- [2af55c9][2af55c9] `AdbDevice` objects exposed via e.g. `adb.devices()` now offer scoped access to all `adb` module properties
+    + It is now possible to e.g. `map(lambda d: d.process(['id']).recvall(), adb.devices())`
+
+
+[629]: https://github.com/Gallopsled/pwntools/issues/629
+[695]: https://github.com/Gallopsled/pwntools/pull/695
+[700]: https://github.com/Gallopsled/pwntools/pull/700
+[701]: https://github.com/Gallopsled/pwntools/pull/701
+[704]: https://github.com/Gallopsled/pwntools/pull/704
+[711]: https://github.com/Gallopsled/pwntools/pull/711
+[717]: https://github.com/Gallopsled/pwntools/pull/717
+[709]: https://github.com/Gallopsled/pwntools/pull/709
+[705]: https://github.com/Gallopsled/pwntools/pull/705
+[703]: https://github.com/Gallopsled/pwntools/pull/703
+[452605e]: https://github.com/Gallopsled/pwntools/commit/452605e854f4870ef5ccfdf7fb110dfd75c50feb
+[ea94ee4]: https://github.com/Gallopsled/pwntools/commit/ea94ee4ca5a8060567cc9bd0dc33796a89ad0b95
+[6376d07]: https://github.com/Gallopsled/pwntools/commit/6376d072660fb2250f48bd22629bbd7e3c61c758
+[1e414af]: https://github.com/Gallopsled/pwntools/commit/1e414afbeb3a01242f4918f111febaa63b640eb7
+[869ec42]: https://github.com/Gallopsled/pwntools/commit/869ec42082b4b98958dfe85103da9b101dde7daa
+[4893819]: https://github.com/Gallopsled/pwntools/commit/4893819b4c23182da570e2f4ea4c14d73af2c0df
+[2af55c9]: https://github.com/Gallopsled/pwntools/commit/2af55c9bc382eca23f89bc0abc7a07c075521f94
+
+## 3.1.1
+
+Fixed a bug in `MemLeak.struct` (PR: #768).
+
+## 3.1.0
+
+A number of smaller bugfixes and documentation tweaks.
+
+## 3.0.4
+
+- Fixed a bug that made 3.0.3 uninstallable (Issue: #751, PR: #752)
+
+## 3.0.3
+
+- Fixed some performance and usability problems with the update system (Issues:
+  #723, #724, #736. PRs: #729, #738, #747).
+- Fixed a bug related to internals in pyelftools (PRs: #730, #746).
+- Fixed an issue with travis (Issue: #741, PRs: #743, #744, #745).
+
+## 3.0.2
+
+- Cherry-pick #695, as this was a regression-fix.
+- Added a fix for the update checker, as it would suggest prereleases as updates to stable releases.
+- Various documentation fixes.
+
+## 3.0.1
+
+A small bugfix release. There were a lot of references to the `master`-branch, however after 3.0.0 we use the names `stable`, `beta` and `dev` for our branches.
+
+## 3.0.0
+
+This was a large release (1305 commits since 2.2.0) with a lot of bugfixes and changes.  The Binjitsu project, a fork of Pwntools, was merged back into Pwntools.  As such, its features are now available here.
+
+As always, the best source of information on specific features is the comprehensive docs at https://pwntools.readthedocs.org.
+
+This list of changes is non-complete, but covers all of the significant changes which were appropriately documented.
+
+#### Android
+
+Android support via a new `adb` module, `context.device`, `context.adb_host`, and `context.adb_port`.
+
+#### Assembly and Shellcode
+
+- Assembly module enhancements for making ELF modules from assembly or pre-assembled shellcode.  See `asm.make_elf` and `asm.make_elf_from_assembly`.
+- `asm` and `shellcraft` command-line tools support flags for the new shellcode encoders
+- `asm` and `shellcraft` command-line tools support `--debug` flag for automatically launching GDB on the result
+- Added MIPS, PowerPC, and AArch64 support to the `shellcraft` module
+- Added Cyber Grand Challenge (CGC) support to the `shellcraft` module
+- Added syscall wrappers for every Linux syscall for all supported architectures to the `shellcraft` module
+    + e.g. `shellcraft.<arch>.gettimeofday`
+- (e.g. `shellcraft.i386.linux.`)
+- Added in-memory ELF loaders for most supported architectures
+    + Only supports statically-linked binaries
+    + `shellcraft.<arch>.linux.loader`
+
+#### Context Module
+
+- Added `context.aslr` which controls ASLR on launched processes.  This works with both `process()` and `ssh.process()`, and can be specified per-process with the `aslr=` keyword argument.
+- Added `context.binary` which automatically sets all `context` variables from an ELF file.
+- Added `context.device`, `context.adb`, `context.adb_port`, and `context.adb_host` for connecting to Android devices.
+- Added `context.kernel` setting for SigReturn-Oriented-Programming (SROP).
+- Added `context.log_file` setting for sending logs to a file.  This can be set with the `LOG_FILE` magic command-line option.
+- Added `context.noptrace` setting for disabling actions which require `ptrace` support.  This is useful for turning all `gdb.debug` and `gdb.attach` options into no-ops, and can be set via the `NOPTRACE` magic command-line option.
+- Added `context.proxy` which hooks all connections and sends them to a SOCKS4/SOCKS5.  This can be set via the `PROXY` magic command-line option.
+- Added `context.randomize` to control randomization of settings like XOR keys and register ordering (default off).
+- Added `context.terminal` for setting how to launch commands in a new terminal.
+
+#### DynELF and MemLeak Module
+
+- Added a `DynELF().libc` property which attempt to find the remote libc and download the ELF from LibcDB.
+- Added a `DynELF().stack` property which leaks the `__environ` pointer from libc, making it easy to leak stack addresses.
+- Added `MemLeak.String` and `MemLeak.NoNewlines` and other related helpers for handling special leakers which cannot e.g. handle newlines in the leaked addresses and which leak a C string (e.g. auto-append a `'\x00'`).
+- Enhancements for leaking speed via `MemLeak.compare` to avoid leaking an entire field if we can tell from a partial leak that it does not match what we are searching for.
+
+#### Encoders Module
+
+- Added a `pwnlib.encoders` module for assembled-shellcode encoders/decoders
+- Includes position-independent basic XOR encoders
+- Includes position-independent delta encoders
+- Includes non-position-independent alphanumeric encoders for Intel
+- Includes position-independent alphanumeric encoders for ARM/Thumb
+
+#### ELF Module
+
+- Added a `Core` object which can parse core-files, in order to extract / search for memory contents, and extract register states (e.g. `Core('./corefile').eax`).
+
+#### Format Strings
+
+- Added a basic `fmtstr` module for assisting with Format String exploitation
+
+#### GDB Module
+
+- Added support for debugging Android devices when `context.os=='android'`
+- Added helpers for debugging shellcode snippets with `gdb.debug_assembly()` and `gdb.debug_shellcode()`
+
+#### ROP Module
+
+- Added support for SigReturn via `pwnlib.rop.srop`
+    + Occurs automatically when syscalls are invoked and a function cannot be found
+    + SigReturn frames can be constructed manually with `SigreturnFrame()` objects
+- Added functional doctests for ROP and SROP
+
+#### Tubes Process Module
+
+- `process()` has many new options, check out the documentation
+    + `aslr` controls ASLR
+    + `setuid` can disable the effect of setuid, allowing core dumps (useful for extracting crash state via the new `Core()` object)
+    + TTY echo and control characters can be enabled via `raw` argument
+- `stdout` and `stderr` are now PTYs by default
+    + `stdin` can be set to a PTY also via setting `stdin=process.PTY`
+
+#### Tubes SSH Module
+
+- Massive enhancements all over
+- `ssh` objects now have a `ssh.process()` method which avoids the need to handle shell expansion via the old `ssh.run()` method
+- Files are downloaded via SFTP if available
+- New `download` and `upload` methods auto-detect whether the target is a file or directory and acts accordingly
+- Added `listen()` method alias for `listen_remote()`
+- Added `remote()` method alias for `connect_remote()`
+
+#### Utilities
+
+- Added `fit()` method to combine the functionality of `flat()` with the functionality of `cyclic()`
+- Added `negative()` method to negate the value of an integer via two's complement, with respect to the current integer size (`context.bytes`).
+- Added `xor_key()` method to generate an XOR key which avoids undesirable bytes over a given input.
+- Added a multi-threaded `bruteforce()` implementation, `mbruteforce()`.
+- Added `dealarm_shell()` helper to remove the effects of `alarm()` after you've popped a shell.
+
+## 2.2.0

 This was a large release with a lot of bugfixes and changes. Only the most significant
 are mentioned here.
@@ -16,3 +635,11 @@ are mentioned here.
 - Added a serial tube
 - Huge performance gains in the buffering for tubes
 - Re-added user agents
+- Begun using Travis CI with lots of test
+- Removed bundled binutils in favor of documenting how to build them yourselves
+- Added support for port forwarding though our SSH module
+- Added dependency for capstone and ropgadget
+- Added a lots of shellcodes
+- Stuff we forgot
+- Lots of documentation fixes
+- Lots of bugfixes
@@ -1,7 +1,5 @@
 # Contributing

-We love pull requests!
-
 Github has a great guide for contributing to open source projects:

 - [Contributing to a project](https://guides.github.com/activities/forking/)
@@ -11,7 +9,7 @@ Github has a great guide for contributing to open source projects:
 - [Making a Pull Request](https://guides.github.com/activities/forking/#making-a-pull-request)
 - [Huzzah!](https://guides.github.com/activities/forking/#huzzah)

-## Pwntools Specifics
+## pwntools Specifics

 In general, we like to keep things documented.  You should add documentation to any new functionality, and update it for any changed functionality.  Our docstrings use the [Google Style Python Docstrings](https://sphinxcontrib-napoleon.readthedocs.org/en/latest/example_google.html#example-google).

@@ -21,18 +19,17 @@ Finally, it is probably a good idea to run the test suite locally before doing
 the pull-request to make sure everything works, however this is not a
 requirement.

+Once you are ready to do a pull-request, you should figure out if your changes
+constitutes a new feature or a bugfix in stable or beta. If it is a bugfix in
+stable or beta, you should do the pull-request against the branch in question,
+and otherwise your pull-request should be against the dev branch.
+
 Once you do the pull-request Travis CI will run the test-suite on it. Once it
 passes one of the core developers will look at your pull request, possibly
-comment on it and then hopefully merge it into master.
+comment on it and then hopefully merge it into the branch in question.

-## Test Suite
+## Automated Testing

-To run the test suite, you should be running Ubuntu 12.04 or 14.04, and run the following commands.  **Be aware** that this will add a user to your machine, and create a public key for SSH login!
+Pull requests against Pwntools require at a minimum that no tests have been broken, and ideally each pull request will include new tests to ensure that all of the functionality works as intended.

-```sh
-bash .travis_install.sh
-bash .travis_ssh_setup.sh
-cd docs
-pip install -r requirements.txt
-make doctest
-```
+You can find more information on testing in [TESTING.md](TESTING.md).
@@ -13,7 +13,7 @@ directories:
 - pwnlib/data/


-Copyright (c) 2013 Gallopsled
+Copyright (c) 2015 Gallopsled et al.

 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -1 +1,7 @@
-include *.txt
+graft examples
+graft extra
+include *.md *.txt *.sh *.yml MANIFEST.in
+recursive-include docs   *.rst *.png Makefile *.py *.txt
+recursive-include pwnlib *.py *.asm *.rst *.md *.txt *.sh __doc__ *.mako
+recursive-include pwn    *.py *.asm *.rst *.md *.txt *.sh
+recursive-exclude *.pyc
@@ -1,11 +1,14 @@
 # pwntools - CTF toolkit
-[![Docs latest](https://readthedocs.org/projects/pwntools/badge/)](https://pwntools.readthedocs.org/en/latest)
-[![Docs 2.1.3](https://readthedocs.org/projects/pwntools/badge/?version=2.1.3)](https://pwntools.readthedocs.org/en/2.1.3)
-[![PyPI](https://img.shields.io/pypi/v/pwntools.svg)](https://pypi.python.org/pypi/pwntools/)
-[![Gittip](https://img.shields.io/gittip/gallopsled.svg)](https://www.gittip.com/gallopsled/)
-[![Travis](https://travis-ci.org/Gallopsled/pwntools.svg)](https://travis-ci.org/Gallopsled/pwntools)
+![pwntools logo](https://github.com/Gallopsled/pwntools/blob/stable/docs/source/logo.png?raw=true)

-This is the CTF framework used by Gallopsled in every CTF.
+[![Docs](https://readthedocs.org/projects/pwntools/badge/?version=stable)](https://docs.pwntools.com/)
+[![PyPI](https://img.shields.io/badge/pypi-v3.13.0-green.svg?style=flat)](https://pypi.python.org/pypi/pwntools/)
+[![Travis](https://travis-ci.org/Gallopsled/pwntools.svg)](https://travis-ci.org/Gallopsled/pwntools)
+[![Coveralls](https://img.shields.io/coveralls/Gallopsled/pwntools/dev.svg)](https://coveralls.io/github/Gallopsled/pwntools?branch=dev)
+[![Twitter](https://img.shields.io/badge/twitter-pwntools-4099FF.svg?style=flat)](https://twitter.com/pwntools)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat)](http://choosealicense.com/licenses/mit/)
+
+Pwntools is a CTF framework and exploit development library. Written in Python, it is designed for rapid prototyping and development, and intended to make exploit writing as simple as possible.

 ```python
 from pwn import *
@@ -17,32 +20,30 @@ r.send(asm(shellcraft.sh()))
 r.interactive()
 ```

-However we have made command-line frontends for some of the functionality
-in `pwnlib`. These are:
+# Try It Now!

-* `asm`/`disasm`: Small wrapper for various assemblers.
-* `constgrep`: Tool for finding constants defined in header files.
-* `cyclic`: De Bruijn sequence generator and lookup tool.
-* `hex`/`unhex`: Command line tools for doing common hexing/unhexing operations.
-* `shellcraft`: Frontend to our shellcode.
-* `phd`: Replacement for `hexdump` with colors.
+You can now do a live demo of Pwntools, [right in your browser](https://demo.pwntools.com).

 # Documentation
-Our documentation is available at [pwntools.readthedocs.org](https://pwntools.readthedocs.org/en/latest/)
+
+Our documentation is available at [docs.pwntools.com](https://docs.pwntools.com/)

 To get you started, we've provided some example solutions for past CTF challenges in our [write-ups repository](https://github.com/Gallopsled/pwntools-write-ups).

 # Installation

-pwntools is best supported on Ubuntu 12.04 and 14.04, but most functionality should work on any Posix-like distribution (Debian, Arch, FreeBSD, OSX, etc.).
+Pwntools is best supported on 64-bit Ubuntu LTE releases (12.04, 14.04, and 16.04).  Most functionality should work on any Posix-like distribution (Debian, Arch, FreeBSD, OSX, etc.).  Python 2.7 is required.

 Most of the functionality of pwntools is self-contained and Python-only.  You should be able to get running quickly with

 ```sh
-pip install pwntools
+apt-get update
+apt-get install python2.7 python-pip python-dev git libssl-dev libffi-dev build-essential
+pip install --upgrade pip
+pip install --upgrade pwntools
 ```

-However, some of the features (ROP generation and assembling/disassembling foreign architectures) require non-Python dependencies.  For more information, see the [complete installation instructions here](https://pwntools.readthedocs.org/en/latest/install.html).
+However, some of the features (assembling/disassembling foreign architectures) require non-Python dependencies.  For more information, see the [complete installation instructions here](https://docs.pwntools.com/en/stable/install.html).


 # Contribution
@@ -50,7 +51,7 @@ However, some of the features (ROP generation and assembling/disassembling forei
 See [CONTRIBUTING.md](CONTRIBUTING.md)

 # Contact
-If you have any questions not worthy of a [bug report](https://github.com/Gallopsled/pwntools/issues), feel free to join us
-at [`#gallopsled` on Freenode](irc://irc.freenode.net/gallopsled) and ask away.
-Click [here](https://kiwiirc.com/client/irc.freenode.net/gallopsled) to connect.
-
+If you have any questions not worthy of a [bug report](https://github.com/Gallopsled/pwntools/issues), feel free to ping us
+at [`#pwntools` on Freenode](irc://irc.freenode.net/pwntools) and ask away.
+Click [here](https://kiwiirc.com/client/irc.freenode.net/pwntools) to connect.
+There is also a [mailing list](https://groups.google.com/forum/#!forum/pwntools-users) for higher latency discussion.
@@ -0,0 +1,44 @@
+# Testing
+
+Pwntools makes extensive use of unit tests and integration tests to ensure everything is in working order, and no regressions occur.
+
+## Test Suite
+
+To run the test suite, it is best to use Ubuntu 12.04 or 14.04, and run the following commands.  **Be aware** that this will add a user to the machine, and create a public key for SSH login!
+
+```sh
+bash travis/install.sh
+bash travis/ssh_setup.sh
+pip install --upgrade --editable .
+PWNLIB_NOTERM=1 make -C docs doctest
+```
+
+## Testing in Docker
+
+A `Dockerfile` has been provided which has a clean testing environment with Ubuntu Xenial.  It is very similar to the online Travis CI testing environment, but uses a more modern version of Ubuntu.
+
+See `travis/docker/README.md` for more information.
+
+## New Tests
+
+To add a new test to an existing module, just add an inline doctest.  If the test needs access to an external module, add the import statement to the `testsetup` block in the corresponding file in `docs/source/<module>.rst`.
+
+To add an entirely new module, create a new `module.rst` and add it to the list in `index.rst`.  The best way to see if your tests are actually being run is to add an intentionally-failing test like:
+
+```py
+>>> assert False
+```
+
+## Example Test Module
+
+The module `pwnlib.testexample` exists to demonstrate how everything is tied together.  The only files which were modified to add this example module and run its tests automatically are:
+
+- `pwnlib/testexample.py`
+- `docs/source/testexample.rst`
+- `docs/source/index.rst`
+
+## Shellcode and ROP
+
+These are both less easy to test, as they require actually executing code, or loading real binaries.  In order to make the process simpler, the `runner` library was created to wrap common tasks.  For an example of testing shellcode with these helpers, see [exit.asm](pwnlib/shellcraft/templates/i386/linux/exit.asm).
+
+Additionally, for loading ELF files on-the-fly, the helpers `ELF.from_bytes` and `ELF.from_assembly` are available.
@@ -6,6 +6,8 @@ SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = build
+DASHBUILD     = ./dashbuild.py
+TAR           = tar

 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
@@ -14,7 +16,8 @@ ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) sou
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source

-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext dash

 help:
 	@echo "Please use \`make <target>' where <target> is one of"
@@ -34,12 +37,17 @@ help:
 	@echo "  texinfo    to make Texinfo files"
 	@echo "  info       to make Texinfo files and run them through makeinfo"
 	@echo "  gettext    to make PO message catalogs"
+	@echo "  dash       to make a Dash docset"
 	@echo "  changes    to make an overview of all changed/added/deprecated items"
 	@echo "  linkcheck  to check all external links for integrity"
 	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"

 clean:
 	-rm -rf $(BUILDDIR)/*
+	-rm -rf /tmp/user/pwn*
+	-rm -rf $(HOME)/.pwntools-cache
+	-rm -rf /tmp/pwn* 2>/dev/null || true
+	-rm -rf build

 html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@@ -136,6 +144,11 @@ gettext:
 	@echo
 	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."

+dash:
+	$(DASHBUILD) source $(BUILDDIR)/dash
+	$(TAR) --exclude='.DS_Store' -cvzf $(BUILDDIR)/dash/pwntools.tgz -C $(BUILDDIR)/dash pwntools.docset
+	@echo "Build finished. The Dash docset is in $(BUILDDIR)/dash."
+
 changes:
 	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
 	@echo
@@ -0,0 +1,99 @@
+#!/usr/bin/env python
+
+# -*- coding: utf-8 -*-
+
+#
+# Helper to build Dash docset from sphinx source files.
+#
+# Dash docsets can be read by various applications:
+#
+# Dash         OS X, iOS         https://kapeli.com
+# Zeal         Linux, Windows    https://zealdocs.org
+# Velocity     Windows           http://velocity.silverlakesoftware.com
+# LovelyDocs   Android           http://lovelydocs.io
+# dasht        POSIX             https://github.com/sunaku/dasht
+# Helm Dash    emacs             https://github.com/areina/helm-dash
+#
+
+import argparse
+import doc2dash.__main__
+import os, os.path
+import sphinx
+import sqlite3
+import sys
+
+sys.path.append(os.path.abspath(os.path.join('..', 'pwnlib')))
+import version
+
+def main(args):
+	"""Generate a Dash docset from Sphinx source files."""
+
+	srcdir = args.srcdir
+	dstdir = args.dstdir
+	name = args.name
+
+	if not os.path.exists(dstdir):
+		os.makedirs(dstdir)
+
+	# Generate HTML without indices.
+	sphinx.build_main([ "sphinx-build", "-b", "html", "-d", os.path.join(dstdir, "doctrees"), \
+		"-t", "dash", srcdir, os.path.join(dstdir, "html") ])
+
+	# Convert to docset.
+	try:
+		doc2dash.__main__.main.main( \
+			[ os.path.join(dstdir, "html"), "-d", dstdir, "-n", name, \
+					"-f", "-I", "index.html"], "doc2dash", False)
+	except SystemExit,e:
+		pass
+
+	# Insert a link to the online version.
+	online = args.online
+	if online is not None and online != "":
+		url = online.replace("@VERSION", args.version)
+		with open(os.path.join(dstdir, name+".docset", "Contents", "Info.plist"), "r+") as f_info:
+			pl = f_info.read()
+			pl = pl.replace("</dict>", \
+				"\t<key>DashDocSetFallbackURL</key>\n\t<string>%s</string>\n</dict>" % url)
+			f_info.seek(0)
+			f_info.write(pl)
+			f_info.truncate()
+
+	# Modify the CSS to hide the menu included in the HTML.
+	with open(os.path.join(dstdir, name+".docset", "Contents", "Resources", "Documents", "_static", "css", "theme.css"), "r+") as f_css:
+		css = f_css.read()
+		css = css.replace( \
+			'@media screen and (max-width: 768px){.wy-body-for-nav{background:#fcfcfc}.wy-nav-top{display:block}',\
+			'@media screen {.wy-body-for-nav{background:#fcfcfc}' )
+		css = css.replace( \
+			'@media screen and (max-width: 480px)', \
+			'@media screen ')
+		f_css.seek(0)
+		f_css.write(css)
+		f_css.truncate()
+
+	# Modify the index
+	db_conn = sqlite3.connect(os.path.join(dstdir, name+".docset", "Contents", "Resources", "docSet.dsidx"))
+	try:
+		db_conn.execute('INSERT INTO "searchIndex" ("name","type","path") VALUES ' \
+			'("1 Contents", "Guide", "index.html"), ' \
+			'("2 About pwntools", "Guide", "about.html"), ' \
+			'("3 Installation", "Guide", "install.html"), ' \
+			'("4 Getting Started", "Guide", "intro.html"), ' \
+			'("5 Globals (pwn)", "Guide", "globals.html"), ' \
+			'("6 Command Line Tools", "Guide", "commandline.html")')
+		db_conn.execute('DELETE FROM "searchIndex" WHERE "type" = "Module" AND ("name" = "pwn" OR "name" = "pwnlib")')
+		db_conn.commit()
+	finally:
+		db_conn.close()
+
+	return 0
+
+parser = argparse.ArgumentParser()
+parser.add_argument("--name", help="docset name", default="pwntools")
+parser.add_argument("--online", help="URL for online docs", default="https://pwntools.readthedocs.org/en/@VERSION/")
+parser.add_argument("--version", help="pwntools version", default=version.__version__)
+parser.add_argument("srcdir", help="Source directory containing .rst files")
+parser.add_argument("dstdir", help="Destination and working directory")
+
+main(parser.parse_args())
@@ -1,6 +1,17 @@
-paramiko
-argparse
-mako
-pyelftools
 sphinxcontrib-napoleon
-sphinxcontrib-autoprogram
+sphinxcontrib-autoprogram==0.1.4
+isort
+paramiko>=1.15.2
+mako>=1.0.0
+pyelftools>=0.2.3
+capstone
+ropgadget>=5.3
+pyserial>=2.7
+requests>=2.5.1
+pip>=6.0.8
+tox>=1.8.1
+pygments>=2.0
+sphinx_rtd_theme
+doc2dash
+coveralls
+sphinx<1.8.0
@@ -11,7 +11,7 @@ nice side-effects.
 When redesigning pwntools for 2.0, we noticed two contrary goals:

 * We would like to have a "normal" python module structure, to allow other
-  people to faster get familiar with how pwntools works.
+  people to familiarize themselves with pwntools quickly.
 * We would like to have even more side-effects, especially by putting the
  terminal in raw-mode.

@@ -30,10 +30,10 @@ the following:

 * Imports everything from the toplevel :mod:`pwnlib` along with
  functions from a lot of submodules. This means that if you do
-  ``import pwn`` or ``from pwn import *``, you will access to
+  ``import pwn`` or ``from pwn import *``, you will have access to
  everything you need to write an exploit.
 * Calls :func:`pwnlib.term.init` to put your terminal in raw mode
-  and implementing functionality to make it look like it is not.
+  and implements functionality to make it appear like it isn't.
 * Setting the :data:`pwnlib.context.log_level` to `"info"`.
 * Tries to parse some of the values in :data:`sys.argv` and every
  value it succeeds in parsing it removes.
@@ -0,0 +1,13 @@
+.. testsetup:: *
+
+   from pwn import *
+   adb = pwnlib.adb
+
+:mod:`pwnlib.adb` --- Android Debug Bridge
+=====================================================
+
+.. automodule:: pwnlib.adb.adb
+   :members:
+
+.. automodule:: pwnlib.adb.protocol
+   :members:
@@ -0,0 +1,9 @@
+.. testsetup:: *
+
+   from pwn import *
+
+:mod:`pwnlib.args` --- Magic Command-Line Arguments
+=====================================================
+
+.. automodule:: pwnlib.args
+   :members:
@@ -1,10 +1,25 @@
 .. testsetup:: *

+   import tempfile
+   import subprocess
+   from pwnlib.context import context
   from pwnlib.asm import *
   from pwnlib import shellcraft
+   from pwnlib.tubes.process import process
+

 :mod:`pwnlib.asm` --- Assembler functions
 =========================================

 .. automodule:: pwnlib.asm
   :members:
+
+Internal Functions
+-----------------------------------------
+
+These are only included so that their tests are run.
+
+You should never need these.
+
+.. autofunction:: pwnlib.asm.dpkg_search_for_binutils
+.. autofunction:: pwnlib.asm.print_binutils_instructions
@@ -14,33 +14,5 @@ pwntools comes with a handful of useful command-line utilities which serve as wr

 .. toctree::

-.. autoprogram:: pwnlib.commandline.asm:parser
-   :prog: asm
-
-.. autoprogram:: pwnlib.commandline.constgrep:p
-   :prog: constgrep
-
-.. autoprogram:: pwnlib.commandline.cyclic:parser
-   :prog: cyclic
-
-.. autoprogram:: pwnlib.commandline.disasm:parser
-   :prog: disasm
-
-.. autoprogram:: pwnlib.commandline.elfdiff:p
-   :prog: elfdiff
-
-.. autoprogram:: pwnlib.commandline.elfpatch:p
-   :prog: elfpatch
-
-.. autoprogram:: pwnlib.commandline.hex:parser
-   :prog: hex
-
-.. autoprogram:: pwnlib.commandline.phd:parser
-   :prog: phd
-
-.. autoprogram:: pwnlib.commandline.shellcraft:p
-   :prog: shellcraft
-
-.. autoprogram:: pwnlib.commandline.unhex:parser
-   :prog: unhex
-
+.. autoprogram:: pwnlib.commandline.main:parser
+   :prog: pwn
@@ -11,14 +11,18 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.

-import sys, os, subprocess
+import os
+import subprocess
+import sys
+
+build_dash = tags.has('dash')

 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath('../..'))

-# -- General configuration -----------------------------------------------------
+import pwnlib

 # If your documentation needs a minimal Sphinx version, state it here.
 #needs_sphinx = '1.0'
@@ -38,20 +42,58 @@ extensions = [
    'sphinxcontrib.napoleon'
 ]

+# Disable "info" logging directly to stdout by Sphinx
+import logging
+
+class SphinxPwnlibFilter(logging.Filter):
+    def filter(self, record):
+        if record.name.startswith('pwn'):
+            return False
+        if record.name.startswith('paramiko'):
+            return False
+        return True
+
+log_filter = SphinxPwnlibFilter()
+
+for i, handler in enumerate(logging.root.handlers):
+    print("Filtering Sphinx handler", handler)
+    handler.addFilter(log_filter)
+
+# Napoleon settings
+napoleon_use_ivar = True
+napoleon_use_rtype = False
+
 doctest_global_setup = '''
+import sys, os
+os.environ['PWNLIB_NOTERM'] = '1'
+os.environ['PWNLIB_RANDOMIZE'] = '0'
 import pwnlib
 pwnlib.context.context.reset_local()
 pwnlib.context.ContextType.defaults['log_level'] = 'ERROR'
+pwnlib.context.ContextType.defaults['randomize'] = False
+pwnlib.util.fiddling.default_style = {}
 pwnlib.term.text.when = 'never'
+pwnlib.log.install_default_handler()
+pwnlib.log.rootlogger.setLevel(1)

+# Sphinx modifies sys.stdout, and context.log_terminal has
+# a reference to the original instance.  We need to update
+# it for logging to be captured.
+class stdout(object):
+    def __getattr__(self, name):
+        return getattr(sys.stdout, name)
+    def __setattr__(self, name, value):
+        return setattr(sys.stdout, name, value)
+pwnlib.context.ContextType.defaults['log_console'] = stdout()
 '''

-autodoc_member_order = 'alphabetical'
+autoclass_content = 'both'
+autodoc_member_order = 'groupwise' # 'alphabetical'

 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

-doctest_test_doctest_blocks = True
+doctest_test_doctest_blocks = 'true'

 # The suffix of source filenames.
 source_suffix = '.rst'
@@ -64,14 +106,13 @@ master_doc = 'index'

 # General information about the project.
 project = u'pwntools'
-copyright = u'2014, Gallopsled et al'
+copyright = u'2016, Gallopsled et al.'

 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-import pwnlib
 release = pwnlib.__version__
 version = release.rsplit('.', 1)[0]

@@ -161,10 +202,10 @@ html_static_path = []
 #html_additional_pages = {}

 # If false, no module index is generated.
-#html_domain_indices = True
+html_domain_indices = not build_dash

 # If false, no index is generated.
-#html_use_index = True
+html_use_index = not build_dash

 # If true, the index is split into individual pages for each letter.
 #html_split_index = False
@@ -207,11 +248,11 @@ latex_elements = {
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
  ('index', 'pwntools.tex', u'pwntools Documentation',
-   u'Gallopsled et al', 'manual'),
+   u'2016, Gallopsled et al.', 'manual'),
 ]

 intersphinx_mapping = {'python': ('https://docs.python.org/2.7', None),
-                       'paramiko': ('https://paramiko-docs.readthedocs.org/en/1.15/', None)}
+                       'paramiko': ('https://paramiko-docs.readthedocs.org/en/2.1/', None)}

 # The name of an image file (relative to this directory) to place at the top of
 # the title page.
@@ -240,7 +281,7 @@ intersphinx_mapping = {'python': ('https://docs.python.org/2.7', None),
 # (source start file, name, description, authors, manual section).
 man_pages = [
    ('index', 'pwntools', u'pwntools Documentation',
-     [u'Gallopsled et al'], 1)
+     [u'2016, Gallopsled et al.'], 1)
 ]

 # If true, show URL addresses after external links.
@@ -254,7 +295,7 @@ man_pages = [
 #  dir menu entry, description, category)
 texinfo_documents = [
  ('index', 'pwntools', u'pwntools Documentation',
-   u'Gallopsled et al', 'pwntools', 'One line description of project.',
+   u'', 'pwntools', 'CTF exploit writing toolkit.',
   'Miscellaneous'),
 ]

@@ -312,3 +353,63 @@ def linkcode_resolve(domain, info):
                pass

    return "https://github.com/Gallopsled/pwntools/blob/%s/%s" % (branch, filename)
+
+
+# The readthedocs theme is used by the Dash generator. (Can be used for HTML too.)
+
+if build_dash:
+
+    # on_rtd is whether we are on readthedocs.org
+    on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+
+    if not on_rtd:  # only import and set the theme if we're building docs locally
+        import sphinx_rtd_theme
+        html_theme = 'sphinx_rtd_theme'
+        html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
+    # otherwise, readthedocs.org uses their theme by default, so no need to specify it
+
+
+# -- Customization to Sphinx autodoc generation --------------------------------------------
+import sphinx.ext.autodoc
+from sphinx.util.inspect import safe_getmembers, safe_getattr
+
+# Test hidden members (e.g. def _foo(...))
+def dont_skip_any_doctests(app, what, name, obj, skip, options):
+    return False
+
+def get_object_members_all(self, want_all):
+    if want_all:
+        # if not hasattr(self.object, '__all__'):
+        #     for implicit module members, check __module__ to avoid
+        #     documenting imported objects
+        return True, safe_getmembers(self.object)
+    # else:
+    #     memberlist = self.object.__all__
+    #     # Sometimes __all__ is broken...
+    #     if not isinstance(memberlist, (list, tuple)) or not \
+        #        all(isinstance(entry, string_types) for entry in memberlist):
+    #         self.directive.warn(
+    #             '__all__ should be a list of strings, not %r '
+    #             '(in module %s) -- ignoring __all__' %
+    #             (memberlist, self.fullname))
+    #         # fall back to all members
+    #         return True, safe_getmembers(self.object)
+    else:
+        memberlist = self.options.members or []
+        ret = []
+        for mname in memberlist:
+            try:
+                ret.append((mname, safe_getattr(self.object, mname)))
+            except AttributeError:
+                self.directive.warn(
+                    'missing attribute mentioned in :members: or __all__: '
+                    'module %s, attribute %s' % (
+                        safe_getattr(self.object, '__name__', '???'), mname))
+        return False, ret
+
+if 'doctest' in sys.argv:
+    def setup(app):
+        app.connect('autodoc-skip-member', dont_skip_any_doctests)
+
+    sphinx.ext.autodoc.ModuleDocumenter.get_object_members = get_object_members_all
@@ -0,0 +1,4 @@
+:mod:`pwnlib.config` --- Pwntools Configuration File
+====================================================
+
+.. automodule:: pwnlib.config
@@ -1,16 +1,33 @@
 .. testsetup:: *

-   import pwnlib
-   from   pwnlib.context import context
-   import threading, logging
-
+   from pwn import *
+   import logging
+   log = pwnlib.log.getLogger('pwnlib.context')
+   context.clear()

 :mod:`pwnlib.context` --- Setting runtime variables
 =====================================================

-.. autodata:: pwnlib.context.context
+Many settings in ``pwntools`` are controlled via the global variable :data:`.context`, such as the selected target operating system, architecture, and bit-width.

-.. autoclass:: pwnlib.context.ContextType
-    :members:
+In general, exploits will start with something like:

-.. autoclass:: pwnlib.context.Thread
+.. code-block:: python
+
+    from pwn import *
+    context.arch = 'amd64'
+
+Which sets up everything in the exploit for exploiting a 64-bit Intel binary.
+
+The recommended method is to use ``context.binary``  to automagically set all of the appropriate values.
+
+.. code-block:: python
+
+    from pwn import *
+    context.binary = './challenge-binary'
+
+Module Members
+----------------------------------------------------
+
+.. automodule:: pwnlib.context
+   :members:
@@ -3,8 +3,16 @@
   from pwnlib.elf import *
   from pwnlib.util.misc import which

-:mod:`pwnlib.elf` --- Working with ELF binaries
-===============================================
+:mod:`pwnlib.elf` --- ELF Executables and Libraries
+===================================================

 .. automodule:: pwnlib.elf
-   :members:
+
+
+ELF Modules
+-------------------
+
+.. toctree::
+    elf/elf
+    elf/config
+    elf/corefile
@@ -0,0 +1,10 @@
+.. testsetup:: *
+
+   from pwn import *
+   from pwnlib.elf.config import parse_kconfig
+
+:mod:`pwnlib.elf.config` --- Kernel Config Parsing
+===========================================================
+
+.. automodule:: pwnlib.elf.config
+  :members:
@@ -0,0 +1,16 @@
+.. testsetup:: *
+
+   from glob import glob
+   from pwn import *
+
+:mod:`pwnlib.elf.corefile` --- Core Files
+===========================================================
+
+.. automodule:: pwnlib.elf.corefile
+
+  .. autoclass:: pwnlib.elf.corefile.Corefile
+     :members:
+     :show-inheritance:
+
+  .. autoclass:: pwnlib.elf.corefile.Mapping
+     :members:
@@ -0,0 +1,28 @@
+.. testsetup:: *
+
+   from pwn import *
+   from glob import glob
+
+:mod:`pwnlib.elf.elf` --- ELF Files
+===========================================================
+
+.. automodule:: pwnlib.elf.elf
+
+  .. autoclass:: pwnlib.elf.elf.ELF
+     :members:
+     :show-inheritance:
+     :inherited-members:
+     :exclude-members: address_offsets,
+                       get_data,
+                       get_dwarf_info,
+                       get_section,
+                       get_segment,
+                       has_dwarf_info,
+                       iter_sections,
+                       iter_segments
+
+  .. autoclass:: pwnlib.elf.elf.Function
+     :members:
+
+  .. autoclass:: pwnlib.elf.elf.dotdict
+     :members:
@@ -0,0 +1,25 @@
+.. testsetup:: *
+
+   from pwn import *
+
+:mod:`pwnlib.encoders` --- Encoding Shellcode
+===============================================
+
+.. automodule:: pwnlib.encoders
+   :members:
+
+.. automodule:: pwnlib.encoders.encoder
+   :members:
+
+
+.. automodule:: pwnlib.encoders.amd64
+   :members:
+
+.. automodule:: pwnlib.encoders.arm
+   :members:
+
+.. automodule:: pwnlib.encoders.i386
+   :members:
+
+.. automodule:: pwnlib.encoders.i386.xor
+   :members:
@@ -0,0 +1,10 @@
+.. testsetup:: *
+
+   from pwn import *
+
+
+:mod:`pwnlib.flag` --- CTF Flag Management
+==========================================
+
+.. automodule:: pwnlib.flag
+   :members:
@@ -0,0 +1,10 @@
+.. testsetup:: *
+
+	from pwn import *
+	import tempfile
+
+:mod:`pwnlib.fmtstr` --- Format string bug exploitation tools
+=============================================================
+
+.. automodule:: pwnlib.fmtstr
+   :members:
@@ -1,3 +1,7 @@
+.. testsetup:: *
+
+    from pwn import *
+
 :mod:`pwnlib.gdb` --- Working with GDB
 ======================================

@@ -13,11 +13,11 @@ Which imports a bazillion things into the global namespace to make your life eas

 This is a quick list of most of the objects and routines imported, in rough order of importance and frequency of use.

- ``context``
+- :mod:`pwnlib.context`
    - :data:`pwnlib.context.context`
    - Responsible for most of the pwntools convenience settings
    - Set `context.log_level = 'debug'` when troubleshooting your exploit
-    - Scope-aware, so you can disable logging for a subsection of code via ``pwnlib.context.ContextType.local``
+    - Scope-aware, so you can disable logging for a subsection of code via :meth:`.ContextType.local`
 - ``remote``, ``listen``, ``ssh``, ``process``
    - :mod:`pwnlib.tubes`
    - Super convenient wrappers around all of the common functionality for CTF challenges
@@ -57,11 +57,11 @@ This is a quick list of most of the objects and routines imported, in rough orde
 - ``gdb.debug`` and ``gdb.attach``
    - :mod:`pwnlib.gdb`
    - Launch a binary under GDB and pop up a new terminal to interact with it.  Automates setting breakpoints and makes iteration on exploits MUCH faster.
-    - Alternately, attach to a running process given a PID, ``pwnlib.tubes`` object, or even just a socket that's connected to it
+    - Alternately, attach to a running process given a PID, :mod:`pwnlib.tubes` object, or even just a socket that's connected to it
 - ``args``
-    - Dictionary contining all-caps command-line arguments for quick access
+    - Dictionary containing all-caps command-line arguments for quick access
    - Run via ``python foo.py REMOTE=1`` and ``args['REMOTE'] == '1'``.
-    - Can also control logging verbosity and terminal fancyness
+    - Can also control logging verbosity and terminal fanciness
        - `NOTERM`
        - `SILENT`
        - `DEBUG`
@@ -78,7 +78,7 @@ This is a quick list of most of the objects and routines imported, in rough orde
    - It's the new ``getch``
 - ``safeeval``
    - :mod:`pwnlib.util.safeeval`
-    - Functions for safely evalutaing python code without nasty side-effects.
+    - Functions for safely evaluating python code without nasty side-effects.

 These are all pretty self explanatory, but are useful to have in the global namespace.

@@ -5,6 +5,20 @@ pwntools
 Written in Python, it is designed for rapid prototyping and development,
 and intended to make exploit writing as simple as possible.

+The primary location for this documentation is at docs.pwntools.com_, which uses
+readthedocs_. It comes in three primary flavors:
+
+- Stable_
+- Beta_
+- Dev_
+
+.. _readthedocs: https://readthedocs.org
+.. _docs.pwntools.com: https://docs.pwntools.com
+.. _Stable: https://docs.pwntools.com/en/stable
+.. _Beta: https://docs.pwntools.com/en/beta
+.. _Dev: https://docs.pwntools.com/en/dev
+
+
 Getting Started
 ---------------

@@ -28,30 +42,51 @@ Each of the ``pwntools`` modules is documented here.
   :maxdepth: 1
   :glob:

+   adb
+   args
   asm
   atexception
   atexit
   constants
+   config
   context
   dynelf
+   encoders
   elf
   exception
+   flag
+   fmtstr
   gdb
+   libcdb
   log
   memleak
+   protocols
+   qemu
   replacements
   rop
+   rop/*
+   runner
   shellcraft
+   shellcraft/*
   term
   timeout
   tubes
+   tubes/*
   ui
+   update
   useragents
   util/*

-Indices and tables
-==================
+.. toctree::
+   :hidden:

-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   testexample
+
+.. only:: not dash
+
+   Indices and tables
+   ==================
+
+   * :ref:`genindex`
+   * :ref:`modindex`
+   * :ref:`search`
@@ -20,27 +20,23 @@ following system libraries installed.
 Released Version
 -----------------

-Pwntools is available as a ``pip`` package.
+pwntools is available as a ``pip`` package.

 .. code-block:: bash

-    $ apt-get install python2.7 python2.7-dev python-pip
-    $ pip install pwntools
+    $ apt-get update
+    $ apt-get install python2.7 python-pip python-dev git libssl-dev libffi-dev build-essential
+    $ pip install --upgrade pip
+    $ pip install --upgrade pwntools

-Latest Version
+Development
 --------------

-Alternatively if you prefer to use the latest version from the
-repository:
+If you are hacking on Pwntools locally, you'll want to do something like this:

 .. code-block:: bash

    $ git clone https://github.com/Gallopsled/pwntools
-    $ cd pwntools
-    $ pip install -e .
+    $ pip install --upgrade --editable ./pwntools

 .. _Ubuntu: https://launchpad.net/~pwntools/+archive/ubuntu/binutils
-.. _libcapstone 2.1: http://www.capstone-engine.org
-.. _i386: http://www.capstone-engine.org/download/2.1.2/capstone-2.1.2_i386.deb
-.. _amd64: http://www.capstone-engine.org/download/2.1.2/capstone-2.1.2_amd64.deb
-
@@ -7,15 +7,20 @@ installed. We've made this process as smooth as we can.

 In these examples, replace ``$ARCH`` with your target architecture (e.g., arm, mips64, vax, etc.).

+Building `binutils` from source takes about 60 seconds on a modern 8-core machine.
+
 Ubuntu
 ^^^^^^^^^^^^^^^^
-First, add our `Personal Package Archive repository <http://binutils.pwntools.com>`__.
+
+For Ubuntu 12.04 through 15.10, you must first add the pwntools `Personal Package Archive repository <http://binutils.pwntools.com>`__.
+
+Ubuntu Xenial (16.04) has official packages for most architectures, and does not require this step.

 .. code-block:: bash

    $ apt-get install software-properties-common
    $ apt-add-repository ppa:pwntools/binutils
-    $ apt-get updatez
+    $ apt-get update

 Then, install the binutils for your architecture.

@@ -56,8 +61,6 @@ OSes, ``binutils`` is simple to build by hand.
    gpg --keyserver keys.gnupg.net --recv-keys 4AE55E93
    gpg --verify binutils-$V.tar.gz.sig

-    rm -rf binutils-*
-
    tar xf binutils-$V.tar.gz

    mkdir binutils-build
@@ -77,6 +80,6 @@ OSes, ``binutils`` is simple to build by hand.
    MAKE=gmake
    hash gmake || MAKE=make

-    $MAKE -j
+    $MAKE -j clean all
    sudo $MAKE install

@@ -1,27 +0,0 @@
-Capstone
-------------
-
-Capstone is a disassembly library required for gathering ROP gadgets
-and ROP chain generation.
-
-It's a separate requirement from ``binutils`` because it's used by
-Jon Salwan's ``ROPgadget`` tool which we use under the covers.
-
-In particular, version ``2.1.2`` should be used.  Capstone can be downloaded here_, or installed with the steps below.
-
-Ubuntu
-^^^^^^^^^^^^^^^^
-
-.. code-block:: bash
-
-    $ wget -nc http://www.capstone-engine.org/download/2.1.2/capstone-2.1.2_amd64.deb
-    $ apt-get install capstone-2.1.2_amd64.deb
-
-Mac OS X
-^^^^^^^^^^^^^^^^
-
-.. code-block:: bash
-
-    $ brew install capstone
-
-.. _here:  http://www.capstone-engine.org/download.html
@@ -1,5 +1,5 @@
 Python Development Headers
-------------
+-----------------------------

 Some of pwntools' Python dependencies require native extensions (for example, Paramiko requires PyCrypto).

@@ -27,7 +27,7 @@ This exposes a standard interface to talk to processes, sockets, serial ports,
 and all manner of things, along with some nifty helpers for common tasks.
 For example, remote connections via :mod:`pwnlib.tubes.remote`.

-    >>> conn = remote('ftp.debian.org',21)
+    >>> conn = remote('ftp.ubuntu.com',21)
    >>> conn.recvline() # doctest: +ELLIPSIS
    '220 ...'
    >>> conn.send('USER anonymous\r\n')
@@ -67,12 +67,12 @@ actually **interact** with processes.

 There's even an SSH module for when you've got to SSH into a box to perform
 a local/setuid exploit with :mod:`pwnlib.tubes.ssh`.  You can quickly spawn
-processes and grab the output, or spawn a process and interact iwth it like
+processes and grab the output, or spawn a process and interact with it like
 a ``process`` tube.

 ::

-    >>> shell = ssh('bandit0', 'bandit.labs.overthewire.org', password='bandit0')
+    >>> shell = ssh('bandit0', 'bandit.labs.overthewire.org', password='bandit0', port=2220)
    >>> shell['whoami']
    'bandit0'
    >>> shell.download_file('/etc/motd')
@@ -170,14 +170,14 @@ But if you do, it's easy to suss out!
       5:   eb f9                   jmp    0x0

 However, you shouldn't even need to write your own shellcode most of the
-time!  Pwntools comes with the :mod:`pwnlib.shellcraft` module, which is
+time!  pwntools comes with the :mod:`pwnlib.shellcraft` module, which is
 loaded with useful time-saving shellcodes.

 Let's say that we want to `setreuid(getuid(), getuid())` followed by `dup`ing
 file descriptor 4 to `stdin`, `stdout`, and `stderr`, and then pop a shell!

-    >>> asm(shellcraft.setreuid() + shellcraft.dupsh(4)).encode('hex')
-    '6a3158cd8089c389d96a4658cd806a045b6a0359496a3f58cd8075f86a68682f2f2f73682f62696e89e331c96a0b5899cd80'
+    >>> asm(shellcraft.setreuid() + shellcraft.dupsh(4)).encode('hex') # doctest: +ELLIPSIS
+    '6a3158cd80...'


 Misc Tools
@@ -190,7 +190,7 @@ Find offsets in your buffer that cause a crash, thanks to :mod:`pwnlib.cyclic`.

    >>> print cyclic(20)
    aaaabaaacaaadaaaeaaa
-    >>> # Assume EIP = 0x62616166 ('faab') at crash time
+    >>> # Assume EIP = 0x62616166 ('faab' which is pack(0x62616166))  at crash time
    >>> print cyclic_find('faab')
    120

@@ -212,8 +212,8 @@ Stop hard-coding things!  Look them up at runtime with :mod:`pwnlib.elf`.
 You can even patch and save the files.

    >>> e = ELF('/bin/cat')
-    >>> e.read(e.address+1, 3)
-    'ELF'
+    >>> e.read(e.address, 4)
+    '\x7fELF'
    >>> e.asm(e.address, 'ret')
    >>> e.save('/tmp/quiet-cat')
    >>> disasm(file('/tmp/quiet-cat','rb').read(1))
@@ -0,0 +1,10 @@
+.. testsetup:: *
+
+   from pwn import *
+   from pwnlib.libcdb import *
+
+:mod:`pwnlib.libcdb` --- Libc Database
+===========================================
+
+.. automodule:: pwnlib.libcdb
+   :members:
@@ -1,7 +1,21 @@
-:mod:`pwnlib.log` and   --- Logging stuff
-=================================================================
+:mod:`pwnlib.log` --- Logging stuff
+===================================

 .. automodule:: pwnlib.log
+   :members: getLogger, install_default_handler, rootlogger
+
+.. autoclass:: pwnlib.log.Progress
+   :members:
+   :member-order: bysource

 .. autoclass:: pwnlib.log.Logger
-   :members: debug, info, warn, error, progress, success, failure, indented, info_once, warn_once
+   :members:
+   :member-order: bysource
+
+.. autoclass:: pwnlib.log.Handler
+   :members:
+   :member-order: bysource
+
+.. autoclass:: pwnlib.log.Formatter
+   :members:
+   :member-order: bysource
@@ -1,11 +1,9 @@
 .. testsetup:: *

-   from pwnlib.memleak import *
+    from pwn import *

 :mod:`pwnlib.memleak` --- Helper class for leaking memory
 =========================================================

-.. module:: pwnlib.memleak
-
-.. autoclass:: MemLeak
-   :members:
+.. automodule:: pwnlib.memleak
+    :members:
@@ -0,0 +1,15 @@
+:mod:`pwnlib.protocols` --- Wire Protocols
+=============================================
+
+.. automodule:: pwnlib.protocols
+
+
+Supported Protocols
+-------------------
+
+.. toctree::
+    :maxdepth: 3
+    :glob:
+
+    protocols/*
+
@@ -0,0 +1,10 @@
+.. testsetup:: *
+
+   from pwn import *
+   from pwnlib.protocols.adb import AdbClient
+
+:mod:`pwnlib.protocols.adb` --- ADB Protocol Implementation
+===========================================================
+
+.. automodule:: pwnlib.protocols.adb
+   :members:
@@ -0,0 +1,10 @@
+.. testsetup:: *
+
+   from pwn import *
+
+
+:mod:`pwnlib.qemu` --- QEMU Utilities
+==========================================
+
+.. automodule:: pwnlib.qemu
+   :members:
@@ -1,11 +1,14 @@
 .. testsetup:: *

-   from pwnlib.elf import *
-   from pwnlib.rop import *
-   from pwnlib.util.misc import which
+   from pwn import *

 :mod:`pwnlib.rop` --- Return Oriented Programming
 =================================================

-.. automodule:: pwnlib.rop
-   :members:
+Submodules
+----------
+
+.. toctree::
+   :glob:
+
+   rop/*
@@ -0,0 +1,9 @@
+.. testsetup:: *
+
+   from pwn import *
+
+:mod:`pwnlib.rop.rop` --- Return Oriented Programming
+==========================================================
+
+.. automodule:: pwnlib.rop.rop
+   :members:
@@ -0,0 +1,9 @@
+.. testsetup:: *
+
+   from pwn import *
+
+:mod:`pwnlib.rop.srop` --- Sigreturn Oriented Programming
+==========================================================
+
+.. automodule:: pwnlib.rop.srop
+   :members:
@@ -0,0 +1,9 @@
+.. testsetup:: *
+
+   from pwn import *
+
+:mod:`pwnlib.runner` --- Running Shellcode
+===========================================
+
+.. automodule:: pwnlib.runner
+   :members:
@@ -0,0 +1,19 @@
+.. testsetup:: *
+
+   from pwn import *
+   context.clear(arch='aarch64')
+
+:mod:`pwnlib.shellcraft.aarch64` --- Shellcode for AArch64
+===========================================================
+
+:mod:`pwnlib.shellcraft.aarch64`
+--------------------------------
+
+.. automodule:: pwnlib.shellcraft.aarch64
+   :members:
+
+:mod:`pwnlib.shellcraft.aarch64.linux`
+--------------------------------------
+
+.. automodule:: pwnlib.shellcraft.aarch64.linux
+   :members:
@@ -1,6 +1,7 @@
 .. testsetup:: *

   from pwn import *
+   context.clear(arch='amd64')

 :mod:`pwnlib.shellcraft.amd64` --- Shellcode for AMD64
 ===========================================================
@@ -1,6 +1,7 @@
 .. testsetup:: *

   from pwn import *
+   context.clear(arch='arm')

 :mod:`pwnlib.shellcraft.arm` --- Shellcode for ARM
 ===========================================================
@@ -1,6 +1,7 @@
 .. testsetup:: *

   from pwn import *
+   context.clear(arch='i386')

 :mod:`pwnlib.shellcraft.i386` --- Shellcode for Intel 80386
 ===========================================================
@@ -0,0 +1,19 @@
+.. testsetup:: *
+
+   from pwn import *
+   context.clear(arch='mips')
+
+:mod:`pwnlib.shellcraft.mips` --- Shellcode for MIPS
+===========================================================
+
+:mod:`pwnlib.shellcraft.mips`
+-----------------------------
+
+.. automodule:: pwnlib.shellcraft.mips
+   :members:
+
+:mod:`pwnlib.shellcraft.mips.linux`
+-----------------------------------
+
+.. automodule:: pwnlib.shellcraft.mips.linux
+   :members:
@@ -0,0 +1,9 @@
+.. testsetup:: *
+
+    from pwnlib.regsort import *
+
+:mod:`pwnlib.regsort` --- Register sorting
+===========================================================
+
+.. automodule:: pwnlib.regsort
+   :members:
@@ -1,6 +1,7 @@
 .. testsetup:: *

   from pwn import *
+   context.clear(arch='thumb')

 :mod:`pwnlib.shellcraft.thumb` --- Shellcode for Thumb Mode
 ===========================================================
@@ -0,0 +1,10 @@
+.. testsetup:: *
+
+   import os
+   from pwnlib.testexample import add
+
+:mod:`pwnlib.testexample` --- Example Test Module
+==================================================
+
+.. automodule:: pwnlib.testexample
+   :members:
@@ -5,7 +5,7 @@
   import time

 :mod:`pwnlib.timeout` --- Timeout handling
-========================================
+============================================

 .. automodule:: pwnlib.timeout
   :members:
@@ -1,69 +1,30 @@
 .. testsetup:: *

-   from pwnlib.tubes.tube import tube
-   from pwnlib.tubes.ssh import *
-   from pwnlib.tubes.remote import remote
-   from pwnlib.util.misc import which
-   from pwnlib.context import context
+   from pwn import *

 :mod:`pwnlib.tubes` --- Talking to the World!
 =============================================

 .. automodule:: pwnlib.tubes

-   Sockets
-   -------

-   .. automodule:: pwnlib.tubes.remote
+Types of Tubes
+-------------------

-      .. autoclass:: pwnlib.tubes.remote.remote
-         :members:
-         :show-inheritance:
+.. toctree::
+    :maxdepth: 3
+    :glob:

-   .. automodule:: pwnlib.tubes.listen
+    tubes/*

-      .. autoclass:: pwnlib.tubes.listen.listen
-         :members:
-         :show-inheritance:

-   .. automodule:: pwnlib.tubes.sock
+:mod:`pwnlib.tubes.tube` --- Common Functionality
+-------------------------------------------------

-      .. autoclass:: pwnlib.tubes.sock.sock()
-         :show-inheritance:

-   Processes
-   ---------
+.. automodule:: pwnlib.tubes.tube

-   .. automodule:: pwnlib.tubes.process
-
-      .. autoclass:: pwnlib.tubes.process.process
-         :members: kill, poll, communicate
-         :show-inheritance:
-
-   SSH
-   ---
-
-   .. automodule:: pwnlib.tubes.ssh
-
-      .. autoclass:: pwnlib.tubes.ssh.ssh
-         :members:
-
-      .. autoclass:: pwnlib.tubes.ssh.ssh_channel()
-         :members: kill, poll, interactive
-         :show-inheritance:
-
-      .. autoclass:: pwnlib.tubes.ssh.ssh_connecter()
-         :show-inheritance:
-
-      .. autoclass:: pwnlib.tubes.ssh.ssh_listener()
-         :show-inheritance:
-
-   Common functionality
-   --------------------
-
-   .. automodule:: pwnlib.tubes.tube
-
-      .. autoclass:: pwnlib.tubes.tube.tube()
-         :members:
-         :exclude-members: recv_raw, send_raw, settimeout_raw,
-                           can_recv_raw
+  .. autoclass:: pwnlib.tubes.tube.tube()
+     :members:
+     :exclude-members: recv_raw, send_raw, settimeout_raw,
+                       can_recv_raw, shutdown_raw, connected_raw,
@@ -0,0 +1,12 @@
+.. testsetup:: *
+
+   from pwn import *
+
+:mod:`pwnlib.tubes.process` --- Processes
+===========================================================
+
+.. automodule:: pwnlib.tubes.process
+
+  .. autoclass:: pwnlib.tubes.process.process
+     :members:
+     :show-inheritance:
@@ -0,0 +1,11 @@
+.. testsetup:: *
+
+   from pwn import *
+
+:mod:`pwnlib.tubes.serialtube` --- Serial Ports
+===========================================================
+
+.. automodule:: pwnlib.tubes.serialtube
+
+   .. autoclass:: pwnlib.tubes.serialtube.serialtube
+      :members:
@@ -0,0 +1,32 @@
+.. testsetup:: *
+
+   from pwn import *
+   from pwnlib.tubes.server import server
+
+:mod:`pwnlib.tubes.sock` --- Sockets
+===========================================================
+
+
+.. automodule:: pwnlib.tubes.sock
+
+   .. autoclass:: pwnlib.tubes.sock.sock()
+      :show-inheritance:
+
+
+.. automodule:: pwnlib.tubes.remote
+
+   .. autoclass:: pwnlib.tubes.remote.remote
+      :members:
+      :show-inheritance:
+
+.. automodule:: pwnlib.tubes.listen
+
+   .. autoclass:: pwnlib.tubes.listen.listen
+      :members:
+      :show-inheritance:
+
+.. automodule:: pwnlib.tubes.server
+
+   .. autoclass:: pwnlib.tubes.server.server
+      :members:
+      :show-inheritance:
@@ -0,0 +1,21 @@
+.. testsetup:: *
+
+   from pwn import *
+
+:mod:`pwnlib.tubes.ssh` --- SSH
+===========================================================
+
+.. automodule:: pwnlib.tubes.ssh
+
+   .. autoclass:: pwnlib.tubes.ssh.ssh
+      :members:
+
+   .. autoclass:: pwnlib.tubes.ssh.ssh_channel()
+      :members: kill, poll, interactive
+      :show-inheritance:
+
+   .. autoclass:: pwnlib.tubes.ssh.ssh_connecter()
+      :show-inheritance:
+
+   .. autoclass:: pwnlib.tubes.ssh.ssh_listener()
+      :show-inheritance:
@@ -0,0 +1,10 @@
+.. testsetup:: *
+
+   from pwn import *
+   from pwnlib.update import *
+
+:mod:`pwnlib.update` --- Updating Pwntools
+===================================================
+
+.. automodule:: pwnlib.update
+   :members:
@@ -1,5 +1,6 @@
 .. testsetup:: *

+   from pwn import *
   from pwnlib.util.cyclic import *


@@ -1,6 +1,7 @@
 .. testsetup:: *

-   from pwnlib.util.fiddling import *
+    from pwn import *
+    from pwnlib.util.fiddling import *


 :mod:`pwnlib.util.fiddling` --- Utilities bit fiddling
@@ -1,6 +1,7 @@
 .. testsetup:: *

   from pwnlib.util.proc import *
+   from pwnlib.tubes.process import process
   import os, sys


@@ -1,6 +1,7 @@
 .. testsetup:: *

   from pwnlib.util.safeeval import *
+   _get_opcodes = pwnlib.util.safeeval._get_opcodes


 :mod:`pwnlib.util.safeeval` --- Safe evaluation of python code
@@ -0,0 +1,10 @@
+.. testsetup:: *
+
+   from pwn import *
+   test = pwnlib.util.sh_string.test
+
+:mod:`pwnlib.util.sh_string` --- Shell Expansion is Hard
+===============================================================
+
+.. automodule:: pwnlib.util.sh_string
+   :members:
@@ -4,7 +4,7 @@ the pwntools project.

 We have a plan to create a separate repository with examples, primarily
 exploits. Until we do so, we recommend new users to look at
-https://pwntools.readthedocs.org, as this is a better overview of our features.
+https://docs.pwntools.com, as this is a better overview of our features.

 In no particular order the docstrings for each example:

@@ -0,0 +1,22 @@
+from pwn import *
+
+# Tell pwntools that the target is an Android device
+context.os='android'
+context.arch='aarch64' # or 'arm'
+
+# Optionally, set the remote ADB server address
+context.adb_host='172.16.110.1'
+
+# Wait for a device to become available
+print adb.wait_for_device()
+
+# Who am I?
+print adb.process('id').recvall().strip()
+
+# Interactive sessions!
+io = adb.shell()
+io.sendline('echo Hello, world; exit')
+print io.recvall().replace('\r\n', '\n').strip()
+
+# Debugging!
+gdb.debug('sh').interactive()
@@ -3,7 +3,8 @@ Example showing the interface to `pwnlib.asm.asm` and `pwnlib.shellcraft`.
 """

 from pwn import *
-context(arch='i386', os='linux', net='tcp4')
+
+context(arch='i386', os='linux')

 shellcode = shellcraft.i386_to_amd64()
 shellcode_asm = asm(shellcode)
@@ -0,0 +1,12 @@
+"""
+Example showing `pwnlib.gdb.attach()`
+"""
+
+from pwn import *
+
+bash = process('/bin/bash')
+gdb.attach(bash, execute = '''
+p "hello from pwnlib"
+c
+''')
+bash.interactive()
@@ -26,4 +26,3 @@ atexit.register(r.clean_and_log)
 while True:
    line = r.recvline()
    print re.findall('^prefix (\S+)$', line)[0]
-
@@ -4,13 +4,14 @@ Script to generate README.md

 from pwn import *

+
 out = '''# Examples
 While these examples should all work, they are not very representative of
 the pwntools project.

 We have a plan to create a separate repository with examples, primarily
 exploits. Until we do so, we recommend new users to look at
-https://pwntools.readthedocs.org, as this is a better overview of our features.
+https://docs.pwntools.com, as this is a better overview of our features.

 In no particular order the docstrings for each example:

@@ -5,8 +5,8 @@ off some proof-of-concepts.
 """

 from pwn import *
-from pwnlib.term.completer import LongestPrefixCompleter, \
-                                  PathCompleter
+from pwnlib.term.completer import LongestPrefixCompleter
+from pwnlib.term.completer import PathCompleter

 c1 = LongestPrefixCompleter([
    'foobar',
@@ -3,9 +3,10 @@ Simple example showing how to use the remote
 gdb debugging features available in pwntools.
 """

-from pwn import *
 import getpass

+from pwn import *
+
 s = ssh(getpass.getuser(), '127.0.0.1', port = 22, keyfile = "~/.ssh/id_rsa")
 c = gdb.ssh_gdb(s, '/bin/sh', execute = '''
 p/x $pc
@@ -0,0 +1,31 @@
+from pwn import *
+context.arch='aarch64'
+frame = SigreturnFrame()
+
+registers = ['x%i' % i for i in range(0, 31)]
+registers += ['sp', 'pc']
+
+
+for index, register in enumerate(registers):
+    setattr(frame, register, index)
+
+assembly = '\n'.join([
+    shellcraft.read(constants.STDIN_FILENO, 'sp', 1024),
+    shellcraft.syscall(constants.SYS_rt_sigreturn)
+])
+
+binary = ELF.from_assembly(assembly)
+
+io = binary.process()
+io.flat(frame)
+io.wait()
+assert io.poll() == -11
+
+corefile = io.corefile
+
+for index, register in enumerate(registers):
+    value = getattr(corefile, register)
+    if index != value:
+        log.error("%s != %i (%i)" % (register, index, value))
+    else:
+        log.success("%s == %i" % (register, value))
@@ -0,0 +1,32 @@
+from pwn import *
+context.arch='amd64'
+frame = SigreturnFrame()
+
+registers = ['rax', 'rbx', 'rcx', 'rdx',
+             'rdi', 'rsi', 'rbp', 'rsp',
+             'rip',
+             'r8', 'r9', 'r10', 'r11', 'r12', 'r13', 'r14', 'r15']
+
+for index, register in enumerate(registers):
+    setattr(frame, register, index)
+
+assembly = '\n'.join([
+    shellcraft.read(constants.STDIN_FILENO, 'rsp', 1024),
+    shellcraft.sigreturn()
+])
+
+binary = ELF.from_assembly(assembly)
+
+io = binary.process()
+io.flat(frame)
+io.wait()
+assert io.poll() == -11
+
+corefile = io.corefile
+
+for index, register in enumerate(registers):
+    value = getattr(corefile, register)
+    if index != value:
+        log.error("%s != %i (%i)" % (register, index, value))
+    else:
+        log.success("%s == %i" % (register, value))
@@ -0,0 +1,32 @@
+from pwn import *
+
+context.arch='arm'
+frame = SigreturnFrame()
+
+registers = ['r0', 'r1', 'r2', 'r3', 'r4', 'r5', 'r6', 'r7',
+             'r8', 'r9', 'r10', 'fp', 'ip', 'sp', 'pc', 'lr']
+
+
+for index, register in enumerate(registers):
+    setattr(frame, register, index)
+
+assembly = '\n'.join([
+    shellcraft.read(constants.STDIN_FILENO, 'sp', 1024),
+    shellcraft.sigreturn()
+])
+
+binary = ELF.from_assembly(assembly)
+
+io = binary.process()
+io.flat(frame)
+io.wait()
+assert io.poll() == -11
+
+corefile = io.corefile
+
+for index, register in enumerate(registers):
+    value = getattr(corefile, register)
+    if index != value:
+        log.error("%s != %i (%i)" % (register, index, value))
+    else:
+        log.success("%s == %i" % (register, value))
@@ -0,0 +1,31 @@
+from pwn import *
+context.kernel='amd64'
+frame = SigreturnFrame()
+
+registers = ['eax', 'ebx', 'ecx', 'edx',
+             'edi', 'esi', 'ebp', 'esp',
+             'eip']
+
+for index, register in enumerate(registers):
+    setattr(frame, register, index)
+
+assembly = '\n'.join([
+    shellcraft.read(constants.STDIN_FILENO, 'esp', 1024),
+    shellcraft.sigreturn()
+])
+
+binary = ELF.from_assembly(assembly)
+
+io = binary.process()
+io.flat(frame)
+io.wait()
+assert io.poll() == -11
+
+corefile = io.corefile
+
+for index, register in enumerate(registers):
+    value = getattr(corefile, register)
+    if index != value:
+        log.error("%s != %i (%i)" % (register, index, value))
+    else:
+        log.success("%s == %i" % (register, value))
@@ -4,7 +4,7 @@ Example showing how to use the ssh class.

 from pwn import *

-shell = ssh(host='bandit.labs.overthewire.org',user='bandit0',password='bandit0')
+shell = ssh(host='bandit.labs.overthewire.org',user='bandit0',password='bandit0', port=2220)

 # Show basic command syntax
 log.info("username: %s" % shell.whoami())
@@ -0,0 +1,10 @@
+"""
+Example showing `pwnlib.ui.yesno()`
+"""
+
+from pwn import *
+
+if ui.yesno('Do you like Pwntools?'):
+    print ':D'
+else:
+    print ':('
@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# cache list of shellcodes
+_shellcraft_shellcodes=$(pwn shellcraft -l)
+
+_shellcraft()
+{
+    COMPREPLY=()
+    local cur prev opts word code
+    cur="${COMP_WORDS[COMP_CWORD]}"
+    prev="${COMP_WORDS[COMP_CWORD-1]}"
+    opts="-h --help -? --show -o --out -f --format"
+
+    if [ "${prev}" == "-f" -o    \
+         "${prev}" == "--format" \
+        ] ; then
+        opts="raw str c hex asm p hexii"
+        COMPREPLY=( $(compgen -W "${opts}" -- ${cur}))
+        return 0
+    fi
+
+    if [ "${prev}" == "-o" -o \
+         "${prev}" == "--out" \
+        ] ; then
+        COMPREPLY=( $(compgen -f ${cur}))
+        return 0
+    fi
+
+    if [[ "${cur}" == -* ]] ; then
+        COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) )
+        return 0
+    fi
+
+    # check if a shellcode was already chosen
+    for word in "${COMP_WORDS[@]}" ; do
+        for code in ${_shellcraft_shellcodes} ; do
+            if [ "${word}" == "${code}" ] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) )
+                return 0
+            fi
+        done
+    done
+
+    # complete shellcode name
+    COMPREPLY=( $(compgen -W "${_shellcraft_shellcodes}" -- ${cur}) )
+}
+
+complete -F _shellcraft pwn shellcraft
+complete -F _shellcraft shellcraft
@@ -0,0 +1,13 @@
+subdirs=xenial stable $(wildcard */)
+makefiles=$(wildcard */Makefile)
+tags=base stable beta dev
+
+all: $(makefiles) $(subdirs)
+
+$(subdirs):
+	docker build -t pwntools/pwntools:$(shell basename $(@)) "$@"
+
+$(makefiles):
+	make -C $(shell dirname $@)
+
+.PHONY: all $(subdirs) $(makefiles)
@@ -0,0 +1 @@
+xenial
@@ -0,0 +1,6 @@
+FROM pwntools/pwntools:stable
+
+USER root
+RUN pip install --upgrade git+https://github.com/Gallopsled/pwntools@beta
+RUN PWNLIB_NOTERM=1 pwn update
+USER pwntools
@@ -0,0 +1,6 @@
+FROM pwntools/pwntools:stable
+
+USER root
+RUN pip install --upgrade git+https://github.com/Gallopsled/pwntools@dev
+RUN PWNLIB_NOTERM=1 pwn update
+USER pwntools
@@ -0,0 +1,26 @@
+############################################################
+# Dockerfile to build Pwntools container
+# Based on Ubuntu
+############################################################
+
+FROM kalilinux/kali-linux-docker
+MAINTAINER Maintainer Gallopsled et al.
+
+RUN apt-get update
+RUN apt-get install -y build-essential
+RUN apt-get install -y git
+RUN apt-get install -y libssl-dev
+RUN apt-get install -y libffi-dev
+RUN apt-get install -y python2.7
+RUN apt-get install -y python-pip
+RUN apt-get install -y python-dev
+RUN pip install --upgrade pip
+RUN python -m pip install --upgrade pwntools
+RUN PWNLIB_NOTERM=1 pwn update
+
+RUN apt-get install -y sudo
+RUN useradd -m pwntools
+RUN passwd --delete --unlock pwntools
+RUN echo "pwntools ALL=(ALL:ALL) NOPASSWD: ALL" > /etc/sudoers.d/pwntools
+USER pwntools
+WORKDIR /home/pwntools
@@ -0,0 +1,8 @@
+all: Dockerfile
+
+Dockerfile: ../xenial/Dockerfile FORCE
+	sed "s|ubuntu:xenial|kalilinux/kali-linux-docker|" < "$<" > "$@"
+
+FORCE:
+
+.PHONY: all
@@ -0,0 +1,26 @@
+############################################################
+# Dockerfile to build Pwntools container
+# Based on Ubuntu
+############################################################
+
+FROM ubuntu:precise
+MAINTAINER Maintainer Gallopsled et al.
+
+RUN apt-get update
+RUN apt-get install -y build-essential
+RUN apt-get install -y git
+RUN apt-get install -y libssl-dev
+RUN apt-get install -y libffi-dev
+RUN apt-get install -y python2.7
+RUN apt-get install -y python-pip
+RUN apt-get install -y python-dev
+RUN pip install --upgrade pip
+RUN python -m pip install --upgrade pwntools
+RUN PWNLIB_NOTERM=1 pwn update
+
+RUN apt-get install -y sudo
+RUN useradd -m pwntools
+RUN passwd --delete --unlock pwntools
+RUN echo "pwntools ALL=(ALL:ALL) NOPASSWD: ALL" > /etc/sudoers.d/pwntools
+USER pwntools
+WORKDIR /home/pwntools
@@ -0,0 +1,8 @@
+all: Dockerfile
+
+Dockerfile: ../xenial/Dockerfile FORCE
+	sed "s|ubuntu:xenial|ubuntu:precise|" < "$<" > "$@"
+
+FORCE:
+
+.PHONY: all
@@ -0,0 +1,6 @@
+FROM pwntools/pwntools:base
+
+USER root
+RUN pip install --upgrade git+https://github.com/Gallopsled/pwntools@stable
+RUN PWNLIB_NOTERM=1 pwn update
+USER pwntools
@@ -0,0 +1,26 @@
+############################################################
+# Dockerfile to build Pwntools container
+# Based on Ubuntu
+############################################################
+
+FROM ubuntu:trusty
+MAINTAINER Maintainer Gallopsled et al.
+
+RUN apt-get update
+RUN apt-get install -y build-essential
+RUN apt-get install -y git
+RUN apt-get install -y libssl-dev
+RUN apt-get install -y libffi-dev
+RUN apt-get install -y python2.7
+RUN apt-get install -y python-pip
+RUN apt-get install -y python-dev
+RUN pip install --upgrade pip
+RUN python -m pip install --upgrade pwntools
+RUN PWNLIB_NOTERM=1 pwn update
+
+RUN apt-get install -y sudo
+RUN useradd -m pwntools
+RUN passwd --delete --unlock pwntools
+RUN echo "pwntools ALL=(ALL:ALL) NOPASSWD: ALL" > /etc/sudoers.d/pwntools
+USER pwntools
+WORKDIR /home/pwntools
@@ -0,0 +1,8 @@
+all: Dockerfile
+
+Dockerfile: ../xenial/Dockerfile FORCE
+	sed "s|ubuntu:xenial|ubuntu:trusty|" < "$<" > "$@"
+
+FORCE:
+
+.PHONY: all
@@ -0,0 +1,26 @@
+############################################################
+# Dockerfile to build Pwntools container
+# Based on Ubuntu
+############################################################
+
+FROM ubuntu:xenial
+MAINTAINER Maintainer Gallopsled et al.
+
+RUN apt-get update
+RUN apt-get install -y build-essential
+RUN apt-get install -y git
+RUN apt-get install -y libssl-dev
+RUN apt-get install -y libffi-dev
+RUN apt-get install -y python2.7
+RUN apt-get install -y python-pip
+RUN apt-get install -y python-dev
+RUN pip install --upgrade pip
+RUN python -m pip install --upgrade pwntools
+RUN PWNLIB_NOTERM=1 pwn update
+
+RUN apt-get install -y sudo
+RUN useradd -m pwntools
+RUN passwd --delete --unlock pwntools
+RUN echo "pwntools ALL=(ALL:ALL) NOPASSWD: ALL" > /etc/sudoers.d/pwntools
+USER pwntools
+WORKDIR /home/pwntools
@@ -0,0 +1,19 @@
+# Pwntools Mako Assembly Syntax Highlighting
+
+This should work for TextMate and anything that's compatible (e.g. Sublime Text).
+
+![screenshot](screenshot.png)
+
+## Installation
+
+### Sublime Text
+
+Copy the `tmLanguage` files into the `Packages/User` folder in your Sublime Text configuration folder.  
+
+These folders are located at the paths shown below.  Replace `2` with `3` if you're a ST3 user.
+
+- OS X: `~/Library/Application Support/Sublime Text 2`
+- Windows: `%APPDATA%\Sublime Text 2`
+- Linux: `~/.config/sublime-text-2`
+
+Open a `.asm` file, and choose `View > Syntax > Open All ... > Pwntools ...`.