FlipperDroid/README.md

# FlipperDroid

**Status: Proof of Concept / Work in Progress**

FlipperDroid is a KernelSU-Next module that bridges a Flipper Zero and an Android phone into a unified pentesting platform. Both devices share resources — the phone gets full access to the Flipper's GPIO, SubGHz radio, NFC, RFID, IR, and iButton hardware, while the Flipper can offload compute-heavy tasks to the phone's CPU.

THIS PRODUCT IS A PROOF OF CONCEPT ONLY

## Architecture

Two daemons, one on each device, communicate over USB CDC serial (or Bluetooth rfcomm). A binary protocol handles command/response and async event streaming.

```
┌─────────────────────┐     USB CDC / BT Serial     ┌──────────────────────┐
│   Android (Phone)   │ ◄═══════════════════════════► │   Flipper Zero       │
│                     │                               │                      │
│  flipperdroidd      │   Binary protocol v0.1        │  FlipperDroid Bridge │
│  (bridge daemon)    │   ─ Commands (phone→flipper)  │  (FAP daemon)        │
│                     │   ─ Responses                 │                      │
│  flipperdroid-webui │   ─ Async events (flipper→)   │  Direct HAL access:  │
│  (WebUI :8089)      │   ─ CPU offload requests      │  ─ GPIO              │
│                     │                               │  ─ CC1101 (SubGHz)   │
│  fd-stealth         │                               │  ─ ST25R3916 (NFC)   │
│  (namespace isolat) │                               │  ─ 125kHz RFID       │
│                     │                               │  ─ IR TX/RX          │
│  Exposes Flipper HW │                               │  ─ iButton           │
│  as local resources │                               │  ─ SD card storage   │
└─────────────────────┘                               └──────────────────────┘
```

## What Works (PoC)

- USB device discovery (VID:PID 0483:5740)
- Bluetooth fallback via rfcomm
- Binary framed protocol with CRC8
- GPIO read/write/init over bridge
- SubGHz frequency set, TX, RX with async event streaming
- IR transmit (NEC, Samsung, RC5, RC6, SIRC, Kaseikyo)
- File operations on Flipper SD card
- System status (battery, temp, uptime)
- Connection monitoring with auto-reconnect
- WebUI with tabs for GPIO, SubGHz, NFC/RFID, IR, Stealth, and live events
- CPU sharing framework (Flipper offloads to phone)
- Stealth via bind mount namespace isolation

## Stealth

FlipperDroid uses bind mount namespace isolation to remain invisible to the system. Nothing on the stock filesystem is modified — dm-verity passes, Play Integrity passes, banking apps see a stock device.

**How it works:**
1. Stock files stay at their real paths, completely untouched.
2. Our custom binaries and configs live in `/data/adb/modules/flipperdroid/stealth/`.
3. Metadata (SELinux context, ownership, permissions, timestamps) is cloned from stock targets onto our files — `ls -Z` looks identical.
4. Using `nsenter`, we enter specific process mount namespaces and bind-mount our files. Only that process sees the swap.
5. Every other process on the system sees the untouched stock filesystem.

**Additional protections:**
- WebUI port firewalled to localhost only via iptables
- Config directory hidden with restrictive permissions
- Nothing runs until user is logged in — no early boot traces
- Configurable stealth map (`stealth_map.conf`) for per-process bind mount rules

**Usage:**
```sh
fd-stealth apply      # Apply stealth map + hide device/port
fd-stealth teardown   # Remove all bind mounts
fd-stealth status     # Show active stealth state
fd-stealth hide-dev   # Quick: hide device + port + config
fd-stealth show-dev   # Quick: unhide everything
```

## What's Planned

- Full NFC relay (card data relayed over phone's network)
- RFID read/write/emulate via bridge
- iButton operations
- PWM and ADC over GPIO
- BadUSB script execution via bridge
- SubGHz signal recording/replay library
- Custom Flipper firmware with optimized bridge daemon
- Direct kernel driver for lower latency USB comms

## Requirements

**Android side:**
- KernelSU-Next or Magisk
- USB OTG support
- Android 12+

**Flipper Zero side:**
- Official firmware 0.90+ or compatible custom firmware
- FlipperDroid Bridge FAP installed on SD card

## Installation

**Android:**
Flash `FlipperDroid.zip` through KernelSU-Next module manager.

**Flipper Zero:**
1. Clone the Flipper Zero firmware repo
2. Copy `flipper/` contents to `applications_user/flipperdroid_bridge/`
3. Build: `./fbt fap_flipperdroid_bridge`
4. Copy the resulting `.fap` to Flipper SD: `apps/Tools/`

## Usage

1. Connect Flipper Zero to phone via USB-C OTG cable
2. Launch FlipperDroid Bridge app on Flipper Zero
3. The Android daemon auto-detects and connects
4. Open `http://localhost:8089` in a browser for the WebUI

## Protocol

See `system/etc/flipperdroid/protocol.md` for the full binary protocol specification.

## License

For authorized security research and penetration testing only.