Frida Mobile Interception Scripts

Part of HTTP Toolkit: powerful tools for building, testing & debugging HTTP(S)

This repo contains Frida scripts designed to do everything required for fully automated HTTPS MitM interception on mobile devices.

This set of scripts can be used all together, to handle interception, manage certificate trust & disabling certificate pinning & transparency checks, for MitM interception of HTTP(S) traffic on Android (iOS coming soon!) or they can be used and tweaked independently to hook just specific features.

The scripts can automatically handle:

• Redirection of traffic to an HTTP(S) proxy - modifying both system settings & directly redirecting all socket connections.
• Injecting a given CA certificate into the system trust stores.
• Patching all known certificate pinning and certificate transparency tools to allow interception by the same CA certificate.
• As a fallback: auto-detection of remaining pinning failures, to attempt auto-patching of obfuscated certificate pinning (in fully obfuscated apps, the first request may fail, but this will trigger additional patching so that all subsequent requests work correctly).

To get started:

1. Start your MitM proxy (e.g. HTTP Toolkit), and set up your rooted Android device or emulator, connected to ADB.
2. Find your MitM proxy's port (e.g. 8000) and its CA certificate in PEM format (should start with -----BEGIN CERTIFICATE-----). In HTTP Toolkit, both details can be found in the 'Anything' option on the Intercept page.
3. Open config.js, and add those details:
   • CERT_PEM: your CA certificate in PEM format
   • PROXY_PORT: the proxy's port
   • PROXY_HOST: the address of your proxy, from the perspective of your device (or use adb reverse tcp:$PORT tcp:$PORT to forward the port over ADB, and use 127.0.0.1 as the host)
4. Install & start Frida on your device (e.g. download the relevant server from github.com/frida/frida, extract it, adb push it to your device, and then run it with adb shell, su, chmod +x /.../frida-server, /.../frida-server).
5. Find the package id for the app you're interested in (for a quick test, try using github.com/httptoolkit/android-ssl-pinning-demo - the package id is tech.httptoolkit.pinning_demo)
6. Use Frida to launch the app you're interested in with the scripts injected (starting with config.js). Which scripts to use is up to you, but for Android a good command to start with is:

   frida -U \
       -l ./config.js \
       -l ./native-connect-hook.js \
       -l ./android/android-proxy-override.js \
       -l ./android/android-system-certificate-injection.js \
       -l ./android/android-certificate-unpinning.js \
       -l ./android/android-certificate-unpinning-fallback.js \
       -f $PACKAGE_ID

7. Explore, examine & modify all the traffic you're interested in! If you have any problems, please open an issue and help make these scripts even better.

The Scripts

The command above uses all the scripts, but you can generally use any subset you like, although in almost all cases you will want to include config.js as the first script (this defines some variables that are used by other scripts).

For example, to do unpinning alone, when handling proxy & certificate configuration elsewhere and without obfuscation fallbacks, you could just run:

frida -U \
    -l ./config.js \
    -l ./android/android-certificate-unpinning.js
    -f $PACKAGE_ID

Each script includes detailed documentation on what it does and how it works in a large comment section at the top. The scripts are:

• config.js

  This defines variables used by other scripts:

  • CERT_PEM - the extra CA certificate to trust, in PEM format
  • PROXY_HOST - the IP address (IPv4) of the proxy server to use (not required if you're only unpinning)
  • PROXY_PORT - the port of the proxy server to use (not required if you're only unpinning)
  • DEBUG_MODE - defaults to false, but switching this to true will enable lots of extra output that can be useful for debugging and reverse engineering any issues.

  This should be listed on the command line before any other scripts.

• native-connect-hook.js

  A low-level hook for all network connections. This ensures that all connections are forcibly redirected to the target proxy server, even those which ignore proxy settings or make other raw socket connections.

• android/

  • android-proxy-override.js

    Overrides the Android proxy settings for the target app, ensuring that all well-behaved traffic is redirected via the proxy server and intercepted.

  • android-system-certificate-injection.js

    Modifies the native Android APIs to ensure that all trust stores trust your extra CA certificate by default, allowing encrypted TLS traffic to be captured.

  • android-certificate-unpinning.js

    Modifies or disables many common known techniques for additional certificate restrictions, including certificate pinning (accepting only a small set of recognized certificates, rather than all certificates trusted on the system) and certificate transparency (validating that all used certificates have been registered in public certificate logs).

  • android-certificate-unpinning-fallback.js

    Detects unhandled certificate validation failures, and attempts to handle unknown unrecognized cases with auto-generated fallback patches. This is more experimental and could be slightly unpredictable, but is very helpful for obfuscated cases, and in general will either fix pinning issues (after one initial failure) or will at least highlight code for further reverse engineering in the Frida log output. This script shares some logic with android-certificate-unpinning.js, and cannot be used standalone - if you want to use this script, you'll need to include the non-fallback unpinning script too.

---

These scripts are part of a broader HTTP Toolkit project, funded through the NGI Zero Entrust Fund, established by NLnet with financial support from the European Commission's Next Generation Internet program. Learn more on the NLnet project page.