One-Click Packet Capturing

The one-click man-in-the-middle (MITM) packet capturing feature can automatically enable a global MITM proxy on the device. The difference between this tool and other commonly used tools is that you don't need to worry about issues like certificate installation and proxy settings. You also don't have to worry about different packet capturing methods for different system versions. It works seamlessly on Android 6.0 - 14. We have handled everything for you, so you only need to focus on your specific tasks. It also supports real-time packet modification and interception. Compared to common GUI applications, it is more suitable for practical business use rather than just "capturing some packets to take a look."

Furthermore, we can guarantee that no packets will be missed (except for cases of certificate pinning), and the success rate of packet capturing is also higher than with conventional software methods. You can intercept the HTTP/S traffic of applications. It can automatically apply and revoke the MITM proxy. After exiting the script, the device and network will be restored to their original state. You don't need to perform any other setup. The script also supports international MITM packet capturing (achieved through an upstream proxy), allowing you to easily capture traffic from foreign software.

Attention

Regardless of your operating system, to ensure a successful one-time setup, please temporarily and completely disable your **network firewall** before starting packet capturing.

Prerequisites

First, ensure that your computer and the device are on the same network segment, or connected via USB. We will assume 192.168.0.2 is the IP address of the mobile device running FIRERPA. Second, make sure you have successfully cloned the project's tool code and installed the necessary dependencies. Verify that mitmproxy is installed correctly by running mitmdump in the command line.

If you don't have Python and are not familiar with cloning repositories and installing dependencies, you can download startmitm.exe from our release page. It is a packaged version of startmitm.py that allows you to perform packet capturing without installing Python. It is a console application, and its command-line arguments are the same as startmitm.py's. (This file may be flagged by antivirus software; please use it at your own discretion).

Basic Packet Capturing

Hint

The application you are trying to capture packets from may use SSL PINNING (certificate pinning) or the QUIC protocol, both of which can affect the capturing results. We automatically force a QUIC downgrade, but due to potential fallback times, the application might experience very slow network performance. Please wait a moment. Applications with certificate pinning cannot be captured directly. You will need to use reverse engineering and write a Frida script to bypass the SSL PINNING logic.

You can quickly start capturing packets with the following command. This is the simplest way to use it.

python3 -u startmitm.py 192.168.0.2

Important

**It is crucial to remember that after executing the startmitm command, you must completely close and reopen the app you want to capture packets from. Closing the app from the taskbar is not a reliable method. Please use an API to close it or use the `kill -9` command to terminate all PIDs related to the app; otherwise, capturing will not work correctly.**

Press CONTROL + C once to exit packet capturing. Please do not press it multiple times in a row.

Shared Packet Capturing

If you want to analyze packets with your colleagues on the same local network, execute the following command. Then, have your colleagues open http://your_ip_address:7890 in their browsers to see the same capture page as you, allowing you to analyze together.

python3 -u startmitm.py 192.168.0.2 --web-port 7890 --web-host 0.0.0.0

Specific Applications

If you need to intercept traffic from a specific application instead of the entire system's traffic, you can append :package_name to the IP address. The following example will only capture traffic from com.some.package.

python3 -u startmitm.py 192.168.0.2:com.some.package

Real-time Modification

You can modify the application's request and response data in real-time. This feature is based on mitmproxy's event hooks. You need to write a hook script yourself based on the mitmproxy API. For information on how to write hook scripts, please refer to the official mitmproxy documentation at docs.mitmproxy.org/stable/addons-examples and the example code at mitmproxy/examples/contrib.

Assuming you have written a hook script named http_flow_hook.py, use the following command to apply it.

python3 -u startmitm.py 192.168.0.2 -s http_flow_hook.py

Different Networks

If your mobile phone and computer are not on the same network, but you have physical access to the device, you can also capture packets via USB ADB. Ensure that the device is connected to the computer via USB ADB and has been properly authorized.

If only one ADB device is connected to the computer, use the following command to capture packets. localhost represents the ADB device.

python3 -u startmitm.py localhost

If multiple ADB devices are connected, you need to specify the ADB serial number, which can be found in the output of the adb devices command.

python3 -u startmitm.py localhost --serial bfde362

If your environment is more restrictive, for example, if the phone and the computer are not on the same network and you cannot physically access the device, you can still perform MITM as long as you can access the FIRERPA port. This scenario typically occurs when you use the built-in frp service to forward FIRERPA to a remote server, or you have forwarded FIRERPA's port 65000 to another location yourself. In this case, you and FIRERPA can only communicate directly through this single port, and other ports are not mutually accessible. In this situation, the phone cannot access any ports on your local machine, and your local machine can only access the FIRERPA port on the phone (or the phone has a public IP, but your machine is on a private network). You need to proceed as follows. (A network interconnected via OpenVPN does not fall into this category).

In this case, you need to use the following combination of steps. First, use adb_pubkey.py or call the API yourself to install your ADB public key on the device. After installation, proceed with the following steps, where x.x.x.x is the IP address that can connect to port 65000 (or 127.0.0.1), modify it according to your actual situation.

adb connect x.x.x.x:65000

Finally, proceed with the USB packet capturing method as described above.

python3 -u startmitm.py localhost

Alternatively, you can do it this way. Here, the serial is the adb connect address, not the hexadecimal serial number.

python3 -u startmitm.py localhost --serial x.x.x.x:65000

Upstream Proxy / International Packet Capturing

startmitm itself starts mitmproxy as a proxy service. By default, all traffic is sent from the local machine's network interface by mitmproxy. If you need the traffic to be sent through an upstream proxy instead of directly from your machine, you can specify an upstream proxy as follows. Only HTTP proxies are supported as upstream proxies. You also need to specify an upstream DNS server that supports TCP queries to avoid DNS pollution.

Tip

The upstream proxy mode requires mitmproxy version >= 9.0.0 (and Python >= 3.9).
python3 -u startmitm.py 192.168.0.2 --upstream http://127.0.0.1:7890 --proxy-dns 8.8.8.8

If the upstream HTTP proxy requires authentication, use the following command and replace USER:PASSWORD.

python3 -u startmitm.py 192.168.0.2 --upstream http://USER:PASSWORD@x.x.x.x:8080 --proxy-dns 8.8.8.8

All the commands above will route the device's traffic through the upstream proxy and send all local DNS queries through the proxy to 8.8.8.8.