pirogue-octopus 1.0.1

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: 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.