rea/docs/frida-instrumentation.md

Frida instrumentation

REA exposes Frida device and process discovery, attach or spawn sessions, and caller-authored JavaScript instrumentation through the CLI and MCP. The Node bindings are an optional package dependency and load only when a Frida operation runs. REA does not install Frida server on a target.

For remote devices, pass a host with an optional port (host[:port]; bracket IPv6 addresses) and any token, certificate, origin, or keepalive options on that operation. The keepalive interval is measured in seconds, matching Frida Core 17.23.2. Authentication values are held only for the active call or session and are excluded from Evidence. Do not embed credentials in the endpoint address.

MCP exposes list_frida_devices, list_frida_processes, start_frida_session, load_frida_script, resume_frida_session, unload_frida_script, frida_session_status, and close_frida_session. A spawned process starts paused so scripts can load first. Closing unloads session scripts and detaches. If a spawn remains paused, REA resumes it only after script cleanup or session detach confirms the instrumentation is released; if both cleanup paths fail, the target stays paused and the cleanup error is retained. REA never kills the target. MCP sessions end with the server process. The one-shot CLI command instrument-with-frida accepts one inline script or script file, observes messages for a bounded duration, and returns Evidence with the source hash and captured messages.

For state and capture-coverage checks, pass {"session_id":"SESSION_ID","detail":"summary"} to frida_session_status. Each call reads the observed session state and retains the complete observation. The reply is an inspect_analysis_view Evidence summary with the session identity, state, scripts, messages_retained, and messages_truncated; message payloads remain in its parent_evidence_id. The count covers retained queued messages, not every target event. Omitted detail or detail=complete preserves the existing complete reply.

A summary's selected fields look like this (excerpt):

{
  "summary": {
    "state": "running",
    "messages_retained": 50,
    "messages_truncated": false
  }
}

Use get_evidence_bundle with detail="summary" and filters={"evidence_id":"PARENT_ID"} to discover parent metadata without message payloads. Filters apply only to summary delivery. Use export_evidence_bundle for the complete canonical bundle, then select the record whose evidence_id matches normalized_result.parent_evidence_id from the status summary. To use the existing CLI inspect-analysis-view, extract that record into a standalone Evidence JSON file and select it as an Evidence-file source with view={"kind":"summary"}. Reading retained Evidence does not refresh a live session or verify a process after exit or PID reuse.

Failed startup cleanup retains acquired Frida handles, including a paused spawn that has not attached, for later cleanup retries. Its remote connection stays leased until session detach and target resume complete. CLI commands await provider cleanup before returning; MCP retains these resources for cleanup when its server closes. Server shutdown stops admitting new Frida operations and waits for admitted startup, discovery, and queued work before releasing their resources. A failed cleanup remains reported and can be retried by closing the server again, rather than treating an unregistered session as fully released.

Frida scripts execute inside the selected target with that process's memory, filesystem, and network authority. Local device lookup waits 1000 ms. This release has no runtime override for that lookup; another REA timeout does not raise it. Remote endpoints do not use that lookup. Message capture is bounded to 16 MiB and reports truncation. Metadata, type, and text field caps, and the JSON node cap, are also fixed. Evidence names a cap when that observation actually dropped data. This release has no runtime override for those capture caps. Script source is not stored in Evidence; its selected path and SHA-256 digest are. For a file, source_sha256 identifies the original selected bytes. Invalid UTF-8 continues to use replacement decoding; Evidence then records that limitation and raw_result.source_representation with the encoding, decoding mode, and loaded_source_sha256 of the UTF-8 string passed to Frida. Valid UTF-8 files and inline scripts do not need this additional representation fact. Evidence retains non-authentication target selection such as device or endpoint, mode, program or PID, and spawn arguments. Authentication values remain excluded. Results report the observed session and messages, while unsupported platform metadata remains unknown. A request cancelled before a Frida operation starts has no provider effects. If cancellation arrives during a native Frida call, REA waits for that call to return, then closes any session it created and returns the observed session as a partial observation. A cancelled script load on an existing session releases only its new script before queued operations can run; the session and previously loaded scripts remain available. If cancellation is observed when the native call returns, partial Evidence retains the source identity and captured messages even if that call rejects, including messages emitted during awaited cleanup. The caller's cancellation reason remains primary and a native rejection is retained as a sanitized diagnostic. A failure already observed before cleanup stays primary if cancellation arrives during cleanup. The cancellation cutoff is REA's observation of native completion, rather than a claim about unobservable native event order. script_id is REA's load-attempt identity. When creation rejects without returning a handle, script_cleanup: "no_handle" means REA acquired no handle to unload; it does not prove that the engine performed no work. Once the provider commits a successful load, later request cancellation does not unload that script; use unload_frida_script to release it. If script cleanup fails, the script remains owned and a paused target cannot resume until the pending instrumentation is released. Queued script loads, resumes, and unloads check cancellation before dispatching native effects. Cancellation Evidence separately reports whether a target resume was observed, whether instrumentation cleanup completed, and that final target liveness remains unknown. REA does not kill the target. Remote discovery retains its observations and reports a separate cleanup error if the temporary connection cannot be removed.

The Frida Core API documents device management, sessions, and script loading; the JavaScript API documents target-side instrumentation. Luma is Frida's standalone GUI; REA does not automate or control it. npm run verify:frida requires a Linux host with the optional Frida binding and uses a short-lived local Node.js fixture created by the verifier. Add -- --address HOST:PORT --pid PID to run the separate remote attach lane against a caller-selected target. Mock tests do not establish real device/server compatibility.