diff options
| -rw-r--r-- | doc-src/02-docstyle.css | 31 | ||||
| -rw-r--r-- | doc-src/index.py | 3 | ||||
| -rw-r--r-- | doc-src/mitmdump.html | 20 | ||||
| -rw-r--r-- | doc-src/scripts.html | 96 | ||||
| -rw-r--r-- | examples/add_header.py | 8 |
5 files changed, 106 insertions, 52 deletions
diff --git a/doc-src/02-docstyle.css b/doc-src/02-docstyle.css index eee82c58..b3d55e1a 100644 --- a/doc-src/02-docstyle.css +++ b/doc-src/02-docstyle.css @@ -52,14 +52,21 @@ a { color: #181818; } + +#bd h3 { + margin-bottom: 0px; + +} + #bd p { margin: 1em 0; + margin-top: 0.5em; } /* Keyboard shortcuts */ #bd em { font-weight: bold; - color: #04B404; + color: #00A700; font-style: normal; } @@ -86,10 +93,9 @@ pre { } .terminal { - color: #ffffff; + color: #c0c0c0; + font-size: 1em; background: #000000; - - } .docindex { @@ -118,5 +124,22 @@ li a { .highlight { 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; +} + diff --git a/doc-src/index.py b/doc-src/index.py index 34704f7e..6241a232 100644 --- a/doc-src/index.py +++ b/doc-src/index.py @@ -34,7 +34,8 @@ ns.index_contents = file(mpath("README.mkd")).read() top = os.path.abspath(os.getcwd()) def example(s): 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 diff --git a/doc-src/mitmdump.html b/doc-src/mitmdump.html index 4d0683ea..1ca5a020 100644 --- a/doc-src/mitmdump.html +++ b/doc-src/mitmdump.html @@ -8,28 +8,36 @@ documentation. ## Example: saving traffic - mitmdump -w outfile +<pre class="terminal"> +mitmdump -w outfile +</pre> Start up mitmdump in proxy mode, and write all traffic to __outfile__. ## Example: client replay - mitmdump -nc outfile +<pre class="terminal"> +mitmdump -nc outfile +</pre> Start mitmdump without binding to the proxy port (_-n_), then replay all 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 another: - mitmdump -nc srcfile -w dstfile +<pre class="terminal"> +mitmdump -nc srcfile -w dstfile +</pre> See the [Client-side Replay](@!urlTo("clientreplay.html")!@) section for more information. ## Example: running a script - mitmdump -s examples/add_header.py +<pre class="terminal"> +mitmdump -s examples/add_header.py +</pre> This runs the __add_header.py__ example script, which simply adds a new header to all responses. @@ -37,7 +45,9 @@ to all responses. ## Example: scripted data transformation - mitmdump -ns examples/add_header.py -r srcfile -w dstfile +<pre class="terminal"> +mitmdump -ns examples/add_header.py -r srcfile -w dstfile +</pre> This command loads flows from __srcfile__, transforms it according to the specified script, then writes it back to __dstfile__. diff --git a/doc-src/scripts.html b/doc-src/scripts.html index 990ca070..af140901 100644 --- a/doc-src/scripts.html +++ b/doc-src/scripts.html @@ -1,47 +1,71 @@ -__mitmproxy__ has a powerful event-drive scripting API, that allows you to -modify flows on-the-fly or rewrite previously saved flows locally. +__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 -<table> - <tr> - <td>start(ctx)</td> - <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> +### 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. +## 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. diff --git a/examples/add_header.py b/examples/add_header.py index 6ddeab3d..0c0593d1 100644 --- a/examples/add_header.py +++ b/examples/add_header.py @@ -1,6 +1,2 @@ -""" - This script adds a new header to all responses. -""" - -def response(ctx, f): - f.response.headers["newheader"] = ["foo"] +def response(context, flow): + flow.response.headers["newheader"] = ["foo"] |