octopus.capture.frida

class octopus.capture.frida.FridaCapture(device, output_dir, gated=True, debug=False)

Bases: AbstractCapture

Captures data from an Android device using Frida instrumentation.

Manages Frida scripts, dynamic hooks, and data collection during an instrumentation session on a connected Android device.

device

The Android device to instrument.

output_dir

Directory where captured data files are saved.

gated

Whether to use gated instrumentation.

debug

Whether to enable debug mode (e.g., write the agent script to disk).

dynamic_hook_dir

Path to the directory containing dynamic hook JSON definitions.

frida_scripts_dir

Path to the directory containing Frida JS scripts.

output_files

Mapping of output filenames to their captured records.

captured_data

Mapping of data types to their output file metadata.

agent_script

The concatenated Frida agent JS script content.

frida_instrumentation

The FridaGatedInstrumentation instance managing the Frida session.

__init__(device, output_dir, gated=True, debug=False)

Initializes FridaCapture with device and output configuration.

Parameters:

• device (AndroidDevice) – The Android device to capture data from.

• output_dir (Path) – Directory path where output files will be written.

• gated (bool) – Whether to use gated instrumentation mode. Defaults to True.

• debug (bool) – Whether to enable debug output, such as writing the agent script to a temporary file. Defaults to False.

capture_data(data)

Processes and stores a single data record received from Frida.

Handles console log messages for debug output and accumulates data records into self.output_files keyed by their target filename. Records without a dump field are ignored.

Parameters:

data – A dict payload sent by the Frida agent, expected to contain keys such as contentType, dump, type, and data.

get_agent_script(extra_scripts_dir=None, reload=False)

Builds and returns the concatenated Frida agent JS script.

Reads all .js files from the default Frida scripts directory and optionally from an additional directory. The result is cached in self.agent_script and can be reloaded by setting reload=True.

When debug mode is enabled, the assembled script is also written to /tmp/octopus_agent.js for inspection.

Parameters:

• extra_scripts_dir (Path) – Optional path to a directory containing additional JS scripts to append to the agent.

• reload (bool) – If True, forces regeneration of the script even if it was previously built. Defaults to False.

Returns:

The full Frida agent script as a string.

get_dynamic_hooks_definitions()

Loads all dynamic hook definitions from JSON files.

Iterates over all .json files in the dynamic hooks directory and aggregates their contents into a single list.

Returns:

A tuple of (hook_definitions, success) where hook_definitions is a list of hook definition dicts and success is False if no hook files were found, True otherwise.

get_output_file()

Not applicable for Frida captures.

Raises:

Exception – Always raised as this method is not applicable for this capture type.

Return type:

Path

get_result()

Retrieve the result of the capture.

Returns:

The result data from the capture.

Return type:

dict

save_data_files()

Writes all captured data records to their respective output files.

Iterates over self.output_files and serializes each collection of records. JSON records are pretty-printed; other records are written one per line using their data field.

start_capture()

Starts the Frida capture session on the device.

Disables USAP pool pre-forking on Android 10+ (API 29) to ensure Frida can attach correctly, starts the Frida server on the device, and begins instrumentation.

stop_capture()

Stops the Frida capture session and persists collected data.

Stops the instrumentation, shuts down the Frida server on the device, and flushes all captured data to disk with save_data_files().

name: str = 'frida'

Name identifier for the capture instance.