mitmproxy/doc-src/scripting/inlinescripts.html

__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.

We can now run this script using mitmdump or mitmproxy as follows:

<pre class="terminal">
> mitmdump -s add_header.py
</pre>

The new header will be added to all responses passing through the proxy.

## Example Scripts

mitmproxy comes with a variety of example inline scripts, which demonstrate
many basic tasks. We encourage you to either browse them locally or in our
[GitHub repo](https://github.com/mitmproxy/mitmproxy/tree/master/examples).


## Events

### start(ScriptContext, argv)

Called once on startup, before any other events.


### clientconnect(ScriptContext, ConnectionHandler)

Called when a client initiates a connection to the proxy. Note that
a connection can correspond to multiple HTTP requests.

### serverconnect(ScriptContext, ConnectionHandler)

Called when the proxy initiates a connection to the target server. Note that
a connection can correspond to multiple HTTP requests.

### request(ScriptContext, HTTPFlow)

Called when a client request has been received. The __HTTPFlow__ object is
guaranteed to have a non-None __request__ attribute.

### responseheaders(ScriptContext, HTTPFlow)

Called when the headers of a server response have been received.
This will always be called before the response hook.
The __HTTPFlow__ object is guaranteed to have non-None __request__ and
__response__ attributes.  __response.content__ will be None,
as the response body has not been read yet.

### response(ScriptContext, HTTPFlow)

Called when a server response has been received. The __HTTPFlow__ object is
guaranteed to have non-None __request__ and __response__ attributes.
Note that if response streaming is enabled for this response,
__response.content__ will not contain the response body.

### error(ScriptContext, HTTPFlow)

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 __HTTPFlow__
object is guaranteed to have non-None __request__ and __error__ attributes.


### clientdisconnect(ScriptContext, ConnectionHandler)

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="table">
    <tr>
        <th>libmproxy.proxy.server.ConnectionHandler</th>
        <td>Describes a proxy client connection session. Always has a client_conn attribute, might have a server_conn
            attribute.
        </td>
    </tr>
    <tr>
        <th>libmproxy.proxy.connection.ClientConnection</th>
        <td>Describes a client connection.</td>
    </tr>
    <tr>
        <th>libmproxy.proxy.connection.ServerConnection</th>
        <td>Describes a server connection.</td>
    </tr>
    <tr>
        <th>libmproxy.protocol.http.HTTPFlow</th>
        <td>A collection of objects representing a single HTTP transaction.</td>
    </tr>
    <tr>
        <th>libmproxy.protocol.http.HTTPResponse</th>
        <td>An HTTP response.</td>
    </tr>
    <tr>
        <th>libmproxy.protocol.http.HTTPRequest</th>
        <td>An HTTP request.</td>
    </tr>
    <tr>
        <th>libmproxy.protocol.primitives.Error</th>
        <td>A communications error.</td>
    </tr>
    <tr>
        <th>libmproxy.script.ScriptContext</th>
        <td> A handle for interacting with mitmproxy's from within scripts.</td>
    </tr>
    <tr>
        <th>netlib.odict.ODict</th>

        <td>A dictionary-like object for managing sets of key/value data. There
        is also a variant called ODictCaseless that ignores key case for some
        calls (used mainly for headers).</td>
    </tr>
    <tr>
        <th>netlib.certutils.SSLCert</th>
        <td>Exposes information SSL certificates.</td>
    </tr>
</table>

The canonical API documentation is the code, which you can browse locally or in our
[GitHub repo](https://github.com/mitmproxy/mitmproxy).
You can view the API documentation using pydoc (which is installed with Python by default), like this:

<pre class="terminal">
> pydoc libmproxy.protocol.http.HTTPRequest
</pre>


## Running scripts in parallel

We have a single flow primitive, so when a script is blocking, other requests are not processed.
While that's usually a very desirable behaviour, blocking scripts can be run threaded by using the <code>libmproxy.script.concurrent</code> decorator.
If your script does not block, you should avoid the overhead of the decorator.

$!example("examples/nonblocking.py")!$

## Make scripts configurable with arguments

Sometimes, you want to pass runtime arguments to the inline script. This can be simply done by surrounding the script call with quotes, e.g.
<code>mitmdump -s "script.py --foo 42"</code>. The arguments are then exposed in the start event:

$!example("examples/modify_response_body.py")!$

## 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__, __responseheaders__, __response__, __error__, __done__.  If
the flow doesn't have a __response__ or __error__ associated with it, the
matching events will be skipped.

## Spaces in the script path
By default, spaces are interpreted as separator between the inline script and its arguments (e.g. <code>-s "foo.py
    42"</code>). Consequently, the script path needs to be wrapped in a separate pair of quotes if it contains spaces:
<code>-s "'./foo bar/baz.py' 42"</code>.