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.


Installation
------------

The recommended way to install mitmproxy is running 

`pip install mitmproxy`

For convenience, we provide binary packages on [mitmproxy.org](http://mitmproxy.org/).


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

* [Python](http://www.python.org) 2.7.x.
* [netlib](http://pypi.python.org/pypi/netlib), version matching mitmproxy.
* Third-party packages listed in [setup.py](https://github.com/mitmproxy/mitmproxy/blob/master/setup.py)

Optional packages 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.
* [cssutils](http://cthedot.de/cssutils/) version 1.0 or newer.

For convenience, all optional dependencies can be installed with 

`pip install mitmproxy contentviews`

__mitmproxy__ is tested and developed on OSX, Linux and OpenBSD. On Windows,
only mitmdump is supported, which does not have a graphical user interface.


Hacking
-------

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

* The test suite requires the `dev` extra requirements listed in [setup.py](https://github.com/mitmproxy/mitmproxy/blob/master/setup.py) and [pathod](http://pathod.net), version matching mitmproxy. Install these with `pip install mitmproxy dev`.
* Rendering the documentation requires [countershape](http://github.com/cortesi/countershape).

The following procedure is recommended to set up your dev environment:

```
$ git clone https://github.com/mitmproxy/mitmproxy.git
$ cd mitmproxy
$ pip install --src . -r requirements.txt
```

This installs the latest GitHub versions of mitmproxy, netlib and pathod into `mitmproxy/`. All other development dependencies save countershape are installed into their usual locations. 

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
Update README.mkd 2014-09-09 00:18:08 +00:00			`Installation`
			`------------`

Documentation re-org - No longer using README.md in the rendered documentation. - Rendered doc instrutions are now for the released version of mitmproxy, with dev install instructions in the README.md 2014-10-22 20:44:47 +00:00			`The recommended way to install mitmproxy is running`

			`pip install mitmproxy`
Update README.mkd 2014-09-09 00:18:08 +00:00
			`For convenience, we provide binary packages on [mitmproxy.org](http://mitmproxy.org/).`


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.`
Doc and readme tweaks. 2014-01-19 05:08:50 +00:00			`* Third-party packages listed in [setup.py](https://github.com/mitmproxy/mitmproxy/blob/master/setup.py)`
README, Linux transparent mode docs, requirements additions. 2013-05-13 21:12:26 +00:00
Doc and readme tweaks. 2014-01-19 05:08:50 +00:00			`Optional packages for extended content decoding:`
README, Linux transparent mode docs, requirements additions. 2013-05-13 21:12:26 +00:00
			`* [PyAMF](http://www.pyamf.org/) version 0.6.1 or newer.`
			`* [protobuf](https://code.google.com/p/protobuf/) version 2.5.0 or newer.`
Doc and readme tweaks. 2014-01-19 05:08:50 +00:00			`* [cssutils](http://cthedot.de/cssutils/) version 1.0 or newer.`
Documentation. 2012-04-09 03:15:41 +00:00
Update README.mkd 2014-09-09 00:18:08 +00:00			`For convenience, all optional dependencies can be installed with`
Documentation re-org - No longer using README.md in the rendered documentation. - Rendered doc instrutions are now for the released version of mitmproxy, with dev install instructions in the README.md 2014-10-22 20:44:47 +00:00
			`pip install mitmproxy contentviews`
Update README.mkd 2014-09-09 00:18:08 +00:00
			`__mitmproxy__ is tested and developed on OSX, Linux and OpenBSD. On Windows,`
			`only mitmdump is supported, which does not have a graphical user interface.`
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
Documentation re-org - No longer using README.md in the rendered documentation. - Rendered doc instrutions are now for the released version of mitmproxy, with dev install instructions in the README.md 2014-10-22 20:44:47 +00:00			* The test suite requires the `dev` extra requirements listed in [setup.py](https://github.com/mitmproxy/mitmproxy/blob/master/setup.py) and [pathod](http://pathod.net), version matching mitmproxy. Install these with `pip install mitmproxy dev`.
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
Documentation re-org - No longer using README.md in the rendered documentation. - Rendered doc instrutions are now for the released version of mitmproxy, with dev install instructions in the README.md 2014-10-22 20:44:47 +00:00			`The following procedure is recommended to set up your dev environment:`

Update README.mkd 2014-09-09 00:18:08 +00:00			```
			`$ git clone https://github.com/mitmproxy/mitmproxy.git`
			`$ cd mitmproxy`
			`$ pip install --src . -r requirements.txt`
			```
Documentation re-org - No longer using README.md in the rendered documentation. - Rendered doc instrutions are now for the released version of mitmproxy, with dev install instructions in the README.md 2014-10-22 20:44:47 +00:00
Update README.mkd 2014-09-09 00:18:08 +00:00			This installs the latest GitHub versions of mitmproxy, netlib and pathod into `mitmproxy/`. All other development dependencies save countershape are installed into their usual locations.
Added requirements.txt to ease installation of deps for hacking on mitmproxy. 2013-05-24 03:23:47 +00:00
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.`