Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
---
# This page was generated from the add-on.
title: 'zaptun: Android Interception'
type: userguide
weight: 1
cascade:
addon:
id: zaptun
version: 0.1.0
---

# zaptun: Android Interception

Captures all traffic of an Android emulator or rooted device in ZAP, with one click.


Pick a device in **Tools \> Android Devices...** (or click the phone button in the toolbar)
and click **Intercept**. The add-on then, over adb:

1. installs the zaptun VPN app on the device;
2. injects ZAP's root CA into the device's **system** CA store, including the Conscrypt APEX on Android 14+, and also installs it as a **user** CA;
3. forwards the device's `127.0.0.1:<port>` to ZAP's proxy with `adb reverse`;
4. starts the VPN. Every TCP connection on the device then goes through ZAP, including apps that ignore the system proxy (Flutter, OkHttp with `Proxy.NO_PROXY`, raw sockets, ...);
5. makes zaptun Android's **always-on VPN with lockdown** , so no app traffic gets around ZAP while zaptun reconnects or restarts (see [Lockdown](#lockdown)).

There's nothing to export, push or configure by hand.

## Requirements

* **adb** , from the Android SDK platform-tools. It's found automatically, or set in the [options](/docs/desktop/addons/zaptun-android-interception/options/).
* **Root on the device** , because injecting a system CA needs it: either an emulator with a "Google APIs" image ("Google Play" images can't `adb root`; the add-on runs `adb root` for you), or a rooted phone with `su` (e.g. Magisk). Grant root to "Shell" when asked.
* ZAP's proxy bound to `localhost` or all interfaces, which is the default: `adb reverse` connects to localhost.

## The Android Devices dialog

* The table lists every adb device with its Android version, how root is obtained and whether zaptun is intercepting it. **Refresh** reads it again.
* **Apps** is optional. Leave it empty to capture every app, or click **Choose...** to pick packages from the device.
* **Intercept** runs the steps above and logs each one. It's safe to click it again at any time.
* **Stop** turns lockdown off, then the VPN, and removes the `adb reverse` rule.
* **Options...** opens the [options](/docs/desktop/addons/zaptun-android-interception/options/), where adb is configured.

The system CA injection lives in RAM, so it's lost when the device reboots: click **Intercept** again after a reboot. Start or restart the app you want to capture after clicking **Intercept** : an app that's already running keeps the CA store it started with.

## Checking it works

* ZAP's History shows hostnames, not IP addresses, for HTTPS traffic from apps.
* The zaptun app on the device shows a green tick next to **System trust enabled**.
* `adb logcat -s zaptun` shows lines like `TLS api.example.com:443 → ZAP`.
* A connection that fails with `proxy said: HTTP/1.1 502 ...` means ZAP couldn't reach the destination; `Connection refused` means ZAP isn't listening on that port.

Certificate pinning isn't bypassed: apps that pin still need Frida or objection.

## Lockdown {#lockdown}

With lockdown ("Block connections without VPN" in Android's settings), apps get no network at all while the VPN is down, so ZAP misses nothing while zaptun reconnects, restarts or hasn't started yet after a boot. Only system code may change this setting, so the add-on runs a small tool from zaptun's own APK as root.

* When only some apps are captured, the other apps aren't on the VPN and lockdown would cut them off, so zaptun is always-on without lockdown.
* While lockdown is on, **Disconnect** in the app leaves apps with no network. Use **Stop** to end a session.
* If the device reboots with lockdown on, Android starts zaptun by itself, but the CA and the `adb reverse` rule are gone, so nothing gets through until you click **Intercept** again.

## What the add-on puts on the device

* The zaptun VPN app (package `dev.davidjosearaujo.zaptun`), installed from the APK bundled in the add-on, and granted `WRITE_SECURE_SETTINGS` (so it can switch Android's global proxy off while connected, and back on after) and `POST_NOTIFICATIONS`.
* ZAP's root CA and two shell scripts, pushed to `/data/local/tmp`: `inject_ca.sh` (system store) and `install_user_ca.sh` (user store).

## See also

| | | |
|---|----------------------------------------------------------------------|------------------------------------------|
| | [Options](/docs/desktop/addons/zaptun-android-interception/options/) | where zaptun finds adb |
| | [API](/docs/desktop/addons/zaptun-android-interception/api/) | intercepting devices from scripts and CI |

## Source code

The add-on, the VPN app it installs and the CA scripts: <https://codeberg.org/davidjosearaujo/zaptun>
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
---
# This page was generated from the add-on.
title: zaptun API
type: userguide
weight: 2
---

# zaptun API

Everything the Android Devices dialog does is also on the ZAP API, under the `zaptun` component, for scripts, CI and ZAP running headless. Progress and the reasons for failures are written to ZAP's log (`zap.log`).

## Views

* **devices**: every adb device, with its serial, state, model, Android version, SDK level, root method, and whether zaptun is installed and intercepting.
* **packages** (`serial`): the third-party apps installed on a device.
* **adb**: the adb binary zaptun runs.
* **optionAdbPath** , **optionSdkPath** , **optionApps**: the saved options.

## Actions

* **intercept** (`serial`, `apps`): sets the device up and starts capturing its traffic. Without a serial, the only connected device is used. `apps` is an optional, comma-separated list of package names; leave it out to capture every app.
* **stop** (`serial`): stops capturing.
* **setOptionAdbPath** , **setOptionSdkPath** , **setOptionApps**: set the options.
* **useDetectedAdb**: clears the adb and SDK paths, so adb is detected from the environment again.

## Examples

```
curl "http://localhost:8080/JSON/zaptun/view/devices/?apikey=$KEY"
curl "http://localhost:8080/JSON/zaptun/action/intercept/?apikey=$KEY&serial=emulator-5554&apps=com.example.app"
curl "http://localhost:8080/JSON/zaptun/action/stop/?apikey=$KEY&serial=emulator-5554"
curl "http://localhost:8080/JSON/zaptun/action/setOptionSdkPath/?apikey=$KEY&String=/opt/android-sdk"
```

The options can also be set when starting ZAP, e.g. `zap.sh -daemon -config zaptun.sdkPath=/opt/android-sdk`.

## See also

| | | |
|---|-----------------------------------------------------------------------------------|---------------------------|
| | [zaptun: Android Interception](/docs/desktop/addons/zaptun-android-interception/) | the add-on's main page |
| | [Options](/docs/desktop/addons/zaptun-android-interception/options/) | what the adb options mean |
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
---
# This page was generated from the add-on.
title: Options Android (zaptun) screen
type: userguide
weight: 1
---

# Options Android (zaptun) screen

This screen sets where zaptun finds adb. Open it from **Tools \> Options \> Android (zaptun)** , or with **Options...** in the Android Devices dialog.

### Android SDK

The Android SDK folder. adb is taken from its `platform-tools` folder.

### adb

The adb binary itself. If set, it takes priority over the SDK.

### Detection

When a field is empty, the screen fills it in and says where the value came from, trying in turn: `ANDROID_HOME`, `ANDROID_SDK_ROOT`, Android Studio's default SDK folders (`~/Android/Sdk`, `~/Library/Android/sdk`, `%LOCALAPPDATA%\Android\Sdk`), then `PATH`.


**Detect** fills both fields in again from the environment, replacing what's there.
**Test adb** runs `adb version` with what's in the fields, without saving them.


If you save the screen with both fields empty, zaptun keeps detecting adb from the environment
every time it runs it.

## See also

| | | |
|---|-----------------------------------------------------------------------------------|---------------------------------------|
| | [zaptun: Android Interception](/docs/desktop/addons/zaptun-android-interception/) | the add-on's main page |
| | [API](/docs/desktop/addons/zaptun-android-interception/api/) | setting these options on headless ZAP |
11 changes: 11 additions & 0 deletions site/data/addons.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -1189,6 +1189,17 @@
downloadUrl: https://github.com/zaproxy/zap-extensions/releases/download/websocket-v38/websocket-release-38.zap
date: 2026-08-07
version: 38
- id: zaptun
name: 'zaptun: Android Interception'
description: Capture all traffic of Android devices and emulators in ZAP, with one
click.
author: David Araújo
status: alpha
infoUrl: https://codeberg.org/davidjosearaujo/zaptun
repoUrl: https://codeberg.org/davidjosearaujo/zaptun
downloadUrl: https://github.com/zaproxy-addons/zaptun/releases/download/v0.1.0/zaptun-alpha-0.1.0.zap
date: 2026-11-10
version: 0.1.0
- id: zest
name: Zest - Graphical Security Scripting Language
description: A graphical security scripting language, ZAPs macro language on steroids
Expand Down
Loading