From 57b8ed21a9a30eb79d9340d5e146e42bbafd0d46 Mon Sep 17 00:00:00 2001 From: Aldo Cortesi Date: Sun, 16 Oct 2016 18:25:59 +1300 Subject: [PATCH] docs: scripts on saved flows --- docs/scripting/overview.rst | 30 +++++++++++++++++++++++------- 1 file changed, 23 insertions(+), 7 deletions(-) diff --git a/docs/scripting/overview.rst b/docs/scripting/overview.rst index a3b83e443..744f5eb43 100644 --- a/docs/scripting/overview.rst +++ b/docs/scripting/overview.rst @@ -1,7 +1,7 @@ .. _overview: -Introduction -============ +Overview +======== Mitmproxy has a powerful scripting API that allows you to control almost any aspect of traffic being proxied. In fact, much of mitmproxy's own core @@ -96,11 +96,27 @@ for advanced usage. Running scripts on saved flows ------------------------------ -Sometimes, we want to run a script on :py:class:`~mitmproxy.models.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 :ref:`here `). -It also happens when you run a one-shot script on a single flow through the ``|`` (pipe) shortcut -in mitmproxy. +When a flow is loaded from disk, the sequence of events that the flow would +have gone through on the wire is partially replayed. So, for instance, an HTTP +flow loaded from disk will trigger `requestheaders +`_, `request `_, +`responseheaders `_ and `response +`_ in order. We can use this behaviour to transform saved +traffic using scripts. For example, we can invoke the replacer script from +above on saved traffic as follows: + +>>> mitmdump -dd -s "./arguments.py html faketml" + + + + + +:py:class:`~mitmproxy.models.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 :ref:`here `). 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**.