Initial commit — FlipperDroid v0.1.0-poc
KernelSU module + Flipper Zero FAP that bridges both devices into a unified pentesting platform over USB CDC serial / BT rfcomm. Android side: bridge daemon, WebUI (:8089), bind mount namespace isolation stealth engine. Flipper side: proper FAP with 4-view GUI, GPIO/SubGHz/IR/file command handlers, async event streaming.
This commit is contained in:
sssnake
116
README.md
Normal file
116
README.md
Normal file
@@ -0,0 +1,116 @@
|
||||
# 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.
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user