Metadata-Version: 2.4
Name: pirogue-octopus
Version: 1.0.1
Summary: Dynamic analysis framework for Android apps.
Author-email: U+039b <hello@pts-project.org>
Maintainer-email: U+039b <hello@pts-project.org>
License-Expression: GPL-3.0-or-later
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Requires-Dist: click==8.1.3
Requires-Dist: frida-tools==14.3
Requires-Dist: frida==17.2.2
Requires-Dist: libusb1==2.0.1
Requires-Dist: pure-python-adb>=0.3.0.dev0
Requires-Dist: requests==2.28.1
Description-Content-Type: text/markdown

<!--
SPDX-FileCopyrightText: 2026 Defensive Lab Agency
SPDX-FileContributor: u039b <git@0x39b.fr>

SPDX-License-Identifier: GPL-3.0-or-later
-->

<div align="center">
<img width="60px" src="https://pts-project.org/android-chrome-512x512.png">
<h1>Octopus</h1>
<p>
Dynamic analysis framework for Android apps.
</p>
<p>
<img src="https://img.shields.io/badge/License-GPL_v3-8A2BE2">
</p>
<p>
<a href="https://pts-project.org">Website</a> |
<a href="https://pts-project.org/octopus/">Documentation</a> |
<a href="https://github.com/PiRogueToolSuite/octopus">GitHub</a> |
<a href="https://discord.gg/qGX73GYNdp">Support</a>
</p>
</div>

# Octopus
Octopus is a dynamic analysis framework for Android applications, part of the
[PiRogue Tool Suite](https://pts-project.org). It instruments Android app behavior
using [Frida](https://frida.re) 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](https://github.com/fkie-cad/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
```bash
pip install pirogue-octopus
```

## Usage
The main entry point is the `octopus` CLI.

```bash
# 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:
```bash
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`)

```bash
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.

```bash
octopus instrument tcp --device-host <DEVICE_IP>
```

## Development
It is recommended to use [uv](https://github.com/astral-sh/uv) for managing the Python environment.

1.  Clone the repository:
    ```bash
    git clone https://github.com/PiRogueToolSuite/octopus.git
    cd octopus
    ```

2.  Install Python dependencies:
    ```bash
    uv sync
    ```

3.  Install Node.js dependencies and build Frida agents:
    ```bash
    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.
