Sparrow-WiFi

Sparrow-WiFi è uno strumento di consapevolezza spettrale WiFi e Bluetooth a 2.4 GHz e 5 GHz per Linux. Integra scansione WiFi, scoperta Bluetooth Low Energy e Classic, analisi spettrale tramite software-defined radio (HackRF, Ubertooth), tracciamento GPS, rilevamento remoto FAA RemoteID, operazioni remote su droni/rover, e indicizzazione ECS 8.17 in Elasticsearch o OpenSearch in un'unica piattaforma. Scritto interamente in Python 3.

Il progetto include quattro componenti che funzionano autonomamente o insieme:

Sparrow Agent e Sparrow DroneID espongono API REST JSON che permettono ad altre applicazioni di interrogare i risultati delle scansioni, attivare scansioni, recuperare rilevamenti di droni e integrare la consapevolezza wireless/dei droni nei propri flussi di lavoro. L'Elastic Bridge consuma l'API REST dell'agente e produce documenti ECS 8.17 con dashboard Kibana incluse.

Novità (Aprile 2026)

Questa versione include tre miglioramenti significativi rispetto alla versione precedente:

• Sparrow Agent: coalescenza delle scansioni WiFi single-flight. Quando più client HTTP (l'app DroneID, il ponte Elasticsearch, la GUI) colpiscono /wireless/networks/<iface> contemporaneamente, l'agent attivava N chiamate iw scan ridondanti che serializzavano sul lock per interfaccia, moltiplicando la latenza di scansione per il numero di client. La prima richiesta ora è il "leader" che effettua la scansione; le richieste concorrenti attendono su un threading.Event e condividono il risultato del leader. Include anche una correzione TOCTOU nella creazione del lock e sicurezza delle eccezioni sui lock per interfaccia.
• Sparrow DroneID — nuova applicazione web per il rilevamento FAA RemoteID tramite WiFi (ASTM F3411 NAN, IE vendor dei beacon, protocollo DroneID proprietario DJI) e Bluetooth LE (annunci BT4/BT5 Legacy). Include sovrapposizioni geozone, allerte multi-stato con integrazione Slack, esportazione KML, output Cursor-on-Target, indicizzazione opzionale ECS 8.17 verso Elasticsearch / OpenSearch (con un namespace droneid.* personalizzato), e un'interfaccia web reattiva multi-dispositivo. Vedi la sezione Sparrow DroneID qui sotto.
• Ponte Elasticsearch / OpenSearch modernizzato — il ponte sparrow-elastic.py è stato riscritto per produrre documenti ECS 8.17 (era ECS 1.5), ora supporta sia Elasticsearch 8.x che OpenSearch 2.x, avvia automaticamente modelli di indice componibili con politiche del ciclo di vita ILM/ISM e alias di rollover, esegue arricchimento OUI dei vendor e classificazione dei dispositivi basata su regole (con fingerprinting opzionale Fingerbank), e fornisce quattro dashboard Kibana incluse più sei visualizzazioni legacy preservate. Il ponte legacy ECS 1.5 è preservato in legacy/sparrow-elastic.py. Vedi .

Sparrow-WiFi (GUI Desktop)

L'applicazione Sparrow originale fornisce un'interfaccia GUI completa che sostituisce strumenti come inSSIDer e LinSSID, con capacità ben oltre la scansione di base:

• Scansione WiFi — scoperta SSID a 2.4 GHz e 5 GHz, potenza del segnale, utilizzo del canale
• Tracciamento delle sorgenti — Modalità Caccia con frequenza di campionamento elevata e finestre di telemetria per localizzare sorgenti WiFi e Bluetooth
• Analisi spettrale — Sovrapposizioni spettrali in tempo reale a 2.4/5 GHz tramite Ubertooth One o HackRF One
• Bluetooth — Scansione annunci BLE, rilevamento/pubblicazione iBeacon, modalità promiscua Ubertooth per Classic + LE
• Agente remoto — Agente headless (sparrowwifiagent.py) per scansione distribuita, operazioni su droni/rover e distribuzioni su Raspberry Pi
• Integrazione GPS — gpsd, coordinate statiche o MAVLink (GPS drone)
• Mappatura — Visualizzazione su Google Maps / OpenStreetMap dei risultati di scansione con tracce GPS
• Importa/Esporta — CSV, JSON e output grezzo di iw scan
• Elasticsearch / OpenSearch — Indicizzazione conforme a ECS 8.17 dei dati di scansione WiFi e Bluetooth con gestione del ciclo di vita ILM/ISM, classificazione dei dispositivi, fingerprinting opzionale Fingerbank e dashboard Kibana incluse
• Plugin Falcon — Integrazione Aircrack-ng per test di penetrazione (modalità monitor, scoperta SSID nascosti, deauth, cattura WEP/WPA)

Schermate

Sparrow DroneID (Applicazione Web)

Un sistema autonomo basato su web per il rilevamento e tracciamento dei droni che decodifica le trasmissioni di Identificazione Remota (RemoteID) obbligatorie per FAA. Funziona come server HTTP Python con un'interfaccia utente basata su browser accessibile da qualsiasi dispositivo sulla rete.

Capacità

• Cattura WiFi — Decodifica frame di azione ASTM F3411 NAN, IE vendor dei beacon e DroneID proprietario DJI
• Cattura Bluetooth LE — Decodifica annunci Legacy ASTM F3411 BT4/BT5 (UUID 0xFFFA)
• Mappa in tempo reale — Mappa basata su Leaflet con icone di quadricotteri, indicatori di direzione, posizioni degli operatori e linee drone-operatore
• Etichette a colpo d'occhio — ID operatore e altitudine AGL visualizzati sotto ogni icona drone sulla mappa
• Popup di dettaglio — Clicca su un drone per vedere seriale, ID registrazione, ID operatore, tipo, velocità, direzione, altitudine, rilevamento/distanza dal ricevitore, stato BVLOS
• Sistema di allerta — Avvisi configurabili per nuovi droni, violazioni di altitudine, violazioni di velocità e perdita di segnale con toni audio, notifiche visive toast, notifiche webhook Slack e POST JSON opzionali con token bearer verso un'API generica esterna di ingest delle allerte (vedi Alerting basato su API più avanti)
• Riconoscimento allerta — Flusso di lavoro a tre stati (Attivo/Riconosciuto/Risolto) con identità dell'operatore, condiviso tra tutti i dispositivi connessi
• Geozone aeroportuali — Download e visualizzazione automatici degli aeroporti vicini (dati OurAirports) e poligoni dello spazio aereo Proibito/Restretto FAA, memorizzati localmente per funzionamento offline
• GPS — Integrazione gpsd o coordinate statiche configurabili
• Cronologia e replay — Cronologia dei rilevamenti basata su SQLite con replay della timeline ed esportazione KML
• Cursor-on-Target (CoT) — Output multicast CoT per integrazione SA
• Multi-dispositivo — L'interfaccia web funziona contemporaneamente su desktop, tablet e telefono
• Metrico / Imperiale — Supporto completo delle preferenze unità in tutta l'interfaccia e nelle allerte

L'interfaccia web è disponibile all'indirizzo http://localhost:8097 una volta avviata. Vedi Installazione più sotto per la configurazione, e il riferimento API per l'accesso programmatico.

Alerting basato su API

Oltre ai webhook Slack, Sparrow DroneID può inviare ogni allerta attivata tramite POST a un endpoint generico esterno di ingest delle allerte. Il canale è disabilitato per impostazione predefinita; configuralo in Impostazioni → Allerte → Alerting basato su API:

• Abilita — interruttore on/off
• API Endpoint Root — URL radice completo includendo qualsiasi prefisso di percorso, es. http://MY_API_HOST:PORT/API_ROOT
• Dominio — stringa opaca del tenant che l'API ricevente usa per instradare le allerte
• Token Bearer — inviato nell'intestazione Authorization: Bearer ...; mascherato nell'interfaccia una volta salvato
• Verifica TLS — deseleziona per endpoint con certificati autofirmati o CA privati
• Test Auth — chiama l'endpoint di verifica del ricevitore e riporta un chiaro superato/fallito
• Invia messaggio di test — Invia tramite POST un'allerta sintetica (rule.category: "test", seriale TEST-0000) in modo che il ricevitore possa essere testato end-to-end senza attendere un drone reale

Contratto dell'endpoint

Sparrow DroneID effettua due chiamate all'URL radice configurato:

Entrambe le chiamate inviano Authorization: Bearer <token> e Content-Type: application/json.

Forma del payload```json

{ "domain": "", "alert": { "message": "", "observer": { "name": "<operator_name or 'Sparrow DroneID'>", "type": "drone-sensor", "geo": {"location": {"lat": 0.0, "lon": 0.0}} }, "rule": {"name": "", "category": "drone_detection"}, "event": { "severity": 40, "category": "network", "action": "new_drone" }, "labels": { "serial": "", "vendor": "", "ua_type": "", "alert_type": "new_drone | altitude_max | speed_max | signal_lost" }, "source": {"geo": {"location": {"lat": 0.0, "lon": 0.0}}}, "details": { "operator_id": "...", "registration_id": "...", "self_id_text": "...", "mac_address": "...", "protocol": "...", "rssi": -68, "range_m": 1234.5, "bearing_deg": 215.0, "bearing_cardinal": "SW", "speed_mps": 5.2, "direction_deg": 240.0, "altitude_m_agl": 42.0, "detail": "..." } } }

`observer.geo.location` è incluso quando il ricevitore ha un fix GPS; `source.geo.location` è incluso quando il drone sta trasmettendo una posizione. La severità segue la convenzione ECS (più bassa = più urgente): avvisi (`new_drone`, `altitude_max`, `speed_max`) sono `40`, eventi informativi (`signal_lost`) sono `70`. I droni contrassegnati come amici non generano avvisi quando l'interruttore "Avvisa su droni amici" lato operatore è disattivato, quindi non raggiungono nemmeno questo endpoint.

Gli avvisi di test sintetici emessi dal pulsante **Invia Messaggio di Test** usano `rule.category: "test"`, `event.action: "test"`, `event.severity: 70`, e seriale `TEST-0000` in modo che il ricevitore possa riconoscerli ed escluderli dai dashboard operativi.

---

## Requisiti di Sistema

| Requisito | Sparrow-WiFi (GUI) | Sparrow DroneID (Web) |
|-------------|-------------------|----------------------|
| **Sistema Operativo** | Ubuntu 20.04+, Kali 2020.3+, Debian 11+ | Ubuntu 20.04+, Kali, Debian 11+, Raspberry Pi OS |
| **Python** | 3.8+ | 3.8+ |
| **Root** | Richiesto (iw scan) | Richiesto (modalità monitor, BLE) |
| **Adattatore WiFi** | Qualsiasi con supporto `iw` | Con supporto modalità monitor (es. rtl8812au, Intel AX200) |
| **Bluetooth** | Opzionale (adattatore hci, Ubertooth) | Opzionale (qualsiasi adattatore BLE per RemoteID) |
| **GPS** | Opzionale (gpsd) | Opzionale (gpsd o coordinate statiche) |
| **Display** | Desktop X11/Wayland | Headless OK (browser web su qualsiasi dispositivo) |

---

## Installazione

### Sparrow-WiFi (GUI desktop)```bash
git clone https://github.com/ghostop14/sparrow-wifi
cd sparrow-wifi

Pacchetti di sistema (Ubuntu 22.04+ / Debian 12+ / Kali rolling):```bash sudo apt install python3-pip python3-pyqt5 python3-pyqt5.qtchart
gpsd gpsd-clients python3-tk python3-setuptools

> **Utenti Kali:** PyQt5, PyQtChart e aircrack-ng (per il plugin Falcon) sono solitamente preinstallati. Per lo più avrai solo bisogno di `gpsd`, `gpsd-clients` e delle dipendenze Python qui sotto.

Dipendenze Python — scegli uno dei due approcci:

**Opzione A: Installazione a livello di sistema con `--break-system-packages`** — la più semplice, si adatta a come vengono avviati la GUI/agent (script di proprietà di root):```bash
# Modern systems (Ubuntu 24.04+, Kali rolling 2023+, Debian 12+) require this
# flag because Python is marked externally-managed (PEP 668). Sparrow runs as
# root anyway, so system-wide install is consistent with how it executes.
sudo pip3 install --break-system-packages -r requirements.txt

Opzione B: Ambiente virtuale — isolato, nessun avviso di pip di sistema, preferito da alcuni operatori:```bash python3 -m venv venv source venv/bin/activate pip install -r requirements.txt

Run with sudo using the venv interpreter:

sudo venv/bin/python3 ./sparrow-wifi.py

In ogni caso, esegui:```bash
sudo ./sparrow-wifi.py

Sparrow DroneID (Applicazione Web)```bash

cd sparrow-droneid

System tools — tcpdump for WiFi monitor mode, bluez for BLE RemoteID

sudo apt install tcpdump bluez

Python dependencies — pick one of:

sudo pip3 install --break-system-packages -r sparrow_droneid/requirements.txt

or:

python3 -m venv venv && source venv/bin/activate && pip install -r sparrow_droneid/requirements.txt

Run (either entry point works):

sudo python3 sparrow_droneid/app.py

or: sudo python3 -m sparrow_droneid

Apri `http://localhost:8097` in un browser. Configura l'interfaccia di monitoraggio e il GPS nelle Impostazioni, quindi clicca su Start.

### Elasticsearch / OpenSearch Bridge (opzionale)```bash
sudo pip3 install --break-system-packages -r requirements-elastic.txt
# or via venv as above

Vedi Integrazione Elasticsearch / OpenSearch di seguito.

Note sull'Adattatore WiFi

La maggior parte degli adattatori WiFi funziona per la scansione di base. Sparrow-WiFi supporta più back-end di enumerazione delle interfacce (iw, iwconfig, nmcli) quindi funziona su sistemi che potrebbero non avere iw installato (ad esempio, RHEL/Fedora con solo NetworkManager).

Per la modalità monitor (richiesta da Sparrow DroneID e dal plugin Falcon), il supporto di adattatore e driver varia:

• Consigliati: Alfa AWUS036ACH (rtl8812au), Alfa AWUS036AXML (mt7921au)
• Funziona bene: Intel AX200/AX210 (iwlwifi) per la scansione; la consegna dei frame in modalità monitor varia in base alla versione del firmware
• Testa prima: iw phy <phy> info | grep monitor o iwconfig <iface> per verificare le capacità

Per Sparrow DroneID in particolare, l'adattatore deve fornire frame 802.11 grezzi in modalità monitor. Alcuni adattatori Intel segnalano la modalità monitor come supportata ma scartano silenziosamente i frame a livello firmware. L'applicazione lo rileva e ti avvisa.

Bluetooth

Sparrow-WiFi supporta diverse modalità di scansione Bluetooth:

Un adattatore Bluetooth standard integrato o USB è sufficiente per la scansione degli annunci BLE e il rilevamento di droni RemoteID. Testa il tuo adattatore con bluetoothctl scan on.

Per la scoperta promiscua completa di dispositivi sia Classic che BLE, avrai bisogno di un Ubertooth One e Blue Hydra installati in /opt/bluetooth/blue_hydra. Questo è opzionale e non richiesto per la scansione BLE di base o RemoteID.

Analisi dello Spettro

Sovrapposizioni spettrali in tempo reale sulle viste dei canali WiFi:

Ubertooth One

• Solo 2,4 GHz, risoluzione 1 MHz
• Test con: ubertooth-specan-ui

HackRF One

• 2,4 GHz (risoluzione 0,5 MHz) e 5 GHz (risoluzione 2 MHz)
• Una banda alla volta; combina con Ubertooth per dual-band simultanea
• Usa un'antenna dual-band appropriata (l'antenna standard HackRF è classificata solo per 1 GHz)
• Nota: è necessario un adattatore da RP-SMA a SMA per la maggior parte delle antenne WiFi
• Test con: hackrf_sweep

GPS

Entrambe le applicazioni usano gpsd per il GPS. Configurazione rapida:```bash

Install

sudo apt install gpsd gpsd-clients

Test with a USB GPS receiver

sudo gpsd -D 2 -N /dev/ttyUSB0

Verify

xgps # or: cgps -s

Per la produzione, configura `/etc/default/gpsd` con il percorso del dispositivo e riavvia il servizio.

Sparrow DroneID supporta anche coordinate statiche (configurate in Impostazioni) per installazioni in siti fissi senza ricevitore GPS.

---

## Agente Remoto e Integrazione API

L'agente Sparrow (`sparrowwifiagent.py`) è un server HTTP senza interfaccia grafica che espone tutte le capacità di scansione WiFi e Bluetooth di Sparrow come API REST basate su JSON. È così che l'interfaccia GUI di Sparrow-WiFi comunica con i sensori remoti, ma l'API è aperta per qualsiasi applicazione.

**Casi d'uso:**
- Distribuibile su Raspberry Pi, drone o rover per scansione remota/mobile
- Integra la consapevolezza situazionale WiFi e Bluetooth nelle tue applicazioni
- Alimenta i dati di scansione in SIEM, dashboard o pipeline di allerta
- Automatizza la scansione con script (avvia scansioni, recupera risultati tramite curl/Python/ecc.)

Anche Sparrow DroneID ha una propria API REST ([riferimento API](https://github.com/ghostop14/sparrow-wifi/blob/HEAD/sparrow-droneid/sparrow_drone_id_api.md)), che fornisce accesso programmatico a rilevamenti di droni, gestione degli allarmi, geozone e configurazione di sistema.

### Esecuzione dell'Agente```bash
sudo ./sparrowwifiagent.py

Ascolta sulla porta 8020 di default. Opzioni principali:

Vedi --help per l'elenco completo.

Esempio di chiamate API```bash

List wireless interfaces the agent can scan

curl http://sensor:8020/wireless/interfaces

Trigger a WiFi scan and pull results (multiple concurrent callers

get coalesced into a single iw scan; first caller is the leader)

curl http://sensor:8020/wireless/networks/wlan0

Filter to specific frequencies

curl "http://sensor:8020/wireless/networks/wlan0?frequencies=2412,2437,2462"

Query GPS status

curl http://sensor:8020/gps/status

Start a Bluetooth Low Energy advertisement scan

curl http://sensor:8020/bluetooth/discoverystarta

Pull current BT discovery results

curl http://sensor:8020/bluetooth/discoverystatus

Per Sparrow DroneID, consultare il [riferimento API](https://github.com/ghostop14/sparrow-wifi/blob/HEAD/sparrow-droneid/sparrow_drone_id_api.md) dedicato.

> **Nota per la produzione:** l'agente ascolta su tutte le interfacce per impostazione predefinita. Per distribuzioni al di fuori di una rete affidabile, utilizzare `--allowedips` per limitare i chiamanti, eseguire dietro un proxy inverso con TLS, o associare solo a un'interfaccia privata.

---

## Plugin Falcon / Aircrack-ng

Integrazione avanzata per test di penetrazione wireless. Fornisce accesso point-and-click a:

- Scoperta di SSID nascosto tramite airodump-ng
- Enumerazione delle stazioni client (AP connesso, SSID sondati)
- Deautenticazione mirata e broadcast
- Cattura IV WEP
- Cattura handshake WPA con estrazione automatica dell'hash (richiede JTR `wpapcap2john`)

### Prerequisiti```bash
# Kali users: aircrack-ng + JTR are usually pre-installed.
# Ubuntu / Debian / Raspberry Pi OS:
sudo apt install aircrack-ng john

Verifica che airmon-ng, airodump-ng e wpapcap2john siano presenti nel tuo PATH dopo l'installazione.

Disclaimer

I test di penetrazione attivi sono soggetti a normative legali. È tua responsabilità ottenere l'autorizzazione appropriata prima di utilizzare questi strumenti.

Integrazione Elasticsearch / OpenSearch

Il pacchetto sparrow_elastic fornisce un ponte ECS 8.17 che interroga l'agente Sparrow WiFi e indicizza in blocco le osservazioni WiFi e Bluetooth in Elasticsearch 8.x o OpenSearch 2.x. Avvia automaticamente modelli di indice componibili, politiche del ciclo di vita ILM/ISM e alias di scrittura rollover; esegue l'arricchimento del fornitore OUI e la classificazione dei dispositivi basata su regole (con fingerprinting opzionale di Fingerbank); e fornisce dashboard Kibana predefiniti.

Avvio rapido```bash

1. Start the remote agent (it provides scan data via HTTP)

sudo ./sparrowwifiagent.py

2. Install bridge dependencies

sudo pip3 install --break-system-packages -r requirements-elastic.txt

3. Run the bridge

./sparrow-elastic.py --elasticserver http://user:pass@host:9200 --wifiinterface wlan1

4. (Optional) Import the bundled Kibana dashboards

python3 install_dashboards.py --kibana-url http://kibana:5601
--username elastic --password ''

> **Igiene delle credenziali:** includere `user:pass@` in `--elasticserver` è comodo, ma l'URL diventa visibile in `ps`, `journalctl` e nella cronologia della shell. Per la produzione, usa i flag `--username`/`--password`, le variabili d'ambiente (`SPARROW_ES_USERNAME`, `SPARROW_ES_PASSWORD`), o il pattern `EnvironmentFile=` nell'esempio di unità systemd incluso.

### Cosa include il bridge

- **5 dashboard Kibana** — Consapevolezza Situazionale, Pattern di Vita, Rilevamento di Nuovi Dispositivi, Pianificazione dello Spettro (con mappa di calore SSID × Canale dell'intensità del segnale) e Consapevolezza Situazionale Bluetooth (con pannello Vega per dispositivi veramente nuovi e tabella di prossimità con distanza stimata)
- **6 visualizzazioni preservate dalla versione legacy** — cloni rinominati delle vecchie visualizzazioni `Sparrow*` per mantenere funzionante la memoria muscolare
- **Classificatore di dispositivi** — tabella seed con 64 regole che coprono controller di droni (DJI/Autel/Skydio/Parrot/Yuneec), BT Class of Device, GAP Appearance, sottotipi Apple Continuity e euristiche OUI del venditore
- **Aggiornamento dei dati di riferimento** — file `manuf` di Wireshark, ID aziendali BT SIG, UUID di servizio, valori GAP Appearance e tabelle dei sottotipi Apple Continuity, con un thread in background di auto-aggiornamento a 30/90 giorni
- **Controllo di compatibilità pre-avvio** — rifiuta di scrivere in indici ECS 1.5 legacy e stampa chiari passaggi di correzione invece di corrompere silenziosamente i dati

Per la documentazione operativa completa (selezione del motore, modalità di autenticazione, importazione delle dashboard, dati di riferimento, riferimento CLI completo) consulta [sparrow_elastic/README.md](https://github.com/ghostop14/sparrow-wifi/blob/HEAD/sparrow_elastic/README.md).

I file di configurazione di esempio si trovano nella radice del repository e in `init.d_scripts/`:

- `sparrow-elastic.conf.example` — configurazione in stile INI con tutte le chiavi supportate
- `sparrow-elastic.env.example` — file env in formato shell per distribuzioni systemd
- `init.d_scripts/sparrow-elastic.service.example` — template di unità systemd

### Migrazione dal bridge legacy ECS 1.5

Il bridge precedente al 2026 scriveva documenti ECS 1.5 in indici denominati dall'operatore tramite `--wifiindex` / `--btindex`. Il nuovo bridge scrive documenti ECS 8.17 in alias di scrittura gestiti da rollover (predefiniti `sparrow-wifi` / `sparrow-bt`).

**Lo script legacy è conservato in `legacy/sparrow-elastic.py`** insieme al suo template `.txt` e ai file delle policy ILM. Per eseguirlo è ancora necessario l'ambiente legacy (impostazione manuale di template e ILM).

**Modifiche ai flag (con retrocompatibilità):**

| Flag legacy         | Nuovo flag         | Note                                                  |
|---------------------|--------------------|--------------------------------------------------------|
| `--wifiindex NAME`  | `--wifi-alias NAME`| La grafia legacy è ancora accettata come alias deprecato. |
| `--btindex NAME`    | `--bt-alias NAME`  | La grafia legacy è ancora accettata come alias deprecato. |
| `--dont-create-indices` | invariato       | Salta il bootstrap.                                       |
| `--elasticserver`, `--sparrowagent`, `--sparrowport`, `--wifiinterface`, `--scandelay` | invariati | |

Un'invocazione legacy come:```bash
./sparrow-elastic.py --elasticserver=http://user:pass@host:9200 \
                     --wifiinterface=wlan1 \
                     --wifiindex=sparrowwifi-home \
                     --btindex=sparrowbt-home

ancora analizza e funziona — ma il bridge ora rifiuta di scrivere in un indice preesistente la cui mappatura non contiene il marcatore dello schema ECS 8.17, uscendo con tre opzioni di remediation (usa un alias diverso, cancella e riavvia, o esegui il bridge legacy). Per un'installazione pulita, basta rimuovere --wifiindex / --btindex e accettare i nuovi valori predefiniti.

Operazioni Drone / Rover

L'agente remoto può essere distribuito su un Raspberry Pi montato su un drone o rover per il rilevamento wireless mobile. Testato su un drone Solo 3DR con integrazione GPS tramite MAVLink.

Registrazione Autonoma```bash

On the Pi: auto-start, pull drone GPS, record to local files

sudo python3 ./sparrowwifiagent.py --userpileds --sendannounce --mavlinkgps 3dr --recordinterface wlan0

Indicatori LED (Raspberry Pi):
1. Entrambi spenti — Inizializzazione
2. Battito rosso — GPS presente, non sincronizzato
3. Rosso fisso — GPS sincronizzato
4. Verde fisso — Agente pronto, serve richieste

Le registrazioni possono essere recuperate tramite l'interfaccia di gestione degli agenti della GUI di Sparrow-WiFi.

### Note di Configurazione del Pi

- Usa Raspberry Pi OS (Bookworm o successivo) con Python 3.8+
- Disabilita il WiFi integrato per abilitare la scansione a 5 GHz con adattatori USB: aggiungi `dtoverlay=disable-wifi` a `/boot/firmware/config.txt` su Bookworm e successivi, o `/boot/config.txt` su versioni precedenti
- Installa i prerequisiti: `sudo pip3 install --break-system-packages -r requirements.txt` (oppure usa un venv come nella sezione [Installazione](#installation))

---

## Struttura del Progetto```
sparrow-wifi/
  sparrow-wifi.py            # Desktop GUI entry point
  sparrowwifiagent.py        # Headless remote agent
  sparrow-elastic.py         # Elasticsearch / OpenSearch bridge (ECS 8.17)
  install_dashboards.py      # One-shot Kibana dashboard installer
  requirements.txt           # Python dependencies (GUI)
  requirements-elastic.txt   # Python dependencies (Elasticsearch bridge)
  wirelessengine.py          # WiFi scan engine (iw)
  sparrowbluetooth.py        # Bluetooth scan engine
  sparrowhackrf.py           # HackRF spectrum engine
  sparrowmap.py              # Map generation
  plugins/                   # Falcon and other plugins
  sparrow_elastic/           # ES/OS bridge package
    *.py                     # Client abstraction, document builder, classifier...
    templates/               # Composable index templates (ES + OS variants)
    policies/                # ILM (ES) and ISM (OS) lifecycle policy JSON
    dashboards/              # Kibana NDJSON: 5 dashboards + legacy-preserved
    data/                    # Bundled reference data (manuf, BT SIG, classifier rules)
    README.md                # Full bridge operator documentation
  legacy/                    # Pre-2026 ECS 1.5 bridge, frozen for reference
    sparrow-elastic.py       # Legacy bridge (still runnable)
    sparrow_elastic_*.txt    # Legacy index templates and ILM policy
  sparrow-droneid/           # DroneID web application
    sparrow_droneid/
      app.py                 # Entry point (sudo python3 app.py)
      __main__.py            # Allows: sudo python3 -m sparrow_droneid
      requirements.txt       # Python dependencies (DroneID)
      backend/               # API server, capture engine, database
      frontend/              # HTML, JS, CSS (served by backend)
    sparrow_drone_id_api.md  # REST API reference

Licenza

Questo progetto è concesso in licenza secondo i termini inclusi nel repository. Vedi il file LICENSE per i dettagli.