From 678be7a052007e26939b5f0cfa13200ab032cf86 Mon Sep 17 00:00:00 2001 From: Thomas Kriechbaumer Date: Sat, 4 Apr 2020 15:31:38 +0200 Subject: improve scripting docs --- examples/addons/events-http-specific.py | 42 +++++++++++++ examples/addons/events-tcp-specific.py | 25 ++++++++ examples/addons/events-websocket-specific.py | 36 +++++++++++ examples/addons/events.py | 93 ---------------------------- examples/complex/websocket_inject_message.py | 2 +- examples/simple/websocket_messages.py | 11 +++- 6 files changed, 113 insertions(+), 96 deletions(-) create mode 100644 examples/addons/events-http-specific.py create mode 100644 examples/addons/events-tcp-specific.py create mode 100644 examples/addons/events-websocket-specific.py (limited to 'examples') diff --git a/examples/addons/events-http-specific.py b/examples/addons/events-http-specific.py new file mode 100644 index 00000000..37d9f91a --- /dev/null +++ b/examples/addons/events-http-specific.py @@ -0,0 +1,42 @@ +import mitmproxy.http + + +class Events: + # HTTP lifecycle + def http_connect(self, flow: mitmproxy.http.HTTPFlow): + """ + An HTTP CONNECT request was received. Setting a non 2xx response on + the flow will return the response to the client 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. + """ + + def requestheaders(self, flow: mitmproxy.http.HTTPFlow): + """ + HTTP request headers were successfully read. At this point, the body + is empty. + """ + + def request(self, flow: mitmproxy.http.HTTPFlow): + """ + The full HTTP request has been read. + """ + + def responseheaders(self, flow: mitmproxy.http.HTTPFlow): + """ + HTTP response headers were successfully read. At this point, the body + is empty. + """ + + def response(self, flow: mitmproxy.http.HTTPFlow): + """ + The full HTTP response has been read. + """ + + def error(self, flow: mitmproxy.http.HTTPFlow): + """ + An HTTP 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. + """ diff --git a/examples/addons/events-tcp-specific.py b/examples/addons/events-tcp-specific.py new file mode 100644 index 00000000..d150d0f9 --- /dev/null +++ b/examples/addons/events-tcp-specific.py @@ -0,0 +1,25 @@ +import mitmproxy.tcp + + +class Events: + # TCP lifecycle + def tcp_start(self, flow: mitmproxy.tcp.TCPFlow): + """ + A TCP connection has started. + """ + + def tcp_message(self, flow: mitmproxy.tcp.TCPFlow): + """ + A TCP connection has received a message. The most recent message + will be flow.messages[-1]. The message is user-modifiable. + """ + + def tcp_error(self, flow: mitmproxy.tcp.TCPFlow): + """ + A TCP error has occurred. + """ + + def tcp_end(self, flow: mitmproxy.tcp.TCPFlow): + """ + A TCP connection has ended. + """ diff --git a/examples/addons/events-websocket-specific.py b/examples/addons/events-websocket-specific.py new file mode 100644 index 00000000..60069fdb --- /dev/null +++ b/examples/addons/events-websocket-specific.py @@ -0,0 +1,36 @@ +import mitmproxy.http +import mitmproxy.websocket + + +class Events: + # Websocket lifecycle + def websocket_handshake(self, flow: mitmproxy.http.HTTPFlow): + """ + 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. + """ + + def websocket_start(self, flow: mitmproxy.websocket.WebSocketFlow): + """ + A websocket connection has commenced. + """ + + def websocket_message(self, flow: mitmproxy.websocket.WebSocketFlow): + """ + Called when a WebSocket message is received from the client or + server. The most recent message will be flow.messages[-1]. The + message is user-modifiable. Currently there are two types of + messages, corresponding to the BINARY and TEXT frame types. + """ + + def websocket_error(self, flow: mitmproxy.websocket.WebSocketFlow): + """ + A websocket connection has had an error. + """ + + def websocket_end(self, flow: mitmproxy.websocket.WebSocketFlow): + """ + A websocket connection has ended. + """ diff --git a/examples/addons/events.py b/examples/addons/events.py index f83c8f11..958e7d39 100644 --- a/examples/addons/events.py +++ b/examples/addons/events.py @@ -10,99 +10,6 @@ import mitmproxy.proxy.protocol class Events: - # HTTP lifecycle - def http_connect(self, flow: mitmproxy.http.HTTPFlow): - """ - An HTTP CONNECT request was received. Setting a non 2xx response on - the flow will return the response to the client 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. - """ - - def requestheaders(self, flow: mitmproxy.http.HTTPFlow): - """ - HTTP request headers were successfully read. At this point, the body - is empty. - """ - - def request(self, flow: mitmproxy.http.HTTPFlow): - """ - The full HTTP request has been read. - """ - - def responseheaders(self, flow: mitmproxy.http.HTTPFlow): - """ - HTTP response headers were successfully read. At this point, the body - is empty. - """ - - def response(self, flow: mitmproxy.http.HTTPFlow): - """ - The full HTTP response has been read. - """ - - def error(self, flow: mitmproxy.http.HTTPFlow): - """ - An HTTP 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. - """ - - # TCP lifecycle - def tcp_start(self, flow: mitmproxy.tcp.TCPFlow): - """ - A TCP connection has started. - """ - - def tcp_message(self, flow: mitmproxy.tcp.TCPFlow): - """ - A TCP connection has received a message. The most recent message - will be flow.messages[-1]. The message is user-modifiable. - """ - - def tcp_error(self, flow: mitmproxy.tcp.TCPFlow): - """ - A TCP error has occurred. - """ - - def tcp_end(self, flow: mitmproxy.tcp.TCPFlow): - """ - A TCP connection has ended. - """ - - # Websocket lifecycle - def websocket_handshake(self, flow: mitmproxy.http.HTTPFlow): - """ - 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. - """ - - def websocket_start(self, flow: mitmproxy.websocket.WebSocketFlow): - """ - A websocket connection has commenced. - """ - - def websocket_message(self, flow: mitmproxy.websocket.WebSocketFlow): - """ - Called when a WebSocket message is received from the client or - server. The most recent message will be flow.messages[-1]. The - message is user-modifiable. Currently there are two types of - messages, corresponding to the BINARY and TEXT frame types. - """ - - def websocket_error(self, flow: mitmproxy.websocket.WebSocketFlow): - """ - A websocket connection has had an error. - """ - - def websocket_end(self, flow: mitmproxy.websocket.WebSocketFlow): - """ - A websocket connection has ended. - """ - # Network lifecycle def clientconnect(self, layer: mitmproxy.proxy.protocol.Layer): """ diff --git a/examples/complex/websocket_inject_message.py b/examples/complex/websocket_inject_message.py index e9c3ea0c..38be5555 100644 --- a/examples/complex/websocket_inject_message.py +++ b/examples/complex/websocket_inject_message.py @@ -13,7 +13,7 @@ class InjectWebSocketMessage: i = 0 while not flow.ended and not flow.error: await asyncio.sleep(5) - flow.inject_message(flow.client_conn, 'This is the #{} an injected message!'.format(i)) + flow.inject_message(flow.client_conn, 'This is the #{} injected message!'.format(i)) i += 1 def websocket_start(self, flow): diff --git a/examples/simple/websocket_messages.py b/examples/simple/websocket_messages.py index 719e7b10..071ea21f 100644 --- a/examples/simple/websocket_messages.py +++ b/examples/simple/websocket_messages.py @@ -6,8 +6,15 @@ def websocket_message(flow): # get the latest message message = flow.messages[-1] - # simply print the content of the message - ctx.log.info(message.content) + # was the message sent from the client or server? + if message.from_client: + ctx.log.info("Client sent a message: {}".format(message.content)) + else: + ctx.log.info("Server sent a message: {}".format(message.content)) # manipulate the message content message.content = re.sub(r'^Hello', 'HAPPY', message.content) + + if 'FOOBAR' in message.content: + # kill the message and not send it to the other endpoint + message.kill() -- cgit v1.2.3