diff options
Diffstat (limited to 'docs/scripting')
| -rw-r--r-- | docs/scripting/api.rst | 54 | ||||
| -rw-r--r-- | docs/scripting/events.rst | 248 | ||||
| -rw-r--r-- | docs/scripting/overview.rst | 148 |
3 files changed, 0 insertions, 450 deletions
diff --git a/docs/scripting/api.rst b/docs/scripting/api.rst deleted file mode 100644 index 368b9ba8..00000000 --- a/docs/scripting/api.rst +++ /dev/null @@ -1,54 +0,0 @@ -.. _api: - - -API -=== - -- Errors - - `mitmproxy.flow.Error <#mitmproxy.flow.Error>`_ -- HTTP - - `mitmproxy.http.HTTPRequest <#mitmproxy.http.HTTPRequest>`_ - - `mitmproxy.http.HTTPResponse <#mitmproxy.http.HTTPResponse>`_ - - `mitmproxy.http.HTTPFlow <#mitmproxy.http.HTTPFlow>`_ -- WebSocket - - `mitmproxy.websocket.WebSocketFlow <#mitmproxy.websocket.WebSocketFlow>`_ - - `mitmproxy.websocket.WebSocketMessage <#mitmproxy.websocket.WebSocketMessage>`_ -- Logging - - `mitmproxy.log.Log <#mitmproxy.controller.Log>`_ - - `mitmproxy.log.LogEntry <#mitmproxy.controller.LogEntry>`_ - - -Errors ------- - -.. autoclass:: mitmproxy.flow.Error - :inherited-members: - -HTTP ----- - -.. autoclass:: mitmproxy.http.HTTPRequest - :inherited-members: - -.. autoclass:: mitmproxy.http.HTTPResponse - :inherited-members: - -.. autoclass:: mitmproxy.http.HTTPFlow - :inherited-members: - -WebSocket ---------- - -.. autoclass:: mitmproxy.websocket.WebSocketFlow - :inherited-members: - -.. autoclass:: mitmproxy.websocket.WebSocketMessage - :inherited-members: - -Logging --------- - -.. autoclass:: mitmproxy.log.Log - :inherited-members: -.. autoclass:: mitmproxy.log.LogEntry - :inherited-members: diff --git a/docs/scripting/events.rst b/docs/scripting/events.rst deleted file mode 100644 index d8b1fbb8..00000000 --- a/docs/scripting/events.rst +++ /dev/null @@ -1,248 +0,0 @@ -.. _events: - -Events -======= - -General -------- - -.. list-table:: - :widths: 40 60 - :header-rows: 0 - - * - .. py:function:: configure(options, updated) - - Called once on startup, and whenever options change. - - *options* - An ``options.Options`` object with the total current configuration - state of mitmproxy. - *updated* - A set of strings indicating which configuration options have been - updated. This contains all options when *configure* is called on - startup, and only changed options subsequently. - - * - .. py:function:: done() - - Called once when the script shuts down, either because it's been - unloaded, or because the proxy itself is shutting down. - - * - .. py:function:: log(entry) - - Called whenever an event log is added. - - *entry* - An ``controller.LogEntry`` object - ``entry.msg`` is the log text, - and ``entry.level`` is the urgency level ("debug", "info", "warn", - "error"). - - * - .. py:function:: start() - - Called once on startup, before any other events. If you return a - value from this event, it will replace the current addon. This - allows you to, "boot into" an addon implemented as a class instance - from the module level. - - * - .. py:function:: tick() - - Called at a regular sub-second interval as long as the addon is - executing. - - -Connection ----------- - -.. list-table:: - :widths: 40 60 - :header-rows: 0 - - * - .. py:function:: clientconnect(root_layer) - - Called when a client initiates a connection to the proxy. Note that a - connection can correspond to multiple HTTP requests. - - *root_layer* - The root layer (see `mitmproxy.proxy.protocol` for an explanation what - the root layer is), provides transparent access to all attributes - of the :py:class:`~mitmproxy.proxy.RootContext`. For example, - ``root_layer.client_conn.address`` gives the remote address of the - connecting client. - - * - .. py:function:: clientdisconnect(root_layer) - - Called when a client disconnects from the proxy. - - *root_layer* - The root layer object. - - * - .. py:function:: next_layer(layer) - - - Called whenever layers are switched. You may change which layer will - be used by returning a new layer object from this event. - - *layer* - The next layer, as determined by mitmpmroxy. - - * - .. py:function:: serverconnect(server_conn) - - Called before the proxy initiates a connection to the target server. - Note that a connection can correspond to multiple HTTP requests. - - *server_conn* - A ``ServerConnection`` object. It is guaranteed to have a non-None - ``address`` attribute. - - * - .. py:function:: serverdisconnect(server_conn) - - Called when the proxy has closed the server connection. - - *server_conn* - A ``ServerConnection`` object. - - -HTTP Events ------------ - -.. list-table:: - :widths: 40 60 - :header-rows: 0 - - * - .. py:function:: http_connect(flow) - - Called when we receive an HTTP CONNECT request. Setting a non 2xx - response on the flow will return the response to the client and abort - the connection. CONNECT requests and responses do not generate the - usual HTTP handler events. CONNECT requests are only valid in regular - and upstream proxy modes. - - *flow* - A ``models.HTTPFlow`` object. The flow is guaranteed to have - non-None ``request`` and ``requestheaders`` attributes. - - - * - .. py:function:: request(flow) - - Called when a client request has been received. - - *flow* - A ``models.HTTPFlow`` object. At this point, the flow is - guaranteed to have a non-None ``request`` attribute. - - * - .. py:function:: requestheaders(flow) - - Called when the headers of a client request have been received, but - before the request body is read. - - *flow* - A ``models.HTTPFlow`` object. At this point, the flow is - guaranteed to have a non-None ``request`` attribute. - - * - .. py:function:: responseheaders(flow) - - - Called when the headers of a server response have been received, but - before the response body is read. - - *flow* - A ``models.HTTPFlow`` object. At this point, the flow is - guaranteed to have a non-none ``request`` and ``response`` - attributes, however the response will have no content. - - * - .. py:function:: response(flow) - - - Called when a server response has been received. - - *flow* - A ``models.HTTPFlow`` object. At this point, the flow is - guaranteed to have a non-none ``request`` and ``response`` - attributes. The raw response body will be in ``response.body``, - unless response streaming has been enabled. - - * - .. py:function:: error(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. - - *flow* - The flow containing the error. It is guaranteed to have - non-None ``error`` attribute. - - -WebSocket Events ------------------ - -These events are called only after a connection made an HTTP upgrade with -"101 Switching Protocols". No further HTTP-related events after the handshake -are issued, only new WebSocket messages are called. - -.. list-table:: - :widths: 40 60 - :header-rows: 0 - - * - .. py:function:: websocket_handshake(flow) - - Called when a client wants to establish a WebSocket connection. The - WebSocket-specific headers can be manipulated to alter the - handshake. The ``flow`` object is guaranteed to have a non-None - ``request`` attribute. - - *flow* - The flow containing the HTTP WebSocket handshake request. The - object is guaranteed to have a non-None ``request`` attribute. - - * - .. py:function:: websocket_start(flow) - - Called when WebSocket connection is established after a successful - handshake. - - *flow* - A ``models.WebSocketFlow`` object. - - * - .. py:function:: websocket_message(flow) - - - Called when a WebSocket message is received from the client or server. The - sender and receiver are identifiable. The most recent message will be - ``flow.messages[-1]``. The message is user-modifiable and is killable. - A message is either of TEXT or BINARY type. - - *flow* - A ``models.WebSocketFlow`` object. - - * - .. py:function:: websocket_end(flow) - - Called when WebSocket connection ends. - - *flow* - A ``models.WebSocketFlow`` object. - - * - .. py:function:: websocket_error(flow) - - Called when a WebSocket error occurs - e.g. the connection closing - unexpectedly. - - *flow* - A ``models.WebSocketFlow`` object. - - -TCP Events ----------- - -These events are called only if the connection is in :ref:`TCP mode -<tcp_proxy>`. So, for instance, TCP events are not called for ordinary HTTP/S -connections. - -.. list-table:: - :widths: 40 60 - :header-rows: 0 - - - * - .. py:function:: tcp_start(flow) - - Called when TCP streaming starts. - - *flow* - A ``models.TCPFlow`` object. - - * - .. py:function:: tcp_message(flow) - - - Called when a TCP payload is received from the client or server. The - sender and receiver are identifiable. The most recent message will be - ``flow.messages[-1]``. The message is user-modifiable. - - *flow* - A ``models.TCPFlow`` object. - - * - .. py:function:: tcp_end(flow) - - Called when TCP streaming ends. - - *flow* - A ``models.TCPFlow`` object. - - * - .. py:function:: tcp_error(flow) - - Called when a TCP error occurs - e.g. the connection closing - unexpectedly. - - *flow* - A ``models.TCPFlow`` object. diff --git a/docs/scripting/overview.rst b/docs/scripting/overview.rst deleted file mode 100644 index 5ceb5da3..00000000 --- a/docs/scripting/overview.rst +++ /dev/null @@ -1,148 +0,0 @@ -.. _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/addons`). - - -A simple example ----------------- - -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/simple/add_header.py - :caption: :src:`examples/simple/add_header.py` - :language: python - -All events that deal with an HTTP request get an instance of `HTTPFlow -<api.html#mitmproxy.models.http.HTTPFlow>`_, which we can use to manipulate the -response itself. We can now run this script using mitmdump, and the new header -will be added to all responses passing through the proxy: - ->>> mitmdump -s add_header.py - - -Examples --------- - -A collection of addons that demonstrate popular features can be found at :src:`examples/simple`. - - -Using classes -------------- - -In the example above, the script object is the ``add_header`` module itself. -That is, the handlers are declared at the global level of the script. This is -great for quick hacks, but soon becomes limiting as scripts become more -sophisticated. - -When a script first starts up, the `start <events.html#start>`_, event is -called before anything else happens. You can replace the current script object -by returning it from this handler. Here's how this looks when applied to the -example above: - -.. literalinclude:: ../../examples/simple/add_header_class.py - :caption: :src:`examples/simple/add_header_class.py` - :language: python - -So here, we're using a module-level script to "boot up" into a class instance. -From this point on, the module-level script is removed from the handler chain, -and is replaced by the class instance. - - -Handling arguments ------------------- - - -FIXME - - -Logging and the context ------------------------ - -Scripts should not output straight to stderr or stdout. Instead, the `log -<api.html#mitmproxy.controller.Log>`_ object on the ``ctx`` context module -should be used, so that the mitmproxy host program can handle output -appropriately. So, mitmdump can print colorised script output to the terminal, -and mitmproxy console can place script output in the event buffer. - -Here's how this looks: - -.. literalinclude:: ../../examples/simple/log_events.py - :caption: :src:`examples/simple/log_events.py` - :language: python - -The ``ctx`` module also exposes the mitmproxy master object at ``ctx.master`` -for advanced usage. - - -Running scripts on saved flows ------------------------------- - -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 -<events.html#requestheaders>`_, `request <events.html#request>`_, -`responseheaders <events.html#responseheaders>`_ and `response -<events.html#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 fakehtml" -r saved -w changed - -This command starts the ``arguments`` script, reads all the flows from -``saved`` transforming them in the process, then writes them all to -``changed``. - -The mitmproxy console tool provides interactive ways to run transforming -scripts on flows - for instance, you can run a one-shot script on a single flow -through the ``|`` (pipe) shortcut. - - -Concurrency ------------ - -The mitmproxy script mechanism is single threaded, and the proxy blocks while -script handlers execute. This hugely simplifies the most common case, where -handlers are light-weight and the blocking doesn't have a performance impact. -It's possible to implement a concurrent mechanism on top of the blocking -framework, and mitmproxy includes a handy example of this that is fit for most -purposes. You can use it as follows: - -.. literalinclude:: ../../examples/complex/nonblocking.py - :caption: :src:`examples/complex/nonblocking.py` - :language: python - - -Testing -------- - -Mitmproxy includes a number of helpers for testing addons. The -``mitmproxy.test.taddons`` module contains a context helper that takes care of -setting up and tearing down the addon event context. The -``mitmproxy.test.tflow`` module contains helpers for quickly creating test -flows. Pydoc is the canonical reference for these modules, and mitmproxy's own -test suite is an excellent source of examples of usage. Here, for instance, is -the mitmproxy unit tests for the `anticache` option, demonstrating a good -cross-section of the test helpers: - -.. literalinclude:: ../../test/mitmproxy/addons/test_anticache.py - :caption: :src:`test/mitmproxy/addons/test_anticache.py` - :language: python - - -Developing scripts ------------------- - -Mitmproxy monitors scripts for modifications, and reloads them on change. When -this happens, the script is shut down (the `done <events.html#done>`_ event is -called), and the new instance is started up as if the script had just been -loaded (the `start <events.html#start>`_ and `configure -<events.html#configure>`_ events are called). |