Wall of Flippers
🐬 A simple and easy way to find Flipper Zero Devices and Bluetooth Low Energy Based Attacks 🐬
🐬 Local project documentation for BLE monitoring and analysis 🐬
Project Maintainer
|
Contributor
|
🐬 Table of Contents
- [Introduction](#doc_introduction)
- [Features](#doc_features)
- [Videos](#doc_videos)
- [Install Guide](#doc_install) - [How to install](#install_guides) - [Debian Linux Install](#debian_install) - [Fedora Install](#fedora_install) - [macOS Install](#macos_install) - [Arch Linux Install (SOON)](#arch_install) - [Windows Install](#windows_install)
- [Run Backend and Frontend](#run_backend_frontend)
- [Headless Usage](#headless_usage)
- [Runtime Config](#runtime_config)
- [Architecture](#architecture)
- [Issues and Fixes](#doc_issues_and_fixes)
- [Common Errors and Fixes](#doc_c_and_e)
- [Related Projects](#doc_related)
- [Notice](#doc_statement)
# 🐬 Wall of Flippers?
# 🐬 Current features and future updates
- [x] Discover Flipper Zero Devices (Bluetooth must be enabled)
- [x] Flipper Name Discovery
- [x] Flipper Address Discovery
- [x] Flipper "Identifier" Discovery ( Transparent, White, & Black Flipper Detection)
- [ ] Spoof Detection (Coming Soon)
- [x] Ability to archive past flipper zero devices discovered
- [x] Auto-install functionality for Debian Linux and Windows
- [x] Ability to identify potential Bluetooth Advertisement attacks
- [x] Suspected Advertisement Attacks
- [x] ~iOS Crash Advertisement Attack~
- [x] iOS Popup Advertisement Attacks
- [x] Samsung and Android BLE Advertisement Attacks
- [x] Windows Swift Pair Advertisement Attacks
- [x] LoveSpouse Advertisement Attacks (Denial of Pleasure)
- [x] BT Settings Flood
- [x] Bluetooth Remote Detection
- [x] BLE Advertiser (Detect other WoF Instances)
- [x] Custom Name Implementation
- [x] BLE Chat
- [x] Badge Mode (Less fancy stats)
- [x] BLE External / Internal Adapter Support
- [x] Linux Supported
- [ ] Windows Supported
- [x] Ratelimiting (New Connections)
- [x] Linux Supported
- [x] Windows Supported (Limited)
- [x] Runtime config via JSON for scan and offline thresholds
- [ ] Chromium Web Bluetooth Support
- [ ] iOS/Android Detection (Pairing)
- [ ] Animations (Looking for ascii artists)
# 🐬 Articles
Talking Sasquach - Wall of Flippers Busts Flipper Zero BLE Spammers Red Handed!
|
BleepingComputer - ‘Wall of Flippers’ detects Flipper Zero Bluetooth spam attacks
|
# 🐬 Installing and Requirements
## How to install
# 🐬 Run Backend and Frontend
## Run Backend
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -r requirements.txt
python3 run_web.py
Backend default:
`http://127.0.0.1:8787`
Untuk akses dari device lain di jaringan lokal:
python3 run_web.py --host 0.0.0.0 --port 8787
## Run Frontend
cd web-frontend
npm install
npm run dev
Frontend default:
`http://127.0.0.1:5173`
Debian Linux Install Guide
### Debian Linux Install Guide
### Step 1 (One): Full system upgrade / update
sudo apt-get update && sudo apt-get upgrade -y
### Step 2 (Two): Git Clone and Git Installiation
sudo apt-get install git
cd /path/to/Wall-of-Flippers
### Step 3 (Three): Installing python (python3)
sudo apt-get install python3
sudo apt-get install python3-dev
### Step 4 (Four): Setting up and Installing the required packages (Multiple Ways)
sudo apt-get install libglib2.0-dev
sudo apt-get install python3-bluez
python3 -m venv .venv
source .venv/bin/activate
################## PACKAGES ######################## # requirement.txt method
python3 -m pip install -r requirements.txt # command method
python3 -m pip install bluepy
python3 -m pip install pybluez
################## PACKAGES ########################
deactivate
bash wof.sh
# You should get a prompt upon startup, about setting up a managed environment, feel free to let it do for you. Then once an environemnet is complete run `wof.sh` again
and use the auto install option to install the dependencies.
### Step 5 (Five): Running Wall of Flippers
bash wof.sh
sudo chmod +x WallofFlippers.py
./WallofFlippers.py
Fedora Linux Install Guide
### Fedora Install Guide
### Step 1 (One): Full system upgrade / update
sudo dnf update && sudo dnf upgrade -y
### Step 2 (Two): Git Clone and Git Installiation
sudo dnf install git
cd /path/to/Wall-of-Flippers
### Step 3 (Three): Installing python (python3)
sudo dnf install python3
sudo dnf install python3-dev
### Step 4 (Four): Setting up and Installing the required packages (Multiple Ways)
sudo dnf install glib2-devel
sudo dnf install python3-bluez
python3 -m venv .venv
source .venv/bin/activate
################## PACKAGES ######################## # requirement.txt method
python3 -m pip install -r requirements.txt # command method
python3 -m pip install bluepy
python3 -m pip install pybluez
################## PACKAGES ########################
deactivate
bash wof.sh
# You should get a prompt upon startup, about setting up a managed environment, feel free to let it do for you. Then once an environemnet is complete run `wof.sh` again
and use the auto install option to install the dependencies.
### Step 5 (Five): Running Wall of Flippers
bash wof.sh
sudo chmod +x WallofFlippers.py
./WallofFlippers.py
macOS Install Guide
## macOS Install Guide
### Step 1 (One): Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate
### Step 2 (Two): Install dependencies
python3 -m pip install -r requirements.txt
### Step 3 (Three): Run Wall of Flippers
python WallofFlippers.py --wall
Windows Install Guide
## Windows Install Guide
### Step 1 (One): Git Clone and Git Installiation
cd /path/to/Wall-of-Flippers
### Step 2 (Two): Installing python and pip (python / pip)
pip install bleak
pip install -r requirements.txt
python WallofFlippers.py
# You should get a prompt upon startup, use the auto install option to install the dependencies. for the easy install and follow the directions and prompts for the install.
### Step 3 (Three): Running Wall of Flippers
python WallofFlippers.py
# Headless Usage
usage: WalloFlippers.py [-h] [-w] [i] [-d DEVICE]
options:
-h, --help Help Message
-w, --wall Wall of Flippers
-i, --install Install Dependencies
-b, --badgemode Toggle Badge Mode
-a, --advertise Advertise WoF Exsistance (OFF=Default)
-d DEVICE, --device DEVICE A bluetooth device (External/Internal)
# Issues and Fixes
# Common Errors and Fixes
### No such file or directory /sys/class/bluetooth
sudo service bluetooth status
sudo service bluetooth restart
### pybluez failing to properly install
# Related Projects
**Pwnagotchi plugin**\
_Written by: cyberartemio_\
wof-pwnagotchi-plugin
**Evil-M5Core2**\
_Written by: 7h30th3r0n3_\
Evil-M5Core2
# Notice
# 🐬 Runtime Config
Runtime tuning sekarang bisa diatur dari:
`config/wof.defaults.json`
Atau dengan file custom:
python WallofFlippers.py --wall --config /path/to/custom.json
Contoh parameter yang bisa diubah:
- `bleak_scan_timeout`
- `offline_miss_threshold`
- `offline_hold_seconds`
- `ble_tx_power_dbm`
- `ble_path_loss_n`
- `rssi_history_max_points`
- `rssi_history_max_devices`
- `max_online`
- `max_offline`
- `ble_threshold`
Structured events untuk automation/debug juga bisa diaktifkan:
python WallofFlippers.py --wall --jsonl
Contoh event:
- `startup`
- `scan_started`
- `scan_completed`
- `device_seen_strong`
- `device_seen_soft`
- `device_online`
- `device_offline`
# 🐬 Architecture
Struktur project yang dikustomisasi di workspace ini sekarang sudah lebih modular:
- `WallofFlippers.py`
Entry point CLI dan loop utama aplikasi.
- `utils/wof_engine.py`
Orchestration satu siklus scan live.
- `utils/wof_scanner.py`
Abstraksi scan BLE untuk macOS/Linux.
- `utils/wof_detection.py`
Parsing packet dan klasifikasi Flipper.
- `utils/wof_presence.py`
State machine online/offline dan `missed_scans`.
- `utils/wof_storage.py`
Storage SQLite dan metadata lokasi lokal scanner.
- `utils/wof_library.py`
Helper/UI layer untuk ASCII rendering, terminal selection, dan persistence logging ringan.
- `utils/wof_display.py`
Render dashboard terminal live.
- `utils/wof_trust.py`
Trust scoring deteksi.
- `utils/wof_rssi_geo.py`
Estimasi jarak kasar dari RSSI.
- `utils/wof_rssi_history.py`
Histori tren RSSI per device.
- `utils/wof_config.py`
Load runtime config JSON.
- `utils/wof_events.py`
Structured event emission untuk automation/debug.
- `utils/wof_logging.py`
File logging ke `logs/wof.log`.
Storage runtime utama sekarang memakai:
`data/flippers.db`
