From e6ef0c3faf21971c144aaf93e6c05d98f1fe74be Mon Sep 17 00:00:00 2001 From: Aldo Cortesi Date: Wed, 16 Mar 2011 11:09:10 +1300 Subject: [PATCH] Begin to flesh out and refactor docs. --- README.mkd | 43 ++++++++-------------- doc-src/certinstall/chrome.html | 0 doc-src/certinstall/firefox.html | 15 ++++++++ doc-src/certinstall/ie.html | 0 doc-src/certinstall/index.py | 10 +++++ doc-src/certinstall/ios.html | 0 doc-src/certinstall/safari.html | 0 doc-src/certinstall/windows7.html | 0 doc-src/index.html | 33 +++++++++-------- doc-src/ssl.html | 61 ++++++++++++++----------------- 10 files changed, 85 insertions(+), 77 deletions(-) create mode 100644 doc-src/certinstall/chrome.html create mode 100644 doc-src/certinstall/firefox.html create mode 100644 doc-src/certinstall/ie.html create mode 100644 doc-src/certinstall/index.py create mode 100644 doc-src/certinstall/ios.html create mode 100644 doc-src/certinstall/safari.html create mode 100644 doc-src/certinstall/windows7.html diff --git a/README.mkd b/README.mkd index 08378007c..0c1902796 100644 --- a/README.mkd +++ b/README.mkd @@ -1,35 +1,26 @@ -__mitmproxy__ is an interactive SSL-capable intercepting HTTP proxy. It lets -you to observe, modify and replay requests and responses on the fly. The -underlying library that mitmproxy is built on can also be used to do these -things programmatically. -By default, mitmproxy starts up with a mutt-like interactive curses interface - -the built-in help page (which you can view by pressing "?") will tell you -everything you need to know. Note that requests and responses are stored -in-memory until you delete them, so leaving mitmproxy running indefinitely or -requesting very large amounts of data through it is a bad idea. +__mitmproxy__ and __mitmdump__ are SSL-capable, intercepting HTTP proxies. + +__mitmproxy__ provides a curses interface that allows traffic to be inspected +and edited on the fly. + +__mitmdump__ is a tcpdump-like tool for HTTP. -SSL ---- +Capabilities +============ -The first time mitmproxy is started, it will generate a bogus SSL certificate -authority (the default location is ~/.mitmproxy/ca.pem). This CA is used to -generate certificates for SSL requests on-the-fly. To avoid the hassle of -having to accept these certificates individually, you can add the certificate -authority to your browser or globally to your system. +- Intercept HTTP requests and responses and modify them on the fly. +- Save complete HTTP conversations for later replay and analysis. +- Client replay to replay the client-side of an HTTP conversation. +- Server replay replays the HTTP responses of a previously recorded server. +- Make scripted changes to HTTP traffic using a simple Python API. +- Dummy SSL certificate authority creates interception certificates on the fly. -Documentation -------------- - -A rendered version of the docs for the latest release can be found here: - -http://corte.si/projects.html - Download --------- +======== Releases can be found here: http://corte.si/projects.html @@ -37,7 +28,7 @@ Source is hosted here: http://github.com/cortesi/mitmproxy Requirements ------------- +============ * A recent [Python](http://www.python.org) interpreter. * SSL certificates are generated using [openssl](http://www.openssl.org/) @@ -53,5 +44,3 @@ following: * PAGER environment variable to determine the external pager. * Appropriate entries in your mailcap files to determine external viewers for request and response contents. - - diff --git a/doc-src/certinstall/chrome.html b/doc-src/certinstall/chrome.html new file mode 100644 index 000000000..e69de29bb diff --git a/doc-src/certinstall/firefox.html b/doc-src/certinstall/firefox.html new file mode 100644 index 000000000..f661a619d --- /dev/null +++ b/doc-src/certinstall/firefox.html @@ -0,0 +1,15 @@ + +### 1: Open preferences, click on "Advanced", then select"Encryption": + + + +### 2: Click "View Certificates", "Import", and select the certificate file: + + + +### 3: Tick "Trust this CS to identify web sites", and click "Ok": + + + +You should now see the mitmproxy certificate listed in the Authorities tab. + diff --git a/doc-src/certinstall/ie.html b/doc-src/certinstall/ie.html new file mode 100644 index 000000000..e69de29bb diff --git a/doc-src/certinstall/index.py b/doc-src/certinstall/index.py new file mode 100644 index 000000000..3dee24ec8 --- /dev/null +++ b/doc-src/certinstall/index.py @@ -0,0 +1,10 @@ +from countershape import Page + +pages = [ + Page("firefox.html", "Firefox"), + Page("chrome.html", "Chrome"), + Page("safari.html", "Safari"), + Page("ie.html", "Internet Explorer"), + Page("windows7.html", "Windows 7"), + Page("ios.html", "IOS"), +] diff --git a/doc-src/certinstall/ios.html b/doc-src/certinstall/ios.html new file mode 100644 index 000000000..e69de29bb diff --git a/doc-src/certinstall/safari.html b/doc-src/certinstall/safari.html new file mode 100644 index 000000000..e69de29bb diff --git a/doc-src/certinstall/windows7.html b/doc-src/certinstall/windows7.html new file mode 100644 index 000000000..e69de29bb diff --git a/doc-src/index.html b/doc-src/index.html index 49e7327f1..8110bf795 100644 --- a/doc-src/index.html +++ b/doc-src/index.html @@ -1,25 +1,26 @@ * [Introduction](@!urlTo("intro.html")!@) +* [mitmproxy](@!urlTo("/mitmproxy.html")!@) +* [mitmdump](@!urlTo("/mitmdump.html")!@) +* [Client script API](@!urlTo("scripts.html")!@) +* [libmproxy](@!urlTo("library.html")!@) +* [SSL](@!urlTo("/ssl.html")!@) + * Browser certificate installation: + * [Firefox](@!urlTo("certinstall/firefox.html")!@#firefox) + * [Chrome](@!urlTo("certinstall/chrome.html")!@#chrome) + * [Safari](@!urlTo("certinstall/safari.html")!@#safari) + * [Internet Explorer](@!urlTo("certinstall/ie.html")!@#ie) + * System-wide certificate installation: + * [Windows 7](@!urlTo("certinstall/windows7.html")!@#windows7) + * [iPhone/iPad](@!urlTo("certinstall/ios.html")!@#ios) * Tutorials * Client replay: a 30 second example - * Scripting: On-the-fly modifications to HTTP conversations - * Breaking iPhone apps for fun and profit -* Reference - * [mitmproxy - HTTP Swiss Army Knife](@!urlTo("/mitmproxy.html")!@) - * [mitmdump - A tcpdump-like tool for HTTP](@!urlTo("/mitmdump.html")!@) - * [Client scripts](@!urlTo("scripts.html")!@) - * [libmproxy](@!urlTo("library.html")!@) - Using the mitmproxy library -* Installing mitmproxy's SSL certificate - * [Firefox](@!urlTo("ssl.html")!@#firefox) - * [Chrome](@!urlTo("ssl.html")!@#chrome) - * [Safari](@!urlTo("ssl.html")!@#safari) - * [IE8](@!urlTo("ssl.html")!@#ie) - * System-wide installation: - * [Windows 7](@!urlTo("ssl.html")!@#windows7) - * [iPhone/iPad](@!urlTo("ssl.html")!@#ios) + * Scripting: On-the-fly modifications to HTTP conversations [coming soon] + * Sticky cookies [coming soon] + * Breaking iPhone apps for fun and profit [coming soon] * [FAQ](@!urlTo("faq.html")!@) -* [administrivia](@!urlTo("admin.html")!@) +* [Administrivia](@!urlTo("admin.html")!@) diff --git a/doc-src/ssl.html b/doc-src/ssl.html index 4fe1ee15b..06d5a9d67 100644 --- a/doc-src/ssl.html +++ b/doc-src/ssl.html @@ -1,41 +1,34 @@ -# Browsers +SSL +=== - -## Firefox 3.x +The first time __mitmproxy__ or __mitmdump__ is started, a dummy SSL +certificate authority is generated (the default location is +~/.mitmproxy/ca.pem). This dummy CA is used to generate dummy certificates for +SSL interception on-the-fly. Since your browser won't trust the __mitmproxy__ +dummy CA out of the box (and rightly so), so you will see an SSL cert warning +every time you visit a new SSL domain through __mitmproxy__. When you're +testing a single site, just accepting the bogus SSL cert manually is not too +much of a hassle, but there are a number of cases where you will want to +configure your testing system or browser to trust __mitmproxy__: -### 1: Open preferences, click on "Advanced", then select"Encryption": - - - -### 2: Click "View Certificates", "Import", and select the certificate file: - - - -### 3: Tick "Trust this CS to identify web sites", and click "Ok": - - - -You should now see the mitmproxy certificate listed in the Authorities tab. +- If you are testing non-browser software that checks SSL cert validiy. +- You are testing an app that makes non-interactive (JSONP, script src, etc.) +requests to SSL resources. Another workaround in this case is to manually visit +the page through the browser, and add a certificate exception. +- You just don't want to deal with the hassle of continuously adding cert +exceptions. - -## Chrome - - -## Safari - - -## Internet Explorer 8 - - -# Global installation - - -## Windows 7 - - -## iPhone/iPad - +Installing the mitmproxy CA +=========================== +* Browser certificate installation: + * [Firefox](@!urlTo("certinstall/firefox.html")!@#firefox) + * [Chrome](@!urlTo("certinstall/chrome.html")!@#chrome) + * [Safari](@!urlTo("certinstall/safari.html")!@#safari) + * [Internet Explorer](@!urlTo("certinstall/ie.html")!@#ie) +* System-wide certificate installation: + * [Windows 7](@!urlTo("certinstall/windows7.html")!@#windows7) + * [iPhone/iPad](@!urlTo("certinstall/ios.html")!@#ios)