pirogue-octopus 1.0.0

Dynamic analysis framework for Android apps.

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
• Full network capture (on device)
• TLS interception with friTap
• Socket operations tracing
• Cryptographic operations logging

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 (emulator, phone, or tablet)

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

Outputs

• ad_ids.txt: the list of Android Advertising IDs
• device.json: the list of device properties (e.g. IMEI, brand, fingerprint)
• dynamic_hook.json: the output of dynamically injected hooks
• experiment.json: the summary and timings of the capture and instrumentation
• screen.mp4: the screen recording
• socket_trace.json: the trace of every operation on sockets
• sslkeylog.txt: the list of TLS client randoms
• traffic.pcap: the network capture

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.

Frida agent development:

• npm run build: Compile TypeScript agent to JavaScript.
• npm run watch: Continuously compile agent on changes.

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.