diff options
Diffstat (limited to 'docs/src/content/addons-overview.md')
-rw-r--r-- | docs/src/content/addons-overview.md | 74 |
1 files changed, 74 insertions, 0 deletions
diff --git a/docs/src/content/addons-overview.md b/docs/src/content/addons-overview.md new file mode 100644 index 00000000..6aa1207e --- /dev/null +++ b/docs/src/content/addons-overview.md @@ -0,0 +1,74 @@ +--- +title: "Addons" +menu: + addons: + weight: 1 +--- + +# 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]({{< relref concepts-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](https://github.com/mitmproxy/mitmproxy/tree/master/mitmproxy/addons), +implementing everything from functionality like [anticaching]({{< relref +"overview-features#anticache" >}}) and [sticky cookies]({{< relref +"overview-features#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](https://docs.python.org/3/library/pydoc.html). +Here, for example, is a command that shows the API documentation for the +mitmproxy's HTTP flow classes: + +{{< highlight bash >}} +pydoc mimtproxy.http +{{< /highlight >}} + +You will be referring to the mitmproxy API documentation frequently, so keep +**pydoc** or an equivalent handy. + +# Anatomy of an addon + +{{< example src="examples/addons/anatomy.py" lang="py" >}} + +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: + +{{< highlight bash >}} +> mitmdump -s ./anatomy.py +{{< /highlight >}} + +Here are a few things to note about the code above: + +- Mitmproxy picks up the contents of the `addons` global list and loads what it + finds into the addons mechanism. +- Addons are just objects - in this case our addon is an instance of `Counter`. +- The `request` method is an example of an **event**. Addons simply implement a + method for each event they wan to handle. Each event has a signature + consisting of arguments that are passed to the method. For `request`, this is + an instance of `mitmproxy.http.HTTPFlow`. +- Finally, the `ctx` module is a holdall module that exposes a set of standard + objects that are commonly used in addons. We could pass a `ctx` object as the + first parameter to every event, but we've found it neater to just expose it as + an importable global. In this case, we're using the `ctx.log` object to do our + logging.
\ No newline at end of file |