Release 4.9.0

Fixes #2140
Closes #2098
Closes #2141

.coveragerc

@@ -0,0 +1,12 @@
+[run]
+branch = True
+parallel = True
+concurrency = thread,multiprocessing
+omit =
+    */constants/*
+source =
+    pwn
+    pwnlib
+    ~/.cache/.pwntools-cache-2.7/
+    ~/.cache/.pwntools-cache-3.8/
+disable_warnings = module-not-imported

.github/ISSUE_TEMPLATE.md

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

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,54 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: backport-required, bug
+assignees: ''
+
+---
+
+Thanks for contributing to Pwntools!
+
+## Update Pwntools First
+
+When reporting an issue, be sure that you are running the latest released version of pwntools (`pip install --upgrade pwntools`).
+
+## Debug Output
+
+Having the extra debug output really helps us, and might help you diagnose the problem yourself.
+
+When submitting an issue that has output from Pwntools, make sure to run your script as shown below, to enable the extra debugging data.
+
+```sh
+$ python exploit.py DEBUG LOG_FILE=log.txt
+```
+
+You should see `[DEBUG]` statements that show what's happening behind the scenes:
+
+```
+[+] Starting local process '/bin/sh' argv=['sh'] : pid 16823
+[DEBUG] Sent 0x7 bytes:
+    'whoami\n'
+[DEBUG] Sent 0x5 bytes:
+    'exit\n'
+[+] Receiving all data: Done (11B)
+[DEBUG] Received 0xb bytes:
+    'crashheap\n'
+[*] Process '/bin/sh' stopped with exit code 0 (pid 16823)
+```
+
+## Verify on Ubuntu
+
+If possible, please verify that your issue occurs on 64-bit Ubuntu 18.04.  We provide a Dockerfile based on Ubuntu 18.04 via `docker.io` to make this super simple, no VM required!
+
+```sh
+# Download the Docker image
+$ docker pull pwntools/pwntools:stable
+
+# Boot the image
+$ docker run -it pwntools/pwntools:stable
+
+pwntools@7dc3ef409476:~$ python
+>>> from pwn import *
+>>> # Test your code here
+```

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,18 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: feature
+assignees: ''
+
+---
+
+Thanks for contributing to Pwntools!   Ideas from the community help make Pwntools an amazing tool for everybody.
+
+If you've got an idea for a new feature, please provide information about:
+
+* What the feature does
+* Why the feature should exist
+* What tests should be included
+
+If you think you can write the feature yourself, please submit a Pull Request and we can review your changes!

.github/ISSUE_TEMPLATE/question.md

@@ -0,0 +1,18 @@
+---
+name: Question
+about: Ask us a question about Pwntools
+title: ''
+labels: question
+assignees: ''
+
+---
+
+Thanks for using Pwntools!  If you have a question, here are some tips that will make it easier for us to help you.
+
+## Check the Documentation
+
+Pwntools has REALLY extensive documentation.  Please check there first!  https://docs.pwntools.com
+
+## Debug Output
+
+If you're having an issue with an exploit, run your script with full debugging output, i.e. `python exploit.py DEBUG`.  This may help you to see what's happening under the hood, and the debug output will help to diagnose any issues you're encountering.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,32 @@
+# 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
+
+## Changelog
+
+After creating your Pull Request, please add and push a commit that updates the changelog for the appropriate branch.  
+You can look at the existing changelog for examples of how to do this.

.github/workflows/android.yml

@@ -0,0 +1,60 @@
+name: Android Tests
+
+on: [push, pull_request]
+
+jobs:
+  android-test:
+    strategy:
+      matrix:
+        python-version: [3.8]
+        os: [ubuntu-latest]
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Cache for pip
+      uses: actions/cache@v1
+      id: cache-pip
+      with:
+        path: ~/.cache/pip
+        key: ${{ matrix.os }}-cache-pip
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v1
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install Linux dependencies
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y --no-install-recommends -o Acquire::Retries=3 \
+          gdb gdbserver socat \
+          qemu-user-static \
+          binutils-aarch64-linux-gnu \
+          binutils-arm-linux-gnueabihf \
+          libc6-dbg \
+          openjdk-8-jre-headless
+
+    - name: Install Android AVD
+      run: |
+        USER=travis source travis/setup_avd.sh
+        sed -i 's/skip_android = True/skip_android = False/' docs/source/conf.py
+        set | egrep '^(ANDROID|PATH)' >.android.env
+
+    - name: Install dependencies
+      run: |
+        pip install --upgrade pip
+        python setup.py egg_info
+        pip install --upgrade --editable .
+
+    - name: Sanity checks
+      run:  PWNLIB_NOTERM=1 python -c 'from pwn import *; print(pwnlib.term.term_mode)'
+
+    - name: Install documentation dependencies
+      run:  pip install -r docs/requirements.txt
+
+    - name: Coverage Doctests (Android Only)
+      run: |
+        source .android.env
+        PWNLIB_NOTERM=1 coverage run -m sphinx -b doctest docs/source docs/build/doctest docs/source/adb.rst

.github/workflows/changelog.yml

@@ -0,0 +1,29 @@
+name: Changelog
+on: [pull_request]
+env:
+  GITHUB_BASE: origin/${{ github.event.pull_request.base.ref }}
+
+jobs:
+  check:
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 5
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        fetch-depth: 0
+
+    - name: Check changelog for updates
+      run: |
+        if git log --stat ${GITHUB_BASE}..HEAD | grep CHANGELOG.md; then
+           echo 'Changelog updated :D'
+        else
+           if git log --stat ${GITHUB_BASE}..HEAD pwnlib pwn | grep '++\|--'; then
+              echo 'Major changes detected, changelog required!'
+              false
+           else
+              echo 'Minor changes detected, no changelog required!'
+           fi
+        fi

.github/workflows/ci.yml

@@ -0,0 +1,216 @@
+name: Continuous Integration
+on: [push, pull_request]
+
+jobs:
+  test:
+    strategy:
+      matrix:
+        python-version: [2.7, 3.8]
+        os: [ubuntu-latest]
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        fetch-depth: 0
+
+    - name: Git History
+      run: |
+        git fetch origin
+        git log --oneline --graph -10
+
+    - name: Cache for pip
+      uses: actions/cache@v1
+      id: cache-pip
+      with:
+        path: ~/.cache/pip
+        key: ${{ matrix.os }}-cache-pip
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Verify tag against version
+      if: github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags')
+      env:
+        GITHUB_REF: ${{ github.event.ref }}
+      run: |
+        set -x
+        GITHUB_TAG=${GITHUB_REF#refs/tags/}
+        echo "$GITHUB_TAG" | grep -E '^[0-9.]*(beta[0-9])?$'
+        vsetup=$(grep -o "version\\s*=\\s*[\"'].*[\"'],$" setup.py | grep -o "[0-9][^\"']*")
+        vpwnlib=$(grep -o "__version__\\s*=\\s*[\"'].*[\"']$" pwnlib/version.py | grep -o "[0-9][^\"']*")
+        [ "$vsetup" = "$vpwnlib" ]
+        [ "$GITHUB_TAG" = "$vsetup" ]
+
+    - name: Install Linux dependencies
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y --no-install-recommends -o Acquire::Retries=3 \
+          ash bash-static dash ksh mksh zsh \
+          pandoc gdb gdbserver socat sshpass \
+          binutils-multiarch qemu-user-static \
+          binutils-aarch64-linux-gnu \
+          binutils-arm-linux-gnueabihf \
+          binutils-mips-linux-gnu \
+          binutils-msp430 \
+          binutils-powerpc-linux-gnu \
+          binutils-s390x-linux-gnu \
+          binutils-sparc64-linux-gnu \
+          gcc-multilib \
+          libc6-dbg \
+          elfutils
+      
+    - name: Install RPyC for GDB
+      run: |
+        sudo apt-get install -y python3-pip
+        /usr/bin/python3 -m pip install rpyc
+
+    - name: Testing Corefiles
+      run: |
+        ulimit -a
+        ulimit -c unlimited
+        cat /proc/sys/kernel/core_pattern
+        cat /proc/sys/kernel/core_uses_pid
+        ( cd $(mktemp -d); sh -c 'kill -11 $$' || true; ls -la ./*core* /var/crash/*.crash /var/lib/apport/coredump/core*) || true
+
+    - name: Set up SSH
+      run: |
+        travis/ssh_setup.sh
+
+    - name: Install dependencies
+      run: |
+        pip install --upgrade pip
+        pip install --upgrade wheel
+        pip install --upgrade flake8 appdirs
+        python setup.py egg_info
+        pip install --upgrade --editable .
+
+    - name: Sanity checks
+      run:  PWNLIB_NOTERM=1 python -bb -c 'from pwn import *; print(pwnlib.term.term_mode)'
+
+    - name: Install documentation dependencies
+      run: pip install -r docs/requirements.txt
+
+    - name: Manually install non-broken Unicorn
+      run:  pip install unicorn==1.0.2rc3
+
+    - name: Disable yama ptrace_scope
+      run: |
+        echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope # required by some gdb doctests
+
+    - name: Coverage doctests
+      run: |
+        PWNLIB_NOTERM=1 python -bb -m coverage run -m sphinx -b doctest docs/source docs/build/doctest
+
+    - name: Coverage running examples
+      run: |
+        export TERM=linux
+        set -x
+        python -bb travis/coverage_chdir.py examples/fmtstr examples/fmtstr/exploit.py
+        python -bb travis/coverage_chdir.py examples/fmtstr examples/fmtstr/exploit2.py || : # can fail randomly?
+        python -bb -m coverage run examples/asm.py
+        python -bb -m coverage run examples/asm.py
+        python -bb -m coverage run examples/text.py
+        # for f in examples/sigreturn_corefile_*.py; do coverage run "$f"; done # XXX something is wrong
+
+    - name: Coverage running commandline tools
+      run: |
+        export TERM=linux
+        pwn() { ( set +x; cmd=$1; shift; PYTHONUNBUFFERED=1 exec python -bb -m coverage run -m pwnlib.commandline."$cmd" "$@" ) }
+        set -x
+
+        pwn cyclic 32
+        pwn cyclic -l 0x62616161
+        pwn cyclic -a ab
+        echo
+
+        pwn shellcraft --list |tail
+        pwn shellcraft -l --syscalls |tail
+        pwn shellcraft -l execve
+        pwn shellcraft --show i386.linux.loader_append
+        pwn shellcraft -f asm --color amd64.linux.sh
+        pwn shellcraft -f elf amd64.linux.syscalls.exit 0 </dev/null |pwn hex
+        pwn shellcraft -f i   --color amd64.linux.cat /etc/passwd </dev/null
+        pwn shellcraft -f c   amd64.linux.syscalls.exit 0 </dev/null
+        pwn shellcraft -f str aarch64.linux.sh </dev/null
+        pwn shellcraft -abr -f elf -o /dev/null amd64.linux.cat /etc/passwd </dev/null
+        pwn shellcraft -nzr thumb.linux.syscalls.execve /bin/cat '["/bin/cat", "/etc/os-release"]' </dev/null
+        pwn shellcraft -fp aarch64.trap
+
+        pwn disasm --color ff3424c3ebfe
+        pwn asm -f hex nop
+
+        pwn hex abcd
+        pwn unhex 4141 4141
+
+        cat /dev/urandom | pwn phd --color -c 256 -s 2
+        pwn phd -l 0x3d --color=always /etc/os-release
+
+        pwn checksec /bin/bash
+
+        pwn errno 2
+        pwn errno -1
+        pwn errno EADDRINUSE
+
+        pwn constgrep -c freebsd -m ^PROT_ '3 + 4'
+        pwn constgrep ^MAP_ 0
+        pwn constgrep -e O_RDWR
+
+        pwn libcdb file /lib/x86_64-linux-gnu/libc.so.6
+        pwn libcdb lookup puts 5f0 __libc_start_main_ret d0a
+        pwn libcdb hash b229d1da1e161f95e839cf90cded5f719e5de308
+
+    - name: Build source and wheel distributions
+      run: |
+        python setup.py sdist
+        python setup.py bdist_wheel --universal
+
+    - uses: actions/upload-artifact@v2
+      with:
+        name: packages
+        path: dist/
+
+    - name: Upload coverage to coveralls.io
+      run: |
+        coverage combine
+        COVERALLS_REPO_TOKEN=PP20MEgztXIQJJTguQwe2jeCh6Bm4lkbv coveralls
+
+  staging-merge:
+    runs-on: ubuntu-latest
+    if: github.repository_owner == 'Gallopsled' && github.event_name == 'push' && startsWith(github.event.ref, 'refs/heads/') && endsWith(github.event.ref, '-staging')
+    needs: test
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        fetch-depth: 20
+    - name: Push changes to protected branch
+      env:
+        GITHUB_REF: ${{ github.event.ref }}
+      run: |
+        BRANCH=${GITHUB_REF#refs/heads/}
+        TARGET=${BRANCH%-staging}
+        git branch -f "$TARGET"
+        git push origin "$TARGET"
+        git push origin --delete "$BRANCH"
+
+  pypi:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags')
+    needs: test
+    steps:
+    - name: Download artifacts
+      uses: actions/download-artifact@v2
+      with:
+        name: packages
+        path: dist
+
+    - name: Publish package
+      uses: pypa/[email protected]
+      with:
+        user: __token__
+        password: ${{ secrets.pypi_password }}
+
+    - if: failure()
+      run: ls -R

.github/workflows/lint.yml

@@ -0,0 +1,35 @@
+name: Lint
+on: [push, pull_request]
+
+jobs:
+  lint:
+    strategy:
+      matrix:
+        python-version: [3.8]
+        os: [ubuntu-latest]
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    steps:
+    - uses: actions/checkout@v2
+    - name: Cache for pip
+      uses: actions/cache@v1
+      id: cache-pip
+      with:
+        path: ~/.cache/pip
+        key: ${{ matrix.os }}-cache-pip
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v1
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Critical lint
+      run: |
+        pip install flake8
+        flake8 . --count --select=E9,F63,F7,E71 --show-source --statistics --exclude=android-?dk  # TODO: Add F82
+
+    - name: Style lint
+      run: |
+        flake8 pwnlib setup.py docs travis --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+        flake8 examples --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics --ignore='F403,F405'
+        flake8 pwn --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics --ignore='F401,F403,F405'

.github/workflows/merge-conflict.yml

@@ -0,0 +1,28 @@
+name: Check for merge markers
+on: [pull_request]
+env:
+  GITHUB_BASE: origin/${{ github.event.pull_request.base.ref }}
+
+jobs:
+  mergecheck:
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 5
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        fetch-depth: 0
+
+    - name: Check for merge conflict markers commited
+      run: |
+        if git show ${GITHUB_BASE}..HEAD | grep -EB15 --color=always '^\+\+(>>>>>|=====|<<<<<)'; then
+            echo 'WARNING: Merge marker commits found in history.'
+            if git diff ${GITHUB_BASE}..HEAD | grep -EB15 --color=always '^\+(>>>>>|=====|<<<<<)'; then
+                echo 'ERROR: Merge markers still present! Do something!'
+                exit 1
+            fi
+        else
+            echo 'Congrats! All the merges you did were clean or resolved correctly :)'
+        fi

.github/workflows/pylint.yml

@@ -0,0 +1,37 @@
+name: PyLint
+on: [pull_request]
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        python-version: [3.8]
+        os: [ubuntu-latest]
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    steps:
+    - uses: actions/checkout@v2
+    - name: Cache for pip
+      uses: actions/cache@v1
+      id: cache-pip
+      with:
+        path: ~/.cache/pip
+        key: ${{ matrix.os }}-cache-pip
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v1
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: PyLint
+      run: |
+        set -x
+        pip install pylint
+        pip install --upgrade -r requirements.txt
+        pylint --exit-zero --errors-only  pwnlib > current.txt
+        git fetch origin
+        git checkout origin/"$GITHUB_BASE_REF"
+        pylint --exit-zero --errors-only  pwnlib > base.txt
+        if diff base.txt current.txt | grep '>'; then
+          false
+        fi

.gitignore

@@ -2,6 +2,8 @@
 *.hi
 *.pyc
 *~
+*.swp
+.ropeproject
 *.pdf
 */auto/*
 */bin/*
@@ -9,4 +11,13 @@ docs/build
 build
 MANIFEST
 dist
-pwntools.egg-info
+venv
+.vscode
+.idea
+*.egg-info
+*.core
+.coverage
+.coverage.*
+.idea
+__pycache__
+!.github

.isort.cfg

@@ -0,0 +1,4 @@
+[settings]
+indent='    '
+not_skip = __init__.py
+force_single_line = 1

.sublime-settings

@@ -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
+}

.travis.yml

@@ -1,15 +1,67 @@
 language: python
+addons:
+  apt:
+    packages:
+    - lib32stdc++6
+    - ash
+    - bash
+    - dash
+    - ksh
+    - mksh
+    - zsh
+    - pandoc
+    - gdb
+    - socat
+    - sshpass
+    - binutils
+    - qemu-user-static
+    - binutils-multiarch
+    - binutils-aarch64-linux-gnu
+    - binutils-arm-linux-gnueabihf
+    - binutils-mips-linux-gnu
+    - binutils-msp430
+    - binutils-powerpc-linux-gnu
+    - binutils-s390x-linux-gnu
+    - binutils-sparc64-linux-gnu
+    - bash-static
+    - python3-pip
+    - elfutils
+cache:
+    - pip
+    - directories:
+        - usr
+        - /home/travis/virtualenv/python2.7.15/lib/python2.7/site-packages/
+        - /home/travis/virtualenv/python2.7.15/bin/
+        - /home/travis/virtualenv/python3.8.*/lib/python3.8/site-packages/
+        - /home/travis/virtualenv/python3.8.*/bin/
+        - docs/build/doctest/.doctrees
 python:
   - "2.7"
-branches:
-  only:
-    - master
+  - "3.8"
+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
+  - /usr/bin/python3 -m pip install rpyc # for GDB
+  - pip install --upgrade pip
+  - pip install --upgrade flake8 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)'
+  - sudo sh -c "echo 0 > /proc/sys/kernel/yama/ptrace_scope"
+script:
+  # stop the build if there are Python syntax errors or undefined names
+  - flake8 . --count --select=E9,F63,F7 --show-source --statistics --exclude=android-?dk  # TODO: Add F82
+  # exit-zero treats all errors as warnings.  The GitHub editor is 127 chars wide
+  - PWNLIB_NOTERM=1 coverage run -m sphinx -b doctest docs/source docs/build/doctest
+  - coverage combine
+after_success:
+  - coveralls
+  - source travis/update_demo.sh

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

.travis_ssh_setup.sh

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

CONTRIBUTING.md

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

DOCKER.md

@@ -0,0 +1,76 @@
+# Using Pwntools with Docker
+
+Sometimes it's annoying to set up Pwntools on your workstation, and you want something that Just Works (TM).
+
+[Docker](https://www.docker.com/) is here to the rescue! Using Docker means that you get a nice, standardized Linux environment and don't need to worry about pip or installing dependencies.
+
+## Quick Start
+
+First, install Docker for your OS, which you can find on their [Getting Started](https://www.docker.com/get-started) page.
+
+Next, download and run the Pwntools stable docker image.
+
+```sh
+$ docker run -it pwntools/pwntools:stable
+```
+
+## Recommended Settings
+
+In order to get the most from your docker image, we need to enable debugging of processes (`--privileged`) and expose the network ports from the guest to the host (`--net=host`).
+
+```sh
+$ docker run -it \
+    --privileged \
+    --net=host \
+    --hostname localhost \
+    --ulimit core=-1:-1 \
+    pwntools/pwntools:stable
+```
+
+## Sharing a Folder
+
+It's really nice to be able to use your preferred native editor, and have the changes show up live inside your Docker image.  This is easy to add, thanks to Docker's bind mounts (`--mount type=bind`).  
+
+With the command below, your `~/exploits` directory will magically show up inside the Docker image at `/home/pwntools/exploits` so that you can easily run them (from Docker) and edit them (from outside Docker).
+
+```sh
+$ mkdir $HOME/exploits
+
+$ vim $HOME/exploits/my_exploit.py
+
+$ docker run -it \
+    --privileged \
+    --net=host \
+    --hostname localhost \
+    --ulimit core=-1:-1 \
+    --mount type=bind,source="$HOME/exploits",target=/home/pwntools/exploits \
+    pwntools/pwntools:stable
+    
+$ python3 exploits/my_exploit.py
+```
+
+### Windows User Bind Mounts
+
+If you're a Windows user `$HOME` doesn't exist in the same way as on Linux, instead it is `%UserProfile%`.  The command from above would look like this, assuming your editor is Visual Studio Code and you have code.exe in your `%PATH%`.
+
+```sh
+C:\Users\user> mkdir Desktop\exploits
+
+C:\Users\user> code Desktop\exploits\my_exploit.py
+
+C:\Users\user> docker run -it \
+    --privileged \
+    --net=host \
+    --hostname localhost \
+    --ulimit core=-1:-1 \
+    --mount type=bind,source="%UserProfile%\Desktop\exploits",target=/home/pwntools/exploits \
+    pwntools/pwntools:stable
+    
+$ python3 exploits/my_exploit.py
+
+```
+
+
+
+
+

LICENSE-pwntools.txt

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

MANIFEST.in

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

README.md

@@ -1,11 +1,17 @@
 # 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.
+[![PyPI](https://img.shields.io/pypi/v/pwntools?style=flat)](https://pypi.python.org/pypi/pwntools/)
+[![Docs](https://readthedocs.org/projects/pwntools/badge/?version=stable)](https://docs.pwntools.com/)
+[![Travis](https://img.shields.io/travis/Gallopsled/pwntools/dev?logo=Travis)](https://travis-ci.org/Gallopsled/pwntools)
+[![GitHub Workflow Status (branch)](https://img.shields.io/github/workflow/status/Gallopsled/pwntools/Continuous%20Integration/dev?logo=GitHub)](https://github.com/Gallopsled/pwntools/actions?query=workflow%3A%22Continuous+Integration%22+branch%3Adev)
+[![Coveralls](https://img.shields.io/coveralls/github/Gallopsled/pwntools/dev?logo=coveralls)](https://coveralls.io/github/Gallopsled/pwntools?branch=dev)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat)](http://choosealicense.com/licenses/mit/)
+[![Packaging status](https://img.shields.io/repology/repositories/python:pwntools)](https://repology.org/project/python:pwntools/versions)
+[![Discord](https://img.shields.io/discord/809590285687980052?label=Discord&style=plastic)](https://discord.gg/96VA2zvjCB)
+[![Twitter](https://img.shields.io/twitter/follow/Pwntools)](https://twitter.com/pwntools)
+
+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,40 +23,34 @@ r.send(asm(shellcraft.sh()))
 r.interactive()
 ```
 
-However we have made command-line frontends for some of the functionality
-in `pwnlib`. These are:
-
-* `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.
-
 # 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/)
+
+A series of tutorials is also [available online](https://github.com/Gallopsled/pwntools-tutorial#readme)
 
 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 LTS releases (14.04, 16.04, 18.04, and 20.04).  Most functionality should work on any Posix-like distribution (Debian, Arch, FreeBSD, OSX, etc.).  
 
-Most of the functionality of pwntools is self-contained and Python-only.  You should be able to get running quickly with
+Python3 is suggested, but Pwntools still works with Python 2.7.  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 python3 python3-pip python3-dev git libssl-dev libffi-dev build-essential
+python3 -m pip install --upgrade pip
+python3 -m 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
 
 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.
-
+# Contact and Community
+If you have any questions not worthy of a [bug report](https://github.com/Gallopsled/pwntools/issues), join the Discord server at https://discord.gg/96VA2zvjCB

TESTING.md

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

docs/Makefile

@@ -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)/.cache/.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

docs/dashbuild.py

@@ -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 as 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())

docs/requirements.txt

@@ -1,6 +1,18 @@
-paramiko
-argparse
-mako
-pyelftools
-sphinxcontrib-napoleon
-sphinxcontrib-autoprogram
+capstone
+coveralls
+doc2dash
+docutils<0.18
+isort
+mako>=1.0.0
+paramiko>=1.15.2
+pip>=6.0.8
+pyelftools>=0.2.3
+pygments>=2.0
+pypandoc
+pyserial>=2.7
+requests>=2.5.1
+ropgadget>=5.3
+sphinx==1.8.6; python_version<'3'
+sphinx>=4.5.0; python_version>='3'
+sphinx_rtd_theme
+sphinxcontrib-autoprogram<=0.1.5

docs/source/about.rst

@@ -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.
@@ -47,7 +47,7 @@ This module is our "clean" python-code. As a rule, we do not think that
 importing :mod:`pwnlib` or any of the submodules should have any significant
 side-effects (besides e.g. caching).
 
-For the most part, you will also only get the bits you import. You for instance
+For the most part, you will also only get the bits you import. You for instance would
 not get access to :mod:`pwnlib.util.packing` simply by doing ``import
 pwnlib.util``.
 

docs/source/adb.rst

@@ -0,0 +1,14 @@
+.. testsetup:: *
+
+   from pprint import pprint
+   from pwn import *
+   adb = pwnlib.adb
+
+:mod:`pwnlib.adb` --- Android Debug Bridge
+=====================================================
+
+.. automodule:: pwnlib.adb.adb
+   :members:
+
+.. automodule:: pwnlib.adb.protocol
+   :members:

docs/source/args.rst

@@ -0,0 +1,9 @@
+.. testsetup:: *
+
+   from pwn import *
+
+:mod:`pwnlib.args` --- Magic Command-Line Arguments
+=====================================================
+
+.. automodule:: pwnlib.args
+   :members:

docs/source/asm.rst

@@ -1,10 +1,21 @@
 .. testsetup:: *
 
-   from pwnlib.asm import *
-   from pwnlib import shellcraft
+   import tempfile
+   import subprocess
+   from pwn import *
 
 :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

docs/source/commandline.rst

@@ -12,35 +12,9 @@ Command Line Tools
 
 pwntools comes with a handful of useful command-line utilities which serve as wrappers for some of the internal functionality.
 
+If these tools do not appear to be installed, make sure that you have added ``~/.local/bin`` to your ``$PATH`` environment variable.
+
 .. 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

docs/source/conf.py

@@ -11,14 +11,22 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys, os, subprocess
+import os
+import doctest
+import signal
+import six
+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.update
+pwnlib.update.disabled = True
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #needs_sphinx = '1.0'
@@ -34,24 +42,72 @@ extensions = [
     'sphinx.ext.coverage',
     'sphinx.ext.todo',
     'sphinx.ext.intersphinx',
+    'sphinx.ext.napoleon',
     'sphinxcontrib.autoprogram',
-    'sphinxcontrib.napoleon'
 ]
 
-doctest_global_setup = '''
-import pwnlib
-pwnlib.context.context.reset_local()
-pwnlib.context.ContextType.defaults['log_level'] = 'ERROR'
-pwnlib.term.text.when = 'never'
+# 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.update
+import pwnlib.util.fiddling
+import logging
+pwnlib.update.disabled = True
+pwnlib.context.context.reset_local()
+pwnlib.context.ContextType.defaults['log_level'] = logging.ERROR
+pwnlib.context.ContextType.defaults['randomize'] = False
+# pwnlib.context.ContextType.defaults['terminal'] = ['sh', '-c']
+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()
+
+github_actions = os.environ.get('USER') == 'runner'
+travis_ci = os.environ.get('USER') == 'travis'
+local_doctest = os.environ.get('USER') == 'pwntools'
+branch_dev = os.environ.get('GITHUB_BASE_REF') == 'dev'
+skip_android = True
 '''
 
-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 +120,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 +216,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 +262,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)}
+intersphinx_mapping = {'python': ('https://docs.python.org/3.8', 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 +295,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 +309,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'),
 ]
 
@@ -270,13 +325,13 @@ texinfo_documents = [
 branch = release
 
 try:
-    git_branch = subprocess.check_output('git describe --tags', shell = True)
+    git_branch = subprocess.check_output('git describe --tags', shell = True, universal_newlines = True)
 except subprocess.CalledProcessError:
     git_branch = '-'
 
 try:
     if '-' in git_branch:
-        branch = subprocess.check_output('git rev-parse HEAD', shell = True).strip()[:10]
+        branch = subprocess.check_output('git rev-parse HEAD', shell = True, universal_newlines = True).strip()[:10]
 except subprocess.CalledProcessError:
     pass
 
@@ -293,7 +348,7 @@ def linkcode_resolve(domain, info):
     val = mod
     for k in info['fullname'].split('.'):
         val = getattr(val, k, None)
-        if val == None:
+        if val is None:
             break
 
     # Special case for shellcraft
@@ -304,11 +359,90 @@ def linkcode_resolve(domain, info):
     else:
         filename = info['module'].replace('.', '/') + '.py'
 
-        if isinstance(val, (types.ModuleType, types.ClassType, types.MethodType, types.FunctionType, types.TracebackType, types.FrameType, types.CodeType)):
+        if isinstance(val, (types.ModuleType, types.MethodType, types.FunctionType, types.TracebackType, types.FrameType, types.CodeType) + six.class_types):
             try:
                 lines, first = inspect.getsourcelines(val)
-                filename += '#L%d-%d' % (first, first + len(lines) - 1)
-            except IOError:
+                filename += '#L%d-L%d' % (first, first + len(lines) - 1)
+            except (IOError, TypeError):
                 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
+
+# Test hidden members (e.g. def _foo(...))
+def dont_skip_any_doctests(app, what, name, obj, skip, options):
+    return None
+
+autodoc_default_options = {'special-members': None, 'private-members': None}
+
+class _DummyClass(object): pass
+
+class Py2OutputChecker(_DummyClass, doctest.OutputChecker):
+    def check_output(self, want, got, optionflags):
+        sup = super(Py2OutputChecker, self).check_output
+        if sup(want, got, optionflags):
+            return True
+        try:
+            rly_want = pwnlib.util.safeeval.const(want)
+            if sup(repr(rly_want), got, optionflags):
+                return True
+            rly_got = pwnlib.util.safeeval.const(got)
+            if rly_want == rly_got:
+                return True
+        except ValueError:
+            pass
+        rly_want = ' '.join(x[:2].replace('b"','"').replace("b'","'")+x[2:] for x in want.replace('\n','\n ').split(' ')).replace('\n ','\n')
+        if sup(rly_want, got, optionflags):
+            return True
+        rly_want = ' '.join(x[:2].replace('b"',' "').replace("b'"," '")+x[2:] for x in want.replace('\n','\n ').split(' ')).replace('\n ','\n')
+        if sup(rly_want, got, optionflags):
+            return True
+        for wantl, gotl in six.moves.zip_longest(want.splitlines(), got.splitlines(), fillvalue=''):
+            rly_want1 = '['.join(x[:2].replace('b"','"').replace("b'","'")+x[2:] for x in wantl.split('['))
+            rly_want2 = ' '.join(x[:2].replace('b"',' "').replace("b'"," '")+x[2:] for x in wantl.split(' '))
+            if not sup(rly_want1, gotl, optionflags) and not sup(rly_want2, gotl, optionflags):
+                return False
+        return True
+
+def py2_doctest_init(self, checker=None, verbose=None, optionflags=0):
+    if checker is None:
+        checker = Py2OutputChecker()
+    doctest.DocTestRunner.__init__(self, checker, verbose, optionflags)
+
+if 'doctest' in sys.argv:
+    def setup(app):
+        pass # app.connect('autodoc-skip-member', dont_skip_any_doctests)
+
+    if sys.version_info[:1] < (3,):
+        import sphinx.ext.doctest
+        sphinx.ext.doctest.SphinxDocTestRunner.__init__ = py2_doctest_init
+    else:
+        # monkey patching paramiko due to https://github.com/paramiko/paramiko/pull/1661
+        import paramiko.client
+        import binascii
+        paramiko.client.hexlify = lambda x: binascii.hexlify(x).decode()
+        paramiko.util.safe_string = lambda x: '' # function result never *actually used*
+    class EndlessLoop(Exception): pass
+    def alrm_handler(sig, frame):
+        signal.alarm(180) # three minutes
+        raise EndlessLoop()
+    signal.signal(signal.SIGALRM, alrm_handler)
+    signal.alarm(600) # ten minutes

docs/source/config.rst

@@ -0,0 +1,4 @@
+:mod:`pwnlib.config` --- Pwntools Configuration File
+====================================================
+
+.. automodule:: pwnlib.config

docs/source/context.rst

@@ -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:

docs/source/elf.rst

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

docs/source/elf/config.rst

@@ -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:

docs/source/elf/corefile.rst

@@ -0,0 +1,32 @@
+.. testsetup:: *
+
+   from glob import glob
+   from pwn import *
+
+   # The Linux kernel won't overwrite an existing corefile, so in case 
+   # some other part of the doctests caused a segfault and core dump,
+   # we need to get rid of it before our tests run.
+   #
+   # We DONT need to worry about e.g. ./core existing when using Corefile()
+   # because we always move and rename the corefile to prevent this situation.
+   if os.path.exists('core'): 
+      os.unlink('core')
+
+   # bash-static is a statically linked version of bash, but if $SHELL is not
+   # set to anything, it decides to up and load ld.so and libc.so which breaks
+   # our example of showing `corefile.libc == None` for a statically linked bin.
+   # Set the environment here so it's not in the middle of our tests.
+   os.environ.setdefault('SHELL', '/bin/sh')
+
+
+:mod:`pwnlib.elf.corefile` --- Core Files
+===========================================================
+
+.. automodule:: pwnlib.elf.corefile
+
+  .. autoclass:: pwnlib.elf.corefile.Corefile
+     :members:
+     :show-inheritance:
+
+  .. autoclass:: pwnlib.elf.corefile.Mapping
+     :members:

docs/source/elf/elf.rst

@@ -0,0 +1,29 @@
+.. testsetup:: *
+
+   from pwn import *
+   from glob import glob
+   from pwnlib.elf.maps import CAT_PROC_MAPS_EXIT
+
+: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:

docs/source/encoders.rst

@@ -0,0 +1,29 @@
+.. testsetup:: *
+
+   from pwn import *
+   
+:mod:`pwnlib.encoders` --- Encoding Shellcode
+===============================================
+
+.. automodule:: pwnlib.encoders.encoder
+   :members:
+
+.. automodule:: pwnlib.encoders.i386.ascii_shellcode
+   :members:
+   :special-members:
+   :exclude-members: __init__
+
+.. automodule:: pwnlib.encoders.i386.xor
+   :members:
+
+.. automodule:: pwnlib.encoders.i386.delta
+   :members:
+
+.. automodule:: pwnlib.encoders.amd64.delta
+   :members:
+
+.. automodule:: pwnlib.encoders.arm.xor
+   :members:
+
+.. automodule:: pwnlib.encoders.mips.xor
+   :members:

docs/source/filepointer.rst

@@ -0,0 +1,9 @@
+.. testsetup:: *
+
+   from pwnlib.filepointer import *
+
+:mod:`pwnlib.filepointer` --- `FILE*` structure exploitation
+============================================================
+
+.. automodule:: pwnlib.filepointer
+   :members:

docs/source/filesystem.rst

@@ -0,0 +1,17 @@
+.. testsetup:: *
+
+    import time
+    import six
+    from pwnlib.context import context
+    from pwnlib.tubes.ssh import ssh
+    from pwnlib.filesystem import *
+
+:mod:`pwnlib.filesystem` --- Manipulating Files Locally and Over SSH
+====================================================================
+
+Provides a Python2-compatible :py:mod:`pathlib` interface for paths
+on the local filesystem (`.Path`) as well as on remote filesystems,
+via SSH (`.SSHPath`).
+
+.. automodule:: pwnlib.filesystem
+   :members:

docs/source/flag.rst

@@ -0,0 +1,10 @@
+.. testsetup:: *
+
+   from pwn import *
+
+
+:mod:`pwnlib.flag` --- CTF Flag Management
+==========================================
+
+.. automodule:: pwnlib.flag
+   :members:

docs/source/fmtstr.rst

@@ -0,0 +1,10 @@
+.. testsetup:: *
+
+	from pwn import *
+	import tempfile
+
+:mod:`pwnlib.fmtstr` --- Format string bug exploitation tools
+=============================================================
+
+.. automodule:: pwnlib.fmtstr
+   :members:

docs/source/gdb.rst

@@ -1,3 +1,9 @@
+.. testsetup:: *
+
+    from pwn import *
+    context.arch = 'amd64'
+    context.terminal = [os.path.join(os.path.dirname(pwnlib.__file__), 'gdb_faketerminal.py')]
+
 :mod:`pwnlib.gdb` --- Working with GDB
 ======================================
 

docs/source/globals.rst

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

docs/source/index.rst

@@ -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,62 @@ Each of the ``pwntools`` modules is documented here.
    :maxdepth: 1
    :glob:
 
+   adb
+   args
    asm
    atexception
    atexit
    constants
+   config
    context
    dynelf
-   elf
+   encoders
+   elf/*
    exception
+   filepointer
+   filesystem
+   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
+   rop/call
+
+.. only:: not dash
+
+   Indices and tables
+   ==================
+
+   * :ref:`genindex`
+   * :ref:`modindex`
+   * :ref:`search`
+
+Bytes
+-----
+
+The bytes vs text distinction is so important that it even made it to this main page.
+See the pwntools-tutorial_ repo for the latest tutorial finally
+explaining the difference once and for all (hopefully).
+
+.. _pwntools-tutorial: https://github.com/Gallopsled/pwntools-tutorial/blob/master/bytes.md

docs/source/install.rst

@@ -1,9 +1,7 @@
 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 LTS releases (14.04, 16.04, 18.04, and 20.04).  Most functionality should work on any Posix-like distribution (Debian, Arch, FreeBSD, OSX, etc.).
 
 Prerequisites
 -------------
@@ -20,27 +18,57 @@ following system libraries installed.
 Released Version
 -----------------
 
-Pwntools is available as a ``pip`` package.
+pwntools is available as a ``pip`` package for both Python2 and Python3.
+
+Python3
+^^^^^^^
 
 .. code-block:: bash
 
-    $ apt-get install python2.7 python2.7-dev python-pip
-    $ pip install pwntools
+    $ apt-get update
+    $ apt-get install python3 python3-pip python3-dev git libssl-dev libffi-dev build-essential
+    $ python3 -m pip install --upgrade pip
+    $ python3 -m pip install --upgrade pwntools
 
-Latest Version
+
+Python2 (Deprecated)
+^^^^^^^^^^^^^^^^^^^^
+
+NOTE: Pwntools maintainers STRONGLY recommend using Python3 for all future Pwntools-based scripts and projects.
+
+Additionally, due to `pip` dropping support for Python2, a specfic version of `pip` must be installed.
+
+.. code-block:: bash
+
+    $ apt-get update
+    $ apt-get install python python-pip python-dev git libssl-dev libffi-dev build-essential
+    $ python2 -m pip install --upgrade pip==20.3.4
+    $ python2 -m pip install --upgrade pwntools
+
+
+Command-Line Tools
+------------------
+
+When installed with ``sudo`` the above commands will install Pwntools' command-line tools to somewhere like ``/usr/bin``.
+
+However, if you run as an unprivileged user, you may see a warning message that looks like this:
+
+.. code-block::
+
+      WARNING: The scripts asm, checksec, common, constgrep, cyclic, debug, disablenx, disasm, 
+      elfdiff, elfpatch, errno, hex, main, phd, pwn, pwnstrip, scramble, shellcraft, template, 
+      unhex, update and version are installed in '/home/user/.local/bin' which is not on PATH.
+
+Follow the instructions listed and add ``~/.local/bin`` to your ``$PATH`` environment variable.
+
+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
-

docs/source/install/binutils.rst

@@ -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 <https://launchpad.net/~pwntools/+archive/ubuntu/binutils>`__.
+
+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.
 
@@ -34,7 +39,7 @@ repo <https://github.com/Gallopsled/pwntools-binutils/>`__.
 
 .. code-block:: bash
 
-    $ brew install https://raw.githubusercontent.com/Gallopsled/pwntools-binutils/master/osx/binutils-$ARCH.rb
+    $ brew install https://raw.githubusercontent.com/Gallopsled/pwntools-binutils/master/macos/binutils-$ARCH.rb
 
 Alternate OSes
 ^^^^^^^^^^^^^^^^
@@ -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
 

docs/source/install/capstone.rst

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

docs/source/install/headers.rst

@@ -1,5 +1,5 @@
 Python Development Headers
--------------
+-----------------------------
 
 Some of pwntools' Python dependencies require native extensions (for example, Paramiko requires PyCrypto).
 

docs/source/intro.rst

@@ -17,6 +17,13 @@ assemble, disassemble, pack, unpack, and many other things with a single functio
 A full list of everything that is imported is available on :doc:`globals`.
 
 
+Tutorials
+---------
+
+A series of tutorials for Pwntools exists online, at
+https://github.com/Gallopsled/pwntools-tutorial#readme
+
+
 Making Connections
 ------------------
 
@@ -27,14 +34,14 @@ 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')
-    >>> conn.recvuntil(' ', drop=True)
-    '331'
+    b'220 ...'
+    >>> conn.send(b'USER anonymous\r\n')
+    >>> conn.recvuntil(b' ', drop=True)
+    b'331'
     >>> conn.recvline()
-    'Please specify the password.\r\n'
+    b'Please specify the password.\r\n'
     >>> conn.close()
 
 It's also easy to spin up a listener
@@ -42,20 +49,20 @@ It's also easy to spin up a listener
     >>> l = listen()
     >>> r = remote('localhost', l.lport)
     >>> c = l.wait_for_connection()
-    >>> r.send('hello')
+    >>> r.send(b'hello')
     >>> c.recv()
-    'hello'
+    b'hello'
 
 Interacting with processes is easy thanks to :mod:`pwnlib.tubes.process`.
 
 ::
 
     >>> sh = process('/bin/sh')
-    >>> sh.sendline('sleep 3; echo hello world;')
+    >>> sh.sendline(b'sleep 3; echo hello world;')
     >>> sh.recvline(timeout=1)
-    ''
+    b''
     >>> sh.recvline(timeout=5)
-    'hello world\n'
+    b'hello world\n'
     >>> sh.close()
 
 Not only can you interact with processes programmatically, but you can
@@ -67,21 +74,21 @@ 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'
+    b'bandit0'
     >>> shell.download_file('/etc/motd')
     >>> sh = shell.run('sh')
-    >>> sh.sendline('sleep 3; echo hello world;') # doctest: +SKIP
+    >>> sh.sendline(b'sleep 3; echo hello world;') # doctest: +SKIP
     >>> sh.recvline(timeout=1)
-    ''
+    b''
     >>> sh.recvline(timeout=5)
-    'hello world\n'
+    b'hello world\n'
     >>> shell.close()
 
 Packing Integers
@@ -97,13 +104,13 @@ unpacking codes, and littering your code with helper routines.
     >>> import struct
     >>> p32(0xdeadbeef) == struct.pack('I', 0xdeadbeef)
     True
-    >>> leet = '37130000'.decode('hex')
-    >>> u32('abcd') == struct.unpack('I', 'abcd')[0]
+    >>> leet = unhex('37130000')
+    >>> u32(b'abcd') == struct.unpack('I', b'abcd')[0]
     True
 
 The packing/unpacking operations are defined for many common bit-widths.
 
-    >>> u8('A') == 0x41
+    >>> u8(b'A') == 0x41
     True
 
 Setting the Target Architecture and OS
@@ -112,9 +119,9 @@ Setting the Target Architecture and OS
 The target architecture can generally be specified as an argument to the routine that requires it.
 
     >>> asm('nop')
-    '\x90'
+    b'\x90'
     >>> asm('nop', arch='arm')
-    '\x00\xf0 \xe3'
+    b'\x00\xf0 \xe3'
 
 However, it can also be set once in the global ``context``.  The operating system, word size, and endianness can also be set here.
 
@@ -126,10 +133,10 @@ However, it can also be set once in the global ``context``.  The operating syste
 Additionally, you can use a shorthand to set all of the values at once.
 
     >>> asm('nop')
-    '\x90'
+    b'\x90'
     >>> context(arch='arm', os='linux', endian='big', word_size=32)
     >>> asm('nop')
-    '\xe3 \xf0\x00'
+    b'\xe3 \xf0\x00'
 
 .. doctest::
    :hide:
@@ -158,26 +165,26 @@ Assembly and Disassembly
 Never again will you need to run some already-assembled pile of shellcode
 from the internet!  The :mod:`pwnlib.asm` module is full of awesome.
 
-    >>> asm('mov eax, 0').encode('hex')
+    >>> enhex(asm('mov eax, 0'))
     'b800000000'
 
 But if you do, it's easy to suss out!
 
-    >>> print disasm('6a0258cd80ebf9'.decode('hex'))
+    >>> print(disasm(unhex('6a0258cd80ebf9')))
        0:   6a 02                   push   0x2
        2:   58                      pop    eax
        3:   cd 80                   int    0x80
        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'
+    >>> enhex(asm(shellcraft.setreuid() + shellcraft.dupsh(4))) # doctest: +ELLIPSIS
+    '6a3158cd80...'
 
 
 Misc Tools
@@ -188,10 +195,10 @@ Never write another hexdump, thanks to :mod:`pwnlib.util.fiddling`.
 
 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
-    >>> print cyclic_find('faab')
+    >>> cyclic(20)
+    b'aaaabaaacaaadaaaeaaa'
+    >>> # Assume EIP = 0x62616166 (b'faab' which is pack(0x62616166))  at crash time
+    >>> cyclic_find(b'faab')
     120
 
 ELF Manipulation
@@ -200,22 +207,22 @@ ELF Manipulation
 Stop hard-coding things!  Look them up at runtime with :mod:`pwnlib.elf`.
 
     >>> e = ELF('/bin/cat')
-    >>> print hex(e.address) #doctest: +SKIP
+    >>> print(hex(e.address)) #doctest: +SKIP
     0x400000
-    >>> print hex(e.symbols['write']) #doctest: +SKIP
+    >>> print(hex(e.symbols['write'])) #doctest: +SKIP
     0x401680
-    >>> print hex(e.got['write']) #doctest: +SKIP
+    >>> print(hex(e.got['write'])) #doctest: +SKIP
     0x60b070
-    >>> print hex(e.plt['write']) #doctest: +SKIP
+    >>> print(hex(e.plt['write'])) #doctest: +SKIP
     0x401680
 
 You can even patch and save the files.
 
     >>> e = ELF('/bin/cat')
-    >>> e.read(e.address+1, 3)
-    'ELF'
+    >>> e.read(e.address, 4)
+    b'\x7fELF'
     >>> e.asm(e.address, 'ret')
     >>> e.save('/tmp/quiet-cat')
-    >>> disasm(file('/tmp/quiet-cat','rb').read(1))
+    >>> disasm(open('/tmp/quiet-cat','rb').read(1))
     '   0:   c3                      ret'
 

docs/source/libcdb.rst

@@ -0,0 +1,10 @@
+.. testsetup:: *
+
+   from pwn import *
+   from pwnlib.libcdb import *
+
+:mod:`pwnlib.libcdb` --- Libc Database
+===========================================
+
+.. automodule:: pwnlib.libcdb
+   :members:

docs/source/log.rst

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

docs/source/memleak.rst

@@ -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:

docs/source/protocols.rst

@@ -0,0 +1 @@
+

docs/source/qemu.rst

@@ -0,0 +1,10 @@
+.. testsetup:: *
+
+   from pwn import *
+
+
+:mod:`pwnlib.qemu` --- QEMU Utilities
+==========================================
+
+.. automodule:: pwnlib.qemu
+   :members:

docs/source/regsort.rst

@@ -0,0 +1,9 @@
+.. testsetup:: *
+
+    from pwnlib.regsort import *
+
+:mod:`pwnlib.regsort` --- Register sorting
+===========================================================
+
+.. automodule:: pwnlib.regsort
+   :members:

docs/source/rop.rst

@@ -1,11 +1,10 @@
-.. testsetup:: *
-
-   from pwnlib.elf import *
-   from pwnlib.rop import *
-   from pwnlib.util.misc import which
-
 :mod:`pwnlib.rop` --- Return Oriented Programming
 =================================================
 
-.. automodule:: pwnlib.rop
-   :members:
+Submodules
+----------
+
+.. toctree::
+   :glob:
+
+   rop/*

docs/source/rop/ret2dlresolve.rst

@@ -0,0 +1,10 @@
+.. testsetup:: *
+
+   from pwn import *
+   import tempfile
+
+:mod:`pwnlib.rop.ret2dlresolve` --- Return to dl_resolve
+========================================================
+
+.. automodule:: pwnlib.rop.ret2dlresolve
+   :members:

docs/source/rop/rop.rst

@@ -0,0 +1,26 @@
+.. testsetup:: *
+
+   import time
+   from glob import glob
+
+   from pwnlib.asm import asm
+   from pwnlib import constants
+   from pwnlib.context import context
+   from pwnlib.elf import ELF
+   from pwnlib.rop import ROP
+   from pwnlib.rop.call import Call, AppendedArgument
+   from pwnlib.elf.maps import CAT_PROC_MAPS_EXIT
+   from pwnlib.util.packing import *
+   from pwnlib.util.fiddling import *
+   from pwnlib.tubes.process import process
+   from pwnlib import shellcraft
+   from pwnlib.util.misc import which
+
+   context.clear()
+
+
+:mod:`pwnlib.rop.rop` --- Return Oriented Programming
+==========================================================
+
+.. automodule:: pwnlib.rop.rop
+   :members:

docs/source/rop/srop.rst

@@ -0,0 +1,14 @@
+.. testsetup:: *
+
+   from pwnlib.rop.srop import *
+
+   from pwnlib import constants
+   from pwnlib import shellcraft
+   from pwnlib.elf import ELF
+   from pwnlib.tubes.process import process
+
+:mod:`pwnlib.rop.srop` --- Sigreturn Oriented Programming
+==========================================================
+
+.. automodule:: pwnlib.rop.srop
+   :members:

docs/source/runner.rst

@@ -0,0 +1,10 @@
+.. testsetup:: *
+
+   from pwnlib.runner import *
+   from pwnlib.asm import asm
+
+:mod:`pwnlib.runner` --- Running Shellcode
+===========================================
+
+.. automodule:: pwnlib.runner
+   :members:

docs/source/shellcraft/aarch64.rst

@@ -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:

docs/source/shellcraft/amd64.rst

@@ -1,6 +1,7 @@
 .. testsetup:: *
 
    from pwn import *
+   context.clear(arch='amd64')
 
 :mod:`pwnlib.shellcraft.amd64` --- Shellcode for AMD64
 ===========================================================

docs/source/shellcraft/arm.rst

@@ -1,6 +1,7 @@
 .. testsetup:: *
 
    from pwn import *
+   context.clear(arch='arm')
 
 :mod:`pwnlib.shellcraft.arm` --- Shellcode for ARM
 ===========================================================

docs/source/shellcraft/i386.rst

@@ -1,6 +1,7 @@
 .. testsetup:: *
 
    from pwn import *
+   context.clear(arch='i386')
 
 :mod:`pwnlib.shellcraft.i386` --- Shellcode for Intel 80386
 ===========================================================

docs/source/shellcraft/mips.rst

@@ -0,0 +1,28 @@
+.. testsetup:: *
+
+   import tempfile
+
+   from pwnlib import shellcraft
+
+   from pwnlib.asm import asm
+   from pwnlib.context import context
+   from pwnlib.runner import run_assembly
+   from pwnlib.util.fiddling import enhex
+   from pwnlib.util.misc import write
+
+   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:

docs/source/shellcraft/thumb.rst

@@ -1,6 +1,7 @@
 .. testsetup:: *
 
    from pwn import *
+   context.clear(arch='thumb')
 
 :mod:`pwnlib.shellcraft.thumb` --- Shellcode for Thumb Mode
 ===========================================================

docs/source/term.rst

@@ -3,3 +3,9 @@
 
 .. automodule:: pwnlib.term
    :members:
+
+Term Modules
+-------------------
+
+.. toctree::
+    term/readline

docs/source/term/readline.rst

@@ -0,0 +1,10 @@
+.. testsetup:: *
+
+   from pwnlib.term.readline import *
+   import io
+
+:mod:`pwnlib.term.readline` --- Terminal nice readline
+======================================================
+
+.. automodule:: pwnlib.term.readline
+   :members:

docs/source/testexample.rst

@@ -0,0 +1,10 @@
+.. testsetup:: *
+
+   import os
+   from pwnlib.testexample import add
+
+:mod:`pwnlib.testexample` --- Example Test Module
+==================================================
+
+.. automodule:: pwnlib.testexample
+   :members:

docs/source/timeout.rst

@@ -5,7 +5,7 @@
    import time
 
 :mod:`pwnlib.timeout` --- Timeout handling
-========================================
+============================================
 
 .. automodule:: pwnlib.timeout
    :members:

docs/source/tubes.rst

@@ -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,

docs/source/tubes/buffer.rst

@@ -0,0 +1,9 @@
+.. testsetup:: *
+
+   from pwnlib.tubes.buffer import *
+
+:mod:`pwnlib.tubes.buffer` --- buffer implementation for tubes
+==============================================================
+
+.. automodule:: pwnlib.tubes.buffer
+   :members:

docs/source/tubes/processes.rst

@@ -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:

docs/source/tubes/serial.rst

@@ -0,0 +1,11 @@
+.. testsetup:: *
+
+   from pwn import *
+
+:mod:`pwnlib.tubes.serialtube` --- Serial Ports
+===========================================================
+
+.. automodule:: pwnlib.tubes.serialtube
+
+   .. autoclass:: pwnlib.tubes.serialtube.serialtube
+      :members:

docs/source/tubes/sockets.rst

@@ -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:

docs/source/tubes/ssh.rst

@@ -0,0 +1,25 @@
+.. 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_process
+      :members:
+      :show-inheritance:
+
+   .. autoclass:: pwnlib.tubes.ssh.ssh_connecter()
+      :show-inheritance:
+
+   .. autoclass:: pwnlib.tubes.ssh.ssh_listener()
+      :show-inheritance:

docs/source/ui.rst

@@ -1,3 +1,8 @@
+.. testsetup:: *
+
+   from pwn import *
+   import io
+
 :mod:`pwnlib.ui` --- Functions for user interaction
 ===================================================
 

docs/source/update.rst

@@ -0,0 +1,10 @@
+.. testsetup:: *
+
+   from pwn import *
+   from pwnlib.update import *
+
+:mod:`pwnlib.update` --- Updating Pwntools
+===================================================
+
+.. automodule:: pwnlib.update
+   :members:

docs/source/util/cyclic.rst

@@ -1,5 +1,6 @@
 .. testsetup:: *
 
+   from pwn import *
    from pwnlib.util.cyclic import *
 
 

docs/source/util/fiddling.rst

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

docs/source/util/getdents.rst

@@ -0,0 +1,11 @@
+.. testsetup:: *
+
+   from pwnlib.util.getdents import *
+   from pwnlib.util.fiddling import unhex
+
+
+:mod:`pwnlib.util.getdents` --- Linux binary directory listing
+==============================================================
+
+.. automodule:: pwnlib.util.getdents
+   :members:

docs/source/util/iters.rst

@@ -17,19 +17,19 @@
      count                                  ,
      cycle                                  ,
      dropwhile                              ,
+     filter                                 ,
+     filterfalse                            ,
      groupby                                ,
-     ifilter                                ,
-     ifilterfalse                           ,
-     imap                                   ,
      islice                                 ,
-     izip                                   ,
-     izip_longest                           ,
+     map                                    ,
      permutations                           ,
      product                                ,
      repeat                                 ,
      starmap                                ,
      takewhile                              ,
-     tee
+     tee                                    ,
+     zip                                    ,
+     zip_longest
 
 .. function:: chain
 
@@ -63,29 +63,29 @@
 
    Alias for :func:`itertools.groupby`
 
-.. function:: ifilter
+.. function:: filter
 
-   Alias for :func:`itertools.ifilter`
+   Alias for python3-style :func:`filter`
 
-.. function:: ifilterfalse
+.. function:: filterfalse
 
-   Alias for :func:`itertools.ifilterfalse`
+   Alias for :func:`itertools.filterfalse`
 
-.. function:: imap
+.. function:: map
 
-   Alias for :func:`itertools.imap`
+   Alias for python3-style :func:`map`
 
 .. function:: islice
 
    Alias for :func:`itertools.islice`
 
-.. function:: izip
+.. function:: zip
 
-   Alias for :func:`itertools.izip`
+   Alias for python3-style :func:`zip`
 
-.. function:: izip_longest
+.. function:: zip_longest
 
-   Alias for :func:`itertools.izip_longest`
+   Alias for :func:`itertools.zip_longest`
 
 .. function:: permutations
 

docs/source/util/misc.rst

@@ -1,8 +1,8 @@
 .. testsetup:: *
 
+   from pprint import pprint
    from pwnlib.util.misc import *
    import os, subprocess
-   os.chdir("..")
 
 :mod:`pwnlib.util.misc` --- We could not fit it any other place
 ===============================================================

docs/source/util/net.rst

@@ -2,7 +2,6 @@
 
    from pwnlib.util.net import *
 
-
 :mod:`pwnlib.util.net` --- Networking interfaces
 ===================================================
 

docs/source/util/proc.rst

@@ -1,6 +1,7 @@
 .. testsetup:: *
 
    from pwnlib.util.proc import *
+   from pwnlib.tubes.process import process
    import os, sys
 
 

docs/source/util/safeeval.rst

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

docs/source/util/sh_string.rst

@@ -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:

docs/source/util/web.rst

@@ -1,5 +1,7 @@
 .. testsetup:: *
 
+   import tempfile
+
    from pwnlib.context import context
    from pwnlib.util.web import *
 

examples/README.md

@@ -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:
 
@@ -26,6 +26,10 @@ Try running this example with::
 ```
 Example showing the interface to `pwnlib.asm.asm` and `pwnlib.shellcraft`.
 ```
+* `attach.py`
+```
+Example showing `pwnlib.gdb.attach()`
+```
 * `clean_and_log.py`
 ```
 Use case for `pwnlib.tubes.tube.clean_and_log`.
@@ -65,8 +69,7 @@ Example showing `pwnlib.ui.options()`
 ```
 * `port_forward.py`
 ```
-A very simple port forwarder using `pwnlib.tubes.tube.connect_both()`.  Notice
-that `<>` is just a shorthand.
+A very simple port forwarder using `pwnlib.tubes.tube.connect_both()`.
 ```
 * `readline_completers.py`
 ```
@@ -74,6 +77,10 @@ Example showing pwnlib's readline implementation and a few completers.  This
 part of pwnlib will probably see some major changes soon, but we wanted to show
 off some proof-of-concepts.
 ```
+* `remote.py`
+```
+Example showing how to use the remote class.
+```
 * `remote_gdb_debugging.py`
 ```
 Simple example showing how to use the remote
@@ -103,7 +110,7 @@ and::
 
   $ TERM=xterm-256color python text.py
 ```
-* `remote.py`
+* `yesno.py`
 ```
-Example showing how to use the remote class.
+Example showing `pwnlib.ui.yesno()`
 ```

examples/android.py

@@ -0,0 +1,25 @@
+from __future__ import print_function
+
+import gdb
+from pwn import adb, context
+
+# 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()

examples/args.py

@@ -14,5 +14,5 @@ Try running this example with::
 
 from pwn import *
 
-print args['RHOST'] or 'RHOST is not set'
-print args['RPORT'] or 'RPORT is not set'
+print(args['RHOST'] or 'RHOST is not set')
+print(args['RPORT'] or 'RPORT is not set')

examples/asm.py

@@ -3,10 +3,11 @@ 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)
 
-print enhex(shellcode_asm)
-print disasm(shellcode_asm)
+print(enhex(shellcode_asm))
+print(disasm(shellcode_asm))

examples/attach.py

@@ -0,0 +1,12 @@
+"""
+Example showing `pwnlib.gdb.attach()`
+"""
+
+from pwn import *
+
+bash = process('/bin/bash')
+gdb.attach(bash, gdbscript = '''
+p "hello from pwnlib"
+c
+''')
+bash.interactive()

examples/clean_and_log.py

@@ -25,5 +25,4 @@ atexit.register(r.clean_and_log)
 
 while True:
     line = r.recvline()
-    print re.findall('^prefix (\S+)$', line)[0]
-
+    print(re.findall(r'^prefix (\S+)$', line)[0])

examples/fmtstr/Makefile

@@ -0,0 +1,53 @@
+CFLAGS := -Wno-unused-result -Wno-format-security
+TARGETS := printf.mips printf.mips64 printf.mipsel printf.mips64el printf.arm printf.aarch64 \
+	         printf.ppc printf.ppc64 printf.sparc64 printf.native printf.native32 \
+	         printf-loop.native printf-loop.native32
+
+.PHONY: run
+run: all
+	./exploit2.py
+	./exploit.py
+
+.PHONY: all
+all: $(TARGETS)
+
+.PHONY: clean
+clean:
+	rm -f $(TARGETS)
+
+# mips variants
+%.mips: %.c
+	mips-linux-gnu-gcc $(CFLAGS) -static -Os -o "$@" $^
+%.mipsel: %.c
+	mipsel-linux-gnu-gcc $(CFLAGS) -static -Os -o "$@" $^
+%.mips64: %.c
+	mips64-linux-gnuabi64-gcc $(CFLAGS) -static -Os -o "$@" $^
+%.mips64el: %.c
+	mips64el-linux-gnuabi64-gcc $(CFLAGS) -static -Os -o "$@" $^
+
+# arm variants
+%.arm: %.c
+	arm-linux-gnueabi-gcc $(CFLAGS) -static -Os -o "$@" $^
+%.aarch64: %.c
+	aarch64-linux-gnu-gcc $(CFLAGS) -static -Os -o "$@" $^
+
+# ppc variants
+%.ppc: %.c
+	powerpc-linux-gnu-gcc $(CFLAGS) -static -Os -o "$@" $^
+%.ppc64: %.c
+	powerpc64-linux-gnu-gcc $(CFLAGS) -static -Os -o "$@" $^
+
+# sparc variants
+%.sparc64: %.c
+	sparc64-linux-gnu-gcc $(CFLAGS) -static -Os -o "$@" $^
+
+# native variants
+%.native: %.c
+	gcc $(CFLAGS) -o "$@" $^
+%.native32: %.c
+	gcc $(CFLAGS) -m32 -o "$@" $^
+
+# install deps on ubuntu xenial
+.PHONY: install-apt
+install-apt:
+	apt-get install -y make gcc-mips64el-linux-gnuabi64 gcc-sparc64-linux-gnu gcc-powerpc64-linux-gnu gcc-powerpc-linux-gnu gcc-arm-linux-gnueabi gcc-aarch64-linux-gnu gcc-mips64-linux-gnuabi64 gcc-mipsel-linux-gnu gcc-mips64el-linux-gnuabi64 gcc-mips-linux-gnu gcc-i686-linux-gnu gcc