mirror of
https://github.com/Grasscutters/mitmproxy.git
synced 2024-11-23 00:01:36 +00:00
First draft of scripting docs.
This commit is contained in:
parent
89a58d7e30
commit
cd0e2f18e6
@ -52,14 +52,21 @@ a {
|
|||||||
color: #181818;
|
color: #181818;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
||||||
|
#bd h3 {
|
||||||
|
margin-bottom: 0px;
|
||||||
|
|
||||||
|
}
|
||||||
|
|
||||||
#bd p {
|
#bd p {
|
||||||
margin: 1em 0;
|
margin: 1em 0;
|
||||||
|
margin-top: 0.5em;
|
||||||
}
|
}
|
||||||
|
|
||||||
/* Keyboard shortcuts */
|
/* Keyboard shortcuts */
|
||||||
#bd em {
|
#bd em {
|
||||||
font-weight: bold;
|
font-weight: bold;
|
||||||
color: #04B404;
|
color: #00A700;
|
||||||
font-style: normal;
|
font-style: normal;
|
||||||
}
|
}
|
||||||
|
|
||||||
@ -86,10 +93,9 @@ pre {
|
|||||||
}
|
}
|
||||||
|
|
||||||
.terminal {
|
.terminal {
|
||||||
color: #ffffff;
|
color: #c0c0c0;
|
||||||
|
font-size: 1em;
|
||||||
background: #000000;
|
background: #000000;
|
||||||
|
|
||||||
|
|
||||||
}
|
}
|
||||||
|
|
||||||
.docindex {
|
.docindex {
|
||||||
@ -118,5 +124,22 @@ li a {
|
|||||||
.highlight {
|
.highlight {
|
||||||
font-size: 14px;
|
font-size: 14px;
|
||||||
}
|
}
|
||||||
|
.example_legend{
|
||||||
|
float: right;
|
||||||
|
line-height: 1;
|
||||||
|
margin-left: 20px;
|
||||||
|
font-size: 12px;
|
||||||
|
}
|
||||||
|
.example pre {
|
||||||
|
margin: 0;
|
||||||
|
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
.kvtable th {
|
||||||
|
text-align: left;
|
||||||
|
white-space: nowrap;
|
||||||
|
}
|
||||||
|
|
||||||
|
@ -34,7 +34,8 @@ ns.index_contents = file(mpath("README.mkd")).read()
|
|||||||
top = os.path.abspath(os.getcwd())
|
top = os.path.abspath(os.getcwd())
|
||||||
def example(s):
|
def example(s):
|
||||||
d = file(mpath(s)).read()
|
d = file(mpath(s)).read()
|
||||||
return countershape.template.Syntax("py")(d)
|
extemp = """<div class="example">%s<div class="example_legend">(%s)</div></div>"""
|
||||||
|
return extemp%(countershape.template.Syntax("py")(d), s)
|
||||||
|
|
||||||
|
|
||||||
ns.example = example
|
ns.example = example
|
||||||
|
@ -8,28 +8,36 @@ documentation.
|
|||||||
|
|
||||||
## Example: saving traffic
|
## Example: saving traffic
|
||||||
|
|
||||||
|
<pre class="terminal">
|
||||||
mitmdump -w outfile
|
mitmdump -w outfile
|
||||||
|
</pre>
|
||||||
|
|
||||||
Start up mitmdump in proxy mode, and write all traffic to __outfile__.
|
Start up mitmdump in proxy mode, and write all traffic to __outfile__.
|
||||||
|
|
||||||
|
|
||||||
## Example: client replay
|
## Example: client replay
|
||||||
|
|
||||||
|
<pre class="terminal">
|
||||||
mitmdump -nc outfile
|
mitmdump -nc outfile
|
||||||
|
</pre>
|
||||||
|
|
||||||
Start mitmdump without binding to the proxy port (_-n_), then replay all
|
Start mitmdump without binding to the proxy port (_-n_), then replay all
|
||||||
requests from outfile (_-c filename_). Flags combine in the obvious way, so
|
requests from outfile (_-c filename_). Flags combine in the obvious way, so
|
||||||
you can replay requests from one file, and write the resulting flows to
|
you can replay requests from one file, and write the resulting flows to
|
||||||
another:
|
another:
|
||||||
|
|
||||||
|
<pre class="terminal">
|
||||||
mitmdump -nc srcfile -w dstfile
|
mitmdump -nc srcfile -w dstfile
|
||||||
|
</pre>
|
||||||
|
|
||||||
See the [Client-side Replay](@!urlTo("clientreplay.html")!@) section for more information.
|
See the [Client-side Replay](@!urlTo("clientreplay.html")!@) section for more information.
|
||||||
|
|
||||||
|
|
||||||
## Example: running a script
|
## Example: running a script
|
||||||
|
|
||||||
|
<pre class="terminal">
|
||||||
mitmdump -s examples/add_header.py
|
mitmdump -s examples/add_header.py
|
||||||
|
</pre>
|
||||||
|
|
||||||
This runs the __add_header.py__ example script, which simply adds a new header
|
This runs the __add_header.py__ example script, which simply adds a new header
|
||||||
to all responses.
|
to all responses.
|
||||||
@ -37,7 +45,9 @@ to all responses.
|
|||||||
|
|
||||||
## Example: scripted data transformation
|
## Example: scripted data transformation
|
||||||
|
|
||||||
|
<pre class="terminal">
|
||||||
mitmdump -ns examples/add_header.py -r srcfile -w dstfile
|
mitmdump -ns examples/add_header.py -r srcfile -w dstfile
|
||||||
|
</pre>
|
||||||
|
|
||||||
This command loads flows from __srcfile__, transforms it according to the
|
This command loads flows from __srcfile__, transforms it according to the
|
||||||
specified script, then writes it back to __dstfile__.
|
specified script, then writes it back to __dstfile__.
|
||||||
|
@ -1,47 +1,71 @@
|
|||||||
|
|
||||||
__mitmproxy__ has a powerful event-drive scripting API, that allows you to
|
__mitmproxy__ has a powerful scripting API that allows you to modify flows
|
||||||
modify flows on-the-fly or rewrite previously saved flows locally.
|
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
|
## Events
|
||||||
|
|
||||||
<table>
|
### start(ScriptContext)
|
||||||
<tr>
|
|
||||||
<td>start(ctx)</td>
|
Called once on startup, before any other events.
|
||||||
<td>Called once on startup, before any other events.</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td>clientconnect(ctx, ClientConnect)</td>
|
|
||||||
<td>Called when a client initiates a connection to the proxy. Note that
|
|
||||||
a connection can correspond to multiple HTTP requests.</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td>request(ctx, Flow)</td>
|
|
||||||
<td>Called when a client request has been received.</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td>response(ctx, Flow)</td>
|
|
||||||
<td>Called when a server response has been received.</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td>error(ctx, Flow)</td>
|
|
||||||
<td>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. </td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td>clientdisconnect(ctx, ClientDisconnect)</td>
|
|
||||||
<td>Called when a client disconnects from the proxy.</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td>done(ctx)</td>
|
|
||||||
<td>Called once on script shutdown, after any other events.</td>
|
|
||||||
</tr>
|
|
||||||
</table>
|
|
||||||
|
|
||||||
|
|
||||||
|
###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.
|
||||||
|
|
||||||
|
|
||||||
|
## Scripts on saved flows
|
||||||
|
|
||||||
|
There are a few circumstances in which a script may run on Flows that are
|
||||||
|
already complete. For example, you could 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). This 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.
|
||||||
|
@ -1,6 +1,2 @@
|
|||||||
"""
|
def response(context, flow):
|
||||||
This script adds a new header to all responses.
|
flow.response.headers["newheader"] = ["foo"]
|
||||||
"""
|
|
||||||
|
|
||||||
def response(ctx, f):
|
|
||||||
f.response.headers["newheader"] = ["foo"]
|
|
||||||
|
Loading…
Reference in New Issue
Block a user