Oops, software is hard! Here’s another quick release to address an issue we missed earlier today.

We’ve fixed an issue with our Meson build scripts where the modulemap dependencies were not correctly specified after the latest changes in frida-core. Specifically, core_public_h is now a custom target index, so we can’t use it directly anymore. Instead, we now depend on its parent, core_api.

Special thanks to @hsorbo for co-authoring this fix.

Exciting new release packed with performance enhancements and bug fixes across various components, especially in our Fruity backend. @hsorbo and I collaborated to bring you the following improvements:

• fruity: Boost NCM performance with multi-transfers, improving data transfer efficiency.
• fruity: Improve userspace NCM driver to perform batching, reducing packet loss in bursty situations.
• fruity: Enable lwIP TCP timestamps and SACK to align with the Linux IP stack defaults, enhancing network performance.
• fruity: Bump lwIP TCP Maximum Segment Size (MSS) to 4036 for better TCP tunnel performance.
• fruity: Account for frida-server bind() delay to improve connection establishment reliability.
• fruity: Fix crash on USB operation creation during teardown.
• fruity: Improve USB device handling on non-macOS systems by avoiding unnecessary USB access when kernel NCM is available.
• fruity: Fix direct channel reliability by ensuring connections are established correctly even when conflicting services are running. Kudos to @mrmacete for helping track this one down.

• fruity: Improve TcpTunnelConnection teardown to ensure proper cleanup upon the remote end closing the connection.

• api: Generate a proper GObject Introspection Repository (GIR), including necessary types and omitting internal ones.
• api: Avoid exposing internal types in the API.

• api: Omit APIs involving HostSession.

• build: Modify output logic to avoid redundant writes to output files, speeding up incremental builds.
• build: Avoid parsing API multiple times by leveraging Meson’s custom_target() support for multiple outputs.
• compat: Create relative subproject symlinks so the source tree can be moved without breaking builds.

• compat: Fix error-handling in compat.symlink_to() for subprojects.

• windows: Fix cpu_type_from_pid() for non-existent PIDs.
• windows: Use GetProcessInformation() on Windows 11+ to ensure correct usage of ProcessMachineTypeInfo.

As always, a huge thanks to @hsorbo and @mrmacete for their invaluable contributions in making this release possible.

Exciting new release packed with improvements and new features across platforms. Here’s what’s new:

Fruity Backend Improvements

@hsorbo and I have been working hard to enhance our Fruity backend, and we’re excited to share the following improvements:

• Added support for the TCP tunnel protocol and made it the default to match Apple’s new behavior. The FRIDA_FRUITY_TUNNEL_PROTOCOL environment variable can be used to revert back to QUIC.
• Fixed edge-case in tunnel logic for older OS versions, ensuring reliable operation even when usbmuxd is not available.
• Gracefully closed TunnelConnection to improve stability.
• Fixed a hang that could occur when a USB operation starts during teardown, preventing transfers from getting stuck.
• Fixed QuicTunnelConnection teardown logic, properly handling errors during close operations.
• Relaxed NCM interface presence check, requiring only one operational network interface.
• Adjusted to always try USB transport first, as network transport may be slower or unavailable.
• Improved handling of timeout cases when skipping jailed fallback.
• Now expect networked devices to respond quickly when connecting to the pairing service, improving the user experience when a device has gone to sleep.
• Fixed CoreDevice UDID logic for modern devices.

Android

• Gadget now supports loading assets from APKs when extractNativeLibs is set to false, improving compatibility with modern Android apps (thanks to @gergesh).
• Revived injector’s handling of shared libc ranges, ensuring correct behavior when the target process’s lowest libc.so range is a shared mapping (thanks to @lx866).

Linux

• Improved injector’s compatibility with MUSL, handling differences in the loader string (thanks to @luckycat889).
• Added support for overriding configuration when building helpers, allowing for greater flexibility in builds (thanks to @luckycat889).
• Allocated stack for injector’s remote calls, improving compatibility with programs using small stacks, such as Go applications (thanks to @ajwerner).
• Added CI that rebuilds helper binaries to ensure consistency between source and checked-in binaries (thanks to @ajwerner).
• Picked alternative temporary directories when $TMPDIR is noexec

Cross-platform

• Added support for non-UTF-8 locales in the build system, ensuring better compatibility on systems with various locale settings (thanks to @JunGe-Y).
• Added support for the PowerPC architecture in the build system.
• Added support for binary data handling in frida-inject and RpcClient internals.

Happy hacking!

Quick bug-fix release to further improve our Fruity backend, where @hsorbo and I filled up our coffee cups and hammered out the following fixes:

• fruity: Fix use-after-free in TcpConnection. The error callback might be called at a point where the PCB has already been freed. This meant that us clearing its user data would result in a use-after-free where a NULL pointer was written into the unknown.
• fruity: Fix DTXArgumentList.parse() GValue init, where we were using the wrong setter when encountering an object. This was caught by GLib’s runtime checks, but went unnoticed because we usually build without them.
• payload: Fix an AddressSanitizer build regression.

Turns out a serious stability regression made it into Frida 16.5.3, where frida-server would crash on incoming connections not originating from a CoreDevice tunnel. Kudos to @mrmacete for investigating and fixing this only hours after the problematic releases made it out. 🎉 Enjoy!

Binaries for the previous release did not make it out due to frida-node’s NAN dependency getting bumped by a script that wasn’t meant to bump it, and the latest code breaking Electron support. This release rolls it back, and bumps frida.Compiler’s @types/frida-gum to 18.7.1 while at it.

Excited to bring you another bug-fix release to further improve our Fruity backend, iOS stability, and a fix for memory scanning with regexes.

The changes mentioned without specific attribution were authored by [@hsorbo][] and I in a series of fun pair-programming sessions.

Here’s the long and short of it:

• memory: Make memory scanning regex patterns raw, so searches are reliable across binary regions that are not valid UTF-8. Thanks @mrmacete!
• web-service: Close connections of removed dynamic interfaces, to avoid them sticking around until we run out of file-descriptors.
• network-stack: Handle abrupt disposal of TcpConnection, where we would free the TCP PCB but fail to notify any live TcpIOSource instances and blocked TcpInputStream.read() calls.
• network-stack: Fix racy TCP data loss upon peer closure, where the closure resulted in us letting go of the PCB, and the recv() logic would return early because the PCB was gone. At that point there might still be data left in the RX buffer, but the application wouldn’t see it.
• network-stack: Fix race in TcpInputStream.read(), where the notify::pending-io signal fires after the call to is_readable() but before our signal handler is connected.
• fruity: Use USB product string as transport name.
• fruity: Fix USB mode parsing on iOS < 16, where the mode is a 3 byte blob.
• fruity: Bubble up USB permission errors.
• fruity: Bail on iOS tunnel service versions pre-17, instead of crashing.
• control-service: Fix reliability on CoreDevice systems, where having a single transport broker listening on all interfaces may result in an early TCP RST when trying to communicate with it from inside a tunnel. The exact cause of this is not known, but we have confirmed that having one broker per dynamic interface/tunnel does resolve the issue. We also observed that listening on all interfaces, but restricted to IPv6, also avoids the issue.
• meson: Fix i/tvOS compilation with GLib as a subproject.
• meson: Disable Fruity and friends on FreeBSD, as we now rely on a libusb API that only exists in our libusb. If anyone’s interested in these backends on FreeBSD it shouldn’t be too hard to fix this – PRs are most welcome.

Quick bug-fix release to further improve our Fruity backend, where @hsorbo and I filled up our coffee cups and hammered out the following fixes and tweaks:

• fruity: Reuse NCM peer when tunnel setup fails.
• fruity: Handle iDevice not paired with anyone.
• fruity: Handle USB TunnelConnection dropping.
• fruity: Fix unreliable modeswitch activation.
• fruity: Fix teardown when using our NCM driver.
• fruity: Fix error marshaling in find_tunnel() for non-macOS.
• fruity: Advertise our RemoteXPC protocol support.

Binaries for the previous release did not make it out due to a build regression on watchOS, which was promptly fixed by this release.

Some of you may have found yourself in a situation where a piece of data in memory looks interesting, and you want to locate the code responsible for it. You may have tried Frida’s MemoryAccessMonitor API, but found the page granularity hard to work with. That is, you might have to collect many samples until you get lucky and catch the code that accesses those specific bytes on the page that they’re on. This might be hard enough on systems with 4K pages, and even worse on modern Apple systems with 16K pages.

To address this, @hsorbo and I filled up our coffee cups and got to work, implementing support for hardware breakpoints and watchpoints. The long story short is that thread objects returned by Process.enumerateThreads() now have setHardwareBreakpoint(), setHardwareWatchpoint(), and corresponding methods to unset them at a later point. These are then combined with Process.setExceptionHandler() where you call the unset method and return true to signal that the exception was handled, and execution should be resumed.

Demo time

Let’s take these new APIs for a spin. As our target we’ll pick id Software’s brand new 2024 re-release of DOOM + DOOM II.

The first thing we might want to do is figure out where in memory the number of bullets is stored. Let’s cook up a tiny agent to help us achieve this:

let matches = [];

function scan(pattern) {
  const locations = new Set();
  for (const r of Process.enumerateMallocRanges()) {
    for (const match of Memory.scanSync(r.base, r.size, pattern)) {
      locations.add(match.address.toString());
    }
  }
  matches = Array.from(locations).map(ptr);
  console.log('Found', matches.length, 'matches');
}

function reduce(val) {
  matches = matches.filter(location => location.readU32() === val);
  console.log('Filtered down to:');
  console.log(JSON.stringify(matches));
}

function patternFromU32(val) {
  return new MatchPattern(ptr(val).toMatchPattern().substr(0, 11));
}

And load it into the game:

$ frida -n doom.exe -l demo.js
…
[Local::doom.exe ]->

We know that we have 50 bullets currently, so let’s find all heap allocations containing the value 50, encoded as a native uint32:

[Local::doom.exe ]-> scan(patternFromU32(50))
Found 6947 matches

That’s quite a few. Let’s narrow it down by firing one bullet, and checking which of those locations now contain the value 49:

[Local::doom.exe ]-> reduce(49)
Filtered down to:
["0x1fbf5191884"]

Bingo! Now that we know where in memory the number of bullets is stored, our next step is to find the code that updates the number of bullets when one is fired. Let’s add another helper function to our agent:

function installWatchpoint(address, size, conditions) {
  const thread = Process.enumerateThreads()[0];

  Process.setExceptionHandler(e => {
    console.log(`\n=== Handler got ${e.type} exception at ${e.context.pc}`);

    if (Process.getCurrentThreadId() === thread.id &&
        ['breakpoint', 'single-step'].includes(e.type)) {
      thread.unsetHardwareWatchpoint(0);
      console.log('\tDisabled hardware watchpoint');
      return true;
    }

    console.log('\tPassing to application');
    return false;
  });

  thread.setHardwareWatchpoint(0, address, size, conditions);

  console.log('Ready');
}

And call it:

[Local::doom.exe ]-> installWatchpoint(ptr('0x1fbf5191884'), 4, 'w')
Ready

Next we’ll flip back to the game and fire another bullet:

[Local::doom.exe ]->
=== Handler got system exception at 0x7ffc2bc2fabc
        Passing to application

=== Handler got single-step exception at 0x7ff6f0a21010
        Disabled hardware watchpoint

Yay, that looks promising. Let’s symbolicate that address:

[Local::doom.exe ]-> ammoCode = ptr('0x7ff6f0a21010')
"0x7ff6f0a21010"
[Local::doom.exe ]-> ammoModule = Process.getModuleByAddress(ammoCode)
{
    "base": "0x7ff6f0730000",
    "name": "DOOM.exe",
    "path": "C:\\Program Files (x86)\\Steam\\steamapps\\common\\Ultimate Doom\\rerelease\\DOOM.exe",
    "size": 15495168
}
[Local::doom.exe ]-> offset = ammoCode.sub(ammoModule.base)
"0x2f1010"

Let’s take a closer look using r2:

We can see that the program counter that we observed in our exception handler is on the instruction right after the sub that triggered our watchpoint.

So from here we can set up an inline hook that gets fired whenever a bullet is fired:

Interceptor.attach(Module.getBaseAddress('doom.exe').add(0x2f1010), function () {
  const ammoLeft = this.context.rax.add(4).readU32();
  console.log(`Shots fired! Ammo left: ${ammoLeft}`);
});

[Local::doom.exe ]-> Shots fired! Ammo left: 42
Shots fired! Ammo left: 41
Shots fired! Ammo left: 40
Shots fired! Ammo left: 39
Shots fired! Ammo left: 38

We can just as easily make ourselves a cheat for infinite ammo:

Interceptor.attach(Module.getBaseAddress('doom.exe').add(0x2f100d), function () {
  this.context.rbx = ptr(0);
  console.log(`Shots fired! Pretending no ammo was actually used`);
});

[Local::doom.exe ]-> Shots fired! Pretending no ammo was actually used
Shots fired! Pretending no ammo was actually used
Shots fired! Pretending no ammo was actually used
Shots fired! Pretending no ammo was actually used
Shots fired! Pretending no ammo was actually used

Look ma, infinite ammo!

Note that we could also have achieved this by using Memory.patchCode() to replace the sub with a 3-byte nop, which X86Writer can do for us through putNopPadding(3). The Interceptor hook has the advantage of automatically being rolled back when our script is unloaded, and makes it easy to execute arbitrary code.

Windows on ARM

Another highlight of this release is that we now support Windows on ARM. This means that an arm64 version of Frida can inject into native arm64 processes, as well as emulated x86_64 and x86 processes.

We don’t yet provide binaries however, as we’re waiting for GitHub to provide arm64 runners to OSS projects, which for now is limited to their Team and Enterprise Cloud customers. While it is technically feasible to cross-compile from an x86_64 build machine, we decided to punt on this as we quickly ran into issues with Meson’s MSVC support.

EOF

There’s also a slew of other exciting changes, so definitely check out the changelog below.

Enjoy!

Changelog

• thread: Support hardware breakpoints and watchpoints.
• fruity: Fix deadlock in perform_on_lwip_thread().
• windows: Add support for arm64.
• windows: Migrate Exceptor to Microsoft’s VEH API.
• linux: Handle process gone when detaching. Thanks @ajwerner!
• linux: Fix the clone() wrapper on MIPS.
• java: Handle Android GC cycle handlers not being exported. Thanks @thinhbuzz!
• java: Add preliminary support for OpenJDK 17 on Windows. Thanks @FrankSpierings!
• meson: Add frida-netif to the public frida-core, so frida-core devkits include all needed symbols.
• node: Add Cancellable.withTimeout() convenience factory function. Thanks @hsorbo!
• node: Add Cancellable.combine() convenience method. Thanks @hsorbo!

Quick bug-fix release to further improve our Fruity backend, where @hsorbo and I filled up our coffee cups and hammered out the following fixes:

• tunnel-connection: Wire up missing stream close logic.
• tunnel-connection: Ensure JSON request ends up in its own UDP packet. When opening the tunnel, it seems problematic if a datagram and stream data end up in the same UDP packet. We make our dummy-datagram larger to avoid this.
• tunnel-connection: Consistently avoid writes after connection is gone, which would result in a crash.
• network-stack: Handle perform_on_lwip_thread() from the lwIP thread instead of deadlocking.

Quick bug-fix release to address some issues:

• tunnel-interface-observer: Fix start() crash on i/tvOS, when SCDynamicStoreCopyKeyList() fails. Thanks @mrmacete!
• darwin-mapper: Initialize TLV before constructors. Thanks @jiska!
• darwin-mapper: Fix TLV init runtime code for arm64. Thanks @jiska!
• arm64-writer: Fix encoding of UBFM and LS{L,R}. Thanks @jiska!

Quick bug-fix release to further improve our Fruity backend:

• lockdown-client: Bubble up CONNECTION_CLOSED error. Thanks @hsorbo!
• fruity: Make find_usbmux_device() non-throwing. Thanks @hsorbo!
• fruity: Guard against lockdown open.- ->close loop.
• fruity: Fix invalidation of closed lockdown client. Thanks @hsorbo!

Quick bug-fix release to address a crash on Windows:

• fruity: Fix crash when enumerating network interfaces on Windows. Some don’t have a unicast address, and need to be ignored. Thanks @xiofee!

This release is packing a whole slew of improvements:

• fruity: Use UsbmuxDevice from USB transport if present, so we can reach the loopback interface, and for better performance.
• fruity: Handle devices without tunnel support on non-macOS.
• fruity: Expose name from USB transport if present. It has a more descriptive name in case of UsbmuxTransport.
• gumjs: Ensure Gum .a is built before building devkit. Thanks @Hexploitable!
• gumjs: Generate simpler enum value lookup code.
• spinlock: Consolidate into a single implementation.
• java: Fix art::Thread::DecodeJObject for Android >= 15. Thanks @esauvisky!

Quick bug-fix release to address a few issues:

• xpc-client: Wire up cancellable in request(), to support cancellation of remotepairingd requests in our Fruity macOS CoreDevice backend.
• java: Properly handle the Android ART CMC GC strategy. Thanks @mbricchi!
• java: Fix Java.choose() on newer ART APEXes. Thanks @mbricchi!

This release is packing a whole slew of improvements:

• darwin: Handle dyld restart on macOS Sequoia and iOS 18.
• darwin: Await ObjC init on macOS Sequoia and iOS 18, by making use of notifyObjCInit() if available.
• fruity: Improve CoreDevice pairing support:
  • Fix support for multiple pairing relationships.
  • Keep the in-memory peer store up-to-date, so new pairing relationships don’t require a process restart to be able to match them up with pairing services on the network.
• ncm: Detach all drivers before changing configuration.
• ncm: Avoid using a broken kernel NCM driver.
• darwin: Fix sysroot on simulator. Thanks @CodeColorist!
• darwin-mapper: Locally resolve shared cache symbols, to avoid resolver functions when possible, side-stepping our existing issue where the generated constructor function tries to write the result to a read-only page.
• gumjs: Fix race in recv().wait() on application thread. Thanks @HexKitchen!
• python: Eliminate usage of unstable ref-counting APIs, so extensions built with newer Python headers still work on older Python runtimes.

This release is packing a whole slew of improvements:

• fruity: Add support for networked devices on Windows and Linux.
• ncm: Switch USB device configuration if needed.
• network-stack: Fix TcpConnection use-after-free.
• fruity: Fix the LWIP.NetworkInterface bindings.
• fruity: Remove forgotten .pcap debug output.
• dtx: Fix teardown of DTXConnection vs. DTXChannel.
• buffer: Add content validation to read_string().
• buffer: Add content validation to read_fixed_string().
• java: Fix Java.choose() on Android >= 14. Thanks @mbricchi!
• java: Handle the CMC GC strategy. Thanks @mbricchi!

Quick bug-fix release with a couple of Fruity backend refinements:

• fruity: Handle libusb failing to initialize.
• fruity: Clean up OS-specific bits.

Quick bug-fix release to address a couple of issues:

• device: Fix property getters for id and name.
• socket: Fix Host header logic in negotiate_connection().

This release is packing some exciting new things. Let’s dive right in.

CoreDevice

As mentioned in the 16.3.0 release notes, @hsorbo and I were working on submitting a patch for the Linux kernel’s CDC-NCM driver to make it compatible with Apple’s private network interface. This has since gone upstream, and will be part of Linux 6.11.

In the meantime, and for those of you using Frida on Windows, we have just implemented a minimal user-mode driver that Frida now uses when it detects that the kernel doesn’t provide one. We leveraged lwIP to also do Ethernet and IPv6 entirely in user space. The result is that Frida can support CoreDevice on any platform supported by libusb.

EOF

There’s also a bunch of other exciting changes, so definitely check out the changelog below.

Enjoy!

Changelog

• fruity: Rework to support userspace CDC-NCM.
• fruity: Add support for dyld restart on iOS >= 18.
• fruity: Await ObjC runtime initialization on iOS >= 18.
• fruity: Fix gadget upload when no usbmux connection is available.
• fruity: Improve open_channel() to support tcp:service-name.
• fruity: Retry RSD port lookup on failure.
• fruity: Revive HostChannelProvider implementation.
• fruity: Skip fetching dyld symbols if libSystem is initialized.
• fruity: Wire up MacOSCoreDeviceTransport event handling.
• fruity: Fix the macOS CoreDevice connection type logic.
• fruity: Add os.build and hardware to the exposed system parameters. Thanks @as0ler!
• server and gadget: Listen on Apple’s CoreDevice tunnel network interfaces on iOS and tvOS.
• xpc-service: Fix handling of request() with arrays. Thanks @hsorbo!
• xpc-service: Support type-annotating request parameters.
• python: Support unmarshaling tuples to GVariant.
• python: Fix unmarshaling of bool to GVariant.
• node: Support type-annotations when marshaling to GVariant.
• node: Bump Node.js requirement to >=16 || 14 >=14.17, to match minimatch.
• java: Fix registerClass() field item ordering on Android. Thanks @eybisi!

The previous release didn’t make it out due to a CI issue. The only change in this release is the CI fix needed. (One of the FreeBSD runner images had just been removed by the CI provider, so we had to bump to a newer one.)

It’s time for another bug-fix release. Quite a few goodies in this one:

• darwin: Avoid thread_set_state() during injection, so we don’t get killed by the system on e.g. macOS >= 14.5. Thanks @_saagarjha for contributing the first draft of the fix!
• fruity: Perform RSDCheckin on services that need it. In this way we retain backwards-compatibility for open_channel() of lockdown services when a CoreDevice tunnel is available.
• fruity: Stop caching the LockdownClient, to avoid issues with multiple consumers. Reproducible using frida-ps with a jailed iOS device connected.
• python: Fix the open_service() plist example.
• node: Fix spawn() options logic for undefined values. Kudos to @as0ler for reporting and helping track this one down!
• node: Skip undefined when marshaling aux options to GVariant.
• node: Skip undefined when marshaling object to GVariant.
• node: Handle errors when marshaling to GVariant.
• node: Fix the openService() plist example.

Kudos to @hsorbo for the fun and productive pair-programming on all of the above! 🙌

Note: This release never made it out due to a CI issue, addressed in 16.3.3.

Just a quick bug-fix release to address a packaging issue with our Node.js bindings. The uploaded prebuilds weren’t stripped and exported symbols they weren’t meant to export. Kudos to 0xDC00 for reporting.

Enjoy!

This release is packing some exciting new things. Let’s dive right in.

CoreDevice

Starting with iOS 17, Apple moved to a new way of communicating with services on the iDevice side, including their Developer Disk Image (DDI) services. Their new way of doing things unifies how Apple software talks to other Apple devices, and is known as CoreDevice. It seems to have originated back when Apple introduced their T2 coprocessor. Cisco’s DUO team published some excellent research on this back in 2019.

Like with the T2, the new stack used for iOS also uses RemoteXPC for talking to services. Things are a bit more complex though, because unlike the T2, mobile devices don’t have a persistent connection to macOS, and also have the notion of pairing. Luckily for us, @doronz88 had already done an amazing job reversing and documenting most of what we needed to implement the new protocols, so that saved us a lot of time.

Even so, it was a massive undertaking, but tons of fun – @hsorbo and I had a blast pair-programming on it. Quite a few moving parts are involved, so let’s take a quick walk through them.

With an iDevice plugged in, it exposes a USB CDC-NCM network interface, known as the “private” interface. It also exposes an interface used for tethering, just like it did in the past – except back then it was using a proprietary Apple protocol instead of CDC-NCM.

This is where we hit the first challenges trying to talk to it from a Linux host. First off, the iOS device needs a USB vendor request to mode-switch it into exposing the new interfaces. This part is easy, as the usbmuxd daemon can do this for us if we set the environment variable USBMUXD_DEFAULT_DEVICE_MODE to 3. So far so good.

The next challenge was that the Linux kernel’s CDC-NCM driver failed to bind to the device. After a bit of debugging we discovered that it was due to the private network interface lacking a status endpoint. The status endpoint is how the driver gets notified about whether a network cable is plugged in. Apple’s tethering network interface has such an endpoint, and it makes sense there – if tethering is disabled it’s just as if the cable is unplugged. But the private interface is always there, so understandably Apple chose not to include a status endpoint for it.

We quickly developed a kernel driver patch to lift the requirement for a status endpoint, and this got it working. Later we realized that we should still require a status endpoint for the tethering interface, so we ended up refining our patch a bit further. The plan is to submit that in the next few days.

Anyway, with the network interface up, the host side uses mDNS to locate the IPv6 address where a RemoteServiceDiscovery (RSD) service is listening. The host connects to it and speaks HTTP/2 with RemoteXPC messages going back and forth. This particular service, RSD, tells the host which services are available on the private interface, the port numbers they’re listening on, and details like the protocol each uses to communicate.

Then, knowing which services are listening on which ports, the host looks up the Tunnel service. This service lets the host establish a tunnel to the device, acting as a VPN to allow it to communicate with the services inside that tunnel. Since setting up such a tunnel requires a pairing relationship between the host and the device, it means that the services inside the tunnel allow the host to do a lot more things than the services outside the tunnel.

The base protocol is the same as with RSD, and after some back and forth involving a pairing parameters binary blob and some cryptography, a pairing relationship is either created or verified. At this point the two endpoints are using encrypted communications, and the host asks the Tunnel service to set up a tunnel listener.

Now, assuming the host asked for the default transport, QUIC, the host goes ahead and connects to it. We should note that the the Tunnel service also supports plain TCP. Presumably that is there for older macOS versions that don’t come with a QUIC stack. Another thing worth mentioning is that the Tunnel service provides the host with a keypair, so it uses that as part of the connection setup.

Once connected, the device sends the host some data across a reliable stream. The data starts with an 8 byte magic, “CDTunnel”, followed by a big-endian uint16 that specifies the size of the payload following it. The payload is JSON, and tells the host which IPv6 address the host’s endpoint inside the tunnel has, along with the netmask and MTU. It also tells the host its own IPv6 address inside the tunnel, and the port that the RSD service is listening on.

The host then sets up a TUN device configured as it was just told, and starts feeding it unreliable datagrams as they’re received from the QUIC connection. And for data in the other direction, whenever there’s a new packet from the TUN device, the host feeds that into the QUIC connection.

So at this point the host connects to the RSD endpoint inside the tunnel, and from there it can access all of the services that the device has to offer. The beauty of this new approach is that clients communicating with device-side services don’t have to worry about crypto, nor provide proof of a pairing relationship. They can simply make plaintext TCP connections on the tunnel interface, and QUIC handles the rest transparently.

What’s even cooler is that the host can establish tunnels across both USB and WiFi, and because of QUIC’s native support for multipath, the device can seamlessly move between wired and wireless without disrupting connections to services inside the tunnel.

So, once we got all of this implemented we were feeling excited and optimistic. Only part left was to do the platform integrations. And uhh yeah, that’s where things got a lot harder. The part that got us stuck for a while was on macOS, where we realized we had to piggyback on Apple’s existing tunnel. We discovered that the Tunnel service would refuse to talk to us when there’s already a tunnel open, so we couldn’t simply open up a tunnel next to Apple’s.

While we could ask the user to send SIGSTOP to remoted, allowing us to set up our own tunnel, it wouldn’t be a great user experience. Especially since any Apple software wanting to talk to the device then wouldn’t be able to, making Xcode, Console, etc. a lot less useful.

It didn’t take us long to find private APIs that would allow us to determine the device-side address inside Apple’s tunnel, and also create a so-called “assertion” so that the tunnel is kept open for as long as we need it. But the part we couldn’t figure out was how to discover the device-side RSD port inside the tunnel.

We knew that remotepairingd, running as the local user, knows the RSD port, but we couldn’t find a way to get it to tell us what it is. After lots of brainstorming we could only think of impractical solutions:

• Port-scan the device-side address: Potentially slow, and faster implementations would require root for raw socket access.
• Scan remotepairingd’s address space for the device-side tunnel address, and locate the port stored near it: Wouldn’t work with SIP enabled.
• Rely on a device-side frida-server to figure things out for us: This wouldn’t work on jailed iOS, and would be complex and potentially fragile.
• Grab it from the syslog: Could take a while or require a manual user action, and forcing a reconnection by killing a system daemon would result in disruption.
• Give up on using the tunnel, and move to a higher level abstraction, e.g. use MobileDevice.framework whenever we need to open a service: Would require us to possess entitlements. Exactly which depend on the particular service. So for example if we’d want to talk to com.apple.coredevice.appservice, we’d need the com.apple.private.CoreDevice.canInstallCustomerContent entitlement. But, trying to give ourselves a com.apple.private.* entitlement just wouldn’t fly, as the system would kill us as only Apple-signed programs can use such entitlements.

This was where we decided to take a break and focus on other things for a while, until we finally found a way: The remoted process has a connection to the RSD service inside the tunnel. We finally arrived at a simple solution, using the same API that Apple’s netstat is using:

foreach (var item in XNU.query_active_tcp_connections ()) {
	if (item.family != IPV6)
		continue;
	if (!item.foreign_address.equal (tunnel_device_address))
		continue;
	if (Darwin.XNU.proc_pidpath (item.effective_pid, path_buf) <= 0)
		continue;
	if (path != "/usr/libexec/remoted")
		continue;

	try {
		var connectable = new InetSocketAddress (tunnel_device_address, item.foreign_port);

		var sc = new SocketClient ();
		SocketConnection connection = yield sc.connect_async (connectable, cancellable);
		Tcp.enable_nodelay (connection.socket);

		return yield DiscoveryService.open (connection, cancellable);
	} catch (GLib.Error e) {
	}
}

The Linux side of the story was a lot easier though, as there we are in control and can set up a tunnel ourselves. There was one challenge however: We didn’t want to require elevated privileges to be able to create a tun device. The solution we came up with was to use lwIP to do IPv6 in user-mode. As we had already designed our other building blocks to work with GLib.IOStream, decoupled from sockets and networking, all we had to do was implement an IOStream that uses lwIP to do the heavy lifting. Datagrams from the QUIC connection get fed into an lwIP network interface, and packets emitted by that network interface are fed into the QUIC connection as datagrams.

Next up was the Windows side of things. We did some digging and quickly realized that Apple’s software doesn’t currently set up a tunnel. The official driver also appears to keep the USB device busy, meaning we can’t easily trigger a mode-switch and do things ourselves. There’s probably an elegant solution to the Windows part of the puzzle, but we realized we were already so deep inside the rabbit-hole that it would be wise to leave this for later. So if anyone reading this is interested in helping out, please do get in touch.

Another area that needs future improvement is that we only support cabled connectivity on macOS. This should be easy to improve on once we have updated frida-server and frida-gadget so they listen on tunnel interfaces whenever they appear.

Jailed iOS 17

With the new CoreDevice infrastructure in place, we have also restored support for jailed instrumentation on iOS 17. This means we can once again spawn (debuggable) apps on latest iOS, which is 17.5.1 at the time of writing. We still have the issue where attach() without spawn() doesn’t work, as our jailed injector doesn’t yet support the restartable dyld case when attaching to an already running app. This will be addressed in a future release.

Device.open_service() and the Service API

Given that Frida needs to speak quite a few protocols to interact with Apple’s device-side services, and applications also sometimes need other such services, this presents a challenge. Applications could speak these protocols themselves, e.g. after using the Device.open_channel() API to open an IOStream to a specific service. But this means they have to duplicate the effort of implementing and maintaining the protocol stacks, and for protocols such as DTX they may be wasting time establishing a connection that Frida already established for its own needs.

One possible solution would be to make these service clients public API and expose them in our language bindings. We would also have to implement clients for all of the Apple services that applications might want to talk to. That’s quite a few, and would result in the Frida API becoming massive. It would also make Frida a kitchen sink of sorts, and that’s clearly not a direction we want to be heading in.

After thinking about this for a while, it occurred to me that we could provide a generic abstraction that lets the application talk to any service that they want. So last week @hsorbo and I filled up our coffee cups and got started on just that.

Here’s how easy it is to talk to a RemoteXPC service from Python:

import frida
import pprint

device = frida.get_usb_device()

appservice = device.open_service("xpc:com.apple.coredevice.appservice")
response = appservice.request({
    "CoreDevice.featureIdentifier": "com.apple.coredevice.feature.listprocesses",
    "CoreDevice.action": {},
    "CoreDevice.input": {},
})
pprint.pp(response)

And the same example, from Node.js:

import frida from 'frida';
import util from 'util';

const device = await frida.getUsbDevice();

const appservice = await device.openService('xpc:com.apple.coredevice.appservice');
const response = await appservice.request({
  'CoreDevice.featureIdentifier': 'com.apple.coredevice.feature.listprocesses',
  'CoreDevice.action': {},
  'CoreDevice.input': {},
});
console.log(util.inspect(response, {
  colors: true,
  depth: Infinity,
  maxArrayLength: Infinity
}));

Which results in:

So now that we’ve looked at the new open_service() API being used from Python and Node.js, we should probably mention that it is (almost) just as easy to use this API from C:

#include <frida-core.h>

int
main (int argc,
      char * argv[])
{
  GCancellable * cancellable = NULL;
  GError * error = NULL;

  frida_init ();

  FridaDeviceManager * manager = frida_device_manager_new ();

  FridaDevice * device = frida_device_manager_get_device_by_type_sync (manager, FRIDA_DEVICE_TYPE_USB, -1, cancellable, &error);
  FridaService * service = frida_device_open_service_sync (device, "xpc:com.apple.coredevice.appservice", cancellable, &error);

  GVariant * parameters = g_variant_new_parsed ("{"
    "'CoreDevice.featureIdentifier': <'com.apple.coredevice.feature.listprocesses'>,"
    "'CoreDevice.action': <@a{sv} {}>,"
    "'CoreDevice.input': <@a{sv} {}>"
  "}");
  GVariant * response = frida_service_request_sync (service, parameters, cancellable, &error);

  gchar * str = g_variant_print (response, FALSE);
  g_printerr ("%s\n", str);

  return 0;
}

(Error-handling and cleanup omitted for brevity.)

The string passed into open_service() is the address where the service can be reached, which starts with a protocol identifier followed by colon and the service name. This returns an implementation of the Service interface, which looks like this:

public interface Service : Object {
	public signal void close ();
	public signal void message (Variant message);

	public abstract bool is_closed ();
	public abstract async void activate (Cancellable? cancellable = null) throws Error, IOError;
	public abstract async void cancel (Cancellable? cancellable = null) throws IOError;
	public abstract async Variant request (Variant parameters, Cancellable? cancellable = null) throws Error, IOError;
}

(Synchronous methods omitted for brevity.)

Here, request() is what you call with a Variant, which can be “anything”, a dictionary, array, string, etc. It is up to the specific protocol what is expected. Our language bindings take care of turning a native value, for example a dict in case of Python, into a Variant. Once request() returns, it gives you a Variant with the response. This is then turned into a native value, e.g. a Python dict.

For protocols that support notifications, the message signal is emitted whenever a notification is received. Since Frida’s APIs also offer synchronous versions of all methods, allowing them to be called from an arbitrary thread, this presents a challenge: If a message is emitted as soon as you open a specific service, you might be too late in registering the handler. This is where activate() comes into play. The service object starts out in the inactive state, allowing signal handlers to be registered. Then, once you’re ready for events, you can either call activate(), or make a request(), which moves the service object into active state.

Then, later, to shut things down, cancel() may be called. The close signal is useful to know when a Service is no longer available, e.g. because the device was unplugged or you sent it an invalid message causing it to close the connection.

It’s also easy to talk to DTX services, which is RemoteXPC’s predecessor, still used by many DDI services.

For example, to grab a screenshot:

import frida

device = frida.get_usb_device()

screenshot = device.open_service("dtx:com.apple.instruments.server.services.screenshot")
png = screenshot.request({"method": "takeScreenshot"})
with open("/path/to/outfile.png", "wb") as f:
    f.write(png)

But there’s more. We also support talking to old-style plist services, where you send a plist as the request, and receive one or more plist responses:

import frida

device = frida.get_usb_device()

diag = device.open_service("plist:com.apple.mobile.diagnostics_relay")
diag.request({"type": "query", "payload": {"Request": "Sleep", "WaitForDisconnect": True}})
diag.request({"type": "query", "payload": {"Request": "Goodbye"}})

As you might have already guessed, this example puts the connected iDevice to sleep.

RPC Binary Passing

Those of you using Gum’s JavaScript bindings might be familiar with our RPC API, which makes it easy for an application to call functions on its agent.

One long-standing limitation with this feature was that you couldn’t pass binary data into an exported function – you would have to serialize it somehow. This is now finally supported.

For example given the following agent:

rpc.exports.hello = (name, icon) => {
  console.log(`Name: "${name}"`);
  console.log('Icon:');
  console.log(hexdump(icon, { ansi: true }));
};

You can now call hello() from Python like this:

script.exports_sync.hello("Joe", b"\x13\x37")

Which would output:

Note that only one binary parameter can be passed, and it needs to be the last parameter.

Another improvement in the same area is that you can now return binary data alongside a JSON-serializable JavaScript value. We previously only supported returning one or the other. This is now also finally supported.

For example given the following agent:

rpc.exports.peek = name => {
  const module = Process.getModuleByName(name);
  const header = module.base.readByteArray(64);
  return [module, header];
};

You can call peek() from Python like this:

module, header = script.exports_sync.peek("libSystem.B.dylib")
print("module:", module)
print("header:", header)

Which, if run on a platform where libSystem.B.dylib is present, might output something like:

module: {'name': 'libSystem.B.dylib', 'base': '0x18ec70000', 'size': 8192, 'path': '/usr/lib/libSystem.B.dylib'}
header: b'\xcf\xfa\xed\xfe\x0c\x00\x00\x01\x02\x00\x00\x80\x06\x00\x00\x006\x00\x00\x00\x10\x10\x00\x00\x85\x00\x00\x82\x00\x00\x00\x00\x19\x00\x00\x00(\x02\x00\x00__TEXT\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00@\x0c\x8d\x01\x00\x00\x00'

EOF

There’s also a few other exciting changes, so definitely check out the changelog below.

Enjoy!

Changelog

• Add device.open_service(address), which provides a Service implementation that exposes device-specific services through a uniform interface.
• fruity: Add RemoteXPC support, with open_service() implemented for three protocols IDs: plist, dtx, xpc.
• fruity: Fix spawn() on jailed iOS 17.
• fruity: Improve DTX protocol support.
• python: Add open_service() and Service API.
• python: Add support for new RPC binary data passing.
• python: Improve GVariant marshaling support.
• node: Add openService() and Service API.
• node: Add support for new RPC binary data passing.
• node: Improve GVariant marshaling support.
• exceptor: Add SA_ONSTACK flag in the POSIX backend. Thanks @asabil!
• gumjs: Support receiving binary data in RPC methods.
• gumjs: Support returning value and binary data from RPC methods.
• gumjs: Expose more Memory APIs to CModule. Thanks @hillelpinto!
• plist: Fix support for writing out binary plist with float and double values.

Kudos to @hsorbo for the fun and productive pair-programming on all of the above changes without specific attribution! 🙌

A quick bug-fix release with three improvements:

• ci: Fix the frida-node prebuild loop for macOS, so we generate prebuilds for all targets, not just the first one.
• node: Avoid relying on package-lock.json, to support fallback build when prebuild is missing.
• android: Set DexFile to read-only in Java.registerClass(). As of Android 14, apps with targetSdk >= 34 are not allowed to have writable permissions on dynamically loaded Dex files. Thanks @pandasauce!

Enjoy!

Just a quick bug-fix release to fix a regression in the DebugSymbol API on Windows, where we failed to bundle the DbgHelp and SymSrv libraries. Kudos to 0xDC00 for reporting this so quickly.

Enjoy!

Just a quick bug-fix release to fix a regression affecting iOS users. Kudos to @andyacer and @IhorLeshko for reporting this so quickly.

Enjoy!

It’s release o’clock, and this one comes jam-packed with improvements! 🎉

Build System

After years of being dissatisfied with our build system situation, I have finally worked up the courage to restructure it — in a big way.

User Experience

One of the things that bothered me was that our build system felt very eccentric and complex. You would invoke make and see a menu of things you could build. But that menu would be different depending on the OS you’re running this on. Changing build options meant either editing config.mk or overriding them on the command-line. And if you were on Windows you’d have to use Visual Studio (MSVS).

The MSVS build system is now gone, and you can build Frida the same way you’d build many other OSS projects:

$ ./configure
$ make

The configure step can be skipped if you don’t need to pass any options, such as –prefix. This script is really just a thin wrapper around Meson’s setup command, and you can pass options straight to Meson by adding -- followed by the options. You can also run make install to install things, which supports the DESTDIR environment variable to change where the output goes.

Cross-compilation is easy too; for example if you want to build for iOS/arm64, invoke configure with –host=ios-arm64. If you have a toolchain for an embedded system, pass –host=$triplet, which will look for $triplet-gcc, $triplet-g++, etc. on your PATH. You can also add CFLAGS, LDFLAGS, etc. to the environment to pass in extra flags, just like you’d expect from other build systems.

What’s cool is that our different repos can now be built standalone. You can clone the frida-gum repo and build it, just like you can do with frida-python, frida-tools, etc. The frida repo is no longer as important, it’s only kept around to be able to version a collection of repos, and host the CI used for rolling new releases.

Each repo contains any needed subprojects/*.wrap files that tell Meson where it can find the dependencies. This means if you grab frida-core and try to build it without already having frida-gum on your PKG_CONFIG_PATH, it will grab and build that for you automatically. What’s also neat is that our Python and Node.js bindings now make use of this to build from source if a .whl or prebuild can’t be found or downloaded.

So now that our different components work well as subprojects, this also means anyone can integrate Frida components into their own projects just as easily. All you need to do is add a .wrap-file to subprojects/ in your project’s top source dir, and call dependency() from your meson.build. Meson then looks on your system first, and if it fails to find the dependency it will clone the git repo in subprojects/ and build it as part of your project. It is also possible to tell Meson to force such a fallback without looking on your system.

Here’s what such a .wrap-file could look like for Gum:

[wrap-git]
url = https://github.com/frida/frida-gum.git
revision = 16.2.4
depth = 1

[provide]
dependency_names = frida-gum-1.0, frida-gum-heap-1.0, frida-gum-prof-1.0, frida-gumjs-1.0, frida-gumjs-inspector-1.0

And for frida-core:

[wrap-git]
url = https://github.com/frida/frida-core.git
revision = 16.2.4
depth = 1

[provide]
dependency_names = frida-core-1.0

Our thin Meson wrapper is also easy to get started with, and you can read more about it here.

A bit of history

The reason I chose to maintain a separate build system for Windows was that I previously worked with quite a few experienced Windows developers, and noticed they’d be a lot more excited about an OSS project if they could work on it using their favorite IDE. It was important to them that they could look at a crash in the debugger, jump to a frame belonging to an OSS library, and be able to add some temporary logging code. And then hit the “Run” hotkey to have the IDE incrementally compile and relink everything, for a short and sweet feedback loop.

At the time, Frida’s non-Windows build system was autotools. We later moved to Meson. Although Meson has a backend for MSVS, meaning we could have it generate MSVS project files for us, there was one issue blocking us from doing that. Unlike MSVS, where you can mix projects targeting different machines in the same “solution” (workspace), Meson only supports compiling for one machine at a time, in addition to the build machine. Due to how Frida supports injecting code into e.g. both 32- and 64-bit targets on Windows, we would introduce a usability regression if we were to remove our MSVS build system. So because of this I hesitated to drop the MSVS build system.

We also had the same challenge on non-Windows. I ended up solving it by writing a Makefile that invokes Meson for each architecture, to glue it all together. While this did work, I never got it to the point where incremental builds would also work reliably. However, late March this year I finally settled on a way to solve this locally in frida-core – the only component where we need this kind of multi-arch madness. By recursively invoking Meson from a custom_target() we can build the needed components for the other architectures.

This took a lot of work to get working right, but once there it made things so much more pleasant to work with in the rest of the stack. The frida repo’s Makefiles and shell-scripts could be dropped and replaced with Meson. The CI became simpler and more uniform. Anyone can just clone the frida-core repo and run make, and the resulting binaries would support cross-arch. (Unless explicitly disabled through –disable-compat / -Dfrida-core:compat=disabled.)

Now you might be wondering why we’re still running make, if we’re now only using Meson. I ended up writing a thin wrapper around Meson that automates the downloading of prebuilt dependencies, choosing sensible linker flags for smaller binaries, etc. The new configure and Makefile files in each repo take care of invoking releng/meson_configure.py and releng/meson_make.py, which constitute the thin wrapper around Meson. The releng directory is a submodule, shared by Frida’s repos. The other thing done before invoking the wrapper, is to also make sure the releng submodule has been initialized and updated.

Maintenance

Before this release we were maintaining seven different build systems:

1. Meson (main components, on non-Windows)
2. Visual Studio (main components, on Windows)
3. GNU Make (main components meta build system, on non-Windows)
4. setuptools (Python bindings)
5. GYP (Node.js bindings)
6. Xcode (Swift bindings)
7. QMake (QML bindings)

As of this release, I am excited to announce that we are down to just one build system: Meson.

The main pain point with the previous situation was having to deal with both 1) and 2), since they were involved in all of the main components. This meant that something as simple as adding a source file would require knowledge of two different build systems. Not only that, but contributors on Linux for example, would typically have a hard time testing their Visual Studio build system changes.

Another aspect was that developers would be less inclined to refactor their code if something as simple as adding a new file involves dealing with two build systems. The long-term consequence of this was that it fostered bad habits. “Hmm, I should split this out into a separate file, but uhh… no, that’s too painful, I’m gonna add that code here for now.”

As for the remaining build systems, only used in bindings, it may not seem that bad to maintain those – they’re typically familiar to the folks touching that code anyway. The challenge there was the lack of pkg-config integration in all but one of them (QMake). This meant that include paths, library paths, and libraries to link with would end up being duplicated in multiple places. This is particularly gnarly when linking with a static library that uses other libraries internally, which is how our language bindings typically consume frida-core.

New Features

Quite a few new things to be excited about in this release:

• gumjs: Add Process.runOnThread(), to make it easy to run arbitrary code on a specific thread. Must be used with care to avoid deadlocks/reentrancy issues.
• gumjs: Add limit option to Thread.backtrace(). Thanks @davinci-tech!
• gumjs: Expand CModule glib.h with alternatives to deprecated APIs.
• stalker: Add StalkerIterator.put_chaining_return(). Thanks @s1341!
• stalker: Add run_on_thread() and run_on_thread_sync().
• interceptor: Add support for shadow stacks on x86. Thanks @yjugl!
• cpu-features: Add CET_SS flag and detection logic. Thanks @yjugl!
• x86-writer: Add cpu_features field. Thanks @yjugl!
• spinlock: Add try_acquire(). Thanks @mrmacete!
• cloak: Add with_lock_held() and is_locked(). Thanks @mrmacete!
• interceptor: Add with_lock_held() and is_locked(). Thanks @mrmacete!
• darwin: Hint at macOS boot arguments when helper crashes.
• java: Support instantiating classes without constructors. Thanks @AeonLucid!
• java: Add support for arrays of array. Thanks @histausse!
• python: Make the source distribution buildable fully from source, instead of only supporting building using a devkit.
• python: Drop the MSVS build system.
• node: Add Meson build system, drop prebuild and node-gyp bits.
• node: Support building fully from source when a prebuilt can’t be found.
• clr: Add Meson build system, drop the MSVS build system.
• qml: Add Meson build system, drop the qmake build system.
• qml: Add support for Qt 6. Thanks @zaxo7!
• qml: Drop support for Qt 5.

Bugfixes

Last but not least, we’re also bringing you a long list of quality improvements:

• gumjs: Preserve thread’s system error over NativeCallback invocations. Thanks @HexKitchen!
• gumjs: Always expose thread’s system error to NativeCallback.
• gumjs: Plug leak of Stalker instance.
• stalker: Fix block events disrupting exclusive access on arm64. Thanks @saicao!
• memory: Fix patch_code() protection flipping on RWX systems.
• swift-api-resolver: Fix handling of indirect type entries.
• swift: Work around Module.load() issue on iOS Simulator. Thanks @zydeco!
• base: Fix racy crash in custom GSource implementations.
• base: Fix the p2p AgentSession registration logic.
• buffer: Fix the read_string() size logic. Thanks @hsorbo!
• linux: Fix early instrumentation on certain 32-bit systems.
• linux: Fix inject_library_blob() on modern Android.
• linux: Fix unreliable exec transition logic.
• linux: Fix unreliable injection when libc is absent.
• agent: Fix hang in child-gating fork() scenarios. Reproducible in situations where pidfd_getfd() is available but not permitted, such as inside Docker containers.
• windows: Use RW/RX permissions for injection. This makes Frida injection compatible with more software. In particular, Mozilla Firefox rejects thread startup if the start address is RWX. Thanks @yjugl!
• darwin: Massage libunwind around Frida hooks, to avoid breaking code making use of exceptions, such as through @try/@catch in Objective-C. Thanks @mrmacete!
• darwin: Take Interceptor and Cloak locks in ThreadSuspendMonitor, to extend its scope to prevent deadlock scenarios where threads holding the Cloak or Interceptor lock get suspended. Thanks @mrmacete!
• darwin: Fix racy teardown of InjectInstance dispatch source.
• darwin: Fix racy teardown of SpawnInstance dispatch source.
• android: Fix child-gating of execl() and friends.
• compiler: Bump @types/frida-gum. Thanks @s1341!
• modulate: Gracefully handle missing symbols. Thanks @hsorbo!
• python: Move _frida package inside the frida package.

EOF

And that pretty much sums it up. Enjoy!

Just a quick bug-fix release to deal with an iOS packaging bug affecting users on palera1n (rootless) and Dopamine. Kudos to @miticollo for reporting this so quickly.

Enjoy!

Lots of exciting new things this time around. Let’s dive right in.

Thread Names

The Process.enumerateThreads() API now also exposes thread names when available:

$ frida -U -F
[Pixel 6 Pro::com.google.android.calculator ]-> Process.enumerateThreads()[1]
{
    "id": 9579,
    "name": "Signal Catcher",
    "state": "waiting",
    "context": { … }
}
[Pixel 6 Pro::com.google.android.calculator ]->

Kudos to @Hexploitable for the awesome pull-request that got this ball rolling 🙌

Memory Protection Queries

Sometimes it’s essential to quickly determine the current protection of a page in memory. Thanks to @mrmacete, now you can:

$ frida -p 0
[Local::SystemSession ]-> Memory.queryProtection(Module.getExportByName(null, 'open'))
"r-x"
[Local::SystemSession ]->

QuickJS 2024-01-13

This release also contains the latest QuickJS, released last month. This means there’s almost complete ES2023 support, and even some features from the upcoming ES2024 specification. Plus, quite a few bug-fixes as well. It’s also worth mentioning that top-level await is now supported, making it easier to write portable scripts that work on both of our JavaScript runtimes.

Cloaking

Frida keeps track of its own memory ranges, threads, etc., to keep you from seeing yourself during process introspection. Introspection APIs such as Process.enumerateThreads() ensure that Frida’s own resources are hidden, and things appear as if you were not inside the process being instrumented.

For those of you using Stalker, or other things that expose you to raw memory locations, you might see code not belonging to any loaded module, and wonder where it came from. For example, if you use Stalker.follow() to follow execution into or out of a hooked function, it’s going to execute some trampoline code generated by Interceptor.

Agents using Gum’s C APIs could already query whether a given memory address, thread, etc., is owned by Frida, but this hadn’t yet been exposed to our JavaScript bindings. But now, thanks to another awesome contribution by @mrmacete, this is now supported. For example:

$ frida -p 0
[Local::SystemSession ]-> open = Module.getExportByName(null, 'open')
"0x7f929a325840"
[Local::SystemSession ]-> Interceptor.attach(open, () => {})
{}
[Local::SystemSession ]-> Instruction.parse(open).toString()
"jmp 0x7f928940c408"
[Local::SystemSession ]-> Cloak.hasRangeContaining(ptr('0x7f928940c408'))
true
[Local::SystemSession ]-> pointInsideOpen = open.add(16)
"0x7f929a325850"
[Local::SystemSession ]-> Instruction.parse(pointInsideOpen).toString()
"push rbx"
[Local::SystemSession ]-> Cloak.hasRangeContaining(pointInsideOpen)
false
[Local::SystemSession ]->

Fast Interceptor

One little known and fairly recent feature, now also available from JavaScript, is Interceptor.replaceFast(). What’s different about it is that the target is modified to vector directly to your replacement, which means there is less overhead compared to Interceptor.replace(). This also means that you need to use the returned pointer if you want to call the original implementation. It is also not possible to combine it with Interceptor.attach() for the same target. However, if you’re dealing with a hot target it’s definitely something you want to have in your toolbox, especially when combined with CModule.

ELF Exports Regression

We discovered way late that Frida 16.1.0 broke Module#enumerateExports() on some ELF binaries, and this is now finally fixed. It turned out to be a bug in the bounds-checking that I added when making Gum.ElfModule a cross-platform API, when it got support for offline use-cases like that of our Barebone backend. (Where we use it to dynamically inject Rust code into OS kernels and bare-metal targets.)

ELF Import Slots

Those of you using Frida on Apple platforms may have noticed that Module#enumerateImports() provides you with import objects that always have a slot property. One way you can use this is to write a new pointer to that address, letting you rebind imports on a per-module basis. Super-handy if Interceptor is unable to hook a function, or for scenarios where you want to avoid inline hooks.

As of this release, we now provide the slot property on ELF-based platforms too, so you can also use this feature on Linux, Android, FreeBSD, and QNX. Yay!

Android Stability

Avid users on recent versions of Android may have experienced “soft-loops”, where Frida randomly crashes Zygote and causes a big chunk of user-space to restart. This turned out to be caused by the runtime preparing itself to fork() by polling /proc/self/stat while waiting for the thread count to drop to one, i.e. waiting for the process to become single-threaded.

This has now been solved by subtracting the threads owned by Frida, which we determine by internally using the Cloak API, touched upon earlier in this post. We also make use of the new ELF Import Slots feature, so we can hook read() only for callers in libart.so. Inserting an inline hook in libc.so’s read() is not a great idea in this case, as the process we’re in might use it for a blocking read that blocks indefinitely. This becomes a challenge when wanting to unload, and getting stuck waiting for the chance to roll back our inline hook.

Anyway, quite an interesting bug. Shout-out to @enovella_ for reporting and helping track this one down 🙌

While on the topic of Android, this release also improves Java hooking on Android 14, where a new ART quick entrypoint is being used in case of –enable-optimizations. Kudos to @cr4zyserb for this neat contribution.

Better iOS 16 support

If you ever got hit by Service cannot load in requested session when trying to install Frida on iOS, this is now finally fixed. Kudos to @as0ler for the assist on fixing this.

Jailbroken tvOS

Another exciting development is that we now support jailbroken tvOS, and you can grab a .deb straight from our repo at https://build.frida.re/. Special thanks to @tmm1 for the pull-requests that made this happen.

Misc

This release also has a lot more to offer. The remaining changes are:

• symbolutil-libdwarf: Fix handling of DW_AT_ranges in DWARF 5. This means the DebugSymbol API works properly on binaries built by newer toolchains.
• elf-module: Fix relocation address when online.
• interceptor: Check module prefix when claiming grafts on arm64, for compatibility with Xcode’s new libLogRedirect.dylib interposing on iOS 17. Thanks @mrmacete!
• interceptor: Cloak thunks on arm64. Thanks @mrmacete!
• windows: Ensure that the MSVC source-charset is set to UTF-8, so embedded JavaScript can be parsed correctly at runtime. Thanks @Qfrost911!
• freebsd: Improve allocate-near strategy.
• gumjs: Plug leak during QJS load() w/ ESM.
• objc: Ensure block structure is writable in implementation setter. Thanks @mrmacete!
• compiler: Bump @types/frida-gum to 18.6.0.

Enjoy!

Lots of goodies this time around:

• stalker: Improve stability on multiple fronts. Kudos to @as0ler, @hsorbo, and @mrmacete for the fun and productive mob programming sessions that resulted in these wonderful improvements:
  • stalker: Copy BLR for excluded calls on arm64, instead of replacing them with functionally-equivalent ones, so that any pointer authentication context is used as expected. Thanks @mrmacete!
  • stalker: Abort when allocate_near() fails on arm64, instead of crashing due to the subsequent NULL pointer dereference.
  • gumjs: Fix crash in Stalker.flush() on a stopped sink. This happens if Stalker.garbageCollect() was just called.
  • gumjs: Fix use-after-free in Stalker QuickJS callback logic. We need to keep the callback values alive in case Stalker.garbageCollect() happens in the middle and releases them.
• darwin: Improve symbolicator cache invalidator logic. Thanks @mrmacete!
• swift-api-resolver: Handle signed pointers.
• linux: Improve spawn() to handle partial link maps.
• linux: Improve injector to handle XOM pages.
• linux: Improve injector RTLD API detection.
• linux: Fix injector ELF SYMTAB name parsing.
• node: Link against the inspector library on UNIX, to fix RTLD panic when Script#enableDebugger() is called. Thanks @pandasauce!
• ci: Publish FreeBSD prebuilds for Node.js 20 and Electron 27.

Some neat little bug-fixes, just in time for Christmas:

• server: Add missing entitlements for iOS 16, required to remap binary files in memory. Thanks @as0ler!
• android: Fix Java hooking of interpreter-run methods on Android 14.
• Fix argv[0] shown in CLI tools such as frida-server and frida-inject. Thanks @bet4it!

Quite a few goodies in this release:

• interceptor: Pause cloaked threads too. This prevents random SIGBUS crashes on our own threads while using Interceptor to hook functions residing on the same page as any of the ones potentially used internally. Thanks @mrmacete!
• darwin: Move to our POSIX Exceptor backend. Mach exception handling APIs have become increasingly restrictive in recent Apple OS versions.
• darwin: Resolve import trampolines on arm64, allowing us to hook targets such as sigaction().
• linux: Improve spawn() to handle r_brk being hit again.
• linker: Improve spawn() to consider on-disk ELF for RTLD symbols. This means we might find r_debug on additional Android systems, for example.
• linux: Fix spawn() when DT_INIT_ARRAY contains sentinel values.
• linux: Improve spawn() to use DT_PREINIT_ARRAY if present.
• android: Handle symlinks in RTLD fallback logic.

Three exciting changes this time around:

• process: Add get_main_module(), exposed to JavaScript as Process.mainModule. Useful when needing to know which module represents the main executable of the process. In the past this was typically accomplished by enumerating the loaded modules and assuming that the first one in the list is the one. This is no longer the case on the latest Apple OSes, so we now provide an efficient and portable solution with this new API. Thanks @mrmacete!
• compiler: Bump @types/frida-gum to 18.5.0, now with typings for recent API additions.
• barebone: Fix compatibility with latest Corellium.

Some neat refinements this time around:

• stalker: Allow transformer to skip calls on x86. Thanks @s1341!
• objc: Tolerate mangled Swift class names. Thanks @hsorbo!
• cpu-features: Improve the AVX2 detection. Thanks for the assist, @smx-smx!
• windows: Add support for MinGW. Thanks for the assist, @smx-smx!
• openssl: Upgrade to openssl-3.0.12+quic@b81f0ae.

Just a quick bug-fix release to roll back two of the Interceptor/Relocator arm64 changes that went into the previous release. Turns out that these need some more refinement before they can land, so we will roll them back for now.

Changelog

• Revert “relocator: Improve scratch register strategy on arm64”.
• Revert “interceptor: Relocate tiny targets on arm64”.
• stalker: Allow transformer to skip calls on arm64.

Since our last release, @hsorbo and I had a lot of fun pair-programming on a wide range of exciting tech. Let’s dive right in.

Swift

We’ve introduced a brand new ApiResolver for Swift, which you can use like this:

const r = new ApiResolver('swift');
r.enumerateMatches('functions:*CoreDevice!*RemoteDevice*')
.forEach(({ name, address }) => {
  console.log('Found:', name, 'at:', address);
});

There’s also a new and exciting frida-tools release, 12.3.0, which upgrades frida-trace with Swift tracing support, using the new ApiResolver:

$ frida-trace Xcode -y '*CoreDevice!*RemoteDevice*'

Module

Our Module API now also provides enumerateSections() and enumerateDependencies(). And for when you want to scan loaded modules for specific section names, our existing module ApiResolver now lets you do this with ease:

const r = new ApiResolver('module');
r.enumerateMatches('sections:*!*text*/i')
.forEach(({ name, address }) => {
  console.log('Found:', name, 'at:', address);
});

EOF

There’s also a bunch of other exciting changes, so definitely check out the changelog below.

Enjoy!

Changelog

• swift-api-resolver: Add a brand new Swift API Resolver.
• module-api-resolver: Support resolving sections.
• api-resolver: Add optional size field to matches.
• module: Add enumerate_sections().
• module: Add enumerate_dependencies().
• device: Add unpair(). Only implemented for iOS-devices for now.
• compiler: Bump frida-compile to 16.4.1, and @types/frida-gum to 18.4.5.
• gdb: Handle empty response packets.
• gdb: Handle error reply to feature document request.
• darwin-mapper: Initialize TLV descriptors on load. Thanks @fabianfreyer!
• darwin-module: Add Thread Local Variable APIs. Thanks @fabianfreyer!
• darwin-module: Optimize exports enumeration slightly.
• elf-module: Improve the section ID generation.
• x86-writer: Add reg-reg {fs,gs}-based MOV insns. Thanks @fabianfreyer!
• arm64-writer: Add MRS instruction. Thanks @fabianfreyer!
• arm64-writer: Add UBFM, LSL, and LSR instructions. Thanks @fabianfreyer!
• relocator: Improve scratch register strategy on arm64.
• interceptor: Branch to trampoline using computed scratch register.
• interceptor: Relocate tiny targets on arm64.
• linux: Handle disabled process_vm_{read,write}v(). Thanks @Pyraun!
• server: Use sysroot for temporary files on rootless iOS. Thanks @fabianfreyer!
• gumjs: Fix crash in File and Database when Interceptor is absent. Thanks @mrmacete!
• gumjs: Fix NativePointer from number for 32-bit BE (#752). Thanks @forky2!
• gumjs: Bump frida-swift-bridge to 2.0.7.
• ci: Publish prebuilds for Node.js 20 & 21, and Electron 27.
• ci: Do not publish Swift bindings for now. There’s a long-standing heisenbug that causes the x86_64 slice to randomly end up corrupted, in turn resulting in CI release jobs failing. As I’m not too keen on sinking time into this anytime soon, considering how easy it is to build these bindings locally using a downloaded core devkit, simply dropping the release asset seems like the best solution.

Some exciting improvements this time around:

• ios: Fix spawn() on iOS 17. Thanks @hsorbo!
• ios: Add support for rootless systems. Thanks for the pair-programming, @hsorbo!
• android: Fix dynamic linker compatibility regression. Thanks for the pair-programming, @hsorbo! Kudo to @getorix for reporting.
• gumjs: Add Worker API, so heavy processing can be moved to a background thread, allowing hooks to be handled in a timely manner. Only implemented in the QuickJS runtime for now. Kudos to @mrmacete for tracking down and fixing last-minute bugs in the implementation.
• linux: Improve error-handling when trying to attach to processes that are near death.

Time for a new release, just in time for the weekend:

• server: Add missing entitlement for iOS >= 17. Kudos to @alexhude for helping get to the bottom of this one.
• stalker: Improve exclusive store handling on arm and arm64. Instead of potentially expanding the current block to include instructions beyond where the block would naturally end, we move to a safer approach: Once we encounter an exclusive store, we look back at the previously generated blocks to see if we can find one with an exclusive load. If we do, we mark this range of blocks as using exclusive access. We also invalidate the blocks, so that problematic instrumentation can be omitted upon recompilation. To also allow custom transformers to adapt their generated code, we introduce StalkerIterator.get_memory_access(). Thanks for the fun and productive pair-programming, @hsorbo!
• gumjs: Add StalkerIterator.memoryAccess, allowing a custom transformer to determine what kind of instrumentation is safe to add without disturbing an exclusive store operation. Set to either ‘open’, when “noisy” instrumentation such as callouts are safe, or ‘exclusive’, when such instrumentation is risky and may lead to infinite loops. (Due to an exclusive store failing, and every subsequent retry also failing.)
• gumjs: Fix CModule bindings for Stalker on arm.
• stalker: Fix crash on invalidation in added slabs.
• arm64-writer: Add put_eor_reg_reg_reg(). Thanks for the fun and productive pair-programming, @hsorbo!

Time for a new release to refine a few things:

• darwin: Fix Stalker.follow() regression where ongoing system calls would get brutally interrupted, typically resulting in the target crashing. Thanks for the pair-programming, @hsorbo!
• gumjs: Implement the WeakRef API for QuickJS.
• compiler: Bump @types/frida-gum to 18.4.0.

Only a few changes this time around:

• compiler: Bump frida-compile to 16.3.0, now with TypeScript 5.1.5 and other improvements. Among them is a fix by @hsorbo that changes the default moduleResolution to Node16.
• stalker: Add Iterator.get_capstone(), so transformers can use Capstone APIs that require the Capstone handle.
• node: Fix RPC message array check. Thanks @ZachQin!

For quite some years I’ve been dreaming of taking Frida beyond user-space software, to also support instrumenting OS kernels as well as barebone systems. Perhaps even microcontrollers…

Microcontrollers

Earlier this year my family’s cat door broke down. After some back and forth with the retailer, double-checking the installation and such, it would work for a little while before it eventually started malfunctioning.

This was obviously not much fun for our cats:

It’s also no surprise that they’d end up making a lot of noise, in turn making it hard to get a good night’s sleep when having to get up to let them back in manually.

I ended up buying a second cat door and, lo and behold, no more issues. The old one ended up collecting dust for a while. Something I kept thinking of was whether I could debug it, and perhaps even extend the software to do more useful things.

Feeling the urge to open it up to poke at the electronics inside of it, I eventually gave in:

That looked like an STM32F030C6T6, which is an ARM Cortex M0-based MCU. My first thought was whether I could dump the flash memory to do some static analysis.

After quickly skimming MCU docs, and a little bit of multimeter probing, I figured out the JP12 pads:

This made it easy to pull BOOT0 high, so the MCU boots into its internal bootloader instead of user code.

By hooking up a USB to 3.3V TTL device to the USART1 pads, I could dump the flash:

$ ./stm32flash -r firmware.bin /dev/ttyUSB0
stm32flash 0.7

http://stm32flash.sourceforge.net/

Interface serial_posix: 57600 8E1
Version      : 0x31
Option 1     : 0x00
Option 2     : 0x00
Device ID    : 0x0444 (STM32F03xx4/6)
- RAM        : Up to 4KiB  (2048b reserved by bootloader)
- Flash      : Up to 32KiB (size first sector: 4x1024)
- Option bytes  : 16b
- System memory : 3KiB
Memory read
Read address 0x08008000 (100.00%) Done.

And perform some static analysis:

Seeing as two of the other pads are connected to SWDIO and SWCLK, used for Serial Wire Debug (SWD), the natural next step was to hook up a Raspberry Pi Debug Probe to those. After getting that set up, I fired up OpenOCD:

$ openocd -f interface/cmsis-dap.cfg -f target/stm32f0x.cfg
Open On-Chip Debugger 0.11.0-g8e3c38f7-dirty (2023-05-05-14:25)
Licensed under GNU GPL v2
For bug reports, read
	http://openocd.org/doc/doxygen/bugs.html
Info : auto-selecting first available session transport "swd". To override use 'transport select <transport>'.
Info : Listening on port 6666 for tcl connections
Info : Listening on port 4444 for telnet connections
Info : Using CMSIS-DAPv2 interface with VID:PID=0x2e8a:0x000c, serial=E6614103E78B482F
Info : CMSIS-DAP: SWD  Supported
Info : CMSIS-DAP: FW Version = 2.0.0
Info : CMSIS-DAP: Interface Initialised (SWD)
Info : SWCLK/TCK = 0 SWDIO/TMS = 0 TDI = 0 TDO = 0 nTRST = 0 nRESET = 0
Info : CMSIS-DAP: Interface ready
Info : clock speed 1000 kHz
Info : SWD DPIDR 0x0bb11477
Info : stm32f0x.cpu: hardware has 4 breakpoints, 2 watchpoints
Info : starting gdb server for stm32f0x.cpu on 3333
Info : Listening on port 3333 for gdb connections

The idea I had been thinking about for a long time was to add a new Frida backend where the only process you can attach to is PID 0. Any scripts loaded there would actually be run locally, and implement the familiar JavaScript API. Any API that accesses memory, such as when dereferencing an int * by doing e.g. ptr(‘0x80000’).readInt(), would end up querying the target, through SWD in the above case.

I initially started sketching this where the backend would talk to the OpenOCD daemon through its telnet interface. But I quickly realized that it would be better to talk to its GDB-compatible remote stub. In this way, Frida will be able to instrument any target with an available remote stub. Whether that’s OpenOCD, Corellium (iOS kernel instrumentation!), QEMU, etc.

As for Interceptor, my thinking was that basic functionality would be implemented using breakpoints. But, only if the user supplies JavaScript callbacks. If function pointers are supplied instead, we could perform inline hooking so the target can run without any traps/ping-pongs with the host. This means it could even be used for observing and modifying hot code inside an OS kernel or MCU firmware.

After some initial sketching, I was able to run the following script:

Interceptor.breakpointKind = 'hard';

const THUMB_BIT = 1;

const initRest = ptr('0x0800306a').or(THUMB_BIT);
Interceptor.attach(initRest, {
  onEnter(args) {
    console.log('>>> init_rest()',
        JSON.stringify(this.context, null, 2));
  },
  onLeave(retval) {
    console.log(`<<< init_rest() retval=${retval}`);
  }
});

Using the Frida REPL:

$ frida -D barebone -p 0 -l demo.js
     ____
    / _  |   Frida 16.1.0 - A world-class dynamic instrumentation toolkit
   | (_| |
    > _  |   Commands:
   /_/ |_|       help      -> Displays the help system
   . . . .       object?   -> Display information about 'object'
   . . . .       exit/quit -> Exit
   . . . .
   . . . .   More info at https://frida.re/docs/home/
   . . . .
   . . . .   Connected to GDB Remote Stub (id=barebone)

[Remote::SystemSession ]-> $gdb.continue()
[Remote::SystemSession ]-> >>> init_rest() {
  "r7": "0xffffffff",
  "pc": "0x800306a",
  "r8": "0xffffffff",
  "xPSR": "0x41000000",
  "r9": "0xffffffff",
  "sp": "0x20000578",
  "r0": "0x0",
  "r10": "0xffffffff",
  "lr": "0x8003069",
  "r1": "0x40021008",
  "r11": "0xffffffff",
  "r2": "0xffffffff",
  "r12": "0xffffffff",
  "r3": "0xffffffff",
  "r4": "0xffffffff",
  "r5": "0xffffffff",
  "r6": "0xffffffff"
}
<<< init_rest() retval=0x1

A few things to note here:

• We set Interceptor.breakpointKind to hard, as our target’s code resides in flash, which means software-breakpoints won’t work. This would not have been necessary if I was using a J-Link or similar SWD interface, which transparently reflashes as software-breakpoints are added.
• The backend does not yet automatically resume, so we are doing that manually through $gdb.continue(), part of this internal API, which exposes most of GDB.Client to JavaScript. This is meant to become an internal implementation detail, but will be needed while this new backend matures – it should not yet be considered stable API.
• We set the least significant bit to indicate to Interceptor that the target function uses Thumb instruction encoding. This part may already be familiar to you if you have previously used Frida’s conventional backends on 32-bit ARM.
• The new Barebone backend connects to the GDB-compatible remote stub at 127.0.0.1:3333 by default. This matches what OpenOCD typically defaults to, but can be overridden by setting the FRIDA_BAREBONE_ADDRESS environment variable.

OS kernels

While my fun little cat door side-quest is a great test case for the tiny part of the spectrum, there’s also a lot of potential in supporting larger systems.

One of the cooler use-cases there is definitely Corellium, as it means we can instrument the iOS kernel. Using a Tamarin Cable it should even be possible to get this working on a checkm8-exploitable physical device.

Before we touch on that though, let’s see if we can get things going with QEMU and a live Linux kernel.

Linux

First, we’ll fire up a VM we can play with:

$ pip install arm_now
$ arm_now start aarch64 --add-qemu-options='-gdb tcp::9000'
...
Welcome to arm_now
buildroot login:

Next, we’ll use the Frida REPL to look around:

$ export FRIDA_BAREBONE_ADDRESS=127.0.0.1:9000
$ frida -D barebone -p 0
     ____
    / _  |   Frida 16.1.0 - A world-class dynamic instrumentation toolkit
   | (_| |
    > _  |   Commands:
   /_/ |_|       help      -> Displays the help system
   . . . .       object?   -> Display information about 'object'
   . . . .       exit/quit -> Exit
   . . . .
   . . . .   More info at https://frida.re/docs/home/
   . . . .
   . . . .   Connected to GDB Remote Stub (id=barebone)

[Remote::SystemSession ]-> Process.arch
"arm64"
[Remote::SystemSession ]-> Process.enumerateRanges('r-x')
[
    {
        "base": "0xffffff8008080000",
        "protection": "r-x",
        "size": 4259840
    }
]
[Remote::SystemSession ]-> $gdb.state
"stopped"
[Remote::SystemSession ]-> $gdb.exception
{
    "breakpoint": null,
    "signum": 2,
    "thread": {}
}
[Remote::SystemSession ]-> $gdb.exception.thread.readRegisters()
{
    "cpsr": 1610613189,
    "pc": "0xffffff8008096648",
    "sp": "0xffffff80085f3f10",
    "x0": "0x0",
    "x1": "0xffffff80085e6b78",
    "x10": "0x880",
    "x11": "0xffffffc00e877180",
    "x12": "0x0",
    "x13": "0xffffffc00ffe1f30",
    "x14": "0x0",
    "x15": "0xfffffff8",
    "x16": "0xffffffbeff000000",
    "x17": "0x0",
    "x18": "0xffffffc00ffe17e0",
    "x19": "0xffffff80085e0000",
    "x2": "0x40079f5000",
    "x20": "0xffffff80085f892c",
    "x21": "0xffffff80085f88a0",
    "x22": "0xffffff80085ffe80",
    "x23": "0xffffff80085ffe80",
    "x24": "0xffffff80085d5028",
    "x25": "0x0",
    "x26": "0x0",
    "x27": "0x0",
    "x28": "0x405a0018",
    "x29": "0xffffff80085f3f10",
    "x3": "0x30c",
    "x30": "0xffffff800808492c",
    "x4": "0x0",
    "x5": "0x40079f5000",
    "x6": "0x1",
    "x7": "0x1c0",
    "x8": "0x2",
    "x9": "0xffffff80085f3e80"
}
[Remote::SystemSession ]->

You might wonder how we’ve implemented Process.enumerateRanges(). This part is for now only implemented on arm64, and it is accomplished by parsing the page tables. (And if we’re talking to Corellium’s remote stub we use a vendor-specific monitor command to save ourselves a lot of network roundtrips.)

So now that we’re peeking into a running kernel, one of the things we might want to do is find internal functions and data structures. This is where the memory- scanning API comes handy:

for (const r of Process.enumerateRanges('r-x')) {
  console.log(JSON.stringify(r, null, 2));
  const matches = Memory.scanSync(r.base, r.size,
      '7b2000f0 fa03082a 992480d2 : 1f00009f ffffffff 1f00e0ff');
  console.log('Matches:', JSON.stringify(matches, null, 2));
}

Here we’re looking for the Linux kernel’s arm64 syscall handler, matching on its first three instructions. We use the masking feature to mask out the immediates of the ADRP and MOV instructions (first and third instruction).

Let’s take it for a spin:

$ frida -D barebone -p 0 -l scan.js
     ____
    / _  |   Frida 16.1.0 - A world-class dynamic instrumentation toolkit
   | (_| |
    > _  |   Commands:
   /_/ |_|       help      -> Displays the help system
   . . . .       object?   -> Display information about 'object'
   . . . .       exit/quit -> Exit
   . . . .
   . . . .   More info at https://frida.re/docs/home/
   . . . .
   . . . .   Connected to GDB Remote Stub (id=barebone)
Attaching...
{
  "base": "0xffffff8008080000",
  "size": 4259840,
  "protection": "r-x"
}
Matches: [
  {
    "address": "0xffffff8008082f00",
    "size": 12
  }
]
[Remote::SystemSession ]->

So now we’ve dynamically detected the kernel’s internal syscall handler! 🚀

Re-implementing the memory scanning feature was one of the highlights for me personally, as @hsorbo and I had a lot of fun pair-programming on it. The implementation is conceptually very similar to what we’re doing in our Fruity backend for jailed iOS, and our new Linux injector: instead of transferring data to the host, and searching that, we can get away with transferring only the search algorithm, to run that on the target.

The memory scanner implementation is written in Rust, and helped prepare the groundwork for a new cool feature I’m going to cover a bit later in this post.

So, now that we know where the Linux kernel’s syscall handler is, we can use Interceptor to install an instruction-level hook:

const el0Svc = ptr('0xffffff8008082f00');
Interceptor.attach(el0Svc, function (args) {
  const { context } = this;
  const scno = context.x8.toUInt32();
  console.log(`syscall! scno=${scno}`);
});

And try that out on our running VM:

$ frida -D barebone -p 0 -l kernhook.js
     ____
    / _  |   Frida 16.1.0 - A world-class dynamic instrumentation toolkit
   | (_| |
    > _  |   Commands:
   /_/ |_|       help      -> Displays the help system
   . . . .       object?   -> Display information about 'object'
   . . . .       exit/quit -> Exit
   . . . .
   . . . .   More info at https://frida.re/docs/home/
   . . . .
   . . . .   Connected to GDB Remote Stub (id=barebone)

[Remote::SystemSession ]-> $gdb.continue()
[Remote::SystemSession ]-> syscall! scno=63
syscall! scno=64
syscall! scno=73
syscall! scno=63
syscall! scno=64
syscall! scno=73
syscall! scno=63
syscall! scno=64
syscall! scno=56
syscall! scno=62
syscall! scno=64
syscall! scno=57
syscall! scno=29
syscall! scno=134
...

And that’s it – we are monitoring system calls across the entire system! 💥

Rust

One of the first things you’ll probably notice if you try the previous example is that we slow down the system quite a bit. This is because Interceptor uses breakpoints when a JavaScript function is specified as the callback.

Not to worry though. If we write our callback in machine code and pass a NativePointer instead, Interceptor will pick a different strategy: it will modify the target’s machine code to redirect execution to a trampoline, which in turn calls the function at the address that we specify.

So that’s great. We only need to get our machine code into memory. Some of you may be familiar with our CModule API. We don’t yet implement that one in this new Barebone backend (and we will, eventually!), but we have something even better. Enter RustModule:

const kernBase = ptr('0xffffff8008080000');
const procPidStatus = kernBase.add(0x15e600);

const m = new RustModule(`
#[no_mangle]
pub unsafe extern "C" fn hook(ic: &mut gum::InvocationContext) -> () {
    let regs = &mut ic.cpu_context;
    println!("proc_pid_status() was called with x0={:#x} x1={:#x}",
        regs.x[0],
        regs.x[1],
    );
}
`);

Interceptor.attach(procPidStatus, m.hook);

The RustModule implementation uses a local Rust toolchain, assumed to be on your PATH, to compile the code you provide it into a no_std self-contained ELF. It relocates this ELF and writes it into the target’s memory. As part of this it will also parse the MMU’s page tables and insert new entries there so the uploaded code becomes part of the virtual address space, where the pages are read/write/execute.

In this example we’re hooking proc_pid_status() in our live Linux kernel.

Note that File.readAllText() can be used to avoid having to inline Rust code inside your JavaScript. Here we’re using inline code for the sake of brevity.

Now, with our Rust-powered agent, let’s take it for a spin:

$ frida -D barebone -p 0 -l kernhook2.js
     ____
    / _  |   Frida 16.1.0 - A world-class dynamic instrumentation toolkit
   | (_| |
    > _  |   Commands:
   /_/ |_|       help      -> Displays the help system
   . . . .       object?   -> Display information about 'object'
   . . . .       exit/quit -> Exit
   . . . .
   . . . .   More info at https://frida.re/docs/home/
   . . . .
   . . . .   Connected to GDB Remote Stub (id=barebone)

Error: to enable this feature, set FRIDA_BAREBONE_HEAP_BASE to the physical base address to use, e.g. 0x48000000
    at <eval> (/home/oleavr/src/demo/kernhook2.js:13)
    at evaluate (native)
    at <anonymous> (/frida/repl-2.js:1)

[Remote::SystemSession ]->

Oops! That didn’t quite work. There is still one piece missing in our new backend: we don’t yet have any “kernel bridges” in place that automatically fingerprint the internals of known kernels in order to find a suitable internal memory allocator we can use. This will also be needed to implement APIs such as Process.enumerateModules(), which will allow listing the loaded kernel modules/kexts. We could also locate the kernel’s process list and implement enumerate_processes(), so frida-ps works. And those are only a couple of examples… How about injecting frida-gadget into a user-space process? That would be super-useful for an embedded system where we want to avoid modifying the flash. Anyway, I digress 😊

So, on MCUs and unknown kernels you will have to tell Frida where, in physical memory, we may clobber if you want to use intrusive features such as RustModule, Interceptor in its inline hooking mode, Memory.alloc(), etc.

With that in mind, let’s retry our example, but this time we’ll set the FRIDA_BAREBONE_HEAP_BASE environment variable:

$ export FRIDA_BAREBONE_HEAP_BASE=0x48000000
$ frida -D barebone -p 0 -l kernhook2.js
     ____
    / _  |   Frida 16.1.0 - A world-class dynamic instrumentation toolkit
   | (_| |
    > _  |   Commands:
   /_/ |_|       help      -> Displays the help system
   . . . .       object?   -> Display information about 'object'
   . . . .       exit/quit -> Exit
   . . . .
   . . . .   More info at https://frida.re/docs/home/
   . . . .
   . . . .   Connected to GDB Remote Stub (id=barebone)

[Remote::SystemSession ]-> m
{
    "hook": "0xffffff80080103e0"
}
[Remote::SystemSession ]-> $gdb.continue()

Yay! 🎉 So now, in the terminal where we have QEMU running, let’s try accessing /proc/$pid/status three times, so the hooked function gets called:

# head -3 /proc/self/status
Name:	head
Umask:	0022
State:	R (running)
# head -3 /proc/self/status
Name:	head
Umask:	0022
State:	R (running)
# head -3 /proc/self/status
Name:	head
Umask:	0022
State:	R (running)

Over in our REPL, we should see our hook() getting hit three times:

proc_pid_status() was called with x0=0xffffffc00d4bca00 x1=0xffffff8008608758
proc_pid_status() was called with x0=0xffffffc00d4bc780 x1=0xffffff8008608758
proc_pid_status() was called with x0=0xffffffc00d4bc780 x1=0xffffff8008608758

It works! 🥳

There’s one important thing to note though: In our example we’re using println!(), and this actually causes the target to hit a breakpoint, so the host can read out the message passed to it, and bubble that up just like a console.log() from JavaScript. This means you should only use this feature for temporary debugging purposes, and throttle how often it’s called if on a hot code-path.

The next thing you might want to do is pass external symbols into your RustModule. For example if you want to call internal kernel functions from your Rust code. This is accomplished by declaring them like this:

extern "C" {
    fn frobnicate(data: *const u8, len: usize);
}

Then when constructing the RustModule, pass it in through the second argument:

const m = new RustModule(source, {
  frobnicate: ptr('0xffffff8008084320'),
});

For those of you familiar with our CModule API, this part is exactly the same. You can also use NativeCallback to implement portions host-side, in JavaScript, but this needs to be handled with care to avoid performance bottlenecks. Going in the opposite direction there is also NativeFunction, which you can use to call into your Rust code from JavaScript.

Last but not least, you may also want to import existing Rust crates from crates.io. This is also supported:

const m = new RustModule(source, {}, {
  dependencies: [
    'cstr_core = { version = "0.2.6", default-features = false }',
  ]
});

Corellium

What’s so exciting is that all of the Linux bits above all “just work” on Corellium as well. All you need to do is point FRIDA_BAREBONE_ADDRESS at the endpoint shown in Corellium’s UI under “Advanced Options” -> “gdb”.

Shout-out to the awesome folks at Corellium for their support while doing this. They even implemented new protocol features to improve interoperability 🔥

Future

This new backend should be considered alpha quality for now, but I think it’s already capable of so many useful things that it would be a shame to keep it sitting on a branch.

You may notice that the JS APIs implemented only cover a subset, and not all features are available on non-arm64 targets yet. But all of this will improve as the backend matures. (Pull-requests are super-welcome!)

And as a fun aside, here’s Frida attached to the BeOS kernel:

EOF

There’s also a bunch of other exciting changes, so definitely check out the changelog below.

Enjoy!

Changelog

• Add Barebone backend. (Covered extensively above.)
• objc: Handle modifiers. This makes type parsing more reliable, especially when dealing with ivars which often times have the “atomic” modifier: exceptions were thrown because the modifiers ended up being treated as unknown types. Thanks @mrmacete!
• android: Fix support for Android 14. Thanks @gsingh93! Also thanks @jayluxferro for contributing a follow-up fix for a mistake I made while merging @gsingh93’s PR.
• gum-graft: Add support for chained imports. Thanks @mrmacete!
• gumjs: Add NativePointer#readVolatile(), to provide a safe way to read from memory that may become unmapped or have its memory protection changed midway through. Thanks @hsorbo!
• darwin: Improve tvOS support to also cover frida-server. Thanks @tmm1!
• darwin: Plug memory leak in fallback kill() logic. Thanks @tmm1!
• fruity: Handle failure to fetch dyld symbols.
• compiler: Bump frida-compile to 16.2.2. Dependencies’ source maps are now also bundled – thanks @vfsfitvnm!
• compiler: Bump @types/frida-gum to 18.3.2, now with improved typings for hexdump().
• gdb: Add GDB.Client, by factoring out the guts of Fruity’s LLDB.Client, with many protocol enhancements and interoperability fixes added on top.
• elf-module: Improve API and make it cross-platform. Support loading from a blob, expose relocations, and improve overall robustness.
• capstone: Fix crash on x86 when building with MSVC.

Some exciting stability improvements this time around:

• darwin: Make spawn() aware of the prewarm feature used on iOS >= 15. What happens is that the most frequently used apps are being spawned ahead of time by dasd and kept suspended until the user attempts to launch them, in order to save some startup time. This was in the way of Frida’s spawn mechanism because:
  • apps launched this way won’t be going through launchd when expected, causing a “timeout was reached” error, or more complex race conditions
  • Frida needs to spawn a fresh process to ensure early instrumentation

  We solve these problems by:

  • ignoring prewarm spawns from the launchd agent (though they’re still emitted as spawn if spawn gating is enabled)
  • killing existing prewarmed apps before attempting to spawn them Thanks @mrmacete!
• glib: Ensure {Input,Output}Stream only g_poll() if pollable. This is essential on Apple OSes and BSDs, where GLib uses kqueue to implement GMainContext, as it may otherwise end up waiting forever when the file-descriptor represents an ordinary file. Thanks @hsorbo!
• android: Fix x86 devkits by improving libffi to avoid problematic relocations.
• gadget: Fix deadlock during Windows process termination. Kudos to @Palacee-hun for reporting!

Just a quick bug-fix release reviving support for Android x86/x86_64 systems with ARM emulation. This is still a blind spot in our CI, and I forgot all about it while working on the new Linux injector. Kudos to @stopmosk for promptly reporting and helping triage this regression.

Time for a bug-fix release with only one change: turns out the ARMv8 BTI interop introduced in 16.0.14 is problematic on Apple A12+ SoCs when running in arm64e mode, i.e. with pointer authentication enabled.

Kudos to @miticollo for reporting and helping triage the cause, and @mrmacete for digging further into it, brainstorming potential fixes, and implementing the fix. You guys rock! ❤️

Seeing as TypeScript 5.0 was released last month, and frida.Compiler was still at 4.9, we figured it’s time to upgrade it. So with this release we’re now shipping 5.0.4. The upgrade also revealed a couple of bugs in our V8-based runtime, and that our embedded frida-gum typings were slightly outdated.

Enjoy!

Changelog

• gumjs: Fix task deadlock during V8 Isolate teardown.
• gumjs: Fix undefined behavior during V8 snapshot creation.
• compiler: Bump frida-compile.
• compiler: Use the proper @types/frida-gum.

Here’s a release fixing two stability issues affecting users on Apple platforms:

• interceptor: Keep thread ports alive between suspend and resume on Darwin. We were borrowing the Mach thread port right names released by enumerate_threads(), assuming that another reference existed to keep each of them alive. When this wasn’t the case we would at best pass an invalid Mach port right name to thread_resume(), and worst-case we would use a totally unrelated port. Regardless, we would leave such threads suspended forever. Thanks @mrmacete!
• agent: Dispose ThreadSuspendMonitor in its own transaction. Since Interceptor relies on ThreadSuspendMonitor passthrough, disposing of it in its own transaction and after all the other components which use Interceptor at destruction time makes sure no Frida thread will attempt executing code on non-executable pages at teardown time. Thanks @mrmacete!

More exciting bug-fixes:

• linux: Fix ProcMapsEntry major/minor number parsing. Thanks @chouex!
• interceptor: Fix ARMv8 BTI interoperability. Thanks @zjw88282740!
• arm64-writer: Add put_ret_reg(). Thanks @zjw88282740!
• compiler: Fix filesystem access on some Linux systems, e.g. Ubuntu 20.04. Kudos to @pancake for reporting and helping track this one down!

Only a few bug-fixes this time around:

• android: Fix dynamic linker probing on older systems.
• android: Limit graceful injection to arm and arm64.
• linux: Fix syscall wait logic on x86 and x86_64.

Lots of goodies this time around. One of them is our brand new Linux injector. This was a lot of fun, especially as it involved lots of pair-programming with @hsorbo.

We’re quite excited about this one. Frida now supports injecting into Linux containers, such as Flatpak apps. Not just that, it can finally inject code into processes without a dynamic linker present.

Another neat improvement is if you’re running Frida on Linux >= 3.17, you may notice that it no longer writes out any temporary files. This is accomplished through memfd and a reworked injector signaling mechanism.

Our new Linux injector has a fully asynchronous design, without any dangerous blocking operations that can result in deadlocks. It is also the first injector to support providing a control channel to the injected payload.

Down the road the plan is to implement this in our other backends as well, and make it part of our cross-platform Injector API. The thinking there is to make it easier to implement custom payloads.

There are also many other goodies in this release, so definitely check out the changelog below.

Enjoy!

Changelog

• linux: Re-engineer injector. Thanks for the productive pair-programming, @hsorbo!
• linux: Fix the libc-based module enumeration.
• linux: Fix query_libc_name() on musl.
• linux: Fix module handle resolver logic on musl.
• linux: Fix Module.ensure_initialized() on musl.
• darwin: Make ThreadSuspendMonitor passthrough if called by Frida, to avoid deadlock scenarios. Thanks @mrmacete!
• darwin: During spawn(), always use PTYs for piped stdio, and enable close-on-exec.
• windows: Use existing DbgHelp instance if present. Thanks @fesily!
• windows: Implement Module.enumerate_symbols(). Thanks @fesily!
• process: Skip cloaked modules in enumerate_modules().
• cloak: Add has_range_containing().
• elf-module: Replace has_interp() with get_interpreter().
• gumjs: Fix runtime serialization unsigned encoding.
• objc: Add symbol property on method as a means for the method object to fully describe itself in a human readable way. Thanks @mrmacete!
• java: Use symbols for unique property names. Thanks @yotamN!
• java: Add toString() method to overloads. Thanks @oriori1703!
• java: Add toString() method to types and field. Thanks @yotamN!
• java: Fix toString() for overloaded methods. Thanks @yotamN!
• server: Support loading as a shared library. Thanks @Yannayli!

Only a few bug-fixes this time around:

• darwin: Fix deadlock while pausing threads on non-RWX systems. Thanks @mrmacete!
• darwin: Fix mapping zero-sized segments. Thanks @comex!
• linux: Improve Gum to support programs without a runtime linker.
• linux: Fix error-propagation from Gum.Linux APIs.

This time we’re bringing you additional iOS 15 improvements, an even better frida.Compiler, brand new support for musl libc, and more. Do check out the changelog below for more details.

Enjoy!

Changelog

• ios: Fix spawn() on lower versions of iOS 15. Thanks @as0ler and @mrmacete!
• ios: Ensure launchd prioritizes our daemon. Kudos to @getorix for investigating and suggesting this fix.
• compiler: Bump frida-compile, frida-fs, and Gum typings. This means that frida.Compiler now also works properly on linux-arm64 and linux-x86.
• linux: Add support for musl libc, including CI that publishes release assets for x86_64 and arm64.
• gumjs: Add console.debug() and console.info(). Thanks @oriori1703!
• gumjs: Fix build when node_modules/@types exists above us.
• gumjs: Ignore tcclib.h symbols when generating runtime. Thanks @milahu!
• build: Improve support for shared builds. Thanks @milahu!

The main theme of this release is improved support for jailbroken iOS. We now support iOS 16.3, including app listing and launching. Also included is improved support for iOS 15, and some regression fixes for older iOS versions.

There are also some other goodies in this release, so definitely check out the changelog below.

Enjoy!

Changelog

• darwin: Fix app listing and launching on iOS >= 16. Thanks for the productive pair-programming, @hsorbo!
• darwin: Fix crash during early instrumentation of modern dylds.
• darwin: Fix breakpoint conflict in early instrumentation, a regression introduced in 16.0.8 as part of improving spawn() performance. Thanks @mrmacete!
• package-server-ios: Force xz compression.
• darwin-grafter: Create multiple segments if needed. Thanks @mrmacete!
• interceptor: Flip page protection on Darwin grafted import activation. Thanks @mrmacete!
• stalker: Fix handling of ARM LDMIA without writeback.
• darwin: Add query_protection(). Thanks @mrmacete!
• darwin: Avoid kernel task port probing in hardened processes. Thanks @as0ler!
• darwin: Fix Process.modify_thread() reliability.
• darwin: Fix query_hardened() on iOS w/ tweaks enabled. Thanks @as0ler!
• darwin: Make Process.modify_thread() less disruptive.
• darwin: Optimize Process.modify_thread().
• darwin: Add modify_thread().
• arm-writer: Add put_ldmia_reg_mask_wb().
• gumjs: Fix runtime serialization not handling unicode. Thanks @milahu!
• python: Add async variant to RPC calls. Thanks @yotamN!
• python: Add specific signals type hinting for core. Thanks @yotamN!

This time we’ve focused on polishing up our macOS and iOS support. For those of you using spawn() and spawn-gating for early instrumentation, things are now in much better shape.

i/macOS spawn() performance

The most exciting change in this release is all about performance. Programs that would previously take a while to start when launched using Frida should now be a lot quicker to start. This long-standing bottleneck was so bad that an app with a lot of libraries could fail to launch due to Frida slowing down its startup too much.

i/macOS and SIGPIPE

Next up we have a fix for a long-standing reliability issue. Turns out our file-descriptors used for IPC did not have SO_NOSIGPIPE set, so we could sometimes end up in a situation where either Frida or the target process terminated abruptly, and the other side would end up getting zapped by SIGPIPE while trying to write().

Sandboxed environments, part two

The previous release introduced some bold new changes to support injecting into hardened targets. Since then @hsorbo and me dug back into our recent GLib kqueue() patch and fixed some rough edges. We also fixed a regression where attaching to hardened processes through usbmuxd would fail with “connection closed”.

Linux

On the Linux and Android side of things, some of you may have noticed that thread enumeration could fail randomly, especially inside busy processes. That issue has now finally been dealt with.

Also, thanks to @drosseau we also have an error-handling improvement that should avoid some confusion when things fail in 32-/64-bit cross-arch builds.

EOF

That is all this time around. Enjoy!

It’s been a busy week. Let’s dive in.

Sandboxed environments

This week @hsorbo and me spent some days trying to get Frida working better in sandboxed environments. Our goal was to be able to get Frida into Apple’s SpringBoard process on iOS. But to make things a little interesting, we figured we’d start with imagent, the daemon that handles the iMessage protocol. It has been hardened quite a bit in recent OS versions, and Frida was no longer able to attach to it.

So we first started out with this daemon on macOS, just to make things easier to debug. After finding the daemon’s sandbox profile at /System/Library/Sandbox/Profiles/com.apple.imagent.sb, it was hard to miss the syscall policy. It disallows all syscalls by default, and carefully enables some groups of syscalls, plus some specific ones that it also needs.

We then discovered that Frida’s use of the pipe() syscall was the first hurdle. This code is not actually in Frida itself, but in GLib, the excellent library that Frida uses for data structures, cross-platform threading primitives, event loop, etc. It uses pipe() to implement a primitive needed for its event loop. More precisely, it uses this primitive to wake up the event loop’s thread in case it is blocking in a poll()-style syscall.

Anyway, we noticed that kqueue() is part of the groups of syscalls explicitly allowed. Given that Apple’s kqueue() supports polling file-descriptors and Mach ports at the same time, among other things, it’s likely to be needed in a lot of places, and thus allowed by a broad range of sandbox profiles. It is also a great fit for us, since EVFILT_USER means there is a way to wake up the event loop’s thread. Not just that, but it doesn’t cost us a single file-descriptor.

After lots of coffee and fun pair-programming, we arrived at a patch that switches GLib’s event loop over to kqueue() on OSes that support it. This got us to the next hurdle: Frida is using socket APIs for file-descriptor passing, part of the child-gating feature used for instrumenting children of the current process. However, since hardened system services aren’t likely to be allowed to do things like fork() and execve(), it is fine to simply degrade this part of our functionality. That was tackled next, and boom… Frida is finally able to attach to imagent. 🎉 Yay!

Next up we moved over to iOS and took it for a spin there. Much to our surprise, Frida could attach to SpringBoard right out of the gate. Later we tried notifyd and profiled, and could attach to those too. Even on latest iOS 16. But, there’s still work to do, as Frida cannot yet attach to imagent and WebContent on iOS. This is exciting progress, though.

Injection on iOS >= 15

While doing all of this we also tracked down a crash on iOS where frida-server would get killed due to EXC_GUARD during injection on iOS >= 15. That has now also been fixed, just in time for the release!

DebugSymbol API

Another exciting piece of news is that @mrmacete improved our DebugSymbol API to consistently provide the full path instead of only the filename. This was a long-standing inconsistency across our different platform backends. While at it he also exposed the column, so you also get that in addition to the line number.

Interceptor.replace(), but fast

Last but not least it’s worth mentioning an exciting new improvement in Interceptor. For those of you using it from C, there’s now replace_fast() to complement replace(). This new fast variant emits an inline hook that vectors directly to your replacement. You can still call the original if you want to, but it has to be called through the function pointer that Interceptor gives you as an optional out-parameter. It also cannot be combined with attach() for the same target. It is a lot faster though, so definitely good to be aware of when needing to hook functions in hot code-paths.

EOF

That’s all this time. Enjoy!

Changelog

• darwin: Disable advanced features in hardened processes.
• darwin: Port GLib’s MainContext to use kqueue() instead of poll().
• darwin: Fix EXC_GUARD during injection on iOS >= 15.
• package-server-ios: Port launchd plist to iOS 16.
• gadget: Do not cloak main thread while loading.
• debug-symbol: Ensure path is absolute and add column field. Thanks @mrmacete!
• darwin: Add query_hardened().
• interceptor: Add replace_fast().
• interceptor: Reduce memory usage per target.

Turns out a serious stability regression made it into Frida 16.0.3, where our out-of-process dynamic linker for Apple OSes could end up crashing the target process. This is especially disastrous when the target process is launchd, as it results in a kernel panic. Thanks to the amazing work of @mrmacete, this embarrassing regression is now fixed. 🎉 Enjoy!

Quick bug-fix release this time around: the Android system_server instrumentation adjustments should now work reliably on all systems.

Here’s a brand new release just in time for the weekend! 🎉 A few critical stability fixes this time around.

Enjoy!

Changelog

• gumjs: Fix use-after-free in the V8 JobState logic. Kudos to @pancake for reporting and helping track this one down!
• android: Fix racy Zygote and system_server instrumentation. Thanks for the fun and productive pair-programming, @hsorbo!
• submodules: Add frida-go. Thanks @lateralusd!

Some cool new things this time. Let’s dive right in.

tvOS and watchOS

One of the exciting contributions this time around came from @tmm1, who opened a whole bunch of pull-requests adding support for tvOS. Yay! As part of landing these I took the opportunity to add support for watchOS as well.

This also turned out to be a great time to simplify the build system, getting rid of complexity introduced to support non-Meson build systems such as autotools. So as part of this clean-up we now have separate binaries for Simulator targets such as the iOS Simulator, tvOS Simulator, etc. Previously we only supported the x86_64 iOS Simulator, and now arm64 is covered as well.

macOS 13 and iOS 16

Earlier this week, @hsorbo and I did some fun and productive pair-programming where we tackled the dynamic linker changes in Apple’s latest OSes. Those of you using Frida on i/macOS may have noticed that spawn() stopped working on macOS 13 and iOS 16.

This was a fun one. It turns out that the dyld binary on the filesystem now looks in the dyld_shared_cache for a dyld with the same UUID as itself, and if found vectors execution there instead. Explaining why this broke Frida’s spawn() functionality needs a little context though, so bear with me.

Part of what Frida does when you call attach() is to inject its agent, if it hasn’t already done this. Before performing the injection however, we check if the process is sufficiently initialized, i.e. whether libSystem has been initialized.

When this isn’t the case, such as after spawn(), where the target is suspended at dyld’s entrypoint, Frida basically advances the main thread’s execution until it reaches a point where libSystem is ready. This is typically accomplished using a hardware breakpoint.

So because the new dyld now chains to another copy of itself, inside the dyld_shared_cache, Frida was placing a breakpoint in the version mapped in from the filesystem, instead of the one in the cache. Obviously that never got hit, so we would end up timing out while waiting for this to happen.

The fix was reasonably straight-forward though, so we managed to squeeze this one into the release in the last minute.

Compiler improvements

The frida.Compiler just got a whole lot better, and now supports additional configuration through tsconfig.json, as well as using local frida-gum typings.

V8 debugger

The V8 debugger integration was knocked out by the move to having one V8 Isolate per script, which was a delicate refactoring needed for V8 snapshot support. This is now back in working order.

Dependency upgrades

One of the heavier lifts this time around was clearly dependency upgrades, where most of our dependencies have now been upgraded: from Capstone supporting ARMv9.2 to latest GLib using PCRE2, etc.

The move to PCRE2 means our Memory.scan() regex support just got upgraded, since GLib was previously using PCRE1. We don’t yet enable PCRE2’s JIT on any platforms though, but this would be an easy thing to improve down the road.

Cross-post: frida-tools 12.0.2

We also have a brand new release of frida-tools, which thanks to @tmm1 has a new and exciting feature. The frida-ls-devices tool now displays higher fidelity device names, with OS name and version displayed in a fourth column:

To upgrade:

$ pip3 install -U frida frida-tools

EOF

There are also some other goodies in this release, so definitely check out the changelog below.

Enjoy!

Changelog

• darwin: Add support for watchOS and tvOS. Thanks @tmm1!
• darwin: Fix early instrumentation on macOS 13 and iOS 16. (Thanks for the pair-programming on this one, @hsorbo!)
• interceptor: Suspend threads while mutating pages on W^X systems such as iOS. This improves stability when instrumenting busy processes.
• system-session: Re-enable Exceptor for now.
• compiler: Allow configuring target, lib, and strict.
• compiler: Fix support for local frida-gum typings.
• compiler: Use latest @types/frida-gum from git.
• ci: Drop prebuilds for Node.js 10.
• ci: Publish prebuilds for Node.js 19.
• ci: Publish prebuilds for Electron 21 instead of 20.
• unw-backtracer: Improve accuracy on 32-bit ARM.
• thread: Add suspend() and resume() to the Gum C API.
• darwin: Improve handling of chained fixups.
• darwin: Fix Objective-C symbol synthesis on arm64e.
• linux: Detect noxsave on Linux.
• linux: Improve injector to handle faux .so mappings. Thanks @lx866!
• module-map: Support lookups with ptrauth bits set.
• gumjs: Add NativeFunction traps: ‘none’ option. Thanks @mrmacete!
• gumjs: Prevent File and SQLite APIs from triggering Interceptor. Thanks @mrmacete!
• gumjs: Hold Isolate lock while performing V8 jobs.
• gumjs: Fix deadlock on V8 script teardown.
• gumjs: Fix V8 debugger not seeing loaded scripts.
• gumjs: Fix CModule external toolchain support on Darwin/arm64e.
• gumjs: Fall back if V8 MAP_JIT fails on Darwin.
• gumjs: Do not freeze V8 flags after init, to avoid issues with hardened processes on Darwin.
• socket: Upgrade to libsoup 3.x for HTTP/2 support.
• devkit: Add .gir to the frida-core kit. Thanks @lateralusd!
• devkit: Update examples to the current Device API.
• python: Support UNIX socket addresses everywhere.
• node: Fix Node.js v19 compatibility.
• deps: Upgrade most of the dependencies to the latest and greatest.
• build: Refactor to get rid of non-Meson cruft.

It’s Friday! Here’s a brand new release with lots of improvements:

• macOS: Fix support for attaching to arm64e system apps and services on macOS >= 12.
• i/macOS: Upgrade support for chained fixups.
• iOS: Fix system session on arm64e devices running iOS < 14.
• system-session: Disable Exceptor and monitors.
  • Exceptor interferes with the signal handling of the hosting process, which is risky and prone to conflict.
  • Monitors aren’t really useful for the system session.
• interceptor: Fix trampolines used in grafted mode on iOS/arm64. Thanks @mrmacete!
• compiler: Fix stability issues on multiple platforms.
• compiler: Fix the @frida/path shim.
• compiler: Speed things up by also making use of snapshot on non-x86/64 Linux.
• devkit: Fix regressions in the Windows, macOS, and Linux devkits.
• v8: Fix heap corruptions caused by our libc-shim failing to implement malloc_usable_size() APIs, which V8 relies on.
• v8: Fix support for scripts using different snapshots, which was broken due to V8 previously being configured to share read-only space across isolates. That option conflicts with multiple snapshots.
• v8: Improve teardown.
• v8: Fix v8::External API contract violations.
• v8: Upgrade to 10.9.42.
• zlib: Upgrade to 1.2.13.
• gum: Fix subproject build for ELF-based OSes.
• python: Fix tags of published Linux wheels.
  • Add legacy platform tags so older versions of pip recognize them.
  • Pretend some of the wheels require glibc >= 2.17, as lower versions aren’t recognized on certain architectures.

Two small but significant bugfixes this time around:

• python: Fix computed sdist version metadata.
• python: Assume non-universal devkit build on macOS.

Hope some of you are enjoying frida.Compiler! In case you have no idea what that is, check out the 15.2.0 release notes.

Performance

Back in 15.2.0 there was something that bothered me about frida.Compiler: it would take a few seconds just to compile a tiny “Hello World”, even on my i9-12900K Linux workstation:

$ time frida-compile explore.ts -o _agent.js

real	0m1.491s
user	0m3.016s
sys	0m0.115s

After a lot of profiling and insane amounts of yak shaving, I finally arrived at this:

$ time frida-compile explore.ts -o _agent.js

real	0m0.325s
user	0m0.244s
sys	0m0.109s

That’s quite a difference! This means on-the-fly compilation use-cases such as frida -l explore.ts are now a lot smoother. More importantly though, it means Frida-based tools can load user scripts this way without making their users suffer through seconds of startup delay.

Snapshots

You might be wondering how we made our compiler so quick to start. If you take a peek under the hood, you’ll see that it uses the TypeScript compiler. This is quite a bit of code to parse and run at startup. Also, loading and processing the .d.ts files that define all of the types involved is actually even more expensive.

The first optimization that we implemented back in 15.2 was to simply use our V8 runtime if it’s available. That alone gave us a nice speed boost. However, after a bit of profiling it was clear that V8 realized that it’s dealing with a heavy workload once we start processing the .d.ts files, and that resulted in it spending a big chunk of time just optimizing the TypeScript compiler’s code.

This reminded me of a really cool V8 feature that I’d noticed a long time ago: custom startup snapshots. Basically if we could warm up the TypeScript compiler ahead of time and also pre-create all of the .d.ts source files when building Frida, we could snapshot the VM’s state at that point and embed the resulting startup snapshot. Then at runtime we can boot from the snapshot and hit the ground running.

As part of implementing this, I extended GumJS so a snapshot can be passed to create_script(), together with the source code of the agent. There is also snapshot_script(), used to create the snapshot in the first place.

For example:

import frida

session = frida.attach(0)

snapshot = session.snapshot_script("const example = { magic: 42 };",
                                   warmup_script="true",
                                   runtime="v8")
print("Snapshot created! Size:", len(snapshot))

This snapshot could then be saved to a file and later loaded like this:

script = session.create_script("console.log(JSON.stringify(example));",
                               snapshot=snapshot,
                               runtime="v8")
script.load()

Note that snapshots need to be created on the same OS/architecture/V8 version as they’re later going to be loaded on.

V8 10.x

Another exciting bit of news is that we’ve upgraded V8 to 10.x, which means we get to enjoy the latest VM refinements and JavaScript language features. Considering that our last upgrade was more than two years ago, it’s definitely a solid upgrade this time around.

The curse of multiple build systems, part two

As you may recall from the 15.1.15 release notes, we were closer than ever to reaching the milestone where all of Frida can be built with a single build system. The only component left at that point was V8, which we used to build using Google’s GN build system. I’m happy to report that we have finally reached that milestone. We now have a brand new Meson build system for V8. Yay!

EOF

There’s also a bunch of other exciting changes, so definitely check out the changelog below.

Enjoy!

Changelog

• compiler: Use snapshot to reduce startup time.
• compiler: Bump frida-compile and other dependencies.
• Add support for JavaScript VM snapshots. This is only implemented by the V8 backend, as QuickJS does not currently support this.
• Move debugger API from Session to Script. This is necessary since V8’s debugger works on a per-Isolate basis, and we now need one Isolate per Script in order to support snapshots.
• server+portal: Fix daemon parent ready fail exit. Thanks @pachoo!
• resource-compiler: Add support for compression. We make use of this for frida.Compiler’s heap snapshot.
• ipc: Bump UNIX socket buffer sizes for improved throughput.
• meson: Promote frida-payload to public API. This allows implementing custom payloads for use-cases where frida-agent and frida-gadget aren’t suitable.
• windows: Move to Visual Studio 2022.
• windows: Move toolchain/SDK logic to use granular SDKs.
• windows: Do not rely on .py file association.
• darwin: Fix compatibility with macOS 13 and iOS >= 15.6.1.
• darwin: Use Apple’s libffi-trampolines.dylib if present, so we can support iOS 15 and beyond. Thanks for the fun pair-programming sessions, @hsorbo!
• fruity: Fix handling of USBMUXD_SOCKET_ADDRESS. Thanks @0x3c3e!
• fruity: Drop support for USBMUXD_SERVER_* envvars. Thanks @as0ler!
• droidy: Improve handling of ADB envvars. Thanks @0x3c3e!
• java: (android) Fix ClassLinker offset detection on Android 11 & 12 (#264). Thanks @sh4dowb!
• java: (android) Fix early instrumentation on Android 13.
• java: Handle methods and fields prefixed with $. Thanks @eybisi!
• android: Move to NDK r25.
• arm64: Optimize memory copy implementation.
• stalker: Ensure EventSink gets stopped on teardown.
• stalker: Fix ARM stack clobbering when branch involves a shift.
• stalker: Handle ARM PC load involving shifted register.
• stalker: Notify ARM observer when backpatches are applied.
• stalker: Apply ARM backpatches when notified.
• stalker: Add ARM support for switch block callback.
• arm-reader: Expose disassemble_instruction_at().
• thumb-reader: Expose disassemble_instruction_at().
• memory: Realign API with current V8 semantics.
• gumjs: Move V8 backend to one Isolate per script.
• gumjs: Support passing V8 flags using an env var: FRIDA_V8_EXTRA_FLAGS.
• gumjs: Use V8 write protection on Darwin/arm*.
• gumjs: Add support for dynamically defined scripts.
• prof: Support old system headers on Linux/MIPS.
• devkit: Improve examples’ compilation docs on UNIX.
• ci: Migrate remainder of the legacy CI to GitHub Actions.
• quickjs: Fix use-after-free on error during module evaluation.
• v8: Upgrade to latest V8 10.x.
• v8: Add Meson build system.
• usrsctp: Lower Windows requirement to XP, like the rest of our components.
• xz: Avoid ANSI-era Windows API.
• libc-shim: Support old system headers on Linux/MIPS.
• glib: Add Linux libc fallbacks for MIPS.
• Add config.mk option to be able to disable emulated agents on Android, to allow building smaller binaries. Thanks @muhzii!
• python: Drop Python 2 support, modernize code, add docstrings, typings, add CI with modern tooling, and many other goodies. Thanks @yotamN!
• python: Build Python wheels instead of eggs. Thanks @oriori1703!
• python: Fix Device.get_bus(). The previous implementation called _Device.get_bus(), which doesn’t exist. Thanks @oriori1703!
• python: Move to the stable Python C API.
• python: Add support for building from source, using a frida-core devkit.
• python: Add support for the new snapshot APIs.
• node: Add support for the new snapshot APIs.
• node: Fix Electron v20 compatibility.

Two more improvements, just in time for the weekend:

• darwin: Always host system session locally. In this way we avoid needing to write our frida-helper to a temporary file and spawn it just to use the system session (PID 0).
• darwin: Rework frida-helper IPC to avoid Mach ports. This means we avoid crashing on recent versions of macOS. Kudos to co-author @hsorbo for the productive pair-programming on this one!

Two small but significant bugfixes this time around:

• compiler: Ignore irrelevant changes during watch().
• darwin: Improve accuracy of memory range file info. By using PROC_PIDREGIONPATHINFO2 when available, so the query is constrained to vnode-backed mappings. Kudos to @i0n1c for discovering and tracking down this long-standing issue.

Super-excited about this one. What I’ve been wanting to do for years is to streamline Frida’s JavaScript developer experience. As a developer I may start out with a really simple agent, but as it grows I start to feel the pain.

Early on I may want to split up the agent into multiple files. I may also want to use some off-the-shelf packages from npm, such as frida-remote-stream. Later I’d want code completion, inline docs, type checking, etc., so I move the agent to TypeScript and fire up VS Code.

Since we’ve been piggybacking on the amazing frontend web tooling that’s already out there, we already have all the pieces of the puzzle. We can use a bundler such as Rollup to combine our source files into a single .js, we can use @frida/rollup-plugin-node-polyfills for interop with packages from npm, and we can plug in @rollup/plugin-typescript for TypeScript support.

That is quite a bit of plumbing to set up over and over though, so I eventually created frida-compile as a simple tool that does the plumbing for you, with configuration defaults optimized for what makes sense in a Frida context. Still though, this does require some boilerplate such as package.json, tsconfig.json, and so forth.

To solve that, I published frida-agent-example, a repo that can be cloned and used as a starting point. That is still a bit of friction, so later frida-tools got a new CLI tool called frida-create. Anyway, even with all of that, we’re still asking the user to install Node.js and deal with npm, and potentially also feel confused by the .json files just sitting there.

Then it struck me. What if we could use frida-compile to compile frida-compile into a self-contained .js that we can run on Frida’s system session? The system session is a somewhat obscure feature where you can load scripts inside of the process hosting frida-core. For example if you’re using our Python bindings, that process would be the Python interpreter.

Once we are able to run that frida-compile agent inside of GumJS, we can communicate with it and turn that into an API. This API can then be exposed by language bindings, and frida-tools can consume it to give the user a frida-compile CLI tool that doesn’t require Node.js/npm to be installed. Tools such as our REPL can seamlessly use this API too if the user asks it to load a script with a .ts extension.

And all of that is precisely what we have done! 🥳

build()

Here’s how easy it is to use it from Python:

import frida

compiler = frida.Compiler()
bundle = compiler.build("agent.ts")

The bundle variable is a string that can be passed to create_script(), or written to a file.

Running that example we might see something like:

Traceback (most recent call last):
  File "/home/oleavr/src/explore.py", line 4, in <module>
    bundle = compiler.build("agent.ts")
  File "/home/oleavr/.local/lib/python3.10/site-packages/frida/core.py", line 76, in wrapper
    return f(*args, **kwargs)
  File "/home/oleavr/.local/lib/python3.10/site-packages/frida/core.py", line 1150, in build
    return self._impl.build(entrypoint, **kwargs)
frida.NotSupportedError: compilation failed

That makes us wonder why it failed, so let’s add a handler for the diagnostics signal:

import frida

def on_diagnostics(diag):
    print("on_diagnostics:", diag)

compiler = frida.Compiler()
compiler.on("diagnostics", on_diagnostics)
bundle = compiler.build("agent.ts")

And suddenly it’s all making sense:

on_diagnostics: [{'category': 'error', 'code': 6053,
    'text': "File '/home/oleavr/src/agent.ts' not "
            "found.\n  The file is in the program "
            "because:\n    Root file specified for"
             " compilation"}]
…

We forgot to actually create the file! Ok, let’s create agent.ts:

console.log("Hello from Frida:", Frida.version);

And let’s also write that script to a file:

import frida

def on_diagnostics(diag):
    print("on_diagnostics:", diag)

compiler = frida.Compiler()
compiler.on("diagnostics", on_diagnostics)
bundle = compiler.build("agent.ts")
with open("_agent.js", "w", newline="\n") as f:
    f.write(bundle)

If we now run it, we should have an _agent.js ready to go:

$ cat _agent.js
📦
175 /explore.js.map
39 /explore.js
✄
{"version":3,"file":"explore.js","sourceRoot":"/home/oleavr/src/","sources":["explore.ts"],"names":[],"mappings":"AAAA,OAAO,CAAC,GAAG,CAAC,SAAS,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC"}
✄
console.log(`Hello ${Frida.version}!`);

This weird-looking format is how GumJS’ allows us to opt into the new ECMAScript Module (ESM) format where code is confined to the module it belongs to instead of being evaluated in the global scope. What this also means is we can load multiple modules that import/export values. The .map files are optional and can be omitted, but if left in they allow GumJS to map the generated JavaScript line numbers back to TypeScript in stack traces.

Anyway, let’s take _agent.js for a spin:

$ frida -p 0 -l _agent.js
     ____
    / _  |   Frida 15.2.0 - A world-class dynamic instrumentation toolkit
   | (_| |
    > _  |   Commands:
   /_/ |_|       help      -> Displays the help system
   . . . .       object?   -> Display information about 'object'
   . . . .       exit/quit -> Exit
   . . . .
   . . . .   More info at https://frida.re/docs/home/
   . . . .
   . . . .   Connected to Local System (id=local)
Attaching...
Hello 15.2.0!
[Local::SystemSession ]->

It works! Now let’s try refactoring it to split the code into two files:

agent.ts

import { log } from "./log.js";

log("Hello from Frida:", Frida.version);

log.ts

export function log(...args: any[]) {
    console.log(...args);
}

If we now run our example compiler script again, it should produce a slightly more interesting-looking _agent.js:

📦
204 /agent.js.map
72 /agent.js
199 /log.js.map
58 /log.js
✄
{"version":3,"file":"agent.js","sourceRoot":"/home/oleavr/src/","sources":["agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAE/B,GAAG,CAAC,mBAAmB,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC"}
✄
import { log } from "./log.js";
log("Hello from Frida:", Frida.version);
✄
{"version":3,"file":"log.js","sourceRoot":"/home/oleavr/src/","sources":["log.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,GAAG,CAAC,GAAG,IAAW;IAC9B,OAAO,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;AACzB,CAAC"}
✄
export function log(...args) {
    console.log(...args);
}

Loading that into the REPL should yield the exact same result as before.

watch()

Let’s turn our toy compiler into a tool that loads the compiled script, and recompiles whenever a source file changes on disk:

import frida
import sys

session = frida.attach(0)
script = None

def on_output(bundle):
    global script
    if script is not None:
        print("Unloading old bundle...")
        script.unload()
        script = None
    print("Loading bundle...")
    script = session.create_script(bundle)
    script.on("message", on_message)
    script.load()

def on_diagnostics(diag):
    print("on_diagnostics:", diag)

def on_message(message, data):
    print("on_message:", message)

compiler = frida.Compiler()
compiler.on("output", on_output)
compiler.on("diagnostics", on_diagnostics)
compiler.watch("agent.ts")

sys.stdin.read()

And off we go:

$ python3 explore.py
Loading bundle...
Hello from Frida: 15.2.0

If we leave that running and then edit the source code on disk we should see some new output:

Unloading old bundle...
Loading bundle...
Hello from Frida version: 15.2.0

Yay!

frida-compile

We can also use frida-tools’ new frida-compile CLI tool:

$ frida-compile agent.ts -o _agent.js

It also supports watch mode:

$ frida-compile agent.ts -o _agent.js -w

REPL

Our REPL is also powered by the new frida.Compiler:

$ frida -p 0 -l agent.ts
     ____
    / _  |   Frida 15.2.0 - A world-class dynamic instrumentation toolkit
   | (_| |
    > _  |   Commands:
   /_/ |_|       help      -> Displays the help system
   . . . .       object?   -> Display information about 'object'
   . . . .       exit/quit -> Exit
   . . . .
   . . . .   More info at https://frida.re/docs/home/
   . . . .
   . . . .   Connected to Local System (id=local)
Compiled agent.ts (1428 ms)
Hello from Frida version: 15.2.0
[Local::SystemSession ]->

Shoutout

Shoutout to @hsorbo for the fun and productive pair-programming sessions where we were working on frida.Compiler together! 🙌

EOF

There are also quite a few other goodies in this release, so definitely check out the changelog below.

Enjoy!

Changelog

• core: Add Compiler API. Only exposed by Python bindings for now, but available from C/Vala.
• interceptor: Improve replace() to support returning original. Thanks @aviramha!
• gumjs: Fix typing for pc in the writer options.
• gumjs: Fix V8 ESM crash with circular dependencies.
• gumjs: Handle ESM bundles with multiple aliases per module.
• gumjs: Tighten up the Checksum data argument parsing.
• android: Fix null pointer deref in crash delivery. Thanks @muhzii!
• fruity: Use env variables to find usbmuxd. Thanks @0x3c3e!
• ios: Make Substrate detection logic a bit more resilient. Thanks @lemon4ex!
• meson: Only try to use V8 if available. Thanks @muhzii!
• windows: Add support for building without V8.
• devkit: Fix library dependency hints on Windows. Thanks @nblog!

A couple of exciting new things in this release.

File API

Those of you using our JavaScript File API may have noticed that it supports writing to the given file, but there was no way to read from it. This is now supported.

For example, to read each line of a text-file as a string:

const f = new File('/etc/passwd', 'r');
let line;
while ((line = f.readLine()) !== '') {
  console.log(`Read line: ${line.trimEnd()}`);
}

(Note that this assumes that the text-file is UTF-8-encoded. Other encodings are not currently supported.)

You can also read a certain number of bytes at some offset:

const f = new File('/var/run/utmp', 'rb');
f.seek(0x2c);
const data = f.readBytes(3);
const str = f.readText(3);

The argument may also be omitted to read the rest of the file. But if you’re just looking to read a text file in one go, there’s an easier way:

const text = File.readAllText('/etc/passwd');

Reading a binary file is just as easy:

const bytes = File.readAllBytes('/var/run/utmp');

(Where bytes is an ArrayBuffer.)

Sometimes you may also want to dump a string into a text file:

File.writeAllText('/tmp/secret.txt', 'so secret');

Or perhaps dump an ArrayBuffer:

const data = args[0].readByteArray(256);
File.writeAllBytes('/tmp/mystery.bin', data);

Going back to the example earlier, seek() also supports relative offsets:

f.seek(7, File.SEEK_CUR);
f.seek(-3, File.SEEK_END);

Retrieving the current file offset is just as easy:

const offset = f.tell();

Checksum API

The other JavaScript API addition this time around is for when you want to compute checksums. While this could be implemented in JavaScript entirely in “userland”, we do get it fairly cheap since Frida depends on GLib, and it already provides a Checksum API out of the box. All we needed to do was expose it.

Putting it all together, this means we can read a file and compute its SHA-256:

const utmp = File.readAllBytes('/var/run/utmp');
const str = Checksum.compute('sha256', utmp);

Or, for more control:

const checksum = new Checksum('sha256');
checksum.update(File.readAllText('/etc/hosts'));
checksum.update(File.readAllBytes('/var/run/utmp'));
console.log('Result:', checksum.getString());
console.log(hexdump(checksum.getDigest(), { ansi: true }));

(You can learn more about this API from our TypeScript bindings.)

EOF

There are also a few other goodies in this release, so definitely check out the changelog below.

Enjoy!

Changelog

• gumjs: Extend the File API.
• gumjs: Add Checksum API.
• gumjs: Fix handling of relative ESM imports from root.
• glib: (win32) Add Input/OutputStream support for plain files.
• build: Make XP SDK optional on Windows.
• node: Target Electron 19.0.0 instead of 19.0.0-alpha.1.
• node: Define openssl_fips to work around node-gyp issue.

It appears I should have had some more coffee this morning, so here’s another release to actually fix this broken fix back in 15.1.25:

• java: (android) Prevent ART from compiling replaced methods

Turns out the kAccCompileDontBother constant changed in Android 8.1. It also didn’t exist before 7.0. Oops! This release fixes it, for real this time 😊

Only one change this time around, related to this fix in the previous release:

• java: (android) Prevent ART from compiling replaced methods

Well, turns out the kAccCompileDontBother constant was incorrect. This release fixes it. (Spoiler from the future: it didn’t.)

Quite a few exciting bits in this release. Let’s dive right in.

FPU/vector register access

Some great news for those of you using Frida on 32- and 64-bit ARM. Up until now, we have only exposed the CPU’s integer registers, but as of this release, FPU/vector registers are also available! 🎉

For 32-bit ARM this means q0 through q15, d0 through d31, and s0 through s31. As for 64-bit ARM they’re q0 through q31, d0 through d31, and s0 through s31. If you’re accessing these from JavaScript, the vector properties are represented using ArrayBuffer, whereas for the others we’re using the number type.

Java.backtrace()

Our existing Java.backtrace() API now provides a couple of new properties in the returned frames, which now also expose methodFlags and origin.

Quality

I finally plugged a memory leak in our RPC server-side code. This was introduced by me in 15.1.10 when implementing an optimization in the Vala compiler’s code generation for DBus reply handling. Shoutout to @rev1si0n for reporting and helping track down this regression!

EOF

There are also some other goodies in this release, so definitely check out the changelog below.

Enjoy!

Changelog

• vala: Plug leak in server-side GDBus reply handling. This affected all server-side implementations in Frida.
• glib: Disable support for “charset.alias”. This means we no longer try to open this file, which could cause sandbox violations on some systems, such as iOS.
• java: (android) Add methodFlags to Java.backtrace() frames.
• java: (android) Add origin to Java.backtrace() frames.
• java: (android) Prevent ART from compiling replaced methods. Kudos to @s1341 for figuring this one out!
• cpu-context: Add ARM FPU/vector registers and NZCV.
• cpu-features: Add VFPD32 flag and detection logic.
• stalker: Fix VFP D32 detection in the arm backend.
• gumjs: Add vector regs to arm_reg bindings.
• x86-writer: Add put_fx{save,rstor}_reg_ptr().
• arm-writer: Add load/store variants without offset.
• arm-writer: Add put_v{push,pop}_range().
• arm-writer: Remove noop check from put_ands_reg_reg_imm().
• arm-writer: Rename *_registers() to *_regs().
• arm-writer: Support vector push/pop with Q regs.
• thumb-writer: Add put_v{push,pop}_range().
• thumb-writer: Support vector push/pop with Q regs.
• arm64-writer: Add load/store variants without offset.
• arm64-writer: Add put_mov_{reg_nzcv,nzcv_reg}().
• libc-shim: Support old system headers on Linux/ARM.
• node: Bump dependencies.
• node: Publish prebuilds for Electron 19 instead of 18.

Only one change this time, but it’s an important one for those of you using Frida on Android: Our Java method hooking implementation was crashing in some cases, where we would pick a scratch register that conflicted with the generated code. This is now fixed.

Enjoy!

The main theme of this release is OS support, where we’ve fixed some rough edges on Android 12, and introduced preliminary support for Android 13. While working on frida-java-bridge I also found myself needing some of the JVMTI code in the JVM-specific backend. Those bits are now shared, and the JVM-specific code is in better shape, with brand new support for JDK 17.

We have also improved stability in several places, and made it easier to use the CodeWriter APIs safely. Portability has also been improved, where our QuickJS-based JavaScript runtime finally works when cross-compiled for big-endian from a little-endian build machine, and vice versa.

To learn more, be sure to check out the changelog below.

Enjoy!

Changelog

• linux: Handle spurious signals during ptrace().
• android: Add missing SELinux rule for system_server on Android 12+.
• android: Fix Android 13 detection on real devices.
• android: Handle new linker internals in Android 13.
• java: Improve the Java.enumerateMethods() error message. Thanks @jpstotz!
• java: (android) Handle inlined GetOatQuickMethodHeader().
• java: (android) Improve support for non-Google Android 12+ ROMs.
• java: (android) Fix Java.choose() on Android >= 12.
• java: (android) Add support for Android 13.
• java: (android) Fix threadReg clobber in the x64 recompilation logic.
• java: (android) Explain why Java.deoptimizeBootImage() is unavailable.
• java: (android) Expose JVMTI through api.jvmti.
• java: (android) Improve error messages about OS features.
• java: (jvm) Add basic support for JDK 17.
• java: (jvm) Add fallback for thread_from_jni_environment().
• java: (jvm) Fix UAF in withJvmThread() prologue/epilogue logic.
• java: (jvm) Improve InstanceKlass offset detection.
• code-writer: Add flush_on_destroy option.
• gumjs: Disable the CodeWriter flush_on_destroy option. In this way, the writers are safer to use as they won’t be writing to memory once they’re garbage-collected. At that point the target memory may no longer be writable, or might be owned by other code.
• gumjs: Embed byteswapped QuickJS bytecode when needed. This means GumJS can be cross-compiled across endians.
• gumjs: Fix double free in the Instruction copy logic.
• gumjs: Fix Relocator instruction accessors.
• gumjs: Flush CodeWriter on reset() and dispose().
• gumjs: Improve NativePointer#strip() to support ARM TBI.
• gumjs: Make Instruction wrapper safer in zero-copy mode.
• gumjs: Plug Relocator leak in the QuickJS runtime.
• quickjs: Fix support for byteswapped output. Also upgrade QuickJS to latest upstream version with Unicode 14 updates.

Turns out the major surgery that Gum went through in 15.1.15 introduced some error-handling regressions. Errors thrown vs. actually expected by the Vala code in frida-core did not match, which resulted in the process crashing instead of a friendly error bubbling up to e.g. the Python bindings. That is now finally taken care of. I wish we had noticed it sooner, though — we’re clearly lacking test coverage in this area.

Beside the error-handling fixes, we’re also including a build system fix for incremental build issues. Kudos to Londek for this nice contribution.

Enjoy!

Only change this time is an important bugfix for i/macOS, where imports could not always be resolved. Kudos to @mrmacete for this fix.

Enjoy!

It was discovered that 15.1.10 broke inline hooking in frida-java-bridge on Android/x86_64. This release fixes it.

This time we’re also moving to shipping Node.js prebuilds for v18 instead of v17. (Sigh, should port frida-node to Node-API so we can stop this madness!)

Enjoy!

Turns out 15.1.18 had a release automation bug that resulted in stale Python binding artifacts getting uploaded.

To make this release a little happier, I also threw in a Stalker improvement for x86/64, where the clone3 syscall is now handled as well. This was caught by Stalker’s test-suite on some systems.

Enjoy!

Lots of improvements all over the place this time. Many stability improvements.

I have continued improving our CI and build system infrastructure. QNX and MIPS support are back from the dead, after long-standing regressions. These went unnoticed due to lack of CI coverage. We now have CI in place to ensure that won’t happen again.

Do check out the changelog below for a full overview of what’s new.

Enjoy!

Changelog

• gadget: Fix deadlock when Gadget is blocking the dynamic linker with its internal lock(s) held while waiting for resume(). In that case we are processing the JS MainContext while blocking, with network I/O handled by the Gadget thread. Because Stalker may interact with the dynamic linker during its class_init(), we must ensure that it happens from the JS thread and not the network I/O thread.
• exit-monitor: Fix deadlock when a fork() goes unnoticed.
• darwin: Skip pseudo-signing when running on Corellium.
• darwin: Fix compatibility with older iOS SDKs.
• darwin-backtracer: Fix loop variable wrap-around.
• darwin-mapper: Fix footprint budgeting w/ chained fixups.
• linux: Fix the Process.modify_thread() wait logic.
• linux: Fully resolve libc on modern glibc systems.
• linux: Remove the Linjector cleanup delay.
• ios: Add config.mk option for building without jailbreak support code, for compatibility with e.g. TestFlight.
• ios: Eliminate dependency on external Mach VM header.
• android: Fix unw_getcontext() on Android/x86, which resulted in stack corruption during e.g. Thread.backtrace().
• freebsd: Add BSDmakefile for convenience.
• freebsd: Fix gum_clear_cache() reliability.
• freebsd: Improve the program path query API.
• freebsd: Try a bit harder when MAP_32BIT fails.
• mips: Fix long-standing regressions that went unnoticed due to lack of CI.
• qnx: Fix long-standing regressions that went unnoticed due to lack of CI. Also improve the QNX backend while at it.
• posix: Use posix_madvise() if madvise() is unavailable.
• stalker: Detect thread exit implementation on glibc, Android, and FreeBSD.
• stalker: Fix Linux clone() support in the x86 backend.
• stalker: Fix backpatching of JECXZ/JRCXZ x86 instructions.
• stalker: Fix two pc vs code mixups in the x86 backend.
• stalker: Optimize Linux syscall logic in the x86 backend.
• stalker: Move unwind support behind an API.
• stalker: Simplify and fix the x86 unwind Interceptor logic.
• stalker: Implement unwind hooking in the arm64 backend. Thanks @s1341!
• stalker: Add backpatch query support.
• stalker: Add support for recompiling blocks.
• process: Add resolve_module_pointer().
• elf-module: Improve the DT_SYMTAB entry count detection.
• elf-module: Skip symbols with a dangling name reference.
• symbolutil-libdwarf: Add support for DWARF v5.
• libdwarf: Backport upstream fix for handling of DW_FORM_line_strp.
• dbghelp-backtracer: Improve reliability on 32-bit x86.
• arm-relocator: Simplify PC-relative LDR handling.
• arm-writer: Add call_reg_with_arguments*().
• arm-writer: Handle put_call*() w/ more than four args.
• thumb-writer: Handle put_call*() stack alignment.
• arm64-writer: Optimize LDR reg, #0.
• x86-relocator: Add input_pc to support offline use.
• x86-relocator: Fix PC vs output mixup in RIP-relative fast-path.
• x86-relocator: Improve the RIP offset fixup logic.
• bounds-checker: Fall back to the matching heap API.
• gumjs: Fix CModule memory allocation logic.
• gumjs: Fix CModule runtime with internal TinyCC.
• gumjs: Lower build-time Python requirement to 3.7.
• heap-api: Improve libc detection on non-Windows OSes.
• heap-api: Include static MSVC CRT APIs in the list.
• gum: Improve Meson build system to support MSVC.
• gum: Improve Gum vapis to expose more APIs.
• core: Fix build failure with some locales by switching off localization when invoking tools from modulate.py.
• python: Fix stability issue caused by incorrect refcounting in get_max_argument_count().
• python: Fix get_index_url_from_pip(). Thanks @X5tar!
• python: Fix index URL retrieval on Python < 3.6. Thanks @serfend!
• node: Publish prebuilds for Electron 18 instead of 16.
• ci: Add Linux/MIPS, FreeBSD/x86_64, FreeBSD/arm64, and QNX/armeabi. For Gum, also add Windows/x86_64, macOS/x86_64, Linux/x86, Linux/x86_64, iOS/arm64, Android/x86, Android/arm, and Android/arm64.

One notable improvement in this release is that Java.backtrace() got a major overhaul. It is now lazy and >10x faster. I have also refined its API, which is now considered stable.

While working on frida-java-bridge, I optimized how Env objects are handled, so we can recycle an existing instance if we already have one for the current thread.

The remaining goodies are covered by the changelog below, so definitely check it out.

Enjoy!

Changelog

• Fix devkits for i/macOS, Android, and QNX, where parts of libiconv were missing.
• Improve devkit packaging on LLVM toolchains.
• Improve diet mode support in GLib.
• cmodule: Expose g_strndup().
• cmodule: Expose Gum’s Thread Local Storage API.
• java: Rework Java.backtrace() to be lazy and >10x faster.
  • Move thread transition and stack walking logic to CModule.
  • Return a Backtrace object instead of an array with the frames.
  • Provide a cheap id property that can be used for deduplication.
  • Lazily compute the frames when accessing the frames property.
• java: Avoid expensive Env creation when possible.
• python: Improve index URL handling. Thanks @GalaxySnail!

This time we’re bringing you two bugfixes and one new feature, just in time for the weekend.

Gum used to depend on GIO, but that dependency was removed in the previous release. The unfortunate result of that change was that agent and gadget no longer tore down GIO, as they were relying on Gum’s teardown code doing that. What this meant was that we were leaving threads behind, and that is never a good thing. So that’s the first bugfix.

Also in the previous release, over in our Python bindings, setup.py went through some heavy changes. We improved the .egg download logic, but managed to break the local .egg logic. That’s the second bugfix.

Onto the new feature. For those of you using Gum’s JavaScript bindings, GumJS, we now support console.count() and console.countReset(). These are implemented by browsers and Node.js, and make it easy to count the number of times a given label has been seen. Kudos to @yotamN for this nice contribution.

Enjoy!

Quite a few exciting bits in this release. Let’s dive right in.

FreeBSD

Our ambition is to support all platforms that our users care about. In this release I wanted to plant the first seed in expanding that to BSDs. So now I’m thrilled to announce that Frida finally also supports FreeBSD! 🎉

For now we only support x86_64 and arm64, but expanding to the remaining architectures is straight-forward in case anybody is interested in helping out.

The porting effort resulted in several architectural refinements and improved robustness for ELF-based OSes in general. It also gave me some ideas on how to improve our Linux injector to support injecting into containers, which is something I’d like to do down the road.

Stalker Performance

Back in 15.1.10, Stalker got a massive performance boost on x86/64. In this release those same ideas have been applied to our arm64 backend. This includes improved locality, better inline caches, etc. I’m told we were able to beat or match QEMU in FuzzBench back then, and now we should be in good shape on arm64 as well. We also managed to improve stability while at it. Exciting!

GObject Introspection

Back in 14.1, @meme wired up build system support for GObject Introspection. This means we have a machine-readable description of all of our APIs, which lets us piggyback on existing language binding infrastructure, and even get auto-generated reference docs for free.

This release adds a lot of annotations and doc-strings to Gum, and we are now closer than ever to having auto-generated reference docs. Still some work left to do before it makes sense to publish the generated documentation, but it’s not far off. If anyone is interested in pitching in, check out Gum’s CI and have a look at the warnings output by GObject Introspection.

Meson subproject support

One thing I really like about the Meson build system is its support for subprojects. Gum now supports being used as a subproject. Some of you may already be consuming Gum through its devkit binaries, and now you have a brand new option that is even easier.

The main advantage over using a devkit is that everything is built from source, so it’s easy to experiment with the code.

Let’s say we have a file hello.c that contains:

#define _GNU_SOURCE
#include <dlfcn.h>
#include <fcntl.h>
#include <gum.h>
#include <stdio.h>
#include <unistd.h>

static int (* open_impl) (const char * path, int oflag, ...);
static int replacement_open (const char * path, int oflag, ...);

int
main (int argc,
      char * argv[])
{
  gum_init ();

  GumInterceptor * interceptor = gum_interceptor_obtain ();

  gum_interceptor_begin_transaction (interceptor);

  open_impl = dlsym (RTLD_DEFAULT, "open");
  gum_interceptor_replace (interceptor, open_impl, replacement_open,
      NULL, NULL);

  gum_interceptor_end_transaction (interceptor);

  close (open_impl ("/etc/hosts", O_RDONLY));
  close (open_impl ("/etc/fstab", O_RDONLY));

  return 0;
}

static int
replacement_open (const char * path,
                  int oflag,
                  ...)
{
  printf ("!!! open(\"%s\", 0x%x)\n", path, oflag);

  return open_impl (path, oflag);
}

To build it we can create a meson.build next to it with the following:

project('hello', 'c')
gum = dependency('frida-gum-1.0')
executable('hello', 'hello.c', dependencies: [gum])

And create subprojects/frida-gum.wrap containing:

[wrap-git]
url = https://github.com/frida/frida-gum.git
revision = main
depth = 1

[provide]
dependency_names = frida-gum-1.0, frida-gum-heap-1.0, frida-gum-prof-1.0, frida-gumjs-1.0

In case you don’t have Meson and Ninja already installed, run pip install meson ninja.

Then, to build and run:

$ meson setup build
$ meson compile -C build
$ ./build/hello
!!! open("/etc/hosts", 0x0)
!!! open("/etc/fstab", 0x0)

Footprint

We put a lot of effort into making sure that Frida can scale from desktops all the way down to embedded systems. In this release I spent some time profiling our binary footprint, and based on this I ended up making a slew of tweaks and build options to reduce our footprint.

I was curious how small I could make a Gum Hello World program that only uses Interceptor. The end result was measured on 32-bit ARM w/ Thumb instructions, where Gum and its dependencies are statically linked, and the only external dependency is the system’s libc.

The result was as small as 55K (!), and that made me really excited. What I did was to introduce new build options in Gum, GLib, and Capstone. For Gum we now support a “diet” mode where we don’t make use of GObject and only offer a plain C API. This means it won’t support GObject Introspection and fancy language bindings. It also means we don’t offer the full Gum API, but that is something that can be expanded on in the future.

Similarly for GLib there is also a new “diet” mode, and boils down to disabling its slice allocator, debugging features, and a few other minor tweaks like that.

As for Capstone, I ended up introducing a new “profile” option that can be set to “tiny”. The result of doing so is that Capstone only understands enough of the instruction set to determine each instruction’s length, and provide some details on position-dependent instructions. The idea is to only support what our Relocator implementations need, as those do most of the heavy lifting behind Interceptor and Stalker.

While I wouldn’t recommend using these build options unless you really need a footprint that small, it’s good to be aware of what’s possible. We also offer other, less extreme options. Read more in our footprint docs.

The curse of multiple build systems

Something that has been bothering me for as long as Frida has existed, is that building Frida involves dealing with multiple build systems. While we do of course try to hide that complexity behind scripts/makefiles, we are inevitably going to have unhappy users who find themselves trying to figure out why Frida is not building for them.

Some are also interested in cross-compiling Frida for a slightly different libc, toolchain, or what have you. They may even be looking to add support for an OS we don’t yet support. Chances are that we’re going to demotivate them the moment they realize they need to deal with four different build-systems: Meson, autotools, custom Perl scripts (OpenSSL), and GN (V8).

As we are happy users of Meson, my goal is to “Mesonify all the things!”. With this release, we have now finally reached the point where virtually all of our required dependencies are built using Meson. The only exception is V8, but we will hopefully also build that with Meson someday. (Spoiler from the future: Frida 16 will get us there!)

EOF

There’s also a bunch of other exciting changes, so definitely check out the changelog below.

Enjoy!

Changelog

• Add support for FreeBSD.
• Add support for ARMv4, for instrumenting old embedded systems.
• Add build options for binary footprint reductions (see config.mk).
• Tweak Capstone and GLib to enable much smaller binary footprints.
• droidy: Add AXML decoder. Thanks @meme!
• windows: Fix dbghelp backtracer support for libffi-frames.
• linux: Fix compatibility with new glibc versions.
• linux: Only use one frida-helper when assets are installed.
• qnx: Remove tempfiles when injector is closed.
• core: Plug leak when agent teardown is cancelled.
• gumjs: Fix handling of RPC invocations returning null.
• interceptor: Use a “jumbo”-JMP on x86 when needed, when impossible to allocate memory reachable from a “JMP ".
• interceptor: Generate variable size x86 NOP padding.
• stalker: Improve performance of the arm64 backend, by applying ideas recently used to optimize the x86/64 backend – e.g. improved locality, better inline caches, etc.
• stalker: Fix handling of zero-sized freeze/thaw().
• stalker: Rework x86 PLT exclusion code to avoid reentrancy-issues during stalking.
• stalker: Don’t require a C++ runtime to be present.
• arm-writer: Add put_bl_reg(), put_call_reg().
• arm-writer: Fix register clobbering in put_call_address*().
• arm64-reader: Expose disassemble_instruction_at().
• arm64-writer: Fix handling of mixed-width literals.
• arm64-writer: Fix TBZ/TBNZ encoding.
• arm64-writer: Fix put_and_reg_reg_imm() on 32-bit systems.
• arm64-writer: Add put_{ldr,str}_reg_reg_offset_mode().
• elf-module: Expose more details, add support for offline mode, add Vala bindings.
• exceptor: Add reset() for exception handler recovery.
• gum: Add lots of GObject Introspection annotations and API docs.
• gum: Add support for using as a Meson subproject.
• gum: Port Meson build system to Windows.
• gum: Eliminate the GIO dependency.
• gum: Add diet mode, allowing a “Hello World” C program that uses Interceptor to be as small as 55K on 32-bit ARM w/ Thumb instructions.
• gum: Add CI. Thanks @meme!
• Improve build system with many portability improvements.
• Build elfutils, libiconv, libdwarf, libunwind, openssl, xz with Meson.
• Upgrade dependencies: capstone, elfutils, libdwarf, libunwind.
• Release packages for Fedora 35 instead of 34.
• python: Use PEP 503 instead of PyPI xmlrpc. Thanks @GalaxySnail!
• python: Fix support for Python >= 3.10 on Windows.

Introducing the brand new Swift bridge! Now that Swift has been ABI-stable since version 5, this long-awaited bridge allows Frida to play nicely with binaries written in Swift. Whether you consider Swift a static or a dynamic language, one thing is for sure, it just got a lot more dynamic with this Frida release.

Metadata

Probably the first thing a reverser does when they start reversing a binary is getting to know the different data structures that the binary defines. So it made most sense to start by building the Swift equivalent of the ObjC.classes and ObjC.protocols APIs. But since Swift has other first-class types, i.e. structs and enums, and since the Swift runtime doesn’t offer reflection primitives, at least not in the sense that Objective-C does, it meant we had to dig a little deeper.

Luckily for us, the Swift compiler emits metadata for each type defined by the binary. This metadata is bundled in a TargetTypeContextDescriptor C++ struct, defined in include/swift/ABI/Metadata.h at the time of writing. This data structure includes the type name, its fields, its methods (if applicable,) and other useful data depending on the type at hand. These data structures are pointed to by relative pointers (defined in include/swift/Basic/RelativePointer.h.) In Mach-O binaries, these are stored in the __swift5_types section.

So to dump types, Frida basically iterates over these data structures and parses them along the way, very similar to what dsdump does, except that you don’t have to build the Swift compiler in order to tinker with it.

Frida also has the advantage of being able to probe into internal Apple dylibs written in Swift, and that’s because we don’t need to parse the dyld_shared_cache thanks to the private getsectiondata API, which gives us section offsets hassle-free.

Once we have the metadata, we’re able to easily create JavaScript wrappers for object instances and values of different types.

Conventions

To be on par with the Objective-C bridge, the Swift bridge has to support calling Swift functions, which also proved to be not as straight forward.

Swift defines its own calling convention, swiftcall, which, to put it succinctly, tries to be as efficient as possible. That means, not wasting load and store instructions on structs that are smaller than 4 registers-worth of size. That is, to pass those kinds of structs directly in registers. And since that could quickly over-book our precious 8 argument registers (on AARCH64 x0-x7), it doesn’t use the first register for the self argument. It also defines an error register where callees can store errors which they throw.

What we just described above is termed “physical lowering” in the Swift compiler docs, and it’s implemented by the back-end, LLVM.

The process that precedes physical lowering is termed “semantic lowering,” which is the compiler front-end figuring out who “owns” a value and whether it’s direct or indirect. Some structs, even though they might be smaller than 4 registers, have to be passed indirectly, because, for example, they are generic and thus their exact memory layout is not known at compile time, or because they include a weak reference that has to be in-memory at all times.

We had to implement both semantic and physical lowering in order to be able to call Swift functions. Physical lowering is implemented using JIT-compiled adapter functions (thanks to the Arm64Writer API) that does the necessary SystemV-swiftcall translation. Semantic lowering is implemented by utilizing the type’s metadata to figure out whether we should pass a value directly or not.

The compiler docs are a great resource to learn more about the calling convention.

Interception

Because Swift passes structs directly in registers, there isn’t a 1-to-1 mapping between registers and actual arguments.

And now that we have JavaScript wrappers for types, and are able to call Swift functions from the JS runtime, a good next step would be extending Interceptor to support Swift functions.

For functions that are not stripped, we use a simple regex to parse argument types and names, same for return values. After parsing them we retrieve the type metadata, figure out the type’s layout, then simply construct JS wrappers for each argument, which we pass the Swift argument value, however many registers it occupies.

EOF

Note that the bridge is still very early in development, and so:

• Currently supports Darwin arm64(e) only.
• Performance is not yet in tip-top shape, some edge case might not be handled properly and some bugs are to be expected.
• There’s a chance the API might change in breaking ways in the short-to-medium term.
• PRs and issues are very welcome!

Refer to the documentation for an up-to-date resource on the current API.

Enjoy!

Changes in 15.1.0

• Implement the Swift bridge, which allows Frida to:
  • Explore Swift modules along with types implemented in them, i.e. classes, structs, enums and protocols.
  • Create JavaScript wrappers for object instances and values.
  • Invoke functions that use the swiftcall calling convention from the JavaScript runtime.
  • Intercept Swift functions and automatically parse their arguments and return values.
• Fix i/macOS regression where changes related to iOS 15 support ended up breaking support for attaching to Apple system daemons.
• gadget: Add interaction.parameters in connect mode. These parameters are then “reflected” into app’s info under parameters.config. Thanks @mrmacete!

Changes in 15.1.1

• gumjs: Fix Swift lifetime logic in the V8 runtime.

Changes in 15.1.2

• control-service: Fix signal wiring, so signals such as Device.output get emitted correctly by a remote frida-server. Thanks @mrmacete!
• gadget: Fix the “runtime” option, which was forgotten during the refactorings leading up to Frida 15.
• relocator: Optimize handling of x86 RIP relative code, by simply adjusting the offset where possible.
• gumjs: Add ESM support, so tools like frida-compile can output better code.
• gumjs: Throw away source code after parsing it.
• gumjs: Plug leak when compiling to QuickJS bytecode.
• java: Expose JNIEnv->GetDirectBufferAddress. Thanks @pandasauce!

Changes in 15.1.3

• objc: Fix the Proxy respondsToSelector implementation. Thanks @hot3eed!
• gumjs: Fix V8 runtime crash when module is missing.
• gumjs: Emit V8 exceptions thrown by ESM entrypoints.

Changes in 15.1.4

• gumjs: Fix double-free related to weak ref callbacks in the QuickJS runtime. Thanks @mrmacete!
• gumjs: Ignore Interceptor context in unrelated NativeCallback invokes. In this way invalid Interceptor contexts from higher up the call stack will be safely ignored in favor of the minimal but correct callback context. Thanks @mrmacete!
• gumjs: Fix ESM module name normalization logic.
• gumjs: Add Process getters for cwd, home, and tmp dirs.
• swift: Improve metadata caching performance by ~3x. Thanks @hot3eed!
• node: Publish Electron prebuilds for v15 instead of v13.

Changes in 15.1.5

• gumjs: Fix crash when QuickJS stringifies large numbers. Thanks @vfsfitvnm!
• gumjs: Expose GError and GIConv to CModule. Thanks @0xDC00!
• droidy: Support ADB server host/port environment variables. Thanks @amirpeles90!
• swift: Improve load behavior on non-Darwin.

Changes in 15.1.6

• swift: Fix crash during load on non-Darwin. Thanks @hot3eed!

Changes in 15.1.7

• swift: Fix CoreSymbolication integration on older OS versions. Thanks @hot3eed!
• python: Add setup.py download logic for Android/ARM. Our CI doesn’t yet build and upload such a binary, though.

Changes in 15.1.8

• darwin: Add support for working in the SRD environment. Thanks @Nessphoro!
• darwin: Add support for building with newer iOS SDKs.

Changes in 15.1.9

• x86-relocator: Fix patching of RIP relative instructions. This was a regression introduced in 15.1.2, resulting in Stalker becoming unreliable.
• portal-service: Always remove ClusterNode sessions whenever a session ID is unset from PortalService. This avoids both NULL dereferences and leaks. Thanks @mrmacete!
• frida-portal: Fix typo in –help output.

Changes in 15.1.10

• p2p: Gracefully handle unsupported ICE candidates.
• p2p: Disable ICE-TCP for now.
• p2p: Rework PeerSocket to fix synchronization issues.
• socket: Fix WebService teardown.
• vala: Optimize server-side GDBus reply handling. This means our RPC and network protocols become less chatty/more performant.
• x86-writer: Add UD2 instructions after/in indirect branches.
• x86-writer: Emit larger NOPs when possible.
• stalker: Improve performance of the x86/64 backend.
• objc-api-resolver: Guard against disposed ObjC classes. Thanks @mrmacete!
• gumjs: Fix V8 Interceptor.{replace,revert}() regression. Thanks @3vilWind!
• gumjs: Expand Instruction API w/ regsAccessed and operand.access. Thanks @3vilWind!

Changes in 15.1.11

• x86-writer: Add put_sahf() and put_lahf().
• x86-relocator: Fix handling of out-of-range Jcc branch targets. Thanks @0xDC00!
• stalker: Optimize target address retrieval.
• stalker: Avoid expensive XCHG instructions.
• stalker: Optimize IC prolog to use SAHF/LAHF.
• memory: Improve scan() to support regex patterns. Thanks @hot3eed!
• kernel: Get base from all_image_info where supported. Thanks @mrmacete!
• windows: Improve dbghelp backtracer reliability. Thanks @HonicRoku!

Changes in 15.1.12

• agent: Fix hang on unload w/ NO_REPLY_EXPECTED calls, where we would wait for a reply to be sent. Due to the server-side DBus code being generated by the Vala compiler, and it previously (in Frida <= 15.1.9) ignoring NO_REPLY_EXPECTED, this bug went unnoticed.
• android: Move to NDK r24 Beta 1.

Changes in 15.1.13

• linux: Improve module resolution on glibc systems.
• fruity: Fix spawn on dyld v4 case (jailed iOS 15.x). Thanks @mrmacete!
• objc-api-resolver: Protect against objc_disposeClassPair() via mutex. Thanks @mrmacete!
• gumjs: Update Kernel.scan*() to match Memory.scan*(). Thanks @hot3eed!
• stalker: Fix emitted branch op-code on x86.
• stalker: Fix handling of Thumb IT AL.
• stalker: Handle excluded Linux calls through PLT on x86.
• stalker: Fix Linux exception handling on x86.
• java: Add Java.backtrace(), without any API stability guarantees for now.

Changes in 15.1.14

• backtracer: Improve fuzzy backtracers to also include the immediate caller, and avoid walking past stack end when known.
• windows: Implement Thread.try_get_ranges().
• linux: Implement Thread.try_get_ranges().
• ios: Check in with launchd on SRD systems.
• stalker: Fix accidental clobbery in call depth code on x86.
• node: Publish Node.js prebuilds for v17, too.

So much has changed. Let’s kick things off with the big new feature that guided most of the other changes in this release:

Portals

Part I: Conception

Earlier this year @insitusec and I were brainstorming ways we could simplify distributed instrumentation use-cases. Essentially ship a Frida Gadget that’s “hollow”, where application-specific instrumentation is provided by a backend.

One way one could implement this is by using the Socket.connect() JavaScript API, and then define an application-specific signaling protocol over which the code is loaded, before handing it off to the JavaScript runtime.

But this way of doing things does quickly end up with quite a bit of boring glue code, and existing tools such as frida-trace won’t actually be usable in such a setup.

That’s when @insitusec suggested that perhaps Frida’s Gadget could offer an inverse counterpart to its Listen interaction. So instead of it being a server that exposes a frida-server compatible interface, it could be configured to act as a client that connects to a Portal.

Such a Portal then aggregates all of the connected gadgets, and also exposes a frida-server compatible interface where all of them appear as processes. To the outside it appears as if they’re processes on the same machine as where the Portal is running: they all have unique process IDs if you use enumerate_processes() or frida-ps, and one can attach() to them seamlessly.

In this way, existing Frida tools work exactly the same way – and by enabling spawn-gating on the Portal, any Gadget connecting could be instructed to wait for somebody to resume() it after applying the desired instrumentation. This is the same way spawn-gating works in other situations.

Part II: Implementation

Implementing this was a lot of fun, and it wasn’t long until the first PoC was up and running. It took some time before all the details were clear, though, but this eventually crystallized into the following:

The Portal should expose two different interfaces:

1. The cluster interface that Gadgets can connect to, allowing them to join the cluster.
2. Optionally also a control interface that controllers can talk to. E.g. frida-trace -H my.portal.com -n Twitter -i open

To a user this would be pretty simple: just grab the frida-portal binary from our releases, and run it on some machine that the Gadget is able to reach. Then point tools at that – as if it was a regular frida-server.

That is however only one part of the story – how it would be used for simple use-cases. The frida-portal CLI program is actually nothing more than a thin CLI wrapper around the underlying PortalService. This CLI program is just a bit north of 200 lines of code, of which very little is actual logic.

One can also use our frida-core language bindings, for e.g. Python or Node.js, to instantiate the PortalService. This allows configuring it to not provide any control interface, and instead access its device property. This is a standard Frida Device object, on which one can enumerate_processes(), attach(), etc. Or one can do both at the same time.

Using the API also offers other features, but we will get back to those.

Part III: TLS

Given how useful it might be to run a frida-portal on the public Internet, it was also clear that we should support TLS. As we already had glib-networking among our dependencies for other features, this made it really cheap to add, footprint-wise.

And implementation-wise it’s a tiny bit of logic on the client side, and similarly straight-forward for the server side of the story.

For the CLI tools it’s only a matter of passing --certificate=/path/to/pem. If it’s a server it expects a PEM-encoded file with a public + private key, where it will accept any certificate from incoming clients. For a client it’s also expecting a PEM-encoded file, but only with the public key of a trusted CA, which the server’s certificate must match or be derived from.

At the API level it boils down to this:

import frida

manager = frida.get_device_manager()
device = manager.add_remote_device("my.portal.com",
                                   certificate="/path/to/pem/or/inline/pem-data")
session = device.attach("Twitter")
…

Part IV: Authentication

The next fairly obvious feature that goes hand in hand with running a frida-portal on the public Internet, is authentication. In this case our server CLI programs now support --token=secret, and so do our CLI tools.

At the API level it’s also pretty simple:

import frida

manager = frida.get_device_manager()
device = manager.add_remote_device("my.portal.com",
                                   token="secret")
session = device.attach("Twitter")
…

But this gets a lot more interesting if you instantiate the PortalService through the API, as it makes it easy to plug in your own custom authentication backend:

import frida

def authenticate(token):
    # Where `token` might be an OAuth access token
    # that is used to grab user details from e.g.
    # GitHub, Twitter, etc.
    user = …

    # Attach some application-specific state to the connection.
    return {
        'name': user.name,
    }

cluster_params = frida.EndpointParameters(authentication=('token', "wow-such-secret"))
control_params = frida.EndpointParameters(authentication=('callback', authenticate))
service = frida.PortalService(cluster_params, control_params)

The EndpointParameters constructor also supports other options such as address, port, certificate, etc.

Part V: Offline Mode

That leads us to our next challenge, which is how to deal with transient connectivity issues. I did make sure to implement automatic reconnect logic in PortalClient, which is what Gadget uses to connect to the PortalService.

But even if the Gadget reconnects to the Portal, what should happen to loaded scripts in the meantime? And what if the controller gets disconnected from the Portal?

We now have a solution that handles both situations. But it’s opt-in, so the old behavior is still the default.

Here’s how it’s done:

session = device.attach("Twitter",
                        persist_timeout=30)

Now, once some connectivity glitch occurs, scripts will stay loaded on the remote end, but any messages emitted will get queued. In the example above, the client has 30 seconds to reconnect before scripts get unloaded and data is lost.

The controller would then subscribe to the Session.detached signal to be able to handle this situation:

def on_detached(reason, crash):
    if reason == 'connection-terminated':
        # Oops. Better call session.resume()

session.on('detached', on_detached)

Once session.resume() succeeds, any buffered messages will be delivered and life is good again.

The above example does gloss over a few details such as our current Python bindings’ finicky threading constraints, but have a look at the full example here. (This will become a lot simpler once we port our Python bindings off our synchronous APIs and onto async/await.)

Part VI: Latency and Bottlenecks

Alright, so next up we’ve got a Portal running in a data center in the US, but the Gadget is at my friend’s place in Spain, and I’m trying to control it from Norway using frida-trace. It would be a shame if the script messages coming from Spain would have to cross the Atlantic twice, not just because of the latency, but also the AWS bill I’ll have to pay next month. Because I’m dumping memory right now, and that’s quite a bit of traffic right there.

This one’s a bit harder, but thanks to libnice, a lightweight and mature ICE implementation built on GLib, we can go ahead and use that. Given that GLib is already part of our stack – as it’s our standard library for C programming (and our Vala code compiles to C code that depends on GLib) – it’s a perfect fit. And this is very good news footprint-wise.

As a user it’s only a matter of passing --p2p along with a STUN server:

$ frida-trace \
    -H my.portal.com \
    --p2p \
    --stun-server=my.stunserver.com \
    -n Twitter \
    -i open

(TURN relays are also supported.)

The API side of the story looks like this:

session.setup_peer_connection(stun_server="my.stunserver.com")

That’s all there is to it!

Part VII: Are Only Gadgets Invited To The Party?

You may have noticed that our Gadget has been a recurring theme so far. I’m not very excited about adding features that only apply to one mode, such as only Injected mode but not Embedded mode. So this was something that came to mind quite early on, that Portals had to be a universally available feature.

So say my buddy is reversing a target on his iPhone from his living room in Italy, and I’d like to join in on the fun, he can go ahead and run:

$ frida-join -U ReversingTarget my.portal.com cert.pem secret

Now I can jump in with the Frida REPL:

$ frida \
    -H my.portal.com \
    --certificate=cert.pem \
    --token=secret \
    --p2p \
    --stun-server=my.stunserver.com \
    -n ReversingTarget

And if my buddy would like to use the API to join the Portal, he can:

session = frida.get_usb_device().attach("ReversingTarget")
membership = session.join_portal("my.portal.com",
                                 certificate="/path/to/cert.pem",
                                 token="secret")

Part VIII: The Web

Something I’ve been wanting to build since before Frida was born, is an online collaborative reversing app. Back in the very beginning of Frida, I built a desktop GUI that had integrated chat, console, etc. My not-so-ample spare-time was a challenge, however, so I eventually got rid of the GUI code and decided to focus on the API instead.

Now we’re in 2021, and single-page apps (SPAs) can be a really appealing option in many cases. I’ve also noticed that there’s been quite a few SPAs built on top of Frida, and that’s super-exciting! But what I’ve noticed when toying with SPAs on my own, is that it’s quite tedious to have to write the middleware.

Well, with Frida 15 I had to make some protocol changes to accomodate the features that I’ve covered so far, so it also seemed like the right time to really break the protocol and go ahead with a major-bump. This is something I’ve been trying to avoid for a long time, as I know how painful they are to everyone, myself included.

So now browsers can finally join in on the fun, without any middleware needed:

async function start() {
  const ws = wrapEventStream(new WebSocket(`ws://${location.host}/ws`));
  const bus = dbus.peerBus(ws, {
    authMethods: [],
  });

  const hostSessionObj = await bus.getProxyObject('re.frida.HostSession15',
      '/re/frida/HostSession');
  const hostSession = hostSessionObj.getInterface('re.frida.HostSession15');

  const processes: HostProcessInfo[] = await hostSession.enumerateProcesses({});
  console.log('Got processes:', processes);

  const target = processes.find(([, name]) => name === 'hello2');
  if (target === undefined) {
    throw new Error('Target process not found');
  }
  const [pid] = target;
  console.log('Got PID:', pid);

  const sessionId = await hostSession.attach(pid, {
    'persist-timeout': new Variant('u', 30)
  });
  …
}

(Full example can be found in examples/web_client.)

This means that Frida’s network protocol is now WebSocket-based, so browsers can finally talk directly to a running Portal/frida-server, without any middleware or gateways in between.

I didn’t want this to be a half-baked story though, so I made sure that the peer-to-peer implementation is built on WebRTC data channels – this way even browsers can communicate with minimal latency and help keep the AWS bill low.

Part IX: Assets

Once we’ve built a web app to go with our Portal, which is speaking WebSocket natively, and thus also HTTP, we can also make it super-easy to serve that SPA from the same server:

$ ./frida-portal --asset-root=/path/to/web/app

This is also easy at the API level:

control_params = frida.EndpointParameters(asset_root="/path/to/web/app")
service = frida.PortalService(cluster_params, control_params)

Part X: Collaboration

A natural next step once we have a controller, say a web app, is that we might want collaboration features where multiple running instances of that SPA are able to communicate with each other.

Given that we already have a TCP connection between the controller and the PortalService, it’s practically free to also let the developer use that channel. For many use-cases, needing an additional signaling channel brings a lot of complexity that could be avoided.

This is where the new Bus API comes into play:

import frida

def on_message(message, data):
    # TODO: Handle incoming message.
    pass

manager = frida.get_device_manager()
device = manager.add_remote_device("my.portal.com")
bus = device.bus

bus.on('message', on_message)
bus.attach()

bus.post({
    'type': 'rename',
    'address': "0x1234",
    'name': "EncryptPacket"
})
bus.post({
    'type': 'chat',
    'text': "Hey, check out EncryptPacket everybody"
})

Here we’re first attaching a message handler so we can receive messages from the Portal.

Then we’re calling attach() so that the Portal knows we’re interested in communicating with it. (We wouldn’t want it sending messages to controllers that don’t make use of the Bus, such as frida-trace.)

Finally, we post() two different message types. It is up to the PortalService to decide what to do with them.

So this means that the remote PortalService needs to be instantiated through the API, as incoming messages need to be handled – the Portal won’t forward them to other controllers on its own.

Worry not, though, this is easy:

import frida
import sys

def on_message(connection_id, message, data):
    # TODO: Handle incoming message.
    pass

cluster_params = frida.EndpointParameters()
control_params = frida.EndpointParameters()
service = frida.PortalService(cluster_params, control_params)
service.on('message', on_message)
service.start()

sys.stdin.read()

In on_message() it should look at the message and decide what to do.

It might choose to reply to the controller that sent it the message:

service.post(connection_id, {
    'type': 'rename-rejected',
    'reason': "Not authorized"
})

Another useful thing to do is sending a welcome message whenever somebody calls attach() on their Bus object:

def on_subscribe(connection_id):
    service.post(connection_id, {
        'type': 'welcome',
        'users': [user.nick for user in connected_users]
    })

service.on('subscribe', on_subscribe)

Depending on your application, you might also need a way to broadcast a message to all controllers who are attached to their Bus:

service.broadcast({
    'type': 'announce',
    'text': "Important Service Announcement"
})

You can also narrowcast() a message to a subset of controllers:

service.narrowcast("#reversing", {
    'type': 'chat',
    'sender': user.nick,
    'text': "Hello everyone"
})

This means any controller connection tagged with #reversing will receive that message. Tagging is done like this:

service.tag(connection_id, "#reversing")

Such tags could then be added based on actions, like a controller sending a “join” message to join a channel. They could also be applied based on authentication, so that only connections belonging to a certain GitHub organization receive that message – just as an example.

Lastly, on the cluster side, it is also possible to specify an Access Control List (ACL) when joining the Portal. The ACL is an array of strings that specify tags which will grant controllers access to discover and interact with the given process. This means that service.tag() needs to be used for each controller that should be granted access to a certain node/group of nodes.

That is pretty much all there is to it. For a more comprehensive example, check out examples/portal_server.py and examples/portal_client.py, which implement an IRC-esque chat service.

System Parameters

Back in May I had a chat with @Hexploitable, who was working on a tool where he needed to pick a Device object based on whether it’s running iOS vs Android. This is a feature that’s been requested in the past, and it felt like it might be time to finally address it.

While one could do device.attach(0) and load a script in the system session, in order to run code inside Frida itself (e.g. in a remote frida-server), it is somewhat tedious. It also doesn’t work if the Device represents a jailed/non-rooted device, where code execution is a lot more constrained.

So after brainstorming this a bit, @Hexploitable started working on implementing it, and quickly got to the point where he had the first draft working. This was later refined by me, and got merged shortly after the Portals feature had finally landed.

The API is simple, and easy to extend in the future:

$ python3 -c 'import frida; import json; \
    print(json.dumps(frida.query_system_parameters()))' \
    | jq

And if I attach a jailed iOS device, I can also query it:

$ python3 -c 'import frida; import json; \
    device = frida.get_usb_device(); \
    print(json.dumps(device.query_system_parameters()))' \
    | jq

An important detail to note here is access: 'jailed'. This is how you can determine whether you’re accessing the device through our support for jailed iOS/Android systems, i.e. limited to debuggable apps, or actually talking to a remote frida-server – which is what access: 'full' means.

Things are not quite as juicy for Android yet (PRs welcome, btw!), but there are still plenty of useful details:

We’re also able to identify the specific Linux distro if it’s LSB-compliant:

And last but not least, Windows:

Application and Process Parameters

Another cool idea that started taking shape after some impromptu chats, was when @pancake told me it would be useful to know the particular version of an installed iOS app.

As I had just broken the protocol in so many ways working on the Portals feature, it also seemed like a great time to break it some more, and avoid another painful major bump down the road.

Fast forward a bit, and here’s how it turned out: Our Application and Process objects no longer have any small_icon or large_icon properties, but they now have a parameters dict.

By default, with enumerate_applications(), things look familiar:

But by changing that to enumerate_applications(scope='metadata'), things get a lot more interesting:

Here we can see the iOS Twitter app’s version and build number, where its app bundle is on the filesystem, the containers that it owns, that it is currently the frontmost app, how long ago it was started, etc.

We can also crank that up to enumerate_applications(scope='full') and get icons as well:

The debuggable: true parameter is very useful if query_system_parameters() reported access: 'jailed', as that means your application may want to filter the list of apps to only show the ones it is able to spawn() and/or attach() to, or perhaps show debuggable apps more prominently to provide a better UX.

It’s probably also worth mentioning that get_frontmost_application() now supports passing a scope as well.

Those of you familiar with the old API may have noticed that icons may now be delivered in compressed form, as PNGs. Previously this was always uncompressed RGBA data, and the iOS side would do the PNG decoding and downscaling to two fixed resolutions (16x16 and 32x32).

All of this meant that we would waste a lot of CPU time, memory and bandwidth to include icons, even if all of that data would end up in a CLI tool that doesn’t make use of it. So now with Frida 15 you might notice that application and process listing is a lot faster. And even if you do request icons, it should also be faster than before as we don’t do any decompression and downscaling.

That was application listing. All of the above is also true for process listing, and this is what enumerate_applications(scope='full') might look like now:

Here it is also clear that the Twitter app is currently frontmost, that its parent PID is launchd (PID 1), the user it is running as, when it was started, etc.

You might be wondering why applications is an array though, and the answer is probably best illustrated by an example from Android:

The “com.android.phone” process actually hosts six different “applications”!

And once again, last but not least, I didn’t forget about Windows:

So that’s the “scope” option. There’s also another one, meant for UIs. The idea is that a UI might want to grab the list of applications/processes quickly, and may not actually need metadata/icons until the user interacts with a particular entry, or scrolls a subset of entries into view. So we now provide an option to support such use-cases.

Say we only want to grab the metadata for two specific apps, we can now do:

ids = [
    "com.atebits.Tweetie2",
    "no.sparebank1.mobilbank"
]
apps = device.enumerate_applications(identifiers=ids,
                                     scope='full')

We also support the same feature for process listing, where it looks like this:

processes = device.enumerate_processes(pids=[1337, 1338],
                                       scope='full')

Portals and Application/Process Parameters

Now that we have covered application parameters and portals, there’s an important detail that’s worth mentioning: Given that it doesn’t make much sense to implement query_system_parameters() in the case of a PortalService, as it’s surfacing processes from any number of (potentially remote) systems, we can use application/process parameters to fill this void.

This means that any Application and Process coming from a PortalService will, if scope is set to metadata or full, provide one parameter named system, which contains the system parameters for that particular application/process. This way an application can still know ahead of time if it’s interested in a particular process.

Jailed iOS and Android Improvements

I had a lot of fun implementing the Application and Process parameters feature, and tried to see how narrow I could make the gap between jailed (non-rooted) and jailbroken (rooted). For example on Android, we didn’t even fetch app labels in the non-rooted code-path. This was because we were relying on running shell commands over ADB, and I couldn’t find a way to grab labels in that case.

The shell command route is very fragile, as most tools output details in a format that’s meant to be consumed by a human, not a machine. And obviously such output is likely to change as Android evolves.

Because of this we now have a tiny prebuilt .dex that we copy over and run, and grabbing metadata is only a matter of making RPC calls to that helper process. This means we are able to provide all the same details for non-rooted as we provide in the rooted case, where we have a frida-server running on the Android side.

Another thing worth mentioning is that we no longer consider Android’s launcher a frontmost app, which means this is now consistent with our behavior on iOS, where SpringBoard is never considered the frontmost app.

As part of these major changes I also added code to fetch icons on Android as well, both non-rooted and rooted, so that this feature is no longer just limited to iOS, macOS, and Windows.

We didn’t provide icons for jailed iOS though, but that feature gap is now also closed. There is however still one difference between jailed and jailbroken iOS: the ppid and user parameters are not available in the jailed case, as this is not exposed by any lockdown/DTX API that I’m currently aware of. But other than that, things are in pretty good shape.

Massively improved backtraces on i/macOS

Thanks to a very exciting pull-request by @hot3eed, we now have an i/macOS symbolication fallback that uses the Objective-C runtime. In this way, instead of showing module!0x1234, we may be able to resolve that to an Objective-C method. Yay!

We also got another awesome contribution by @mrmacete, where NativeCallback now always exposes a context, so you can do Thread.backtrace(this.context) and expect it to work in all cases.

This was previously only possible when NativeCallback was used as an Interceptor replacement. So if you were using ObjC.implement() to swizzle an Objective-C API, you couldn’t actually capture a backtrace from that NativeCallback. So this is a super-exciting improvement!

Unextracted Native Libraries on Android

For those of you using Frida on Android, you may have encountered apps where native libraries don’t reside on the filesystem, but are loaded directly from the app’s .apk. Thanks to a great contribution by @P-Sc, we now support this transparently – no changes needed in your existing instrumentation code.

Upgraded OS Support

We now also support the latest betas of macOS Monterey, iOS 15, and Android 12. Special thanks to @alexhude at Corellium for helping debug and test things on iOS 15, and @pengzhangdev who contributed a fix for frida-java-bridge to support Android 12.

Networked iOS Devices

Another feature that’s been requested a few times is support for networked iOS devices. This is great if you don’t want to destroy your iPhone/iPad’s battery by leaving it plugged in all day. What’s great about this feature is that it “just works” – you should see them if you run frida-ls-devices.

Only two pitfalls worth mentioning: You may now have two different Device objects with the same ID, in case a networked iOS device is reachable through the network while also being plugged in.

E.g.:

$ frida-ls-devices
Id                         Type    Name
-------------------------  ------  -------------------------------------
local                      local   Local System
00008027-xxxxxxxxxxxxxxxx  usb     iPad
socket                     remote  Local Socket
00008027-xxxxxxxxxxxxxxxx  remote  iOS Device [fe80::146f:75af:d79:630c]

So if you’re using -U or frida.get_usb_device() things will work just like before, where you’ll be using your device through USB. But if you want to use the networked device, then resolving it by ID means the USB entry will take precedence, as it’s typically ahead of the networked device in the list of devices.

This means you would also need to check its type. Our CLI tools don’t yet provide a switch to do this, but this would be a welcome pull-request if anyone’s interested!

The second pitfall is that frida-server only listens on the loopback interface by default, meaning we won’t be able to connect to it over the network. So if you’re using our iOS .deb either manually or through Cydia, you will have to edit /Library/LaunchDaemons/re.frida.server.plist to add the --listen switch, and then use launchctl to restart it.

This may also be a situation where you want to make use of the new TLS and authentication features mentioned earlier, depending on how much you trust your network environment.

EOF

There’s also a bunch of other exciting changes, so definitely check out the changelog below.

Enjoy!

Changes in 15.0.0

• Introduce PortalService API and daemon, a network service that orchestrates a cluster of remote processes instrumented by Frida. Implements both a frida-server compatible control interface, as well as a cluster interface that agents and gadgets in target processes can talk to. Connected controllers can enumerate processes as if they were local to the system where the portal is running, and are able to attach() and also enable spawn-gating to apply early instrumentation.
• Add Session.join_portal(), making it easy to share control of a process with a remote PortalService, joining its cluster together with other nodes.
• Add “connect” interaction to frida-gadget, so it can join a PortalService cluster as well.
• Add PortalClient, used to implement Session.join_portal() and frida-gadget’s “connect” interaction. Connects to the PortalService and joins its cluster. Implements automatic reconnect in case of transient failures. Also supports specifying an ACL, which is a list of tags that the PortalService must require connected controllers to possess at least one of. It’s up to the application to implement tagging of controllers based on e.g. authentication.
• Add Device.bus API to allow clients connected to a PortalService to exchange application-specific messages with it. Requires instantiating the service using the API in order to wire up message handlers and protocol logic.
• Add Session persistence support, enabled by specifying a non-zero “persist_timeout” option when attach()ing to a process. When the server subsequently detects that the client owning the session got disconnected, it will allow scripts to stay loaded until the timeout (in seconds) is reached. Any script and debugger messages emitted in the meantime are queued, and may later be delivered if the client returns before the timeout is reached.
• Add TLS support, enabled by specifying a certificate. On the server end this is a PEM with a public and private key, where the server will accept any certificate from the client’s side. However for the client this is a PEM with the public key of a trusted CA, which the server’s certificate must match or be derived from.
• Add authentication support, enabled by specifying a token. The daemons allow specifying a static token through a CLI option, and the APIs allow plugging in a custom authentication backend – which means the token can be interpreted as desired.
• Move network protocols to WebSocket.
• Add protocol-level keepalives.
• Implement WebRTC Data Channel compatible peer-to-peer support, enabled by calling setup_peer_connection() on Session. This allows a direct connection to be established between the client and the remote process, which is useful when talking to it through e.g. a Portal.
• Optimize protocol by skipping the DBus authentication handshake and telling GDBus not to fetch properties, saving an additional roundtrip.
• Drop deprecated protocol bits, such as Session.enable_jit().
• Add Device.query_system_parameters(). Thanks @Hexploitable!
• Improve the application and process query APIs. (Covered extensively above.)
• Switch Crash parameter names to kebab-case.
• Add Session.is_detached(), useful in multi-threaded scenarios where the “detached” signal may already have been emitted by the time we manage to connect to it.
• Fix Stalker handling of SYSCALL instructions on Linux/x86.
• Fix the iPad device name on macOS.
• Massively improve backtraces/symbolication on i/macOS in cases where symbols are missing, but the address to be symbolicated belongs to an Objective-C method. Thanks @hot3eed!
• Improve backtracer accuracy and flexibility, now exposing a minimal context to NativeCallback in cases where it’s not used as an Interceptor replacement. One such example is ObjC.implement(), used for swizzling APIs. Thanks @mrmacete!
• Improve Interceptor reliability on macOS/arm64, by switching to the mapping strategy that we use on iOS.
• Add support for network-connected iOS devices.
• Avoid leaving behind a file when sandbox check fails on iOS.
• Fix Stalker on newer iOS hardware jailbroken with checkra1n. This was solved by disabling RWX support on iOS for now: Even if the jailbreak appears to make it available, whether it actually works boils down to which mitigations the hardware supports. Shout-out to @stacksmashing for reporting and helping get to the bottom of this one!
• Remove bashisms from iOS maintainer scripts, for improved jailbreak compatibility. Thanks @nyuszika7h!
• Improve Interceptor frame layout on arm64, so backtracing code is able to walk the stack past our generated code. This also makes it easier to use a debugger together with Interceptor.
• Fix ObjC ApiResolver deadlock, which occurred when free() was resolved lazily from a dyld image callback, at which point it is a bad idea to call dlsym().
• Add support for unextracted native libraries on Android. Thanks @P-Sc!
• Fix Android get_frontmost_application() name truncation.
• Don’t consider the Android launcher a frontmost app.
• Use the Android app’s label as the process name if the process represents is its main UI process. This is finally consistent with what we do on iOS.
• Improve jailed Android injector: Now using a long-lived shell session to speed things up. Also ensure filenames dropped into /data/local/tmp are unique, and clean up temporary files.
• Drop Firefox OS support.
• Rename the weak ref API to avoid clashing with ES2021. So instead of WeakRef.bind() and WeakRef.unbind(), these are now Script.bindWeak() and Script.unbindWeak().
• Massively improve memory allocation performance on Windows, by lowering the dlmalloc spin-lock sleep duration to zero – which means it will only yield the remainder of its time slice. The default of 50 ms is prone to introduce significant delay as soon as threads start competing for the lock.
• Lazily create the ScriptScheduler thread pool. This means anyone using GumJS can avoid background threads until they’re really needed. Very useful if you’re writing a tool or agent that needs to handle fork(), without having to implement logic to stop and later restart threads. (Something frida-agent does, but which isn’t necessarily needed for simple use-cases.)
• Java: Add support for Android 12 beta. Thanks @pengzhangdev!
• Java: Fix Java.array() for unloaded array types: If the type of the array was not used in the application it means that it wasn’t loaded into memory, and Java.array() previously failed because of this. Thanks @yotamN!
• Java: Add toString() to primitive arrays, so that instead of the generic “[Object Object]” string it will generate a string where the array values are separated by commas. Thanks @yotamN!
• CModule: Add missing TinyCC builtins for 32-bit x86.
• python: Add Script.is_destroyed property.
• python: Add Session.is_detached property.
• python: Add Device.is_lost property.
• python: Throw when attempting an RPC call on a destroyed script.
• node: Fix compatibility with newer versions of Node.js, where any given Buffer’s backing store needs to be unique. We solve this by simply making a copy in cases where we cannot guarantee that the same buffer can only be observed once.
• node: Fix use-after-free in signal transform callbacks.
• node: Fix use-after-free in signal connection callbacks.
• node: Move to C++17, for compatibility with newer Node.js headers.
• node: Add Script.isDestroyed property.
• node: Add Device.isLost property.

Changes in 15.0.1

• Ensure DarwinGrafter’s merging of binds doesn’t make gaps in __LINKEDIT. Not doing so triggers a bug in codesign for which the resulting signed binary turns out corrupted. Thanks @mrmacete!
• node: Fix compilation error when building with MSVC.

Changes in 15.0.2

• Fix handling of large messages, for both client-server and p2p. Also bump the WebSocket payload size limit to 256 KiB - same as is typically negotiated for data channels in p2p mode.
• Move WebSocket I/O to the DBus thread, to avoid unnecessary thread hopping.
• Plug leaks when using p2p.

Changes in 15.0.3

• Implement a new frida-pipe strategy for i/macOS. Turns out that our previous strategy of directly setting up a Mach port in the target process becomes problematic with guarded Mach ports. So instead we register a Mach service that’s globally visible, and have the target process contact it to fetch its end of the socketpair. We also check with the sandbox up front, and issue an extension token if needed. However, if we’re unable to register the Mach service with launchd, we fall back to our previous strategy.
• Skip iOS platformized detection on iOS >= 15. It interacts badly with guarded Mach ports.
• Port early instrumentation to macOS 12 and iOS 15.
• Gracefully handle agent failing to start. Instead of crashing the target process, simply log the error and unload.
• Linux: Use an abstract name for frida-pipe when supported.
• Unlink UNIX socket when frida-pipe is done with it.
• Fix iOS policyd Mach message lifetime logic.

Changes in 15.0.4

• Fix the i/macOS injector’s data size logic. It’s been hard-coded since the beginning, and the recent entrypoint data size adjustment broke it on systems with 4K pages.
• Fix i/macOS early instrumentation regression on dyld < 4.

Changes in 15.0.5

• Fix the __CFInitialize() code-path on dyld >= 4.
• Fix i/macOS sandbox extension logic during spawn().
• Port jailed iOS injector to iOS 15.
• Implement Android USAP interop.
• Improve DarwinGrafter lazy binds merge logic. Thanks @mrmacete!

Changes in 15.0.6

• Fix Windows build regression.

Changes in 15.0.7

• Fix early instrumentation on Android 12.
• node: Fix the ApplicationParameters typings. Thanks for reporting, @pancake!

Changes in 15.0.8

• iOS: Add support for unc0ver v6.1.2.
• iOS: Update Substrate interop logic to support 0.9.7113.

Changes in 15.0.9

• iOS: Revive support for older OS versions. (Verified on iOS 10.3.)
• iOS: Fix support for older Apple usbmuxd versions.
• Android: Handle devices where jailed is unsupported.
• Fix DarwinGrafter alignment issue, aligning to 16 bytes also when lazy binds follow regular binds. Thanks @mrmacete!

Changes in 15.0.10

• Fix regression where Device.open_channel(“lockdown:”) ended up closing the stream right away.
• Fix crash when talking to older versions of ADB.

Changes in 15.0.11

• Rewrite macOS spawn gating to use DTrace. This means we’ve now dropped support for our kernel extension, and we don’t need to worry about future OSes no longer supporting extensions. It also means we finally support spawn gating on Apple Silicon as well.
• Work around i/macOS arm64 single-step delay during early instrumentation.

Changes in 15.0.12

• Fix macOS spawn gating task port lifetime issue. Should not try to be clever and keep task ports around – bad things happen if a task port is used after an exec transition.
• Remove the i/macOS task port caching logic. It is dangerous in exec transitions, adds some complexity, and doesn’t help all that much performance-wise, anyway.
• Make the macOS spawn gating DTrace predicate environment variable optional.
• Improve the macOS spawn gating error message.

Changes in 15.0.13

• Improve clients to specify Host header and use TLS SNI.
• Revert i/macOS single-step delay workarounds.
• iOS: Fix usbmux port number encoding in the connect request.
• Python, Node.js: Fix ownership in Device.spawn() aux options logic.

Changes in 15.0.14

• Port iOS crash reporter integration to iOS 14.7.1.
• Configure internal agents to be less intrusive on i/macOS.
• Improve i/macOS error-handling during process preparation.
• Revive i/macOS single-step delay workarounds, which turned out to be needed after all.
• Handle reentrancy when about to yield JS lock, which may happen if a replaced function gets called by Interceptor during end_transaction().
• Fix conditional Interceptor unignore logic in GumJS. This was preventing Interceptor from ignoring internal calls, and resulted in noise and reduced performance.
• Enhance the i/macOS DebugSymbol fallback name to also include the unslid address. This makes it easy to plop it into a static analysis tool.
• Fix Stalker code slab refill logic.
• Add Stalker stats interface.

Changes in 15.0.15

• Rework i/macOS Exceptor to support latest iOS 14. This would previously result in a deadlock whenever a native exception occurred.

Changes in 15.0.16

• Fix i/macOS single-step handling on ARM during early instrumentation, which would result in attach() failing randomly for a freshly spawn()ed process. Thanks @mrmacete!
• Add Stalker backpatch prefetching support.
• Make Stalker inline cache size configurable on x86.
• Optimize Stalker x86 return handling.
• ObjC: Allow proxies to implement methods. Thanks @hot3eed!

Changes in 15.0.17

• gadget: Support packaging as framework on i/macOS. Load config from “Resources/config.json”, and resolve relative paths relative to the same directory. As an added bonus, we now also support specifying relative paths for “certificate” and “asset_root”.
• web-service: Implement basic directory listing with NGINX-style output. This is useful with e.g. “frida-server –asset-root=/”.
• stalker: Fix backpatch args for 32-bit x86.

Changes in 15.0.18

• Plug long-standing memory leaks, both in our internal heap’s realloc behavior being misconfigured and causing leaks, and in how we register JavaScript classes with QuickJS. Kudos to @mrmacete for discovering and helping track down these long-standing bugs!

Changes in 15.0.19

• gadget: Fix framework resource lookup logic on iOS.

So much to talk about. Let’s kick things off with a big new feature:

Realms

Frida has supported Android for quite a while, but one particular feature has kept getting requested (mostly) by users who thought they were looking at a bug. The conversation usually started something like: “I’m using Frida inside the hardware-accelerated Android emulator X, and when I attach to this process Y, Process.enumerateModules() is missing JNI library Z. But I can see it in Process.enumerateRanges() and /proc/$pid/maps. How come?”

As you may have guessed, we’re talking about Android’s NativeBridge, typically used on Intel-powered Android devices to enable them to run apps that only support ARM – i.e. apps with one or more JNI components only built for ARM.

In a Frida context, however, we’re usually talking about a VirtualBox-based emulator that runs an Android system built for x86. This system then ships with NativeBridge support powered by libhoudini, a proprietary ARM translator.

There’s quite a few of these emulators, e.g. BlueStacks, LDPlayer, NoxPlayer, etc. While the ones mentioned are optimized for running games, there’s now also Google’s official Android 11 AVDs which ship with NativeBridge support out of the gate.

Through the years I’ve been thinking about how we could support such scenarios in Frida, but thinking about it always made my head hurt a little. It did feel like something we should support at some point, though, I just had a hard time figuring out what the API would look like.

Then along came 2020 and Apple announced their transition to ARM, and suddenly Rosetta became relevant once again. “Alright”, I thought, “now we have two platforms where it would be useful to support processes containing an emulated realm that’s running legacy code.”

And yeah there’s also Windows, but we don’t yet support Windows on ARM. We totally should though, so if somebody’s interested in taking a stab at this then please do get in touch.

Anyway, I’m exited to announce that our Android binaries for x86 and x86_64 now support such processes out of the box. You may already be familiar with the following frida-core API, where the Python flavor looks like this:

session = device.attach(target)

(Or frida.attach() if your code only deals with the local system.)

If target has an emulated realm, you can now do:

session = device.attach(target, realm='emulated')

The default is realm='native', and you can actually use both realms at the same time. And when using our CLI tools, pass --realm=emulated to act on the emulated realm.

One important caveat when using this on Android is that you will need to apply your Java-level instrumentation in the native realm.

Lastly it’s worth noting that this new feature is only supported on Android for now, but it shouldn’t be hard to support Rosetta on macOS down the road. Definitely get in touch if you want to help out with this.

Taking Android Java Hooking Inline

The way Frida’s Java bridge replaces Java methods on Android has up until now been accomplished by mutating the in-memory method metadata so that the target method becomes native – if it wasn’t already. This allows us to install a NativeCallback that matches the given method’s JNI signature.

This has presented some challenges, as the ART runtime does have other internal state that depends on the given method’s personality. We have devised a few hacks to dance around some of these issues, but some particularly gnarly edge-cases remained unsolved. One such example is JIT profiling data maintained by the ART VM.

An idea I had been thinking about for a while was to stop mutating the method metadata, and instead perform inline hooking of the AOT-generated machine code – for non-native methods that is. That still leaves methods run on the VM’s interpreter, but the assumption was that we could deal with those by hooking VM internals.

I took a stab at an early prototype to explore this approach further. It seemed like it could work, but there were still many challenges to work through. After some brainstorming with @muhzii, he kept working on evolving this rough PoC further in his spare time. Then one day I almost fell off my chair out of pure excitement when I saw the amazing pull-request he had just opened.

Thanks to Muhammed’s amazing work, you can now all enjoy a much improved Java instrumentation experience on Android. This means improved stability and also that direct calls won’t bypass your replacement method. Yay!

Deoptimization

For those of you using Java.deoptimizeEverything() on Android to ensure that your hooks aren’t skipped due to optimizations, there’s now a more granular alternative. Thanks to @alkalinesec’s neat contribution to our Java bridge, you can now use Java.deoptimizeBootImage(). It ensures only code in the boot image OAT files gets deoptimized. This is a serious performance gain in some situations where the app code itself is slow when deoptimized, and it is not necessary to deoptimize it in order for hooks to be hit reliably.

CModule

Another really exciting update here. The next hero in our story is @mephi42, who started porting Frida to S390x. Our CModule implementation relies on TinyCC behind the scenes, and it doesn’t yet support this architecture. The system might have a C compiler though, so @mephi42 proposed that we add support for using GCC on systems where TinyCC cannot help us out.

I really liked this idea. Not only from the perspective of architecture support, but also because of the potential for much faster code – TinyCC optimizes for small compiler footprint and fast compilation, not fast code.

So needless to say I got more and more excited with each pull-request towards GCC support. Once the last one landed it inspired me to add support for using Apple’s clang on i/macOS.

In the end we arrived at this:

const cm = new CModule(`…`, {}, { toolchain: 'external' });

Where toolchain is either any, internal, or external. The default is any, which means we will use TinyCC if it supports your Process.arch, and fall back to external otherwise.

The story doesn’t end here, though. While implementing support for i/macOS, it wasn’t really clear to me how we could fuse in symbols provided by the JavaScript side. (The second argument to CModule’s constructor.)

The GCC implementation uses a linker script, which is a really elegant solution that Apple’s linker doesn’t support. But then it hit me: we already have our own dynamic linker that we use for our injector.

Once I had wired that up, it seemed really obvious that we could also trivially support skipping Clang entirely, and allow the user to pass in a precompiled shared library.

The thinking there was that it would enable cross-compilation, but also make it possible to implement a CModule in languages such as Swift and Rust: basically anything that can interop with C.

So this means we now also support the following:

const cm = new CModule(blob);

Where blob is an ArrayBuffer containing the shared library to construct it from. For now this part is only implemented on i/macOS, but the goal is to support this on all platforms. (Contributions welcome!)

Also, as of frida-tools 9.2, the REPL’s -C switch also supports this, making it easy to use an external toolchain without missing out on live-reload – which makes for a much shorter feedback loop during development.

Taking that one step further, the CModule API now also provides a the property CModule.builtins, which scaffolding tools can use to obtain the built-in headers and preprocessor defines.

And on that note we now have such a tool in frida-tools:

$ mkdir pewpew
$ cd pewpew
$ frida-create cmodule
Created ./meson.build
Created ./pewpew.c
Created ./.gitignore
Created ./include/glib.h
Created ./include/gum/gumstalker.h
Created ./include/gum/gumprocess.h
Created ./include/gum/gummetalarray.h
Created ./include/gum/guminterceptor.h
Created ./include/gum/gumspinlock.h
Created ./include/gum/gummetalhash.h
Created ./include/gum/gummemory.h
Created ./include/gum/gumdefs.h
Created ./include/gum/gummodulemap.h
Created ./include/json-glib/json-glib.h
Created ./include/gum/arch-x86/gumx86writer.h
Created ./include/capstone.h
Created ./include/x86.h
Created ./include/platform.h

Run `meson build && ninja -C build` to build, then:
- Inject CModule using the REPL: frida Calculator -C ./build/pewpew.dylib
- Edit *.c, and build incrementally through `ninja -C build`
- REPL will live-reload whenever ./build/pewpew.dylib changes on disk

$ meson build && ninja -C build
…
[2/2] Linking target pewpew.dylib
$ frida Calculator -C ./build/pewpew.dylib
…
init()
[Local::Calculator]->

And yes, it live-reloads! Taken to the extreme you could use a file-watcher tool and make it run ninja -C build whenever pewpew.c changes – then just save and instantly see the instrumentation go live in the target process.

It’s worth noting that you can also use the above when using the internal CModule toolchain, as having the headers available on disk is handy for editor features such as code completion.

EOF

There’s also a bunch of other exciting changes, so definitely check out the changelog below.

Enjoy!

Changes in 14.2.0

• Brand new realms API for instrumenting emulated realms inside native processes. Only implemented on Android for now.
• Add Java.deoptimizeBootImage(). Thanks @alkalinesec!
• Add –disable-preload/-P to frida-server. Useful in case of OS compatibility issues where Frida crashes certain OS processes when attaching to them.
• Fix libc detection on older versions of Android.
• Fix crash when resolving export of the vDSO on Android. Thanks @ant9000!
• Restore support for libhoudini on Android.
• Fix ARM cache flushing on Android 11’s translator.
• Fix linker offsets for Android 5.x. Thanks @muhzii!
• Start refactoring CModule’s internals to prepare for multiple backends. Thanks @mephi42!
• Fix CModule aggregate initializations on ARM.
• Fix ModuleApiResolver fast-path emitting bad matches.

Changes in 14.2.1

• Fix CModule constructor error-path in the V8 runtime.
• Use V8 runtime for the “system_server” agent on Android.

Changes in 14.2.2

• Fix Darwin.Mapper arm64e handling of pages without fixups. This went unnoticed out of pure “luck”, until our binaries eventually mutated sufficiently to expose this bug.

Changes in 14.2.3

• Upgrade to using inline hooking for the ART runtime. Thanks @muhzii!
• Fix direct transport regression on i/macOS, introduced by GLib upgrade where GLib.Socket gained GLib.Credentials support on Apple OSes. A typical symptom of this regression is that frida-server gets killed by Jetsam.
• Fix libffi support for stdcall, thiscall, and fastcall on 32-bit Windows.
• Extend Memory.alloc() to support allocating near a given address. Thanks @muhzii!
• Fix relocation of RIP-relative indirect branches on x86_64. Thanks @dkw72n!
• Improve the JVM C++ allocator API probing logic by consulting debug symbols before giving up. Thanks @Happyholic1203!
• Upgrade SELinux libraries to support bleeding edge Android systems.
• Add gum-linux-x86_64-gir target for GIR generation. Thanks @meme!

Changes in 14.2.4

• Fix Android performance regression when ART’s interpreter is used, such as when using deoptimizeEverything() or deoptimizeBootImage(), which results in our JS callbacks becoming extremely hot. Move the hot callbacks to CModule to speed things up.
• Fix V8 debugger support in Node.js bindings on Linux.
• Fix crash on ELF init error in the libdwarf backend.

Changes in 14.2.5

• Fix regression on older Android systems, introduced in 14.2.4.

Changes in 14.2.6

• Fix compatibility with legacy NativeBridge v3 and newer, where a namespace needs to be specified.

Changes in 14.2.7

• Fix frida-java-bridge crash on systems where printf() renders %p without “0x” prefix.
• Fix jni_ids_indirection_ offset parsing on ARM64. Thanks @muhzii!

Changes in 14.2.8

• Fix GLib SO_NOSIGPIPE regression on i/macOS. This would typically result in frida-server dying due to SIGPIPE. Thanks @mrmacete!
• Refactor CModule internals and lay foundations for GCC backend. Thanks @mephi42!
• Add EventSink.make_from_callback() for Stalker C API consumers that only care about events, and don’t need lifecycle hooks or code transformations.
• Emit Stalker BLOCK event at the start of the block, as this is what’s the most intuitive, as one would expect at least as many BLOCK events as COMPILE events. This behavior is also the most suitable for measuring coverage.
• Add Stalker prefetch support, useful for optimizing “AFL fork server”-like use-cases.

Changes in 14.2.9

• Handle permanent entries in Darwin CodeSegment backend. Starting from iOS 14.3 on A12+ devices, mach_vm_remap() can return KERN_NO_SPACE when the target VM map entries are marked as “permanent”. Thanks @mrmacete!
• Wire up GCC support in CModule. Thanks @mephi42!
• Add CModule backend for Clang on Apple OSes.
• Add support for linking in a prebuilt CModule. (Only on i/macOS for now.)
• Finalize the CModule toolchain selection API.
• Add CModule.builtins property for tooling support.
• Generate frida-core GIR by default. Thanks @meme!
• Fix regressions on Linux/MIPS.

Changes in 14.2.10

• Improve frida-inject to support bidirectional stdio.
• Add support for Termux in frida-python: pip install frida-tools now works.

Changes in 14.2.11

• Improve frida-inject to support raw terminal mode.
• Add internal policy daemon for Darwin.
• Improve Gum.Darwin.Mapper to support strict kernels.

Changes in 14.2.12

• Fix ART method hooking reliability after GC. Thanks @muhzii!

Changes in 14.2.13

• Fix Instruction operands parsing on x86, ensuring the immediate value is always represented by an Int64 and never a number. Thanks @muhzii!
• Fix frida-inject when process is not attached to a terminal. Thanks @muhzii!
• Expose Base64 and Checksum GLib primitives to CModule. Thanks @mrmacete!

Changes in 14.2.14

• Fix Gadget crash on i/macOS when loaded early.
• Make frida-inject stdin communication optional. Thanks @muhzii!
• Support iOS app spawn on unc0ver 6.x. Thanks @mrmacete!
• Work around single-step delay when spawning iOS apps, to avoid failing randomly. Thanks @mrmacete!
• Fix read() signature mismatch in the libc shim, which would result in a compilation error on newer Apple toolchains. Thanks @Manouchehri!
• Fix Android enumerate_applications() name truncation on newer versions of Android. Kudos to @pancake for reporting and helping figure this one out!
• Fix hang when target is unable to load frida-agent.
• Fix support for attaching to Windows services.
• Clean up stale Windows services before registering new ones.
• Add build option to support using installed assets instead of embedding them.
• Update iOS packaging to use installed assets.
• Add basic support for jailed Android. Thanks @enovella_ for all the fun and productive pair-programming on this one!
• Extend Arm64Writer API to support more immediates.
• Improve Stalker to support temporarily misaligned stack on arm64.
• Fix crash in Stalker follow() without a sink.
• Implement Stalker invalidation support. This allows updating the instrumentation without throwing away all of the translated code. Thanks for the assist on this one, @p1onk!
• Add Gum.DarwinModule.enumerate_function_starts().
• Add Gum.DarwinGrafter for AOT grafting to be able to prepare binaries so they can be instrumented when runtime code modification isn’t possible. Thanks for the assist, @mrmacete!
• Add Memory.allocate_near().
• Improve Stalker performance and robustness on all supported architectures:
  • Improve call probes to probe at the target instead of at the call site, and take advantage of the new invalidation infrastructure.
  • Handle adding/removing call probes from within call probes.
  • Refactor callout-handling so user data can be destroyed on invalidate. This also eliminates the callout lock.
  • In case of self-modifying code, recompile instead of allocating a new block.
  • Use separate slabs for code and data, to avoid cases where we only use part of the slab because we run out of metadata storage.
  • Inline the first code/data slab in ExecCtx, so we use a lot less memory when following threads that either don’t touch much code, or none at all in case they don’t wake up.
  • Don’t bother storing original code when trust_threshold is 0.
  • Simplify Stalker block metadata to reduce the per-block memory consumption.
• Fix result of Java.enumerateMethods() on ART. This was a bug where static initializer methods were being included in the enumerated set as ‘$init’ when they should be skipped altogether. Thanks @muhzii!
• Fix the Android/ART near memory allocation code path used during Java method hooking. Thanks @muhzii!
• Fix handling of generic Java array types. This allows array objects obtained from the runtime to be reused later when marshalling array types, which is necessary to preserve type information particularly in cases where the type is dynamic. Thanks @muhzii!
• Port Android/ART StackVisitor to x86, x64, and ARM32. Thanks @P-Sc!
• Fix ARM cache flushing on Android. Turns out cacheflush() expects a range on Linux/ARM. This 32-bit Android/ARM regression was introduced in 14.2.0.
• Add a few missing TinyCC builtins for 32-bit ARM. Kudos to @giantpune for reporting and helping figure this one out!
• Fix wrap-around in Stalker block recycling logic.
• Fix V8 NativePointer construction from large numbers.
• Fix Stalker local thread actions on Windows.
• Fix the CModule temporary directory cleanup logic.
• Remove forgotten InspectorServer debug code.
• Fix the V8 debugger integration. Kudos to @taviso for reporting!

Changes in 14.2.15

• Fix compatibility with latest unc0ver iOS jailbreak. Thanks @mrmacete!
• Add support for Anbox. Thanks @asabil!
• Add Java.deoptimizeMethod(). Thanks @liuyufei!
• Handle replacing ART methods that may be devirtualized. Thanks @liuyufei!

Changes in 14.2.16

• Add many missing TinyCC builtins for 32-bit ARM. Kudos to @giantpune for reporting and helping figure this one out!
• Fix Android ART trampoline alignment when using ADRP on arm64, previously resulting in Error: invalid argument exception being thrown when attempting to replace some methods. Kudos to @pandasauce for reporting and helping figure this one out!

Changes in 14.2.17

• Enumerate Darwin imports from chained fixups, to support the latest arm64e binaries. Thanks @mrmacete!
• Fix chained fixups handling in the jailed iOS injector. Thanks @mrmacete!
• qml: Compile with no_keywords for GLib compatibility. Thanks @suy!

Changes in 14.2.18

• Fix i/macOS injector on recent XNU versions, where mach_port_extract_right() fails with KERN_INVALID_CAPABILITY when trying to steal the target process’ POSIX thread port send right. This resulted in the injector assuming that we’d uninjected, subsequently deallocating memory still in use.
• Fix ___error symbol name in the jailed iOS injector. Thanks @mrmacete!
• Fix enumeration of modules with spaces on path in the Linux backend. Thanks @suy!
• Fix Stalker handling of direct branch addresses on x64.
• python: Add RPC exports listing functionality. Thanks @NewbieGoose!

Lots of goodies this time! 🎉 Let’s dive in.

Dependencies

We’ve just upgraded all of our dependencies to the latest and greatest. Part of this work included refurbishing the build system bits used for building them.

With these improvements we will finally support building past versions of Frida fully from source, which has been a long-standing issue that’s caused a lot of frustration.

It is now also a whole lot easier to tweak our dependencies, e.g. while debugging an issue. Say you’re troubleshooting why Thread.backtrace() isn’t working well on Android, you might want to play around with libunwind’s internals. It is now really easy to build one specific dependency:

$ make -f Makefile.sdk.mk FRIDA_HOST=android-arm64 libunwind

Or if you’re building it for the local system:

$ make -f Makefile.sdk.mk libunwind

But you might already have built Frida, and want to switch out libunwind in the prebuilt SDK that it is using. To do that you can now do:

$ make -f Makefile.sdk.mk symlinks-libunwind

You can then keep making changes to “deps/libunwind”, and perform an incremental compilation by re-running:

$ make -f Makefile.sdk.mk libunwind

iOS

We now support iOS 14.2. It was kinda already working, but our crash reporter integration would deadlock Apple’s crash reporter, and this isn’t great for system stability overall.

GumJS support for size_t and ssize_t

Thanks to @mame82 we finally support “size_t” and “ssize_t” in APIs such as NativeFunction. This means that your cross-platform agents no longer need to maintain mappings to the native types that these correspond to. Yay!

System GLib support

Gum can finally be built with the upstream version of GLib, and we now support generating GObject introspection definitions. This paves the way for future language bindings that are fully auto-generated.

Kudos to @meme for these awesome improvements!

Windows inprocess injection

Our Windows backend finally supports inprocess injection. By this I mean that in the most common cases where the target process’ architecture is the same – and no elevation is needed – we can now avoid writing out “frida-helper-{32,64}.exe” to a temporary directory and launching it before we’re able to attach() to a given target. As an added bonus this also reduces our startup time.

The motivation behind this improvement was to fix a long-standing issue where some endpoint security products would prevent our injector from working, as our logic was prone to trigger false positives in such software. We will still obviously run into such issues when we do need to spawn our helpers, but there’s now a good chance that the most common use-cases will actually work.

Stalker ARM improvements

For those of you using Stalker on 32-bit ARM, it should now be working a whole lot better than ever before. A whole slew of fixes landed in this release.

Bytecode and frida-tools

One of the realizations since 14.0 was released is that QuickJS’ bytecode format is a lot more volatile than expected. Because of this I would caution against using “frida-compile -b” unless your application is designed to only be used with one exact version of Frida.

As I wasn’t aware of this pitfall when cutting the previous release of frida-tools, I opted to precompile the frida-trace agent to bytecode. Upon realizing my mistake while working on releasing 14.1, I reverted this mistake and released a new version of frida-tools.

So make sure you also grab its latest release while upgrading:

$ pip3 install -U frida-tools

EOF

There’s also a bunch of other exciting changes, so definitely check out the changelog below.

Enjoy!

Changes in 14.1.0

• All dependencies upgraded to the latest and greatest.
• Heavily refurbished build system for dependencies. Going forward we will finally support building past versions of Frida fully from source.
• Port iOS crash reporter integration to iOS 14.2.
• Fix error propagation when talking to iOS devices.
• Add support for “size_t” and “ssize_t” in GumJS. Thanks @mame82!
• Support linking against system GLib and libffi. Thanks @meme!
• Support GObject Introspection. Thanks @meme!
• Improve Windows backend to support inprocess injection. This means we can dodge common AV heuristics and speed things up in the most common cases where the target process’ architecture is the same, and no elevation is needed.
• Fix Stalker ARM handling of “ldr pc, [sp], #4”.
• Fix Stalker ARM clobbering of flags in IT blocks.
• Fix Stalker ARM handling of CMN/CMP/TST in IT blocks.
• Fix suppression flags for ThumbWriter instruction.
• Fix Stalker ARM exclusion logic reliability.
• Fix ARM Stalker follow() of thread in Thumb mode.
• Fix ARM Stalker SVC handling in Thumb mode.
• Fix ThumbRelocator handling of unaligned ADR.
• Move Stalker ARM to runtime VFP feature detection.
• Refuse to Interceptor.attach() without any callbacks.
• Improve GumJS error message formatting.
• Fix starvation in the V8 debugger integration.
• Keep NativeCallback alive during calls on V8 also.

Changes in 14.1.1

• Fix CModule regression where Capstone went missing.
• Add missing CModule builtins for 32-bit ARM.
• Fix Thread.backtrace() on Android/ARM64.

Changes in 14.1.2

• Fix Thread.backtrace() on Android/ARM.

Changes in 14.1.3

• Fix ObjC.choose(). The TinyCC upgrade in 14.1.0 exposed an existing bug.
• Re-enable V8 by default. Turns out we have use-cases where it is a much better fit than QuickJS, and its debugger features were also being sorely missed.
• Add –ignore-crashes/-C to frida-server for disabling the native crash reporter integration. For use-cases where the integration is undesired, or when running on bleeding edge OS versions that we don’t yet fully support. (Crash reporter integration is only available on iOS and Android for now.)
• Enhance devkits to ensure Capstone APIs are exposed on all platforms.
• Improve devkit examples.

Here’s a major new release that took weeks of intense coding, with way too many cups of coffee. But before we dive into it, we need to have a quick look down memory lane.

For years now our V8-based runtime has served us well. But eventually we needed to support constrained systems where V8 isn’t a great fit, so we introduced a second runtime.

This has worked out nicely, but there were some trade-offs we were left with:

• Language feature support being wildly different between the two runtimes. We tried to alleviate some of this by making the minimalistic runtime be the default, as it’s available everywhere and is the lowest common denominator in terms of features.
• Needing to sacrifice performance when using a tool such as frida-compile to compile modern JavaScript to old JavaScript that runs on both runtimes.
• Non-trivial agents with lots of code and data floating around make it clear not just how fast V8 is – no surprise there – but that it’s really good at packing objects to avoid wasting precious RAM. And to widen the gap between the two runtimes even more, V8 can run the modern JavaScript as-is and doesn’t need to run a bloated version that contains compatibility shims to fill in the missing runtime bits such as Map and Set.
• Example code and documentation tends to look arcane to avoid confusing users who might try to run modern code on the default runtime.
• Garbage collector implementation differences may hide the user’s bugs in one runtime that instantly blow up in the other where resources are released way more eagerly. One such example is failing to keep a NativeCallback alive while external code is still using it.
• Terrible UX: All of the above is a very frustrating and confusing story to tell our users.
• New features and refinements need to be implemented twice. This is a real pain for me as a maintainer for obvious reasons.

Fast-forward to 2019 and QuickJS caught my eye. I was really busy with other things at the time, though, so by the time I looked closer at it I noticed it supports ES2020, and also performs impressively well for an interpreter.

But as I started thinking about bringing up a new runtime from scratch, and seeing as the other two are roughly ~25 KLOC each, it just felt overwhelming.

I kept coming back to the QuickJS website though, devouring the technical details, and even started reading deeper into the public API at some point.

Then I noticed that it didn’t support cooperative multi-threaded use, where multiple threads execute JavaScript in lockstep. This made the mountain of work ahead feel even more daunting, but then I remembered that I’d already contributed support for this in Duktape, and it wasn’t that hard.

Eventually I mustered up the courage. Picked a super-simple test from GumJS’ extensive test-suite as my first challenge, and went ahead and copy-pasted the ScriptBackend and Script implementations from the youngest of the existing two runtimes. First renaming things, then stubbing out all of the modules (Interceptor, Stalker, etc.), just wanting to get a near-empty “shell” to compile and run.

At this point I was hooked and couldn’t stop. Lots of coffee was consumed, and before I knew it I’d gotten the core bits and the first module implemented. Then another, and then one more.

After working quite a bit with the QuickJS API, and jumping around its internals to make sure I understood the reference counting rules etc., it suddenly seemed really clear what was needed to implement the cooperative multi-threading API that would be needed to make this a real runtime and not just a toy.

What we need to be able to do is suspend JS execution while calling out to a NativeFunction. This is because the called function may block waiting for a lock which another thread might already be holding, but that other thread may have just called a hooked function and is waiting to enter the JS runtime. So if we didn’t let go of the JS lock before calling the NativeFunction, we’d now be in a deadlock.

Another use-case is calling Thread.sleep() or some other blocking API where we’d cause starvation if we did that while holding the JS lock.

Anyway, the QuickJS multi-threading API turned out to be straight-forward, so from there I kept on going, until it was all finally done! 🎉

At this point I was really curious about the performance of this brand new runtime, starting with the question of what it costs to enter and leave it.

Went ahead and took it for a spin on an iPhone 6, running the GumJS test that uses Interceptor to hook a nearly empty C function, supplying an empty JS callback, and then measures the wall-clock time spent on each call as it keeps calling the C function over and over.

The idea is to simulate what would happen if the user hooks a function that’s called frequently, to get an idea of the base overhead.

Here’s what I got:

# QuickJS
<min: 1.0 us, max: 7.0 us, median: 2.0 us> ok 1 /GumJS/Script/Interceptor/Performance/interceptor_on_enter_performance#QJS
<min: 2.0 us, max: 54.0 us, median: 2.0 us> ok 2 /GumJS/Script/Interceptor/Performance/interceptor_on_leave_performance#QJS
<min: 3.0 us, max: 18.0 us, median: 3.0 us> ok 3 /GumJS/Script/Interceptor/Performance/interceptor_on_enter_and_leave_performance#QJS
# Duktape
<min: 2.0 us, max: 8.0 us, median: 3.0 us> ok 4 /GumJS/Script/Interceptor/Performance/interceptor_on_enter_performance#DUK
<min: 2.0 us, max: 6.0 us, median: 3.0 us> ok 5 /GumJS/Script/Interceptor/Performance/interceptor_on_leave_performance#DUK
<min: 4.0 us, max: 89.0 us, median: 4.0 us> ok 6 /GumJS/Script/Interceptor/Performance/interceptor_on_enter_and_leave_performance#DUK
# V8
<min: 13.0 us, max: 119.0 us, median: 14.0 us> ok 7 /GumJS/Script/Interceptor/Performance/interceptor_on_enter_performance#V8
<min: 15.0 us, max: 127.0 us, median: 16.0 us> ok 8 /GumJS/Script/Interceptor/Performance/interceptor_on_leave_performance#V8
<min: 26.0 us, max: 198.0 us, median: 28.0 us> ok 9 /GumJS/Script/Interceptor/Performance/interceptor_on_enter_and_leave_performance#V8

Wow, so that was looking promising! How about baseline memory usage, i.e. how much memory is consumed by one instance of the runtime itself?

That’s quite an improvement – only one fifth of the previous runtime!