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.
2026-03-31 21:26:58 -07:00
commit be81a92d44
22 changed files with 4191 additions and 0 deletions
--- a/research.md
+++ b/research.md
@@ -0,0 +1,169 @@
+# FlipperDroid Research Notes
+
+## Concept
+
+Fuse a Flipper Zero and Android phone into a single pentesting platform via shared computing.
+Not kernel-level fusion — daemon-based approach on both sides, communicating over USB CDC serial
+or Bluetooth rfcomm.
+
+## Flipper Zero Hardware APIs (from doxygen research)
+
+### FuriHalBus
+- Manages peripheral device init on STM32WB55
+- Three tiers: always-on (DMA, GPIO ports, FLASH), on-demand system (RNG, SPI, I2C, USB, USART), on-demand user (ADC, CRC, timers, SAI)
+- `furi_hal_bus_enable()` / `furi_hal_bus_disable()` / `furi_hal_bus_reset()`
+- Crash if you enable an already-enabled peripheral or disable an already-disabled one
+
+### GPIO
+- 12 usable external pins: PA2, PA3, PA4, PA6, PA7, PB2, PB3, PB13, PB14, PC0, PC1, PC3
+- `furi_hal_gpio_init(pin, mode, pull, speed)`
+- `furi_hal_gpio_write(pin, state)`
+- `furi_hal_gpio_read(pin)` -> bool
+- Modes: Input, OutputPushPull, OutputOpenDrain, Analog
+- All exposed via bridge protocol
+
+### USB CDC
+- Flipper Zero uses STM32 USB as CDC (Virtual COM Port)
+- VID:PID = 0483:5740
+- Firmware provides `furi_hal_cdc_send()` and `furi_hal_cdc_receive()`
+- Channel 0 is normally CLI, can be repurposed for bridge data
+- This is the primary transport — faster and more reliable than BT
+
+### SubGHz (CC1101)
+- Frequency range: 300-348, 387-464, 779-928 MHz
+- `furi_hal_subghz_set_frequency()`, `furi_hal_subghz_tx()`, `furi_hal_subghz_rx()`
+- `furi_hal_subghz_write_packet()`, `furi_hal_subghz_read_packet()`
+- `furi_hal_subghz_get_rssi()` -> float
+- `furi_hal_subghz_is_rx_data_crc_valid()` to check for pending data
+
+### NFC (ST25R3916)
+- 13.56 MHz NFC-A/B/V/F support
+- Complex worker-based API (NfcWorker state machine)
+- Relay mode would be killer — relay card to phone, phone relays over network
+- Requires deep firmware integration, marked for v0.2
+
+### RFID (125 kHz)
+- LF RFID via built-in analog frontend
+- Worker-based API similar to NFC
+- Supports EM4100, HIDProx, Indala, etc.
+
+### IR
+- IR LED TX and IR receiver
+- `infrared_send()` for protocol-based TX
+- Supports NEC, Samsung, RC5, RC6, SIRC, Kaseikyo
+- Raw timing TX/RX also available
+
+### Furi OS
+- Custom RTOS (FreeRTOS-based)
+- `FuriThread` — threads with configurable stack
+- `FuriMutex` — standard mutex
+- `FuriMessageQueue` — message passing
+- `furi_delay_ms()` — thread-safe delay
+- `furi_get_tick()` — system tick counter
+
+### FAP (Flipper Application Package)
+- External apps stored on SD card under `/ext/apps/`
+- Built using `./fbt fap_<appname>` from firmware source
+- `application.fam` manifest defines entry point, dependencies, resources
+- Can access most firmware APIs: GPIO, SubGHz, NFC, RFID, IR, Storage, GUI
+- Stack size configurable (default 2048, we use 4096)
+- External apps run in isolated address space with API table binding
+
+## Android Side
+
+### USB Discovery
+- Flipper Zero appears as USB CDC ACM device
+- VID:PID 0483:5740
+- Shows up as `/dev/ttyACM*`
+- Android needs OTG support and appropriate permissions
+- SELinux rules needed for tty_device access
+
+### Bluetooth Fallback
+- Flipper Zero supports BLE (Bluetooth Low Energy)
+- Serial Profile for data transfer
+- Much slower than USB but works wirelessly
+- rfcomm bind creates `/dev/rfcomm*` device
+
+### Bridge Protocol
+- Binary framed: MAGIC(2) + LEN(2) + CMD(1) + PAYLOAD(N) + CRC8(1)
+- CRC8 using Dallas/Maxim polynomial 0x31
+- Commands 0x01-0x93 (phone -> flipper)
+- Events 0xA0-0xA5 (flipper -> phone, async push)
+- Responses 0xFE (OK) / 0xFF (ERR)
+
+### CPU Sharing
+- Flipper (ARM Cortex-M4 @ 64MHz) can offload to phone (ARM Cortex-X4/A720/A520)
+- Flipper sends workload via event 0xA5
+- Phone executes and returns result via command 0x81
+- Use cases: crypto operations, data processing, pattern matching
+
+## Stealth — Bind Mount Namespace Isolation
+
+### The Problem
+Replacing files on Android is detectable. dm-verity checks block-level hashes, Play Integrity
+checks signatures, banking apps scan for modifications. Any file replacement fails verification.
+
+### The Solution
+Don't replace anything. Use bind mounts in isolated mount namespaces.
+
+Every process on Android has its own "view" of the filesystem. We make two processes look at
+the same path and see different files:
+- Banking app reads a path → sees STOCK file (original hash, original signature)
+- Our daemon reads the same path → sees CUSTOM file via bind mount in its namespace
+
+### How It Works
+1. Stock files stay at their real paths, completely untouched. dm-verity happy.
+2. Custom binaries go in `/data/adb/modules/flipperdroid/stealth/`
+3. We clone ALL metadata from stock onto custom — SELinux context, ownership, permissions,
+   timestamps. Even `ls -Z` looks identical.
+4. Using `nsenter`, we enter the mount namespace of the specific process that needs our
+   file and do a bind mount there. Only that process sees the swap.
+5. Every other process on the system sees the untouched stock file.
+
+### Configuration
+`stealth_map.conf` format:
+```
+# stock_path|custom_filename|target_process|spoof_type
+# spoof_type: process (per-process), global (init ns), hidden (mount empty over path)
+```
+
+### FlipperDroid-Specific Stealth
+- WebUI port (8089) firewalled to localhost via iptables — not visible to port scanners
+- Config directory `/data/adb/flipperdroid` set to 700 + chattr hidden
+- ttyACM device can be hidden from non-bridge processes via stealth map
+- Nothing runs until user login — no early boot traces for DroidGuard to see
+- All stealth fully reversible: `fd-stealth teardown` removes everything cleanly
+
+### What This Means for Detection
+- dm-verity: PASS (no partition modifications)
+- Play Integrity: PASS (no modified system files)
+- Banking apps: PASS (they see stock everything)
+- SafetyNet: PASS (green boot state, locked bootloader appearance)
+
+## Key Decisions
+
+1. **Daemon-based, not kernel-level** — Much simpler PoC, avoids custom kernel builds on both sides
+2. **USB CDC primary, BT fallback** — USB is orders of magnitude faster
+3. **Binary protocol** — More efficient than text/JSON for embedded comms
+4. **FAP not custom firmware** — Can run on stock Flipper firmware, easier distribution
+5. **Shell-based Android daemons** — Matches existing module pattern (RadioControl), works everywhere
+6. **WebUI for control** — Browser-based, no separate app needed
+7. **Namespace isolation stealth** — Bind mounts in per-process namespaces, stock files untouched
+
+## Future Directions
+
+- Custom Flipper firmware with optimized bridge (bypass CLI, direct USB bulk)
+- Android kernel driver (`/dev/flipperdroid`) for zero-copy USB transfers
+- NFC relay over network — relay card from Flipper to remote reader via phone's internet
+- SubGHz signal database — capture, store, replay library
+- Mesh networking — multiple Flipper+Phone pairs working together
+- Integration with Autarch framework for automated pentesting workflows
+- GPIO expansion — use Flipper as I2C/SPI bridge for external hardware
+
+## References
+
+- Flipper Zero Doxygen: https://developer.flipper.net/flipperzero/doxygen/
+- FuriHalBus API: https://developer.flipper.net/flipperzero/doxygen/furi_hal_bus.html
+- Firmware source: https://github.com/flipperdevices/flipperzero-firmware
+- FAP development: https://github.com/flipperdevices/flipperzero-firmware/blob/dev/documentation/AppsOnSDCard.md
+- Awesome Flipper Zero: https://github.com/djsime1/awesome-flipperzero