Sparrow-WiFi

Sparrow-WiFi ist ein Tool zur 2,4 GHz- und 5 GHz-WLAN- und Bluetooth-Spektralanalyse für Linux. Es integriert WLAN-Scanning, Bluetooth Low Energy- und Classic-Erkennung, Software Defined Radio-Spektrumanalyse (HackRF, Ubertooth), GPS-Tracking, FAA-RemoteID-Drohnenerkennung, Drohnen-/Rover-gestützten Fernbetrieb und ECS 8.17-Indizierung in Elasticsearch oder OpenSearch in einer einzigen Plattform. Vollständig in Python 3 geschrieben.

Das Projekt umfasst vier Komponenten, die eigenständig oder zusammenarbeiten können:

Der Sparrow Agent und Sparrow DroneID stellen JSON-REST-APIs bereit, über die andere Anwendungen Scanergebnisse abfragen, Scans auslösen, Drohnenerkennungen abrufen und drahtlose/Drohnen-Erkennungsfunktionen in ihre eigenen Workflows integrieren können. Die Elastic Bridge nutzt die REST-API des Agents und übermittelt ECS 8.17-Dokumente mit gebündelten Kibana-Dashboards.

Neuerungen (April 2026)

Diese Version enthält drei wesentliche Verbesserungen gegenüber der Vorgängerversion:

• Sparrow Agent: Single-Flight-WLAN-Scan-Zusammenführung. Wenn mehrere HTTP-Clients (die DroneID-App, die Elasticsearch-Bridge, die GUI) gleichzeitig auf /wireless/networks/<iface> zugreifen, hat der Agent zuvor N redundante iw scan-Aufrufe gestartet, die auf der Schnittstellensperre serialisiert wurden, wodurch die Scan-Latenz um die Anzahl der Clients multipliziert wurde. Die erste Anfrage ist jetzt der "Leader", der tatsächlich scannt; gleichzeitige Anfragen warten auf ein threading.Event und teilen sich das Ergebnis des Leaders. Enthält auch einen TOCTOU-Fix bei der Sperrerstellung und Ausnahmesicherheit bei schnittstellenspezifischen Sperren.
• Sparrow DroneID — neue webbasierte Anwendung zur FAA-RemoteID-Erkennung über WLAN (ASTM F3411 NAN, Beacon-Vendor-IEs, DJIs proprietäres DroneID-Protokoll) und Bluetooth LE (BT4/BT5 Legacy Advertising). Beinhaltet Geozonen-Overlays, mehrstufige Benachrichtigungen mit Slack-Integration, KML-Export, Cursor-on-Target-Ausgabe, optionale ECS 8.17-Indizierung in Elasticsearch / OpenSearch (mit einem benutzerdefinierten droneid.*-Namespace) und eine reaktionsfähige Multi-Device-Web-Benutzeroberfläche. Siehe Abschnitt Sparrow DroneID unten.
• Modernisierte Elasticsearch / OpenSearch-Bridge — die sparrow-elastic.py-Bridge wurde neu geschrieben, um ECS 8.17-Dokumente (zuvor ECS 1.5) zu erzeugen, unterstützt jetzt sowohl Elasticsearch 8.x als auch OpenSearch 2.x, erstellt automatisch zusammensetzbare Indexvorlagen mit ILM/ISM-Lebenszyklusrichtlinien und Rollover-Write-Aliase, führt OUI-Vendor-Anreicherung und regelbasierte Geräteklassifizierung (mit optionalem Fingerbank-Fingerprinting) durch und liefert vier gebündelte Kibana-Dashboards sowie sechs konservierte Legacy-Visualisierungen. Die Legacy-ECS-1.5-Bridge bleibt unter legacy/sparrow-elastic.py erhalten. Siehe .

Sparrow-WiFi (Desktop-GUI)

Die ursprüngliche Sparrow-Anwendung bietet eine umfassende GUI-basierte Alternative zu Tools wie inSSIDer und LinSSID mit weit über das einfache Scannen hinausgehenden Fähigkeiten:

• WLAN-Scannen — 2,4 GHz- und 5 GHz-SSID-Erkennung, Signalstärke, Kanalauslastung
• Quellenverfolgung — Jagdmodus mit hohen Abtastraten und Telemetriefenstern zum Lokalisieren von WLAN- und Bluetooth-Quellen
• Spektrumanalyse — Echtzeit-Spektralüberlagerungen für 2,4/5 GHz über Ubertooth One oder HackRF One
• Bluetooth — BLE-Werbe-Scanning, iBeacon-Erkennung/-Ausstrahlung, Ubertooth-Promiscuous-Modus für Classic + LE
• Remote-Agent — Headless-Agent (sparrowwifiagent.py) für verteiltes Scannen, Drohnen-/Rover-gestützten Betrieb und Raspberry-Pi-Einsätze
• GPS-Integration — gpsd, statische Koordinaten oder MAVLink (Drohnen-GPS)
• Kartendarstellung — Google Maps / OpenStreetMap-Visualisierung von Scanergebnissen mit GPS-Tracks
• Import/Export — CSV, JSON und rohe iw scan-Ausgabe
• Elasticsearch / OpenSearch — ECS 8.17-konforme Indizierung von WLAN- und Bluetooth-Scandaten mit ILM/ISM-Lebenszyklusverwaltung, Geräteklassifizierung, optionalem Fingerbank-Fingerprinting und gebündelten Kibana-Dashboards
• Falcon-Plugin — Aircrack-ng-Integration für Penetrationstests (Monitor-Modus, Erkennung versteckter SSIDs, Deauth, WEP/WPA-Erfassung)

Screenshots

Sparrow DroneID (Webanwendung)

Ein eigenständiges webbasiertes Drohnenerkennungs- und Verfolgungssystem, das die von der FAA vorgeschriebene Fernidentifikation (Remote Identification, RemoteID) dekodiert. Läuft als Python-HTTP-Server mit einer browserbasierten Benutzeroberfläche, die von jedem Gerät im Netzwerk aus zugänglich ist.

Fähigkeiten

• WLAN-Erfassung — Dekodiert ASTM F3411 NAN-Action-Frames, Beacon-Vendor-IEs und DJIs proprietäres DroneID
• Bluetooth LE-Erfassung — Dekodiert ASTM F3411 BT4/BT5 Legacy Advertising (UUID 0xFFFA)
• Echtzeitkarte — Leaflet-basierte Karte mit Quadcopter-Symbolen, Richtungsanzeigern, Operator-Positionsmarkierungen und Drohne-zu-Operator-Linien
• Auf einen Blick — Operator-ID und Höhe über Grund (AGL) werden unter jedem Drohnensymbol auf der Karte angezeigt
• Detail-Popups — Klicken Sie auf eine Drohne, um Seriennummer, Registrierungs-ID, Operator-ID, Typ, Geschwindigkeit, Richtung, Höhe, Peilung/Entfernung zum Empfänger, BVLOS-Status anzuzeigen
• Benachrichtigungssystem — Konfigurierbare Benachrichtigungen für neue Drohnen, Höhenverstöße, Geschwindigkeitsverstöße und Signalverlust mit Audio-Tönen, visuellen Toasts, Slack-Webhook-Benachrichtigungen und optionalen Bearer-Token-JSON-POSTs an eine generische externe Alert-Ingest-API (siehe API-basierte Benachrichtigung unten)
• Benachrichtigungsbestätigung — Drei-Stufen-Workflow (Aktiv/Bestätigt/Aufgelöst) mit Operator-Identität, der auf allen verbundenen Geräten geteilt wird
• Flughafen-Geozonen — Automatischer Download und Anzeige nahegelegener Flughäfen (OurAirports-Daten) und FAA-Sperr-/Einschränkungs-Luftraum-Polygone, lokal für den Offline-Betrieb zwischengespeichert
• GPS — gpsd-Integration oder konfigurierbare statische Koordinaten
• Verlauf & Wiedergabe — SQLite-gestützter Erkennungsverlauf mit Zeitleisten-Wiedergabe und KML-Export
• Cursor-on-Target (CoT) — Multicast-CoT-Ausgabe für SA-Integration
• Multi-Device — Web-UI funktioniert gleichzeitig auf Desktop, Tablet und Telefon
• Metrisch / Imperial — Vollständige Einheitenpräferenz-Unterstützung in der gesamten UI und den Benachrichtigungen

Die Web-UI läuft nach dem Start unter http://localhost:8097. Siehe Installation unten für die Einrichtung und die API-Referenz für den programmatischen Zugriff.

API-basierte Benachrichtigung

Zusätzlich zu Slack-Webhooks kann Sparrow DroneID jede ausgelöste Benachrichtigung an einen generischen externen Alert-Ingest-Endpunkt senden. Der Kanal ist standardmäßig deaktiviert; konfigurieren Sie ihn in Einstellungen → Benachrichtigungen → API-basierte Benachrichtigung:

• Aktivieren — Ein/Aus-Umschalter
• API-Endpunkt-Root — vollständige Root-URL inklusive Pfadpräfix, z.B. http://MEIN_API_HOST:PORT/API_ROOT
• Domain — undurchsichtige Mandanten-Zeichenkette, die die empfangende API zum Weiterleiten von Benachrichtigungen verwendet
• Bearer-Token — wird im Authorization: Bearer ...-Header gesendet; in der UI nach dem Speichern maskiert
• TLS überprüfen — deaktivieren für selbstsignierte oder private-CA-Endpunkte
• Auth testen — ruft den Verifikationsendpunkt des Empfängers auf und meldet eindeutig bestanden/nicht bestanden
• Testnachricht senden — POSTet eine synthetische Benachrichtigung (rule.category: "test", Seriennummer TEST-0000), damit der Empfänger End-to-End getestet werden kann, ohne auf eine echte Drohne zu warten

Endpunkt-Vertrag

Sparrow DroneID führt zwei Aufrufe gegen die konfigurierte Root-URL aus:

Beide Aufrufe senden Authorization: Bearer <token> und Content-Type: application/json.

Nutzlaststruktur```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` wird eingefügt, wenn der Empfänger einen GPS-Fix hat; `source.geo.location` wird eingefügt, wenn die Drohne ihre Position sendet. Der Schweregrad folgt der ECS-Konvention (niedriger = dringlicher): Warnungen (`new_drone`, `altitude_max`, `speed_max`) sind `40`, informative Ereignisse (`signal_lost`) sind `70`. Als freundlich markierte Drohnen lösen keine Warnungen aus, wenn der Schalter "Warnungen bei freundlichen Drohnen" auf der Betreiberseite deaktiviert ist, daher erreichen sie diesen Endpunkt ebenfalls nicht.

Synthetische Test-Warnungen, die über die Schaltfläche **Testnachricht senden** ausgelöst werden, verwenden `rule.category: "test"`, `event.action: "test"`, `event.severity: 70` und die Seriennummer `TEST-0000`, damit der Empfänger sie erkennen und aus den operativen Dashboards ausschließen kann.

---

## Systemanforderungen

| Anforderung | Sparrow-WiFi (GUI) | Sparrow DroneID (Web) |
|-------------|-------------------|----------------------|
| **Betriebssystem** | Ubuntu 20.04+, Kali 2020.3+, Debian 11+ | Ubuntu 20.04+, Kali, Debian 11+, Raspberry Pi OS |
| **Python** | 3.8+ | 3.8+ |
| **Root** | Erforderlich (iw scan) | Erforderlich (Monitor-Modus, BLE) |
| **WLAN-Adapter** | Jedes mit `iw`-Unterstützung | Monitor-Modus-fähig (z.B. rtl8812au, Intel AX200) |
| **Bluetooth** | Optional (hci-Adapter, Ubertooth) | Optional (jeder BLE-fähige Adapter für RemoteID) |
| **GPS** | Optional (gpsd) | Optional (gpsd oder statische Koordinaten) |
| **Display** | X11/Wayland-Desktop | Headless OK (Webbrowser auf jedem Gerät) |

---

## Installation

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

Systempakete (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

> **Kali-Nutzer:** PyQt5, PyQtChart und aircrack-ng (für das Falcon-Plugin) sind normalerweise vorinstalliert. Sie benötigen hauptsächlich nur `gpsd`, `gpsd-clients` und die folgenden Python-Abhängigkeiten.

Python-Abhängigkeiten — wählen Sie einen der beiden Ansätze:

**Option A: Systemweite Installation mit `--break-system-packages`** — am einfachsten, passt zur Startweise von GUI/Agent (root-eigene Skripte):```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

Option B: Virtuelle Umgebung — isoliert, keine System-Pip-Warnungen, von einigen Betreibern bevorzugt:```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

Wie auch immer, führen Sie aus:```bash
sudo ./sparrow-wifi.py

Sparrow DroneID (Webanwendung)```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

Öffnen Sie `http://localhost:8097` in einem Browser. Konfigurieren Sie die Überwachungsschnittstelle und das GPS in den Einstellungen und klicken Sie dann auf Start.

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

Siehe Elasticsearch / OpenSearch Integration unten.

Hinweise zu WiFi-Adaptern

Die meisten WiFi-Adapter funktionieren für grundlegendes Scannen. Sparrow-WiFi unterstützt mehrere Schnittstellen-Erfassungs-Backends (iw, iwconfig, nmcli), sodass es auch auf Systemen funktioniert, die nicht über iw verfügen (z. B. RHEL/Fedora nur mit NetworkManager).

Für den Monitormodus (erforderlich für Sparrow DroneID und das Falcon-Plugin) variiert die Unterstützung von Adaptern und Treibern:

• Empfohlen: Alfa AWUS036ACH (rtl8812au), Alfa AWUS036AXML (mt7921au)
• Funktioniert gut: Intel AX200/AX210 (iwlwifi) zum Scannen; die Frame-Zustellung im Monitormodus variiert je nach Firmware-Version
• Zuerst testen: iw phy <phy> info | grep monitor oder iwconfig <iface> um die Fähigkeiten zu überprüfen

Speziell für Sparrow DroneID muss der Adapter rohe 802.11-Frames im Monitormodus liefern. Einige Intel-Adapter melden den Monitormodus als unterstützt, verwerfen jedoch stillschweigend Frames auf Firmware-Ebene. Die Anwendung erkennt dies und warnt Sie.

Bluetooth

Sparrow-WiFi unterstützt mehrere Bluetooth-Scan-Modi:

Ein standardmäßiger eingebauter oder USB-Bluetooth-Adapter ist ausreichend für BLE-Werbescan und RemoteID-Drohnenerkennung. Testen Sie Ihren Adapter mit bluetoothctl scan on.

Für die vollständige promiskuitive Erkennung sowohl von Classic- als auch BLE-Geräten benötigen Sie einen Ubertooth One und Blue Hydra, installiert in /opt/bluetooth/blue_hydra. Dies ist optional und nicht erforderlich für grundlegendes BLE- oder RemoteID-Scannen.

Spektrumanalyse

Echtzeit-Spektralüberlagerungen auf WiFi-Kanalansichten:

Ubertooth One

• Nur 2,4 GHz, 1 MHz Auflösung
• Testen mit: ubertooth-specan-ui

HackRF One

• 2.4 GHz (0.5 MHz Auflösung) und 5 GHz (2 MHz Auflösung)
• Ein Band auf einmal; kombinieren Sie mit Ubertooth für gleichzeitiges Dualband
• Verwenden Sie eine geeignete Dualband-Antenne (die Standard-HackRF-Antenne ist nur bis 1 GHz ausgelegt)
• Hinweis: RP-SMA-auf-SMA-Adapter für die meisten WiFi-Antennen erforderlich
• Testen mit: hackrf_sweep

GPS

Beide Anwendungen verwenden gpsd für GPS. Schnelle Einrichtung:```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

Für den Produktionseinsatz konfigurieren Sie `/etc/default/gpsd` mit Ihrem Gerätepfad und starten Sie den Dienst neu.

Sparrow DroneID unterstützt auch statische Koordinaten (in den Einstellungen konfiguriert) für feste Installationen ohne GPS-Empfänger.

---

## Remote-Agent und API-Integration

Der Sparrow-Agent (`sparrowwifiagent.py`) ist ein kopfloser HTTP-Server, der alle WLAN- und Bluetooth-Scan-Funktionen von Sparrow als JSON-basierte REST-API bereitstellt. So kommuniziert die Sparrow-WiFi-GUI mit entfernten Sensoren, aber die API steht jeder Anwendung offen.

**Anwendungsfälle:**
- Einsatz auf einem Raspberry Pi, einer Drohne oder einem Rover für ferngesteuertes/mobiles Scannen
- Integration von WLAN- und Bluetooth-Lagebewusstsein in Ihre eigenen Anwendungen
- Einspeisung von Scandaten in SIEM, Dashboards oder Alarmierungs-Pipelines
- Automatisierung des Scannings mit Skripten (Scans auslösen, Ergebnisse per curl/Python/usw. abrufen)

Sparrow DroneID hat ebenfalls eine eigene REST-API ([API-Referenz](https://github.com/ghostop14/sparrow-wifi/blob/HEAD/sparrow-droneid/sparrow_drone_id_api.md)), die programmatischen Zugriff auf Drohnenerkennungen, Alarmverwaltung, Geozonen und Systemkonfiguration bietet.

### Ausführen des Agents```bash
sudo ./sparrowwifiagent.py

Hört standardmäßig auf Port 8020. Wichtige Optionen:

Siehe --help für die vollständige Liste.

Beispiel-API-Aufrufe```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

Für Sparrow DroneID siehe die dedizierte [API-Referenz](https://github.com/ghostop14/sparrow-wifi/blob/HEAD/sparrow-droneid/sparrow_drone_id_api.md).

> **Produktionshinweis:** der Agent lauscht standardmäßig auf allen Schnittstellen. Für Bereitstellungen außerhalb eines vertrauenswürdigen Netzwerks verwenden Sie `--allowedips`, um Aufrufer einzuschränken, führen Sie ihn hinter einem Reverse-Proxy mit TLS aus oder binden Sie ihn nur an eine private Schnittstelle.

---

## Falcon / Aircrack-ng Plugin

Erweiterte Integration für drahtlose Penetrationstests. Bietet Point-and-Click-Zugriff auf:

- Erkennung versteckter SSIDs mittels airodump-ng
- Aufzählung von Client-Stationen (verbundener AP, angefragte SSIDs)
- Gezielte und Broadcast-Deauthentifizierung
- WEP-IV-Erfassung
- WPA-Handshake-Erfassung mit automatischer Hash-Extraktion (erfordert JTR `wpapcap2john`)

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

Überprüfen Sie, dass airmon-ng, airodump-ng und wpapcap2john nach der Installation in Ihrem PATH vorhanden sind.

Haftungsausschluss

Aktive Penetrationstests unterliegen gesetzlichen Bestimmungen. Es liegt in Ihrer Verantwortung, vor der Nutzung dieser Werkzeuge eine entsprechende Genehmigung einzuholen.

Elasticsearch / OpenSearch Integration

Das Paket sparrow_elastic bietet eine ECS 8.17-Brücke, die den Sparrow-WiFi-Agenten abfragt und WiFi- und Bluetooth-Beobachtungen in Elasticsearch 8.x oder OpenSearch 2.x bulk-indexiert. Es bootstrapt automatisch zusammensetzbare Indexvorlagen, ILM/ISM-Lebenszyklusrichtlinien und Rollover-Write-Aliase; führt OUI-Anreicherung und regelbasierte Geräteklassifizierung durch (mit optionalem Fingerbank-Fingerprinting); und liefert vorgefertigte Kibana-Dashboards aus.

Schnellstart```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 ''

> **Anmeldeinformationshygiene:** Das Einbetten von `user:pass@` in `--elasticserver` ist praktisch, aber die URL wird in `ps`, `journalctl` und der Shell-Historie sichtbar. Für den Produktiveinsatz verwenden Sie die Flags `--username`/`--password`, Umgebungsvariablen (`SPARROW_ES_USERNAME`, `SPARROW_ES_PASSWORD`) oder das `EnvironmentFile=`-Muster in der beigefügten systemd-Unit-Beispiel.

### Was die Bridge mitliefert

- **5 Kibana-Dashboards** — Situationsbewusstsein, Verhaltensmuster, Erkennung neuer Geräte, Spektrumplanung (mit SSID × Kanal-Signalstärke-Heatmap) und Bluetooth-Situationsbewusstsein (mit Vega-Panel für wirklich neue Geräte und Entfernungsschätzungstabelle)
- **6 beibehaltene Visualisierungen aus der Vorgängerversion** — umbenannte Klone der ursprünglichen `Sparrow*`-Visualisierungen, damit die vertrauten Arbeitsabläufe weiterhin funktionieren
- **Geräteklassifizierer** — 64-Regeln-Stammtabelle, die Drohnencontroller (DJI/Autel/Skydio/Parrot/Yuneec), BT-Klasse des Geräts, GAP-Erscheinungsbild, Apple Continuity-Untertypen und OUI-Herstellerheuristiken abdeckt
- **Referenzdatenaktualisierung** — gebündelte Wireshark-`manuf`, BT-SIG-Unternehmens-IDs, Service-UUIDs, GAP-Erscheinungsbildwerte und Apple Continuity-Untertyp-Tabellen, mit einem 30/90-Tage-Selbstaktualisierungs-Hintergrundthread
- **Kompatibilitätsprüfung vor dem Start** — weigert sich, in Legacy-ECS-1.5-Indizes zu schreiben und gibt stattdessen klare Abhilfeschritte aus, anstatt Daten stillschweigend zu beschädigen

Die vollständige Bedienerdokumentation (Engine-Auswahl, Authentifizierungsmodi, Dashboard-Import, Referenzdaten, vollständige CLI-Referenz) finden Sie in [sparrow_elastic/README.md](https://github.com/ghostop14/sparrow-wifi/blob/HEAD/sparrow_elastic/README.md).

Beispielkonfigurationsdateien befinden sich im Repository-Stammverzeichnis und in `init.d_scripts/`:

- `sparrow-elastic.conf.example` — INI-ähnliche Konfiguration mit allen unterstützten Schlüsseln
- `sparrow-elastic.env.example` — Shell-Format-Umgebungsdatei für systemd-Bereitstellungen
- `init.d_scripts/sparrow-elastic.service.example` — systemd-Unit-Vorlage

### Migration von der Legacy-ECS-1.5-Bridge

Die Bridge vor 2026 schrieb ECS-1.5-Dokumente in vom Betreiber benannte Indizes über `--wifiindex` / `--btindex`. Die neue Bridge schreibt ECS-8.17-Dokumente in rollover-verwaltete Schreibaliase (Standard `sparrow-wifi` / `sparrow-bt`).

**Das Legacy-Skript bleibt unter `legacy/sparrow-elastic.py` erhalten**, zusammen mit seiner `.txt`-Vorlage und ILM-Richtliniendateien. Die Ausführung erfordert weiterhin die Legacy-Umgebung (manuelle Vorlagen- und ILM-Einrichtung).

**Flag-Änderungen (mit Abwärtskompatibilität):**

| Legacy-Flag         | Neues Flag           | Anmerkungen                                                  |
|---------------------|--------------------|--------------------------------------------------------|
| `--wifiindex NAME`  | `--wifi-alias NAME`| Die Legacy-Schreibweise wird weiterhin als veralteter Alias akzeptiert.  |
| `--btindex NAME`    | `--bt-alias NAME`  | Die Legacy-Schreibweise wird weiterhin als veralteter Alias akzeptiert.  |
| `--dont-create-indices` | unverändert       | Überspringt Bootstrap.                                       |
| `--elasticserver`, `--sparrowagent`, `--sparrowport`, `--wifiinterface`, `--scandelay` | unverändert | |

Ein Legacy-Aufruf wie:```bash
./sparrow-elastic.py --elasticserver=http://user:pass@host:9200 \
                     --wifiinterface=wlan1 \
                     --wifiindex=sparrowwifi-home \
                     --btindex=sparrowbt-home

parst und läuft weiterhin — aber die Brücke weigert sich nun, in einen bereits bestehenden Index zu schreiben, dessen Mapping nicht den ECS-8.17-Schema-Marker trägt, und beendet sich mit drei Abhilfemaßnahmen (einen anderen Alias verwenden, den Index löschen und neu bootstrappen, oder die Legacy-Brücke ausführen). Bei einer Neuinstallation reicht es, --wifiindex / --btindex wegzulassen und die neuen Standardeinstellungen zu akzeptieren.

Drohnen- / Rover-Betrieb

Der Remote-Agent kann auf einem Raspberry Pi bereitgestellt werden, der auf einer Drohne oder einem Rover montiert ist, für mobile drahtlose Vermessungen. Getestet auf einer Solo 3DR-Drohne mit GPS-Integration über MAVLink.

Autonome Aufzeichnung```bash

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

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

LED-Anzeigen (Raspberry Pi):
1. Beide aus — Initialisierung
2. Roter Herzschlag — GPS vorhanden, nicht synchronisiert
3. Rotes Dauerlicht — GPS synchronisiert
4. Grünes Dauerlicht — Agent bereit, bedient Anfragen

Aufnahmen können über die Agentenverwaltungsoberfläche der Sparrow-WiFi-GUI abgerufen werden.

### Pi Setup-Hinweise

- Verwenden Sie Raspberry Pi OS (Bookworm oder später) mit Python 3.8+
- Deaktivieren Sie das integrierte WLAN, um 5-GHz-Scanning mit USB-Adaptern zu ermöglichen: fügen Sie `dtoverlay=disable-wifi` zu `/boot/firmware/config.txt` unter Bookworm und später, oder `/boot/config.txt` unter älteren Versionen hinzu
- Installieren Sie die Voraussetzungen: `sudo pip3 install --break-system-packages -r requirements.txt` (oder verwenden Sie eine venv wie im Abschnitt [Installation](#installation))

---

## Projektstruktur```
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

Lizenz

Dieses Projekt ist unter den im Repository enthaltenen Bedingungen lizenziert. Weitere Details finden Sie in der LICENSE-Datei.