proxy.http.proxy.plugin module#

⚡⚡⚡ Fast, Lightweight, Pluggable, TLS interception capable proxy server focused on Network monitoring, controls & Application development, testing, debugging.

  1. 2013-present by Abhinav Singh and contributors.


BSD, see LICENSE for more details.

class proxy.http.proxy.plugin.HttpProxyBasePlugin(uid: str, flags: argparse.Namespace, client: proxy.http.connection.HttpClientConnection, event_queue: proxy.core.event.queue.EventQueue, upstream_conn_pool: Optional[UpstreamConnectionPool] = None)[source]#

Bases: proxy.http.descriptors.DescriptorsHandlerMixin, abc.ABC

Base HttpProxyPlugin Plugin class.

Implement various lifecycle event methods to customize behavior.

_abc_impl = <_abc._abc_data object>#
before_upstream_connection(request: proxy.http.parser.parser.HttpParser) Optional[proxy.http.parser.parser.HttpParser][source]#

Handler called just before Proxy upstream connection is established.

Return optionally modified request object. If None is returned, upstream connection won’t be established.

Raise HttpRequestRejected or HttpProtocolException directly to drop the connection.

do_intercept(_request: proxy.http.parser.parser.HttpParser) bool[source]#

By default returns True (only) when necessary flags for TLS interception are passed.

When TLS interception is enabled, plugins can still disable TLS interception by returning False explicitly. This hook will allow you to run proxy instance with TLS interception flags BUT only conditionally enable interception for certain requests.

handle_client_data(raw: memoryview) Optional[memoryview][source]#

Handler called in special scenarios when an upstream server connection is never established.

Essentially, if you return None from within before_upstream_connection, be prepared to handle_client_data and not handle_client_request.

Only called after initial request from client has been received.

Raise HttpRequestRejected to tear down the connection Return None to drop the connection

handle_client_request(request: proxy.http.parser.parser.HttpParser) Optional[proxy.http.parser.parser.HttpParser][source]#

Handler called before dispatching client request to upstream.

Note: For pipelined (keep-alive) connections, this handler can be called multiple times, for each request sent to upstream.

Note: If TLS interception is enabled, this handler can be called multiple times if client exchanges multiple requests over same SSL session.

Return optionally modified request object to dispatch to upstream. Return None to drop the request data, e.g. in case a response has already been queued. Raise HttpRequestRejected or HttpProtocolException directly to tear down the connection with client.

handle_upstream_chunk(chunk: memoryview) Optional[memoryview][source]#

Handler called right after receiving raw response from upstream server.

For HTTPS connections, chunk will be encrypted unless TLS interception is also enabled.

Return None if you don’t want to sent this chunk to the client.

name() str[source]#

A unique name for your plugin.

Defaults to name of the class. This helps plugin developers to directly access a specific plugin by its name.

on_access_log(context: Dict[str, Any]) Optional[Dict[str, Any]][source]#

Use this method to override default access log format (see DEFAULT_HTTP_ACCESS_LOG_FORMAT and DEFAULT_HTTPS_ACCESS_LOG_FORMAT) and to add/update/modify/delete context for next plugin.on_access_log invocation.

This is specially useful if a plugins want to provide extra context in the access log which may not available within other plugins’ context or even in core.

Returns Log context or None. If plugin chooses to access log, they ideally must return None to prevent other plugin.on_access_log invocation.

on_upstream_connection_close() None[source]#

Handler called right after upstream connection has been closed.

resolve_dns(host: str, port: int) Tuple[Optional[str], Optional[HostPort]][source]#

Resolve upstream server host to an IP address.

Optionally also override the source address to use for connection with upstream server.

For upstream IP: Return None to use default resolver available to the system. Return IP address as string to use your custom resolver.

For source address: Return None to use default source address Return 2-tuple representing (host, port) to use as source address