__mitmproxy__ has a powerful scripting API that allows you to modify flows on-the-fly or rewrite previously saved flows locally. The mitmproxy scripting API is event driven - a script is simply a Python module that exposes a set of event methods. Here's a complete mitmproxy script that adds a new header to every HTTP response before it is returned to the client: $!example("examples/add_header.py")!$ The first argument to each event method is an instance of ScriptContext that lets the script interact with the global mitmproxy state. The __response__ event also gets an instance of Flow, 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. ## Events ### start(ScriptContext, argv) Called once on startup, before any other events. ### clientconnect(ScriptContext, ClientConnect) Called when a client initiates a connection to the proxy. Note that a connection can correspond to multiple HTTP requests. ### request(ScriptContext, Flow) Called when a client request has been received. The __Flow__ object is guaranteed to have a non-None __request__ attribute. ### response(ScriptContext, Flow) Called when a server response has been received. The __Flow__ object is guaranteed to have non-None __request__ and __response__ attributes. ### error(ScriptContext, 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. The __Flow__ object is guaranteed to have non-None __request__ and __error__ attributes. ### clientdisconnect(ScriptContext, ClientDisconnect) Called when a client disconnects from the proxy. ### done(ScriptContext) Called once on script shutdown, after any other events. ## API The main classes you will deal with in writing mitmproxy scripts are:
libmproxy.flow.ClientConnection Describes a client connection.
libmproxy.flow.ClientDisconnection Describes a client disconnection.
libmproxy.flow.Error A communications error.
libmproxy.flow.Flow A collection of objects representing a single HTTP transaction.
libmproxy.flow.Headers HTTP headers for a request or response.
libmproxy.flow.ODict A dictionary-like object for managing sets of key/value data. There is also a variant called CaselessODict that ignores key case for some calls (used mainly for headers).
libmproxy.flow.Response An HTTP response.
libmproxy.flow.Request An HTTP request.
libmproxy.flow.ScriptContext A handle for interacting with mitmproxy's from within scripts.
libmproxy.certutils.SSLCert Exposes information SSL certificates.
The canonical API documentation is the code. You can view the API documentation using pydoc (which is installed with Python by default), like this: 
> pydoc libmproxy.flow.Request
## Running scripts on saved flows Sometimes, we want to run a script on __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 on the [mitmdump](@!urlTo("mitmdump.html")!@) page). 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__, __response__, __error__, __done__. If the flow doesn't have a __response__ or __error__ associated with it, the matching event will be skipped. > 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 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256