Table of Contents
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.
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" ];
};
Replace http with https if the server expects an HTTPS connection.
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.
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.
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 ]
}
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
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
Specific integration tests are defined in /test/blocks/mitmdump.nix.
shb.mitmdump.addons
Addons available to the be added to the mitmdump instance.
To enabled them, add them to the enabledAddons option.
Type: attribute set of string
Default:
[ ]
Declared by:
<selfhostblocks/modules/blocks/mitmdump.nix>
|
shb.mitmdump.instances
Mitmdump instance.
Type: attribute set of (submodule)
Default:
{ }
Declared by:
<selfhostblocks/modules/blocks/mitmdump.nix>
|
shb.mitmdump.instances.<name>.enabledAddons
Addons to enable on this mitmdump instance.
Type: list of string
Default:
[ ]
Example:
[ config.shb.mitmdump.addons.logger ]
Declared by:
<selfhostblocks/modules/blocks/mitmdump.nix>
|
shb.mitmdump.instances.<name>.package
The mitmproxy package to use.
Type: package
Default:
pkgs.mitmproxy
Declared by:
<selfhostblocks/modules/blocks/mitmdump.nix>
|
shb.mitmdump.instances.<name>.after
Systemd services that must be started before this mitmdump proxy instance.
You are guaranteed the mitmdump is listening on the listenPort
when its systemd service has started.
Type: list of string
Default:
[ ]
Declared by:
<selfhostblocks/modules/blocks/mitmdump.nix>
|
shb.mitmdump.instances.<name>.extraArgs
Extra arguments to pass to the mitmdump instance.
See upstream manual for all possible options.
Type: list of string
Default:
[ ]
Example:
[ "--set" "verbose_pattern=/api" ]
Declared by:
<selfhostblocks/modules/blocks/mitmdump.nix>
|
shb.mitmdump.instances.<name>.listenHost
Host the mitmdump instance will connect on.
Type: string
Default:
"127.0.0.1"
Declared by:
<selfhostblocks/modules/blocks/mitmdump.nix>
|
shb.mitmdump.instances.<name>.listenPort
Port the mitmdump instance will listen on.
The upstream port from the client’s perspective.
Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)
Declared by:
<selfhostblocks/modules/blocks/mitmdump.nix>
|
shb.mitmdump.instances.<name>.serviceName
Name of the mitmdump system service.
Type: string (read only)
Default:
"mitmdump-‹name›.service"
Declared by:
<selfhostblocks/modules/blocks/mitmdump.nix>
|
shb.mitmdump.instances.<name>.upstreamHost
Host the mitmdump instance will connect to.
If only an IP or domain is provided, mitmdump will default to connect using HTTPS. If this is not wanted, prefix the IP or domain with the ‘http://’ protocol.
Type: string
Default:
"http://127.0.0.1"
Declared by:
<selfhostblocks/modules/blocks/mitmdump.nix>
|
shb.mitmdump.instances.<name>.upstreamPort
Port the mitmdump instance will connect to.
The port the server is listening on.
Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)
Declared by:
<selfhostblocks/modules/blocks/mitmdump.nix>
|