Clone this repository to ~/.mitmproxy (or copy only addon-commands.py) like this (for macOS and Linux):

git clone https://github.com/Dima-369/mitmproxy-config.git ~/.mitmproxy

You may optionally also use config.yaml or keys.yaml if you have the need for them, but they are not that interesting.

It is possible that you do not need to install the mitmproxy library:

pip install pyperclip pathlib mitmproxy

Those 2 JSON keys are mandatory and you need to set them up for your system. Here is an example how it could look like:

Note that mapLocalBaseUrls is an array and can contain multiple base URLs. But take care that the file system does not reflect this, so the mapped file is overwritten regardless of the base URL.

{
  "mapLocalBaseUrls": ["http://api.baubuddy.de/int/index.php/"],
  "mapLocalDir": "/Users/dima/vero/mitmproxy-local/"
}

Optionally, you can add the startCommandOnLocalMap array to specify a program which should be launched on command l to view the current flow. The ### string in startCommandOnLocalMap is replaced with the file path of the mapped file.

"startCommandOnLocalMap": ["notepad", "###"]

Or an example for Emacs:

"startCommandOnLocalMap": [
  "emacsclient",
  "-e",
  "(run-at-time nil nil (lambda () (x-focus-frame nil) (let (query-about-changed-file) (find-file \"###\") (revert-buffer-quick) (goto-char (point-min)))))"
]

You can also use this on Windows to open PhpStorm:

"startCommandOnLocalMap": ["C:/Program Files/JetBrains/PhpStorm 2022.1.2/bin/phpstorm64.exe", "###"]

If startCommandOnLocalMap is not present, $EDITOR is used to view the flow.

You can add stripUrlParts to replace parts of a URL via wildcard for local mapping. So if this is added to config.json:

"stripUrlParts": ["filter[editedOn][gte]"]

It means that GET v3/projects?foo=bar&filter[editedOn][gte]=2023-06-05T09:52:00Z is equivalent to GET v3/projects?foo=bar. The filter[editedOn][gte] parameter is simply ignored regardless what it contains for mapping the flow to the local file system.

If use la often to map out all shown flows, it can be useful to ignore certain flows like POST login where the token needs to be unique and mapping the response locally is rarely useful.

You can ignore those like this:

"ignoreForLocalMapping": ["POST login", "POST login/refresh"]

On Windows it could be that Windows Powershell has problems displaying mitmproxy, so use Windows Terminal instead.

You can save a .bat file with the following content to quickly start mitmproxy on the port of your choice. It is very likely that you need to start the .bat file as Administrator then, so the addon file can be correctly loaded in.

Take care to modify the paths below:

start "" "C:\Program Files (x86)\mitmproxy\bin\mitmproxy.exe" -p 9090 -s "C:\addon-commands.py"

Use mitmproxy on port 9090 and load addon-commands.py like this:

mitmproxy -p 9090 -s /path/to/addon-commands.py

function mi
    sudo networksetup -setwebproxy 'Thunderbolt Ethernet' 127.0.0.1 9090
    sudo networksetup -setwebproxy 'HUAWEI Mobile' 127.0.0.1 9090
    sudo networksetup -setwebproxy 'Wi-fi' 127.0.0.1 9090

    sudo networksetup -setwebproxystate 'Thunderbolt Ethernet' on
    sudo networksetup -setwebproxystate 'HUAWEI Mobile' on
    sudo networksetup -setwebproxystate 'Wi-fi' on

    mitmproxy -p 9090 -s ~/.mitmproxy/addon-commands.py

    sudo networksetup -setwebproxystate 'Thunderbolt Ethernet' off
    sudo networksetup -setwebproxystate 'HUAWEI Mobile' off
    sudo networksetup -setwebproxystate 'Wi-fi' off

    echo "Disabled proxy"
end

Use -setsecurewebproxystate if you need HTTPS support as well.

Those commands are invoked first by hitting : and then entering any command.

The Markdown formatting is used for quick pasting into GitLab.

Use the local command to create a JSON file. For instance, if the local command is used on GET settings/wos, it creates the file {map_local_dir}/settings/GET wos.json.

The response value can be changed, just like the headers and statusCode JSON values. On subsequent API calls, the mapped local file is used instead of the API response, so you do not need to wait for the API response.

The url and requestBody JSON values should not be changed. They are just logged for context.

{
  "response": {
    "dkeinkop": "0"
  },
  "url": "GET http://api.baubuddy.de/int/index.php/settings/wos",
  "headers": {
    "Date": "Thu, 23 Jun 2022 05:06:51 GMT",
    "Server": "Apache",
    "Vary": "Accept",
    "Cache-Control": "no-cache, must-revalidate",
    "Expires": "0",
    "X-Powered-By": "Luracast Restler v3.0.0rc5",
    "Content-Language": "en",
    "Access-Control-Allow-Origin": "https://web.baubuddy.de",
    "Content-Length": "16",
    "Content-Type": "application/json; charset=utf-8"
  },
  "statusCode": 200
}