Skip to content

Commit d99cdf0

Browse files
TomTruyenTomTruyen
committed
feat: setup initial scripts with controller
1 parent 639f484 commit d99cdf0

File tree

4 files changed

+488
-2
lines changed

4 files changed

+488
-2
lines changed

‎README.md‎

Lines changed: 221 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,221 @@
1-
# mitm-proxy-configuration-scripts
2-
Scripts to setup mitmproxy with custom network logs capturing
1+
# 🕵️ mitmproxy Emulator & Simulator Integration
2+
3+
This repository contains helper scripts and a `mitmproxy` addon to easily intercept HTTP(S) traffic from Android emulators and iOS simulators using `mitmproxy`. It also provides control endpoints to start/stop recording and dynamically map local responses to specific request URLs.
4+
5+
---
6+
7+
## 📦 Requirements
8+
9+
- `mitmproxy` (v9+ recommended)
10+
- Android Emulator with **root access**
11+
- iOS Simulator (via Xcode)
12+
- macOS or Linux
13+
14+
---
15+
16+
## 🔧 Installation
17+
18+
### macOS
19+
20+
```bash
21+
brew install mitmproxy
22+
```
23+
24+
### Linux (Debian/Ubuntu)
25+
26+
```bash
27+
sudo apt update
28+
sudo apt install mitmproxy
29+
```
30+
31+
Verify installation:
32+
33+
```bash
34+
mitmdump --version
35+
```
36+
37+
---
38+
39+
## 📱 Android Emulator Setup
40+
41+
### ⚠️ Requirements:
42+
- Emulator must be rooted (use x86 or ARM images that support root).
43+
- Android SDK + ADB installed and configured in your `$PATH`.
44+
45+
### 🛠️ Setup Steps:
46+
47+
1. Run the script:
48+
49+
```bash
50+
chmod +x android-certificate-install.sh
51+
./android-certificate-install.sh
52+
```
53+
54+
This script will:
55+
- Ensure the mitmproxy CA certificate exists
56+
- Push the certificate to the emulator’s system certificate store
57+
- Configure proxy settings to forward traffic to mitmproxy on host (`10.0.2.2:8080`)
58+
- Reboot the emulator to apply changes
59+
60+
---
61+
62+
## 🍏 iOS Simulator Setup
63+
64+
### ⚠️ Requirements:
65+
- `xcode-select` must point to an installed Xcode
66+
- You **may** need to manually trust the certificate in:
67+
`Settings > General > About > Certificate Trust Settings`
68+
69+
If `simctl` fails:
70+
```bash
71+
sudo xcode-select -s /Applications/Xcode.app
72+
```
73+
74+
### 🛠️ Setup Steps:
75+
76+
```bash
77+
chmod +x ios-certificate-install.sh
78+
./ios-certificate-install.sh
79+
```
80+
81+
This will:
82+
- Boot or select a running iOS simulator
83+
- Install mitmproxy CA certificate into the simulator keychain
84+
- Set system proxy on macOS interfaces (used by the simulator)
85+
- Prompt you to manually trust the certificate if needed
86+
87+
### (Optional) macOS System Trust:
88+
89+
If you want your entire macOS system to trust mitmproxy (for capturing CLI tools or other apps):
90+
91+
```bash
92+
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain mitmproxy-ca-cert.crt
93+
```
94+
95+
---
96+
97+
## 🧩 mitmproxy Addon – Session Controller
98+
99+
The file `proxy-session-controller.py` is a mitmproxy addon that:
100+
101+
- Records flows while a session is active
102+
- Allows you to **start/stop recording** via HTTP API
103+
- Lets you map specific URLs to local mock response files
104+
105+
### 🚀 Usage
106+
107+
Start mitmproxy with the addon:
108+
109+
```bash
110+
mitmdump -p 8080 -s proxy-session-controller.py
111+
```
112+
113+
This starts mitmproxy with:
114+
115+
- Listening port: `8080`
116+
- Control API: `http://localhost:9999`
117+
118+
---
119+
120+
## 🛠️ Control API Endpoints
121+
122+
These endpoints allow dynamic control of recording and local response mapping.
123+
124+
### ▶️ Start Recording
125+
126+
```bash
127+
curl http://localhost:9999/start_recording
128+
```
129+
130+
### ⏹️ Stop Recording and Save
131+
132+
```bash
133+
curl http://localhost:9999/stop_recording
134+
```
135+
136+
This saves all recorded flows to `flows.json`.
137+
138+
### 🔁 Enable Local Mapping for a URL
139+
140+
```bash
141+
curl -X POST http://localhost:9999/map_local/enable \
142+
-H "Content-Type: application/json" \
143+
-d '{"url": "https://api.example.com/data", "file_path": "/absolute/path/to/response.json"}'
144+
```
145+
146+
Any requests matching the URL will return the contents of `response.json`.
147+
148+
### 🚫 Disable Mapping for a URL
149+
150+
```bash
151+
curl -X POST http://localhost:9999/map_local/disable \
152+
-H "Content-Type: application/json" \
153+
-d '{"url": "https://api.example.com/data"}'
154+
```
155+
156+
### 🔄 Clear All Mappings
157+
158+
```bash
159+
curl -X POST http://localhost:9999/map_local/disable
160+
```
161+
162+
---
163+
164+
## 📎 Notes & Edge Cases
165+
166+
- For Android: Emulator **must be rooted** to modify `/system/etc/security/cacerts`
167+
- For iOS:
168+
- `simctl keychain` may not work on all Xcode versions. If it fails, the certificate will be opened manually for trust.
169+
- You may need to **manually trust** the cert in the iOS Simulator settings
170+
- For macOS:
171+
- You can manually install the CA cert into the system keychain to capture macOS traffic too
172+
- The local mapping only works if the URL matches **exactly**, including protocol and query params.
173+
174+
---
175+
176+
## 📂 Output Example: `flows.json`
177+
178+
Each captured flow includes the method, URL, headers, and parsed JSON request/response body if possible.
179+
180+
```json
181+
[
182+
{
183+
"request": {
184+
"method": "GET",
185+
"url": "https://api.example.com/data",
186+
"headers": { ... },
187+
"body": {}
188+
},
189+
"response": {
190+
"status_code": 200,
191+
"headers": { ... },
192+
"body": { "result": "ok" }
193+
}
194+
}
195+
]
196+
```
197+
198+
---
199+
200+
## 🙌 Contributions
201+
202+
Feel free to extend this tool with more proxy automation, better cert handling, or a simple UI for the control endpoints.
203+
204+
---
205+
206+
## 🧼 Cleanup
207+
208+
To reset Android emulator proxy:
209+
210+
```bash
211+
adb shell settings put global http_proxy :0
212+
```
213+
214+
To reset macOS proxy:
215+
216+
```bash
217+
networksetup -listallnetworkservices | tail +2 | while read -r interface; do
218+
networksetup -setwebproxystate "$interface" off
219+
networksetup -setsecurewebproxystate "$interface" off
220+
done
221+
```

‎android-certificate-install.sh‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
#!/bin/bash
2+
3+
# NOTE: Must use an emulator that has Root Access (x86 or ARM images with root)
4+
5+
set -e
6+
7+
MITM_PORT=8080
8+
MITM_CERT_NAME="mitmproxy-ca-cert.crt"
9+
MITM_CERT_PATH="./$MITM_CERT_NAME"
10+
HOST_IP="10.0.2.2" # This is how emulators access the host
11+
12+
echo "[*] Starting Android emulator mitmproxy setup..."
13+
14+
# Ensure mitmproxy CA cert exists
15+
if [ ! -f ~/.mitmproxy/mitmproxy-ca-cert.pem ]; then
16+
echo "[*] Generating mitmproxy CA certificate..."
17+
mitmdump --set block_global=false --mode=transparent --listen-port=0 --quiet &
18+
sleep 2
19+
pkill -f mitmdump
20+
fi
21+
22+
# Copy cert to working directory
23+
cp ~/.mitmproxy/mitmproxy-ca-cert.pem "$MITM_CERT_PATH"
24+
25+
# Set up emulator proxy
26+
echo "[*] Setting proxy on emulator..."
27+
adb emu network delay none
28+
adb emu network speed full
29+
adb shell settings put global http_proxy "$HOST_IP:$MITM_PORT"
30+
31+
# Install cert into system cert store
32+
echo "[*] Installing CA cert in emulator system store..."
33+
adb root
34+
adb remount
35+
adb push "$MITM_CERT_PATH" /system/etc/security/cacerts/
36+
adb shell chmod 644 /system/etc/security/cacerts/$MITM_CERT_NAME
37+
38+
echo "[*] Rebooting emulator to apply certificate..."
39+
adb reboot
40+
41+
adb wait-for-device
42+
43+
echo "[✓] Android emulator is now routed through mitmproxy with trusted CA."

‎ios-certificate-install.sh‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
#!/bin/bash
2+
3+
# NOTE: If simctl does not work, then you need to select Xcode using: sudo xcode-select -s /Applications/Xcode.app
4+
5+
set -e
6+
7+
MITM_CERT_NAME="mitmproxy-ca-cert.crt"
8+
MITM_CERT_PATH="./$MITM_CERT_NAME"
9+
10+
echo "[*] Starting iOS simulator mitmproxy setup..."
11+
12+
# Ensure mitmproxy CA cert exists
13+
if [ ! -f ~/.mitmproxy/mitmproxy-ca-cert.pem ]; then
14+
echo "[*] Generating mitmproxy CA certificate..."
15+
mitmdump --set block_global=false --mode=transparent --listen-port=0 --quiet &
16+
sleep 2
17+
pkill -f mitmdump
18+
fi
19+
20+
# Copy cert locally
21+
cp ~/.mitmproxy/mitmproxy-ca-cert.pem "$MITM_CERT_PATH"
22+
23+
# Get or boot simulator
24+
BOOTED=$(xcrun simctl list devices | grep -E 'Booted' | head -1 | awk -F '[()]' '{print $2}')
25+
if [ -z "$BOOTED" ]; then
26+
echo "[*] Booting default iOS simulator..."
27+
DEVICE=$(xcrun simctl list devices available | grep 'iPhone' | head -1 | awk -F '[()]' '{print $2}')
28+
xcrun simctl boot "$DEVICE"
29+
BOOTED="$DEVICE"
30+
fi
31+
32+
echo "[*] Using simulator: $BOOTED"
33+
34+
# Try installing cert into simulator keychain
35+
if xcrun simctl keychain "$BOOTED" add-root-cert "$MITM_CERT_PATH" 2>/dev/null; then
36+
echo "[✓] Certificate installed into simulator keychain."
37+
else
38+
echo "[!] simctl keychain not available or failed."
39+
echo "[*] Opening certificate manually. You may need to trust it in Settings > General > About > Certificate Trust Settings."
40+
open -a Simulator
41+
open "$MITM_CERT_PATH"
42+
fi
43+
44+
# Optional: This only makes sense if you need to look at MacOS traffic as well.
45+
# echo "[*] Setting up CA for MacOS"
46+
# Install the CA cert into the MacOS keychain
47+
# security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain "$MITM_CERT_PATH" || {
48+
# echo "[!] Failed to add certificate to System keychain. You may need to do this manually."
49+
# echo "[!] Open the certificate in Finder and add it to the System keychain."
50+
}
51+
52+
echo "[✓] iOS Simulator CA setup complete."
53+
54+
echo "[*] Setup mitmproxy to intercept traffic:"
55+
56+
# NOTE: This sets it up for ALL network interfaces. If you want a specific one, you can modify the script.
57+
interfaces="$(networksetup -listallnetworkservices | tail +2)"
58+
59+
IFS=$'\n' # split on newlines in the for loops
60+
61+
for interface in $interfaces; do
62+
echo "[*] Setting proxy on $interface"
63+
networksetup -setwebproxy "$interface" localhost 8080
64+
networksetup -setwebproxystate "$interface" on
65+
networksetup -setsecurewebproxy "$interface" localhost 8080
66+
networksetup -setsecurewebproxystate "$interface" on
67+
done
68+
69+
echo "[✓] Proxy setup complete. You can now use mitmproxy to intercept iOS simulator traffic."
70+

0 commit comments

Comments
 (0)