Kismet live REST API integration

[dougborg]

Idea

Connect to a running Kismet instance over its REST API and stream device detections into DeFlock in real-time. This enables serious wardriving setups (laptop with a proper WiFi adapter in monitor mode) to feed directly into DeFlock's map and detection database.

This issue is a proposal/placeholder to gather community feedback, ideas, and suggestions — not a prescriptive spec.

Why

Kismet with a proper WiFi adapter in monitor mode is dramatically more powerful than phone-native scanning — wider frequency range, passive monitoring (no probe requests), and support for all WiFi frames. Many wardriving enthusiasts already run Kismet on a laptop or Raspberry Pi. Connecting DeFlock to a live Kismet instance gives these users a purpose-built mobile UI for surveillance device detection while leveraging their existing hardware.

How it might work

1. User runs Kismet on a nearby device (laptop, Raspberry Pi, etc.) with a monitor-mode WiFi adapter
2. In DeFlock, user enters the Kismet instance's IP/hostname and port
3. App connects to Kismet's REST API over the local network
4. Streams device events, filters through the OUI/SSID watchlist
5. Matching devices appear on the map in real-time, stored in rf_devices/rf_sightings

Kismet REST API

• Default port: 2501
• /devices/last-time/{timestamp}/devices.ekjson — stream devices seen since a timestamp (EKJSON format, one JSON object per line)
• /devices/by-key/{key}/device.json — get full device details
• Device records include: MAC, manufacturer, channel, signal strength, GPS coordinates (if Kismet has a GPS source), encryption type, packet counts
• Supports authentication (user/password or API key)
• Long-polling / streaming endpoints available for real-time updates

Architecture

This would be a new transport type in the scanner architecture from PR #37, alongside BLE and USB serial:

• New ScannerService implementation: KismetScannerService
• Connects over HTTP/HTTPS instead of BLE/serial
• Same RfDetection output pipeline
• Configuration: host, port, credentials

Considerations

• Network connectivity — Kismet runs on a separate device; the phone needs to reach it over WiFi (same network, hotspot, etc.)
• GPS source — Kismet may or may not have its own GPS. If not, DeFlock's phone GPS should be used for location tagging
• Multiple adapters — Kismet can use multiple WiFi adapters simultaneously; all their data flows through the same API
• Security — Kismet's REST API supports authentication; credentials should be stored securely in DeFlock

Open Questions

• Should DeFlock discover Kismet instances on the local network (mDNS/bonjour), or require manual configuration?
• How to handle GPS — prefer Kismet's GPS, phone GPS, or let the user choose?
• Should we support Kismet's WebSocket endpoints for lower-latency streaming?
• Is there interest in also importing Kismet's .kismet database files directly (covered separately in the import issue)?

Effort Estimate

Medium

Dependencies

• Curated surveillance device OUI + SSID watchlist (the watchlist issue)
• PR Add FlockSquawk scanner integration (USB + BLE) #37 merged (scanner architecture)

Related

• PR Add FlockSquawk scanner integration (USB + BLE) #37 — FlockSquawk scanner integration (scanner architecture, ScannerService interface)
• Part of the Wardriving & Surveillance Detection epic