mirror of
https://github.com/Grasscutters/mitmproxy.git
synced 2024-11-24 00:31:33 +00:00
138 lines
4.2 KiB
HTML
138 lines
4.2 KiB
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.
|
|
|
|
|
|
|
|
## 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="table">
|
|
<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.
|