Setup

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.

Install required Python 3 libraries

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

pip install pyperclip pathlib mitmproxy

Create the config.json file in the same directory as addon-commands.py

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/"
}

Optional key startCommandOnLocalMap

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.

Optional key stripUrlParts

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.

Optional key ignoreForLocalMapping

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"]

Use Windows Terminal/Powershell to launch mitmproxy

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

Use a mitmproxy preconfigured .bat file for Windows

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"

Load addon-commands.py on macOS/Linux

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

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

fish shell function to toggle the proxy system-wide for macOS

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.

Command overview

Command	Description
local	Map the flow to the file system. The mapped JSON file can be edited and will be used on consequent access.
l	Alias for local @focus
la	Alias for local @shown
localdelete	Delete the mapped flow on the file system
ld	Alias for localdelete @focus
lc	Delete everything in the mapped file system directory

---

copyrequest	Copy the request body
req	Alias for copyrequest @focus
copyresponse	Copy the response body
resp	Alias for copyresponse @focus
cu	Copy cURL with ```bash ticks for Markdown formatting
u	Copy full URL
ur	Copy URL behind index.php/ with the method like: `GET v1/hours/all?params…`= in Markdown code blocks
url	Copy URL behind index.php/ with the method like, but without the API URL: GET v1/hours/all
copyall	Copy cURL with the status code, response time and response body
a	Alias for copyall @focus
ab	Copy cURL with the status code and response time

---

intercept.inner	Create an intercept filter for the current flow
cept	Alias for intercept.inner @focus
r	Resume intercepted flow

---

f	Insert set view_filter into console
fc	Clear view_filter
k	View keybindings

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

The Markdown formatting is used for quick pasting into GitLab.

Local Directory Mapping

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
}