Mobile apps

Spectral can capture traffic from Android apps. The process has three phases: prepare the device, patch the app, and capture traffic. The first two are one-time setup — once done, you can capture as many times as needed.

Note

iOS is not currently supported. Android is the only mobile platform with a supported capture workflow.

1. Prepare the device

Prerequisites

• adb — Android SDK Platform Tools, for communicating with the device
• java — JDK, for signing patched APKs
• WireGuard installed on the device

Enable USB debugging

On the device, go to Settings > About phone and tap Build number 7 times to unlock Developer options. Then go to Settings > Developer options and enable USB debugging. Connect the device via USB and confirm the authorization prompt.

Verify the connection:

adb devices

2. Patch the app

Replace the target app with a patched version that trusts the proxy CA:

spectral android replace com.spotify.music

This pulls the APK from the device, patches it, uninstalls the original, and installs the patched version — all in one command.

What patching does

Since Android 7 (Nougat), apps only trust system CA certificates by default and ignore user-installed ones. The patch modifies the APK’s network security configuration to trust user-installed CAs, then re-signs it with a debug key.

This is the same approach used by tools like apk-mitm. Spectral uses apk-mitm-python under the hood, which handles both single APKs and split APK bundles.

Step-by-step alternative

The replace command chains four steps. You can run them individually for more control:

# 1. Find the package name
spectral android list spotify

# 2. Pull the APK from the device
spectral android pull com.spotify.music

# 3. Patch it to trust user CAs
spectral android patch com.spotify.music.apk

# 4. Uninstall the original and install the patched version
spectral android uninstall com.spotify.music
spectral android install com.spotify.music-patched.apk

Updating patched apps

The Play Store can no longer update a patched app because the signing key has changed. To update:

1. Uninstall the patched version: spectral android uninstall com.spotify.music
2. Reinstall the original from the Play Store
3. Re-run spectral android replace com.spotify.music

Limitations

APK patching has inherent limitations. Some apps may not work correctly after patching:

• Google Sign-In breaks. Google Play Services performs Play Integrity attestation checks that fail on re-signed APKs. Apps relying on Google SSO for login will not work with patched APKs. Use -e to exclude Google domains from interception if needed.

• Signature verification. Some apps verify their own APK signature at runtime and refuse to launch if it has been tampered with. This is a common anti-tampering measure in banking and DRM-protected apps. There is no general workaround — these apps cannot be captured with this method.

• Flutter certificate pinning. Flutter apps embed their trusted CA certificates in libflutter.so rather than using the Android network security configuration. Patching the APK’s XML config has no effect on these apps. Capturing Flutter traffic requires binary patching of the Flutter engine — support for this is a work in progress.

• Certificate pinning. The patching process automatically disables the most common certificate pinning implementations: javax.net.ssl.X509TrustManager, HostnameVerifier, and OkHttp’s CertificatePinner (all major versions). However, apps using custom native pinning (C/C++ libraries) or non-standard implementations may still reject the proxy certificate.

3. Capture traffic

Start the proxy in WireGuard VPN mode:

spectral capture proxy -a spotify --wireguard -d "*.spotify.com"

The proxy displays a WireGuard configuration and QR code. Open the WireGuard app, scan the QR code, and activate the tunnel. All device traffic is routed through the proxy — no system proxy configuration needed.

The WireGuard configuration is generated once and reused across sessions. You only need to scan the QR code on the first run — after that, just toggle the existing tunnel on in the WireGuard app.

Use the app on the device. Press Ctrl+C to stop. The capture is stored in managed storage.

Auto-detect foreground app

When capturing from multiple apps, use --autodetect-app to let Spectral poll ADB for the foreground Android app and store captures separately per app:

spectral capture proxy --wireguard --autodetect-app

This removes the need for -a — each detected package gets its own capture bundle automatically.

System proxy (alternative)

If you cannot use WireGuard, configure the device to use the proxy directly: Settings > Wi-Fi, long-press your network, set the proxy to your machine’s IP on port 8080. Then start the proxy without --wireguard:

spectral capture proxy -a spotify -d "*.spotify.com"

Note that some apps (particularly Flutter apps) bypass the system proxy, making WireGuard the more reliable option.