Octopus

Dynamic analysis framework for Android apps.

Website | Documentation | GitHub | Support

Octopus

Octopus is a dynamic analysis framework for Android applications, part of the PiRogue Tool Suite. It instruments Android app behavior using Frida and provides the following capabilities:

  • Screen recording: Capture the device screen during analysis.

  • Full network capture: On-device network capture using tcpdump.

  • TLS interception: Decrypt TLS traffic with friTap.

  • Socket tracing: Log all socket operations (connect, read, write).

  • Cryptographic logging: Capture cryptographic keys and operations.

  • API Hooking: Intercept various Android APIs (Advertising IDs, device info, etc.).

Octopus communicates with a running adb-server, either locally or remotely. The target device can be a physical Android phone or an emulator, accessible via USB or TCP.

Requirements

  • Python 3.11 or newer.

  • A rooted Android device (physical phone, tablet, or emulator).

  • ADB installed and accessible on your host.

Installation

pip install pirogue-octopus

Usage

The main entry point is the octopus CLI.

# List available Android devices (local only)
octopus device list

# Start instrumentation over USB
octopus instrument usb

# Start instrumentation over network
octopus instrument tcp --device-host <DEVICE_IP>

Octopus instruments processes when they spawn. To instrument an application, start octopus then launch the application to be analyzed when Octopus is Waiting for data. Press CTRL + C to stop.

Common options for instrument:

  • -o, --output-path: directory to save capture results (default: ./output).

  • -d, --device-id: serial number of the device connected to ADB (USB mode only).

  • -ns, --no-screen-record: disable screen recording.

  • -ni, --no-instrumentation: disable Frida instrumentation.

  • -nn, --no-network-capture: disable network capture.

  • --duration: capture duration in seconds to wait before it’s automatically stopped (default: unlimited).

  • -w, --overwrite: to overwrite the output files.

  • --log-level: set the logging level (DEBUG, INFO, WARNING, ERROR).

Example with more options:

octopus --log-level DEBUG instrument usb --output-path ./my_analysis --duration 60 --overwrite

Outputs

All outputs are saved in the directory specified by -o (default: ./output).

  • ad_ids.txt: List of Android Advertising IDs (AAID) intercepted.

  • device.json: Comprehensive device properties (IMEI, brand, fingerprint, Android version, etc.).

  • dynamic_hook.json: Data from dynamically injected Frida hooks.

  • experiment.json: Summary metadata of the capture session, including timings and component status.

  • screen.mp4: Video recording of the device screen.

  • socket_trace.json: Detailed trace of all socket operations (TCP/UDP).

  • sslkeylog.txt: TLS master secrets in NSS Key Log format (used for decrypting traffic.pcap in Wireshark).

  • traffic.pcap: Full network traffic capture in PCAP format.

Remote ADB server

The following options let you specify the ADB server to use:

  • -ah, --adb-host: ADB server IP address (default: 127.0.0.1)

  • -ap, --adb-port: ADB server port (default: 5037)

octopus device list --adb-host 127.0.0.1 --adb-port 5037

Remote Android device

The following options let you specify the device to use:

  • -dh, --device-host: device IP address

  • -dp, --device-port: device port (default: 5555)

ADB over network must be enabled.

octopus instrument tcp --device-host <DEVICE_IP>

Development

It is recommended to use uv for managing the Python environment.

  1. Clone the repository:

    git clone https://github.com/PiRogueToolSuite/octopus.git
cd octopus

  2. Install Python dependencies:

    uv sync

  3. Install Node.js dependencies and build Frida agents:

    npm install
npm run build

Scripts

The project uses tox for automation:

  • tox -e fix: Format code using Ruff and run pre-commit hooks.

  • tox -e docs: Generate HTML documentation.

  • tox -e servedocs: Serve documentation with live reload.

Frida agent development:

  • npm run build: Compile TypeScript agent to JavaScript.

  • npm run watch: Continuously compile agent on changes.

  • npm run lint: Run ESLint on the TypeScript source.

Project Structure

  • octopus/: Core Python package.

    • capture/: Modules for device, network, screen, and Frida management.

    • commands/: CLI command definitions.

    • frida/: Frida instrumentation logic.

  • frida-scripts-src/: TypeScript source for Frida agents.

  • debian/: Debian packaging configuration.

License

This project is licensed under the GPL-3.0-or-later. See the LICENSES directory for details.