octopus.android.device

class octopus.android.device.AndroidDevice(adb_device)[source]

Bases: object

Represents an Android device and provides methods for device management.

This class encapsulates operations such as rooting, property retrieval, and Frida server management for an Android device.

adb: Instance of ADB used for device communication.

is_root: Indicates if the device is running as root.

requires_su: Indicates if su access is required for root operations.

rooted: Indicates if the device is rooted or has su access.

adb_device: The connected ADB device instance.

__init__(adb_device)[source]

Initializes the AndroidDevice instance.

Connects to the device using the provided ADB instance, attempts to root the device, checks root status, and verifies Frida server installation.

Parameters:: adb – An instance of ADB for device communication.

adb_pull(device_path, local_path)[source]

Pulls a file from the device to the local system.

Parameters:

device_path – Path to the file on the device.
local_path – Destination path on the local system.

Raises:

Exception – If the pull operation fails.

Uses the ADB pull method to transfer files.

adb_push(local_path, device_path)[source]

Pushes a file from the local system to the device.

Parameters:

local_path – Path to the local file.
device_path – Destination path on the device.

Raises:

Exception – If the push operation fails.

Uses the ADB push method to transfer files.

adb_shell(command)[source]

Executes a shell command on the device via ADB.

Parameters:: command – The shell command to execute.
Returns:: The output of the shell command as a string.
Raises:: Exception – If the command execution fails.
Return type:: str

Uses su if root access is required and sets timeout=30.

adb_shell_nohup(command)[source]

Executes a shell command on the device without waiting for output.

Parameters:: command – The shell command to execute.

Uses su if root access is required. Opens the shell command with short timeouts for non-blocking execution.

check_frida_server_installed()[source]

Checks if the Frida server binary is installed on the device.

Returns:: True if the Frida server binary exists, False otherwise.
Return type:: bool

Uses the ls command to verify the presence of the Frida server binary.

check_frida_server_running()[source]

Checks if the Frida server process is running on the device.

Returns:: True if the Frida server is running, False otherwise.
Return type:: bool

This method uses the ps command to search for the Frida server process.

get_device_properties()[source]

Retrieves key properties and identifiers from the Android device.

Returns:: A dictionary containing device properties such as fingerprint, brand, device, manufacturer, model, name, serial number, Android version, API level, and IMEI.
Return type:: Dict[str, str]

Notes

Uses the get_property() method to fetch system properties. IMEI is retrieved using a shell command that parses the output of service call iphonesubinfo. Handles missing or empty property values gracefully.

get_frida_device()[source]

Return type:: Device

get_frida_server_version()[source]

Retrieves the version of the installed Frida server.

Returns:: The version string of the Frida server, or ‘0.0.0’ if not found.
Return type:: str

Executes the Frida server binary with the –version flag.

get_property(key)[source]

Retrieves a system property from the device.

Parameters:: key (str) – The property key to retrieve.
Returns:: The value of the system property as a string.
Return type:: str

Uses the getprop shell command.

get_tcpdump_version()[source]

install_frida_server(version=None)[source]

Installs the Frida server binary on the device.

Downloads the specified version of the Frida server binary, pushes it to the device, and sets the executable permission. Uses a temporary file for the download.

Parameters:: version (str | None) – The version of the Frida server to install. Defaults to the currently installed frida Python package version.

install_tcpdump()[source]

is_rooted()[source]

Checks if the device is rooted.

Returns:: True if the device is rooted or has su access, False otherwise.
Return type:: bool

root()[source]

Attempts to root the Android device using ADB.

Raises:: RuntimeError – If root access is disabled on the device.

Uses the internal ADB service to request root access. If the device is not already running as root, attempts to reconnect.

start_frida_server(force_stop=True)[source]

Starts the Frida server on the device if it is not already running.

Parameters:: force_stop (bool) – Forces stopping the Frida server before starting it.

If the server is already running, just logs an informational message. Otherwise, starts the server in daemon mode.

stop_frida_server()[source]

Stops the Frida server process on the device.

Uses the pkill command to terminate the Frida server process.

property architecture[source]

device_tmp_dir = PosixPath('/data/local/tmp')

property system_properties: Dict[str, Any][source]

class octopus.android.device.AndroidDeviceTcp(host, port=5555, adb_host='127.0.0.1', adb_port=5037)[source]

Bases: AndroidDevice

Android device connected via TCP/IP.

Inherits from AndroidDevice and initializes the device using a ADB instance configured for TCP/IP communication.

__init__(host, port=5555, adb_host='127.0.0.1', adb_port=5037)[source]

Initializes an AndroidDeviceTcp instance.

Parameters:

host (str) – The IP address or hostname of the device.
port (int) – The TCP port for ADB connection, defaults to 5555.
adb_host – Optional ADB host address, defaults to 127.0.0.1.
adb_port – Optional ADB port number, defaults to 5037.

get_frida_device()[source]

Return type:: Device

class octopus.android.device.AndroidDeviceUsb(device_id=None, adb_host='127.0.0.1', adb_port=5037)[source]

Bases: AndroidDevice

Android device connected via USB.

Inherits from AndroidDevice and initializes the device using a default ADB instance for USB communication.

__init__(device_id=None, adb_host='127.0.0.1', adb_port=5037)[source]

Instantiate an AndroidDeviceUsb instance.

Connects to an ADB client and selects the appropriate device. If a device_id is provided, connects to that specific device. If only one device is connected, selects it automatically.

Parameters:

device_id (str | None) – Optional ADB device serial number. If omitted and exactly one device is connected, it is selected automatically. Raises RuntimeError if no device can be determined.
adb_host – Optional ADB host address, defaults to 127.0.0.1.
adb_port – Optional ADB port number, defaults to 5037.

Raises:

RuntimeError – If no device is found and device_id is not provided, or if more than one device is connected without specifying a device_id.

get_frida_device()[source]

Return type:: Device