octopus.frida.instrument_gated

class octopus.frida.instrument_gated.FridaGatedInstrumentation(frida_device, capture_manager)

Bases: Thread

Thread that manages Frida-based gated instrumentation of spawned processes.

Uses Frida’s spawn gating mechanism to intercept newly spawned processes, attach to them, inject an agent script, and invoke tracing APIs before resuming execution.

pending

List of spawned processes waiting to be instrumented.

sessions

List of active Frida sessions for instrumented processes.

scripts

List of loaded Frida scripts for instrumented processes.

event

Threading event used to signal new pending spawns.

__init__(frida_device, capture_manager)

Initialize the instrumentation thread.

Parameters:

• frida_device (object) – The Frida device to attach and enable spawn gating on.

• capture_manager (object) – Manager responsible for capturing intercepted data.

run()

Entry point for the instrumentation thread.

Delegates to start_instrumentation().

start_instrumentation()

Enable spawn gating and instrument each intercepted process.

Enables Frida spawn gating on the target device, then enters a loop waiting for new spawns. For each spawn with a known identifier, it attaches a Frida session, loads the agent script, invokes available tracing APIs, and resumes the process.

stop()

Signal the instrumentation loop to stop gracefully.

event = <threading.Event at 0x7f5ef6f48380: unset>

Event signaled when a new spawn is added to the pending list.

pending = []

List of spawned processes pending instrumentation.

scripts = []

List of loaded Frida script instances.

sessions = []

List of active Frida attach sessions.

octopus.frida.instrument_gated.on_message(capture_manager, spawn, message, script)

Handle messages received from an injected Frida script.

Processes control messages (e.g. offset_hooking, pattern_hooking) by posting the appropriate response back to the script. Captures data payloads via the capture manager, with special handling for friTap SSL keylog data.

Parameters:

• capture_manager (object) – Manager responsible for capturing and storing data.

• spawn (object) – The spawn object associated with the instrumented process.

• message (dict) – The message dict received from the Frida script.

• script (object) – The Frida script instance used to post responses.

octopus.frida.instrument_gated.on_spawned(spawn)

Handle a newly spawned process detected by Frida’s spawn gating.

Appends the spawn to the pending list and signals the instrumentation thread to process it.

Parameters:

spawn (object) – The spawn object provided by Frida containing process info.