heap_search
Find live Java class instances in the heap of an Android device by specifying the class name and maximum results. Enables runtime inspection of objects for security analysis.
Instructions
Search Java heap for live instances of a class
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| class_name | Yes | Full Java class name (e.g., 'java.security.Key') | |
| max_results | No | Max instances to return (default: 10) |
Implementation Reference
- agent/agent.js:367-395 (handler)The JavaScript Frida agent implementation that uses Java.choose() to enumerate live Java heap instances of a class, collecting their handle, toString(), and class name up to maxResults.
heapSearch(className, maxResults) { if (!Java.available) { throw new Error("Java runtime not available"); } const results = []; const limit = maxResults || 10; Java.performNow(() => { try { Java.choose(className, { onMatch(instance) { if (results.length < limit) { const info = { handle: instance.$h || instance.toString() }; try { info.toString = instance.toString(); } catch (e) {} try { info.class = instance.getClass().getName(); } catch (e) {} results.push(info); } }, onComplete() {} }); } catch (e) { results.push({ error: e.message }); } }); return { instances: results }; }, - src/frida_mcp/android.py:61-64 (handler)Python handler that gets the active Frida RPC API and calls the heap_search RPC method (which maps to the JS agent's heapSearch), with a 10-second timeout.
def heap_search(class_name: str, max_results: int = 10) -> dict: """Search Java heap for instances of a class.""" api = get_api() return with_timeout(lambda: api.heap_search(class_name, max_results), timeout=10) - src/frida_mcp/tools.py:329-340 (schema)MCP tool schema definition for heap_search, declaring the input schema (class_name required, max_results optional with default 10) and description.
Tool( name="heap_search", description="Search Java heap for live instances of a class", inputSchema={ "type": "object", "properties": { "class_name": {"type": "string", "description": "Full Java class name (e.g., 'java.security.Key')"}, "max_results": {"type": "integer", "description": "Max instances to return (default: 10)"}, }, "required": ["class_name"], }, ), - src/frida_mcp/server.py:96-97 (registration)Tool dispatch in the server's call_tool function that routes the 'heap_search' tool name to android.heap_search(), passing class_name from arguments and defaulting max_results to 10.
elif name == "heap_search": return android.heap_search(arguments["class_name"], arguments.get("max_results", 10))