diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/features/passthrough.rst | 4 | ||||
| -rw-r--r-- | docs/scripting/inlinescripts.rst | 63 |
2 files changed, 42 insertions, 25 deletions
diff --git a/docs/features/passthrough.rst b/docs/features/passthrough.rst index 80521393..b7b5df84 100644 --- a/docs/features/passthrough.rst +++ b/docs/features/passthrough.rst @@ -31,9 +31,9 @@ mitmproxy allows you to specify a regex which is matched against a ``host:port`` There are two important quirks to consider: -- **In transparent mode, the ignore pattern is matched against the IP.** While we usually infer the +- **In transparent mode, the ignore pattern is matched against the IP and ClientHello SNI host.** While we usually infer the hostname from the Host header if the :option:`--host` argument is passed to mitmproxy, we do not - have access to this information before the SSL handshake. + have access to this information before the SSL handshake. If the client uses SNI however, then we treat the SNI host as an ignore target. - In regular mode, explicit HTTP requests are never ignored. [#explicithttp]_ The ignore pattern is applied on CONNECT requests, which initiate HTTPS or clear-text WebSocket connections. diff --git a/docs/scripting/inlinescripts.rst b/docs/scripting/inlinescripts.rst index 19e17582..27e4abef 100644 --- a/docs/scripting/inlinescripts.rst +++ b/docs/scripting/inlinescripts.rst @@ -36,14 +36,13 @@ We encourage you to either browse them locally or on `GitHub`_. Events ------ -.. TODO: Split this into Connection, HTTP and TCP events once we have TCP events. - The ``context`` argument passed to each event method is always a :py:class:`~libmproxy.script.ScriptContext` instance. It is guaranteed to be the same object for the scripts lifetime and is not shared between multiple inline scripts. You can safely use it to store any form of state you require. -Events are listed in the order they usually occur. +Script Lifecycle Events +^^^^^^^^^^^^^^^^^^^^^^^ .. py:function:: start(context, argv) @@ -52,6 +51,13 @@ Events are listed in the order they usually occur. :param List[str] argv: The inline scripts' arguments. For example, ``mitmproxy -s 'example.py --foo 42'`` sets argv to ``["--foo", "42"]``. +.. py:function:: done(context) + + Called once on script shutdown, after any other events. + +Connection Events +^^^^^^^^^^^^^^^^^ + .. py:function:: clientconnect(context, root_layer) Called when a client initiates a connection to the proxy. Note that @@ -64,14 +70,13 @@ Events are listed in the order they usually occur. :py:class:`~libmproxy.proxy.RootContext`. For example, ``root_layer.client_conn.address`` gives the remote address of the connecting client. +.. py:function:: clientdisconnect(context, root_layer) -.. py:function:: request(context, flow) + Called when a client disconnects from the proxy. - Called when a client request has been received. The ``flow`` object is - guaranteed to have a non-None ``request`` attribute. + .. versionchanged:: 0.14 - :param HTTPFlow flow: The flow containing the request which has been received. - The object is guaranteed to have a non-None ``request`` attribute. + :param Layer root_layer: see :py:func:`clientconnect` .. py:function:: serverconnect(context, server_conn) @@ -81,6 +86,25 @@ Events are listed in the order they usually occur. :param ServerConnection server_conn: The server connection object. It is guaranteed to have a non-None ``address`` attribute. +.. py:function:: serverdisconnect(context, server_conn) + + Called when the proxy has closed the server connection. + + .. versionadded:: 0.14 + + :param ServerConnection server_conn: see :py:func:`serverconnect` + +HTTP Events +^^^^^^^^^^^ + +.. py:function:: request(context, flow) + + Called when a client request has been received. The ``flow`` object is + guaranteed to have a non-None ``request`` attribute. + + :param HTTPFlow flow: The flow containing the request which has been received. + The object is guaranteed to have a non-None ``request`` attribute. + .. py:function:: responseheaders(context, flow) Called when the headers of a server response have been received. @@ -109,26 +133,19 @@ Events are listed in the order they usually occur. :param HTTPFlow flow: The flow containing the error. It is guaranteed to have non-None ``error`` attribute. -.. py:function:: serverdisconnect(context, server_conn) +TCP Events +^^^^^^^^^^ - Called when the proxy has closed the server connection. +.. py:function:: tcp_message(context, tcp_msg) - .. versionadded:: 0.14 + .. warning:: API is subject to change - :param ServerConnection server_conn: see :py:func:`serverconnect` + If the proxy is in :ref:`TCP mode <tcpproxy>`, this event is called when it + receives a TCP payload from the client or server. -.. py:function:: clientdisconnect(context, root_layer) - - Called when a client disconnects from the proxy. - - .. versionchanged:: 0.14 - - :param Layer root_layer: see :py:func:`clientconnect` - -.. py:function:: done(context) - - Called once on script shutdown, after any other events. + The sender and receiver are identifiable. The message is user-modifiable. + :param TcpMessage tcp_msg: see *examples/tcp_message.py* API --- |