aboutsummaryrefslogtreecommitdiffstats
path: root/docs/scripting/events.rst
blob: 622664853519c36c19d3222fbdfaf231f7dad2a6 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
.. _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:: 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
-----------------

.. list-table::
    :widths: 40 60
    :header-rows: 0

    *   - .. py:function:: websockets_handshake(flow)

        - Called when a client wants to establish a WebSockets connection. The
          WebSockets-specific headers can be manipulated to manipulate 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.


TCP Events
----------

These events are called only if the connection is in :ref:`TCP mode
<tcpproxy>`. So, for instance, TCP events are not called for ordinary HTTP/S
connections.

.. list-table::
    :widths: 40 60
    :header-rows: 0

    *   - .. 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.

    *   - .. py:function:: tcp_message(flow)

        - Called 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_start(flow)
        - Called when TCP streaming starts.

          *flow*
            A ``models.TCPFlow`` object.