From 3f9263a57a5d365fe5d058ed584f596944443eff Mon Sep 17 00:00:00 2001 From: Aldo Cortesi Date: Sun, 16 Sep 2012 15:35:58 +1200 Subject: Doc reorg. --- doc-src/index.html | 9 +-- doc-src/index.py | 4 +- doc-src/scripting.html | 0 doc-src/scripting/index.py | 6 ++ doc-src/scripting/inlinescripts.html | 129 +++++++++++++++++++++++++++++++++++ doc-src/scripting/libmproxy.html | 12 ++++ 6 files changed, 154 insertions(+), 6 deletions(-) create mode 100644 doc-src/scripting.html create mode 100644 doc-src/scripting/index.py create mode 100644 doc-src/scripting/inlinescripts.html create mode 100644 doc-src/scripting/libmproxy.html diff --git a/doc-src/index.html b/doc-src/index.html index d3ff6f17..c0236f73 100644 --- a/doc-src/index.html +++ b/doc-src/index.html @@ -15,7 +15,11 @@
  • Anticache
  • Filter expressions
    • -
  • Scripts
    • +
  • Scripting mitmproxy
    • +
  • Setting up SSL interception
    • -
  • libmproxy
  • Tutorials
    • - - diff --git a/doc-src/index.py b/doc-src/index.py index 722506ab..379d6372 100644 --- a/doc-src/index.py +++ b/doc-src/index.py @@ -79,10 +79,10 @@ pages = [ Page("reverseproxy.html", "Reverse proxy mode"), Page("anticache.html", "Anticache"), Page("filters.html", "Filter expressions"), - Page("scripts.html", "Scripts"), + Page("scripting.html", "Scripts"), + Directory("scripting"), Page("ssl.html", "Setting up SSL interception"), Directory("certinstall"), - Page("library.html", "libmproxy: mitmproxy as a library"), Directory("tutorials"), Page("faq.html", "FAQ"), Page("admin.html", "Administrivia") diff --git a/doc-src/scripting.html b/doc-src/scripting.html new file mode 100644 index 00000000..e69de29b diff --git a/doc-src/scripting/index.py b/doc-src/scripting/index.py new file mode 100644 index 00000000..94c71a76 --- /dev/null +++ b/doc-src/scripting/index.py @@ -0,0 +1,6 @@ +from countershape import Page + +pages = [ + Page("inlinescripts.html", "Inline Scripts"), + Page("libmproxy.html", "libmproxy") +] diff --git a/doc-src/scripting/inlinescripts.html b/doc-src/scripting/inlinescripts.html new file mode 100644 index 00000000..860ad9b6 --- /dev/null +++ b/doc-src/scripting/inlinescripts.html @@ -0,0 +1,129 @@ + +__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 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: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    libmproxy.flow.ClientConnectionDescribes a client connection.
    libmproxy.flow.ClientDisconnectionDescribes a client disconnection.
    libmproxy.flow.ErrorA communications error.
    libmproxy.flow.FlowA collection of objects representing a single HTTP transaction.
    libmproxy.flow.HeadersHTTP headers for a request or response.
    libmproxy.flow.ODictA 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).
    libmproxy.flow.ResponseAn HTTP response.
    libmproxy.flow.RequestAn HTTP request.
    libmproxy.flow.ScriptContext A handle for interacting with mitmproxy's from within scripts.
    libmproxy.certutils.SSLCertExposes information SSL certificates.
    + +The canonical API documentation is the code. You can view the API documentation +using pydoc (which is installed with Python by default), like this: + +
    +> pydoc libmproxy.flow.Request
+
    + + +## 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. diff --git a/doc-src/scripting/libmproxy.html b/doc-src/scripting/libmproxy.html new file mode 100644 index 00000000..e2d2ff6a --- /dev/null +++ b/doc-src/scripting/libmproxy.html @@ -0,0 +1,12 @@ + +All of mitmproxy's basic functionality is exposed through the __libmproxy__ +library. The example below shows a simple implementation of the "sticky cookie" +functionality included in the interactive mitmproxy program. Traffic is +monitored for __cookie__ and __set-cookie__ headers, and requests are rewritten +to include a previously seen cookie if they don't already have one. In effect, +this lets you log in to a site using your browser, and then make subsequent +requests using a tool like __curl__, which will then seem to be part of the +authenticated session. + +$!example("examples/stickycookies")!$ + -- cgit v1.2.3