Release 3.4.0

We cannot determine the length of the file if passed e.g. a tube or a pipe or PTY or character device (e.g. stdin or /dev/null).

Supercedes: 9c2f0f4e
(cherry picked from commit 14f717b7b4)

.coveragerc

@@ -0,0 +1,8 @@
+[run]
+branch = True
+omit =
+    */constants/*
+source =
+    pwn
+    pwnlib
+    ~/.pwntools-cache/

.gitattributes

@@ -0,0 +1 @@
+pwnlib/data/* linguist-vendored

.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,9 @@
+# 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 in `extra/docker/Dockerfile` to save time.
+
+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/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,27 @@
+# Pwntools Pull Request
+
+Thanks for contributing to Pwntools!  Take a moment to look at [`CONTRIBUTING.md`][contributing] to make sure you're familiar with Pwntools development.
+
+Please provide a high-level explanation of what this pull request is for.
+
+## Testing
+
+Pull Requests that introduce new code should try to add doctests for that code.  See [`TESTING.md`][testing] for more information.
+
+## Target Branch
+
+Depending on what the PR is for, it needs to target a different branch.
+
+You can always [change the branch][change] after you create the PR if it's against the wrong branch.
+
+| Branch   | Type of PR                                                       |
+| -------- | ---------------------------------------------------------------- |
+| `dev`    | New features, and enhancements
+| `dev`    | Documentation fixes and new tests
+| `stable` | Bug fixes that affect the current `stable` branch
+| `beta`   | Bug fixes that affect the current `beta` branch, but not `stable`
+| `dev`    | Bug fixes for code that has never been released
+
+[contributing]: https://github.com/Gallopsled/pwntools/blob/dev/CONTRIBUTING.md
+[testing]: https://github.com/Gallopsled/pwntools/blob/dev/TESTING.md
+[change]: https://github.com/blog/2224-change-the-base-branch-of-a-pull-request

.gitignore

@@ -2,10 +2,16 @@
 *.hi
 *.pyc
 *~
+*.swp
+.ropeproject
 *.pdf
 */auto/*
 */bin/*
+docs/build
 build
 MANIFEST
 dist
-pwntools.egg-info
+*.egg-info
+*.core
+.coverage
+.tox

.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

@@ -0,0 +1,43 @@
+sudo: false
+language: python
+addons:
+  apt:
+    packages:
+    - gcc-multilib
+    - gcc-4.6-arm-linux-gnueabihf
+    - lib32stdc++6
+    - ash
+    - bash
+    - dash
+    - ksh
+    - mksh
+    - zsh
+    - pandoc
+    - gdb
+cache:
+    - pip
+    - directories:
+        - usr
+        - /home/travis/virtualenv/python2.7.9/lib/python2.7/site-packages/
+        - /home/travis/virtualenv/python2.7.9/bin/
+python:
+  - "2.7"
+before_install:
+  - echo $-
+  - source travis/install.sh
+  - source travis/ssh_setup.sh
+  - echo $-
+install:
+  - pip install --upgrade pip
+  - pip install --upgrade --editable .
+  - pip install --upgrade --requirement docs/requirements.txt
+before_script:
+  - PWNLIB_NOTERM=1 python -c 'from pwn import *; print pwnlib.term.term_mode'
+  - PWNLIB_NOTERM=1 python -c 'from pwn import *; print pwnlib.term.term_mode'
+  - PWNLIB_NOTERM=1 python -c 'from pwn import *; print pwnlib.term.term_mode'
+  - PWNLIB_NOTERM=1 python -c 'from pwn import *; print pwnlib.term.term_mode'
+script:
+  - PWNLIB_NOTERM=1 coverage run -m sphinx -b doctest docs/source docs/build/doctest
+after_success:
+  - coveralls
+  - source travis/update_demo.sh

CHANGELOG.md

@@ -0,0 +1,348 @@
+# Changelog
+
+This changelog only includes added major features and changes. Bugfixes and
+minor changes are omitted.
+
+## Release History
+
+The table below shows which release corresponds to each branch, and what date the version was released.
+
+| Version          | Branch   | Release Date           |
+| ---------------- | -------- | ---------------------- |
+| [3.6.0](#350)    | `dev`    | May 6, 2017 (planned)
+| [3.5.0](#350)    | `beta`   | Mar 25, 2017 (planned)
+| [3.4.0](#340)    | `stable` | Feb 13, 2017
+| [3.3.4](#334)    |          | Jan 12, 2016
+| [3.3.3](#333)    |          | Jan 10, 2016
+| [3.3.2](#332)    |          | Jan 10, 2016
+| [3.3.1](#331)    |          | Jan 10, 2016
+| [3.3.0](#330)    |          | Dec 24, 2016
+| [3.2.1](#321)    |          | Dec 24, 2016
+| [3.2.0](#320)    |          | Nov 12, 2016
+| [3.1.1](#311)    |          | Oct 23, 2016
+| [3.1.0](#310)    |          | Oct 2, 2016
+| [3.0.4](#304)    |          | Sept 19, 2016
+| [3.0.3](#303)    |          | Sept 18, 2016
+| [3.0.2](#302)    |          | Sept 6, 2016
+| [3.0.1](#301)    |          | Aug 20, 2016
+| [3.0.0](#300)    |          | Aug 20, 2016
+| [2.2.0](#220)    |          | Jan 5, 2015
+
+
+## 3.6.0
+
+To be released on May 6, 2017.
+
+## 3.5.0
+
+To be released on Mar 25, 2017.
+
+## 3.4.0
+
+- [#800][800] Add `shell=` option to `ssh.process()`
+- [#806][806] Add `context.buffer_size` for fine-tuning `tube` performance
+    + Also adds `buffer_fill_size=` argument for all tubes
+- [b83a6c7][b83a6c7] Fix undocumented `process.leak` function
+- [546061e][546061e] Modify `coredump_filter` of all spawned processes, so that core dumps are more complete
+- [#809][809] Add several functions to `adb` (`unlink`, `mkdir`, `makedirs`, `isdir`, `exists`)
+- [#817][817] Make disconnection detection more robust
+
+[800]: https://github.com/Gallopsled/pwntools/pull/800
+[806]: https://github.com/Gallopsled/pwntools/pull/806
+[809]: https://github.com/Gallopsled/pwntools/pull/809
+[817]: https://github.com/Gallopsled/pwntools/pull/817
+[5d9792f]: https://github.com/Gallopsled/pwntools/commit/5d9792f
+[b83a6c7]: https://github.com/Gallopsled/pwntools/commit/b83a6c7
+[546061e]: https://github.com/Gallopsled/pwntools/commit/546061e
+
+## 3.3.4
+
+- [#850][850] and [#846][846] fix issues with `hexdump` and the `phd` command-line utility, when using pipes (e.g. `echo foo | phd`)
+- [#852][852] Fixes register ordering in `regsort`
+- [#853][853] Fixes the registers restored in `shellcraft.amd64.popad`
+
+[846]: https://github.com/gallopsled/pwntools/pull/846
+[850]: https://github.com/gallopsled/pwntools/pull/850
+[852]: https://github.com/gallopsled/pwntools/pull/852
+[853]: https://github.com/gallopsled/pwntools/pull/853
+
+## 3.3.3
+
+- [#843][843] fixed a bug in `amd64.mov`.
+
+[843]: https://github.com/gallopsled/pwntools/pull/843
+
+## 3.3.2
+
+- [#840][840] fixed a regression introduced by [#837][837].
+
+[840]: https://github.com/gallopsled/pwntools/pull/840
+
+## 3.3.1
+
+- [#833][833] Fixed a performance-impacting bug in the adb module.
+- [#837][837] Fixed a bug([#836][836]) causing `hexdump(cyclic=True)` to throw an exception.
+
+[833]: https://github.com/Gallopsled/pwntools/pull/833
+[837]: https://github.com/Gallopsled/pwntools/pull/837
+[836]: https://github.com/Gallopsled/pwntools/issues/836
+
+## 3.3.0
+
+- [b198ec8][b198ec8] Added `tube.stream()` function, which is like `tube.interact()` without a prompt or keyboard input.
+    + Effectively, this is similar to `cat file` and just prints data as fast as it is received.
+- [aec3fa6][aec3fa6] Disable update checks against GitHub
+    + These checks frequently broke due to GitHub query limits
+- [#757][757] Fixed `adb.wait_for_device()` re-use of the same connection
+- [f9133b1][f9133b1] Add a `STDERR` magic argument to make logging go to `stderr` instead of `stdout`
+    + Usage is e.g. `python foo.py STDERR` or `PWNLIB_STDERR=1 python foo.py`
+    + Also adds `context.log_console` to log to any file or terminal
+- [67e11a9][67e11a9] Add faster error checking to `cyclic()` when provided very large values
+- [5fda658][5fda658] Expose BitPolynom in `globals()`
+- [#765][765] Added `-d` option for hex-escaped output for `shellcraft` command-line tool
+- [#772][772] Fixed bash completion regressions
+- [30c34b7][30c34b7] Fix `ROP.call()` with `Function` objects from `ELF.functions`
+- [fa402ce][fa402ce] Add `adb.uptime` and `adb.boot_time`
+- [82312ba][82312ba] Add `cyclic_metasploit` and `cyclic_metasploit_find`
+
+[757]: https://github.com/Gallopsled/pwntools/pull/757
+[765]: https://github.com/Gallopsled/pwntools/pull/765
+[772]: https://github.com/Gallopsled/pwntools/pull/772
+[b198ec8]: https://github.com/Gallopsled/pwntools/commit/b198ec8
+[aec3fa6]: https://github.com/Gallopsled/pwntools/commit/aec3fa6
+[f9133b1]: https://github.com/Gallopsled/pwntools/commit/f9133b1
+[67e11a9]: https://github.com/Gallopsled/pwntools/commit/67e11a9
+[5fda658]: https://github.com/Gallopsled/pwntools/commit/5fda658
+[30c34b7]: https://github.com/Gallopsled/pwntools/commit/30c34b7
+[fa402ce]: https://github.com/Gallopsled/pwntools/commit/fa402ce
+[82312ba]: https://github.com/Gallopsled/pwntools/commit/82312ba
+
+## 3.2.1
+
+Multiple bug fixes.
+
+- [#783][783] Fix `adb.uninstall` typo
+- [#787][787] Added error handling for `ssh.process` argument `preexec_fn`
+- [#793][793] Fixed progress message in `remote()` when connections failed
+- [#802][802] Fixed partition listing in `adb.partitions`, which accidentally shelled out to the `adb` binary
+- [#804][804] Fix error message for 32-bit distributions
+- [#805][805] Fix exception in `Core.segments` when a segment has no name
+- [#811][811] Fixes and performance improvements for `adb.wait_for_device()`
+- [#813][813] Fixed a release script
+- [#814][814] Fixed exceptions thrown if the `$HOME` directory is not writable
+- [#815][815] Properly handle `None` in `MemLeak`
+
+[783]: https://github.com/Gallopsled/pwntools/pull/783
+[787]: https://github.com/Gallopsled/pwntools/pull/787
+[793]: https://github.com/Gallopsled/pwntools/pull/793
+[802]: https://github.com/Gallopsled/pwntools/pull/802
+[804]: https://github.com/Gallopsled/pwntools/pull/804
+[805]: https://github.com/Gallopsled/pwntools/pull/805
+[811]: https://github.com/Gallopsled/pwntools/pull/811
+[813]: https://github.com/Gallopsled/pwntools/pull/813
+[814]: https://github.com/Gallopsled/pwntools/pull/814
+[815]: https://github.com/Gallopsled/pwntools/pull/815
+
+## 3.2.0
+
+- [#695][695] Fixed a performance regression in `phd`.
+- [452605e][452605e] Fixed [#629][629] related to correct removal of temporary files.
+- [ea94ee4][ea94ee4] Disallows semi-colons in for the `run_in_terminal` function, since it did not work properly in all cases.
+- [6376d07][6376d07] Added the mips shellcode `pushstr_array`.
+- [#700][700] Added missing MIPS shellcode documentation to readthedocs, and enabled unit tests
+- [#701][701] Command line tools refactored to have a common `pwn` entry point.
+    + Added an option to *not* install the traditional `asm`, `disasm`, `checksec`, etc scripts
+    + All existing tools can be accessed from the `pwn` command (e.g. `pwn asm nop`).
+- [#704][704] The `process` object has a new, optional argument `alarm` for setting a `SIGALRM` timeout for processes.
+- [#705][705] Added the Android Emulator to the test suite and Travis CI.
+    + Android Emulator is now required for the full test suite
+    + Android Emulator tests are skipped if no Android-related changes are detected
+- [#711][711] `DynELF` has a new attribute, `heap`, which leaks the current `brk` address (heap base).  This is useful for finding heap allocations with dlmalloc-derived allocators like those used by Glibc.
+- [#717][717] `sh_string` was rewritten to emit more compact and compatible strings
+    + This was achieved by embedding single-quoted non-printable literals
+    + Much more testing was added
+    + Emitted strings are no longer copy-paste compatible, but work fine with e.g. `tubes` module and the default `subprocess` module
+- [#709][709] The `adb` module now directly talks to the `adb` server process via a new module, `adb.protocol`
+    + Removes the need to shell out to `adb`
+    + Avoids version-compatibility issues with `adb` server vs. client
+- [#703][703] Added new methods to `adb`
+    + `install` - Installs an APK
+    + `uninstall` - Uninstalls a package
+    + `packages` - Lists installed packages
+- [4893819][4893819] Modified `shellcraft.sh` on all platforms to provide `argv[0]` and set `argc==1`
+    + This is needed for systems which have Busybox or other minimal shell for `/bin/sh` which does not behave well with `argc==0` or `argv[0]==NULL`.
+- [1e414af][1e414af] Added `connect()` alias for `remote()`
+    + For example, `io=connect('google.com', 80)`
+    + This also works with `tcp(...)` and `udp(...)` aliases
+- [869ec42][869ec42] Added `ssh.read()` and `ssh.write()` aliases
+- [2af55c9][2af55c9] `AdbDevice` objects exposed via e.g. `adb.devices()` now offer scoped access to all `adb` module properties
+    + It is now possible to e.g. `map(lambda d: d.process(['id']).recvall(), adb.devices())`
+
+
+[629]: https://github.com/Gallopsled/pwntools/issues/629
+[695]: https://github.com/Gallopsled/pwntools/pull/695
+[700]: https://github.com/Gallopsled/pwntools/pull/700
+[701]: https://github.com/Gallopsled/pwntools/pull/701
+[704]: https://github.com/Gallopsled/pwntools/pull/704
+[711]: https://github.com/Gallopsled/pwntools/pull/711
+[717]: https://github.com/Gallopsled/pwntools/pull/717
+[709]: https://github.com/Gallopsled/pwntools/pull/709
+[705]: https://github.com/Gallopsled/pwntools/pull/705
+[703]: https://github.com/Gallopsled/pwntools/pull/703
+[452605e]: https://github.com/Gallopsled/pwntools/commit/452605e854f4870ef5ccfdf7fb110dfd75c50feb
+[ea94ee4]: https://github.com/Gallopsled/pwntools/commit/ea94ee4ca5a8060567cc9bd0dc33796a89ad0b95
+[6376d07]: https://github.com/Gallopsled/pwntools/commit/6376d072660fb2250f48bd22629bbd7e3c61c758
+[1e414af]: https://github.com/Gallopsled/pwntools/commit/1e414afbeb3a01242f4918f111febaa63b640eb7
+[869ec42]: https://github.com/Gallopsled/pwntools/commit/869ec42082b4b98958dfe85103da9b101dde7daa
+[4893819]: https://github.com/Gallopsled/pwntools/commit/4893819b4c23182da570e2f4ea4c14d73af2c0df
+[2af55c9]: https://github.com/Gallopsled/pwntools/commit/2af55c9bc382eca23f89bc0abc7a07c075521f94
+
+## 3.1.1
+
+Fixed a bug in `MemLeak.struct` (PR: #768).
+
+## 3.1.0
+
+A number of smaller bugfixes and documentation tweaks.
+
+## 3.0.4
+
+- Fixed a bug that made 3.0.3 uninstallable (Issue: #751, PR: #752)
+
+## 3.0.3
+
+- Fixed some performance and usability problems with the update system (Issues:
+  #723, #724, #736. PRs: #729, #738, #747).
+- Fixed a bug related to internals in pyelftools (PRs: #730, #746).
+- Fixed an issue with travis (Issue: #741, PRs: #743, #744, #745).
+
+## 3.0.2
+
+- Cherry-pick #695, as this was a regression-fix.
+- Added a fix for the update checker, as it would suggest prereleases as updates to stable releases.
+- Various documentation fixes.
+
+## 3.0.1
+
+A small bugfix release. There were a lot of references to the `master`-branch, however after 3.0.0 we use the names `stable`, `beta` and `dev` for our branches.
+
+## 3.0.0
+
+This was a large release (1305 commits since 2.2.0) with a lot of bugfixes and changes.  The Binjitsu project, a fork of Pwntools, was merged back into Pwntools.  As such, its features are now available here.
+
+As always, the best source of information on specific features is the comprehensive docs at https://pwntools.readthedocs.org.
+
+This list of changes is non-complete, but covers all of the significant changes which were appropriately documented.
+
+#### Android
+
+Android support via a new `adb` module, `context.device`, `context.adb_host`, and `context.adb_port`.
+
+#### Assembly and Shellcode
+
+- Assembly module enhancements for making ELF modules from assembly or pre-assembled shellcode.  See `asm.make_elf` and `asm.make_elf_from_assembly`.
+- `asm` and `shellcraft` command-line tools support flags for the new shellcode encoders
+- `asm` and `shellcraft` command-line tools support `--debug` flag for automatically launching GDB on the result
+- Added MIPS, PowerPC, and AArch64 support to the `shellcraft` module
+- Added Cyber Grand Challenge (CGC) support to the `shellcraft` module
+- Added syscall wrappers for every Linux syscall for all supported architectures to the `shellcraft` module
+    + e.g. `shellcraft.<arch>.gettimeofday`
+- (e.g. `shellcraft.i386.linux.`)
+- Added in-memory ELF loaders for most supported architectures
+    + Only supports statically-linked binaries
+    + `shellcraft.<arch>.linux.loader`
+
+#### Context Module
+
+- Added `context.aslr` which controls ASLR on launched processes.  This works with both `process()` and `ssh.process()`, and can be specified per-process with the `aslr=` keyword argument.
+- Added `context.binary` which automatically sets all `context` variables from an ELF file.
+- Added `context.device`, `context.adb`, `context.adb_port`, and `context.adb_host` for connecting to Android devices.
+- Added `context.kernel` setting for SigReturn-Oriented-Programming (SROP).
+- Added `context.log_file` setting for sending logs to a file.  This can be set with the `LOG_FILE` magic command-line option.
+- Added `context.noptrace` setting for disabling actions which require `ptrace` support.  This is useful for turning all `gdb.debug` and `gdb.attach` options into no-ops, and can be set via the `NOPTRACE` magic command-line option.
+- Added `context.proxy` which hooks all connections and sends them to a SOCKS4/SOCKS5.  This can be set via the `PROXY` magic command-line option.
+- Added `context.randomize` to control randomization of settings like XOR keys and register ordering (default off).
+- Added `context.terminal` for setting how to launch commands in a new terminal.
+
+#### DynELF and MemLeak Module
+
+- Added a `DynELF().libc` property which attempt to find the remote libc and download the ELF from LibcDB.
+- Added a `DynELF().stack` property which leaks the `__environ` pointer from libc, making it easy to leak stack addresses.
+- Added `MemLeak.String` and `MemLeak.NoNewlines` and other related helpers for handling special leakers which cannot e.g. handle newlines in the leaked addresses and which leak a C string (e.g. auto-append a `'\x00'`).
+- Enhancements for leaking speed via `MemLeak.compare` to avoid leaking an entire field if we can tell from a partial leak that it does not match what we are searching for.
+
+#### Encoders Module
+
+- Added a `pwnlib.encoders` module for assembled-shellcode encoders/decoders
+- Includes position-independent basic XOR encoders
+- Includes position-independent delta encoders
+- Includes non-position-independent alphanumeric encoders for Intel
+- Includes position-independent alphanumeric encoders for ARM/Thumb
+
+#### ELF Module
+
+- Added a `Core` object which can parse core-files, in order to extract / search for memory contents, and extract register states (e.g. `Core('./corefile').eax`).
+
+#### Format Strings
+
+- Added a basic `fmtstr` module for assisting with Format String exploitation
+
+#### GDB Module
+
+- Added support for debugging Android devices when `context.os=='android'`
+- Added helpers for debugging shellcode snippets with `gdb.debug_assembly()` and `gdb.debug_shellcode()`
+
+#### ROP Module
+
+- Added support for SigReturn via `pwnlib.rop.srop`
+    + Occurs automatically when syscalls are invoked and a function cannot be found
+    + SigReturn frames can be constructed manually with `SigreturnFrame()` objects
+- Added functional doctests for ROP and SROP
+
+#### Tubes Process Module
+
+- `process()` has many new options, check out the documentation
+    + `aslr` controls ASLR
+    + `setuid` can disable the effect of setuid, allowing core dumps (useful for extracting crash state via the new `Core()` object)
+    + TTY echo and control characters can be enabled via `raw` argument
+- `stdout` and `stderr` are now PTYs by default
+    + `stdin` can be set to a PTY also via setting `stdin=process.PTY`
+
+#### Tubes SSH Module
+
+- Massive enhancements all over
+- `ssh` objects now have a `ssh.process()` method which avoids the need to handle shell expansion via the old `ssh.run()` method
+- Files are downloaded via SFTP if available
+- New `download` and `upload` methods auto-detect whether the target is a file or directory and acts accordingly
+- Added `listen()` method alias for `listen_remote()`
+- Added `remote()` method alias for `connect_remote()`
+
+#### Utilities
+
+- Added `fit()` method to combine the functionality of `flat()` with the functionality of `cyclic()`
+- Added `negative()` method to negate the value of an integer via two's complement, with respect to the current integer size (`context.bytes`).
+- Added `xor_key()` method to generate an XOR key which avoids undesirable bytes over a given input.
+- Added a multi-threaded `bruteforce()` implementation, `mbruteforce()`.
+- Added `dealarm_shell()` helper to remove the effects of `alarm()` after you've popped a shell.
+
+## 2.2.0
+
+This was a large release with a lot of bugfixes and changes. Only the most significant
+are mentioned here.
+
+- Added shellcodes
+- Added phd
+- Re-added our expansion of itertools
+- Added replacements for some semi-broken python standard library modules
+- Re-implemented the rop module
+- Added a serial tube
+- Huge performance gains in the buffering for tubes
+- Re-added user agents
+- Begun using Travis CI with lots of test
+- Removed bundled binutils in favor of documenting how to build them yourselves
+- Added support for port forwarding though our SSH module
+- Added dependency for capstone and ropgadget
+- Added a lots of shellcodes
+- Stuff we forgot
+- Lots of documentation fixes
+- Lots of bugfixes

CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# Contributing
+
+Github has a great guide for contributing to open source projects:
+
+- [Contributing to a project](https://guides.github.com/activities/forking/)
+- [Fork the repository](https://guides.github.com/activities/forking/#fork)
+- [Clone your fork](https://guides.github.com/activities/forking/#clone)
+- [Making and pushing changes](https://guides.github.com/activities/forking/#making-changes)
+- [Making a Pull Request](https://guides.github.com/activities/forking/#making-a-pull-request)
+- [Huzzah!](https://guides.github.com/activities/forking/#huzzah)
+
+## 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).
+
+After you have documentation, you should add a [doctest](https://docs.python.org/2/library/doctest.html).
+
+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 the branch in question.
+
+## Automated Testing
+
+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.
+
+You can find more information on testing in [TESTING.md](TESTING.md).

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
+recursive-include pwn    *.py *.asm *.rst *.md *.txt *.sh
+recursive-exclude *.pyc

README.md

@@ -1,38 +1,56 @@
-# Introduction
+# pwntools - CTF toolkit
+![pwntools logo](https://github.com/Gallopsled/pwntools/blob/stable/docs/source/logo.png?raw=true)
 
-This is the CTF framework used by Gallopsled in every CTF.
+[![Docs](https://readthedocs.org/projects/pwntools/badge/?version=stable)](https://docs.pwntools.com/)
+[![PyPI](https://img.shields.io/badge/pypi-v3.4.0-green.svg?style=flat)](https://pypi.python.org/pypi/pwntools/)
+[![Travis](https://travis-ci.org/Gallopsled/pwntools.svg)](https://travis-ci.org/Gallopsled/pwntools)
+[![Coveralls](https://img.shields.io/coveralls/Gallopsled/pwntools/dev.svg)](https://coveralls.io/github/Gallopsled/pwntools?branch=dev)
+[![Twitter](https://img.shields.io/badge/twitter-pwntools-4099FF.svg?style=flat)](https://twitter.com/pwntools)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat)](http://choosealicense.com/licenses/mit/)
 
-Most code is inside the pwnlib folder with some functionality inside pwn or
-bin. It is typically used as:
+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 *
 context(arch = 'i386', os = 'linux')
 
-# EXPLOIT HERE
+r = remote('exploitme.example.com', 31337)
+# EXPLOIT CODE GOES HERE
+r.send(asm(shellcraft.sh()))
+r.interactive()
 ```
 
-However we have made command-line frontends for some of the functionality
-inside the pwnlib. These are:
+# Try It Now!
 
-* `asm`/`disasm`: Small wrapper for various assemblers
-* `constgrep`: Tool for finding constants defined in header files
-* `cyclic`: De Bruijn sequence generator and lookup tool
-* `hex`/`unhex`: Command line tools for doing common hexing/unhexing operations
-* `shellcraft`: Frontend to our shellcode
+You can now do a live demo of Pwntools, [right in your browser](https://demo.pwntools.com).
 
 # Documentation
-Our documentation is available on http://pwntools.readthedocs.org/
+
+Our documentation is available at [docs.pwntools.com](https://docs.pwntools.com/)
+
+To get you started, we've provided some example solutions for past CTF challenges in our [write-ups repository](https://github.com/Gallopsled/pwntools-write-ups).
 
 # Installation
-Pwntools is available as a pip package. You can install it by running
-`pip install pwntools`.
 
-Alternatively if you prefer to have the latest version in git, you can
-simply clone this repository, run `pip install -r requirements.txt`
-and add entries in your `PATH` and `PYTHONPATH` variables. The script
-`install_local.sh` will help you do so, in case you are using bash.
+pwntools is best supported on 64-bit Ubuntu 12.04 and 14.04, but most functionality should work on any Posix-like distribution (Debian, Arch, FreeBSD, OSX, etc.).  Python 2.7 is required.
+
+Most of the functionality of pwntools is self-contained and Python-only.  You should be able to get running quickly with
+
+```sh
+apt-get update
+apt-get install python2.7 python-pip python-dev git libssl-dev libffi-dev
+pip install --upgrade pwntools
+```
+
+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, feel free to join us
-at `#gallopsled` on Freenode and ask away.
+If you have any questions not worthy of a [bug report](https://github.com/Gallopsled/pwntools/issues), feel free to ping us
+at [`#pwntools` on Freenode](irc://irc.freenode.net/pwntools) and ask away.
+Click [here](https://kiwiirc.com/client/irc.freenode.net/pwntools) to connect.
+There is also a [mailing list](https://groups.google.com/forum/#!forum/pwntools-users) for higher latency discussion.

TESTING.md

@@ -0,0 +1,39 @@
+# 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
+```
+
+## 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.

bin/asm

@@ -1,59 +0,0 @@
-#!/usr/bin/env python2
-
-import argparse, sys
-from pwnlib.asm           import asm
-from pwnlib.context       import __possible__ as contexts
-from pwnlib.util.fiddling import enhex
-
-parser = argparse.ArgumentParser(
-    description = 'Assemble shellcode into bytes'
-)
-
-parser.add_argument(
-    'lines',
-    metavar='line',
-    nargs='*',
-    help='Lines to assemble. If none are supplied, use stdin'
-)
-
-parser.add_argument(
-    "-f", "--format",
-    help="Output format (defaults to hex for ttys, otherwise raw)",
-    choices=['raw', 'hex', 'string']
-)
-
-parser.add_argument(
-    "-o","--output",
-    metavar='file',
-    help="Output file (defaults to stdout)",
-    type=argparse.FileType('w'),
-    default=sys.stdout
-)
-
-parser.add_argument(
-    '-c', '--context',
-    metavar = '<opt>',
-    choices = contexts['os'] + contexts['arch'],
-    default = ['i386','linux'],
-    action = 'append',
-    help = 'The os/architecture the shellcode will run in (default: linux/i386), choose from: %s' % \
-      ', '.join(contexts['os'] + contexts['arch'])
-)
-
-args   = parser.parse_args()
-tty    = args.output.isatty()
-
-for arch in args.context[::-1]:
-    if arch in contexts['arch']: break
-for os in args.context[::-1]:
-    if os in contexts['os']: break
-
-data   = '\n'.join(args.lines) or sys.stdin.read()
-output = asm(data.replace(';', '\n'), arch = arch, os = os)
-fmt    = args.format or ('hex' if tty else 'raw')
-formatters = {'r':str, 'h':enhex, 's':repr}
-
-args.output.write(formatters[fmt[0]](output))
-
-if tty and fmt is not 'raw':
-    args.output.write('\n')

bin/constgrep

@@ -1,136 +0,0 @@
-#!/usr/bin/env python2
-
-import argparse, sys, os, types, re
-from pwnlib import asm, util, constants
-from pwnlib.util import safeeval
-from pwnlib.context import __possible__ as contexts
-
-p = argparse.ArgumentParser(
-    description = "Looking up constants from header files.\n\nExample: constgrep -c freebsd -m  ^PROT_ '3 + 4'",
-    formatter_class = argparse.RawDescriptionHelpFormatter,
-)
-
-group = p.add_mutually_exclusive_group()
-group.add_argument(
-    '-e', '--exact',
-    metavar = '<constant name>',
-    # nargs = 1,
-    default = None,
-    help = 'Do an exact match for a constant instead of searching for a regex',
-)
-group.add_argument(
-    'regex',
-    nargs = '?',
-    default = '',
-    help = 'The regex matching constant you want to find',
-)
-
-p.add_argument(
-    'constant',
-    nargs = '?',
-    default = None,
-    help = 'The constant to find',
-)
-
-p.add_argument(
-    '-i', '--case-insensitive',
-    action = 'store_true',
-    help = 'Search case insensitive',
-)
-
-p.add_argument(
-    '-m', '--mask-mode',
-    action = 'store_true',
-    help = 'Instead of searching for a specific constant value, search for values not containing strictly less bits that the given value.',
-)
-
-p.add_argument(
-    '-c', '--context',
-    metavar = '<opt>',
-    choices = contexts['os'] + contexts['arch'],
-    default = ['i386','linux'],
-    action = 'append',
-    help = 'The os/architecture to find constants for (default: linux/i386), choose from: %s' % \
-    ', '.join(dir(constants) + dir(constants.linux))
-)
-
-args = p.parse_args()
-
-# Find the architecture and os from the list of contexts
-for arch in args.context[::-1]:
-    if arch in contexts['arch']: break
-for os in args.context[::-1]:
-    if os in contexts['os']: break
-
-if args.exact:
-    # This is the simple case
-    print asm.cpp(args.exact, os = os, arch = arch).strip()
-else:
-    # New we search in the right module.
-    # But first: We find the right module
-    if os == 'freebsd':
-        mod = constants.freebsd
-    else:
-        mod = getattr(getattr(constants, os), arch)
-
-    # Compile the given regex, for optimized lookup
-    if args.case_insensitive:
-        matcher = re.compile(args.regex, re.IGNORECASE)
-    else:
-        matcher = re.compile(args.regex)
-
-    # Evaluate the given constant
-    if args.constant:
-        constant = safeeval.expr_eval(args.constant)
-    else:
-        constant = None
-
-    # The found matching constants and the length of the longest string
-    out    = []
-    maxlen = 0
-
-    for k in dir(mod):
-        # No python stuff
-        if k.endswith('__') and k.startswith('__'):
-            continue
-
-        # Run the regex
-        if not matcher.search(k):
-            continue
-
-        # Check the constant
-        if constant != None:
-            val = getattr(mod, k)
-            if args.mask_mode:
-                if constant & val != val:
-                    continue
-            else:
-                if constant != val:
-                    continue
-
-        # Append it
-        out.append((getattr(mod, k), k))
-        maxlen = max(len(k), maxlen)
-
-    # Output all matching constants
-    for _, k in sorted(out):
-        print '#define %s %s' % (k.ljust(maxlen), asm.cpp(k, os = os, arch = arch).strip())
-
-    # If we are in match_mode, then try to find a combination of
-    # constants that yield the exact given value
-    # We do not want to find combinations using the value 0.
-    if not (constant == None or constant == 0) and args.mask_mode:
-        mask = constant
-        good = []
-        out = [(v, k) for v, k in out if v != 0]
-
-        while mask and out:
-            cur = out.pop()
-            mask &= ~cur[0]
-            good.append(cur)
-
-            out = [(v, k) for v, k in out if mask & v == v]
-
-        if reduce(lambda x, cur: x | cur[0], good, 0) == constant:
-            print
-            print '(%s) == %s' % (' | '.join(k for v, k in good), args.constant)

bin/cyclic

@@ -1,69 +0,0 @@
-#!/usr/bin/env python2
-import argparse, string
-from pwnlib.util import cyclic, packing
-from pwnlib import log
-
-parser = argparse.ArgumentParser(
-    description = "Cyclic pattern creator/finder"
-)
-
-parser.add_argument(
-    '-a', '--alphabet',
-    metavar = 'alphabet',
-    default = string.ascii_lowercase,
-    help = 'The alphabet to use in the cyclic pattern (defaults to all lower case letters)',
-)
-
-parser.add_argument(
-    '-n', '--length',
-    metavar = 'length',
-    default = 4,
-    type = int,
-    help = 'Size of the unique subsequences (defaults to 4).'
-)
-
-group = parser.add_mutually_exclusive_group(required = True)
-group.add_argument(
-    '-l', '-o', '--offset', '--lookup',
-    metavar = '<lookup value>',
-    help = 'Do a lookup instead printing the alphabet',
-)
-
-group.add_argument(
-    'count',
-    type = int,
-    nargs = '?',
-    help = 'Number of characters to print'
-)
-
-args = parser.parse_args()
-alphabet = args.alphabet
-subsize  = args.length
-
-if args.lookup:
-    pat = args.lookup
-
-    if pat.startswith('0x'):
-        pat = packing.pack(int(pat[2:], 16), subsize*8, 'little', 'unsigned')
-    elif pat.isdigit():
-        pat = packing.pack(int(pat, 10), subsize*8, 'little', 'unsigned')
-
-    if len(pat) != 4:
-        log.fatal('Subpattern must be 4 bytes', 1)
-
-    if not all(c in alphabet for c in pat):
-        log.fatal('Pattern contains characters not present in the alphabet', 1)
-
-    offset = cyclic.cyclic_find(pat, alphabet, subsize)
-
-    if offset == -1:
-        log.fatal('Given pattern does not exist in cyclic pattern', 1)
-    else:
-        print offset
-else:
-    want   = args.count
-    result = cyclic.cyclic(want, alphabet, subsize)
-    got    = len(result)
-    if got < want:
-        log.failure("Alphabet too small (max length = %i)" % got)
-    print result

bin/disasm

@@ -1,38 +0,0 @@
-#!/usr/bin/env python2
-
-import argparse, sys
-from pwnlib import asm, context
-from string import whitespace, hexdigits
-
-parser = argparse.ArgumentParser(
-    description = 'Disassemble bytes into text format'
-)
-
-parser.add_argument(
-    'hex',
-    metavar = 'hex',
-    nargs = '*',
-    help = 'Hex-string to disasemble. If none are supplied, then it uses stdin in non-hex mode.'
-)
-
-parser.add_argument(
-    '-c', '--context',
-    metavar = '<opt>',
-    choices = context.__possible__['arch'],
-    default = 'i386',
-    help = 'The architecture of the shellcode (default: i386), choose from:\n%s' % ', '.join(context.__possible__['arch'])
-)
-
-args = parser.parse_args()
-
-if len(args.hex) > 0:
-    dat = ''.join(args.hex)
-    dat = dat.translate(None, whitespace)
-    if not set(hexdigits) >= set(dat):
-        print "This is not a hex string"
-        exit(-1)
-    dat = dat.decode('hex')
-else:
-    dat = sys.stdin.read()
-
-print asm.disasm(dat, arch = args.context)

bin/hex

@@ -1,7 +0,0 @@
-#!/usr/bin/env python2
-import sys
-
-if len(sys.argv) == 1:
-    print sys.stdin.read().encode('hex')
-else:
-    print ' '.join(sys.argv[1:]).encode('hex')

bin/shellcraft

@@ -1,173 +0,0 @@
-#!/usr/bin/env python2
-import argparse, sys, os, types
-import pwnlib
-from pwnlib import asm, log, util
-from pwnlib.context import __possible__ as contexts
-import pwnlib.term.text as text
-
-r = text.red
-g = text.green
-b = text.blue
-banner = '\n'.join(['  ' + r('____') + '  ' + g('_') + '          ' + r('_') + ' ' + g('_') + '                 ' + b('__') + ' ' + r('_'),
-                    ' ' + r('/ ___|') + g('| |__') + '   ' + b('___') + r('| |') + ' ' + g('|') + ' ' + b('___') + ' ' + r('_ __') + ' ' + g('__ _') + ' ' + b('/ _|') + ' ' + r('|_'),
-                    ' ' + r('\___ \\') + g('| \'_ \\') + ' ' + b('/ _ \\') + ' ' + r('|') + ' ' + g('|') + b('/ __|') + ' ' + r('\'__/') + ' ' + g('_` |') + ' ' + b('|_') + r('| __|'),
-                    '  ' + r('___) |') + ' ' + g('| | |') + '  ' + b('__/') + ' ' + r('|') + ' ' + g('|') + ' ' + b('(__') + r('| |') + ' ' + g('| (_| |') + '  ' + b('_|') + ' ' + r('|_'),
-                    ' ' + r('|____/') + g('|_| |_|') + b('\\___|') + r('_|') + g('_|') + b('\\___|') + r('_|') + '  ' + g('\\__,_|') + b('_|') + '  ' + r('\\__|'),
-                    ''
-                    ])
-#  ____  _          _ _                 __ _
-# / ___|| |__   ___| | | ___ _ __ __ _ / _| |_
-# \___ \| '_ \ / _ \ | |/ __| '__/ _` | |_| __|
-#  ___) | | | |  __/ | | (__| | | (_| |  _| |_
-# |____/|_| |_|\___|_|_|\___|_|  \__,_|_|  \__|
-
-def _string(s):
-    out = []
-    for c in s:
-        co = ord(c)
-        if co >= 0x20 and co <= 0x7e and c not in '/$\'"`':
-            out.append(c)
-        else:
-            out.append('\\x%02x' % co)
-    return '"' + ''.join(out) + '"\n'
-
-def _carray(s):
-    out = []
-    for c in s:
-        out.append('0x' + util.fiddling.enhex(c))
-    return '{' + ', '.join(out) + '};\n'
-
-def _hex(s):
-    return pwnlib.util.fiddling.enhex(s) + '\n'
-
-p = argparse.ArgumentParser(
-    description = banner + '\nMicrowave shellcode -- Easy, fast and delicious',
-    formatter_class = argparse.RawDescriptionHelpFormatter,
-)
-
-p.add_argument(
-    'shellcode',
-    nargs = '?',
-    default = '',
-    metavar = '<shellcode>',
-    help = 'The shellcode you want',
-)
-
-p.add_argument(
-    'args',
-    nargs = '*',
-    metavar = '<arg>',
-    default = (),
-    help = 'Argument to the chosen shellcode',
-)
-
-p.add_argument(
-    '-?', '--show',
-    action = 'store_true',
-    help = 'Show shellcode documentation',
-)
-
-p.add_argument(
-    '-o', '--out',
-    metavar = '<file>',
-    type = argparse.FileType('w'),
-    default = sys.stdout,
-    help = 'Output file (default: stdout)',
-)
-
-p.add_argument(
-    '-f', '--format',
-    metavar = '<format>',
-    choices = ['r', 'raw',
-               's', 'str', 'string',
-               'c',
-               'h', 'hex',
-               'a', 'asm', 'assembly',
-               'p',
-               'i', 'hexii'],
-    default = 'hex',
-    help = 'Output format (default: hex), choose from {r}aw, {s}tring, {c}-style array, {h}ex string, hex{i}i, {a}ssembly code, {p}reprocssed code',
-)
-
-args = p.parse_args()
-
-def get_tree(path, val, result):
-    if path:
-        path += '.'
-
-    if path.startswith('common.'):
-        return
-
-    mods = []
-
-    for k in sorted(dir(val)):
-        if k and k[0] != '_':
-            cur = getattr(val, k)
-            if isinstance(cur, types.ModuleType):
-                mods.append((path + k, cur))
-            else:
-                result.append((path + k, cur))
-
-    for path, val in mods:
-        get_tree(path, val, result)
-    return result
-
-vals = get_tree('', pwnlib.shellcraft, [])
-if args.shellcode:
-    vals = [(k, val) for k, val in vals if k.startswith(args.shellcode + '.') or k == args.shellcode]
-
-if len(vals) == 0:
-    log.fatal("Cannot find subtree by the name of %r" % args.shellcode)
-elif len(vals) > 1:
-    for k, _ in vals:
-        print k
-    exit()
-else:
-    func = vals[0][1]
-
-if args.show:
-    print func.__doc__
-    exit()
-
-defargs = len(func.func_defaults or ())
-reqargs = func.func_code.co_argcount - defargs
-if len(args.args) < reqargs:
-    if defargs > 0:
-        log.fatal('%s takes at least %d arguments' % (args.shellcode, reqargs))
-    else:
-        log.fatal('%s takes exactly %d arguments' % (args.shellcode, reqargs))
-
-# Captain uglyness saves the day!
-for i in range(len(args.args)):
-    if args.args[i] in ['False', 'false']:
-        args.args[i] = False
-
-# And he strikes again!
-os = arch = None
-for k in args.shellcode.split('.')[:-1]:
-    if k in contexts['arch']:
-        arch = k
-    elif k in contexts['os']:
-        os = k
-
-code = func(*args.args)
-
-if args.format in ['a', 'asm', 'assembly']:
-    print code
-    exit()
-if args.format == 'p':
-    print pwnlib.asm.cpp(code, arch = arch, os = os)
-    exit()
-
-code = pwnlib.asm.asm(code, arch = arch, os = os)
-
-if args.format in ['s', 'str', 'string']:
-    code = _string(code)
-elif args.format == 'c':
-    code = _carray(code)
-elif args.format in ['h', 'hex']:
-    code = _hex(code)
-elif args.format in ['i', 'hexii']:
-    code = pwnlib.util.fiddling.hexii(code) + '\n'
-
-sys.stdout.write(code)

bin/unhex

@@ -1,11 +0,0 @@
-#!/usr/bin/env python2
-import sys
-from string import whitespace
-try:
-    if len(sys.argv) == 1:
-        s = sys.stdin.read().translate(None, whitespace)
-        sys.stdout.write(s.decode('hex'))
-    else:
-        sys.stdout.write(''.join(sys.argv[1:]).decode('hex'))
-except TypeError, e:
-    sys.stderr.write(str(e) + '\n')

docs/.gitignore

@@ -1 +1,2 @@
 build
+robots.txt

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)/.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,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

@@ -0,0 +1,16 @@
+sphinxcontrib-napoleon
+sphinxcontrib-autoprogram==0.1.2
+isort
+paramiko>=1.15.2
+mako>=1.0.0
+pyelftools>=0.2.3
+capstone
+ropgadget>=5.3
+pyserial>=2.7
+requests>=2.5.1
+pip>=6.0.8
+tox>=1.8.1
+pygments>=2.0
+sphinx_rtd_theme
+doc2dash
+coveralls

docs/source/about.rst

@@ -0,0 +1,56 @@
+About pwntools
+========================
+
+Whether you're using it to write exploits, or as part
+of another software project will dictate how you use it.
+
+Historically pwntools was used as a sort of exploit-writing DSL. Simply doing
+``from pwn import *`` in a previous version of pwntools would bring all sorts of
+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 familiarize themselves with pwntools quickly.
+* We would like to have even more side-effects, especially by putting the
+  terminal in raw-mode.
+
+To make this possible, we decided to have two different modules. :mod:`pwnlib`
+would be our nice, clean Python module, while :mod:`pwn` would be used during
+CTFs.
+
+:mod:`pwn` --- Toolbox optimized for CTFs
+-----------------------------------------
+
+.. module:: pwn
+
+As stated, we would also like to have the ability to get a lot of these
+side-effects by default. That is the purpose of this module. It does
+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 have access to
+  everything you need to write an exploit.
+* Calls :func:`pwnlib.term.init` to put your terminal in raw mode
+  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.
+
+:mod:`pwnlib` --- Normal python library
+---------------------------------------
+
+.. module:: pwnlib
+
+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
+not get access to :mod:`pwnlib.util.packing` simply by doing ``import
+pwnlib.util``.
+
+Though there are a few exceptions (such as :mod:`pwnlib.shellcraft`), that does
+not quite fit the goals of being simple and clean, but they can still be
+imported without implicit side-effects.

docs/source/adb.rst

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

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,6 +1,12 @@
 .. testsetup:: *
 
+   import tempfile
+   import subprocess
+   from pwnlib.context import context
    from pwnlib.asm import *
+   from pwnlib import shellcraft
+   from pwnlib.tubes.process import process
+
 
 :mod:`pwnlib.asm` --- Assembler functions
 =========================================

docs/source/atexception.rst

@@ -0,0 +1,5 @@
+:mod:`pwnlib.atexception` --- Callbacks on unhandled exception
+==============================================================
+
+.. automodule:: pwnlib.atexception
+   :members:

docs/source/atexit.rst

@@ -0,0 +1,5 @@
+:mod:`pwnlib.atexit` --- Replacement for atexit
+===============================================
+
+.. automodule:: pwnlib.atexit
+   :members:

docs/source/commandline.rst

@@ -0,0 +1,18 @@
+.. testsetup:: *
+
+   from pwn import *
+   old = context.defaults.copy()
+
+.. testcleanup:: *
+
+    context.defaults.copy = old
+
+Command Line Tools
+========================
+
+pwntools comes with a handful of useful command-line utilities which serve as wrappers for some of the internal functionality.
+
+.. toctree::
+
+.. autoprogram:: pwnlib.commandline.main:parser
+   :prog: pwn

docs/source/conf.py

@@ -11,13 +11,19 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys, os
+import os
+import subprocess
+import sys
+
+build_dash = tags.has('dash')
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath('../..'))
 
+import pwnlib
+
 # -- General configuration -----------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -31,22 +37,37 @@ extensions = [
     'sphinx.ext.doctest',
     'sphinx.ext.linkcode',
     'sphinx.ext.autosummary',
+    'sphinx.ext.coverage',
     'sphinx.ext.todo',
     'sphinx.ext.intersphinx',
+    'sphinxcontrib.autoprogram',
+    'sphinxcontrib.napoleon'
 ]
 
-try:
-    import sphinxcontrib.napoleon
-    extensions.append('sphinxcontrib.napoleon')
-except ImportError:
-    pass
-
 doctest_global_setup = '''
+import sys, os
+os.environ['PWNLIB_NOTERM'] = '1'
+os.environ['PWNLIB_RANDOMIZE'] = '0'
 import pwnlib
-pwnlib.context.reset_local()
+pwnlib.context.context.reset_local()
+pwnlib.context.ContextType.defaults['log_level'] = 'ERROR'
+pwnlib.context.ContextType.defaults['randomize'] = False
+pwnlib.term.text.when = 'never'
+pwnlib.log.install_default_handler()
+pwnlib.log.rootlogger.setLevel(1)
+
+# Sphinx modifies sys.stdout, and context.log_terminal has
+# a reference to the original instance.  We need to update
+# it for logging to be captured.
+class stdout(object):
+    def __getattr__(self, name):
+        return getattr(sys.stdout, name)
+    def __setattr__(self, name, value):
+        return setattr(sys.stdout, name, value)
+pwnlib.context.ContextType.defaults['log_console'] = stdout()
 '''
 
-autodoc_member_order = 'bysource'
+autodoc_member_order = 'alphabetical'
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -57,21 +78,20 @@ doctest_test_doctest_blocks = True
 source_suffix = '.rst'
 
 # The encoding of source files.
-#source_encoding = 'utf-8-sig'
+source_encoding = 'utf-8-sig'
 
 # The master toctree document.
 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 +181,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,10 +227,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': ('http://docs.python.org/2.7', None)}
+intersphinx_mapping = {'python': ('https://docs.python.org/2.7', None),
+                       'paramiko': ('https://paramiko-docs.readthedocs.org/en/1.15/', None)}
 
 # The name of an image file (relative to this directory) to place at the top of
 # the title page.
@@ -239,7 +260,7 @@ intersphinx_mapping = {'python': ('http://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.
@@ -253,7 +274,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'),
 ]
 
@@ -266,6 +287,19 @@ texinfo_documents = [
 # How to display URL addresses: 'footnote', 'no', or 'inline'.
 #texinfo_show_urls = 'footnote'
 
+branch = release
+
+try:
+    git_branch = subprocess.check_output('git describe --tags', shell = True)
+except subprocess.CalledProcessError:
+    git_branch = '-'
+
+try:
+    if '-' in git_branch:
+        branch = subprocess.check_output('git rev-parse HEAD', shell = True).strip()[:10]
+except subprocess.CalledProcessError:
+    pass
+
 def linkcode_resolve(domain, info):
     if domain != 'py':
         return None
@@ -290,21 +324,26 @@ def linkcode_resolve(domain, info):
     else:
         filename = info['module'].replace('.', '/') + '.py'
 
-        # Fixup for context properties
-        if info['module'].startswith('pwnlib.context'):
-            filename = 'pwnlib/context.py'
-
-            if not isinstance(val, (types.FunctionType, types.MethodType)):
-                import pwnlib.context.defaults
-                val = getattr(pwnlib.context.defaults.__class__, info['fullname'], None)
-                if isinstance(val, property):
-                    val = val.fget
-                    val = getattr(val, '_inner', val)
-
         if isinstance(val, (types.ModuleType, types.ClassType, types.MethodType, types.FunctionType, types.TracebackType, types.FrameType, types.CodeType)):
             try:
                 lines, first = inspect.getsourcelines(val)
                 filename += '#L%d-%d' % (first, first + len(lines) - 1)
             except IOError:
                 pass
-    return "https://github.com/Gallopsled/pwntools/blob/%s/%s" % (release, filename)
+
+    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

docs/source/constants.rst

@@ -1,6 +1,7 @@
 .. testsetup:: *
 
-   from pwnlib import context, constants
+   from pwnlib import constants
+   from pwnlib.context import context
 
 :mod:`pwnlib.constants` --- Easy access to header file constants
 ================================================================

docs/source/context.rst

@@ -1,49 +1,15 @@
 .. testsetup:: *
 
-   from pwnlib import context
-
+   from pwn import *
+   import logging
+   log = pwnlib.log.getLogger('pwnlib.context')
 
 :mod:`pwnlib.context` --- Setting runtime variables
 =====================================================
 
+.. autodata:: pwnlib.context.context
 
-:mod:`pwnlib.context`
----------------------
+.. autoclass:: pwnlib.context.ContextType
+    :members:
 
-.. automodule:: pwnlib.context
-
-   .. exec::
-      import pwnlib
-      from inspect import cleandoc
-      mod = pwnlib.context.defaults.__class__
-      for key in sorted(dir(mod)):
-          val = getattr(mod, key)
-          if isinstance(val, property):
-              print ".. data:: " + key
-              print ""
-              print cleandoc(val.__doc__)
-              print ""
-
-
-   .. autofunction:: pwnlib.context.__call__(**kwargs)
-   .. autofunction:: pwnlib.context.local(**kwargs)
-   .. autofunction:: pwnlib.context.reset_local()
-
-:mod:`pwnlib.context.defaults`
-------------------------------
-
-.. automodule:: pwnlib.context.defaults
-
-   .. exec::
-      import pwnlib
-      mod = pwnlib.context.defaults.__class__
-      for key in sorted(dir(mod)):
-          val = getattr(mod, key)
-          if isinstance(val, property):
-              print ".. data:: " + key
-              print ""
-              print "This is the global version of :data:`pwnlib.context.%s`." % key
-              print
-
-
-   .. autofunction:: pwnlib.context.defaults.__call__(**kwargs)
+.. autoclass:: pwnlib.context.Thread

docs/source/elf.rst

@@ -1,6 +1,7 @@
 .. testsetup:: *
 
    from pwnlib.elf import *
+   from pwnlib.util.misc import which
 
 :mod:`pwnlib.elf` --- Working with ELF binaries
 ===============================================

docs/source/encoders.rst

@@ -0,0 +1,25 @@
+.. testsetup:: *
+
+   from pwn import *
+
+:mod:`pwnlib.encoders` --- Encoding Shellcode
+===============================================
+
+.. automodule:: pwnlib.encoders
+   :members:
+
+.. automodule:: pwnlib.encoders.encoder
+   :members:
+
+
+.. automodule:: pwnlib.encoders.amd64
+   :members:
+
+.. automodule:: pwnlib.encoders.arm
+   :members:
+
+.. automodule:: pwnlib.encoders.i386
+   :members:
+
+.. automodule:: pwnlib.encoders.i386.xor
+   :members:

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/globals.rst

@@ -0,0 +1,102 @@
+.. testsetup:: *
+
+   from pwn import *
+
+``from pwn import *``
+========================
+
+The most common way that you'll see pwntools used is
+
+    >>> from pwn import *
+
+Which imports a bazillion things into the global namespace to make your life easier.
+
+This is a quick list of most of the objects and routines imported, in rough order of importance and frequency of use.
+
+- ``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``
+- ``remote``, ``listen``, ``ssh``, ``process``
+    - :mod:`pwnlib.tubes`
+    - Super convenient wrappers around all of the common functionality for CTF challenges
+    - Connect to anything, anywhere, and it works the way you want it to
+    - Helpers for common tasks like ``recvline``, ``recvuntil``, ``clean``, etc.
+    - Interact directly with the application via ``.interactive()``
+- ``p32`` and ``u32``
+    - :mod:`pwnlib.util.packing`
+    - Useful functions to make sure you never have to remember if ``'>'`` means signed or unsigned for ``struct.pack``, and no more ugly ``[0]`` index at the end.
+    - Set ``signed`` and ``endian`` in sane manners (also these can be set once on ``context`` and not bothered with again)
+    - Most common sizes are pre-defined (``u8``, ``u64``, etc), and :func:`pwnlib.util.packing.pack` lets you define your own.
+- ``log``
+    - :mod:`pwnlib.log`
+    - Make your output pretty!
+- ``cyclic`` and ``cyclic_func``
+    - :mod:`pwnlib.util.cyclic`
+    - Utilities for generating strings such that you can find the offset of any given substring given only N (usually 4) bytes.  This is super useful for straight buffer overflows.  Instead of looking at 0x41414141, you could know that 0x61616171 means you control EIP at offset 64 in your buffer.
+- ``asm`` and ``disasm``
+    - :mod:`pwnlib.asm`
+    - Quickly turn assembly into some bytes, or vice-versa, without mucking about
+    - Supports any architecture for which you have a binutils installed
+    - Over 20 different architectures have pre-built binaries at `ppa:pwntools/binutils <https://launchpad.net/~pwntools/+archive/ubuntu/binutils>`_.
+- ``shellcraft``
+    - :mod:`pwnlib.shellcraft`
+    - Library of shellcode ready to go
+    - ``asm(shellcraft.sh())`` gives you a shell
+    - Templating library for reusability of shellcode fragments
+- ``ELF``
+    - :mod:`pwnlib.elf`
+    - ELF binary manipulation tools, including symbol lookup, virtual memory to file offset helpers, and the ability to modify and save binaries back to disk
+- ``DynELF``
+    - :mod:`pwnlib.dynelf`
+    - Dynamically resolve functions given only a pointer to any loaded module, and a function which can leak data at any address
+- ``ROP``
+    - :mod:`pwnlib.rop`
+    - Automatically generate ROP chains using a DSL to describe what you want to do, rather than raw addresses
+- ``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
+- ``args``
+    - Dictionary contining 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
+        - `NOTERM`
+        - `SILENT`
+        - `DEBUG`
+- ``randoms``, ``rol``, ``ror``, ``xor``, ``bits``
+    - :mod:`pwnlib.util.fiddling`
+    - Useful utilities for generating random data from a given alphabet, or simplifying math operations that usually require masking off with `0xffffffff` or calling `ord` and `chr` an ugly number of times
+- ``net``
+    - :mod:`pwnlib.util.net`
+    - Routines for querying about network interfaces
+- ``proc``
+    - :mod:`pwnlib.util.proc`
+    - Routines for querying about processes
+- ``pause``
+    - It's the new ``getch``
+- ``safeeval``
+    - :mod:`pwnlib.util.safeeval`
+    - Functions for safely evalutaing python code without nasty side-effects.
+
+These are all pretty self explanatory, but are useful to have in the global namespace.
+
+- ``hexdump``
+- ``read`` and ``write``
+- ``enhex`` and ``unhex``
+- ``more``
+- ``group``
+- ``align`` and ``align_down``
+- ``urlencode`` and ``urldecode``
+- ``which``
+- ``wget``
+
+Additionally, all of the following modules are auto-imported for you.  You were going to do it anyway.
+
+- ``os``
+- ``sys``
+- ``time``
+- ``requests``
+- ``re``
+- ``random``

docs/source/index.rst

@@ -1,31 +1,88 @@
-Welcome to pwntools's documentation!
+pwntools
 ====================================
 
-Contents:
+``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.
+
+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
+---------------
 
 .. toctree::
    :maxdepth: 3
    :glob:
 
+   about
+   install
    intro
+   globals
+   commandline
+
+
+Module Index
+------------
+
+Each of the ``pwntools`` modules is documented here.
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   adb
+   args
    asm
+   atexception
+   atexit
    constants
    context
    dynelf
+   encoders
    elf
    exception
+   flag
+   fmtstr
    gdb
    log
    memleak
-   tubes
+   replacements
+   rop
+   rop/*
+   runner
    shellcraft
+   shellcraft/*
    term
+   timeout
+   tubes
+   tubes/*
    ui
+   update
+   useragents
    util/*
 
-Indices and tables
-==================
+.. toctree::
+   :hidden:
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   testexample
+
+.. only:: not dash
+
+   Indices and tables
+   ==================
+
+   * :ref:`genindex`
+   * :ref:`modindex`
+   * :ref:`search`

docs/source/install.rst

@@ -0,0 +1,41 @@
+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.).
+
+Prerequisites
+-------------
+
+In order to get the most out of ``pwntools``, you should have the
+following system libraries installed.
+
+.. toctree::
+   :maxdepth: 3
+   :glob:
+
+   install/*
+
+Released Version
+-----------------
+
+pwntools is available as a ``pip`` package.
+
+.. code-block:: bash
+
+    $ apt-get update
+    $ apt-get install python2.7 python-pip python-dev git libssl-dev libffi-dev
+    $ pip install --upgrade pwntools
+
+Development
+--------------
+
+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
+    $ pip install --upgrade --editable ./pwntools
+
+.. _Ubuntu: https://launchpad.net/~pwntools/+archive/ubuntu/binutils

docs/source/install/binutils.rst

@@ -0,0 +1,85 @@
+Binutils
+-------------
+
+Assembly of foreign architectures (e.g. assembling Sparc shellcode on
+Mac OS X) requires cross-compiled versions of ``binutils`` to be
+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
+^^^^^^^^^^^^^^^^
+
+For Ubuntu 12.04 through 15.10, you must first add the pwntools `Personal Package Archive repository <http://binutils.pwntools.com>`__.
+
+Ubuntu Xenial (16.04) has official packages for most architectures, and does not require this step.
+
+.. code-block:: bash
+
+    $ apt-get install software-properties-common
+    $ apt-add-repository ppa:pwntools/binutils
+    $ apt-get update
+
+Then, install the binutils for your architecture.
+
+.. code-block:: bash
+
+    $ apt-get install binutils-$ARCH-linux-gnu
+
+Mac OS X
+^^^^^^^^^^^^^^^^
+
+Mac OS X is just as easy, but requires building binutils from source.
+However, we've made ``homebrew`` recipes to make this a single command.
+After installing `brew <http://brew.sh>`__, grab the appropriate
+recipe from our `binutils
+repo <https://github.com/Gallopsled/pwntools-binutils/>`__.
+
+.. code-block:: bash
+
+    $ brew install https://raw.githubusercontent.com/Gallopsled/pwntools-binutils/master/osx/binutils-$ARCH.rb
+
+Alternate OSes
+^^^^^^^^^^^^^^^^
+
+If you want to build everything by hand, or don't use any of the above
+OSes, ``binutils`` is simple to build by hand.
+
+.. code-block:: bash
+
+    #!/usr/bin/env bash
+
+    V=2.25   # Binutils Version
+    ARCH=arm # Target architecture
+
+    cd /tmp
+    wget -nc https://ftp.gnu.org/gnu/binutils/binutils-$V.tar.gz
+    wget -nc https://ftp.gnu.org/gnu/binutils/binutils-$V.tar.gz.sig
+
+    gpg --keyserver keys.gnupg.net --recv-keys 4AE55E93
+    gpg --verify binutils-$V.tar.gz.sig
+
+    tar xf binutils-$V.tar.gz
+
+    mkdir binutils-build
+    cd binutils-build
+
+    export AR=ar
+    export AS=as
+
+    ../binutils-$V/configure \
+        --prefix=/usr/local \
+        --target=$ARCH-unknown-linux-gnu \
+        --disable-static \
+        --disable-multilib \
+        --disable-werror \
+        --disable-nls
+
+    MAKE=gmake
+    hash gmake || MAKE=make
+
+    $MAKE -j clean all
+    sudo $MAKE install
+

docs/source/install/headers.rst

@@ -0,0 +1,18 @@
+Python Development Headers
+-----------------------------
+
+Some of pwntools' Python dependencies require native extensions (for example, Paramiko requires PyCrypto).
+
+In order to build these native extensions, the development headers for Python must be installed.
+
+Ubuntu
+^^^^^^^^^^^^^^^^
+
+.. code-block:: bash
+
+    $ apt-get install python-dev
+
+Mac OS X
+^^^^^^^^^^^^^^^^
+
+No action needed.

docs/source/intro.rst

@@ -1,53 +1,221 @@
-Introduction to pwntools
+.. testsetup:: *
+
+   from pwn import *
+
+Getting Started
 ========================
 
-Historically pwntools was used as a sort of exploit-writing DSL. Simply doing
-``from pwn import *`` in a previous version of pwntools would bring all sorts of
-nice side-effects.
+To get your feet wet with pwntools, let's first go through a few examples.
 
-When redesigning pwntools for 2.0, we noticed two contrary goals:
+When writing exploits, pwntools generally follows the "kitchen sink" approach.
 
-* We would like to have a "normal" python module structure, to allow other
-  people to faster get familiar with how pwntools works.
-* We would like to have even more side-effects, especially by putting the
-  terminal in raw-mode.
+    >>> from pwn import *
 
-To make this possible, we decided to have two different modules. :mod:`pwnlib`
-would be our nice, clean python module, while :mod:`pwn` would be used during
-CTFs.
+This imports a lot of functionality into the global namespace.  You can now
+assemble, disassemble, pack, unpack, and many other things with a single function.
 
-:mod:`pwnlib` --- Normal python library
----------------------------------------
+A full list of everything that is imported is available on :doc:`globals`.
 
-.. module:: pwnlib
 
-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).
+Making Connections
+------------------
 
-For the most part, you will also only get the bits you import. You for instance
-not get access to :mod:`pwnlib.util.packing` simply by doing ``import
-pwnlib.util``.
+You need to talk to the challenge binary in order to pwn it, right?
+pwntools makes this stupid simple with its :mod:`pwnlib.tubes` module.
 
-Though there are a few exceptions (such as :mod:`pwnlib.shellcraft`), that does
-not quite fit the goals of being simple and clean, but they can still be
-imported without implicit side-effects.
+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`.
 
-:mod:`pwn` --- Toolbox optimized for CTFs
------------------------------------------
+    >>> conn = remote('ftp.debian.org',21)
+    >>> conn.recvline() # doctest: +ELLIPSIS
+    '220 ...'
+    >>> conn.send('USER anonymous\r\n')
+    >>> conn.recvuntil(' ', drop=True)
+    '331'
+    >>> conn.recvline()
+    'Please specify the password.\r\n'
+    >>> conn.close()
 
-.. module:: pwn
+It's also easy to spin up a listener
 
-As stated, we would also like to have the ability to get a lot of these
-side-effects by default. That is the purpose of this module. It does
-the following:
+    >>> l = listen()
+    >>> r = remote('localhost', l.lport)
+    >>> c = l.wait_for_connection()
+    >>> r.send('hello')
+    >>> c.recv()
+    'hello'
+
+Interacting with processes is easy thanks to :mod:`pwnlib.tubes.process`.
+
+::
+
+    >>> sh = process('/bin/sh')
+    >>> sh.sendline('sleep 3; echo hello world;')
+    >>> sh.recvline(timeout=1)
+    ''
+    >>> sh.recvline(timeout=5)
+    'hello world\n'
+    >>> sh.close()
+
+Not only can you interact with processes programmatically, but you can
+actually **interact** with processes.
+
+    >>> sh.interactive() # doctest: +SKIP
+    $ whoami
+    user
+
+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 with it like
+a ``process`` tube.
+
+::
+
+    >>> shell = ssh('bandit0', 'bandit.labs.overthewire.org', password='bandit0')
+    >>> shell['whoami']
+    'bandit0'
+    >>> shell.download_file('/etc/motd')
+    >>> sh = shell.run('sh')
+    >>> sh.sendline('sleep 3; echo hello world;') # doctest: +SKIP
+    >>> sh.recvline(timeout=1)
+    ''
+    >>> sh.recvline(timeout=5)
+    'hello world\n'
+    >>> shell.close()
+
+Packing Integers
+------------------
+
+A common task for exploit-writing is converting between integers as Python
+sees them, and their representation as a sequence of bytes.
+Usually folks resort to the built-in ``struct`` module.
+
+pwntools makes this easier with :mod:`pwnlib.util.packing`.  No more remembering
+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]
+    True
+
+The packing/unpacking operations are defined for many common bit-widths.
+
+    >>> u8('A') == 0x41
+    True
+
+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'
+    >>> asm('nop', arch='arm')
+    '\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.
+
+    >>> context.arch      = 'i386'
+    >>> context.os        = 'linux'
+    >>> context.endian    = 'little'
+    >>> context.word_size = 32
+
+Additionally, you can use a shorthand to set all of the values at once.
+
+    >>> asm('nop')
+    '\x90'
+    >>> context(arch='arm', os='linux', endian='big', word_size=32)
+    >>> asm('nop')
+    '\xe3 \xf0\x00'
+
+.. doctest::
+   :hide:
+
+    >>> context.clear()
+
+Setting Logging Verbosity
+-------------------------
+
+You can control the verbosity of the standard pwntools logging via ``context``.
+
+For example, setting
+
+    >>> context.log_level = 'debug'
+
+Will cause all of the data sent and received by a ``tube`` to be printed to the screen.
+
+.. doctest::
+   :hide:
+
+    >>> context.clear()
+
+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')
+    'b800000000'
+
+But if you do, it's easy to suss out!
+
+    >>> print disasm('6a0258cd80ebf9'.decode('hex'))
+       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
+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') # doctest: +ELLIPSIS
+    '6a3158cd80...'
+
+
+Misc Tools
+----------------------
+
+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' which is pack(0x62616166))  at crash time
+    >>> print cyclic_find('faab')
+    120
+
+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
+    0x400000
+    >>> print hex(e.symbols['write']) #doctest: +SKIP
+    0x401680
+    >>> print hex(e.got['write']) #doctest: +SKIP
+    0x60b070
+    >>> 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.asm(e.address, 'ret')
+    >>> e.save('/tmp/quiet-cat')
+    >>> disasm(file('/tmp/quiet-cat','rb').read(1))
+    '   0:   c3                      ret'
 
-* 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
-  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.
-* 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.

docs/source/log.rst

@@ -1,11 +1,21 @@
-:mod:`pwnlib.log` and   --- Logging stuff
-=================================================================
+:mod:`pwnlib.log` --- Logging stuff
+===================================
 
 .. automodule:: pwnlib.log
-   :members:
+   :members: getLogger, install_default_handler, rootlogger
 
-:mod:`pwnlib.log_levels` --- Possible log levels
-------------------------------------------------
-
-.. automodule:: pwnlib.log_levels
+.. autoclass:: pwnlib.log.Progress
    :members:
+   :member-order: bysource
+
+.. autoclass:: pwnlib.log.Logger
+   :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,3 +1,7 @@
+.. testsetup:: *
+
+   from pwnlib.memleak import *
+
 :mod:`pwnlib.memleak` --- Helper class for leaking memory
 =========================================================
 

docs/source/replacements.rst

@@ -0,0 +1,5 @@
+:mod:`pwnlib.replacements` --- Replacements for various functions
+=================================================================
+
+.. automodule:: pwnlib.replacements
+   :members:

docs/source/rop.rst

@@ -0,0 +1,14 @@
+.. testsetup:: *
+
+   from pwn import *
+
+:mod:`pwnlib.rop` --- Return Oriented Programming
+=================================================
+
+Submodules
+----------
+
+.. toctree::
+   :glob:
+
+   rop/*

docs/source/rop/rop.rst

@@ -0,0 +1,9 @@
+.. testsetup:: *
+
+   from pwn import *
+
+:mod:`pwnlib.rop.rop` --- Return Oriented Programming
+==========================================================
+
+.. automodule:: pwnlib.rop.rop
+   :members:

docs/source/rop/srop.rst

@@ -0,0 +1,9 @@
+.. testsetup:: *
+
+   from pwn import *
+
+:mod:`pwnlib.rop.srop` --- Sigreturn Oriented Programming
+==========================================================
+
+.. automodule:: pwnlib.rop.srop
+   :members:

docs/source/runner.rst

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

docs/source/shellcraft/amd64.rst

@@ -0,0 +1,19 @@
+.. testsetup:: *
+
+   from pwn import *
+   context.clear(arch='amd64')
+
+:mod:`pwnlib.shellcraft.amd64` --- Shellcode for AMD64
+===========================================================
+
+:mod:`pwnlib.shellcraft.amd64`
+---------------------------------------
+
+.. automodule:: pwnlib.shellcraft.amd64
+   :members:
+
+:mod:`pwnlib.shellcraft.amd64.linux`
+---------------------------------------
+
+.. automodule:: pwnlib.shellcraft.amd64.linux
+   :members:

docs/source/shellcraft/arm.rst

@@ -0,0 +1,19 @@
+.. testsetup:: *
+
+   from pwn import *
+   context.clear(arch='arm')
+
+:mod:`pwnlib.shellcraft.arm` --- Shellcode for ARM
+===========================================================
+
+:mod:`pwnlib.shellcraft.arm`
+-----------------------------
+
+.. automodule:: pwnlib.shellcraft.arm
+   :members:
+
+:mod:`pwnlib.shellcraft.arm.linux`
+-----------------------------------
+
+.. automodule:: pwnlib.shellcraft.arm.linux
+   :members:

docs/source/shellcraft/i386.rst

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

docs/source/shellcraft/mips.rst

@@ -0,0 +1,19 @@
+.. testsetup:: *
+
+   from pwn import *
+   context.clear(arch='mips')
+
+:mod:`pwnlib.shellcraft.mips` --- Shellcode for MIPS
+===========================================================
+
+:mod:`pwnlib.shellcraft.mips`
+-----------------------------
+
+.. automodule:: pwnlib.shellcraft.mips
+   :members:
+
+:mod:`pwnlib.shellcraft.mips.linux`
+-----------------------------------
+
+.. automodule:: pwnlib.shellcraft.mips.linux
+   :members:

docs/source/shellcraft/regsort.rst

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

docs/source/shellcraft/thumb.rst

@@ -0,0 +1,19 @@
+.. testsetup:: *
+
+   from pwn import *
+   context.clear(arch='thumb')
+
+:mod:`pwnlib.shellcraft.thumb` --- Shellcode for Thumb Mode
+===========================================================
+
+:mod:`pwnlib.shellcraft.thumb`
+-------------------------------
+
+.. automodule:: pwnlib.shellcraft.thumb
+   :members:
+
+:mod:`pwnlib.shellcraft.thumb.linux`
+---------------------------------------
+
+.. automodule:: pwnlib.shellcraft.thumb.linux
+   :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

@@ -0,0 +1,11 @@
+.. testsetup:: *
+
+   from pwnlib.context import context
+   from pwnlib.timeout import Timeout
+   import time
+
+:mod:`pwnlib.timeout` --- Timeout handling
+============================================
+
+.. automodule:: pwnlib.timeout
+   :members:

docs/source/tubes.rst

@@ -1,56 +1,30 @@
+.. testsetup:: *
+
+   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(host, port, fam = None, typ = None, proto = 0, timeout = 'default', log_level = INFO)
-         :members:
-         :show-inheritance:
+.. toctree::
+    :maxdepth: 3
+    :glob:
 
-   .. automodule:: pwnlib.tubes.listen
-
-      .. autoclass:: pwnlib.tubes.listen.listen(port, bindaddr = "0.0.0.0", fam = "any", typ = "tcp", timeout = 'default', log_level = INFO)
-         :members:
-         :show-inheritance:
-
-   .. automodule:: pwnlib.tubes.sock
-
-      .. autoclass:: pwnlib.tubes.sock.sock()
-         :show-inheritance:
-
-   Processes
-   ---------
-
-   .. automodule:: pwnlib.tubes.process
-
-      .. autoclass:: pwnlib.tubes.process.process(args, shell = False, executable = None, env = None, timeout = 'default', log_level = INFO)
-         :members: kill, poll, communicate
-         :show-inheritance:
-
-   SSH
-   ---
-
-   .. automodule:: pwnlib.tubes.ssh
-
-      .. autoclass:: pwnlib.tubes.ssh.ssh(user, host, port = 22, password = None, key = None, keyfile = None, proxy_command = None, proxy_sock = None, timeout = 'default', log_level = INFO)
-         :members:
-
-      .. autoclass:: pwnlib.tubes.ssh.ssh_channel()
-         :members: kill, poll, interactive
-         :show-inheritance:
+    tubes/*
 
 
-   Common functionality
-   --------------------
+:mod:`pwnlib.tubes.tube` --- Common Functionality
+-------------------------------------------------
 
-   .. automodule:: pwnlib.tubes.tube
 
-      .. autoclass:: pwnlib.tubes.tube.tube()
-         :members:
-         :exclude-members: recv_raw, send_raw, settimeout_raw,
-                           can_recv_raw
+.. automodule:: pwnlib.tubes.tube
+
+  .. autoclass:: pwnlib.tubes.tube.tube()
+     :members:
+     :exclude-members: recv_raw, send_raw, settimeout_raw,
+                       can_recv_raw

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,25 @@
+.. testsetup:: *
+
+   from pwn import *
+
+: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:

docs/source/tubes/ssh.rst

@@ -0,0 +1,21 @@
+.. testsetup:: *
+
+   from pwn import *
+
+:mod:`pwnlib.tubes.ssh` --- SSH
+===========================================================
+
+.. automodule:: pwnlib.tubes.ssh
+
+   .. autoclass:: pwnlib.tubes.ssh.ssh
+      :members:
+
+   .. autoclass:: pwnlib.tubes.ssh.ssh_channel()
+      :members: kill, poll, interactive
+      :show-inheritance:
+
+   .. autoclass:: pwnlib.tubes.ssh.ssh_connecter()
+      :show-inheritance:
+
+   .. autoclass:: pwnlib.tubes.ssh.ssh_listener()
+      :show-inheritance:

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/useragents.rst

@@ -0,0 +1,9 @@
+.. testsetup:: *
+
+   from pwnlib.useragents import *
+
+:mod:`pwnlib.useragents` --- A database of useragent strings
+============================================================
+
+.. automodule:: pwnlib.useragents
+   :members:

docs/source/util/hashes.rst

@@ -0,0 +1,5 @@
+:mod:`pwnlib.util.hashes` --- Hashing functions
+===============================================
+
+.. automodule:: pwnlib.util.hashes
+   :members:

docs/source/util/iters.rst

@@ -0,0 +1,113 @@
+.. testsetup:: *
+
+   import string, operator
+   from pwnlib.util.iters import *
+
+
+:mod:`pwnlib.util.iters` --- Extension of standard module :mod:`itertools`
+==========================================================================
+
+.. automodule:: pwnlib.util.iters
+   :members:
+   :exclude-members:
+     chain                                  ,
+     combinations                           ,
+     combinations_with_replacement          ,
+     compress                               ,
+     count                                  ,
+     cycle                                  ,
+     dropwhile                              ,
+     groupby                                ,
+     ifilter                                ,
+     ifilterfalse                           ,
+     imap                                   ,
+     islice                                 ,
+     izip                                   ,
+     izip_longest                           ,
+     permutations                           ,
+     product                                ,
+     repeat                                 ,
+     starmap                                ,
+     takewhile                              ,
+     tee
+
+.. function:: chain
+
+   Alias for :func:`itertools.chain`.
+
+.. function:: combinations
+
+   Alias for :func:`itertools.combinations`
+
+.. function:: combinations_with_replacement
+
+   Alias for :func:`itertools.combinations_with_replacement`
+
+.. function:: compress
+
+   Alias for :func:`itertools.compress`
+
+.. function:: count
+
+   Alias for :func:`itertools.count`
+
+.. function:: cycle
+
+   Alias for :func:`itertools.cycle`
+
+.. function:: dropwhile
+
+   Alias for :func:`itertools.dropwhile`
+
+.. function:: groupby
+
+   Alias for :func:`itertools.groupby`
+
+.. function:: ifilter
+
+   Alias for :func:`itertools.ifilter`
+
+.. function:: ifilterfalse
+
+   Alias for :func:`itertools.ifilterfalse`
+
+.. function:: imap
+
+   Alias for :func:`itertools.imap`
+
+.. function:: islice
+
+   Alias for :func:`itertools.islice`
+
+.. function:: izip
+
+   Alias for :func:`itertools.izip`
+
+.. function:: izip_longest
+
+   Alias for :func:`itertools.izip_longest`
+
+.. function:: permutations
+
+   Alias for :func:`itertools.permutations`
+
+.. function:: product
+
+   Alias for :func:`itertools.product`
+
+.. function:: repeat
+
+   Alias for :func:`itertools.repeat`
+
+.. function:: starmap
+
+   Alias for :func:`itertools.starmap`
+
+.. function:: takewhile
+
+   Alias for :func:`itertools.takewhile`
+
+.. function:: tee
+
+   Alias for :func:`itertools.tee`
+

docs/source/util/misc.rst

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

docs/source/util/proc.rst

@@ -1,6 +1,7 @@
 .. testsetup:: *
 
    from pwnlib.util.proc import *
+   import os, sys
 
 
 :mod:`pwnlib.util.proc` --- Working with ``/proc/``

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

@@ -0,0 +1,10 @@
+.. testsetup:: *
+
+   from pwnlib.context import context
+   from pwnlib.util.web import *
+
+:mod:`pwnlib.util.web` --- Utilities for working with the WWW
+=============================================================
+
+.. automodule:: pwnlib.util.web
+   :members:

examples/README

@@ -1,6 +0,0 @@
-While these examples should all work, they are not very representative of
-the pwntools project.
-
-We have a plan to create a separate repository with examples, primarily
-exploits. Until we do so, we recommend new users to look at
-http://pwntools.readthedocs.org, as this is a better overview of our features.

examples/README.md

@@ -0,0 +1,109 @@
+# Examples
+While these examples should all work, they are not very representative of
+the pwntools project.
+
+We have a plan to create a separate repository with examples, primarily
+exploits. Until we do so, we recommend new users to look at
+https://docs.pwntools.com, as this is a better overview of our features.
+
+In no particular order the docstrings for each example:
+
+* `args.py`
+```
+When not in lib-mode (import `pwn` rather than `pwnlib`) we parse the
+commandline for variables definitions.  A variable definition has the form::
+
+  <var>=<val>
+
+where ``<var>`` contains only uppercase letters, digits and underscores and
+doesn't start with a digit.
+
+Try running this example with::
+
+  $ python args.py RHOST=localhost RPORT=1337
+```
+* `asm.py`
+```
+Example showing the interface to `pwnlib.asm.asm` and `pwnlib.shellcraft`.
+```
+* `clean_and_log.py`
+```
+Use case for `pwnlib.tubes.tube.clean_and_log`.
+
+Sometimes you will have a solution to a challenge but you don't know what it
+will look like when you get the flag.  Sometimes that will leave you with a
+top-level exception, no flag, and angry team members.
+
+Solution:
+ 1. Always run wireshark or tcpdump.  Always.
+ 2. Register <your socket>.clean or <your socket>.clean_and_log to run at exit.
+```
+* `indented.py`
+```
+When running in term-mode (import `pwn` rather than `pwnlib`, stdout is a TTY
+and not running in a REPL), we can do proper indentation where lines too long to
+fit on a screen are split into multiple individually indented lines.
+
+Too see the difference try running with::
+
+  $ python indented.py
+
+and
+
+  $ python -i indented.py
+
+Also notice that `pause()` can react on any key when in `term_mode`.
+```
+* `listen_uroboros.py`
+```
+An example showing interconnection of sockets.  This script will wait for three
+connections on port 1337, then connect them like a three-way Uroboros.
+```
+* `options.py`
+```
+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.
+```
+* `readline_completers.py`
+```
+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_gdb_debugging.py`
+```
+Simple example showing how to use the remote
+gdb debugging features available in pwntools.
+```
+* `spinners.py`
+```
+Just a lot of spinners!
+```
+* `splash.py`
+```
+"Easteregg"
+```
+* `ssh.py`
+```
+Example showing how to use the ssh class.
+```
+* `text.py`
+```
+Example showing how to use `pwnlib.term.text`.
+
+Try running with::
+
+  $ TERM=xterm python text.py
+
+and::
+
+  $ TERM=xterm-256color python text.py
+```
+* `remote.py`
+```
+Example showing how to use the remote class.
+```

examples/android.py

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

examples/args.py

@@ -0,0 +1,18 @@
+"""
+When not in lib-mode (import `pwn` rather than `pwnlib`) we parse the
+commandline for variables definitions.  A variable definition has the form::
+
+  <var>=<val>
+
+where ``<var>`` contains only uppercase letters, digits and underscores and
+doesn't start with a digit.
+
+Try running this example with::
+
+  $ python args.py RHOST=localhost RPORT=1337
+"""
+
+from pwn import *
+
+print args['RHOST'] or 'RHOST is not set'
+print args['RPORT'] or 'RPORT is not set'

examples/argstest.py

@@ -1,4 +0,0 @@
-import pwn
-
-print pwn.args['RHOST'],
-print pwn.args['RPORT']

examples/asm.py

@@ -1,5 +1,10 @@
+"""
+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)

examples/attach.py

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

examples/clean_and_log.py

@@ -0,0 +1,28 @@
+"""
+Use case for `pwnlib.tubes.tube.clean_and_log`.
+
+Sometimes you will have a solution to a challenge but you don't know what it
+will look like when you get the flag.  Sometimes that will leave you with a
+top-level exception, no flag, and angry team members.
+
+Solution:
+ 1. Always run wireshark or tcpdump.  Always.
+ 2. Register <your socket>.clean or <your socket>.clean_and_log to run at exit.
+"""
+
+from pwn import *
+
+os.system('''((
+echo prefix sometext ;
+echo prefix someothertext ;
+echo here comes the flag ;
+echo LostInTheInterTubes
+) | nc -l 1337) &
+''')
+
+r = remote('localhost', 1337)
+atexit.register(r.clean_and_log)
+
+while True:
+    line = r.recvline()
+    print re.findall('^prefix (\S+)$', line)[0]

examples/completertest.py

@@ -1,15 +0,0 @@
-import pwn
-import pwnlib.term.completer
-
-c1 = pwn.term.completer.LongestPrefixCompleter([
-    'foobar',
-    'foobaz',
-    'fooquux',
-    ])
-
-c2 = pwn.term.completer.PathCompleter(mask = '*.py')
-
-with c1:
-    while True:
-        s = pwn.term.readline.readline(prompt = '> ')
-        print 'You wrote', s

examples/contexttest.py

@@ -1,6 +0,0 @@
-import pwn
-
-print pwn.context
-
-pwn.context.arch = 'i386'
-pwn.context.arch = 'yolo'

examples/gen-README.py

@@ -0,0 +1,42 @@
+"""
+Script to generate README.md
+"""
+
+from pwn import *
+
+
+out = '''# Examples
+While these examples should all work, they are not very representative of
+the pwntools project.
+
+We have a plan to create a separate repository with examples, primarily
+exploits. Until we do so, we recommend new users to look at
+https://docs.pwntools.com, as this is a better overview of our features.
+
+In no particular order the docstrings for each example:
+
+'''
+
+def append_example(_arg, top, names):
+    global out
+    for name in names:
+        if not (name.endswith('.py') and name != __file__):
+            continue
+        path = os.path.join(top, name)[2:] # strip './'
+        log.info('-> %s' % path)
+        data = read(path).strip()
+        if data[0:3] not in ('"""', "'''"):
+            log.warning('  Has no docstring!')
+            continue
+        try:
+            i = data.index(data[0:3], 3)
+        except ValueError:
+            log.warning('  Docstring is weird')
+            continue
+        doc = util.safeeval.const(data[0:i + 3])
+        out += '* `%s`\n' % path
+        out += '```%s```\n' % doc
+
+os.path.walk('.', append_example, None)
+
+write('README.md', out)

examples/indented.py

@@ -0,0 +1,25 @@
+"""
+When running in term-mode (import `pwn` rather than `pwnlib`, stdout is a TTY
+and not running in a REPL), we can do proper indentation where lines too long to
+fit on a screen are split into multiple individually indented lines.
+
+Too see the difference try running with::
+
+  $ python indented.py
+
+and
+
+  $ python -i indented.py
+
+Also notice that `pause()` can react on any key when in `term_mode`.
+"""
+
+from pwn import *
+
+context.log_level = 'info'
+
+log.indented('A' * 100)
+log.indented('B' * 100)
+log.indented('C' * 100)
+
+pause()

examples/indenttest.py

@@ -1,8 +0,0 @@
-import pwn
-
-pwn.context.log_level = 'info'
-
-# print pwn2.lib
-pwn.log.info(('A' * 100 + '\n') * 4)
-
-raw_input('>')

examples/inputtest.py

@@ -1,48 +0,0 @@
-# raise Exception('1234')
-
-# import sys
-# _write = sys.stdout.write
-# class Proxy:
-#     def __init__(self, fd):
-#         self._fd = fd
-#     def readline(self):
-#         _write('Input plox: ')
-#         return self._fd.readline()
-#     def read(self, n):
-#         _write('xxx')
-#         return self._fd.read(n)
-#     def __getattr__(self, k):
-#         # _write('[%s]\n' % k)
-#         return self._fd.__getattribute__(k)
-
-# # sys.stdout = Proxy(sys.stdout)
-# sys.stdin = Proxy(sys.stdin)
-
-# print raw_input()
-
-
-import pwn
-import pwnlib.term.readline
-
-h = pwn.term.output('yolo\n')
-i = 0
-def foo(_):
-    global i
-    i += 1
-    pwn.term.output('foooooo%d\n' % i, frozen = True, before = h)
-
-def bar():
-    print
-
-def baz(_):
-    import sys
-    sys.exit()
-
-pwnlib.term.readline.startup_hook = bar
-pwnlib.term.readline.keymap.register({
-    'C-x C-a': foo,
-    'C-x C-s': baz,
-    })
-
-while True:
-    print raw_input('> ')

examples/iotest.py

@@ -1,70 +0,0 @@
-import termios, tty, sys, string, time
-
-def get_term_size():
-    fd = os.open(os.ctermid(), os.O_RDONLY)
-    height, width = struct.unpack('hh', fcntl.ioctl(fd, termios.TIOCGWINSZ, '1234'))
-    os.close(fd)
-    return width, height
-
-def get_cursor_pos():
-    sys.stdout.write("\033[6n")
-    s = ''
-    while True:
-        c = sys.stdin.read(1)
-        if c == 'R':
-            break
-        s += c
-    col, row = map(int, s[2:].split(';'))
-    return col, row
-
-fd = sys.stdin.fileno()
-old_settings = termios.tcgetattr(fd)
-tty.setraw(sys.stdin.fileno())
-
-while True:
-    # print 'At (%d, %d)' % get_cursor_pos()
-    c = sys.stdin.read(1)
-    if c == 'q':
-        break
-    if c == '\r':
-        print
-    if c == 'w':
-        s = '\x01\x1b[s\x1b[50Ayolo\x1b[u\x02'
-        sys.stdout.write(s)
-    if c == 'e':
-        sys.stdout.write('\x1b[s')
-        for i in range(100):
-            sys.stdout.write('\x1b[0;15f%s' % '/-\\|'[i % 4])
-            sys.stdout.flush()
-            time.sleep(0.1)
-        sys.stdout.write('\x1b[u')
-    if c == 'E':
-        sys.stdout.write('\x1b[s')
-        for i in range(100):
-            sys.stdout.write('\x1b[0;15H%s' % '.oO*'[i % 4])
-            sys.stdout.flush()
-            time.sleep(0.1)
-        sys.stdout.write('\x1b[u')
-    if c == 'r':
-        sys.stdout.write('\x1b[S')
-    if c == 't':
-        sys.stdout.write('\x1b[T')
-    if c == 'y':
-        sys.stdout.write('\x1b[syolo\r\n\x1b[ufoo')
-    if c == 'u':
-        x = ord('a')
-        for i in range(10):
-            sys.stdout.write('\x1b[A' + chr(x))
-            sys.stdout.flush()
-            time.sleep(0.3)
-            x += 1
-            sys.stdout.write('\x1b[B' + chr(x))
-            sys.stdout.flush()
-            time.sleep(0.3)
-            x += 1
-    if c in string.printable:
-        sys.stdout.write(c)
-    else:
-        sys.stdout.write('\\x%02x' % ord(c))
-
-termios.tcsetattr(fd, termios.TCSADRAIN, old_settings)

examples/keymaptest.py

@@ -1,27 +0,0 @@
-import pwn
-
-def match(t):
-    print 'match', t
-
-def nomatch(t):
-    print 'nomatch', t
-
-def key(t):
-    print 'key', t
-
-def tab(t):
-    print 'tab', t
-
-def tabtab(t):
-    print 'tabtab', t
-
-import pwnlib.term.keymap
-km = pwnlib.term.keymap.Keymap({
-    '<match>'     : match,
-    '<nomatch>'   : nomatch,
-    '<any>'       : key,
-    '<tab>'       : tab,
-    '<tab> <tab>' : tabtab,
-    })
-
-km.handle_input()

examples/listen_uroboros.py

@@ -0,0 +1,14 @@
+"""
+An example showing interconnection of sockets.  This script will wait for three
+connections on port 1337, then connect them like a three-way Uroboros.
+"""
+
+from pwn import *
+
+cs = [listen(1337).wait_for_connection() for _ in range(3)]
+
+cs[0] << cs[1] << cs[2] << cs[0]
+
+cs[0].wait_for_close()
+cs[1].wait_for_close()
+cs[2].wait_for_close()

examples/logtest.py

@@ -1,55 +0,0 @@
-# import pwn2.lib as lib
-import pwn
-import time
-
-pwn.context.log_level = 0
-
-n = 0
-
-h = pwn.log.waitfor('spinners running', status = '0')
-
-hs = []
-while True:
-    s = raw_input('> ')
-    if s == 'q':
-        break
-    hs.append(pwn.log.waitfor(s, status = 'running'))
-    n += 1
-    h.status(str(n))
-
-h.success()
-
-for h in hs:
-    h.failure()
-
-# pwn.log.waitfor('waiting for stuff')
-# time.sleep(0.5)
-# pwn.log.info('something happened')
-# time.sleep(0.5)
-# pwn.log.success('something went well')
-# time.sleep(0.5)
-# pwn.log.waitfor('waiting for some minor stuff')
-# time.sleep(0.5)
-# pwn.log.failure('went wrong')
-# raw_input('please hit <enter> ')
-# time.sleep(0.5)
-# pwn.log.done_failure()
-# time.sleep(0.5)
-# pwn.log.info('all in all it went ok')
-# time.sleep(0.5)
-# pwn.log.done_success()
-
-
-# def foo():
-#     plib.log.stub()
-
-# foo()
-
-# try:
-#     try:
-#         raise KeyError
-#     except:
-#         plib.log.die('no reason')
-# except Exception as e:
-#     print `e`
-#     # raise

examples/memleaktest.py

@@ -1,12 +0,0 @@
-from pwn import *
-
-context(endianness='little', sign='unsigned')
-
-def legit_leak(addr):
-    return p32(addr)
-
-mem = MemLeak(legit_leak)
-print mem.b(0x08040001) # prints 1
-mem.setd(0x08040000, 0xaabbccdd)
-print hex(mem.b(0x08040001))   # prints 0xcc
-print mem.raw(0x08040000, 20)  # prints stuff

examples/options.py

@@ -0,0 +1,8 @@
+"""
+Example showing `pwnlib.ui.options()`
+"""
+
+from pwn import *
+
+opts = [string.letters[x] for x in range(10)]
+print 'You choose "%s"' % opts[options('Pick one:', opts)]

examples/port_forward.py

@@ -0,0 +1,11 @@
+"""
+A very simple port forwarder using `pwnlib.tubes.tube.connect_both()`.  Notice
+that `<>` is just a shorthand.
+"""
+
+from pwn import *
+
+while True:
+    listen(1337).wait_for_connection() <> remote('google.com', 80)
+
+# now point your browser (or curl(1)) to http://localhost:1337

examples/ptytest.py

@@ -1,37 +0,0 @@
-import pty, os, select, sys, time, pwn
-
-pid, fd = pty.fork()
-
-if pid == 0:
-    argv = ('/usr/bin/vim',)
-    argv = ('/bin/bash',)
-    os.execlp(argv[0], *argv)
-else:
-    # time.sleep(1)
-    # sys.stdout.write(os.read(fd, 4096))
-    while True:
-        rfds, wfds, xfds = select.select([fd, 0], [], [])
-        if fd in rfds:
-            s = os.read(fd, 4096)
-            if not s:
-                raise EOFError
-            sys.stdout.write(s)
-            sys.stdout.flush()
-        if 0 in rfds:
-            s = os.read(0, 4096)
-            if not s:
-                raise EOFError
-            os.write(fd, s)
-
-
-# def master_read(fd):
-#     import os
-#     s = os.read(fd, 4096)
-#     return s
-
-# def stdin_read(fd):
-#     import os
-#     s = os.read(fd, 4096)
-#     return s
-
-# pty.spawn('/bin/sh', master_read = master_read, stdin_read = stdin_read)

examples/readline_completers.py

@@ -0,0 +1,31 @@
+"""
+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.
+"""
+
+from pwn import *
+from pwnlib.term.completer import LongestPrefixCompleter
+from pwnlib.term.completer import PathCompleter
+
+c1 = LongestPrefixCompleter([
+    'foobar',
+    'foobaz',
+    'fooqux',
+    'exit',
+    'enough!',
+    ])
+
+c2 = PathCompleter(mask = '*.py')
+
+with c1:
+    print 'type "exit" to exit'
+    while True:
+        s = term.readline.readline(prompt = '> ').strip()
+        if s in ('exit', 'enough!'):
+            break
+        print 'You wrote', s
+with c2:
+    print 'choose a file'
+    s = term.readline.readline(prompt = text.bold_green('$ ')).strip()
+    print 'You picked', s

examples/readlineexc.py

@@ -1,15 +0,0 @@
-
-# import sys
-# class Wrapper:
-#     def __init__(self, fd):
-#         self._fd = fd
-#     def readline(self, size = None):
-#         return ''
-#     def __getattr__(self, k):
-#         return self._fd.__getattribute__(k)
-# sys.stdin = Wrapper(sys.stdin)
-# print `raw_input()`
-
-import readline
-import pwn
-raw_input('> ')

examples/remote.py

@@ -0,0 +1,11 @@
+"""
+Example showing how to use the remote class.
+"""
+
+from pwn import *
+
+sock = remote('127.0.0.1', 9001)
+
+print sock.recvline()
+sock.send('foo')
+sock.interactive()

examples/remote_gdb_debugging.py

@@ -0,0 +1,17 @@
+"""
+Simple example showing how to use the remote
+gdb debugging features available in pwntools.
+"""
+
+import getpass
+
+from pwn import *
+
+s = ssh(getpass.getuser(), '127.0.0.1', port = 22, keyfile = "~/.ssh/id_rsa")
+c = gdb.ssh_gdb(s, '/bin/sh', execute = '''
+p/x $pc
+c''')
+
+c.sendline('ls -la')
+c.sendline('exit')
+print c.recvall()