diff options
author | Aldo Cortesi <aldo@nullcube.com> | 2016-10-12 10:57:05 +1300 |
---|---|---|
committer | Aldo Cortesi <aldo@nullcube.com> | 2016-10-16 20:26:06 +1300 |
commit | fdb6a44245249a50b5c95cdf0d8d13ecddfe5726 (patch) | |
tree | e173229b7b604641b8a103995e3ceb64276abf3c /docs/scripting/overview.rst | |
parent | 26af9b29fc3fed60a003d097b3470e85115b2161 (diff) | |
download | mitmproxy-fdb6a44245249a50b5c95cdf0d8d13ecddfe5726.tar.gz mitmproxy-fdb6a44245249a50b5c95cdf0d8d13ecddfe5726.tar.bz2 mitmproxy-fdb6a44245249a50b5c95cdf0d8d13ecddfe5726.zip |
docs: cleanups improvements and fighting sphinx
- Hide links to internal code listings, and link to github instead
- Improve formatting of code/example captions
- Fix outdated documentation of command-line options
- Complete documentation of all events + improved formatting
- tcp_open -> tcp_start, tcp_close -> tcp_end to reduce confusion
Diffstat (limited to 'docs/scripting/overview.rst')
-rw-r--r-- | docs/scripting/overview.rst | 79 |
1 files changed, 79 insertions, 0 deletions
diff --git a/docs/scripting/overview.rst b/docs/scripting/overview.rst new file mode 100644 index 00000000..a0dfe111 --- /dev/null +++ b/docs/scripting/overview.rst @@ -0,0 +1,79 @@ +.. _overview: + +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 +functionality is implemented using the exact same API exposed to scripters (see +:src:`mitmproxy/builtins`). + +Scripting is event driven, with named handlers on the script object called at +appropriate points of mitmproxy's operation. Here's a complete mitmproxy script +that adds a new header to every HTTP response before it is returned to the +client: + +.. literalinclude:: ../../examples/add_header.py + :caption: :src:`examples/add_header.py` + :language: python + +All events that deal with an HTTP request get an instance of +:py:class:`~mitmproxy.models.HTTPFlow`, which we can use to manipulate the +response itself. We can now run this script using mitmdump or mitmproxy as +follows: + +>>> mitmdump -s add_header.py + +The new header will be added to all responses passing through the proxy. + + +mitmproxy comes with a variety of example inline scripts, which demonstrate +many basic tasks. + + +Running scripts in parallel +--------------------------- + +We have a single flow primitive, so when a script is blocking, other requests are not processed. +While that's usually a very desirable behaviour, blocking scripts can be run threaded by using the +:py:obj:`mitmproxy.script.concurrent` decorator. +**If your script does not block, you should avoid the overhead of the decorator.** + +.. literalinclude:: ../../examples/nonblocking.py + :caption: examples/nonblocking.py + :language: python + +Make scripts configurable with arguments +---------------------------------------- + +Sometimes, you want to pass runtime arguments to the inline script. This can be simply done by +surrounding the script call with quotes, e.g. ```mitmdump -s 'script.py --foo 42'``. +The arguments are then exposed in the start event: + +.. literalinclude:: ../../examples/modify_response_body.py + :caption: examples/modify_response_body.py + :language: python + + +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 <mitmdump>`). +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**. +If the flow doesn't have a **response** or **error** associated with it, the matching events will +be skipped. + +Spaces in the script path +------------------------- + +By default, spaces are interpreted as a separator between the inline script and its arguments +(e.g. ``-s 'foo.py 42'``). Consequently, the script path needs to be wrapped in a separate pair of +quotes if it contains spaces: ``-s '\'./foo bar/baz.py\' 42'``. + +.. _GitHub: https://github.com/mitmproxy/mitmproxy |