frooky 0.1.0

Frida-powered hook runner based on JSON hook files.

Frooky

   ___    ____           
  / __\  / _  |    _     _    _  _   _   _
 / _\   | (_) |  / _ \ / _ \ | / /  | | | |
/ /     / / | | | (_) | (_) ||  <   | |_| |
\/     /_/  |_|  \___/ \___/ |_|\_\  \__, |
                                     |___/

A Frida-based dynamic analysis tool for Android and iOS applications.

Installation

pip install frooky

Usage

# Attach by app name
frooky -U -n "My App" hooks.json

# Spawn and add multiple hook files (hooks are merged)
frooky -U -f com.example.app hooks.json hooks2.json more_hooks.json

See frooky -h for more options.

Hook Files

Hook files use JSON format. When multiple hook files are provided, their hooks arrays are merged together.

Basic Structure

{
  "category": "STORAGE",
  "hooks": [
    {
      "class": "com.example.MyClass",
      "methods": ["method1", "method2"]
    }
  ]
}

Java/Kotlin Hooks

Simple Method Hook

{
  "class": "java.io.File",
  "method": "exists"
}

Multiple Methods

{
  "class": "java.io.FileOutputStream",
  "methods": ["write", "close", "flush"]
}

Method Overloads

Specify exact method signatures using overloads:

{
  "class": "java.io.FileOutputStream",
  "method": "write",
  "overloads": [
    { "args": ["[B"] },
    { "args": ["[B", "int", "int"] },
    { "args": ["int"] }
  ]
}

Stack Traces

Control stack trace depth with maxFrames:

{
  "class": "javax.crypto.Cipher",
  "method": "doFinal",
  "maxFrames": 10
}

Native Hooks

Native hooks intercept C/C++ functions. Set native: true and specify the symbol.

Basic Native Hook

{
  "native": true,
  "symbol": "open",
  "module": "libc.so"
}

Argument Descriptors

Define how arguments should be captured:

{
  "native": true,
  "symbol": "write",
  "module": "libc.so",
  "args": [
    { "name": "fd", "type": "int32" },
    { "name": "buf", "type": "bytes", "length": 256 },
    { "name": "count", "type": "int32" }
  ]
}

Dynamic Length from Another Argument

Use lengthInArg to read length from another argument:

{
  "native": true,
  "symbol": "send",
  "module": "libc.so",
  "args": [
    { "name": "sockfd", "type": "int32" },
    { "name": "buf", "type": "bytes", "lengthInArg": 2 },
    { "name": "len", "type": "int32" },
    { "name": "flags", "type": "int32" }
  ]
}

Capture Return Values

Set returnValue: true on the last argument:

{
  "native": true,
  "symbol": "read",
  "module": "libc.so",
  "args": [
    { "name": "fd", "type": "int32" },
    { "name": "buf", "type": "bytes", "lengthInArg": 2 },
    { "name": "count", "type": "int32" },
    { "name": "result", "type": "int32", "returnValue": true }
  ]
}

Outbound Parameters

Use direction: "out" for output parameters that should be read after the function returns:

{
  "native": true,
  "symbol": "CCCrypt",
  "module": "libcommonCrypto.dylib",
  "args": [
    { "name": "op", "type": "int32" },
    { "name": "alg", "type": "int32" },
    { "name": "dataOut", "type": "bytes", "length": 256, "direction": "out" },
    { "name": "dataOutMoved", "type": "pointer", "direction": "out" }
  ]
}

Filter by Value

Only capture events when arguments match specific values:

{
  "native": true,
  "symbol": "open",
  "module": "libc.so",
  "args": [
    { "name": "pathname", "type": "string", "filter": ["/data/", "/sdcard/"] }
  ]
}

Filter by Stack Trace

Only capture events when the call stack contains specific patterns:

{
  "native": true,
  "symbol": "SSL_write",
  "module": "libssl.so",
  "filterEventsByStacktrace": ["com.example.network", "okhttp3"]
}

Debug Mode

Enable verbose logging for troubleshooting:

{
  "native": true,
  "symbol": "problematic_function",
  "module": "libfoo.so",
  "debug": true
}

Argument Types

Type	Description
string	Null-terminated C string
int32	32-bit signed integer
uint32	32-bit unsigned integer
int64	64-bit signed integer
pointer	Memory address
bytes	Raw bytes (requires length or lengthInArg)
bool	Boolean value
double	64-bit floating point
CFData	iOS CFData object
CFDictionary	iOS CFDictionary object

iOS Objective-C Hooks

Hook Objective-C methods using objClass and symbol:

{
  "native": true,
  "objClass": "NSURLSession",
  "symbol": "dataTaskWithRequest:completionHandler:"
}

Output Format

Events are written to the output file in JSON Lines format (one JSON object per line, know as NDJSON). You can easily pretty-print it e.g. using jq . output.json.

Example event (pretty-printed for clarity):

{
    "id": "0117229c-b034-4676-ba33-075fc27922ba",
    "type": "hook",
    "category": "STORAGE",
    "time": "2026-01-18T16:17:25.470Z",
    "class": "android.app.SharedPreferencesImpl$EditorImpl",
    "method": "putString",
    "instanceId": 268282727,
    "stackTrace": [
        "android.app.SharedPreferencesImpl$EditorImpl.putString(Native Method)",
        "androidx.security.crypto.EncryptedSharedPreferences$Editor.putEncryptedObject(EncryptedSharedPreferences.java:389)",
        ...
    ],
    "inputParameters": [
        {
            "declaredType": "java.lang.String",
            "value": "AQMRC7OWD6/h1iJseuzJVrClpwKE8swB8gOrGnsdaN4="
        },
        {
            "declaredType": "java.lang.String",
            "value": "AX4R5MZu+J1p0U3hvKyuEnJDQopI+wupiSi8CAG8dzq0PU76NbbebjhqMtqCD7fFUy2SmmQuQVDlDrrj30d3GQes+PlD8HmRFszVTge039GQ"
        }
    ],
    "returnValue": [
        {
            "declaredType": "android.content.SharedPreferences$Editor",
            "value": "<instance: android.content.SharedPreferences$Editor, $className: android.app.SharedPreferencesImpl$EditorImpl>",
            "runtimeType": "android.app.SharedPreferencesImpl$EditorImpl",
            "instanceId": "268282727",
            "instanceToString": "android.app.SharedPreferencesImpl$EditorImpl@ffdab67"
        }
    ]
}