View on GitHub


User Guide

1.1 What is PCAPdroid

PCAPdroid is an open source network capture and monitoring tool which works without root privileges. The common use cases include:

PCAPdroid leverages the android VpnService to receive all the traffic generated by the android apps. No external VPN is actually created, the traffic is processed locally by the app.

If you plan to use PCAPdroid to perform packet analysis, check out the related section below.

1.2 Basic Usage

In order to start using PCAPdroid, you just need to tap the play button in the action bar.

On the first start, a VPN confirmation dialog is shown. After accepting it, PCAPdroid will start capturing the traffic. PCAPdroid can be put in the background while operating with other apps as it continues to run as a service until the capture is stopped. As long as PCAPdroid is running, a key icon will be displayed into the android notification bar (this may vary depending on your system). Moreover, a persistent notification is shown, which includes the details about the captured traffic.

By default, an HTTP server is started on port 8080 to serve the traffic PCAP. You can visit the provided URL from another device (e.g. a PC) to start downloading the PCAP. The download is streamed so it’s normal to see a 0% download progress indicator in the browser. Only the traffic generated after the download has been started will be captured. It will finish once the stop button in PCAPdroid is pressed. Beware that any user in your local network can download a copy of your device traffic! If you want to avoid this, you can select “None” as the dump mode.

The connections made by the apps can be easily reviewed in the “Connections” tab.

Each row represents an outgoing connection made by an app or by the Android system itself. The following information will be shown:

By clicking on the connection it is possible to get more details about it.

Some details, like the IP addresses, status and statistics, are always shown. Other information, like the URL or the host, is only shown when available. Among other things, PCAPdroid tries to detect the plain text request data sent at the start of a connection, which will reported in the “Request Plaintext” row when available. For HTTP connections, for example, it will show the HTTP request sent.

During the capture, PCAPdroid logs all the connections in memory. After a limit is reached, old connections will be removed and replaced by new ones and a message indicating the number of discarded connections is shown. An overview of the traffic generated by the apps can be seen in the “Apps” view.

By pressing on an app, its details page will open, where it’s possible to review its metadata, like the installation date, version and permissions.

By clicking on the “Settings” button, the system settings for the app will open. The “Connections” button provides a shortcut to show the connections made by the app.

1.3 Filters

Before the capture is started, in the “Status” tab it is possible to specify an “App Filter” to only capture the traffic of the specified app. Only this app will be routed inside the VPNService. This is especially useful when using the TLS decryption to ensure that the mitm will only take place on the target app.

After the capture is started, PCAPdroid provides different ways to filter the displayed connections:

The “Hidden Connections” filter allows you to create rules to hide groups of connections from the “Connections” tab. By carefully building a list of “good” connections, it is possible to filter out the background noise made by the periodic connections or by the frequently used apps and only display a few relevant connections. This is particularly useful to detect unwanted or possibly malicious connections. The list is persistent.

The “Edit Filter” dialog allows you to specify filters for the connections list:

The active filters are shown via chips above the connections list, which provide a convenient way to remove existing filters.

1.4 Packet Analysis

If you need to perform a low level analysis on the L3 or L4 headers of the packets or on the size/timing of packets, then the non-root capture may not be appropriate for your task. You should instead use the root capture, which provides a 1:1 view on the traffic of your device without any modifications.

When running in non-root mode, PCAPdroid alters the network traffic, which is a required step in order to capture it via the VPNService. The modifications only affect the L3 and L4 layers of the packets, whereas the L7 data is untouched. In particular:

Moreover, in non-root mode, only outgoing connections (i.e. started by the Android device) are routed into the VPNService and captured.

For a technical explanation of why this happens, check out the how_it_works document.