Android Burp Suite Emulator Setup

Automated setup for Android emulator with Burp Suite proxy integration for mobile security testing and HTTPS traffic interception.

Platforms: macOS and Linux

Security Notes

⚠️ This setup is for testing purposes only:

• The emulator is rooted and has a writable system partition
• All HTTPS traffic is intercepted by Burp Suite
• System CA certificate bypasses most app security checks
• Do not use for production apps or sensitive data
• Certificate pinning may still prevent interception for some apps

What This Does

This project automates the creation and configuration of a rooted Android emulator that's ready for security testing with Burp Suite:

• ✅ Automatic Java Detection - Finds and uses Android Studio's bundled JDK or system Java
• ✅ Auto-Install SDK Tools - Downloads Android SDK command-line tools if missing
• ✅ Create Rooted AVD - Sets up a Pixel 7 API 35 emulator with writable system partition
• ✅ Burp CA Installation - Downloads and installs Burp Suite's CA certificate into system trust store
• ✅ Proxy Configuration - Automatically configures global HTTP proxy to route traffic through Burp
• ✅ No Play Store - Uses google_apis flavor to avoid Google Play Services restrictions

Prerequisites

Required

• macOS (tested on macOS Sonoma and later) or Linux (tested on Ubuntu 22.04+)
• Android Studio installed (for bundled JDK and SDK) OR standalone Android SDK
• Burp Suite running on http://127.0.0.1:8080 (for initial setup)

Optional

• Java 11+ (if not using Android Studio's bundled JDK)

Quick Start

First Time Setup

1. Configure Burp Suite - Ensure proxy listener is running on 127.0.0.1:8080

   • Verify with: curl -I http://127.0.0.1:8080/cert
   • See docs/BURP_SETUP.md for detailed instructions

2. Run installation:

   make install

   This will:

   • Detect/install Java
   • Download cmdline-tools (if needed)
   • Download Burp CA certificate from http://127.0.0.1:8080/cert
   • Install Android SDK packages
   • Create the AVD
   • Boot emulator and install CA cert
   • Configure proxy settings

Subsequent Runs

After initial setup, quickly launch the emulator:

make run

This skips the setup and directly launches the configured emulator with Burp proxy.

Stop Emulator

make stop

Verify Traffic is Being Intercepted

Once the emulator is running, test that traffic flows through Burp:

1. Check Burp's HTTP History

   • In Burp Suite, go to Proxy → HTTP history

2. Test with a Browser Request

   # Open Chrome in the emulator and visit a site
   adb shell am start -a android.intent.action.VIEW -d http://example.com

3. Or use curl from the emulator

   adb shell curl -v http://example.com

4. Check Burp

   • You should see requests appear in HTTP history
   • For HTTPS sites, you should see decrypted traffic (not encrypted)

5. Verify CA Certificate Installation

   # Check system CA store
   adb shell ls -la /system/etc/security/cacerts/ | grep -i portswigger
   # Should show a certificate file

If traffic isn't appearing:

• Verify proxy settings: adb shell settings get global http_proxy (should show 10.0.2.2:8080)
• Restart the emulator: make stop && make run
• Check Burp listener is on 127.0.0.1:8080 and running

Clean Up

To delete the AVD and start fresh:

make clean

What Gets Installed

The installation process sets up:

1. Android SDK Command-line Tools (if not present)

   • Location: ~/Library/Android/sdk/cmdline-tools/latest/ (macOS) or ~/Android/Sdk/cmdline-tools/latest/ (Linux)

2. Android SDK Packages:

   • Platform Tools (adb, fastboot, etc.)
   • Emulator
   • Android API 35 platform
   • System image: google_apis;android-35;arm64-v8a

3. Android Virtual Device:

   • Name: Pixel_7_API_35_NoPlay
   • Device: Pixel 7
   • API Level: 35
   • System: Google APIs (no Play Store)
   • ABI: arm64-v8a

4. Burp Suite Integration:

   • CA certificate downloaded from Burp
   • CA installed in system trust store (/system/etc/security/cacerts/)
   • Global HTTP proxy: 10.0.2.2:8080 (Burp from emulator's perspective)

Configuration

Edit the configuration variables in install.sh or Makefile:

# SDK Location (defaults: ~/Library/Android/sdk on macOS, ~/Android/Sdk on Linux)
SDKROOT="${ANDROID_SDK_ROOT:-${HOME}/Library/Android/sdk}"  # macOS default shown

# Android Configuration
API_LEVEL=35
IMG_FLAVOR="google_apis"          # google_apis or default (NOT google_apis_playstore)
ABI="arm64-v8a"                   # or x86_64
AVD_NAME="Pixel_7_API_${API_LEVEL}_NoPlay"
DEVICE_ID="pixel_7"

# Burp Proxy Configuration
BURP_HOST="10.0.2.2"              # Host from emulator's perspective
BURP_PORT="8080"

Why 10.0.2.2?

Android emulator's special network aliases:

• 10.0.2.2 = Host machine's localhost
• 10.0.2.15 = Emulator itself

So when the emulator connects to 10.0.2.2:8080, it reaches Burp Suite running on your host's 127.0.0.1:8080.

How It Works

Initial Setup Flow (make install or ./install.sh)

1. Java Detection

   • Checks for JAVA_HOME environment variable
   • Falls back to Android Studio's bundled JDK (platform-specific paths)
   • Falls back to system Java (macOS: /usr/libexec/java_home, Linux: common /usr/lib/jvm/ paths)
   • Exits with error if no Java found

2. Cmdline-Tools Installation (if missing)

   • Downloads platform-specific cmdline-tools from Google (macOS or Linux)
   • Extracts to ${SDKROOT}/cmdline-tools/latest/

3. CA Certificate Download

   • Attempts to download from http://127.0.0.1:8080/cert
   • Saves to certs/burp_ca.pem
   • Exits if Burp is not running

4. SDK Package Installation

   • Accepts Android SDK licenses
   • Installs platform-tools, emulator, platform, and system image

5. AVD Creation

   • Creates Pixel 7 AVD if it doesn't exist
   • Uses google_apis flavor (rootable, no Play Store)

6. Emulator Boot

   • Launches with -writable-system flag
   • Waits for boot completion
   • Roots device with adb root
   • Remounts system partition as read-write

7. Burp Integration

   • Sets global HTTP proxy to Burp
   • Converts CA cert to PEM format (if needed)
   • Computes certificate hash
   • Installs CA to /system/etc/security/cacerts/
   • Reboots to activate system CA

Quick Run Flow (make run)

1. Verifies AVD exists
2. Checks if emulator is already running
3. Launches emulator with writable system
4. Waits for boot
5. Roots and remounts system
6. Configures Burp proxy
7. Ready for testing!

Troubleshooting

"ERROR: sdkmanager not found"

Solution:

• Run make install which will offer to download cmdline-tools
• Or manually install via Android Studio: Settings → SDK Manager → SDK Tools → Android SDK Command-line Tools

"ERROR: Failed to download CA cert from Burp"

Solution:

• Ensure Burp Suite is running with proxy listener on 127.0.0.1:8080
• See docs/BURP_SETUP.md for detailed configuration
• Test the listener: curl -I http://127.0.0.1:8080/cert should return HTTP/1.1 200 OK
• Verify listener is checked as "Running" in Burp: Proxy → Options → Proxy Listeners

"ERROR: JAVA_HOME is not set and no Java installation found"

Solution:

• Install Android Studio (comes with bundled JDK)
• Or install Java 11+ manually and set JAVA_HOME
• Or set JAVA_HOME environment variable: export JAVA_HOME=/path/to/jdk

"ERROR: AVD not found" (after successful install)

Solution:

• This was caused by JAVA_HOME not being set in Makefile context (now fixed)
• Verify AVD exists:
  • macOS: ~/Library/Android/sdk/cmdline-tools/latest/bin/avdmanager list avd
  • Linux: ~/Android/Sdk/cmdline-tools/latest/bin/avdmanager list avd

Emulator won't boot or is slow

Solution:

• Close and restart: make stop then make run
• Check available disk space
• Try x86_64 ABI instead of arm64-v8a (edit ABI in config)
• Increase RAM in AVD settings

Apps don't trust the CA certificate

Solution:

• This setup installs CA as system cert (works for most apps)
• Some apps use certificate pinning (will still fail)
• Ensure emulator rebooted after CA install
• For Android 7+, some apps require network security config

File Structure

android-burp/
├── Makefile            # Convenient make targets
├── install.sh          # Full installation script
├── certs/              # Directory for Burp CA certificates
│   └── burp_ca.pem     # Downloaded from Burp Suite
├── docs/
│   └── BURP_SETUP.md   # Detailed Burp Suite configuration guide
├── .gitignore          # Ignore certs directory
└── README.md           # This file

Make Targets

Target	Description
make help	Show available targets and configuration (default)
make install	Full installation (runs install.sh)
make run	Launch emulator quickly (no setup)
make stop	Stop running emulator
make clean	Delete AVD (with confirmation)

References

• Android Developer - Emulator Networking
• Burp Suite - Installing CA Certificate
• Android SDK Command-line Tools

License

Apache 2.0 - Use at your own risk for security testing purposes.

---

Pro Tip: After setup, you can change proxy on-the-fly:

adb shell settings put global http_proxy host:port
adb shell settings delete global http_proxy  # to disable