gum-graft

Apr 22, 2026 00:00:00

Purpose

gum-graft pre-patches Mach-O binaries so that Frida’s Interceptor can instrument them in environments where runtime code modification is blocked by strict code-signing enforcement.

Primary use case: Jailed Apple mobile devices (iOS/iPadOS) running an app without a debugger attached.

Prerequisites

Target: Mach-O binary (Apple mobile platforms)
Required Gadget configuration: set code_signing option to required in the Frida Gadget config
Download gum-graft from: https://github.com/frida/frida/releases

When to Use

Condition	Use gum-graft?
Jailed iOS device, no debugger attached, strict code-signing	Yes
Jailed iOS device with debugger attached	No (runtime patching works)
Jailbroken device	No (runtime patching works)
macOS / Linux / Windows	No (runtime patching works)

CLI Reference

Usage: gum-graft [OPTION?] BINARY - graft instrumentation into Mach-O binaries

Help Options

Flag	Description
`-h`, `--help`	Show help options

Application Options

Flag	Argument	Description
`-i`, `--instrument`	`0x1234`	Include instrumentation for a specific code offset
`-s`, `--ingest-function-starts`	—	Include instrumentation for all offsets from `LC_FUNCTION_STARTS` load command
`-m`, `--ingest-imports`	—	Include instrumentation for all imported symbols
`-z`, `--transform-lazy-binds`	—	Transform lazy binds into regular binds (experimental)

Usage Notes

-i / --instrument: Use when you know the exact offset(s) to instrument (e.g., a specific function address within the binary).
-s / --ingest-function-starts: Instruments every function recorded in the LC_FUNCTION_STARTS Mach-O load command — broadest coverage, largest overhead.
-m / --ingest-imports: Instruments all imported functions at the boundary, useful for tracing library calls.
-z / --transform-lazy-binds: Converts lazily-bound imports to eagerly-bound; experimental — may affect startup behavior.

Workflow

Build and sign the target binary with Frida Gadget embedded.
Set Gadget code_signing to required in its JSON config.
Run gum-graft against the binary with the desired instrumentation options.
Re-sign the patched binary with your provisioning profile.
Deploy to the jailed device — Interceptor hooks will fire at the pre-patched sites.