mitmproxy/README.mkd

[![Build Status](https://travis-ci.org/mitmproxy/mitmproxy.png?branch=master)](https://travis-ci.org/mitmproxy/mitmproxy) [![Coverage Status](https://coveralls.io/repos/mitmproxy/mitmproxy/badge.png?branch=master)](https://coveralls.io/r/mitmproxy/mitmproxy)

__mitmproxy__ is an interactive, SSL-capable man-in-the-middle proxy for HTTP
with a console interface.

__mitmdump__ is the command-line version of mitmproxy. Think tcpdump for HTTP.

__libmproxy__ is the library that mitmproxy and mitmdump are built on.

Documentation, tutorials and distribution packages can be found on the
mitmproxy.org website:

[mitmproxy.org](http://mitmproxy.org).


Features
--------

- Intercept HTTP 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 certificates for interception are generated on the fly.
- And much, much more.


Requirements
------------

* [Python](http://www.python.org) 2.7.x.
* [netlib](http://pypi.python.org/pypi/netlib), version matching mitmproxy.
* [PyOpenSSL](http://pypi.python.org/pypi/pyOpenSSL) 0.13 or newer.
* [pyasn1](http://pypi.python.org/pypi/pyasn1) 0.1.2 or newer.
* [urwid](http://excess.org/urwid/) version 1.1 or newer.
* [PIL](http://www.pythonware.com/products/pil/) version 1.1 or newer.
* [lxml](http://lxml.de/) version 2.3 or newer.
* [flask](http://flask.pocoo.org/) version 0.9 or newer.

Optional, for extended content decoding:

* [PyAMF](http://www.pyamf.org/) version 0.6.1 or newer.
* [protobuf](https://code.google.com/p/protobuf/) version 2.5.0 or newer.

__mitmproxy__ is tested and developed on OSX, Linux and OpenBSD. Windows is not
officially supported at the moment.


Hacking
-------

The following components are needed if you plan to hack on mitmproxy:

* The test suite uses the [nose](http://readthedocs.org/docs/nose/en/latest/) unit testing
  framework and requires [pathod](http://pathod.org) and [flask](http://flask.pocoo.org/).
* Rendering the documentation requires [countershape](http://github.com/cortesi/countershape).

For convenience, all dependencies save countershape, can be installed from pypi to a virtualenv with 'pip install -r requirements.txt'.

Please ensure that all patches are accompanied by matching changes in the test
suite. The project maintains 100% test coverage.
display build status from master branch 2014-01-09 16:38:08 +00:00			`[![Build Status](https://travis-ci.org/mitmproxy/mitmproxy.png?branch=master)](https://travis-ci.org/mitmproxy/mitmproxy) [![Coverage Status](https://coveralls.io/repos/mitmproxy/mitmproxy/badge.png?branch=master)](https://coveralls.io/r/mitmproxy/mitmproxy)`
add status images to README, include TestHTTPS again 2013-08-25 02:31:35 +00:00
Docs and Readme - Don't keep a full duplicate readme just for pypi. Pypi really needs to learn to read markdown. - Style and content adjustments 2013-01-01 03:35:52 +00:00			`__mitmproxy__ is an interactive, SSL-capable man-in-the-middle proxy for HTTP`
			`with a console interface.`
Make README reflect reality. 2011-02-20 23:11:41 +00:00
Docs and Readme - Don't keep a full duplicate readme just for pypi. Pypi really needs to learn to read markdown. - Style and content adjustments 2013-01-01 03:35:52 +00:00			`__mitmdump__ is the command-line version of mitmproxy. Think tcpdump for HTTP.`

			`__libmproxy__ is the library that mitmproxy and mitmdump are built on.`
Docs, minor cert tweaks. 2011-03-17 20:04:49 +00:00
Trim docs. 2013-03-23 02:42:25 +00:00			`Documentation, tutorials and distribution packages can be found on the`
			`mitmproxy.org website:`

Add README.txt for PyPi. Yes, this means we now maintain two complete README files that are identical except for markup. We distribute with only README.txt, so README.mkd can actually move in to the documentation tree at some point. 2012-02-25 00:16:30 +00:00			`[mitmproxy.org](http://mitmproxy.org).`
Update README. 2010-02-16 05:25:03 +00:00

Start preparing for 0.7 Update CHANGELOG, CONTRIBUTORS, README.mkd, todo, and bump version. 2012-02-19 09:43:05 +00:00			`Features`
			`--------`
Update README. 2010-02-16 05:25:03 +00:00
Begin to flesh out and refactor docs. 2011-03-15 22:09:10 +00:00			`- Intercept HTTP requests and responses and modify them on the fly.`
			`- Save complete HTTP conversations for later replay and analysis.`
Docs, minor cert tweaks. 2011-03-17 20:04:49 +00:00			`- Replay the client-side of an HTTP conversations.`
Docs. 2011-03-18 22:26:51 +00:00			`- Replay HTTP responses of a previously recorded server.`
Minor docs and example script fixes. 2012-02-20 23:32:56 +00:00			`- Reverse proxy mode to forward traffic to a specified server.`
Docs and Readme - Don't keep a full duplicate readme just for pypi. Pypi really needs to learn to read markdown. - Style and content adjustments 2013-01-01 03:35:52 +00:00			`- Transparent proxy mode on OSX and Linux.`
remove trailing whitespace 2012-12-09 21:57:11 +00:00			`- Make scripted changes to HTTP traffic using Python.`
Docs. 2011-03-18 22:26:51 +00:00			`- SSL certificates for interception are generated on the fly.`
Docs and Readme - Don't keep a full duplicate readme just for pypi. Pypi really needs to learn to read markdown. - Style and content adjustments 2013-01-01 03:35:52 +00:00			`- And much, much more.`
Documentation updates. 2011-01-24 21:59:50 +00:00
We now have a mailing list and an IRC channel Come join us in the #mitmproxy channel on the OFTC IRC network (irc://irc.oftc.net:6667). We also have a mailing list, hosted here: http://groups.google.com/group/mitmproxy 2011-08-06 21:52:13 +00:00
Initial checkin. 2010-02-16 04:09:07 +00:00			`Requirements`
Docs - refinement and styling. 2011-03-19 06:47:19 +00:00			`------------`
Initial checkin. 2010-02-16 04:09:07 +00:00
Fix READMEs: we don't support Python 2.6 Fixes #70 2012-11-29 19:17:50 +00:00			`* [Python](http://www.python.org) 2.7.x.`
Expand "How mitmproxy works". Clean up some un-needed sections. 2013-03-10 04:09:40 +00:00			`* [netlib](http://pypi.python.org/pypi/netlib), version matching mitmproxy.`
Updated readme files with new PyOpenSSL 0.13 dependency. 2012-08-08 19:38:02 +00:00			`* [PyOpenSSL](http://pypi.python.org/pypi/pyOpenSSL) 0.13 or newer.`
Update docs to reflect new dependencies. 2012-03-11 01:41:03 +00:00			`* [pyasn1](http://pypi.python.org/pypi/pyasn1) 0.1.2 or newer.`
Docs and Readme - Don't keep a full duplicate readme just for pypi. Pypi really needs to learn to read markdown. - Style and content adjustments 2013-01-01 03:35:52 +00:00			`* [urwid](http://excess.org/urwid/) version 1.1 or newer.`
Add PIL dependencies to READMEs. Thanks to Sven Neuhaus for pointing this out. 2012-04-03 21:55:14 +00:00			`* [PIL](http://www.pythonware.com/products/pil/) version 1.1 or newer.`
Documentation. 2012-04-09 03:15:41 +00:00			`* [lxml](http://lxml.de/) version 2.3 or newer.`
README, Linux transparent mode docs, requirements additions. 2013-05-13 21:12:26 +00:00			`* [flask](http://flask.pocoo.org/) version 0.9 or newer.`

			`Optional, for extended content decoding:`

			`* [PyAMF](http://www.pyamf.org/) version 0.6.1 or newer.`
			`* [protobuf](https://code.google.com/p/protobuf/) version 2.5.0 or newer.`
Documentation. 2012-04-09 03:15:41 +00:00
Test WSGI app calling. - Factor out test servers into a separate file - Adjust docs to note new Flask dependency 2013-02-16 03:46:16 +00:00			`__mitmproxy__ is tested and developed on OSX, Linux and OpenBSD. Windows is not`
			`officially supported at the moment.`
Documentation. 2012-04-09 03:15:41 +00:00
Minor docs tweaks. Mention countershape. 2011-03-28 22:53:13 +00:00
Test WSGI app calling. - Factor out test servers into a separate file - Adjust docs to note new Flask dependency 2013-02-16 03:46:16 +00:00			`Hacking`
			`-------`

			`The following components are needed if you plan to hack on mitmproxy:`
Initial checkin. 2010-02-16 04:09:07 +00:00
Test WSGI app calling. - Factor out test servers into a separate file - Adjust docs to note new Flask dependency 2013-02-16 03:46:16 +00:00			`* The test suite uses the [nose](http://readthedocs.org/docs/nose/en/latest/) unit testing`
Remove human_curl requirement for the test suite - it's pathoc all the way, baby. 2013-03-02 02:09:22 +00:00			`framework and requires [pathod](http://pathod.org) and [flask](http://flask.pocoo.org/).`
Test WSGI app calling. - Factor out test servers into a separate file - Adjust docs to note new Flask dependency 2013-02-16 03:46:16 +00:00			`* Rendering the documentation requires [countershape](http://github.com/cortesi/countershape).`
Trim docs. 2013-03-23 02:42:25 +00:00
Added requirements.txt to ease installation of deps for hacking on mitmproxy. 2013-05-24 03:23:47 +00:00			`For convenience, all dependencies save countershape, can be installed from pypi to a virtualenv with 'pip install -r requirements.txt'.`

README, Linux transparent mode docs, requirements additions. 2013-05-13 21:12:26 +00:00			`Please ensure that all patches are accompanied by matching changes in the test`
			`suite. The project maintains 100% test coverage.`