core

from mitm import core

Core components of the MITM framework.

---

class Host

Dataclass representing an mitm host.

A host is a pair of asyncio.StreamReader and asyncio.StreamWriter objects that are used to communicate with the remote host. There are two types of hosts: a client, and a server. A client host is one that is connected to the mitm, and a server host is one that the mitm connected to on behalf of the client.

The mitm_managed attribute is used to determine whether the mitm is responsible for closing the connection with the host. If mitm_managed is True, the mitm will close the connection with the host when it is done with it. If mitm_managed is set to False, the mitm will not close the connection with the host, and instead, the developer must close the connection with the host manually. This is useful for situations where the mitm is running as a seperate utility and the developer wants to keep the connection open with the host after the mitm is done with it.

Note

See more on dataclasses.

Parameters:

• reader (Optional[StreamReader]) – The reader of the host.

• writer (Optional[StreamWriter]) – The writer of the host.

• mitm_managed (Optional[bool]) – Whether or not the host is managed by the mitm.

reader

The reader of the host.

Type:

asyncio.streams.StreamReader | None

writer

The writer of the host.

Type:

asyncio.streams.StreamWriter | None

mitm_managed

Whether or not the host is managed by the mitm.

Type:

bool | None

ip

The IP address of the host.

port

The port of the host.

Example

reader, writer = await asyncio.open_connection(...)
server = Host(reader, writer)

class Connection

Dataclass representing a standard mitm connection.

A connection is a pair of Host objects that the mitm relays data between. When a connection is created the server host is not resolved until the data is intercepted and the protocol and destination server is figured out.

Note

See more on dataclasses.

Parameters:

• client (Host) – The client host.

• server (Host) – The server host.

• protocol (Optional[Protocol]) – The protocol of the connection.

Example

client = Host(...)
server = Host(...)

connection = Connection(client, server, Protocol.HTTP)

class Flow(enum.Enum)

Enum representing the flow of the connection.

Can be used within the appropriate locations to determine the flow of the connection. Not used by the core mitm framework, but used by the HTTP extension.

Parameters:

• CLIENT_TO_SERVER – The client is sending data to the server.

• SERVER_TO_CLIENT – The server is sending data to the client.

class Middleware(abc.ABC)

Event-driven hook extension for the mitm.

A middleware is a class that is used to extend the mitm framework by allowing event-driven hooks to be added to the mitm and executed when the appropriate event occurs. Built-in middlewares can be found in the mitm.middleware module.

abstract async mitm_started(host, port)

Called when the mitm server boots-up.

abstract async client_connected(connection)

Called when the connection is established with the client.

Note

Note that the mitm.core.Connection object is not fully initialized yet, and only contains a valid client mitm.core.Host.

abstract async server_connected(connection)

Called when the connection is established with the server.

Note

At this point the mitm.core.Connection object is fully initialized.

abstract async client_data(connection, data)

Called when data is received from the client.

Note

Raw TLS/SSL handshake is not sent through this method. Everything should be decrypted beforehand.

Parameters:

request – The request received from the client.

Return type:

bytes

Returns:

The request to send to the server.

abstract async server_data(connection, data)

Called when data is received from the server.

Parameters:

response – The response received from the server.

Return type:

bytes

Returns:

The response to send back to the client.

abstract async client_disconnected(connection)

Called when the client disconnects.

abstract async server_disconnected(connection)

Called when the server disconnects.

class InvalidProtocol(Exception)

Exception raised when the protocol did not work.

This is the only error that mitm.MITM will catch. Throwing this error will continue the search for a valid protocol.

class Protocol

Custom protocol implementation.

Protocols are implementations on how the data flows between the client and server. Application-layer protocols are implemented by subclassing this class. Built-in protocols can be found in the mitm.extension package.

Parameters:

• bytes_needed – Minimum number of bytes needed to determine the protocol.

• buffer_size – The size of the buffer to use when reading data.

• timeout – The timeout to use when reading data.

• keep_alive – Whether or not to keep the connection alive.

__init__(certificate_authority, middlewares)

Initializes the protocol.

Parameters:

• certificate_authority (Optional[CertificateAuthority]) – The certificate authority to use for the connection.

• middlewares (Optional[List[Middleware]]) – The middlewares to use for the connection.

abstract async resolve(connection, data)

Resolves the destination of the connection.

Parameters:

• connection (Connection) – Connection object containing a client host.

• data (bytes) – The initial incoming data from the client.

Return type:

Tuple[str, int, bool]

Returns:

A tuple containing the host, port, and bool that indicates if the connection is encrypted.

Raises:

InvalidProtocol – If the connection failed.

abstract async connect(connection, host, port, tls, data)

Attempts to connect to destination server using the given data. Returns True if the connection was successful, raises InvalidProtocol if the connection failed.

Parameters:

• connection (Connection) – Connection object containing a client host.

• data (bytes) – The initial incoming data from the client.

Raises:

InvalidProtocol – If the connection failed.

abstract async handle(connection)

Handles the connection between a client and a server.

Parameters:

connection (Connection) – Client/server connection to relay.