Grapefruit Mobile Security Testing for iOS and Android

Grapefruit's Role in Authorized Mobile Assessments

Grapefruit addresses the part of mobile security testing that happens inside a running application. Instead of limiting an assessment to a static APK, IPA, DEX file, or native binary, it uses Frida to inspect methods, capture runtime data, browse application storage, and modify process behavior while the target remains active. Its intended users are mobile security practitioners performing authorized assessments, reverse engineering, or application privacy reviews.

The project supports both iOS and Android through a web-based interface. Documented capabilities include runtime method hooking, cryptographic API interception, filesystem navigation, SQLite queries, process crash reports, memory scanning, thread inspection, and module or symbol browsing. Platform-specific features add Keychain, `NSURLSession`, WebView, and Objective-C inspection on iOS. Android users can inspect `AndroidManifest.xml`, Android Keystore entries, content providers, JNI calls, Java classes, and application components.

Grapefruit is an interaction and observation suite, not an automated scanner that returns a complete vulnerability verdict. It exposes evidence about runtime behavior, including which sensitive APIs an application accesses, which files it opens, and what reaches an SQLite database. It can also alter process state. Geolocation and device ID spoofing, for example, change what the target application receives. Such operations require explicit authorization over the target device and application.

The choice between runtime and static analysis affects tooling decisions. A static tool can inspect an artifact without attaching to it. Grapefruit instead requires a live Frida session, but that prerequisite allows an assessor to observe process state, method arguments, network events, and data changes that artifact inspection cannot establish directly.

Frida Instrumentation and Grapefruit's Server Architecture

The README describes Grapefruit as a runtime mobile application instrumentation toolkit powered by Frida. Its web interface supports inspecting, hooking, and modifying mobile applications. Before starting Grapefruit, the assessor must configure and run a Frida server on the target device using Frida's official setup guides for iOS or Android.

The `igf` command starts a server on `127.0.0.1:31337` by default and opens the browser unless `--no-open` is specified. Project data, cache, and logs are written under `.igf` in the current working directory unless another path is configured. This local default limits accidental network exposure, but changing the bind address expands the operational boundary because the interface provides inspection and runtime modification controls.

The package dependencies include `frida`, an npm alias named `frida16` for the older major release, and `frida-remote-stream`. It also depends on `socket.io` and `socket.io-client`, which is consistent with a Node.js server communicating with a browser client. The repository layout separates CLI or daemon code under `src/`, the web interface under `gui/`, agent artifacts under `agent/`, and database-related files under `drizzle/`.

The repository also documents its CLI and daemon, architecture, and RPC layers. The contents of `docs/arch.md` and `docs/rpc.md` are not reproduced here, so their exact internal boundaries are not confirmed. CLI flags override environment variables, and the application supports selecting Frida major version 16 or 17. That flexibility does not remove the need to coordinate the selected Grapefruit dependency with the Frida server and target environment.

Installing igf and Starting a Local Session

The README identifies npm installation as the recommended route and requires Node.js 22.18 or later. The package exposes the `igf` executable. The following command installs it globally:

npm install -g igf

After installation, run `igf` from the directory in which the default `.igf` project directory should be created. With the documented defaults, the server binds to `127.0.0.1`, listens on port `31337`, and opens the web interface.

igf

An assessor can also run the package without a global installation. This command invokes the same `igf` executable through `npx` and still requires Node.js 22.18 or later.

npx igf

The documented CLI includes `--host <host>`, `--port <port>`, `--project <path>`, `--frida <16 | 17>`, and `--no-open`. These options are documented as command-line settings, but the README does not provide a complete first-use sequence that combines them. Prebuilt executables for macOS, Linux, and Windows are also available through GitHub Releases. The first workflow begins with the Frida server running on the authorized device, followed by the Grapefruit server and its browser interface.

Frida 16 and Frida 17 Selection

Grapefruit defaults to Frida 17, while the CLI accepts either major version through `--frida`. This is a meaningful deployment choice because instrumentation behavior can differ between Frida releases. The CLI exposes Frida as a named dependency and a `frida16` alias, allowing the application to select a client for either supported major line.

The CLI selection takes precedence over the `FRIDA_VERSION` environment variable. The documented accepted values are `16` or `17`. The same selection can be expressed through the environment variable, with the CLI option winning when both are set.

The device-side Frida server and target application must work with the selected client. A mismatch may surface during attachment, script loading, transport setup, or runtime instrumentation. The README points users to Frida's official platform guides but does not provide a single compatibility matrix for every iOS version, Android version, Grapefruit release, and Frida server build. Teams should therefore treat their device setup as a prerequisite to verify rather than assuming that installation of `igf` configures the device automatically.

Frida selection also affects the separate RASP investigation path. The README's recommended `frida-strace` example requires Frida 17.8.0 or later, while Grapefruit itself defaults to major version 17 and accepts major version 16. The two version statements serve different purposes, so an assessor should check the exact Frida version needed by both Grapefruit and any bypass tooling before combining them.

iOS and Android Runtime Inspection Surfaces

Grapefruit's feature set combines passive observation with active interaction. For iOS, the README documents Keychain access and modification, `NSURLSession` traffic capture, WebView and `JSContext` inspection, JavaScript execution, UI hierarchy dumps, element highlighting, and viewers for `Info.plist`, entitlements, cookies, and `Assets.car`.

Additional iOS features include `UserDefaults` browsing, pasteboard and file operation monitoring, open file handles, network connections, Objective-C class and method inspection, XPC message inspection, and geolocation or device ID spoofing. The documented biometric controls cover Touch ID and Face ID bypass. These functions can alter application decisions, so they should be used only against targets covered by written authorization.

Android support includes decoding `AndroidManifest.xml` and browsing activities, services, receivers, and providers. The suite can inspect Android Keystore key attributes, issue content provider queries, inserts, updates, and deletes, trace JNI calls with arguments, return values, and backtraces, and inspect Java methods, fields, and interfaces.

The Android interface also documents intent construction and launching, resources browsing, clipboard and `SharedPreferences` monitoring, broadcast receiver monitoring, and HTTP capture for OkHttp, Volley, and `URLConnection`. Cross-platform inspection includes SQLite queries, file uploads and downloads, hex or text previews, syslog streaming, memory searches, privacy monitoring, and thread management.

The breadth makes Grapefruit useful for a runtime review that crosses several data sources. It does not guarantee coverage for every framework or API. The README lists named frameworks and protocols, but an assessor should verify that the exact APIs and binary structure of the target application are represented by the available inspection surface.

Flutter, React Native, and Analysis Outputs

Grapefruit has explicit support for Flutter and React Native, covering application layers that sit above ordinary native APIs. For Flutter, the README documents monitoring of platform method channels and exploration of Dart AOT snapshots. Users can inspect functions, classes, strings, references, and recovered components, while the broader analysis surface includes DEX, Flutter AOT, Hermes bytecode, and native code.

The repository includes a `r2hermes-wasm` package dependency and GUI scripts for checking an R2 WebAssembly artifact. This supports the claim that Hermes analysis has project-specific machinery, but the README does not explain the complete decoding workflow or the fidelity of recovered components. Those details should not be inferred from a successful interface view.

For React Native, Grapefruit provides a bridge inspector and a JavaScript injection REPL. The bridge view exposes communication between JavaScript and native code, while the REPL allows an assessor to evaluate JavaScript in the supported runtime. The README does not state which React Native releases are covered or how bridge messages are validated.

The suite also supports AI-assisted hook script generation through configured LLM providers. Supported `LLM_PROVIDER` values are `anthropic`, `openai`, `gemini`, and `openrouter`. An API key, model, and optional custom endpoint can be supplied with `LLM_API_KEY`, `LLM_MODEL`, and `LLM_BASE_URL`.

These capabilities add value during authorized analysis, but they also create a separate data-handling decision. The README does not specify which target details are transmitted to an LLM provider. An organization should settle that question before enabling the integration on sensitive applications or captured runtime data.

RASP Detection and Certificate-Pinning Exclusions

The clearest limitation is explicit in the Scope and Non-Goals section. Grapefruit does not include built-in bypasses for Frida detection, SSL or TLS certificate pinning, jailbreak detection, or root detection. The README explains that RASP controls evolve and that bypasses tend to be application-specific, which can create maintenance and stability problems for a general-purpose suite.

This boundary matters when selecting the project. Traffic capture does not guarantee that a protected application will allow an instrumented connection, and a method hook does not guarantee that the process will continue running after it detects Frida. An assessor must not treat Grapefruit's instrumentation features as proof that every target can be attached.

For authorized assessments requiring RASP bypass, the README recommends creating a separate Frida session first. Because the target is already running, Grapefruit attaches to the existing process instead of respawning it, preserving the bypass session according to the project documentation. The assessor must coordinate the two sessions and maintain any application-specific bypass scripts separately.

The README also recommends the Frida syscall tracer for identifying detection artifacts. The documented command targets a package by its Android application identifier:

frida-strace -U -f com.example.app

The README states that this command requires Frida 17.8.0 or later. It can help an assessor investigate a detection path, but it does not guarantee a reusable bypass. A target that requires root, jailbreak, integrity, or certificate-pinning work remains outside Grapefruit's built-in scope.

Server Exposure, Project Data, and LLM Configuration

Grapefruit stores project data, cache, and logs in `.igf` under the current working directory by default. That directory can contain evidence and state associated with an assessment, so operators need to account for it when collecting results or moving the project between systems. The `--project <path>` flag and `PROJECT_DIR` environment variable can select another directory.

The server binds to `127.0.0.1` by default. `HOST`, `PORT`, `--host`, and `--port` provide server settings, with command-line flags taking precedence. The interface can inspect sensitive data and modify application behavior. Changing the host from the documented local default therefore deserves a separate exposure review, particularly for assessments involving credentials, private files, or production-like environments.

The README documents `LLM_PROVIDER`, `LLM_API_KEY`, `LLM_MODEL`, and `LLM_BASE_URL` for optional AI-assisted hook generation. `LLM_PROVIDER` accepts `anthropic`, `openai`, `gemini`, or `openrouter`. `LLM_BASE_URL` overrides the provider default. The README does not document credential redaction, prompt retention, provider data processing, or a policy for captured secrets, so those details cannot be inferred from the variable names.

The local server default and project-directory controls are documented, while LLM data handling remains outside the stated documentation. An assessor should decide whether captured application data is suitable for the selected provider before enabling the feature.

Grapefruit Releases, License, and Upgrade Cost

The repository is not archived, and the last push was on 2026-10-06. Recent releases include `v1.1.0`, `v1.1.1`, and `v1.1.2`, each released on 2026-03-30. The npm package version in `package.json` is `1.1.2`, and the package declares `[email protected]` as its package manager. These are concrete maintenance facts, but they do not establish compatibility with every target application or device configuration.

Upgrade effort is tied closely to Frida and the target environment. The package depends on `frida` at `17.22.2` and includes `frida16`, an alias for `frida@^16.7.19`. The CLI supports major versions 16 and 17. Moving between Grapefruit, Frida client, and device-side Frida server versions can require synchronized changes, and custom hooks may also need review after such an upgrade.

The project uses the MIT license in both the repository and `package.json`. MIT licensing permits reuse, modification, and distribution subject to its notice and disclaimer conditions. That license does not authorize testing a third-party application, grant access to a device, or override contractual restrictions on security testing.

Operational upgrades also involve stored assessment artifacts, logs, external bypass scripts, and optional LLM configuration. The README documents `PROJECT_DIR` and the provider variables but does not provide a migration guide for every historical Grapefruit project. An adopter should verify release compatibility, Frida alignment, and the handling of existing `.igf` data before replacing a working installation.

Static Inspection and Standalone Frida Scripts as Alternatives

The main alternative described by the available documentation is a static analysis workflow. A static tool examines an IPA, APK, DEX file, manifest, entitlement set, or native binary without attaching to a live process. Grapefruit uses a different approach: it depends on a running Frida session and exposes live process events through a browser interface.

Static inspection is better suited to package contents, declared components, embedded resources, strings, and binary structure that can be decoded without execution. Grapefruit is better suited to method arguments, live API calls, process state, file operations, database contents, network events, memory, threads, and controlled behavior changes. A broad assessment can require both, because each reveals different evidence.

Another approach is to combine standalone Frida scripts with task-specific tools. That can produce a smaller workflow for one inspection goal, but each script and interface must be assembled separately. Grapefruit puts hooks, storage, databases, logs, memory, threads, modules, crash data, and platform inspection into one web-based suite. The trade-off is a broader tool with more device-side prerequisites and a separate requirement for RASP bypass tooling.

The deciding question is whether the assessment needs live process evidence. Grapefruit has a clear role when an assessor must interact with a running application. Static inspection is the better starting point when the objective is package triage without attaching to a device.

Editorial conclusion

Security practitioners should adopt Grapefruit when an authorized assessment needs interactive hooks, file and database inspection, runtime evidence, or controlled application modification from a web interface. It is not a complete solution for applications protected by Frida detection, root or jailbreak detection, or certificate pinning because those bypasses are explicit non-goals. Before adoption, verify that the target can be instrumented with the selected Frida version, confirm that the device setup is authorized, and review the configured bind address, project directory, logs, and optional LLM integration.

Frequently asked questions

Official sources

1. ChiChou/grapefruit on GitHub
2. License: MIT
3. Project website
4. README
5. Releases