Edit on GitHub

#  Addons

Mitmproxy’s addon mechanism consists of a set of APIs that support components of any complexity. Addons interact with mitmproxy by responding to events, which allow them to hook into and change mitmproxy’s behaviour. They are configured through options, which can be set in mitmproxy’s config file, changed interactively by users, or passed on the command-line. Finally, they can expose commands, which allows users to invoke their actions either directly or by binding them to keys in the interactive tools.

Addons are an exceptionally powerful part of mitmproxy. In fact, much of mitmproxy’s own functionality is defined in a suite of built-in addons, implementing everything from functionality like anticaching and sticky cookies to our onboarding webapp. The built-in addons make for instructive reading, and you will quickly see that quite complex functionality can often boil down to a very small, completely self-contained modules. Mitmproxy provides the exact same set of facilities it uses for its own functionality to third-party scripters and extenders.

This document will show you how to build addons using events, options and commands. However, this is not an API manual, and the mitmproxy source code remains the canonical reference. One easy way to explore the API from the command-line is to use pydoc. Here, for example, is a command that shows the API documentation for the mitmproxy’s HTTP flow classes:

pydoc mitmproxy.http

You will be referring to the mitmproxy API documentation frequently, so keep pydoc or an equivalent handy.

#  Anatomy of an addon

Basic skeleton of a mitmproxy addon.

Run as follows: mitmproxy -s anatomy.py
from mitmproxy import ctx

class Counter:
    def __init__(self):
        self.num = 0

    def request(self, flow):
        self.num = self.num + 1
        ctx.log.info("We've seen %d flows" % self.num)

addons = [

Above is a simple addon that keeps track of the number of flows (or more specifically HTTP requests) we’ve seen. Every time it sees a new flow, it uses mitmproxy’s internal logging mechanism to announce its tally. The output can be found in the event log in the interactive tools, or on the console in mitmdump.

Take it for a spin and make sure that it does what it’s supposed to, by loading it into your mitmproxy tool of choice. We’ll use mitmpdump in these examples, but the flag is identical for all tools:

> mitmdump -s ./anatomy.py

Here are a few things to note about the code above: