Update certinstall.rst

Added LDAP Auth

.appveyor.yml

@@ -0,0 +1,77 @@
+version: '{build}'
+build: off  # Not a C# project
+
+environment:
+  CI_DEPS: codecov>=2.0.5
+  CI_COMMANDS: codecov
+  matrix:
+    - PYTHON: "C:\\Python35"
+      TOXENV: "py35"
+    # TODO: ENABLE WHEN AVAILABLE
+    # - PYTHON: "C:\\Python36"
+    #   TOXENV: "py36"
+
+  SNAPSHOT_HOST:
+    secure: NeTo57s2rJhCd/mjKHetXVxCFd3uhr8txnjnAXD1tUI=
+  SNAPSHOT_PORT:
+    secure: TiJPtg60/edYTH8RnoBErg==
+  SNAPSHOT_USER:
+    secure: 6yBwmO5gv4vAwoFYII8qjQ==
+  SNAPSHOT_PASS:
+    secure: LPjrtFrWxYhOVGXzfPRV1GjtZE/wHoKq9m/PI6hSalfysUK5p2DxTG9uHlb4Q9qV
+  RTOOL_KEY:
+    secure: 0a+UUNbA+JjquyAbda4fd0JmiwL06AdG6torRPdCvbPDbKHnaW/BHHp1nRPytOKM
+
+install:
+  - "SET PATH=%PYTHON%;%PYTHON%\\Scripts;%PATH%"
+  - "python -m pip install --disable-pip-version-check -U pip"
+  - "pip install -U tox"
+
+test_script:
+  - ps: "tox -- --verbose --cov-report=term"
+  - ps: |
+      $Env:VERSION = $(python mitmproxy/version.py)
+      $Env:SKIP_MITMPROXY = "python -c `"print('skip mitmproxy')`""
+      tox -e wheel
+      tox -e rtool -- bdist
+
+  - ps: |
+      if(
+        ($Env:TOXENV -match "py35") -and !$Env:APPVEYOR_PULL_REQUEST_NUMBER -and
+        (($Env:APPVEYOR_REPO_BRANCH -In ("master", "pyinstaller")) -or ($Env:APPVEYOR_REPO_TAG -match "true"))
+      ) {
+        tox -e rtool -- decrypt release\installbuilder\license.xml.enc release\installbuilder\license.xml
+        if (!(Test-Path "C:\projects\mitmproxy\release\installbuilder-installer.exe")) {
+          "Download InstallBuilder..."
+          (New-Object System.Net.WebClient).DownloadFile(
+            "https://installbuilder.bitrock.com/installbuilder-enterprise-17.1.0-windows-installer.exe",
+            "C:\projects\mitmproxy\release\installbuilder-installer.exe"
+          )
+        }
+        Start-Process "C:\projects\mitmproxy\release\installbuilder-installer.exe" "--mode unattended --unattendedmodeui none" -Wait
+        & 'C:\Program Files (x86)\BitRock InstallBuilder Enterprise 17.1.0\bin\builder-cli.exe' `
+          build `
+          .\release\installbuilder\mitmproxy.xml `
+          windows `
+          --license .\release\installbuilder\license.xml `
+          --setvars project.version=$Env:VERSION `
+          --verbose
+      }
+
+deploy_script:
+  # we build binaries on every run, but we only upload them for master snapshots or tags.
+  ps: |
+    if(
+      ($Env:TOXENV -match "py35") -and
+      (($Env:APPVEYOR_REPO_BRANCH -In ("master", "pyinstaller")) -or ($Env:APPVEYOR_REPO_TAG -match "true"))
+    ) {
+      tox -e rtool -- upload-snapshot --bdist --wheel --installer
+    }
+
+cache:
+  - C:\projects\mitmproxy\release\installbuilder-installer.exe -> .appveyor.yml
+  - C:\Users\appveyor\AppData\Local\pip\cache
+
+notifications:
+  - provider: Slack
+    incoming_webhook: https://hooks.slack.com/services/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

.codecov.yml

@@ -0,0 +1 @@
+comment: off

.coveragerc

@@ -1,2 +0,0 @@
-[report]
-include = *netlib*

.gitattributes

@@ -0,0 +1,2 @@
+mitmproxy/tools/web/static/**/* -diff linguist-vendored
+web/src/js/filt/filt.js -diff

.gitignore

@@ -1,9 +1,25 @@
+.DS_Store
 MANIFEST
-/build
-/dist
-/tmp
-/doc
+**/tmp
+/venv*
 *.py[cdo]
 *.swp
 *.swo
-.coverage
+*.egg-info/
+.coverage*
+.idea
+.cache/
+.tox*/
+build/
+mitmproxy/contrib/kaitaistruct/*.ksy
+
+# UI
+
+node_modules
+bower_components
+*.map
+sslkeylogfile.log
+.tox/
+.python-version
+coverage.xml
+web/coverage/

.landscape.yml

@@ -0,0 +1,20 @@
+ignore-paths:
+  - docs
+  - examples
+  - mitmproxy/contrib
+  - web
+max-line-length: 140
+pylint:
+  options:
+    dummy-variables-rgx: _$|.+_$|dummy_.+
+  disable:
+    - missing-docstring
+    - protected-access
+    - too-few-public-methods
+    - too-many-arguments
+    - too-many-instance-attributes
+    - too-many-locals
+    - too-many-public-methods
+    - too-many-return-statements
+    - too-many-statements
+    - unpacking-non-sequence

.travis.yml

@@ -0,0 +1,107 @@
+sudo: false
+language: python
+
+env:
+  global:
+    - CI_DEPS=codecov>=2.0.5
+    - CI_COMMANDS=codecov
+git:
+  depth: 10000
+
+matrix:
+  fast_finish: true
+  include:
+    - python: 3.5
+      env: TOXENV=lint
+    - os: osx
+      osx_image: xcode7.3
+      language: generic
+      env: TOXENV=py35 BDIST=1
+    - python: 3.5
+      env: TOXENV=py35 OPENSSL_OLD
+      addons:
+        apt:
+          packages:
+            - libssl-dev
+    - python: 3.5
+      env: TOXENV=py35 BDIST=1 OPENSSL_ALPN
+      addons:
+        apt:
+          sources:
+            # Debian sid currently holds OpenSSL 1.1.0
+            # change this with future releases!
+            - debian-sid
+          packages:
+            - libssl-dev
+    - python: 3.6
+      env: TOXENV=py36 OPENSSL_ALPN
+      addons:
+        apt:
+          sources:
+            # Debian sid currently holds OpenSSL 1.1.0
+            # change this with future releases!
+            - debian-sid
+          packages:
+            - libssl-dev
+    - python: 3.5
+      env: TOXENV=individual_coverage
+    - python: 3.5
+      env: TOXENV=docs
+    - language: node_js
+      node_js: "node"
+      before_install:
+          - curl -o- -L https://yarnpkg.com/install.sh | bash
+          - export PATH=$HOME/.yarn/bin:$PATH
+      install:
+          - cd web && yarn
+          - yarn global add codecov
+      script: npm test && codecov
+      cache:
+          yarn: true
+          directories:
+              - web/node_modules
+
+install:
+  - |
+    if [[ $TRAVIS_OS_NAME == "osx" ]]
+    then
+      brew update || brew update
+      brew outdated pyenv || brew upgrade pyenv
+      eval "$(pyenv init -)"
+      env PYTHON_CONFIGURE_OPTS="--enable-framework" pyenv install --skip-existing 3.5.2
+      pyenv global 3.5.2
+      pyenv shell 3.5.2
+      pip install -U pip setuptools wheel virtualenv
+    fi
+  - pip install tox
+
+script:
+  - tox -- --verbose --cov-report=term
+  - |
+    if [[ $BDIST == "1" ]]
+    then
+        git fetch --unshallow --tags
+        tox -e rtool -- bdist
+    fi
+
+after_success:
+  # we build binaries on every run, but we only upload them for master snapshots or tags.
+  - |
+    if [[ $BDIST == "1" && $TRAVIS_PULL_REQUEST == "false" && ($TRAVIS_BRANCH == "pyinstaller" || $TRAVIS_BRANCH == "master" || -n $TRAVIS_TAG) ]]
+    then
+        tox -e rtool -- upload-snapshot --bdist
+    fi
+
+notifications:
+  slack:
+      -rooms:
+          mitmproxy:YaDGC9Gt9TEM7o8zkC2OLNsu
+      on_success: change
+      on_failure: change
+      on_start: never
+
+cache:
+  directories:
+    - $HOME/.pyenv
+    - $HOME/.cache/pip
+    # - $HOME/build/mitmproxy/mitmproxy/.tox

CHANGELOG

@@ -0,0 +1,714 @@
+28 April 2017: mitmproxy 2.0.2
+
+    * Fix mitmweb's Content-Security-Policy to work with Chrome 58+
+
+    * HTTP/2: actually use header normalization from hyper-h2
+
+
+15 March 2017: mitmproxy 2.0.1
+
+    * bump cryptography dependency
+
+    * bump pyparsing dependency
+
+    * HTTP/2: use header normalization from hyper-h2
+
+
+21 February 2017: mitmproxy 2.0
+
+    * HTTP/2 is now enabled by default.
+
+    * Image ContentView: Parse images with Kaitai Struct (kaitai.io) instead of Pillow. 
+      This simplifies installation, reduces binary size, and allows parsing in pure Python.
+
+    * Web: Add missing flow filters.
+
+    * Add transparent proxy support for OpenBSD.
+
+    * Check the mitmproxy CA for expiration and warn the user to regenerate it if necessary.
+
+    * Testing: Tremendous improvements, enforced 100% coverage for large parts of the 
+      codebase, increased overall coverage.
+
+    * Enforce individual coverage: one source file -> one test file with 100% coverage.
+
+    * A myriad of other small improvements throughout the project.
+
+    * Numerous bugfixes.
+
+
+26 December 2016: mitmproxy 1.0
+
+    * All mitmproxy tools are now Python 3 only! We plan to support Python 3.5 and higher.
+
+    * Web-Based User Interface: Mitmproxy now offically has a web-based user interface
+      called mitmweb. We consider it stable for all features currently exposed 
+      in the UI, but it still misses a lot of mitmproxy’s options.
+      
+    * Windows Compatibility: With mitmweb, mitmproxy is now useable on Windows. 
+      We are also introducing an installer (kindly sponsored by BitRock) that 
+      simplifies setup.
+      
+    * Configuration: The config file format is now a single YAML file. In most cases,
+      converting to the new format should be trivial - please see the docs for
+      more information.
+
+    * Console: Significant UI improvements - including sorting of flows by
+      size, type and url, status bar improvements, much faster indentation for
+      HTTP views, and more.
+
+    * HTTP/2: Significant improvements, but is temporarily disabled by default
+      due to wide-spread protocol implementation errors on some large website
+
+    * WebSocket: The protocol implementation is now mature, and is enabled by
+      default. Complete UI support is coming in the next release. Hooks for 
+      message interception and manipulation are available.
+
+    * A myriad of other small improvements throughout the project.
+
+
+16 October 2016: mitmproxy 0.18
+
+    * Python 3 Compatibility for mitmproxy and pathod (Shadab Zafar, GSoC 2016)
+
+    * Major improvements to mitmweb (Clemens Brunner & Jason Hao, GSoC 2016)
+
+    * Internal Core Refactor: Separation of most features into isolated Addons
+
+    * Initial Support for WebSockets
+
+    * Improved HTTP/2 Support
+
+    * Reverse Proxy Mode now automatically adjusts host headers and TLS Server Name Indication
+
+    * Improved HAR export
+
+    * Improved export functionality for curl, python code, raw http etc.
+
+    * Flow URLs are now truncated in the console for better visibility
+
+    * New filters for TCP, HTTP and marked flows.
+
+    * Mitmproxy now handles comma-separated Cookie headers
+
+    * Merge mitmproxy and pathod documentation
+
+    * Mitmdump now sanitizes its console output to not include control characters
+
+    * Improved message body handling for HTTP messages:
+      .raw_content provides the message body as seen on the wire
+      .content provides the decompressed body (e.g. un-gzipped)
+      .text provides the body decompressed and decoded body
+
+    * New HTTP Message getters/setters for cookies and form contents.
+
+    * Add ability to view only marked flows in mitmproxy
+
+    * Improved Script Reloader (Always use polling, watch for whole directory)
+
+    * Use tox for testing
+
+    * Unicode support for tnetstrings
+
+    * Add dumpfile converters for mitmproxy versions 0.11 and 0.12
+
+    * Numerous bugfixes
+
+
+9 April 2016: mitmproxy 0.17
+
+    * Simplify repository and release structure. mitmproxy now comes as a single package, including netlib and pathod.
+
+    * Rename the Python package from libmproxy to mitmproxy.
+
+    * New option to add server certs to client chain (CVE-2016-2402, John Kozyrakis)
+
+    * Enable HTTP/2 by default (Thomas Kriechbaumer)
+
+    * Improved HAR extractor (Shadab Zafar)
+
+    * Add icon for OSX and Windows binaries
+
+    * Add content view for query parameters (Will Coster)
+
+    * Initial work on Python 3 compatibility
+
+    * locust.io export (Zohar Lorberbaum)
+
+    * Fix XSS vulnerability in HTTP errors (Will Coster)
+
+    * Numerous bugfixes and minor improvements
+
+
+15 February 2016: mitmproxy 0.16
+
+    * Completely revised HTTP2 implementation based on hyper-h2 (Thomas Kriechbaumer)
+
+    * Export flows as cURL command, Python code or raw HTTP (Shadab Zafar)
+
+    * Fixed compatibility with the Android Emulator (Will Coster)
+
+    * Script Reloader: Inline scripts are reloaded automatically if modified (Matthew Shao)
+
+    * Inline script hooks for TCP mode (Michael J. Bazzinotti)
+
+    * Add default ciphers to support iOS9 App Transport Security (Jorge Villacorta)
+
+    * Basic Authentication for mitmweb (Guillem Anguera)
+
+    * Exempt connections from interception based on TLS Server Name Indication (David Weinstein)
+
+    * Provide Python Wheels for faster installation
+
+    * Numerous bugfixes and minor improvements
+
+
+4 December 2015: mitmproxy 0.15
+
+    * Support for loading and converting older dumpfile formats (0.13 and up)
+
+    * Content views for inline script (@chrisczub)
+
+    * Better handling of empty header values (Benjamin Lee/@bltb)
+
+    * Fix a gnarly memory leak in mitmdump
+
+    * A number of bugfixes and small improvements
+
+
+6 November 2015: mitmproxy 0.14
+
+    * Statistics: 399 commits, 13 contributors, 79 closed issues, 37 closed
+      PRs, 103 days
+
+    * Docs: Greatly updated docs now hosted on ReadTheDocs!
+      http://docs.mitmproxy.org
+
+    * Docs: Fixed Typos, updated URLs etc. (Nick Badger, Ben Lerner, Choongwoo
+      Han, onlywade, Jurriaan Bremer)
+
+    * mitmdump: Colorized TTY output
+
+    * mitmdump: Use mitmproxy's content views for human-readable output (Chris
+      Czub)
+
+    * mitmproxy and mitmdump: Support for displaying UTF8 contents
+
+    * mitmproxy: add command line switch to disable mouse interaction (Timothy
+      Elliott)
+
+    * mitmproxy: bug fixes (Choongwoo Han, sethp-jive, FreeArtMan)
+
+    * mitmweb: bug fixes (Colin Bendell)
+
+    * libmproxy: Add ability to fall back to TCP passthrough for non-HTTP
+      connections.
+
+    * libmproxy: Avoid double-connect in case of TLS Server Name Indication.
+      This yields a massive speedup for TLS handshakes.
+
+    * libmproxy: Prevent unneccessary upstream connections (macmantrl)
+
+    * Inline Scripts: New API for HTTP Headers:
+      http://docs.mitmproxy.org/en/latest/dev/models.html#netlib.http.Headers
+
+    * Inline Scripts: Properly handle exceptions in `done` hook
+
+    * Inline Scripts: Allow relative imports, provide `__file__`
+
+    * Examples: Add probabilistic TLS passthrough as an inline script
+
+    * netlib: Refactored HTTP protocol handling code
+
+    * netlib: ALPN support
+
+    * netlib: fixed a bug in the optional certificate verification.
+
+    * netlib: Initial Python 3.5 support (this is the first prerequisite for
+      3.x support in mitmproxy)
+
+
+24 July 2015: mitmproxy 0.13
+
+    * Upstream certificate validation. See the --verify-upstream-cert,
+      --upstream-trusted-cadir and --upstream-trusted-ca parameters. Thanks to
+      Kyle Morton (github.com/kyle-m) for his work on this.
+
+    * Add HTTP transparent proxy mode. This uses the host headers from HTTP
+      traffic (rather than SNI and IP address information from the OS) to
+      implement perform transparent proxying. Thanks to github.com/ijiro123 for
+      this feature.
+
+    * Add ~src and ~dst REGEX filters, allowing matching on source and
+      destination addresses in the form of <IP>:<Port>
+
+    * mitmproxy console: change g/G keyboard shortcuts to match less. Thanks to
+      Jose Luis Honorato (github.com/jlhonora).
+
+    * mitmproxy console: Flow marking and unmarking. Marked flows are not
+      deleted when the flow list is cleared. Thanks to Jake Drahos
+      (github.com/drahosj).
+
+    * mitmproxy console: add marking of flows
+
+    * Remove the certforward feature. It was added to allow exploitation of
+      #gotofail, which is no longer a common vulnerability. Permitting this
+      hugely increased the complexity of packaging and distributing mitmproxy.
+
+
+
+
+3 June 2015: mitmproxy 0.12.1
+
+    * mitmproxy console: mouse interaction - scroll in the flow list, click on
+      flow to view, click to switch between tabs.
+
+    * Update our crypto defaults: SHA256, 2048 bit RSA, 4096 bit DH parameters.
+
+    * BUGFIX: crash under some circumstances when copying to clipboard.
+
+    * BUGFIX: occasional crash when deleting flows.
+
+
+18 May 2015: mitmproxy 0.12
+
+    * mitmproxy console: Significant revamp of the UI. The major changes are
+      listed below, and in addition almost every aspect of the UI has
+      been tweaked, and performance has improved significantly.
+
+    * mitmproxy console: A new options screen has been created ("o" shortcut),
+      and many options that were previously manipulated directly via a
+      keybinding have been moved there.
+
+    * mitmproxy console: Big improvement in palettes. This includes improvements
+      to all colour schemes. Palettes now set the terminal background colour by
+      default, and a new --palette-transparent option has been added to disable
+      this.
+
+    * mitmproxy console: g/G shortcuts throughout mitmproxy console to jump
+      to the beginning/end of the current view.
+
+    * mitmproxy console: switch  palettes on the fly from the options screen.
+
+    * mitmproxy console: A cookie editor has been added for mitmproxy console
+      at long last.
+
+    * mitmproxy console: Various components of requests and responses can be
+      copied to the clipboard from mitmproxy - thanks to @marceloglezer.
+
+    * Support for creating new requests from scratch in mitmproxy console (@marceloglezer).
+
+    * SSLKEYLOGFILE environment variable to specify a logging location for TLS
+      master keys. This can be used with tools like Wireshark to allow TLS
+      decoding.
+
+    * Server facing SSL cipher suite specification (thanks to Jim Shaver).
+
+    * Official support for transparent proxying on FreeBSD - thanks to Mike C
+      (http://github.com/mike-pt).
+
+    * Many other small bugfixes and improvemenets throughout the project.
+
+
+29 Dec 2014: mitmproxy 0.11.2:
+
+    * Configuration files - mitmproxy.conf, mitmdump.conf, common.conf in the
+      .mitmproxy directory.
+    * Better handling of servers that reject connections that are not SNI.
+    * Many other small bugfixes and improvements.
+
+
+15 November 2014: mitmproxy 0.11.1:
+
+    * Bug fixes: connection leaks some crashes
+
+
+7 November 2014: mitmproxy 0.11:
+
+    * Performance improvements for mitmproxy console
+
+    * SOCKS5 proxy mode allows mitmproxy to act as a SOCKS5 proxy server
+
+    * Data streaming for response bodies exceeding a threshold
+      (bradpeabody@gmail.com)
+
+    * Ignore hosts or IP addresses, forwarding both HTTP and HTTPS traffic
+      untouched
+
+    * Finer-grained control of traffic replay, including options to ignore
+      contents or parameters when matching flows (marcelo.glezer@gmail.com)
+
+    * Pass arguments to inline scripts
+
+    * Configurable size limit on HTTP request and response bodies
+
+    * Per-domain specification of interception certificates and keys (see
+      --cert option)
+
+    * Certificate forwarding, relaying upstream SSL certificates verbatim (see
+      --cert-forward)
+
+    * Search and highlighting for HTTP request and response bodies in
+      mitmproxy console (pedro@worcel.com)
+
+    * Transparent proxy support on Windows
+
+    * Improved error messages and logging
+
+    * Support for FreeBSD in transparent mode, using pf (zbrdge@gmail.com)
+
+    * Content view mode for WBXML (davidshaw835@air-watch.com)
+
+    * Better documentation, with a new section on proxy modes
+
+    * Generic TCP proxy mode
+
+    * Countless bugfixes and other small improvements
+
+    * pathod: Hugely improved SSL support, including dynamic generation of certificates
+    using the mitproxy cacert
+
+7 November 2014: pathod 0.11:
+
+  * Hugely improved SSL support, including dynamic generation of certificates
+    using the mitproxy cacert
+
+  * pathoc -S dumps information on the remote SSL certificate chain
+
+  * Big improvements to fuzzing, including random spec selection and memoization to avoid repeating randomly generated patterns
+
+  * Reflected patterns, allowing you to embed a pathod server response specification in a pathoc request, resolving both on client side. This makes fuzzing proxies and other intermediate systems much better.
+
+
+28 January 2014: mitmproxy 0.10:
+
+    * Support for multiple scripts and multiple script arguments
+
+    * Easy certificate install through the in-proxy web app, which is now
+      enabled by default
+
+    * Forward proxy mode, that forwards proxy requests to an upstream HTTP server
+
+    * Reverse proxy now works with SSL
+
+    * Search within a request/response using the "/" and "n" shortcut keys
+
+    * A view that beatifies CSS files if cssutils is available
+
+    * Bug fix, documentation improvements, and more.
+
+
+25 August 2013: mitmproxy 0.9.2:
+
+    * Improvements to the mitmproxywrapper.py helper script for OSX.
+
+    * Don't take minor version into account when checking for serialized file
+      compatibility.
+
+    * Fix a bug causing resource exhaustion under some circumstances for SSL
+      connections.
+
+    * Revamp the way we store interception certificates. We used to store these
+      on disk, they're now in-memory. This fixes a race condition related to
+      cert handling, and improves compatibility with Windows, where the rules
+      governing permitted file names are weird, resulting in errors for some
+      valid IDNA-encoded names.
+
+    * Display transfer rates for responses in the flow list.
+
+    * Many other small bugfixes and improvements.
+
+
+25 August 2013: pathod 0.9.2:
+
+    * Adapt to interface changes in netlib
+
+
+16 June 2013: mitmproxy 0.9.1:
+
+    * Use "correct" case for Content-Type headers added by mitmproxy.
+
+    * Make UTF environment detection more robust.
+
+    * Improved MIME-type detection for viewers.
+
+    * Always read files in binary mode (Windows compatibility fix).
+
+    * Some developer documentation.
+
+
+15 May 2013: mitmproxy 0.9:
+
+    * Upstream certs mode is now the default.
+
+    * Add a WSGI container that lets you host in-proxy web applications.
+
+    * Full transparent proxy support for Linux and OSX.
+
+    * Introduce netlib, a common codebase for mitmproxy and pathod
+      (http://github.com/cortesi/netlib).
+
+    * Full support for SNI.
+
+    * Color palettes for mitmproxy, tailored for light and dark terminal
+      backgrounds.
+
+    * Stream flows to file as responses arrive with the "W" shortcut in
+      mitmproxy.
+
+    * Extend the filter language, including ~d domain match operator, ~a to
+      match asset flows (js, images, css).
+
+    * Follow mode in mitmproxy ("F" shortcut) to "tail" flows as they arrive.
+
+    * --dummy-certs option to specify and preserve the dummy certificate
+      directory.
+
+    * Server replay from the current captured buffer.
+
+    * Huge improvements in content views. We now have viewers for AMF, HTML,
+      JSON, Javascript, images, XML, URL-encoded forms, as well as hexadecimal
+      and raw views.
+
+    * Add Set Headers, analagous to replacement hooks. Defines headers that are set
+      on flows, based on a matching pattern.
+
+    * A graphical editor for path components in mitmproxy.
+
+    * A small set of standard user-agent strings, which can be used easily in
+      the header editor.
+
+    * Proxy authentication to limit access to mitmproxy
+
+    * pathod: Proxy mode. You can now configure clients to use pathod as an
+      HTTP/S proxy.
+
+    * pathoc: Proxy support, including using CONNECT to tunnel directly to
+      targets.
+
+    * pathoc: client certificate support.
+
+    * pathod: API improvements, bugfixes.
+
+
+15 May 2013: pathod 0.9 (version synced with mitmproxy):
+
+    * Pathod proxy mode. You can now configure clients to use pathod as an
+      HTTP/S proxy.
+
+    * Pathoc proxy support, including using CONNECT to tunnel directly to
+      targets.
+
+    * Pathoc client certificate support.
+
+    * API improvements, bugfixes.
+
+
+16 November 2012: pathod 0.3:
+
+    A release focusing on shoring up our fuzzing capabilities, especially with
+    pathoc.
+
+    * pathoc -q and -r options, output full request and response text.
+
+    * pathod -q and -r options, add full request and response text to pathod's
+      log buffer.
+
+    * pathoc and pathod -x option, makes -q and -r options log in hex dump
+      format.
+
+    * pathoc -C option, specify response codes to ignore.
+
+    * pathoc -T option, instructs pathoc to ignore timeouts.
+
+    * pathoc -o option, a one-shot mode that exits after the first non-ignored
+      response.
+
+    * pathoc and pathod -e option, which explains the resulting message by
+      expanding random and generated portions, and logging a reproducible
+      specification.
+
+    * Streamline the specification langauge. HTTP response message is now
+      specified using the "r" mnemonic.
+
+    * Add a "u" mnemonic for specifying User-Agent strings. Add a set of
+      standard user-agent strings accessible through shortcuts.
+
+    * Major internal refactoring and cleanup.
+
+    * Many bugfixes.
+
+
+22 August 2012: pathod 0.2:
+
+    * Add pathoc, a pathological HTTP client.
+
+    * Add libpathod.test, a truss for using pathod in unit tests.
+
+    * Add an injection operator to the specification language.
+
+    * Allow Python escape sequences in value literals.
+
+    * Allow execution of requests and responses from file, using the new + operator.
+
+    * Add daemonization to Pathod, and make it more robust for public-facing use.
+
+    * Let pathod pick an arbitrary open port if -p 0 is specified.
+
+    * Move from Tornado to netlib, the network library written for mitmproxy.
+
+    * Move the web application to Flask.
+
+    * Massively expand the documentation.
+
+
+5 April 2012: mitmproxy 0.8:
+
+    * Detailed tutorial for Android interception. Some features that land in
+      this release have finally made reliable Android interception possible.
+
+    * Upstream-cert mode, which uses information from the upstream server to
+      generate interception certificates.
+
+    * Replacement patterns that let you easily do global replacements in flows
+      matching filter patterns. Can be specified on the command-line, or edited
+      interactively.
+
+    * Much more sophisticated and usable pretty printing of request bodies.
+      Support for auto-indentation of Javascript, inspection of image EXIF
+      data, and more.
+
+    * Details view for flows, showing connection and SSL cert information (X
+      keyboard shortcut).
+
+    * Server certificates are now stored and serialized in saved traffic for
+      later analysis. This means that the 0.8 serialization format is NOT
+      compatible with 0.7.
+
+    * Many other improvements, including bugfixes, and expanded scripting API,
+      and more sophisticated certificate handling.
+
+
+20 February 2012: mitmproxy 0.7:
+
+    * New built-in key/value editor. This lets you interactively edit URL query
+      strings, headers and URL-encoded form data.
+
+    * Extend script API to allow duplication and replay of flows.
+
+    * API for easy manipulation of URL-encoded forms and query strings.
+
+    * Add "D" shortcut in mitmproxy to duplicate a flow.
+
+    * Reverse proxy mode. In this mode mitmproxy acts as an HTTP server,
+      forwarding all traffic to a specified upstream server.
+
+    * UI improvements - use unicode characters to make GUI more compact,
+      improve spacing and layout throughout.
+
+    * Add support for filtering by HTTP method.
+
+    * Add the ability to specify an HTTP body size limit.
+
+    * Move to typed netstrings for serialization format - this makes 0.7
+      backwards-incompatible with serialized data from 0.6!
+
+    * Significant improvements in speed and responsiveness of UI.
+
+    * Many minor bugfixes and improvements.
+
+
+7 August 2011: mitmproxy 0.6:
+
+    * New scripting API that allows much more flexible and fine-grained
+      rewriting of traffic. See the docs for more info.
+
+    * Support for gzip and deflate content encodings. A new "z"
+      keybinding in mitmproxy to let us quickly encode and decode content, plus
+      automatic decoding for the "pretty" view mode.
+
+    * An event log, viewable with the "v" shortcut in mitmproxy, and the
+      "-e" command-line flag in mitmdump.
+
+    * Huge performance improvements: mitmproxy interface, loading
+      large numbers of flows from file.
+
+    * A new "replace" convenience method for all flow objects, that does a
+      universal regex-based string replacement.
+
+    * Header management has been rewritten to maintain both case and order.
+
+    * Improved stability for SSL interception.
+
+    * Default expiry time on generated SSL certs has been dropped to avoid an
+      OpenSSL overflow bug that caused certificates to expire in the distant
+      past on some systems.
+
+    * A "pretty" view mode for JSON and form submission data.
+
+    * Expanded documentation and examples.
+
+    * Countless other small improvements and bugfixes.
+
+
+27 June 2011: mitmproxy 0.5:
+
+    * An -n option to start the tools without binding to a proxy port.
+
+    * Allow scripts, hooks, sticky cookies etc. to run on flows loaded from
+      save files.
+
+    * Regularize command-line options for mitmproxy and mitmdump.
+
+    * Add an "SSL exception" to mitmproxy's license to remove possible
+      distribution issues.
+
+    * Add a --cert-wait-time option to make mitmproxy pause after a new SSL
+      certificate is generated. This can pave over small discrepancies in
+      system time between the client and server.
+
+    * Handle viewing big request and response bodies more elegantly. Only
+      render the first 100k of large documents, and try to avoid running the
+      XML indenter on non-XML data.
+
+    * BUGFIX: Make the "revert" keyboard shortcut in mitmproxy work after a
+      flow has been replayed.
+
+    * BUGFIX: Repair a problem that sometimes caused SSL connections to consume
+      100% of CPU.
+
+
+30 March 2011: mitmproxy 0.4
+
+    * Full serialization of HTTP conversations
+
+    * Client and server replay
+
+    * On-the-fly generation of dummy SSL certificates
+
+    * mitmdump has "grown up" into a powerful tcpdump-like tool for HTTP/S
+
+    * Dozens of improvements to the mitmproxy console interface
+
+    * Python scripting hooks for programmatic modification of traffic
+
+
+1 March 2010: mitmproxy 0.2
+
+    * Big speed and responsiveness improvements, thanks to Thomas Roth
+
+    * Support urwid 0.9.9
+
+    * Terminal beeping based on filter expressions
+
+    * Filter expressions for terminal beeps, limits, interceptions and sticky
+      cookies can now be passed on the command line.
+
+    * Save requests and responses to file
+
+    * Split off non-interactive dump functionality into a new tool called
+      mitmdump
+
+    * "A" will now accept all intercepted connections
+
+    * Lots of bugfixes

CONTRIBUTORS

@@ -0,0 +1,189 @@
+  2407	Aldo Cortesi
+  1873	Maximilian Hils
+   556	Thomas Kriechbaumer
+   258	Shadab Zafar
+    97	Jason
+    83	Marcelo Glezer
+    68	Clemens
+    28	Jim Shaver
+    18	Henrik Nordstrom
+    16	Matthew Shao
+    14	Pedro Worcel
+    14	David Weinstein
+    13	Thomas Roth
+    11	Jake Drahos
+    11	Stephen Altamirano
+    11	arjun23496
+    11	Justus Wingert
+    10	András Veres-Szentkirályi
+    10	Zohar Lorberbaum
+    10	smill
+    10	Chris Czub
+    10	Sandor Nemes
+    10	Doug Freed
+     9	ikoz
+     9	Legend Tang
+     9	Rouli
+     9	Kyle Morton
+     8	Jason A. Novak
+     8	Chandler Abraham
+     7	Matthias Urlichs
+     7	Brad Peabody
+     7	dufferzafar
+     7	Alexis Hildebrandt
+     6	Felix Yan
+     5	Will Coster
+     5	Sam Cleveland
+     5	iroiro123
+     5	elitest
+     5	Tomaz Muraus
+     5	Choongwoo Han
+     4	Schamper
+     4	Youhei Sakurai
+     4	Bryan Bishop
+     4	root
+     4	Valtteri Virtanen
+     4	Clemens Brunner
+     4	Marc Liyanage
+     4	Wade 524
+     4	chhsiao90
+     4	yonder
+     4	Michael J. Bazzinotti
+     3	Ryan Welton
+     3	Ryan Laughlin
+     3	Kyle Manna
+     3	Eli Shvartsman
+     3	Vincent Haupert
+     3	Manish Kumar
+     3	Zack B
+     3	MatthewShao
+     3	redfast00
+     3	requires.io
+     3	Guillem Anguera
+     3	smill@cuckoo.sh
+     3	Chris Neasbitt
+     3	Benjamin Lee
+     2	Steven Van Acker
+     2	Slobodan Mišković
+     2	Jim Lloyd
+     2	isra17
+     2	israel
+     2	Sean Coates
+     2	Sachin Kelkar
+     2	jpkrause
+     2	Bennett Blodinger
+     2	lilydjwg
+     2	Michael Frister
+     2	Israel Nir
+     2	Cory Benfield
+     2	phackt
+     2	Anant
+     2	Jaime Soriano Pastor
+     2	Paul
+     2	Colin Bendell
+     2	依云
+     2	Heikki Hannikainen
+     2	Rob Wills
+     2	Niko Kommenda
+     2	Naveen Pai
+     2	strohu
+     2	alts
+     2	Yoginski
+     2	Mark E. Haase
+     2	Wade Catron
+     2	Terry Long
+     2	Krzysztof Bielicki
+     2	Nick Badger
+     1	Nicolas Esteves
+     1	Andrew Orr
+     1	Andrey Plotnikov
+     1	Andy Smith
+     1	Angelo Agatino Nicolosi
+     1	Anthony Zhang
+     1	BSalita
+     1	Ben Lerner
+     1	Bradley Baetz
+     1	Brady Law
+     1	Brett Randall
+     1	Chris Hamant
+     1	Christian Frichot
+     1	Dan Wilbraham
+     1	David Dworken
+     1	David Shaw
+     1	Doug Lethin
+     1	Drake Caraker
+     1	Edgar Boda-Majer
+     1	Eric Entzel
+     1	Felix Wolfsteller
+     1	FreeArtMan
+     1	Gabriel Kirkpatrick
+     1	Henrik Nordström
+     1	Israel Blancas
+     1	Ivaylo Popov
+     1	JC
+     1	Jakub Nawalaniec
+     1	Jakub Wilk
+     1	James Billingham
+     1	Jason Pepas
+     1	Jean Regisser
+     1	Jonathan Jones
+     1	Jorge Villacorta
+     1	Kit Randel
+     1	Kostya Esmukov
+     1	Linmiao Xu
+     1	Lucas Cimon
+     1	M. Utku Altinkaya
+     1	Mathieu Mitchell
+     1	Michael Bisbjerg
+     1	Mike C
+     1	Mike Fotinakis
+     1	Mikhail Korobov
+     1	Morton Fox
+     1	Nick HS
+     1	Nick Raptis
+     1	Aditya
+     1	Oleksandr Sheremet
+     1	Parth Ganatra
+     1	Pritam Baral
+     1	Quentin Pradet
+     1	Rich Somerfield
+     1	Rory McCann
+     1	Rune Halvorsen
+     1	Ryo Onodera
+     1	Sahil Chelaramani
+     1	Sahn Lam
+     1	Sanchit Sokhey
+     1	Seppo Yli-Olli
+     1	Sergey Chipiga
+     1	Stefan Wärting
+     1	Steve Phillips
+     1	Steven Noble
+     1	Suyash
+     1	Tai Dickerson
+     1	Tarashish Mishra
+     1	TearsDontFalls
+     1	Thiago Arrais
+     1	Tim Becker
+     1	Timothy Elliott
+     1	Tyler St. Onge
+     1	Ulrich Petri
+     1	Vyacheslav Bakhmutov
+     1	Wes Turner
+     1	Yuangxuan Wang
+     1	capt8bit
+     1	cle1000
+     1	davidpshaw
+     1	deployable
+     1	gecko655
+     1	jlhonora
+     1	joebowbeer
+     1	kronick
+     1	meeee
+     1	michaeljau
+     1	peralta
+     1	phil plante
+     1	sentient07
+     1	sethp-jive
+     1	starenka
+     1	vulnminer
+     1	vzvu3k6k

LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2013, Aldo Cortesi. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

MANIFEST.in

@@ -0,0 +1,3 @@
+graft mitmproxy
+graft pathod
+recursive-exclude * *.pyc *.pyo *.swo *.swp *.map

README

@@ -1,11 +0,0 @@
-
-Netlib is a collection of network utility classes, used by pathod and mitmproxy
-projects. It differs from other projects in some fundamental respects, because
-both pathod and mitmproxy often need to violate standards. This means that
-protocols are implemented as small, well-contained and flexible functions, and
-servers are implemented to allow misbehaviour when needed.
-
-At this point, I have no plans to make netlib useful beyond mitmproxy and
-pathod. Please get in touch if you think parts of netlib might have broader
-utility.
-

README.rst

@@ -0,0 +1,189 @@
+mitmproxy
+^^^^^^^^^
+
+|travis| |appveyor| |coverage| |latest_release| |python_versions|
+
+This repository contains the **mitmproxy** and **pathod** projects.
+
+``mitmproxy`` is an interactive, SSL-capable intercepting proxy with a console
+interface.
+
+``mitmdump`` is the command-line version of mitmproxy. Think tcpdump for HTTP.
+
+``mitmweb`` is a web-based interface for mitmproxy.
+
+``pathoc`` and ``pathod`` are perverse HTTP client and server applications
+designed to let you craft almost any conceivable HTTP request, including ones
+that creatively violate the standards.
+
+
+Documentation & Help
+--------------------
+
+
+General information, tutorials, and precompiled binaries can be found on the mitmproxy
+and pathod websites.
+
+|mitmproxy_site|
+
+The latest documentation for mitmproxy is also available on ReadTheDocs.
+
+|mitmproxy_docs|
+
+
+Join our discussion forum on Discourse to ask questions, help
+each other solve problems, and come up with new ideas for the project.
+
+|mitmproxy_discourse|
+
+
+Join our developer chat on Slack if you would like to contribute to mitmproxy itself.
+
+|slack|
+
+
+Installation
+------------
+
+The installation instructions are `here <http://docs.mitmproxy.org/en/stable/install.html>`__.
+If you want to contribute changes, keep on reading.
+
+Contributing
+------------
+
+As an open source project, mitmproxy welcomes contributions of all forms. If you would like to bring the project forward,
+please consider contributing in the following areas:
+
+- **Maintenance:** We are *incredibly* thankful for individuals who are stepping up and helping with maintenance. This includes (but is not limited to) triaging issues, reviewing pull requests and picking up stale ones, helping out other users in our forums_, creating minimal, complete and verifiable examples or test cases for existing bug reports, updating documentation, or fixing minor bugs that have recently been reported.
+- **Code Contributions:** We actively mark issues that we consider are `good first contributions`_. If you intend to work on a larger contribution to the project, please come talk to us first.
+
+Development Setup
+-----------------
+
+To get started hacking on mitmproxy, please follow the `advanced installation`_ steps to install mitmproxy from source, but stop right before running ``pip3 install mitmproxy``. Instead, do the following:
+
+.. code-block:: bash
+
+    git clone https://github.com/mitmproxy/mitmproxy.git
+    cd mitmproxy
+    ./dev.sh  # "powershell .\dev.ps1" on Windows
+
+
+The *dev* script will create a `virtualenv`_ environment in a directory called "venv"
+and install all mandatory and optional dependencies into it. The primary
+mitmproxy components - mitmproxy and pathod - are installed as
+"editable", so any changes to the source in the repository will be reflected
+live in the virtualenv.
+
+The main executables for the project - ``mitmdump``, ``mitmproxy``,
+``mitmweb``, ``pathod``, and ``pathoc`` - are all created within the
+virtualenv. After activating the virtualenv, they will be on your $PATH, and
+you can run them like any other command:
+
+.. code-block:: bash
+
+    . venv/bin/activate  # "venv\Scripts\activate" on Windows
+    mitmdump --version
+
+Testing
+-------
+
+If you've followed the procedure above, you already have all the development
+requirements installed, and you can run the full test suite (including tests for code style and documentation) with tox_:
+
+.. code-block:: bash
+
+    tox
+
+For speedier testing, we recommend you run `pytest`_ directly on individual test files or folders:
+
+.. code-block:: bash
+
+    cd test/mitmproxy/addons
+    pytest --cov mitmproxy.addons.anticache --looponfail test_anticache.py
+
+As pytest does not check the code style, you probably want to run ``tox -e lint`` before committing your changes.
+
+Please ensure that all patches are accompanied by matching changes in the test
+suite. The project tries to maintain 100% test coverage and enforces this strictly for some parts of the codebase.
+
+Documentation
+-------------
+
+The mitmproxy documentation is build using Sphinx_, which is installed
+automatically if you set up a development environment as described above. After
+installation, you can render the documentation like this:
+
+.. code-block:: bash
+
+    cd docs
+    make clean
+    make html
+    make livehtml
+
+The last command invokes `sphinx-autobuild`_, which watches the Sphinx directory and rebuilds
+the documentation when a change is detected.
+
+Code Style
+----------
+
+Keeping to a consistent code style throughout the project makes it easier to
+contribute and collaborate. Please stick to the guidelines in
+`PEP8`_ and the `Google Style Guide`_ unless there's a very
+good reason not to.
+
+This is automatically enforced on every PR. If we detect a linting error, the
+PR checks will fail and block merging. You can run our lint checks yourself
+with the following command:
+
+.. code-block:: bash
+
+    tox -e lint
+
+
+.. |mitmproxy_site| image:: https://shields.mitmproxy.org/api/https%3A%2F%2F-mitmproxy.org-blue.svg
+    :target: https://mitmproxy.org/
+    :alt: mitmproxy.org
+
+.. |mitmproxy_docs| image:: https://shields.mitmproxy.org/api/docs-latest-brightgreen.svg
+    :target: http://docs.mitmproxy.org/en/latest/
+    :alt: mitmproxy documentation
+
+.. |mitmproxy_discourse| image:: https://shields.mitmproxy.org/api/https%3A%2F%2F-discourse.mitmproxy.org-orange.svg
+    :target: https://discourse.mitmproxy.org
+    :alt: Discourse: mitmproxy
+
+.. |slack| image:: http://slack.mitmproxy.org/badge.svg
+    :target: http://slack.mitmproxy.org/
+    :alt: Slack Developer Chat
+
+.. |travis| image:: https://shields.mitmproxy.org/travis/mitmproxy/mitmproxy/master.svg?label=travis%20ci
+    :target: https://travis-ci.org/mitmproxy/mitmproxy
+    :alt: Travis Build Status
+
+.. |appveyor| image:: https://shields.mitmproxy.org/appveyor/ci/mhils/mitmproxy/master.svg?label=appveyor%20ci
+    :target: https://ci.appveyor.com/project/mhils/mitmproxy
+    :alt: Appveyor Build Status
+
+.. |coverage| image:: https://shields.mitmproxy.org/codecov/c/github/mitmproxy/mitmproxy/master.svg?label=codecov
+    :target: https://codecov.io/gh/mitmproxy/mitmproxy
+    :alt: Coverage Status
+
+.. |latest_release| image:: https://shields.mitmproxy.org/pypi/v/mitmproxy.svg
+    :target: https://pypi.python.org/pypi/mitmproxy
+    :alt: Latest Version
+
+.. |python_versions| image:: https://shields.mitmproxy.org/pypi/pyversions/mitmproxy.svg
+    :target: https://pypi.python.org/pypi/mitmproxy
+    :alt: Supported Python versions
+
+.. _`advanced installation`: http://docs.mitmproxy.org/en/latest/install.html#advanced-installation
+.. _virtualenv: https://virtualenv.pypa.io/
+.. _`pytest`: http://pytest.org/
+.. _tox: https://tox.readthedocs.io/
+.. _Sphinx: http://sphinx-doc.org/
+.. _sphinx-autobuild: https://pypi.python.org/pypi/sphinx-autobuild
+.. _PEP8: https://www.python.org/dev/peps/pep-0008
+.. _`Google Style Guide`: https://google.github.io/styleguide/pyguide.html
+.. _forums: https://discourse.mitmproxy.org/
+.. _`good first contributions`: https://github.com/mitmproxy/mitmproxy/issues?q=is%3Aissue+is%3Aopen+label%3Agood-first-contribution

dev.ps1

@@ -0,0 +1,20 @@
+$ErrorActionPreference = "Stop"
+
+$pyver = python --version
+if($pyver -notmatch "3\.[5-9]") {
+    Write-Warning "Unexpected Python version, expected Python 3.5 or above: $pyver"
+}
+
+python -m venv .\venv --copies
+& .\venv\Scripts\activate.ps1
+
+python -m pip install --disable-pip-version-check -U pip
+cmd /c "pip install -r requirements.txt 2>&1"
+
+echo @"
+
+  * Created virtualenv environment in .\venv.
+  * Installed all dependencies into the virtualenv.
+  * Activated virtualenv environment.
+
+"@

dev.sh

@@ -0,0 +1,15 @@
+#!/bin/sh
+set -e
+set -x
+
+echo "Creating dev environment in ./venv..."
+
+python3 -m venv venv
+. venv/bin/activate
+pip3 install -U pip setuptools
+pip3 install -r requirements.txt
+
+echo ""
+echo "  * Created virtualenv environment in ./venv."
+echo "  * Installed all dependencies into the virtualenv."
+echo "  * You can now activate the $(python3 --version) virtualenv with this command: \`. venv/bin/activate\`"

docs/.gitignore

@@ -0,0 +1 @@
+_build/

docs/Makefile

@@ -0,0 +1,195 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = _build
+
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  applehelp  to make an Apple Help Book"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@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 "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  xml        to make Docutils-native XML files"
+	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+	@echo "  coverage   to run coverage check of the documentation (if enabled)"
+
+clean:
+	rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/mitmproxy.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/mitmproxy.qhc"
+
+applehelp:
+	$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
+	@echo
+	@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
+	@echo "N.B. You won't be able to view it unless you put it in" \
+	      "~/Library/Documentation/Help or install it in your application" \
+	      "bundle."
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/mitmproxy"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/mitmproxy"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+latexpdfja:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through platex and dvipdfmx..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
+
+coverage:
+	$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
+	@echo "Testing of coverage in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/coverage/python.txt."
+
+xml:
+	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+	@echo
+	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+pseudoxml:
+	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+	@echo
+	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
+
+livehtml:
+	sphinx-autobuild -b html -z '../mitmproxy' -r '___jb_(old|bak|tmp)___$$' $(ALLSPHINXOPTS) $(BUILDDIR)/html

docs/_static/theme_overrides.css

@@ -0,0 +1,44 @@
+
+/* override table width restrictions */
+.wy-table-responsive table td, .wy-table-responsive table th {
+    white-space: normal;
+}
+
+.wy-table-responsive > table > tbody > tr > td {
+    vertical-align: top !important;
+}
+
+.wy-table-responsive {
+    margin-bottom: 24px;
+    max-width: 100%;
+    overflow: visible;
+}
+
+.wy-menu-vertical header, .wy-menu-vertical p.caption {
+    color: #e0e0e0;
+}
+
+.code-block-caption {
+    height: 1.5em;
+}
+
+.code-block-caption .caption-text {
+    font-size: 0.8em;
+    float: right;
+}
+
+.code-block-caption .headerlink {
+    display: none !important;
+}
+
+.function .headerlink {
+    display: none !important;
+}
+
+dl .reference.internal {
+    display: none !important;
+}
+
+dl .headerlink {
+    display: none !important;
+}

docs/_templates/page.html

@@ -0,0 +1,10 @@
+{% extends "!page.html" %}
+{% block sidebartitle %}
+    <a href="https://mitmproxy.org/" style="margin-bottom: 7px; background: none !important;">
+        <button class="btn btn-info">
+            <i class="fa fa-arrow-left"></i>
+            Return to mitmproxy.org
+        </button>
+    </a>
+    {{ super() }}
+{% endblock %}

docs/certinstall.rst

@@ -0,0 +1,211 @@
+.. _certinstall:
+
+About Certificates
+==================
+
+Introduction
+------------
+
+Mitmproxy can decrypt encrypted traffic on the fly, as long as the client
+trusts its built-in certificate authority. Usually this means that the
+mitmproxy CA certificates have to be installed on the client device.
+
+Quick Setup
+-----------
+
+By far the easiest way to install the mitmproxy certificates is to use the
+built-in certificate installation app. To do this, just start mitmproxy and
+configure your target device with the correct proxy settings. Now start a
+browser on the device, and visit the magic domain **mitm.it**. You should see
+something like this:
+
+.. image:: certinstall-webapp.png
+
+Click on the relevant icon, follow the setup instructions for the platform
+you're on and you are good to go.
+
+For iOS version 10.3 or up, you need to make sure ``mitmproxy`` is enabled in 
+``Certificate Trust Settings``, you can check it by going to 
+``Settings > General > About > Certificate Trust Settings``.
+
+Installing the mitmproxy CA certificate manually
+------------------------------------------------
+
+Sometimes using the quick install app is not an option - Java or the iOS
+Simulator spring to mind - or you just need to do it manually for some other
+reason. Below is a list of pointers to manual certificate installation
+documentation for some common platforms.
+
+The mitmproxy CA cert is located in ``~/.mitmproxy`` after it has been generated at the first
+start of mitmproxy.
+
+
+iOS
+^^^
+
+See http://jasdev.me/intercepting-ios-traffic
+
+and https://web.archive.org/web/20150920082614/http://kb.mit.edu/confluence/pages/viewpage.action?pageId=152600377
+
+iOS Simulator
+^^^^^^^^^^^^^
+
+See https://github.com/ADVTOOLS/ADVTrustStore#how-to-use-advtruststore
+
+Java
+^^^^
+
+See https://docs.oracle.com/cd/E19906-01/820-4916/geygn/index.html
+
+Android/Android Simulator
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+See http://wiki.cacert.org/FAQ/ImportRootCert#Android_Phones_.26_Tablets
+
+Windows
+^^^^^^^
+
+See https://web.archive.org/web/20160612045445/http://windows.microsoft.com/en-ca/windows/import-export-certificates-private-keys#1TC=windows-7
+
+Windows (automated)
+^^^^^^^^^^^^^^^^^^^
+
+>>> certutil.exe -importpfx Root mitmproxy-ca-cert.p12
+
+See also: https://technet.microsoft.com/en-us/library/cc732443.aspx
+
+Mac OS X
+^^^^^^^^
+
+See https://support.apple.com/kb/PH7297?locale=en_US
+
+Ubuntu/Debian
+^^^^^^^^^^^^^
+
+See https://askubuntu.com/questions/73287/how-do-i-install-a-root-certificate/94861#94861
+
+Mozilla Firefox
+^^^^^^^^^^^^^^^
+
+See https://wiki.mozilla.org/MozillaRootCertificate#Mozilla_Firefox
+
+Chrome on Linux
+^^^^^^^^^^^^^^^
+
+See https://stackoverflow.com/a/15076602/198996
+
+
+The mitmproxy certificate authority
+-----------------------------------
+
+The first time **mitmproxy** or **mitmdump** is run, the mitmproxy Certificate
+Authority (CA) is created in the config directory (``~/.mitmproxy`` by default).
+This CA is used for on-the-fly generation of dummy certificates for each of the
+SSL sites that your client visits. Since your browser won't trust the
+mitmproxy CA out of the box, you will see an SSL certificate warning every
+time you visit a new SSL domain through mitmproxy. When you are testing a
+single site through a browser, just accepting the bogus SSL cert manually is
+not too much trouble, but there are a many circumstances where you will want to
+configure your testing system or browser to trust the mitmproxy CA as a
+signing root authority. For security reasons, the mitmproxy CA is generated uniquely on the first start and is not shared between mitmproxy installations on different devices.
+
+Certificate Pinning
+^^^^^^^^^^^^^^^^^^^
+
+Some applications employ `Certificate Pinning`_ to prevent man-in-the-middle attacks.
+This means that **mitmproxy** and **mitmdump's** certificates will not be
+accepted by these applications without modifying them. It is recommended to use the
+:ref:`passthrough` feature in order to prevent **mitmproxy** and **mitmdump** from intercepting
+traffic to these specific domains. If you want to intercept the pinned connections, you need to patch the application manually. For Android and (jailbroken) iOS devices, various tools exist to accomplish this.
+
+
+CA and cert files
+-----------------
+
+The files created by mitmproxy in the .mitmproxy directory are as follows:
+
+===================== ==========================================================================
+mitmproxy-ca.pem      The certificate **and the private key** in PEM format.
+mitmproxy-ca-cert.pem The certificate in PEM format.
+                      Use this to distribute on most non-Windows platforms.
+mitmproxy-ca-cert.p12 The certificate in PKCS12 format. For use on Windows.
+mitmproxy-ca-cert.cer Same file as .pem, but with an extension expected by some Android devices.
+===================== ==========================================================================
+
+Using a custom certificate
+--------------------------
+
+You can use your own (leaf) certificate by passing the ``--cert [domain=]path_to_certificate`` option to
+mitmproxy. Mitmproxy then uses the provided certificate for interception of the
+specified domain instead of generating a certificate signed by its own CA.
+
+The certificate file is expected to be in the PEM format.  You can include
+intermediary certificates right below your leaf certificate, so that your PEM
+file roughly looks like this:
+
+.. code-block:: none
+
+    -----BEGIN PRIVATE KEY-----
+    <private key>
+    -----END PRIVATE KEY-----
+    -----BEGIN CERTIFICATE-----
+    <cert>
+    -----END CERTIFICATE-----
+    -----BEGIN CERTIFICATE-----
+    <intermediary cert (optional)>
+    -----END CERTIFICATE-----
+
+
+For example, you can generate a certificate in this format using these instructions:
+
+
+>>> openssl genrsa -out cert.key 2048
+>>> openssl req -new -x509 -key cert.key -out cert.crt
+    (Specify the mitm domain as Common Name, e.g. *.google.com)
+>>> cat cert.key cert.crt > cert.pem
+
+Now, you can run mitmproxy with the generated certificate:
+
+**For all domain names**
+
+``>>>mitmproxy --cert *=cert.pem``
+
+**For specific domain names**
+
+``>>>mitmproxy --cert *.example.com=cert.pem``
+
+**Note:** ``*.example.com`` is for all the subdomains. You can also use ``www.example.com`` for a particular subdomain.
+
+
+Using a custom certificate authority
+------------------------------------
+
+By default, mitmproxy will use ``~/.mitmproxy/mitmproxy-ca.pem`` as
+the certificate authority to generate certificates for all domains for which no
+custom certificate is provided (see above). You can use your own certificate
+authority by passing the ``--cadir DIRECTORY`` option to mitmproxy. Mitmproxy
+will then look for ``mitmproxy-ca.pem`` in the specified directory. If
+no such file exists, it will be generated automatically.
+
+
+Using a client side certificate
+-------------------------------
+
+You can use a client certificate by passing the ``--client-certs DIRECTORY|FILE``
+option to mitmproxy. Using a directory allows certs to be selected based on
+hostname, while using a filename allows a single specific certificate to be used for
+all SSL connections. Certificate files must be in the PEM format and should
+contain both the unencrypted private key and the certificate.
+
+Multiple certs by Hostname
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you've specified a directory to ``--client-certs``, then the following
+behavior will be taken:
+
+If you visit example.org, mitmproxy looks for a file named ``example.org.pem`` in the specified
+directory and uses this as the client cert.
+
+
+
+.. _Certificate Pinning: https://security.stackexchange.com/questions/29988/what-is-certificate-pinning/

docs/conf.py

@@ -0,0 +1,243 @@
+import importlib
+import inspect
+import os
+import subprocess
+import sys
+
+sys.path.insert(0, os.path.abspath('..'))
+from mitmproxy import version as mversion
+
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.doctest',
+    'sphinx.ext.extlinks',
+    'sphinx.ext.linkcode',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.napoleon',
+    'sphinxcontrib.documentedlist'
+]
+
+# https://github.com/sphinx-doc/sphinx/pull/2053
+napoleon_include_special_with_doc = False
+
+autodoc_member_order = "bysource"
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'mitmproxy docs'
+copyright = u'2016, the mitmproxy project'
+author = u'The mitmproxy project'
+
+# 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.
+version = mversion.VERSION
+# The full version, including alpha/beta/rc tags.
+release = mversion.VERSION
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build']
+
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+modindex_common_prefix = ['mitmproxy.']
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+#keep_warnings = False
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'sphinx_rtd_theme'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+html_theme_options = {
+    'logo_only': True,
+}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+html_title = "mitmproxy %s documentation" % version
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+html_logo = "mitmproxy-docs.png"
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+html_favicon = "favicon.ico"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+#html_extra_path = []
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+html_show_sourcelink = False
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Language to be used for generating the HTML full-text search index.
+# Sphinx supports the following languages:
+#   'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
+#   'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr'
+#html_search_language = 'en'
+
+# A dictionary with options for the search language support, empty by default.
+# Now only 'ja' uses this config value
+#html_search_options = {'type': 'default'}
+
+# The name of a javascript file (relative to the configuration directory) that
+# implements a search results scorer. If empty, the default will be used.
+#html_search_scorer = 'scorer.js'
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'mitmproxydoc'
+
+last_tag, tag_dist, commit = (
+    subprocess.check_output(["git", "describe", "--tags", "--long"])
+        .decode()
+        .strip()
+        .rsplit("-", 2)
+)
+tag_dist = int(tag_dist)
+if tag_dist == 0:
+    tag = last_tag
+else:
+    tag = "master"
+
+SRCBASE = "https://github.com/mitmproxy/mitmproxy/blob/{}".format(tag)
+
+extlinks = dict(
+    src = (SRCBASE + r"/%s", '')
+)
+
+
+def linkcode_resolve(domain, info):
+    if domain != 'py':
+        return None
+    module, fullname = info['module'], info['fullname']
+    if not module:
+        return None
+    obj = importlib.import_module(module)
+    for item in fullname.split('.'):
+        obj = getattr(obj, item, None)
+    if obj is None:
+        return None
+    try:
+        spath = inspect.getsourcefile(obj)
+        _, line = inspect.getsourcelines(obj)
+    except (TypeError, IOError):
+        return None
+    if spath.rfind("mitmproxy") > -1:
+        off = spath.rfind("mitmproxy")
+        mpath = spath[off:]
+    else:
+        return None
+    return SRCBASE + "/%s#L%s" % (mpath, line)
+
+
+def setup(app):
+    app.add_stylesheet('theme_overrides.css')

docs/config.rst

@@ -0,0 +1,13 @@
+.. _config:
+
+Configuration
+=============
+
+Mitmproxy is configured with a YAML_ file, located at
+``~/.mitmproxy/config.yaml``. We'll have complete documentation for all
+supported options in the next release in the meantime, please consult the
+source_ for a complete list of options and types.
+
+
+.. _YAML: http://www.yaml.org/start.html
+.. _source: https://github.com/mitmproxy/mitmproxy/blob/master/mitmproxy/options.py

docs/custom-routing.txt

@@ -0,0 +1,24 @@
+# Adapted from http://tldp.org/HOWTO/TransparentProxy-6.html (6.2 Second method)
+# Note that the choice of firewall mark (3) and routing table (2) was fairly arbitrary.
+# If you are already using policy routing or firewall marking for some other purpose,
+# make sure you choose unique numbers here. Otherwise, don't worry about it.
+
+
+
+# On the router, run
+
+PROXY_IP=192.168.1.100
+TARGET_IP=192.168.1.110
+
+iptables -t mangle -A PREROUTING -j ACCEPT -p tcp -m multiport --dports 80,443 -s ! $TARGET_IP
+# Alternative to MITM the whole network:
+# iptables -t mangle -A PREROUTING -j ACCEPT -p tcp -m multiport --dports 80,443 -s  $PROXY_IP
+iptables -t mangle -A PREROUTING -j MARK --set-mark 3 -p tcp -m multiport --dports 80,443
+ip rule add fwmark 3 table 2
+ip route add default via $PROXY_IP dev br0 table 2
+
+
+
+# On the proxy machine, run
+
+iptables -A PREROUTING -t nat -i eth0 -p tcp -m multiport --dports 80,443 -j REDIRECT --to-port 8080

docs/dev/addingviews.html

@@ -0,0 +1,52 @@
+As discussed in [the Flow View section of the mitmproxy
+overview](@!urlTo("mitmproxy.html")!@), mitmproxy allows you to inspect and
+manipulate flows.  When inspecting a single flow, mitmproxy uses a number of
+heuristics to show a friendly view of various content types; if mitmproxy
+cannot show a friendly view, mitmproxy defaults to a __raw__ view.
+
+Each content type invokes a different flow viewer to parse the data and display
+the friendly view. Users can add custom content viewers by adding a view class
+to contentview.py, discussed below.
+
+## Adding a new View class to contentview.py
+
+The content viewers used by mitmproxy to present a friendly view of various
+content types are stored in contentview.py.  Reviewing this file shows a number
+of classes named ViewSomeDataType, each with the properties: __name__,
+__prompt__, and __content\_types__ and a function named __\_\_call\_\___.
+
+Adding a new content viewer to parse a data type is as simple as writing a new
+View class.  Your new content viewer View class should have the same properties
+as the other View classes: __name__, __prompt__, and __content\_types__ and a
+__\_\_call\_\___ function to parse the content of the request/response.
+
+* The __name__ property should be a string describing the contents and new content viewer;
+* The __prompt__ property should be a two item tuple:
+
+  - __1__: A string that will be used to display the new content viewer's type; and
+  - __2__: A one character string that will be the hotkey used to select the new content viewer from the Flow View screen;
+
+* The __content\_types__ property should be a list of strings of HTTP Content\-Types that the new content viewer can parse.
+  * Note that mitmproxy will use the content\_types to try and heuristically show a friendly view of content and that you can override the built-in views by populating content\_types with values for content\_types that are already parsed -- e.g. "image/png".
+
+After defining the __name__, __prompt__, and __content\_types__ properties of
+the class, you should write the __\_\_call\_\___ function, which will parse the
+request/response data and provide a friendly view of the data.  The
+__\_\_call\_\___ function should take the following arguments: __self__,
+__hdrs__, __content__, __limit__; __hdrs__ is a MultiDict object containing
+the headers of the request/response; __content__ is the content of the
+request/response, and __limit__ is an integer representing the amount of data
+to display in the view window.
+
+The __\_\_call\_\___ function returns two values: (1) a string describing the
+parsed data; and (2) the parsed data for friendly display.  The parsed data to
+be displayed should be a list of strings formatted for display.  You can use
+the __\_view\_text__ function in contentview.py to format text for display.
+Alternatively, you can display content as a series of key-value pairs; to do
+so, prepare a list of lists, where each list item is a two item list -- a key
+that describes the data, and then the data itself; after preparing the list of
+lists, use the __common.format\_keyvals__ function on it to prepare it as text
+for display.
+
+If the new content viewer fails or throws an exception, mitmproxy will default
+to a __raw__ view.

docs/dev/contributing.rst

@@ -0,0 +1,11 @@
+.. _contributing:
+
+Contributing
+============
+
+As an open source project, **mitmproxy** welcomes contributions of all forms. 
+
+Please head over to the README_ to get started! 😃
+
+
+.. _README: https://github.com/mitmproxy/mitmproxy/blob/master/README.rst

docs/dev/sslkeylogfile.rst

@@ -0,0 +1,15 @@
+.. _sslkeylogfile:
+
+TLS Master Secrets
+==================
+
+The SSL master keys can be logged by mitmproxy so that external programs can decrypt TLS
+connections both from and to the proxy. Key logging is enabled by setting the environment variable
+:envvar:`SSLKEYLOGFILE` so that it points to a writable text file.
+Recent versions of WireShark can use these log files to decrypt packets.
+You can specify the key file path in WireShark via
+
+:samp:`Edit -> Preferences -> Protocols -> SSL -> (Pre)-Master-Secret log filename`.
+
+Note that :envvar:`SSLKEYLOGFILE` is respected by other programs as well, e.g. Firefox and Chrome.
+If this creates any issues, you can set :envvar:`MITMPROXY_SSLKEYLOGFILE` alternatively.

docs/features/anticache.rst

@@ -0,0 +1,15 @@
+.. _anticache:
+
+Anticache
+=========
+When the ``--anticache`` option is passed to mitmproxy, it removes headers
+(``if-none-match`` and ``if-modified-since``) that might elicit a
+``304 not modified`` response from the server. This is useful when you want to make
+sure you capture an HTTP exchange in its totality. It's also often used during
+:ref:`clientreplay`, when you want to make sure the server responds with complete data.
+
+
+================== ======================
+command-line       ``--anticache``
+mitmproxy shortcut :kbd:`O` then :kbd:`a`
+================== ======================

docs/features/clientreplay.rst

@@ -0,0 +1,18 @@
+.. _clientreplay:
+
+Client-side replay
+==================
+
+Client-side replay does what it says on the tin: you provide a previously saved
+HTTP conversation, and mitmproxy replays the client requests one by one. Note
+that mitmproxy serializes the requests, waiting for a response from the server
+before starting the next request. This might differ from the recorded
+conversation, where requests may have been made concurrently.
+
+You may want to use client-side replay in conjunction with the
+:ref:`anticache` option, to make sure the server responds with complete data.
+
+================== ===========
+command-line       ``-c path``
+mitmproxy shortcut :kbd:`R` then :kbd:`c`
+================== ===========

docs/features/filters.rst

@@ -0,0 +1,38 @@
+.. _filters:
+
+Filter expressions
+==================
+
+Many commands in :program:`mitmproxy` and :program:`mitmdump` take a filter expression.
+Filter expressions consist of the following operators:
+
+.. documentedlist::
+    :header: "Expression" "Description"
+    :listobject: mitmproxy.flowfilter.help
+
+- Regexes are Python-style
+- Regexes can be specified as quoted strings
+- Header matching (~h, ~hq, ~hs) is against a string of the form "name: value".
+- Strings with no operators are matched against the request URL.
+- The default binary operator is &.
+
+Examples
+--------
+
+URL containing "google.com":
+
+.. code-block:: none
+
+    google\.com
+
+Requests whose body contains the string "test":
+
+.. code-block:: none
+
+    ~q ~b test
+
+Anything but requests with a text/html content type:
+
+.. code-block:: none
+
+    !(~q & ~t "text/html")

docs/features/passthrough.rst

@@ -0,0 +1,102 @@
+.. _passthrough:
+
+Ignore Domains
+==============
+
+There are two main reasons why you may want to exempt some traffic from mitmproxy's interception
+mechanism:
+
+- **Certificate pinning:** Some traffic is is protected using `Certificate Pinning`_ and
+  mitmproxy's interception leads to errors. For example, the Twitter app, Windows Update or
+  the Apple App Store fail to work if mitmproxy is active.
+- **Convenience:** You really don't care about some parts of the traffic and just want them to go
+  away. Note that mitmproxy's "Limit" option is often the better alternative here, as it is
+  not affected by the limitations listed below.
+
+If you want to peek into (SSL-protected) non-HTTP connections, check out the :ref:`tcpproxy`
+feature.
+If you want to ignore traffic from mitmproxy's processing because of large response bodies,
+take a look at the :ref:`responsestreaming` feature.
+
+How it works
+------------
+
+================== ======================
+command-line       ``--ignore regex``
+mitmproxy shortcut :kbd:`O` then :kbd:`I`
+================== ======================
+
+
+mitmproxy allows you to specify a regex which is matched against a ``host:port`` string
+(e.g. "example.com:443") to determine hosts that should be excluded.
+
+Limitations
+-----------
+
+There are two important quirks to consider:
+
+- **In transparent mode, the ignore pattern is matched against the IP and ClientHello SNI host.** While we usually infer the
+  hostname from the Host header if the ``--host`` argument is passed to mitmproxy, we do not
+  have access to this information before the SSL handshake. If the client uses SNI however, then we treat the SNI host as an ignore target.
+- **In regular mode, explicit HTTP requests are never ignored.** [#explicithttp]_ The ignore pattern is
+  applied on CONNECT requests, which initiate HTTPS or clear-text WebSocket connections.
+
+Tutorial
+--------
+
+If you just want to ignore one specific domain, there's usually a bulletproof method to do so:
+
+1. Run mitmproxy or mitmdump in verbose mode (``-v``) and observe the ``host:port``
+   information in the serverconnect messages. mitmproxy will filter on these.
+2. Take the ``host:port`` string, surround it with ^ and $, escape all dots (. becomes \\.)
+   and use this as your ignore pattern:
+
+.. code-block:: none
+    :emphasize-lines: 6,7,9
+
+    >>> mitmdump -v
+    127.0.0.1:50588: clientconnect
+    127.0.0.1:50588: request
+      -> CONNECT example.com:443 HTTP/1.1
+    127.0.0.1:50588: Set new server address: example.com:443
+    127.0.0.1:50588: serverconnect
+      -> example.com:443
+    ^C
+    >>> mitmproxy --ignore ^example\.com:443$
+
+
+Here are some other examples for ignore patterns:
+
+.. code-block:: none
+
+    # Exempt traffic from the iOS App Store (the regex is lax, but usually just works):
+    --ignore apple.com:443
+    # "Correct" version without false-positives:
+    --ignore '^(.+\.)?apple\.com:443$'
+
+    # Ignore example.com, but not its subdomains:
+    --ignore '^example.com:'
+
+    # Ignore everything but example.com and mitmproxy.org:
+    --ignore '^(?!example\.com)(?!mitmproxy\.org)'
+
+    # Transparent mode:
+    --ignore 17\.178\.96\.59:443
+    # IP address range:
+    --ignore 17\.178\.\d+\.\d+:443
+
+
+.. seealso::
+
+    - :ref:`tcpproxy`
+    - :ref:`responsestreaming`
+    - mitmproxy's "Limit" feature
+
+.. rubric:: Footnotes
+
+.. [#explicithttp] This stems from an limitation of explicit HTTP proxying:
+    A single connection can be re-used for multiple target domains - a
+    ``GET http://example.com/`` request may be followed by a ``GET http://evil.com/`` request on the
+    same connection. If we start to ignore the connection after the first request,
+    we would miss the relevant second one.
+.. _Certificate Pinning: https://security.stackexchange.com/questions/29988/what-is-certificate-pinning

docs/features/proxyauth.rst

@@ -0,0 +1,17 @@
+.. _proxyauth:
+
+Proxy Authentication
+====================
+
+
+Asks the user for authentication before they are permitted to use the proxy.
+Authentication headers are stripped from the flows, so they are not passed to
+upstream servers. For now, only HTTP Basic authentication is supported. The
+proxy auth options are not compatible with the transparent, socks or reverse proxy
+mode.
+
+================== ======================
+command-line       ``--nonanonymous``,
+                   ``--singleuser USER``,
+                   ``--htpasswd PATH``
+================== ======================

docs/features/replacements.rst

@@ -0,0 +1,71 @@
+.. _replacements:
+
+Replacements
+============
+
+Mitmproxy lets you specify an arbitrary number of patterns that define text
+replacements within flows. Each pattern has 3 components: a filter that defines
+which flows a replacement applies to, a regular expression that defines what
+gets replaced, and a target value that defines what is substituted in.
+
+Replace hooks fire when either a client request or a server response is
+received. Only the matching flow component is affected: so, for example, if a
+replace hook is triggered on server response, the replacement is only run on
+the Response object leaving the Request intact. You control whether the hook
+triggers on the request, response or both using the filter pattern. If you need
+finer-grained control than this, it's simple to create a script using the
+replacement API on Flow components.
+
+Replacement hooks are extremely handy in interactive testing of applications.
+For instance you can use a replace hook to replace the text "XSS" with a
+complicated XSS exploit, and then "inject" the exploit simply by interacting
+with the application through the browser. When used with tools like Firebug and
+mitmproxy's own interception abilities, replacement hooks can be an amazingly
+flexible and powerful feature.
+
+
+On the command-line
+-------------------
+
+The replacement hook command-line options use a compact syntax to make it easy
+to specify all three components at once. The general form is as follows:
+
+.. code-block:: none
+
+    /patt/regex/replacement
+
+Here, **patt** is a mitmproxy filter expression, **regex** is a valid Python
+regular expression, and **replacement** is a string literal. The first
+character in the expression (``/`` in this case) defines what the separation
+character is. Here's an example of a valid expression that replaces "foo" with
+"bar" in all requests:
+
+.. code-block:: none
+
+    :~q:foo:bar
+
+In practice, it's pretty common for the replacement literal to be long and
+complex. For instance, it might be an XSS exploit that weighs in at hundreds or
+thousands of characters. To cope with this, there's a variation of the
+replacement hook specifier that lets you load the replacement text from a file.
+To specify a file as replacement, prefix the file path with ``@``.
+You might start **mitmdump** as follows:
+
+>>> mitmdump --replacements :~q:foo:@~/xss-exploit
+
+This will load the replacement text from the file ``~/xss-exploit``.
+
+The ``--replacements`` flag can be passed multiple times.
+
+
+Interactively
+-------------
+
+The :kbd:`R` shortcut key in the mitmproxy options menu (:kbd:`O`) lets you add and edit
+replacement hooks using a built-in editor. The context-sensitive help (:kbd:`?`) has
+complete usage information.
+
+================== =======================
+command-line       ``--replacements``
+mitmproxy shortcut :kbd:`O` then :kbd:`R`
+================== =======================

docs/features/responsestreaming.rst

@@ -0,0 +1,68 @@
+.. _responsestreaming:
+
+Response Streaming
+==================
+
+By using mitmproxy's streaming feature, response contents can be passed to the client incrementally
+before they have been fully received by the proxy. This is especially useful for large binary files
+such as videos, where buffering the whole file slows down the client's browser.
+
+By default, mitmproxy will read the entire response, perform any indicated
+manipulations on it and then send the (possibly modified) response to
+the client. In some cases this is undesirable and you may wish to "stream"
+the response back to the client. When streaming is enabled, the response is
+not buffered on the proxy but directly sent back to the client instead.
+
+On the command-line
+-------------------
+
+Streaming can be enabled on the command line for all response bodies exceeding a certain size.
+The SIZE argument understands k/m/g suffixes, e.g. 3m for 3 megabytes.
+
+================== =================
+command-line       ``--stream SIZE``
+================== =================
+
+.. warning::
+
+    When response streaming is enabled, **streamed response contents will not be
+    recorded or preserved in any way.**
+
+.. note::
+
+    When response streaming is enabled, the response body cannot be modified by the usual means.
+
+Customizing Response Streaming
+------------------------------
+
+You can also use a script to customize exactly which responses are streamed.
+
+Responses that should be tagged for streaming by setting their ``.stream``
+attribute to ``True``:
+
+.. literalinclude:: ../../examples/complex/stream.py
+   :caption: examples/complex/stream.py
+   :language: python
+
+Implementation Details
+----------------------
+
+When response streaming is enabled, portions of the code which would have otherwise performed
+changes on the response body will see an empty response body. Any modifications will be ignored.
+
+Streamed responses are usually sent in chunks of 4096 bytes. If the response is sent with a
+``Transfer-Encoding: chunked`` header, the response will be streamed one chunk at a time.
+
+Modifying streamed data
+-----------------------
+
+If the ``.stream`` attribute is callable, ``.stream`` will wrap the generator that yields all
+chunks.
+
+.. literalinclude:: ../../examples/complex/stream_modify.py
+   :caption: examples/complex/stream_modify.py
+   :language: python
+
+.. seealso::
+
+    - :ref:`passthrough`

docs/features/reverseproxy.rst

@@ -0,0 +1,43 @@
+.. _reverseproxy:
+
+Reverse Proxy
+=============
+
+In reverse proxy mode, mitmproxy accepts standard HTTP(S) requests and forwards
+them to the specified upstream server. This is in contrast to :ref:`upstreamproxy`, in which
+mitmproxy forwards HTTP(S) proxy requests to an upstream proxy server.
+
+================== ================================
+command-line       ``-R http[s]://hostname[:port]``
+================== ================================
+
+Here, **http[s]** signifies if the proxy should use TLS to connect to the server.
+mitmproxy always accepts both encrypted and unencrypted requests and transforms
+them to what the server expects.
+
+.. code-block:: none
+
+    >>> mitmdump -R https://httpbin.org -p 80
+    >>> curl http://localhost/
+    # requests will be transparently upgraded to TLS by mitmproxy
+
+    >>> mitmdump -R https://httpbin.org -p 443
+    >>> curl https://localhost/
+    # mitmproxy will use TLS on both ends.
+
+
+Host Header
+-----------
+
+In reverse proxy mode, mitmproxy automatically rewrites the Host header to match the
+upstream server. This allows mitmproxy to easily connect to existing endpoints on the
+open web (e.g. ``mitmproxy -R https://example.com``). You can disable this behaviour
+by passing ``--keep-host-header`` on the console.
+
+However, keep in mind that absolute URLs within the returned document or HTTP redirects will
+NOT be rewritten by mitmproxy. This means that if you click on a link for "http://example.com"
+in the returned web page, you will be taken directly to that URL, bypassing mitmproxy.
+
+One possible way to address this is to modify the hosts file of your OS so that "example.com"
+resolves to your proxy's IP, and then access the proxy by going directly to example.com.
+Make sure that your proxy can still resolve the original IP, or specify an IP in mitmproxy.

docs/features/serverreplay.rst

@@ -0,0 +1,52 @@
+.. _serverreplay:
+
+Server-side replay
+==================
+
+Server-side replay lets us replay server responses from a saved HTTP
+conversation.
+
+Matching requests with responses
+--------------------------------
+
+By default, :program:`mitmproxy` excludes request headers when matching incoming
+requests with responses from the replay file. This works in most circumstances,
+and makes it possible to replay server responses in situations where request
+headers would naturally vary, e.g. using a different user agent.
+The ``--rheader headername`` command-line option allows you to override
+this behaviour by specifying individual headers that should be included in matching.
+
+
+Response refreshing
+-------------------
+
+Simply replaying server responses without modification will often result in
+unexpected behaviour. For example cookie timeouts that were in the future at
+the time a conversation was recorded might be in the past at the time it is
+replayed. By default, :program:`mitmproxy` refreshes server responses before sending
+them to the client. The **date**, **expires** and **last-modified** headers are
+all updated to have the same relative time offset as they had at the time of
+recording. So, if they were in the past at the time of recording, they will be
+in the past at the time of replay, and vice versa. Cookie expiry times are
+updated in a similar way.
+
+You can turn off response refreshing using the ``--norefresh`` argument, or using
+the :kbd:`O` options shortcut within :program:`mitmproxy`.
+
+
+Replaying a session recorded in Reverse-proxy Mode
+--------------------------------------------------
+
+If you have captured the session in reverse proxy mode, in order to replay it you 
+still have to specify the server URL, otherwise you may get the error: 
+'HTTP protocol error in client request: Invalid HTTP request form (expected authority or absolute...)'.
+
+During replay, when the client's requests match previously recorded requests, then the
+respective recorded responses are simply replayed  by mitmproxy. 
+Otherwise, the unmatched requests is forwarded to the upstream server.
+If forwarding is not desired, you can use the --kill (-k) switch to prevent that.
+
+================== ===========
+command-line       ``-S path``
+mitmproxy shortcut :kbd:`R` then :kbd:`s`
+================== ===========

docs/features/setheaders.rst

@@ -0,0 +1,19 @@
+.. _setheaders:
+
+Set Headers
+===========
+
+This feature lets you specify a set of headers to be added to requests or
+responses, based on a filter pattern. You can specify these either on the
+command-line, or through an interactive editor in mitmproxy.
+
+Example: Set the **Host** header to "example.com" for all requests.
+
+.. code-block:: none
+
+    mitmdump -R http://example.com --setheader :~q:Host:example.com
+
+================== =======================
+command-line       ``--setheader PATTERN``
+mitmproxy shortcut :kbd:`O` then :kbd:`H`
+================== =======================

docs/features/socksproxy.rst

@@ -0,0 +1,10 @@
+.. _socksproxy:
+
+SOCKS Mode
+==========
+
+In this mode, mitmproxy acts as a SOCKS5 proxy server.
+
+================== ===========
+command-line       ``--socks``
+================== ===========

docs/features/sticky.rst

@@ -0,0 +1,41 @@
+.. _sticky:
+
+Sticky cookies and auth
+=======================
+
+Sticky cookies
+--------------
+
+When the sticky cookie option is set, __mitmproxy__ will add the cookie most
+recently set by the server to any cookie-less request. Consider a service that
+sets a cookie to track the session after authentication. Using sticky cookies,
+you can fire up mitmproxy, and authenticate to a service as you usually would
+using a browser. After authentication, you can request authenticated resources
+through mitmproxy as if they were unauthenticated, because mitmproxy will
+automatically add the session tracking cookie to requests. Among other things,
+this lets you script interactions with authenticated resources (using tools
+like wget or curl) without having to worry about authentication.
+
+Sticky cookies are especially powerful when used in conjunction with :ref:`clientreplay` - you can
+record the authentication process once, and simply replay it on startup every time you need
+to interact with the secured resources.
+
+================== ======================
+command-line       ``-t FILTER``
+mitmproxy shortcut :kbd:`O` then :kbd:`t`
+================== ======================
+
+
+Sticky auth
+-----------
+
+The sticky auth option is analogous to the sticky cookie option, in that HTTP
+**Authorization** headers are simply replayed to the server once they have been
+seen. This is enough to allow you to access a server resource using HTTP Basic
+authentication through the proxy. Note that :program:`mitmproxy` doesn't (yet) support
+replay of HTTP Digest authentication.
+
+================== ======================
+command-line       ``-u FILTER``
+mitmproxy shortcut :kbd:`O` then :kbd:`A`
+================== ======================

docs/features/tcpproxy.rst

@@ -0,0 +1,31 @@
+.. _tcpproxy:
+
+TCP Proxy
+=========
+
+In case mitmproxy does not handle a specific protocol, you can exempt
+hostnames from processing, so that mitmproxy acts as a generic TCP forwarder.
+This feature is closely related to the :ref:`passthrough` functionality,
+but differs in two important aspects:
+
+- The raw TCP messages are printed to the event log.
+- SSL connections will be intercepted.
+
+Please note that message interception or modification are not possible yet.
+If you are not interested in the raw TCP messages, you should use the ignore domains feature.
+
+How it works
+------------
+
+================== ======================
+command-line       ``--tcp HOST``
+mitmproxy shortcut :kbd:`O` then :kbd:`T`
+================== ======================
+
+For a detailed description how the hostname pattern works, please look at the :ref:`passthrough`
+feature.
+
+.. seealso::
+
+    - :ref:`passthrough`
+    - :ref:`responsestreaming`

docs/features/upstreamcerts.rst

@@ -0,0 +1,23 @@
+.. _upstreamcerts:
+
+Upstream Certificates
+=====================
+
+When mitmproxy receives a connection destined for an SSL-protected service, it
+freezes the connection before reading its request data, and makes a connection
+to the upstream server to "sniff" the contents of its SSL certificate. The
+information gained - the **Common Name** and **Subject Alternative Names** - is
+then used to generate the interception certificate, which is sent to the client
+so the connection can continue.
+
+This rather intricate little dance lets us seamlessly generate correct
+certificates even if the client has specified only an IP address rather than the
+hostname. It also means that we don't need to sniff additional data to generate
+certs in transparent mode.
+
+Upstream cert sniffing is on by default, and can optionally be turned off.
+
+================== ======================
+command-line       ``--no-upstream-cert``
+mitmproxy shortcut :kbd:`O` then :kbd:`U`
+================== ======================

docs/features/upstreamproxy.rst

@@ -0,0 +1,12 @@
+.. _upstreamproxy:
+
+Upstream proxy mode
+===================
+
+In this mode, mitmproxy accepts proxy requests and unconditionally forwards all
+requests to a specified upstream proxy server. This is in contrast to :ref:`reverseproxy`,
+in which mitmproxy forwards ordinary HTTP requests to an upstream server.
+
+================== =============================
+command-line       ``-U http://hostname[:port]``
+================== =============================

docs/howmitmproxy.rst

@@ -0,0 +1,240 @@
+How mitmproxy works
+===================
+
+Mitmproxy is an enormously flexible tool. Knowing exactly how the proxying
+process works will help you deploy it creatively, and take into account its
+fundamental assumptions and how to work around them. This document explains
+mitmproxy's proxy mechanism in detail, starting with the simplest unencrypted
+explicit proxying, and working up to the most complicated interaction -
+transparent proxying of TLS-protected traffic [#tls]_ in the presence of `Server
+Name Indication`_.
+
+Explicit HTTP
+-------------
+
+Configuring the client to use mitmproxy as an explicit proxy is the simplest and
+most reliable way to intercept traffic. The proxy protocol is codified in the
+`HTTP RFC`_, so the behaviour of both the client and the server is well defined,
+and usually reliable. In the simplest possible interaction with mitmproxy, a
+client connects directly to the proxy, and makes a request that looks like this:
+
+.. code-block:: none
+
+    GET http://example.com/index.html HTTP/1.1
+
+This is a proxy GET request - an extended form of the vanilla HTTP GET request
+that includes a schema and host specification, and it includes all the
+information mitmproxy needs to proceed.
+
+.. image:: schematics/how-mitmproxy-works-explicit.png
+    :align: center
+
+1. The client connects to the proxy and makes a request.
+2. Mitmproxy connects to the upstream server and simply forwards the request on.
+
+
+Explicit HTTPS
+--------------
+
+The process for an explicitly proxied HTTPS connection is quite different. The
+client connects to the proxy and makes a request that looks like this:
+
+.. code-block:: none
+
+    CONNECT example.com:443 HTTP/1.1
+
+A conventional proxy can neither view nor manipulate a TLS-encrypted data
+stream, so a CONNECT request simply asks the proxy to open a pipe between the
+client and server. The proxy here is just a facilitator - it blindly forwards
+data in both directions without knowing anything about the contents. The
+negotiation of the TLS connection happens over this pipe, and the subsequent
+flow of requests and responses are completely opaque to the proxy.
+
+The MITM in mitmproxy
+^^^^^^^^^^^^^^^^^^^^^
+
+This is where mitmproxy's fundamental trick comes into play. The MITM in its
+name stands for Man-In-The-Middle - a reference to the process we use to
+intercept and interfere with these theoretically opaque data streams. The basic
+idea is to pretend to be the server to the client, and pretend to be the client
+to the server, while we sit in the middle decoding traffic from both sides. The
+tricky part is that the `Certificate Authority`_ system is designed to prevent
+exactly this attack, by allowing a trusted third-party to cryptographically sign
+a server's certificates to verify that they are legit. If this signature doesn't
+match or is from a non-trusted party, a secure client will simply drop the
+connection and refuse to proceed. Despite the many shortcomings of the CA system
+as it exists today, this is usually fatal to attempts to MITM a TLS connection
+for analysis. Our answer to this conundrum is to become a trusted Certificate
+Authority ourselves. Mitmproxy includes a full CA implementation that generates
+interception certificates on the fly. To get the client to trust these
+certificates, we :ref:`register mitmproxy as a trusted CA with the device
+manually <certinstall>`.
+
+Complication 1: What's the remote hostname?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To proceed with this plan, we need to know the domain name to use in the
+interception certificate - the client will verify that the certificate is for
+the domain it's connecting to, and abort if this is not the case. At first
+blush, it seems that the CONNECT request above gives us all we need - in this
+example, both of these values are "example.com".  But what if the client had
+initiated the connection as follows:
+
+.. code-block:: none
+
+    CONNECT 10.1.1.1:443 HTTP/1.1
+
+Using the IP address is perfectly legitimate because it gives us enough
+information to initiate the pipe, even though it doesn't reveal the remote
+hostname.
+
+Mitmproxy has a cunning mechanism that smooths this over - :ref:`upstream
+certificate sniffing <upstreamcerts>`. As soon as we see the CONNECT request, we
+pause the client part of the conversation, and initiate a simultaneous
+connection to the server. We complete the TLS handshake with the server, and
+inspect the certificates it used. Now, we use the Common Name in the upstream
+certificates to generate the dummy certificate for the client. Voila, we have
+the correct hostname to present to the client, even if it was never specified.
+
+
+Complication 2: Subject Alternative Name
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Enter the next complication. Sometimes, the certificate Common Name is not, in
+fact, the hostname that the client is connecting to. This is because of the
+optional `Subject Alternative Name`_ field in the certificate that allows an
+arbitrary number of alternative domains to be specified. If the expected domain
+matches any of these, the client will proceed, even though the domain doesn't
+match the certificate CN. The answer here is simple: when we extract the CN from
+the upstream cert, we also extract the SANs, and add them to the generated dummy
+certificate.
+
+
+Complication 3: Server Name Indication
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+One of the big limitations of vanilla TLS is that each certificate requires its
+own IP address. This means that you couldn't do virtual hosting where multiple
+domains with independent certificates share the same IP address. In a world with
+a rapidly shrinking IPv4 address pool this is a problem, and we have a solution
+in the form of the `Server Name Indication`_ extension to the TLS protocols.
+This lets the client specify the remote server name at the start of the TLS
+handshake, which then lets the server select the right certificate to complete
+the process.
+
+SNI breaks our upstream certificate sniffing process, because when we connect
+without using SNI, we get served a default certificate that may have nothing to
+do with the certificate expected by the client. The solution is another tricky
+complication to the client connection process. After the client connects, we
+allow the TLS handshake to continue until just **after** the SNI value has been
+passed to us. Now we can pause the conversation, and initiate an upstream
+connection using the correct SNI value, which then serves us the correct
+upstream certificate, from which we can extract the expected CN and SANs.
+
+Putting it all together
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Lets put all of this together into the complete explicitly proxied HTTPS flow.
+
+.. image:: schematics/how-mitmproxy-works-explicit-https.png
+    :align: center
+
+1. The client makes a connection to mitmproxy, and issues an HTTP CONNECT request.
+2. Mitmproxy responds with a ``200 Connection Established``, as if it has set up the CONNECT pipe.
+3. The client believes it's talking to the remote server, and initiates the TLS connection.
+   It uses SNI to indicate the hostname it is connecting to.
+4. Mitmproxy connects to the server, and establishes a TLS connection using the SNI hostname
+   indicated by the client.
+5. The server responds with the matching certificate, which contains the CN and SAN values
+   needed to generate the interception certificate.
+6. Mitmproxy generates the interception cert, and continues the
+   client TLS handshake paused in step 3.
+7. The client sends the request over the established TLS connection.
+8. Mitmproxy passes the request on to the server over the TLS connection initiated in step 4.
+
+Transparent HTTP
+----------------
+
+When a transparent proxy is used, the connection is redirected into a proxy at
+the network layer, without any client configuration being required. This makes
+transparent proxying ideal for those situations where you can't change client
+behaviour - proxy-oblivious Android applications being a common example.
+
+To achieve this, we need to introduce two extra components. The first is a
+redirection mechanism that transparently reroutes a TCP connection destined for
+a server on the Internet to a listening proxy server. This usually takes the
+form of a firewall on the same host as the proxy server - `iptables`_ on Linux
+or pf_ on OSX. Once the client has initiated the connection, it makes a vanilla
+HTTP request, which might look something like this:
+
+.. code-block:: none
+
+    GET /index.html HTTP/1.1
+
+Note that this request differs from the explicit proxy variation, in that it
+omits the scheme and hostname. How, then, do we know which upstream host to
+forward the request to? The routing mechanism that has performed the redirection
+keeps track of the original destination for us.  Each routing mechanism has a
+different way of exposing this data, so this introduces the second component
+required for working transparent proxying: a host module that knows how to
+retrieve the original destination address from the router. In mitmproxy, this
+takes the form of a built-in set of modules_ that know how to talk to each
+platform's redirection mechanism. Once we have this information, the process is
+fairly straight-forward.
+
+.. image:: schematics/how-mitmproxy-works-transparent.png
+    :align: center
+
+1. The client makes a connection to the server.
+2. The router redirects the connection to mitmproxy, which is typically
+   listening on a local port of the same host. Mitmproxy then consults the
+   routing mechanism to establish what the original destination was.
+3. Now, we simply read the client's request...
+4. ... and forward it upstream.
+
+Transparent HTTPS
+-----------------
+
+The first step is to determine whether we should treat an incoming connection as
+HTTPS. The mechanism for doing this is simple - we use the routing mechanism to
+find out what the original destination port is. All incoming connections pass
+through different layers which can determin the actual protocol to use.
+Automatic TLS detection works for SSLv3, TLS 1.0, TLS 1.1, and TLS 1.2 by
+looking for a *ClientHello* message at the beginning of each connection. This
+works independently of the used TCP port.
+
+From here, the process is a merger of the methods we've described for
+transparently proxying HTTP, and explicitly proxying HTTPS. We use the routing
+mechanism to establish the upstream server address, and then proceed as for
+explicit HTTPS connections to establish the CN and SANs, and cope with SNI.
+
+.. image:: schematics/how-mitmproxy-works-transparent-https.png
+    :align: center
+
+1. The client makes a connection to the server.
+2. The router redirects the connection to mitmproxy, which is typically listening on a local port
+   of the same host. Mitmproxy then consults the routing mechanism to establish what the original
+   destination was.
+3. The client believes it's talking to the remote server, and initiates the TLS connection.
+   It uses SNI to indicate the hostname it is connecting to.
+4. Mitmproxy connects to the server, and establishes a TLS connection using the SNI hostname
+   indicated by the client.
+5. The server responds with the matching certificate, which contains the CN and SAN values
+   needed to generate the interception certificate.
+6. Mitmproxy generates the interception cert, and continues the client TLS handshake paused in
+   step 3.
+7. The client sends the request over the established TLS connection.
+8. Mitmproxy passes the request on to the server over the TLS connection initiated in step 4.
+
+.. rubric:: Footnotes
+
+.. [#tls] The use of "TLS" refers to both SSL (outdated and insecure) and TLS
+          (1.0 and up) in the generic sense, unless otherwise specified.
+
+.. _Server Name Indication: https://en.wikipedia.org/wiki/Server_Name_Indication
+.. _HTTP RFC: https://tools.ietf.org/html/rfc7230
+.. _Certificate Authority: https://en.wikipedia.org/wiki/Certificate_authority
+.. _Subject Alternative Name: https://en.wikipedia.org/wiki/SubjectAltName
+.. _iptables: http://www.netfilter.org/
+.. _pf: https://en.wikipedia.org/wiki/PF_\(firewall\)
+.. _modules: https://github.com/mitmproxy/mitmproxy/tree/master/mitmproxy/platform

docs/index.rst

@@ -0,0 +1,91 @@
+.. include:: introduction.rst
+
+
+..  toctree::
+    :hidden:
+    :maxdepth: 1
+
+    introduction
+    install
+    certinstall
+    howmitmproxy
+    modes
+
+.. toctree::
+    :hidden:
+    :caption: Tools
+
+    mitmproxy
+    mitmdump
+    mitmweb
+    config
+
+.. toctree::
+    :hidden:
+    :caption: Features
+
+    features/anticache
+    features/filters
+    features/replacements
+    features/clientreplay
+    features/serverreplay
+    features/setheaders
+    features/passthrough
+    features/proxyauth
+    features/reverseproxy
+    features/responsestreaming
+    features/socksproxy
+    features/sticky
+    features/tcpproxy
+    features/upstreamproxy
+    features/upstreamcerts
+
+.. toctree::
+    :hidden:
+    :caption: Transparent Proxying
+
+    transparent
+    transparent/linux
+    transparent/osx
+    transparent/openbsd
+
+.. toctree::
+    :hidden:
+    :caption: Scripting
+
+    scripting/overview
+    scripting/events
+    scripting/api
+
+
+.. toctree::
+    :hidden:
+    :caption: Tutorials
+
+    tutorials/30second
+    tutorials/gamecenter
+    tutorials/transparent-dhcp
+
+
+.. toctree::
+    :hidden:
+    :caption: Pathod & Pathoc
+
+    pathod/intro
+    pathod/language
+    pathod/library
+    pathod/test
+
+
+.. toctree::
+    :hidden:
+    :caption: Development
+
+    dev/contributing
+    dev/sslkeylogfile
+
+..  Indices and tables
+    ==================
+
+    * :ref:`genindex`
+    * :ref:`modindex`

docs/install.rst

@@ -0,0 +1,166 @@
+.. _install:
+
+Installation
+============
+
+Please follow the steps for your operating system.
+
+Once installation is complete, you can run :ref:`mitmproxy`, :ref:`mitmdump` or
+:ref:`mitmweb` from a terminal.
+
+
+.. _install-macos:
+
+Installation on macOS
+---------------------
+
+You can use Homebrew to install everything:
+
+.. code:: bash
+
+    brew install mitmproxy
+
+Or you can download the pre-built binary packages from our `releases`_.
+
+
+.. _install-windows:
+
+Installation on Windows
+-----------------------
+
+The recommended way to install mitmproxy on Windows is to use the installer
+provided at `mitmproxy.org`_. After installation, you'll find shortcuts for
+:ref:`mitmweb` (the web-based interface) and :ref:`mitmdump` in the start menu.
+Both executables are  added to your PATH and can be invoked from the command
+line.
+
+.. note::
+    Mitmproxy's console interface is not supported on Windows, but you can use
+    mitmweb (the web-based interface) and mitmdump.
+
+.. _install-linux:
+
+Installation on Linux
+---------------------
+
+The recommended way to run mitmproxy on Linux is to use the pre-built binaries
+provided at `releases`_.
+
+Our pre-built binaries provide you with the latest version of mitmproxy, a
+self-contained Python 3.5 environment and a recent version of OpenSSL that
+supports HTTP/2. Of course, you can also install mitmproxy from source if you
+prefer that (see :ref:`install-advanced`).
+
+.. _install-advanced:
+
+Advanced Installation
+---------------------
+
+.. _install-docker:
+
+Docker Images
+^^^^^^^^^^^^^
+
+You can also use the official mitmproxy images from `DockerHub`_. That being
+said, our portable binaries are just as easy to install and even easier to use. 😊
+
+
+.. _install-arch:
+
+Installation on Arch Linux
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+mitmproxy has been added into the [community] repository. Use pacman to install it:
+
+>>> sudo pacman -S mitmproxy
+
+
+.. _install-source-ubuntu:
+
+Installation from Source on Ubuntu
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Ubuntu comes with Python but we need to install pip3, python3-dev and several
+libraries. This was tested on a fully patched installation of Ubuntu 16.04.
+
+.. code:: bash
+
+   sudo apt-get install python3-dev python3-pip libffi-dev libssl-dev
+   sudo pip3 install mitmproxy  # or pip3 install --user mitmproxy
+
+On older Ubuntu versions, e.g., **12.04** and **14.04**, you may need to install
+a newer version of Python. mitmproxy requires Python 3.5 or higher. Please take
+a look at pyenv_. Make sure to have an up-to-date version of pip by running
+``pip3 install -U pip``.
+
+
+.. _install-source-fedora:
+
+Installation from Source on Fedora
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Fedora comes with Python but we need to install pip3, python3-dev and several
+libraries. This was tested on a fully patched installation of Fedora 24.
+
+.. code:: bash
+
+   sudo dnf install make gcc redhat-rpm-config python3-devel python3-pip libffi-devel openssl-devel
+   sudo pip3 install mitmproxy  # or pip3 install --user mitmproxy
+
+Make sure to have an up-to-date version of pip by running ``pip3 install -U pip``.
+
+
+.. _install-source-opensuse:
+
+Installation from Source on openSUSE
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This was tested on a fully patched installation of openSUSE Tumbleweed.
+Please note that openSUSE Leap 42.2 only comes with Python 3.4.x, whereas mitmproxy requires Python 3.5 or above.
+You can check you Python version by running ``python3 --version``.
+
+.. code:: bash
+
+   sudo zypper install python3-pip python3-devel libffi-devel openssl-devel gcc-c++
+   sudo pip3 install mitmproxy
+
+
+.. _install-source-windows:
+
+Installation from Source on Windows
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. note::
+    Mitmproxy's console interface is not supported on Windows, but you can use
+    mitmweb (the web-based interface) and mitmdump.
+
+First, install the latest version of Python 3.5 or later from the `Python
+website`_. During installation, make sure to select `Add Python to PATH`.
+
+Mitmproxy has no other dependencies on Windows. You can now install mitmproxy by running
+
+.. code:: powershell
+
+    pip3 install mitmproxy
+
+
+
+.. _install-dev-version:
+
+Latest Development Version
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you would like to install mitmproxy directly from the master branch on GitHub
+or would like to get set up to contribute to the project, install the
+dependencies as you would for a regular installation from source. Then see the
+project's README_ on GitHub. You can check your system information
+by running: ``mitmproxy --version``
+
+
+.. _README: https://github.com/mitmproxy/mitmproxy/blob/master/README.rst
+.. _releases: https://github.com/mitmproxy/mitmproxy/releases
+.. _mitmproxy.org: https://mitmproxy.org/
+.. _`Python website`: https://www.python.org/downloads/windows/
+.. _pip: https://pip.pypa.io/en/latest/installing.html
+.. _pyenv: https://github.com/yyuu/pyenv
+.. _DockerHub: https://hub.docker.com/r/mitmproxy/mitmproxy/

docs/introduction.rst

@@ -0,0 +1,25 @@
+Introduction
+============
+
+**mitmproxy** is an interactive man-in-the-middle proxy for HTTP and HTTPS
+with a console interface.
+
+**mitmdump** is the command-line version of mitmproxy. Think tcpdump for HTTP.
+
+**mitmweb** is a web-based interface for mitmproxy.
+
+Documentation, tutorials and distribution packages can be found on the
+mitmproxy website: `mitmproxy.org <https://mitmproxy.org/>`_
+
+
+.. rubric:: Features
+
+- Intercept HTTP & HTTPS requests and responses and modify them on the fly
+- Save complete HTTP conversations for later replay and analysis
+- Replay the client-side of an HTTP conversations
+- Replay HTTP responses of a previously recorded server
+- Reverse proxy mode to forward traffic to a specified server
+- Transparent proxy mode on OSX and Linux
+- Make scripted changes to HTTP traffic using Python
+- SSL/TLS certificates for interception are generated on the fly
+- And much, much more...

docs/mitmdump.rst

@@ -0,0 +1,66 @@
+.. _mitmdump:
+.. program:: mitmdump
+
+mitmdump
+========
+
+
+**mitmdump** is the command-line companion to mitmproxy. It provides
+tcpdump-like functionality to let you view, record, and programmatically
+transform HTTP traffic. See the ``--help`` flag output for complete
+documentation.
+
+
+
+Examples
+--------
+
+Saving traffic
+^^^^^^^^^^^^^^
+
+>>> mitmdump -w outfile
+
+Start up mitmdump in proxy mode, and write all traffic to **outfile**. 
+
+
+Filtering saved traffic
+^^^^^^^^^^^^^^^^^^^^^^^
+
+>>> mitmdump -nr infile -w outfile "~m post"
+
+Start mitmdump without binding to the proxy port (``-n``), read all flows from
+infile, apply the specified filter expression (only match POSTs), and write to
+outfile.
+
+
+Client replay
+^^^^^^^^^^^^^
+
+>>> mitmdump -nc outfile
+
+Start mitmdump without binding to the proxy port (``-n``), then replay all
+requests from outfile (``-c filename``). Flags combine in the obvious way, so
+you can replay requests from one file, and write the resulting flows to
+another:
+
+>>> mitmdump -nc srcfile -w dstfile
+
+See the :ref:`clientreplay` section for more information.
+
+
+Running a script
+^^^^^^^^^^^^^^^^
+
+>>> mitmdump -s examples/add_header.py
+
+This runs the **add_header.py** example script, which simply adds a new header
+to all responses.
+
+Scripted data transformation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+>>> mitmdump -ns examples/add_header.py -r srcfile -w dstfile
+
+This command loads flows from **srcfile**, transforms it according to the
+specified script, then writes it back to **dstfile**.
+

docs/mitmproxy.rst

@@ -0,0 +1,125 @@
+.. _mitmproxy:
+.. program:: mitmproxy
+
+mitmproxy
+=========
+
+**mitmproxy** is a console tool that allows interactive examination and
+modification of HTTP traffic. It differs from mitmdump in that all flows are
+kept in memory, which means that it's intended for taking and manipulating
+small-ish samples. Use the :kbd:`?` shortcut key to view, context-sensitive
+documentation from any **mitmproxy** screen.
+
+Flow list
+---------
+
+The flow list shows an index of captured flows in chronological order.
+
+.. image:: screenshots/mitmproxy.png
+
+- **1**: A GET request, returning a 302 Redirect response.
+- **2**: A GET request, returning 16.75kb of text/html data.
+- **3**: A replayed request.
+- **4**: Intercepted flows are indicated with orange text. The user may edit
+  these flows, and then accept them (using the :kbd:`a` key) to continue. In this
+  case, the request has been intercepted on the way to the server.
+- **5**: A response intercepted from the server on the way to the client.
+- **6**: The event log can be toggled on and off using the :kbd:`e` shortcut key. This
+  pane shows events and errors that may not result in a flow that shows up in the
+  flow pane.
+- **7**: Flow count.
+- **8**: Various information on mitmproxy's state. In this case, we have an
+  interception pattern set to ``.*``.
+- **9**: Bind address indicator - mitmproxy is listening on port 8080 of all
+  interfaces.
+
+
+Flow view
+---------
+
+The **Flow View** lets you inspect and manipulate a single flow:
+
+.. image:: screenshots/mitmproxy-flowview.png
+
+- **1**: Flow summary.
+- **2**: The Request/Response tabs, showing you which part of the flow you are
+  currently viewing. In the example above, we're viewing the Response. Hit :kbd:`tab`
+  to switch between the Response and the Request.
+- **3**: Headers.
+- **4**: Body.
+- **5**: View Mode indicator. In this case, we're viewing the body in **hex** mode. The other
+  available modes are **pretty**, which uses a number of heuristics to show you a friendly
+  view of various content types, and **raw**, which shows you exactly what's there without any
+  changes. You can change modes using the :kbd:`m` key.
+
+
+Grid Editor
+-----------
+
+Much of the data that we'd like to interact with in mitmproxy is structured.
+For instance, headers, queries and form data can all be thought of as a list of
+key/value pairs. Mitmproxy has a built-in editor that lays this type of data
+out in a grid for easy manipulation.
+
+At the moment, the Grid Editor is used in four parts of mitmproxy:
+
+  - Editing request or response headers (:kbd:`e` for edit, then :kbd:`h` for headers in flow view)
+  - Editing a query string (:kbd:`e` for edit, then :kbd:`q` for query in flow view)
+  - Editing a URL-encoded form (:kbd:`e` for edit, then :kbd:`f` for form in flow view)
+  - Editing replacement patterns (:kbd:`O` for options, then :kbd:`R` for Replacement Patterns)
+
+If there is is no data, an empty editor will be started to let you add some.
+Here is the editor showing the headers from a request:
+
+.. image:: screenshots/mitmproxy-kveditor.png
+
+To edit, navigate to the key or value you want to modify using the arrow or vi
+navigation keys, and press enter. The background color will change to show that
+you are in edit mode for the specified field:
+
+.. image:: screenshots/mitmproxy-kveditor-editmode.png
+
+Modify the field as desired, then press escape to exit edit mode when you're
+done. You can also add a row (:kbd:`a` key), delete a row (:kbd:`d` key), spawn an
+external editor on a field (:kbd:`e` key). Be sure to consult the context-sensitive
+help (:kbd:`?` key) for more.
+
+Example: Interception
+---------------------
+
+**mitmproxy**'s interception functionality lets you pause an HTTP request or
+response, inspect and modify it, and then accept it to send it on to the server
+or client.
+
+
+1: Set an interception pattern
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. image:: screenshots/mitmproxy-intercept-filt.png
+
+We press :kbd:`i` to set an interception pattern. In this case, the ``~q`` filter
+pattern tells **mitmproxy** to intercept all requests. For complete filter
+syntax, see the :ref:`filters` section of the documentation,
+or the built-in help function in **mitmproxy**.
+
+2: Intercepted connections are indicated with orange text:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. image:: screenshots/mitmproxy-intercept-mid.png
+
+3: You can now view and modify the request:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. image:: screenshots/mitmproxy-intercept-options.png
+
+In this case, we viewed the request by selecting it, pressed :kbd:`e` for "edit"
+and :kbd:`m` for "method" to change the HTTP request method.
+
+4: Accept the intercept to continue:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. image:: screenshots/mitmproxy-intercept-result.png
+
+Finally, we press :kbd:`a` to accept the modified request, which is then sent on to
+the server. In this case, we changed the request from an HTTP GET to
+OPTIONS, and Google's server has responded with a 405 "Method not allowed".

docs/mitmweb.rst

@@ -0,0 +1,18 @@
+.. _mitmweb:
+.. program:: mitmweb
+
+mitmweb
+=======
+
+**mitmweb** is mitmproxy's web-based user interface that allows interactive
+examination and modification of HTTP traffic. Like mitmproxy, it differs from
+mitmdump in that all flows are kept in memory, which means that it's intended
+for taking and manipulating small-ish samples.
+
+.. warning::
+
+  Mitmweb is currently in beta. We consider it stable for all features currently
+  exposed in the UI, but it still misses a lot of mitmproxy's features.
+
+
+.. image:: screenshots/mitmweb.png

docs/modd.conf

@@ -0,0 +1,6 @@
+@build = ./_build
+
+** !_build/** ../mitmproxy/**/*.py {
+    prep: sphinx-build -W -d @build/doctrees -b html . @build/html
+    daemon: devd -m @build/html
+}

docs/modes.rst

@@ -0,0 +1,193 @@
+.. _modes:
+
+Modes of Operation
+==================
+
+Mitmproxy has four modes of operation that allow you to use mitmproxy in a
+variety of scenarios:
+
+- **Regular** (the default)
+- **Transparent**
+- **Reverse Proxy**
+- **Upstream Proxy**
+
+
+Now, which one should you pick? Use this flow chart:
+
+.. image:: schematics/proxy-modes-flowchart.png
+    :align: center
+
+Regular Proxy
+-------------
+
+Mitmproxy's regular mode is the simplest and the easiest to set up.
+
+1. Start mitmproxy.
+2. Configure your client to use mitmproxy by explicitly setting an HTTP proxy.
+3. Quick Check: You should already be able to visit an unencrypted HTTP site through the proxy.
+4. Open the magic domain **mitm.it** and install the certificate for your device.
+
+.. note::
+    Unfortunately, some applications bypass the system HTTP proxy settings - Android applications
+    are a common example. In these cases, you need to use mitmproxy's transparent mode.
+
+If you are proxying an external device, your network will probably look like this:
+
+.. image:: schematics/proxy-modes-regular.png
+    :align: center
+
+The square brackets signify the source and destination IP addresses. Your
+client explicitly connects to mitmproxy and mitmproxy explicitly connects
+to the target server.
+
+Transparent Proxy
+-----------------
+
+In transparent mode, traffic is directed into a proxy at the network layer,
+without any client configuration required. This makes transparent proxying
+ideal for situations where you can't change client behaviour. In the graphic
+below, a machine running mitmproxy has been inserted between the router and
+the internet:
+
+.. image:: schematics/proxy-modes-transparent-1.png
+    :align: center
+
+The square brackets signify the source and destination IP addresses. Round
+brackets mark the next hop on the *Ethernet/data link* layer. This distinction
+is important: when the packet arrives at the mitmproxy machine, it must still
+be addressed to the target server. This means that Network Address Translation
+should not be applied before the traffic reaches mitmproxy, since this would
+remove the target information, leaving mitmproxy unable to determine the real
+destination.
+
+.. image:: schematics/proxy-modes-transparent-wrong.png
+    :align: center
+
+Common Configurations
+^^^^^^^^^^^^^^^^^^^^^
+
+There are many ways to configure your network for transparent proxying. We'll
+look at two common scenarios:
+
+1. Configuring the client to use a custom gateway/router/"next hop"
+2. Implementing custom routing on the router
+
+In most cases, the first option is recommended due to its ease of use.
+
+(a) Custom Gateway
+~~~~~~~~~~~~~~~~~~
+
+One simple way to get traffic to the mitmproxy machine with the destination IP
+intact, is to simply configure the client with the mitmproxy box as the
+default gateway.
+
+.. image:: schematics/proxy-modes-transparent-2.png
+    :align: center
+
+In this scenario, we would:
+
+1. Configure the proxy machine for transparent mode. You can find instructions
+   in the :ref:`transparent` section.
+2. Configure the client to use the proxy machine's IP as the default gateway.
+3. Quick Check: At this point, you should already be able to visit an
+   unencrypted HTTP site over the proxy.
+4. Open the magic domain **mitm.it** and install the certificate
+   for your device.
+
+Setting the custom gateway on clients can be automated by serving the settings
+out to clients over DHCP. This lets set up an interception network where all
+clients are proxied automatically, which can save time and effort.
+
+.. admonition:: Troubleshooting Transparent Mode
+    :class: note
+
+    Incorrect transparent mode configurations are a frequent source of
+    error. If it doesn't work for you, try the following things:
+
+    - Open mitmproxy's event log (press :kbd:`e`) - do you see clientconnect messages?
+      If not, the packets are not arriving at the proxy. One common cause is the occurrence of ICMP
+      redirects, which means that your machine is telling the client that there's a faster way to
+      the internet by contacting your router directly (see the :ref:`transparent` section on how to
+      disable them). If in doubt, Wireshark_ may help you to see whether something arrives at your
+      machine or not.
+    - Make sure you have not explicitly configured an HTTP proxy on the client.
+      This is not needed in transparent mode.
+    - Re-check the instructions in the :ref:`transparent` section. Anything you missed?
+
+    If you encounter any other pitfalls that should be listed here, please let us know!
+
+(b) Custom Routing
+~~~~~~~~~~~~~~~~~~
+
+In some cases, you may need more fine-grained control of which traffic reaches
+the mitmproxy instance, and which doesn't. You may, for instance, choose only
+to divert traffic to some hosts into the transparent proxy. There are a huge
+number of ways to accomplish this, and much will depend on the router or
+packet filter you're using. In most cases, the configuration will look like
+this:
+
+.. image:: schematics/proxy-modes-transparent-3.png
+    :align: center
+
+
+Reverse Proxy
+-------------
+
+mitmproxy is usually used with a client that uses the proxy to access the
+Internet. Using reverse proxy mode, you can use mitmproxy to act like a normal
+HTTP server:
+
+.. image:: schematics/proxy-modes-reverse.png
+    :align: center
+
+There are various use-cases:
+
+- Say you have an internal API running at http://example.local/. You could now
+  set up mitmproxy in reverse proxy mode at http://debug.example.local/ and
+  dynamically point clients to this new API endpoint, which provides them
+  with the same data and you with debug information. Similarly, you could move
+  your real server to a different IP/port and set up mitmproxy in the original
+  place to debug and or redirect all sessions.
+
+- Say you're a web developer working on http://example.com/ (with a development
+  version running on http://localhost:8000/). You can modify your hosts file so that
+  example.com points to 127.0.0.1 and then run mitmproxy in reverse proxy mode
+  on port 80. You can test your app on the example.com domain and get all
+  requests recorded in mitmproxy.
+
+- Say you have some toy project that should get SSL support. Simply set up
+  mitmproxy as a reverse proxy on port 443 and you're done (``mitmdump -p 443 -R
+  http://localhost:80/``). Mitmproxy auto-detects TLS traffic and intercepts it dynamically.
+  There are better tools for this specific task, but mitmproxy is very quick and simple way to
+  set up an SSL-speaking server.
+
+- Want to add a non-SSL-capable compression proxy in front of your server? You
+  could even spawn a mitmproxy instance that terminates SSL (``-R http://...``),
+  point it to the compression proxy and let the compression proxy point to a
+  SSL-initiating mitmproxy (``-R https://...``), which then points to the real
+  server. As you see, it's a fairly flexible thing.
+
+.. admonition:: Caveat: Interactive Use
+    :class: warning
+
+    Reverse Proxy mode is usually not sufficient to create a copy of an interactive website at
+    different URL. The HTML served to the client remains unchanged - as soon as the user clicks on
+    an non-relative URL (or downloads a non-relative image resource), traffic no longer passes
+    through mitmproxy.
+
+Upstream Proxy
+--------------
+
+If you want to chain proxies by adding mitmproxy in front of a different proxy
+appliance, you can use mitmproxy's upstream mode. In upstream mode, all
+requests are unconditionally transferred to an upstream proxy of your choice.
+
+.. image:: schematics/proxy-modes-upstream.png
+    :align: center
+
+mitmproxy supports both explicit HTTP and explicit HTTPS in upstream proxy
+mode. You could in theory chain multiple mitmproxy instances in a row, but
+that doesn't make any sense in practice (i.e. outside of our tests).
+
+
+.. _Wireshark: https://wireshark.org/

docs/pathod/intro.rst

@@ -0,0 +1,307 @@
+.. _intro:
+
+Pathology 101
+=============
+
+
+pathod
+------
+
+Pathod is a pathological HTTP daemon designed to let you craft almost any
+conceivable HTTP response, including ones that creatively violate the
+standards. HTTP responses are specified using a :ref:`small, terse language
+<language>` which pathod shares with its evil twin :ref:`pathoc`. To start
+playing with pathod, fire up the daemon:
+
+>>> pathod
+
+By default, the service listens on port 9999 of localhost, and the default
+crafting anchor point is the path **/p/**. Anything after this URL prefix is
+treated as a response specifier. So, hitting the following URL will generate an
+HTTP 200 response with 100 bytes of random data:
+
+    http://localhost:9999/p/200:b@100
+
+See the :ref:`language documentation <language>` to get (much) fancier. The
+pathod daemon also takes a range of configuration options. To view those, use
+the command-line help:
+
+>>> pathod --help
+
+Mimicing a proxy
+^^^^^^^^^^^^^^^^
+
+Pathod automatically responds to both straight HTTP and proxy requests. For
+proxy requests, the upstream host is ignored, and the path portion of the URL
+is used to match anchors. This lets you test software that supports a proxy
+configuration by spoofing responses from upstream servers.
+
+By default, we treat all proxy CONNECT requests as HTTPS traffic, serving the
+response using either pathod's built-in certificates, or the cert/key pair
+specified by the user. You can over-ride this behaviour if you're testing a
+client that makes a non-SSL CONNECT request using the **-C** command-line
+option.
+
+Anchors
+^^^^^^^
+
+Anchors provide an alternative to specifying the response in the URL. Instead,
+you attach a response to a pre-configured anchor point, specified with a regex.
+When a URL matching the regex is requested, the specified response is served.
+
+>>> pathod -a "/foo=200"
+
+Here, "/foo" is the regex specifying the anchor path, and the part after the "="
+is a response specifier.
+
+
+File Access
+^^^^^^^^^^^
+
+There are two operators in the :ref:`language <language>` that load contents
+from file - the **+** operator to load an entire request specification from
+file, and the **>** value specifier. In pathod, both of these operators are
+restricted to a directory specified at startup, or disabled if no directory is
+specified:
+
+>>> pathod -d ~/staticdir"
+
+
+Internal Error Responses
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Pathod uses the non-standard 800 response code to indicate internal errors, to
+distinguish them from crafted responses. For example, a request to:
+
+    http://localhost:9999/p/foo
+
+... will return an 800 response because "foo" is not a valid page specifier.
+
+
+
+
+
+.. _pathoc:
+
+
+pathoc
+------
+
+Pathoc is a perverse HTTP daemon designed to let you craft almost any
+conceivable HTTP request, including ones that creatively violate the standards.
+HTTP requests are specified using a :ref:`small, terse language <language>`,
+which pathod shares with its server-side twin pathod. To view pathoc's complete
+range of options, use the command-line help:
+
+>>> pathoc --help
+
+
+Getting Started
+^^^^^^^^^^^^^^^
+
+The basic pattern for pathoc commands is as follows:
+
+    pathoc hostname request [request ...]
+
+That is, we specify the hostname to connect to, followed by one or more
+requests. Lets start with a simple example::
+
+    > pathoc google.com get:/
+    07-06-16 12:13:43: >> 'GET':/
+    << 302 Found: 261 bytes
+
+Here, we make a GET request to the path / on port 80 of google.com. Pathoc's
+output tells us that the server responded with a 302 redirection. We can tell
+pathoc to connect using SSL, in which case the default port is changed to 443
+(you can over-ride the default port with the **-p** command-line option)::
+
+    > pathoc -s www.google.com get:/
+    07-06-16 12:14:56: >> 'GET':/
+    << 302 Found: 262 bytes
+
+
+Multiple Requests
+^^^^^^^^^^^^^^^^^
+
+There are two ways to tell pathoc to issue multiple requests. The first is to specify
+them on the command-line, like so::
+
+    > pathoc google.com get:/ get:/
+    07-06-16 12:21:04: >> 'GET':/
+    << 302 Found: 261 bytes
+    07-06-16 12:21:04: >> 'GET':/
+    << 302 Found: 261 bytes
+
+In this case, pathoc issues the specified requests over the same TCP connection -
+so in the above example only one connection is made to google.com
+
+The other way to issue multiple requests is to use the **-n** flag::
+
+    > pathoc -n 2 google.com get:/
+    07-06-16 12:21:04: >> 'GET':/
+    << 302 Found: 261 bytes
+    07-06-16 12:21:04: >> 'GET':/
+    << 302 Found: 261 bytes
+
+The output is identical, but two separate TCP connections are made to the
+upstream server. These two specification styles can be combined::
+
+    pathoc -n 2 google.com get:/ get:/
+
+
+Here, two distinct TCP connections are made, with two requests issued over
+each.
+
+
+
+Basic Fuzzing
+^^^^^^^^^^^^^
+
+The combination of pathoc's powerful request specification language and a few
+of its command-line options makes for quite a powerful basic fuzzer. Here's an
+example::
+
+    pathoc -e -I 200 -t 2 -n 1000 localhost get:/:b@10:ir,@1
+
+The request specified here is a valid GET with a body consisting of 10 random bytes,
+but with 1 random byte inserted in a random place. This could be in the headers,
+in the initial request line, or in the body itself. There are a few things
+to note here:
+
+- Corrupting the request in this way will often make the server enter a state where
+  it's awaiting more input from the client. This is where the
+  **-t** option comes in, which sets a timeout that causes pathoc to
+  disconnect after two seconds.
+- The **-n** option tells pathoc to repeat the request 1000 times.
+- The **-I** option tells pathoc to ignore HTTP 200 response codes.
+  You can use this to fine-tune what pathoc considers to be an exceptional
+  condition, and therefore log-worthy.
+- The **-e** option tells pathoc to print an explanation of each logged
+  request, in the form of an expanded pathoc specification with all random
+  portions and automatic header additions resolved. This lets you precisely
+  replay a request that triggered an error.
+
+
+Interacting with Proxies
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Pathoc has a reasonably sophisticated suite of features for interacting with
+proxies. The proxy request syntax very closely mirrors that of straight HTTP,
+which means that it is possible to make proxy-style requests using pathoc
+without any additional syntax, by simply specifying a full URL instead of a
+simple path:
+
+>>> pathoc -p 8080 localhost "get:'http://google.com'"
+
+Another common use case is to use an HTTP CONNECT request to probe remote
+servers via a proxy. This is done with the **-c** command-line option, which
+allows you to specify a remote host and port pair:
+
+>>> pathoc -c google.com:80 -p 8080 localhost get:/
+
+Note that pathoc does **not** negotiate SSL without being explictly instructed
+to do so. If you're making a CONNECT request to an SSL-protected resource, you
+must also pass the **-s** flag:
+
+>>> pathoc -sc google.com:443 -p 8080 localhost get:/
+
+
+
+Embedded response specification
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+One interesting feature of the Request specification language is that you can
+embed a response specification in it, which is then added to the request path.
+Here's an example:
+
+>>> pathoc localhost:9999 "get:/p/:s'401:ir,@1'"
+
+This crafts a request that connects to the pathod server, and which then crafts
+a response that generates a 401, with one random byte embedded at a random
+point. The response specification is parsed and expanded by pathoc, so you see
+syntax errors immediately. This really becomes handy when combined with the
+**-e** flag to show the expanded request::
+
+    07-06-16 12:32:01: >> 'GET':/p/:s'401:i35,\x27\\x1b\x27:h\x27Content-Length\x27=\x270\x27:h\x27Content-Length\x27=\x270\x27':h'Host'='localhost'
+    << 401 Unauthorized: 0 bytes
+
+Note that the embedded response has been resolved *before* being sent to
+the server, so that "ir,@1" (embed a random byte at a random location) has
+become "i15,\'o\'" (embed the character "o" at offset 15). You now have a
+pathoc request specification that is precisely reproducible, even with random
+components. This feature comes in terribly handy when testing a proxy, since
+you can now drive the server response completely from the client, and have a
+complete log of reproducible requests to analyze afterwards.
+
+
+Request Examples
+----------------
+
+.. list-table::
+    :widths: 50 50
+    :header-rows: 0
+
+    * - get:/
+      - Get path /
+
+    * - get:/:b@100
+      - 100 random bytes as the body
+
+    * - get:/:h"Etag"="&;drop table browsers;"
+      - Add a header
+
+    * - get:/:u"&;drop table browsers;"
+      - Add a User-Agent header
+
+    * - get:/:b@100:dr
+      - Drop the connection randomly
+
+    * - get:/:b@100,ascii:ir,@1
+      - 100 ASCII bytes as the body, and randomly inject a random byte
+
+    * - ws:/
+      - Initiate a websocket handshake.
+
+
+Response Examples
+-----------------
+
+.. list-table::
+    :widths: 50 50
+    :header-rows: 0
+
+
+    * - 200
+      - A basic HTTP 200 response.
+
+    * - 200:r
+      - A basic HTTP 200 response with no Content-Length header. This will hang.
+
+    * - 200:da
+      - Server-side disconnect after all content has been sent.
+
+    * - 200:b\@100
+      - 100 random bytes as the body. A Content-Length header is added, so the disconnect
+        is no longer needed.
+
+    * - 200:b\@100:h"Etag"="';drop table servers;"
+      - Add a Server header
+
+    * - 200:b\@100:dr
+      - Drop the connection randomly
+
+    * - 200:b\@100,ascii:ir,@1
+      - 100 ASCII bytes as the body, and randomly inject a random byte
+
+    * - 200:b\@1k:c"text/json"
+      - 1k of random bytes, with a text/json content type
+
+    * - 200:b\@1k:p50,120
+      - 1k of random bytes, pause for 120 seconds after 50 bytes
+
+    * - 200:b\@1k:pr,f
+      - 1k of random bytes, but hang forever at a random location
+
+    * - 200:b\@100:h\@1k,ascii_letters='foo'
+      - 100 ASCII bytes as the body, randomly generated 100k header name, with the value
+        'foo'.

docs/pathod/language.rst

@@ -0,0 +1,257 @@
+.. _language:
+
+language spec
+=============
+
+************
+HTTP Request
+************
+
+    **method:path:[colon-separated list of features]**
+
+.. list-table::
+    :widths: 20 80
+    :header-rows: 0
+
+    * - method
+      - A :ref:`VALUE` specifying the HTTP method to
+        use. Standard methods do not need to be enclosed in quotes, while
+        non-standard methods can be specified as quoted strings.
+
+        The special method **ws** creates a valid websocket upgrade
+        GET request, and signals to pathoc to switch to websocket recieve
+        mode if the server responds correctly. Apart from that, websocket
+        requests are just like any other, and all aspects of the request
+        can be over-ridden.
+    * - h\ :ref:`VALUE`\ =\ :ref:`VALUE`\
+      - Set a header.
+    * - r
+      - Set the **raw** flag on this response. Pathod will not calculate a
+        *Content-Length* header if a body is set.
+    * - c\ :ref:`VALUE`
+      - A shortcut for setting the Content-Type header. Equivalent to
+        ``h"Content-Type"=VALUE``
+    * - u\ :ref:`VALUE`
+        uSHORTCUT
+      - Set a User-Agent header on this request. You can specify either a
+        complete :ref:`VALUE`, or a User-Agent shortcut: **android**,
+        **blackberry**, **bingbot**, **chrome**, **firefox**, **googlebot**,
+        **ie9**, **ipad**, **iphone**, **safari**.
+    * - b\ :ref:`VALUE`
+      - Set the body. The appropriate Content-Length header is added
+        automatically unless the **r** flag is set.
+    * - s\ :ref:`VALUE`
+      - An embedded Response specification, appended to the path of the request.
+    * - x\ :ref:`INTEGER`
+      - Repeat this message N times.
+    * - d\ :ref:`OFFSET`
+      - Disconnect after OFFSET bytes (HTTP/1 only).
+    * - i\ :ref:`OFFSET`,\ :ref:`VALUE`
+      - Inject the specified value at the offset (HTTP/1 only)
+    * - p\ :ref:`OFFSET`,SECONDS
+      - Pause for SECONDS seconds after OFFSET bytes. SECONDS can be an integer
+        or "f" to pause forever (HTTP/1 only)
+
+
+*************
+HTTP Response
+*************
+
+    **code:[colon-separated list of features]**
+
+.. list-table::
+    :widths: 20 80
+    :header-rows: 0
+
+    * - code
+      - An integer specifying the HTTP response code.
+
+        The special method **ws** creates a valid websocket upgrade
+        response (code 101), and moves pathod to websocket mode. Apart
+        from that, websocket responses are just like any other, and all
+        aspects of the response can be over-ridden.
+    * - m\ :ref:`VALUE`
+      - HTTP Reason message. Automatically chosen according to the response
+        code if not specified. (HTTP/1 only)
+    * - h\ :ref:`VALUE`\ =\ :ref:`VALUE`\
+      - Set a header.
+    * - r
+      - Set the **raw** flag on this response. Pathod will not calculate a
+        *Content-Length* header if a body is set.
+    * - l\ :ref:`VALUE`
+      - A shortcut for setting the Location header. Equivalent to
+        ``h"Location"=VALUE``
+    * - c\ :ref:`VALUE`
+      - A shortcut for setting the Content-Type header. Equivalent to
+        ``h"Content-Type"=VALUE``
+    * - b\ :ref:`VALUE`
+      - Set the body. The appropriate Content-Length header is added
+        automatically unless the **r** flag is set.
+    * - d\ :ref:`OFFSET`
+      - Disconnect after OFFSET bytes (HTTP/1 only).
+    * - i\ :ref:`OFFSET`,\ :ref:`VALUE`
+      - Inject the specified value at the offset (HTTP/1 only)
+    * - p\ :ref:`OFFSET`,SECONDS
+      - Pause for SECONDS seconds after OFFSET bytes. SECONDS can be an integer
+        or "f" to pause forever (HTTP/1 only)
+
+***************
+Websocket Frame
+***************
+
+    **wf:[colon-separated list of features]**
+
+.. list-table::
+    :widths: 20 80
+    :header-rows: 0
+
+    * - b\ :ref:`VALUE`
+      - Set the frame payload. If a masking key is present, the value is
+        encoded automatically.
+    * - c\ :ref:`INTEGER`
+      - Set the op code. This can either be an integer from 0-15, or be one of
+        the following opcode names: **text** (the default), **continue**,
+        **binary**, **close**, **ping**, **pong**.
+    * - d\ :ref:`OFFSET`
+      - Disconnect after OFFSET bytes
+    * - i\ :ref:`OFFSET`,\ :ref:`VALUE`
+      - Inject the specified value at the offset
+    * - p\ :ref:`OFFSET`,SECONDS
+      - Pause for SECONDS seconds after OFFSET bytes. SECONDS can be an integer
+        or "f" to pause forever
+    * - x\ :ref:`INTEGER`
+      - Repeat this message N times.
+    * - [-]fin
+      - Set or un-set the **fin** bit.
+    * - k\ :ref:`VALUE`
+      - Set the masking key. The resulting value must be exactly 4 bytes long.
+        The special form **knone** specifies that no key should be set, even if
+        the mask bit is on.
+    * - l\ :ref:`INTEGER`
+      - Set the payload length in the frame header, regardless of the actual
+        body length.
+    * - [-]mask
+      - Set or un-set the <b>mask</b> bit.
+    * - r\ :ref:`VALUE`
+      - Set the raw frame payload. This disables masking, even if the key is present.
+    * - [-]rsv1
+      - Set or un-set the **rsv1** bit.
+    * - [-]rsv2
+      - Set or un-set the **rsv2** bit.
+    * - [-]rsv2
+      - Set or un-set the **rsv2** bit.
+
+
+
+**********
+Data types
+**********
+
+.. _INTEGER:
+
+INTEGER
+^^^^^^^
+
+.. _OFFSET:
+
+OFFSET
+^^^^^^
+
+Offsets are calculated relative to the base message, before any injections or
+other transforms are applied. They have 3 flavors:
+
+=======                 ==========================
+integer                 An integer byte offset
+**r**                   A random location
+**a**                   The end of the message
+=======                 ==========================
+
+
+.. _VALUE:
+
+VALUE
+^^^^^
+
+Literals
+""""""""
+
+Literal values are specified as a quoted strings::
+
+    "foo"
+
+Either single or double quotes are accepted, and quotes can be escaped with
+backslashes within the string::
+
+    'fo\'o'
+
+Literal values can contain Python-style backslash escape sequences::
+
+    'foo\r\nbar'
+
+
+
+Generated
+"""""""""
+
+An @-symbol lead-in specifies that generated data should be used. There are two
+components to a generator specification - a size, and a data type. By default
+pathod assumes a data type of "bytes".
+
+Here's a value specifier for generating 100 bytes::
+
+    @100
+
+You can use standard suffixes to indicate larger values. Here, for instance, is
+a specifier for generating 100 megabytes:
+
+    @100m
+
+Data is generated and served efficiently - if you really want to send a
+terabyte of data to a client, pathod can do it. The supported suffixes are:
+
+==========          ====================
+b                   1024**0 (bytes)
+k                   1024**1 (kilobytes)
+m                   1024**2 (megabytes)
+g                   1024**3 (gigabytes)
+t                   1024**4 (terabytes)
+==========          ====================
+
+Data types are separated from the size specification by a comma. This specification
+generates 100mb of ASCII::
+
+    @100m,ascii
+
+Supported data types are:
+
+=================          ==============================================
+ascii                      All ASCII characters
+ascii_letters              A-Za-z
+ascii_lowercase            a-z
+ascii_uppercase            A-Z
+bytes                      All 256 byte values
+digits                     0-9
+hexdigits                  0-f
+octdigits                  0-7
+punctuation                !"#$%&\'()*+,-./:;<=>?@[\\]^_`{|}~ and space
+whitespace                 \\t \\n \\x0b \\x0c \\r and space
+=================          ==============================================
+
+
+
+Files
+"""""
+
+You can load a value from a specified file path. To do so, you have to specify a
+_staticdir_ option to pathod on the command-line, like so:
+
+>>> pathod -d ~/myassets
+
+All paths are relative paths under this directory. File loads are indicated by
+starting the value specifier with the left angle bracket::
+
+    <my/path
+
+The path value can also be a quoted string, with the same syntax as literals::
+
+    <"my/path"

docs/pathod/library.rst

@@ -0,0 +1,14 @@
+.. _library:
+
+pathod library
+==============
+
+Behind the pathod and pathoc command-line tools lurks the **pathod** library, a
+powerful way to manipulate and serve HTTP requests and responses from code. The
+canonical documentation for the library is in the code, and can be accessed
+using pydoc.
+
+
+.. literalinclude:: ../../examples/pathod/libpathod_pathoc.py
+   :caption: examples/pathod/libpathod_pathoc.py
+   :language: python

docs/pathod/test.rst

@@ -0,0 +1,38 @@
+.. _test:
+
+pathod.test
+===========
+
+The **pathod.test** module is a light, flexible testing layer for HTTP clients.
+It works by firing up a Pathod instance in a separate thread, letting you use
+Pathod's full abilities to generate responses, and then query Pathod's internal
+logs to establish what happened. All the mechanics of startup, shutdown, finding
+free ports and so forth are taken care of for you.
+
+The canonical docs can be accessed using pydoc:
+
+>>> pydoc pathod.test
+
+The remainder of this page demonstrates some common interaction patterns using
+`Nose`_. These examples are
+also applicable with only minor modification to most commonly used Python testing
+engines.
+
+
+Context Manager
+---------------
+
+.. literalinclude:: ../../examples/pathod/test_context.py
+   :caption: examples/pathod/test_context.py
+   :language: python
+
+
+One instance per test
+---------------------
+
+.. literalinclude:: ../../examples/pathod/test_setup.py
+   :caption: examples/pathod/test_setup.py
+   :language: python
+
+
+.. _Nose: https://nose.readthedocs.org/en/latest/

docs/schematics/_explicit.graffle/data.plist

@@ -0,0 +1,572 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>ActiveLayerIndex</key>
+	<integer>0</integer>
+	<key>ApplicationVersion</key>
+	<array>
+		<string>com.omnigroup.OmniGraffle.MacAppStore</string>
+		<string>139.16</string>
+	</array>
+	<key>AutoAdjust</key>
+	<true/>
+	<key>BackgroundGraphic</key>
+	<dict>
+		<key>Bounds</key>
+		<string>{{0, 0}, {559.19998741149902, 782.79998779296875}}</string>
+		<key>Class</key>
+		<string>SolidGraphic</string>
+		<key>ID</key>
+		<integer>2</integer>
+		<key>Style</key>
+		<dict>
+			<key>shadow</key>
+			<dict>
+				<key>Draws</key>
+				<string>NO</string>
+			</dict>
+			<key>stroke</key>
+			<dict>
+				<key>Draws</key>
+				<string>NO</string>
+			</dict>
+		</dict>
+	</dict>
+	<key>BaseZoom</key>
+	<integer>0</integer>
+	<key>CanvasOrigin</key>
+	<string>{0, 0}</string>
+	<key>ColumnAlign</key>
+	<integer>1</integer>
+	<key>ColumnSpacing</key>
+	<real>36</real>
+	<key>CreationDate</key>
+	<string>2013-01-02 19:31:53 +0000</string>
+	<key>Creator</key>
+	<string>Aldo Cortesi</string>
+	<key>DisplayScale</key>
+	<string>1.000 cm = 1.000 cm</string>
+	<key>GraphDocumentVersion</key>
+	<integer>8</integer>
+	<key>GraphicsList</key>
+	<array>
+		<dict>
+			<key>Class</key>
+			<string>LineGraphic</string>
+			<key>ID</key>
+			<integer>4074</integer>
+			<key>Points</key>
+			<array>
+				<string>{300.4483540852865, 420.70833897590637}</string>
+				<string>{344.88497416178387, 420.70833897590654}</string>
+				<string>{362.21830749511713, 420.04167230923986}</string>
+				<string>{413.55166625976557, 419.70833905537921}</string>
+			</array>
+			<key>Style</key>
+			<dict>
+				<key>stroke</key>
+				<dict>
+					<key>HeadArrow</key>
+					<string>FilledArrow</string>
+					<key>Legacy</key>
+					<true/>
+					<key>TailArrow</key>
+					<string>0</string>
+				</dict>
+			</dict>
+		</dict>
+		<dict>
+			<key>Class</key>
+			<string>LineGraphic</string>
+			<key>ID</key>
+			<integer>4070</integer>
+			<key>Points</key>
+			<array>
+				<string>{84.896692911783873, 420.66667453447985}</string>
+				<string>{129.33331298828122, 420.66667453448002}</string>
+				<string>{146.66664632161454, 420.00000786781334}</string>
+				<string>{198.00000508626297, 419.66667461395269}</string>
+			</array>
+			<key>Style</key>
+			<dict>
+				<key>stroke</key>
+				<dict>
+					<key>HeadArrow</key>
+					<string>FilledArrow</string>
+					<key>Legacy</key>
+					<true/>
+					<key>TailArrow</key>
+					<string>0</string>
+				</dict>
+			</dict>
+		</dict>
+		<dict>
+			<key>Bounds</key>
+			<string>{{326.00000000000023, 391.39999198913591}, {62, 24}}</string>
+			<key>Class</key>
+			<string>ShapedGraphic</string>
+			<key>FitText</key>
+			<string>YES</string>
+			<key>Flow</key>
+			<string>Resize</string>
+			<key>FontInfo</key>
+			<dict>
+				<key>Font</key>
+				<string>Helvetica</string>
+				<key>Size</key>
+				<real>12</real>
+			</dict>
+			<key>ID</key>
+			<integer>4063</integer>
+			<key>Shape</key>
+			<string>Rectangle</string>
+			<key>Style</key>
+			<dict>
+				<key>fill</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+				<key>shadow</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+				<key>stroke</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+			</dict>
+			<key>Text</key>
+			<dict>
+				<key>Pad</key>
+				<integer>0</integer>
+				<key>Text</key>
+				<string>{\rtf1\ansi\ansicpg1252\cocoartf1187\cocoasubrtf340
+\cocoascreenfonts1{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
+{\colortbl;\red255\green255\blue255;}
+\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\pardirnatural\qc
+
+\f0\fs20 \cf0 2: Forwarded \
+Request}</string>
+				<key>VerticalPad</key>
+				<integer>0</integer>
+			</dict>
+			<key>Wrap</key>
+			<string>NO</string>
+		</dict>
+		<dict>
+			<key>Bounds</key>
+			<string>{{110, 403.39997863769622}, {49, 12}}</string>
+			<key>Class</key>
+			<string>ShapedGraphic</string>
+			<key>FitText</key>
+			<string>YES</string>
+			<key>Flow</key>
+			<string>Resize</string>
+			<key>FontInfo</key>
+			<dict>
+				<key>Font</key>
+				<string>Helvetica</string>
+				<key>Size</key>
+				<real>12</real>
+			</dict>
+			<key>ID</key>
+			<integer>4061</integer>
+			<key>Shape</key>
+			<string>Rectangle</string>
+			<key>Style</key>
+			<dict>
+				<key>fill</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+				<key>shadow</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+				<key>stroke</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+			</dict>
+			<key>Text</key>
+			<dict>
+				<key>Pad</key>
+				<integer>0</integer>
+				<key>Text</key>
+				<string>{\rtf1\ansi\ansicpg1252\cocoartf1187\cocoasubrtf340
+\cocoascreenfonts1{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
+{\colortbl;\red255\green255\blue255;}
+\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\pardirnatural\qc
+
+\f0\fs20 \cf0 1: Request}</string>
+				<key>VerticalPad</key>
+				<integer>0</integer>
+			</dict>
+			<key>Wrap</key>
+			<string>NO</string>
+		</dict>
+		<dict>
+			<key>Bounds</key>
+			<string>{{430.83098347981803, 515.99999999999989}, {36, 14}}</string>
+			<key>Class</key>
+			<string>ShapedGraphic</string>
+			<key>FitText</key>
+			<string>YES</string>
+			<key>Flow</key>
+			<string>Resize</string>
+			<key>ID</key>
+			<integer>4026</integer>
+			<key>Shape</key>
+			<string>Rectangle</string>
+			<key>Style</key>
+			<dict>
+				<key>fill</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+				<key>shadow</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+				<key>stroke</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+			</dict>
+			<key>Text</key>
+			<dict>
+				<key>Pad</key>
+				<integer>0</integer>
+				<key>Text</key>
+				<string>{\rtf1\ansi\ansicpg1252\cocoartf1187\cocoasubrtf340
+\cocoascreenfonts1{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
+{\colortbl;\red255\green255\blue255;}
+\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\pardirnatural\qc
+
+\f0\fs24 \cf0 Server}</string>
+				<key>VerticalPad</key>
+				<integer>0</integer>
+			</dict>
+			<key>Wrap</key>
+			<string>NO</string>
+		</dict>
+		<dict>
+			<key>Bounds</key>
+			<string>{{40.499999999999993, 486.66666666666663}, {31, 14}}</string>
+			<key>Class</key>
+			<string>ShapedGraphic</string>
+			<key>FitText</key>
+			<string>YES</string>
+			<key>Flow</key>
+			<string>Resize</string>
+			<key>ID</key>
+			<integer>4025</integer>
+			<key>Shape</key>
+			<string>Rectangle</string>
+			<key>Style</key>
+			<dict>
+				<key>fill</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+				<key>shadow</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+				<key>stroke</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+			</dict>
+			<key>Text</key>
+			<dict>
+				<key>Pad</key>
+				<integer>0</integer>
+				<key>Text</key>
+				<string>{\rtf1\ansi\ansicpg1252\cocoartf1187\cocoasubrtf340
+\cocoascreenfonts1{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
+{\colortbl;\red255\green255\blue255;}
+\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\pardirnatural\qc
+
+\f0\fs24 \cf0 Client}</string>
+				<key>VerticalPad</key>
+				<integer>0</integer>
+			</dict>
+			<key>Wrap</key>
+			<string>NO</string>
+		</dict>
+		<dict>
+			<key>Bounds</key>
+			<string>{{417.16432189941418, 323.90565299479198}, {63.333332061767578, 185.52200317382812}}</string>
+			<key>Class</key>
+			<string>ShapedGraphic</string>
+			<key>ID</key>
+			<integer>4004</integer>
+			<key>ImageID</key>
+			<integer>6</integer>
+			<key>Shape</key>
+			<string>Rectangle</string>
+			<key>Style</key>
+			<dict>
+				<key>fill</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+				<key>shadow</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+				<key>stroke</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+			</dict>
+		</dict>
+		<dict>
+			<key>Bounds</key>
+			<string>{{205.34386889139773, 289.33333333333331}, {84, 248.66667175292969}}</string>
+			<key>Class</key>
+			<string>ShapedGraphic</string>
+			<key>ID</key>
+			<integer>4023</integer>
+			<key>Shape</key>
+			<string>Rectangle</string>
+			<key>Style</key>
+			<dict>
+				<key>fill</key>
+				<dict>
+					<key>Color</key>
+					<dict>
+						<key>b</key>
+						<string>0</string>
+						<key>g</key>
+						<string>0.463735</string>
+						<key>r</key>
+						<string>1</string>
+					</dict>
+				</dict>
+			</dict>
+			<key>Text</key>
+			<dict>
+				<key>Text</key>
+				<string>{\rtf1\ansi\ansicpg1252\cocoartf1187\cocoasubrtf340
+\cocoascreenfonts1{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
+{\colortbl;\red255\green255\blue255;\red37\green17\blue0;}
+\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\pardirnatural\qc
+
+\f0\fs24 \cf2 mitmproxy}</string>
+			</dict>
+		</dict>
+		<dict>
+			<key>Bounds</key>
+			<string>{{4.6666666467984399, 351.33332316080771}, {102.66666412353516, 130.66667175292969}}</string>
+			<key>Class</key>
+			<string>ShapedGraphic</string>
+			<key>ID</key>
+			<integer>134</integer>
+			<key>ImageID</key>
+			<integer>3</integer>
+			<key>Shape</key>
+			<string>Rectangle</string>
+			<key>Style</key>
+			<dict>
+				<key>fill</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+				<key>shadow</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+				<key>stroke</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+			</dict>
+		</dict>
+	</array>
+	<key>GridInfo</key>
+	<dict/>
+	<key>GuidesLocked</key>
+	<string>NO</string>
+	<key>GuidesVisible</key>
+	<string>YES</string>
+	<key>HPages</key>
+	<integer>1</integer>
+	<key>ImageCounter</key>
+	<integer>7</integer>
+	<key>ImageLinkBack</key>
+	<array>
+		<dict/>
+		<dict/>
+	</array>
+	<key>ImageList</key>
+	<array>
+		<string>image6.tiff</string>
+		<string>image3.icns</string>
+	</array>
+	<key>KeepToScale</key>
+	<false/>
+	<key>Layers</key>
+	<array>
+		<dict>
+			<key>Lock</key>
+			<string>NO</string>
+			<key>Name</key>
+			<string>Layer 1</string>
+			<key>Print</key>
+			<string>YES</string>
+			<key>View</key>
+			<string>YES</string>
+		</dict>
+	</array>
+	<key>LayoutInfo</key>
+	<dict>
+		<key>Animate</key>
+		<string>NO</string>
+		<key>circoMinDist</key>
+		<real>18</real>
+		<key>circoSeparation</key>
+		<real>0.0</real>
+		<key>layoutEngine</key>
+		<string>dot</string>
+		<key>neatoSeparation</key>
+		<real>0.0</real>
+		<key>twopiSeparation</key>
+		<real>0.0</real>
+	</dict>
+	<key>LinksVisible</key>
+	<string>NO</string>
+	<key>MagnetsVisible</key>
+	<string>NO</string>
+	<key>MasterSheets</key>
+	<array/>
+	<key>ModificationDate</key>
+	<string>2013-01-03 02:27:49 +0000</string>
+	<key>Modifier</key>
+	<string>Aldo Cortesi</string>
+	<key>NotesVisible</key>
+	<string>NO</string>
+	<key>Orientation</key>
+	<integer>2</integer>
+	<key>OriginVisible</key>
+	<string>NO</string>
+	<key>PageBreaks</key>
+	<string>YES</string>
+	<key>PrintInfo</key>
+	<dict>
+		<key>NSBottomMargin</key>
+		<array>
+			<string>float</string>
+			<string>41</string>
+		</array>
+		<key>NSHorizonalPagination</key>
+		<array>
+			<string>coded</string>
+			<string>BAtzdHJlYW10eXBlZIHoA4QBQISEhAhOU051bWJlcgCEhAdOU1ZhbHVlAISECE5TT2JqZWN0AIWEASqEhAFxlwCG</string>
+		</array>
+		<key>NSLeftMargin</key>
+		<array>
+			<string>float</string>
+			<string>18</string>
+		</array>
+		<key>NSPaperSize</key>
+		<array>
+			<string>size</string>
+			<string>{595.19998741149902, 841.79998779296875}</string>
+		</array>
+		<key>NSPrintReverseOrientation</key>
+		<array>
+			<string>int</string>
+			<string>0</string>
+		</array>
+		<key>NSRightMargin</key>
+		<array>
+			<string>float</string>
+			<string>18</string>
+		</array>
+		<key>NSTopMargin</key>
+		<array>
+			<string>float</string>
+			<string>18</string>
+		</array>
+	</dict>
+	<key>PrintOnePage</key>
+	<false/>
+	<key>ReadOnly</key>
+	<string>NO</string>
+	<key>RowAlign</key>
+	<integer>1</integer>
+	<key>RowSpacing</key>
+	<real>36</real>
+	<key>SheetTitle</key>
+	<string>Canvas 1</string>
+	<key>SmartAlignmentGuidesActive</key>
+	<string>YES</string>
+	<key>SmartDistanceGuidesActive</key>
+	<string>YES</string>
+	<key>UniqueID</key>
+	<integer>1</integer>
+	<key>UseEntirePage</key>
+	<false/>
+	<key>VPages</key>
+	<integer>1</integer>
+	<key>WindowInfo</key>
+	<dict>
+		<key>CurrentSheet</key>
+		<integer>0</integer>
+		<key>ExpandedCanvases</key>
+		<array>
+			<dict>
+				<key>name</key>
+				<string>Canvas 1</string>
+			</dict>
+		</array>
+		<key>Frame</key>
+		<string>{{300, 236}, {974, 874}}</string>
+		<key>ListView</key>
+		<true/>
+		<key>OutlineWidth</key>
+		<integer>142</integer>
+		<key>RightSidebar</key>
+		<false/>
+		<key>ShowRuler</key>
+		<true/>
+		<key>Sidebar</key>
+		<true/>
+		<key>SidebarWidth</key>
+		<integer>120</integer>
+		<key>VisibleRegion</key>
+		<string>{{0, 202}, {550, 469.33333333333337}}</string>
+		<key>Zoom</key>
+		<real>1.5</real>
+		<key>ZoomValues</key>
+		<array>
+			<array>
+				<string>Canvas 1</string>
+				<real>1.5</real>
+				<real>1</real>
+			</array>
+		</array>
+	</dict>
+</dict>
+</plist>

docs/schematics/_transparent.graffle/data.plist

@@ -0,0 +1,771 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>ActiveLayerIndex</key>
+	<integer>0</integer>
+	<key>ApplicationVersion</key>
+	<array>
+		<string>com.omnigroup.OmniGraffle.MacAppStore</string>
+		<string>139.16</string>
+	</array>
+	<key>AutoAdjust</key>
+	<true/>
+	<key>BackgroundGraphic</key>
+	<dict>
+		<key>Bounds</key>
+		<string>{{0, 0}, {559.19998741149902, 782.79998779296875}}</string>
+		<key>Class</key>
+		<string>SolidGraphic</string>
+		<key>ID</key>
+		<integer>2</integer>
+		<key>Style</key>
+		<dict>
+			<key>shadow</key>
+			<dict>
+				<key>Draws</key>
+				<string>NO</string>
+			</dict>
+			<key>stroke</key>
+			<dict>
+				<key>Draws</key>
+				<string>NO</string>
+			</dict>
+		</dict>
+	</dict>
+	<key>BaseZoom</key>
+	<integer>0</integer>
+	<key>CanvasOrigin</key>
+	<string>{0, 0}</string>
+	<key>ColumnAlign</key>
+	<integer>1</integer>
+	<key>ColumnSpacing</key>
+	<real>36</real>
+	<key>CreationDate</key>
+	<string>2013-01-02 19:31:53 +0000</string>
+	<key>Creator</key>
+	<string>Aldo Cortesi</string>
+	<key>DisplayScale</key>
+	<string>1.000 cm = 1.000 cm</string>
+	<key>GraphDocumentVersion</key>
+	<integer>8</integer>
+	<key>GraphicsList</key>
+	<array>
+		<dict>
+			<key>Bounds</key>
+			<string>{{101.18773396809897, 358.41662979125977}, {62, 12}}</string>
+			<key>Class</key>
+			<string>ShapedGraphic</string>
+			<key>FitText</key>
+			<string>YES</string>
+			<key>Flow</key>
+			<string>Resize</string>
+			<key>FontInfo</key>
+			<dict>
+				<key>Font</key>
+				<string>Helvetica</string>
+				<key>Size</key>
+				<real>12</real>
+			</dict>
+			<key>ID</key>
+			<integer>4079</integer>
+			<key>Shape</key>
+			<string>Rectangle</string>
+			<key>Style</key>
+			<dict>
+				<key>fill</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+				<key>shadow</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+				<key>stroke</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+			</dict>
+			<key>Text</key>
+			<dict>
+				<key>Pad</key>
+				<integer>0</integer>
+				<key>Text</key>
+				<string>{\rtf1\ansi\ansicpg1252\cocoartf1187\cocoasubrtf340
+\cocoascreenfonts1{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
+{\colortbl;\red255\green255\blue255;}
+\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\pardirnatural\qc
+
+\f0\fs20 \cf0 2: Redirection}</string>
+				<key>VerticalPad</key>
+				<integer>0</integer>
+			</dict>
+			<key>Wrap</key>
+			<string>NO</string>
+		</dict>
+		<dict>
+			<key>Bounds</key>
+			<string>{{102.18775939941409, 405.16666666666663}, {78, 12}}</string>
+			<key>Class</key>
+			<string>ShapedGraphic</string>
+			<key>FitText</key>
+			<string>YES</string>
+			<key>Flow</key>
+			<string>Resize</string>
+			<key>FontInfo</key>
+			<dict>
+				<key>Font</key>
+				<string>Helvetica</string>
+				<key>Size</key>
+				<real>12</real>
+			</dict>
+			<key>ID</key>
+			<integer>4078</integer>
+			<key>Shape</key>
+			<string>Rectangle</string>
+			<key>Style</key>
+			<dict>
+				<key>fill</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+				<key>shadow</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+				<key>stroke</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+			</dict>
+			<key>Text</key>
+			<dict>
+				<key>Pad</key>
+				<integer>0</integer>
+				<key>Text</key>
+				<string>{\rtf1\ansi\ansicpg1252\cocoartf1187\cocoasubrtf340
+\cocoascreenfonts1{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
+{\colortbl;\red255\green255\blue255;}
+\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\pardirnatural\qc
+
+\f0\fs20 \cf0 3: HTTP Request}</string>
+				<key>VerticalPad</key>
+				<integer>0</integer>
+			</dict>
+			<key>Wrap</key>
+			<string>NO</string>
+		</dict>
+		<dict>
+			<key>Class</key>
+			<string>LineGraphic</string>
+			<key>ControlPoints</key>
+			<array>
+				<string>{-29.333333333333343, 15.666671991348267}</string>
+				<string>{-14, -7.3333333333333712}</string>
+			</array>
+			<key>ID</key>
+			<integer>37</integer>
+			<key>Points</key>
+			<array>
+				<string>{196.99999491373691, 331.83332316080725}</string>
+				<string>{198.00000508626303, 402.49998982747394}</string>
+			</array>
+			<key>Style</key>
+			<dict>
+				<key>stroke</key>
+				<dict>
+					<key>Bezier</key>
+					<true/>
+					<key>HeadArrow</key>
+					<string>FilledArrow</string>
+					<key>Legacy</key>
+					<true/>
+					<key>LineType</key>
+					<integer>1</integer>
+					<key>TailArrow</key>
+					<string>0</string>
+				</dict>
+			</dict>
+		</dict>
+		<dict>
+			<key>Bounds</key>
+			<string>{{205.34387397766082, 289.3333333333328}, {84, 52.666667938232422}}</string>
+			<key>Class</key>
+			<string>ShapedGraphic</string>
+			<key>ID</key>
+			<integer>4076</integer>
+			<key>Shape</key>
+			<string>Rectangle</string>
+			<key>Style</key>
+			<dict>
+				<key>fill</key>
+				<dict>
+					<key>Color</key>
+					<dict>
+						<key>b</key>
+						<string>0.547829</string>
+						<key>g</key>
+						<string>1</string>
+						<key>r</key>
+						<string>0.790866</string>
+					</dict>
+				</dict>
+			</dict>
+			<key>Text</key>
+			<dict>
+				<key>Text</key>
+				<string>{\rtf1\ansi\ansicpg1252\cocoartf1187\cocoasubrtf340
+\cocoascreenfonts1{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
+{\colortbl;\red255\green255\blue255;\red37\green17\blue0;}
+\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\pardirnatural\qc
+
+\f0\fs24 \cf2 router}</string>
+			</dict>
+		</dict>
+		<dict>
+			<key>Class</key>
+			<string>LineGraphic</string>
+			<key>ID</key>
+			<integer>4075</integer>
+			<key>Points</key>
+			<array>
+				<string>{304.061024983724, 422.16667167345679}</string>
+				<string>{348.49764506022132, 422.16667167345696}</string>
+				<string>{365.83097839355469, 421.50000500679027}</string>
+				<string>{417.16433715820312, 421.16667175292963}</string>
+			</array>
+			<key>Style</key>
+			<dict>
+				<key>stroke</key>
+				<dict>
+					<key>HeadArrow</key>
+					<string>FilledArrow</string>
+					<key>Legacy</key>
+					<true/>
+					<key>TailArrow</key>
+					<string>0</string>
+				</dict>
+			</dict>
+		</dict>
+		<dict>
+			<key>Bounds</key>
+			<string>{{321.11267089843761, 405.16706339518225}, {49, 12}}</string>
+			<key>Class</key>
+			<string>ShapedGraphic</string>
+			<key>FitText</key>
+			<string>YES</string>
+			<key>Flow</key>
+			<string>Resize</string>
+			<key>FontInfo</key>
+			<dict>
+				<key>Font</key>
+				<string>Helvetica</string>
+				<key>Size</key>
+				<real>12</real>
+			</dict>
+			<key>ID</key>
+			<integer>4067</integer>
+			<key>Shape</key>
+			<string>Rectangle</string>
+			<key>Style</key>
+			<dict>
+				<key>fill</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+				<key>shadow</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+				<key>stroke</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+			</dict>
+			<key>Text</key>
+			<dict>
+				<key>Pad</key>
+				<integer>0</integer>
+				<key>Text</key>
+				<string>{\rtf1\ansi\ansicpg1252\cocoartf1187\cocoasubrtf340
+\cocoascreenfonts1{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
+{\colortbl;\red255\green255\blue255;}
+\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\pardirnatural\qc
+
+\f0\fs20 \cf0 4: Request}</string>
+				<key>VerticalPad</key>
+				<integer>0</integer>
+			</dict>
+			<key>Wrap</key>
+			<string>NO</string>
+		</dict>
+		<dict>
+			<key>Bounds</key>
+			<string>{{101.18773682912195, 295.66660690307623}, {62, 12}}</string>
+			<key>Class</key>
+			<string>ShapedGraphic</string>
+			<key>FitText</key>
+			<string>YES</string>
+			<key>Flow</key>
+			<string>Resize</string>
+			<key>FontInfo</key>
+			<dict>
+				<key>Font</key>
+				<string>Helvetica</string>
+				<key>Size</key>
+				<real>12</real>
+			</dict>
+			<key>ID</key>
+			<integer>4058</integer>
+			<key>Shape</key>
+			<string>Rectangle</string>
+			<key>Style</key>
+			<dict>
+				<key>fill</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+				<key>shadow</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+				<key>stroke</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+			</dict>
+			<key>Text</key>
+			<dict>
+				<key>Pad</key>
+				<integer>0</integer>
+				<key>Text</key>
+				<string>{\rtf1\ansi\ansicpg1252\cocoartf1187\cocoasubrtf340
+\cocoascreenfonts1{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
+{\colortbl;\red255\green255\blue255;}
+\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\pardirnatural\qc
+
+\f0\fs20 \cf0 1: Connection}</string>
+				<key>VerticalPad</key>
+				<integer>0</integer>
+			</dict>
+			<key>Wrap</key>
+			<string>NO</string>
+		</dict>
+		<dict>
+			<key>Class</key>
+			<string>LineGraphic</string>
+			<key>ID</key>
+			<integer>4041</integer>
+			<key>Points</key>
+			<array>
+				<string>{85.896713256836037, 421.41666793823208}</string>
+				<string>{199.00002034505209, 421.16666666666669}</string>
+			</array>
+			<key>Style</key>
+			<dict>
+				<key>stroke</key>
+				<dict>
+					<key>HeadArrow</key>
+					<string>FilledArrow</string>
+					<key>Legacy</key>
+					<true/>
+					<key>TailArrow</key>
+					<string>0</string>
+				</dict>
+			</dict>
+		</dict>
+		<dict>
+			<key>Class</key>
+			<string>LineGraphic</string>
+			<key>ID</key>
+			<integer>31</integer>
+			<key>Points</key>
+			<array>
+				<string>{84.896687825520857, 314.66666126251221}</string>
+				<string>{129.33330790201822, 314.66666126251238}</string>
+				<string>{146.66664123535153, 313.99999459584569}</string>
+				<string>{198, 313.66666134198505}</string>
+			</array>
+			<key>Style</key>
+			<dict>
+				<key>stroke</key>
+				<dict>
+					<key>HeadArrow</key>
+					<string>FilledArrow</string>
+					<key>Legacy</key>
+					<true/>
+					<key>TailArrow</key>
+					<string>0</string>
+				</dict>
+			</dict>
+		</dict>
+		<dict>
+			<key>Bounds</key>
+			<string>{{430.83098347981803, 515.99999999999989}, {36, 14}}</string>
+			<key>Class</key>
+			<string>ShapedGraphic</string>
+			<key>FitText</key>
+			<string>YES</string>
+			<key>Flow</key>
+			<string>Resize</string>
+			<key>ID</key>
+			<integer>4026</integer>
+			<key>Shape</key>
+			<string>Rectangle</string>
+			<key>Style</key>
+			<dict>
+				<key>fill</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+				<key>shadow</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+				<key>stroke</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+			</dict>
+			<key>Text</key>
+			<dict>
+				<key>Pad</key>
+				<integer>0</integer>
+				<key>Text</key>
+				<string>{\rtf1\ansi\ansicpg1252\cocoartf1187\cocoasubrtf340
+\cocoascreenfonts1{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
+{\colortbl;\red255\green255\blue255;}
+\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\pardirnatural\qc
+
+\f0\fs24 \cf0 Server}</string>
+				<key>VerticalPad</key>
+				<integer>0</integer>
+			</dict>
+			<key>Wrap</key>
+			<string>NO</string>
+		</dict>
+		<dict>
+			<key>Bounds</key>
+			<string>{{40.499999999999993, 486.66666666666663}, {31, 14}}</string>
+			<key>Class</key>
+			<string>ShapedGraphic</string>
+			<key>FitText</key>
+			<string>YES</string>
+			<key>Flow</key>
+			<string>Resize</string>
+			<key>ID</key>
+			<integer>4025</integer>
+			<key>Shape</key>
+			<string>Rectangle</string>
+			<key>Style</key>
+			<dict>
+				<key>fill</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+				<key>shadow</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+				<key>stroke</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+			</dict>
+			<key>Text</key>
+			<dict>
+				<key>Pad</key>
+				<integer>0</integer>
+				<key>Text</key>
+				<string>{\rtf1\ansi\ansicpg1252\cocoartf1187\cocoasubrtf340
+\cocoascreenfonts1{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
+{\colortbl;\red255\green255\blue255;}
+\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\pardirnatural\qc
+
+\f0\fs24 \cf0 Client}</string>
+				<key>VerticalPad</key>
+				<integer>0</integer>
+			</dict>
+			<key>Wrap</key>
+			<string>NO</string>
+		</dict>
+		<dict>
+			<key>Bounds</key>
+			<string>{{417.16432189941418, 323.90565299479198}, {63.333332061767578, 185.52200317382812}}</string>
+			<key>Class</key>
+			<string>ShapedGraphic</string>
+			<key>ID</key>
+			<integer>4004</integer>
+			<key>ImageID</key>
+			<integer>6</integer>
+			<key>Shape</key>
+			<string>Rectangle</string>
+			<key>Style</key>
+			<dict>
+				<key>fill</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+				<key>shadow</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+				<key>stroke</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+			</dict>
+		</dict>
+		<dict>
+			<key>Bounds</key>
+			<string>{{205.34386889139773, 289.33333333333331}, {84, 248.66667175292969}}</string>
+			<key>Class</key>
+			<string>ShapedGraphic</string>
+			<key>ID</key>
+			<integer>4023</integer>
+			<key>Shape</key>
+			<string>Rectangle</string>
+			<key>Style</key>
+			<dict>
+				<key>fill</key>
+				<dict>
+					<key>Color</key>
+					<dict>
+						<key>b</key>
+						<string>0</string>
+						<key>g</key>
+						<string>0.463735</string>
+						<key>r</key>
+						<string>1</string>
+					</dict>
+				</dict>
+			</dict>
+			<key>Text</key>
+			<dict>
+				<key>Text</key>
+				<string>{\rtf1\ansi\ansicpg1252\cocoartf1187\cocoasubrtf340
+\cocoascreenfonts1{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
+{\colortbl;\red255\green255\blue255;\red37\green17\blue0;}
+\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\pardirnatural\qc
+
+\f0\fs24 \cf2 mitmproxy}</string>
+			</dict>
+		</dict>
+		<dict>
+			<key>Bounds</key>
+			<string>{{4.6666666467984399, 351.33332316080771}, {102.66666412353516, 130.66667175292969}}</string>
+			<key>Class</key>
+			<string>ShapedGraphic</string>
+			<key>ID</key>
+			<integer>134</integer>
+			<key>ImageID</key>
+			<integer>3</integer>
+			<key>Shape</key>
+			<string>Rectangle</string>
+			<key>Style</key>
+			<dict>
+				<key>fill</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+				<key>shadow</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+				<key>stroke</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+			</dict>
+		</dict>
+	</array>
+	<key>GridInfo</key>
+	<dict/>
+	<key>GuidesLocked</key>
+	<string>NO</string>
+	<key>GuidesVisible</key>
+	<string>YES</string>
+	<key>HPages</key>
+	<integer>1</integer>
+	<key>ImageCounter</key>
+	<integer>7</integer>
+	<key>ImageLinkBack</key>
+	<array>
+		<dict/>
+		<dict/>
+	</array>
+	<key>ImageList</key>
+	<array>
+		<string>image6.tiff</string>
+		<string>image3.icns</string>
+	</array>
+	<key>KeepToScale</key>
+	<false/>
+	<key>Layers</key>
+	<array>
+		<dict>
+			<key>Lock</key>
+			<string>NO</string>
+			<key>Name</key>
+			<string>Layer 1</string>
+			<key>Print</key>
+			<string>YES</string>
+			<key>View</key>
+			<string>YES</string>
+		</dict>
+	</array>
+	<key>LayoutInfo</key>
+	<dict>
+		<key>Animate</key>
+		<string>NO</string>
+		<key>circoMinDist</key>
+		<real>18</real>
+		<key>circoSeparation</key>
+		<real>0.0</real>
+		<key>layoutEngine</key>
+		<string>dot</string>
+		<key>neatoSeparation</key>
+		<real>0.0</real>
+		<key>twopiSeparation</key>
+		<real>0.0</real>
+	</dict>
+	<key>LinksVisible</key>
+	<string>NO</string>
+	<key>MagnetsVisible</key>
+	<string>NO</string>
+	<key>MasterSheets</key>
+	<array/>
+	<key>ModificationDate</key>
+	<string>2013-01-03 04:13:10 +0000</string>
+	<key>Modifier</key>
+	<string>Aldo Cortesi</string>
+	<key>NotesVisible</key>
+	<string>NO</string>
+	<key>Orientation</key>
+	<integer>2</integer>
+	<key>OriginVisible</key>
+	<string>NO</string>
+	<key>PageBreaks</key>
+	<string>YES</string>
+	<key>PrintInfo</key>
+	<dict>
+		<key>NSBottomMargin</key>
+		<array>
+			<string>float</string>
+			<string>41</string>
+		</array>
+		<key>NSHorizonalPagination</key>
+		<array>
+			<string>coded</string>
+			<string>BAtzdHJlYW10eXBlZIHoA4QBQISEhAhOU051bWJlcgCEhAdOU1ZhbHVlAISECE5TT2JqZWN0AIWEASqEhAFxlwCG</string>
+		</array>
+		<key>NSLeftMargin</key>
+		<array>
+			<string>float</string>
+			<string>18</string>
+		</array>
+		<key>NSPaperSize</key>
+		<array>
+			<string>size</string>
+			<string>{595.19998741149902, 841.79998779296875}</string>
+		</array>
+		<key>NSPrintReverseOrientation</key>
+		<array>
+			<string>int</string>
+			<string>0</string>
+		</array>
+		<key>NSRightMargin</key>
+		<array>
+			<string>float</string>
+			<string>18</string>
+		</array>
+		<key>NSTopMargin</key>
+		<array>
+			<string>float</string>
+			<string>18</string>
+		</array>
+	</dict>
+	<key>PrintOnePage</key>
+	<false/>
+	<key>ReadOnly</key>
+	<string>NO</string>
+	<key>RowAlign</key>
+	<integer>1</integer>
+	<key>RowSpacing</key>
+	<real>36</real>
+	<key>SheetTitle</key>
+	<string>Canvas 1</string>
+	<key>SmartAlignmentGuidesActive</key>
+	<string>YES</string>
+	<key>SmartDistanceGuidesActive</key>
+	<string>YES</string>
+	<key>UniqueID</key>
+	<integer>1</integer>
+	<key>UseEntirePage</key>
+	<false/>
+	<key>VPages</key>
+	<integer>1</integer>
+	<key>WindowInfo</key>
+	<dict>
+		<key>CurrentSheet</key>
+		<integer>0</integer>
+		<key>ExpandedCanvases</key>
+		<array>
+			<dict>
+				<key>name</key>
+				<string>Canvas 1</string>
+			</dict>
+		</array>
+		<key>Frame</key>
+		<string>{{295, 141}, {974, 874}}</string>
+		<key>ListView</key>
+		<true/>
+		<key>OutlineWidth</key>
+		<integer>142</integer>
+		<key>RightSidebar</key>
+		<false/>
+		<key>ShowRuler</key>
+		<true/>
+		<key>Sidebar</key>
+		<true/>
+		<key>SidebarWidth</key>
+		<integer>120</integer>
+		<key>VisibleRegion</key>
+		<string>{{0, 208}, {550, 469.33333333333337}}</string>
+		<key>Zoom</key>
+		<real>1.5</real>
+		<key>ZoomValues</key>
+		<array>
+			<array>
+				<string>Canvas 1</string>
+				<real>1.5</real>
+				<real>1</real>
+			</array>
+		</array>
+	</dict>
+</dict>
+</plist>