httptoolkit frida-interception-and-unpinning: automated HTTPS interception for Android and iOS

One repository, six problems to solve before any traffic is readable

Intercepting HTTPS on a mobile device is rarely one problem. It is at least six: traffic has to reach your proxy, your proxy's certificate has to be trusted, the app's pinning has to be disabled, certificate transparency checks have to be neutralised, the app must not notice any of this, and the connection must not escape over HTTP/3 where your proxy cannot see it. This repository addresses all six, and the honesty of that list is the reason to read it.

The scripts can be used together as a set or individually, hooked onto one specific feature. The README makes the difference between interception and unpinning explicit: interception is about getting traffic to your proxy and making your CA trusted, unpinning is about defeating the app's refusal to accept a CA you injected. Tools that conflate the two leave you stuck at a specific failure, and knowing which half you are missing saves hours.

The attribution is worth noting. The README badge records funding from NLnet through the NGI Zero Entrust programme, with the project link pointing at AppInterception, and the whole thing is described as part of HTTP Toolkit, a commercial product. So there is a deliberate relationship here: these scripts are the difficult part of the product, published freely because a usable reference implementation is what makes the ecosystem credible.

The tree is small and legible for a project doing this kind of work: a `config.js` for your settings, `frida-script.js`, `native-connect-hook.js` and `native-tls-hook.js` at the root, then `android/` and `ios/` directories holding platform-specific pieces, plus `test/` and `utilities/`. JavaScript is the primary language, and the licence is AGPL-3.0.

Configuring config.js with your proxy details

Setup starts with running your own MitM proxy and having a rooted device or emulator connected over ADB. Everything else follows from two values: your proxy's port and your proxy's CA certificate in PEM format. In HTTP Toolkit both appear under the Anything option on the Intercept page, and the certificate should start with the standard BEGIN CERTIFICATE marker, which is the quick way to confirm you copied the right one.

You paste both into `config.js`, using `CERT_PEM` for the certificate, `PROXY_PORT` for the port, and `PROXY_HOST` for the address as the device sees it. That last field has a useful trick. Rather than putting a LAN address in it, you can forward the port over ADB and use the loopback address:

adb reverse tcp:$PORT tcp:$PORT

This matters more than it looks. With `adb reverse`, the device's own loopback port points back at your machine, so the configuration does not change when you move between networks or switch from Wi-Fi to a USB cable.

The README also flags a practical detail about verification: after entering `su` on the device, run `whoami` and confirm it prints `root`. Frida will only run as root on a rooted device, and if that check fails, everything downstream fails in ways that look like script bugs rather than a permissions problem.

The frida command that ties the scripts together

Frida is launched against the device with `-U`, loading each script with `-l` in a specific order. The order matters: configuration first, then the native hooks, then the Android-specific pieces. This is the command the README recommends as a starting point:

frida -U \
    -l ./config.js \
    -l ./native-connect-hook.js \
    -l ./native-tls-hook.js \
    -l ./android/android-proxy-override.js

The two native hooks are the interesting part. `native-connect-hook.js` redirects socket connections at a low level rather than relying on system proxy settings, which is what makes it work on apps that ignore or override those settings. `native-tls-hook.js` intercepts TLS at the native layer, which is where most pinning checks live. The Android proxy override then handles the case where the app configures its proxy explicitly and would otherwise route around yours.

Getting Frida onto the device is a short sequence the README gives as an example rather than a recipe, since it varies by device. Download the matching `frida-server` from the Frida releases page, push it with `adb push`, then start it:

adb shell
su
chmod +x /.../frida-server
/.../frida-server

If commands fail, check `adb devices` first. That single check resolves a large share of the problems people hit here, since Frida needs both the device on and the connection established.

You also need the target package id. For a first run, the README points at the android-ssl-pinning-demo project, whose package id is `tech.httptoolkit.pinning_demo`, precisely so you can confirm the pipeline works against an app built to defeat it.

What the scripts do once they are attached

Five behaviours are listed, and each maps to a specific obstacle.

Traffic redirection happens two ways at once: system settings are modified, and all socket connections are redirected directly. Doing both covers apps that read the system proxy setting and apps that do not.

CA injection places your certificate into the system trust stores, so it is trusted by default rather than requiring the app to opt in. On Android that means user and system certificate stores, which is what separates this from the older approach of installing a user CA and hoping the app does not distinguish between the two.

Pinning patching is the hardest part, and the README is refreshingly honest about the uncertainty involved, describing it as patching many or possibly all known certificate pinning and certificate transparency tools. The wording matters: anyone who has debugged an obfuscated pinning implementation will recognise that promise as ambitious rather than absolute.

For Android there is a fallback worth understanding. If pinning is obfuscated, the first request may fail, but that failure triggers additional patching so all subsequent requests work. The cost is one failed request at startup, which is a reasonable price for the cases a static hook cannot cover.

Then there are the two mechanisms that make interception possible at all rather than merely easier. Many root and jailbreak detection checks are disabled, so the app does not simply exit. And HTTP/3 is blocked at the network layer by dropping all UDP to port 443, which forces fallback to HTTP/2 or HTTP/1. The README concedes this may be inconvenient, and it is the correct trade: a QUIC connection your proxy cannot decrypt is worse than a slightly older protocol version.

Where this sits against Frida CodeShare and community alternatives

There are other ways to unpin an Android app, and the differences matter. Frida CodeShare is the mainstream route: it serves scripts from a central service and requires no local setup beyond installing the companion app, which is far less friction for a one-off inspection. Its trade-off is that you are depending on someone else's hosted scripts and on your app's detection surface against a third-party service.

The community alternative most people compare against is Akabe1's multiple-unpinning script, which is a single well-known file for Frida that hooks common pinning methods. It is a smaller answer with a broader failure surface: when an app uses something unusual, you write the hook yourself.

This repository sits between those two and is more ambitious than both in one specific way. It is a complete pipeline rather than a single hook, covering redirect, trust injection, pinning patches, root detection and HTTP/3 blocking together, and it ships both Android and iOS variants. What it costs you is setup work: editing a config file, forwarding a port, starting a rooted server, and assembling a five-file command line.

What it does not claim is equally clear. There are no releases, no version tags and no compatibility matrix in the README, so there is nothing telling you which Frida version or Android release a given combination is known to work with. Pinning implementations change as apps are updated, and with no release history you cannot tell whether a failure is a regression or an app that has adopted a newer defence. The topic list is only five entries long, android, certificate, frida, interception and mitm, which reflects a focused repository rather than a broad toolkit.

Editorial conclusion

These scripts are the most complete public answer to a problem that is genuinely hard: getting readable HTTPS out of an app that has been told not to allow it. Use them when you have root on the device, a proxy you trust, and an app whose behaviour you are authorised to inspect, because the flow requires editing `config.js` with your own CA and rerunning the Frida command on every session. Skip them entirely for non-rooted devices or production traffic. The last push was on 2026-09-18, the repository publishes no releases, so treat `main` as the only version, and the AGPL-3.0 licence has real implications if you plan to redistribute a modified copy.

Frequently asked questions

Official sources

1. httptoolkit/frida-interception-and-unpinning on GitHub
2. Issues
3. License: AGPL-3.0
4. Project website
5. README