diff options
| -rw-r--r-- | doc-src/index.html | 9 | ||||
| -rw-r--r-- | doc-src/index.py | 4 | ||||
| -rw-r--r-- | doc-src/scripting.html | 0 | ||||
| -rw-r--r-- | doc-src/scripting/index.py | 6 | ||||
| -rw-r--r-- | doc-src/scripting/inlinescripts.html | 129 | ||||
| -rw-r--r-- | doc-src/scripting/libmproxy.html | 12 |
6 files changed, 154 insertions, 6 deletions
diff --git a/doc-src/index.html b/doc-src/index.html index d3ff6f17..c0236f73 100644 --- a/doc-src/index.html +++ b/doc-src/index.html @@ -15,7 +15,11 @@ <li><a href="@!urlTo("anticache.html")!@">Anticache</a></li> <li><a href="@!urlTo("filters.html")!@">Filter expressions</a></li> </ul> - <li><a href="@!urlTo("scripts.html")!@">Scripts</a></li> + <li>Scripting mitmproxy</li> + <ul> + <li><a href="@!urlTo("scripting/inlinescripts.html")!@">Inline Scripts</a></li> + <li><a href="@!urlTo("scripting/libmproxy.html")!@">libmproxy</a></li> + </ul> <li><a href="@!urlTo("ssl.html")!@">Setting up SSL interception</a></li> <ul> <li><a href="@!urlTo("certinstall/firefox.html")!@">Firefox</a></li> @@ -24,7 +28,6 @@ <li><a href="@!urlTo("certinstall/ios.html")!@">iPhone/iPad</a></li> <li><a href="@!urlTo("certinstall/android.html")!@">Android</a></li> </ul> - <li><a href="@!urlTo("library.html")!@">libmproxy</a></li> <li>Tutorials</li> <ul> <li> <a href="@!urlTo("tutorials/30second.html")!@">Client replay: a 30 second example</a> </li> @@ -33,5 +36,3 @@ <li><a href="@!urlTo("faq.html")!@">FAQ</a></li> <li><a href="@!urlTo("admin.html")!@">Administrivia</a></li> </ul> - - diff --git a/doc-src/index.py b/doc-src/index.py index 722506ab..379d6372 100644 --- a/doc-src/index.py +++ b/doc-src/index.py @@ -79,10 +79,10 @@ pages = [ Page("reverseproxy.html", "Reverse proxy mode"), Page("anticache.html", "Anticache"), Page("filters.html", "Filter expressions"), - Page("scripts.html", "Scripts"), + Page("scripting.html", "Scripts"), + Directory("scripting"), Page("ssl.html", "Setting up SSL interception"), Directory("certinstall"), - Page("library.html", "libmproxy: mitmproxy as a library"), Directory("tutorials"), Page("faq.html", "FAQ"), Page("admin.html", "Administrivia") diff --git a/doc-src/scripting.html b/doc-src/scripting.html new file mode 100644 index 00000000..e69de29b --- /dev/null +++ b/doc-src/scripting.html diff --git a/doc-src/scripting/index.py b/doc-src/scripting/index.py new file mode 100644 index 00000000..94c71a76 --- /dev/null +++ b/doc-src/scripting/index.py @@ -0,0 +1,6 @@ +from countershape import Page + +pages = [ + Page("inlinescripts.html", "Inline Scripts"), + Page("libmproxy.html", "libmproxy") +] diff --git a/doc-src/scripting/inlinescripts.html b/doc-src/scripting/inlinescripts.html new file mode 100644 index 00000000..860ad9b6 --- /dev/null +++ b/doc-src/scripting/inlinescripts.html @@ -0,0 +1,129 @@ + +__mitmproxy__ has a powerful scripting API that allows you to modify flows +on-the-fly or rewrite previously saved flows locally. + +The mitmproxy scripting API is event driven - a script is simply a Python +module that exposes a set of event methods. Here's a complete mitmproxy script +that adds a new header to every HTTP response before it is returned to the +client: + +$!example("examples/add_header.py")!$ + +The first argument to each event method is an instance of ScriptContext that +lets the script interact with the global mitmproxy state. The __response__ +event also gets an instance of Flow, which we can use to manipulate the +response itself. + + +## Events + +### start(ScriptContext) + +Called once on startup, before any other events. + + +###clientconnect(ScriptContext, ClientConnect) + +Called when a client initiates a connection to the proxy. Note that +a connection can correspond to multiple HTTP requests. + + +###request(ScriptContext, Flow) + +Called when a client request has been received. The __Flow__ object is +guaranteed to have a non-None __request__ attribute. + + +### response(ScriptContext, Flow) + +Called when a server response has been received. The __Flow__ object is +guaranteed to have non-None __request__ and __response__ attributes. + + +### error(ScriptContext, Flow) + +Called when a flow error has occurred, e.g. invalid server responses, or +interrupted connections. This is distinct from a valid server HTTP error +response, which is simply a response with an HTTP error code. The __Flow__ +object is guaranteed to have non-None __request__ and __error__ attributes. + + +### clientdisconnect(ScriptContext, ClientDisconnect) + +Called when a client disconnects from the proxy. + +### done(ScriptContext) + +Called once on script shutdown, after any other events. + + +## API + +The main classes you will deal with in writing mitmproxy scripts are: + +<table class="kvtable"> + <tr> + <th>libmproxy.flow.ClientConnection</th> + <td>Describes a client connection.</td> + </tr> + <tr> + <th>libmproxy.flow.ClientDisconnection</th> + <td>Describes a client disconnection.</td> + </tr> + <tr> + <th>libmproxy.flow.Error</th> + <td>A communications error.</td> + </tr> + <tr> + <th>libmproxy.flow.Flow</th> + <td>A collection of objects representing a single HTTP transaction.</td> + </tr> + <tr> + <th>libmproxy.flow.Headers</th> + <td>HTTP headers for a request or response.</td> + </tr> + <tr> + <th>libmproxy.flow.ODict</th> + + <td>A dictionary-like object for managing sets of key/value data. There + is also a variant called CaselessODict that ignores key case for some + calls (used mainly for headers).</td> + </tr> + <tr> + <th>libmproxy.flow.Response</th> + <td>An HTTP response.</td> + </tr> + <tr> + <th>libmproxy.flow.Request</th> + <td>An HTTP request.</td> + </tr> + <tr> + <th>libmproxy.flow.ScriptContext</th> + <td> A handle for interacting with mitmproxy's from within scripts. </td> + </tr> + <tr> + <th>libmproxy.certutils.SSLCert</th> + <td>Exposes information SSL certificates.</td> + </tr> +</table> + +The canonical API documentation is the code. You can view the API documentation +using pydoc (which is installed with Python by default), like this: + +<pre class="terminal"> +> pydoc libmproxy.flow.Request +</pre> + + +## Running scripts on saved flows + +Sometimes, we want to run a script on __Flow__ objects that are already +complete. This happens when you start a script, and then load a saved set of +flows from a file (see the "scripted data transformation" example on the +[mitmdump](@!urlTo("mitmdump.html")!@) page). It also happens when you run a +one-shot script on a single flow through the _|_ (pipe) shortcut in mitmproxy. + +In this case, there are no client connections, and the events are run in the +following order: __start__, __request__, __response__, __error__, __done__. If +the flow doesn't have a __response__ or __error__ associated with it, the +matching event will be skipped. diff --git a/doc-src/scripting/libmproxy.html b/doc-src/scripting/libmproxy.html new file mode 100644 index 00000000..e2d2ff6a --- /dev/null +++ b/doc-src/scripting/libmproxy.html @@ -0,0 +1,12 @@ + +All of mitmproxy's basic functionality is exposed through the __libmproxy__ +library. The example below shows a simple implementation of the "sticky cookie" +functionality included in the interactive mitmproxy program. Traffic is +monitored for __cookie__ and __set-cookie__ headers, and requests are rewritten +to include a previously seen cookie if they don't already have one. In effect, +this lets you log in to a site using your browser, and then make subsequent +requests using a tool like __curl__, which will then seem to be part of the +authenticated session. + +$!example("examples/stickycookies")!$ + |