Internals of mitm

Quick guide on the internal structure of mitm.

Make sure to check out the documentation for asyncio streams before reading this section.

Core

class mitm.core.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.

reader

The asyncio.StreamReader object for the host.

writer

The asyncio.StreamWriter object for the host.

mitm_managed

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.

ip

The IP address of the host.

port

The port of the host.

Host is a dataclass that is defined like so:

@dataclass
class Host:
    reader: Optional[asyncio.StreamReader] = None
    writer: Optional[asyncio.StreamWriter] = None
    mitm_managed: Optional[bool] = True
class mitm.core.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.

client

The client mitm.core.Host. The client host connects to the mitm.

server

The server mitm.core.Host. A server host is connected to the mitm on behalf of the client host.

protocol

The mitm.core.Protocol object for the connection.

Connection is a dataclass that is defined like so:

@dataclass
class Connection:
    client: Host
    server: Host
    protocol: Optional[Protocol] = None

Extensions

class mitm.core.Middleware

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.

async static mitm_started(host: str, port: int)

Called when the mitm server boots-up.

async static client_connected(connection: Connection)

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

async static server_connected(connection: Connection)

Called when the mitm connects with the destination server. At this point the mitm.core.Connection object is fully initialized.

async static client_data(connection: Connection, data: bytes) → bytes

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

Note:

This method must return back data. Modified or not.

async static server_data(connection: Connection, data: bytes) → bytes

Called when the mitm receives data from the destination server. Data that comes through this hook can be modified and returned to the mitm as new data to be sent to the client.

Note:

This method must return back data. Modified or not.

async static client_disconnected(connection: Connection)

Called when the client disconnects.

async static server_disconnected(connection: Connection)

Called when the server disconnects.

class mitm.core.Protocol

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.

bytes_needed

Specifies how many bytes are 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.

Note that the attributes above must be set per-protocol basis.

async resolve(connection: Connection, data: bytes) → Tuple[str, int, bool]

Resolves the destination of the connection. Returns a tuple containing the host, port, and bool that indicates if the connection is encrypted.

async connect(connection: Connection, host: str, port: int, data: bytes)

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

async handle(connection: Connection)

Handles the connection between a client and a server.