FlipperDroid/research.md

# 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