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.

Supported SSL/TLS implementations

Library	Apps Using It
BoringSSL/OpenSSL	Chrome, most Google apps
Conscrypt	Android system, many apps
GnuTLS	Some native apps
WolfSSL	IoT/embedded apps
mbedTLS	Embedded/IoT apps
NSS	Firefox, Mozilla apps
Cronet	Chrome-based networking
Flutter	Flutter applications
S2N-TLS	AWS SDK apps
Rustls	Rust-based apps
Go TLS	Go applications
BouncyCastle/Spongycastle	Java crypto apps
Mono BTLS	Xamarin/.NET apps
MetaRTC	WebRTC applications
Java TLS	Pure Java apps

Find more details in friTap documentation.

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
# or
uv tool 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>

Use uv tool run --from pirogue-octopus octopus when installed with uv.

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.