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_device (Device) – An instance of PPDevice 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.

am_i_root()[source]

Checks if the current ADB shell user is root.

Runs the whoami command via ADB and checks if the output contains root.

Returns:: True if the current user is root, False otherwise.
Return type:: bool

check_adb_is_available()[source]

Checks if the ADB connection to the device is available.

Attempts to run a simple shell command on the device to verify that ADB communication is functional.

Returns:: True if ADB is available, False if a RuntimeError is raised during the shell command.
Return type:: bool

check_device_is_debuggable()[source]

Checks if the Android device is debuggable.

Retrieves the ro.debuggable system property and checks whether it is set to 1.

Returns:: True if the device is debuggable, False otherwise.
Return type:: bool

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.

check_su_is_available()[source]

Checks if su is available on the device.

Runs a simple command via su and checks if it succeeds.

Returns:: True if su is available, False otherwise.
Return type:: bool

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]

init()[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]

Installs the tcpdump binary on the Android device.

Copies the appropriate tcpdump binary for the device’s architecture from the local assets directory to the device’s temporary directory and sets the executable permission.

Logs the progress and outcome of the installation.

is_ready()[source]

Return type:: bool

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