selfhostblocks/modules/blocks/mitmdump/docs/default.md

Mitmdump Block

Defined in /modules/blocks/mitmdump.nix.

This block sets up an Mitmdump service in reverse proxy mode. In other words, you can put this block between a client and a server to inspect all the network traffic.

Multiple instances of mitmdump all listening on different ports and proxying to different upstream servers can be created.

The systemd service is made so it is started only when the mitmdump instance has started listening on the expected port.

Also, addons can be enabled with the enabledAddons option.

Usage

Put mitmdump in front of a HTTP server listening on port 8000 on the same machine:

shb.mitmdump.instances."my-instance" = {
  listenPort = 8001;
  upstreamHost = "http://127.0.0.1";
  upstreamPort = 8000;
  after = [ "server.service" ];
};

upstreamHost has its default value here and can be left out.

Put mitmdump in front of a HTTP server listening on port 8000 on another machine:

shb.mitmdump.instances."my-instance" = {
  listenPort = 8001;
  upstreamHost = "http://otherhost";
  upstreamPort = 8000;
  after = [ "server.service" ];
};

Handle Upstream TLS

Replace http with https if the server expects an HTTPS connection.

Accept Connections from Anywhere

By default, mitmdump is configured to listen only for connections from localhost. Add listenHost=0.0.0.0 to make mitmdump accept connections from anywhere.

Extra Logging

To print request and response bodies and more, increase the logging with:

extraArgs = [
    "--set" "flow_detail=3"
    "--set" "content_view_lines_cutoff=2000"
];

The default flow_details is 1. See the manual for more explanations on the option.

This will change the verbosity for all requests and responses. If you need more fine grained logging, configure instead the Logger Addon.

Addons

All provided addons can be found under the shb.mitmproxy.addons option.

To enable one for an instance, add it to the enabledAddons option. For example:

shb.mitmdump.instances."my-instance" = {
    enabledAddons = [ config.shb.mitmdump.addons.logger ]
}

Fine Grained Logger

The Fine Grained Logger addon is found under shb.mitmproxy.addons.logger. Enabling this addon will add the mitmdump option verbose_pattern which takes a regex and if it matches, prints the request and response headers and body. If it does not match, it will just print the response status.

For example, with the extraArgs:

extraArgs = [
  "--set" "verbose_pattern=/verbose"
];

A GET request to /notverbose will print something similar to:

mitmdump[972]: 127.0.0.1:53586: GET http://127.0.0.1:8000/notverbose HTTP/1.1
mitmdump[972]:      << HTTP/1.0 200 OK 16b

While a GET request to /verbose will print something similar to:

mitmdump[972]: [22:42:58.840]
mitmdump[972]: RequestHeaders:
mitmdump[972]:     Host: 127.0.0.1:8000
mitmdump[972]:     User-Agent: curl/8.14.1
mitmdump[972]:     Accept: */*
mitmdump[972]: RequestBody:
mitmdump[972]: Status:          200
mitmdump[972]: ResponseHeaders:
mitmdump[972]:     Server: BaseHTTP/0.6 Python/3.13.4
mitmdump[972]:     Date: Sun, 03 Aug 2025 22:42:58 GMT
mitmdump[972]:     Content-Type: text/plain
mitmdump[972]:     Content-Length: 13
mitmdump[972]: ResponseBody:    test2/verbose
mitmdump[972]: 127.0.0.1:53602: GET http://127.0.0.1:8000/verbose HTTP/1.1
mitmdump[972]:      << HTTP/1.0 200 OK 13b

Example

Let's assume a server is listening on port 8000 which responds a plain text response test1 and its related systemd service is named test1.service. Sorry, creative naming is not my forte.

Let's put an mitmdump instance in front of it, like so:

shb.mitmdump.instances."test1" = {
  listenPort = 8001;
  upstreamPort = 8000;
  after = [ "test1.service" ];
  extraArgs = [
    "--set" "flow_detail=3"
    "--set" "content_view_lines_cutoff=2000"
  ];
};

This creates an mitmdump-test1.service systemd service. We can then use journalctl -u mitmdump-test1.service to see the output.

If we make a curl request to it: curl -v http://127.0.0.1:8001, we will get the following output:

mitmdump-test1[971]: 127.0.0.1:40878: GET http://127.0.0.1:8000/ HTTP/1.1
mitmdump-test1[971]:     Host: 127.0.0.1:8000
mitmdump-test1[971]:     User-Agent: curl/8.14.1
mitmdump-test1[971]:     Accept: */*
mitmdump-test1[971]:  << HTTP/1.0 200 OK 5b
mitmdump-test1[971]:     Server: BaseHTTP/0.6 Python/3.13.4
mitmdump-test1[971]:     Date: Thu, 31 Jul 2025 20:55:16 GMT
mitmdump-test1[971]:     Content-Type: text/plain
mitmdump-test1[971]:     Content-Length: 5
mitmdump-test1[971]:     test1

Tests

Specific integration tests are defined in /test/blocks/mitmdump.nix.

Options Reference

id-prefix: blocks-mitmdump-options-
list-id: selfhostblocks-block-mitmdump-options
source: @OPTIONS_JSON@