Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
tree: fa72b2cd10
Fetching contributors…

Cannot retrieve contributors at this time

file 119 lines (83 sloc) 3.689 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119

__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 occured, 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.ScriptContext</th>
        <td>A handle for interacting with mitmproxy's global state.</td>
    </tr>
    <tr>
        <th>libmproxy.flow.Flow</th>
        <td>A collection of objects representing a single HTTP transaction.</td>
    </tr>
    <tr>
        <th>libmproxy.flow.Request</th>
        <td>An HTTP request.</td>
    </tr>
    <tr>
        <th>libmproxy.flow.Response</th>
        <td>An HTTP response.</td>
    </tr>
    <tr>
        <th>libmproxy.flow.Error</th>
        <td>A communications error.</td>
    </tr>
    <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.Headers</th>
        <td>HTTP headers for a request or response.</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.
Something went wrong with that request. Please try again.