Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

ghostesp blescan

Starts a BLE scan on a GhostESP device in one of eight modes, collects observations for a configurable duration, stops the scan and reports everything as structured findings.

Requirements

An ESP32 that runs GhostESP. Not all ESP32 variants support Bluetooth — check your board’s specifications before use.

Scan modes

ModeGhostESP flagDescription
flipper-fDetect Flipper Zero devices nearby
spam-detector-dsDetect active BLE advertisement spam
airtag-aScan for Apple AirTags
advertiser-advParsed BLE advertiser scan (default)
oui-oui <prefix>Filter advertisers by OUI prefix
vendor-vendor <name>Filter advertisers by vendor name
gatt-gScan connectable GATT devices
raw-rRaw BLE packet capture

Plugin description

Opens a serial connection to a GhostESP device, waits for the ghost> prompt, then starts a BLE scan in the chosen mode. After the configured duration the scan is stopped with blescan -s and all observed output is reported as findings.

Findings are classified as follows:

FindingSeverityCondition
N BLE observationsInfoOne or more devices detected
No BLE devices detectedInfoScan returned no output
Prompt not found / port errorInfoDevice absent or wrong firmware

Usage

iottack ghostesp blescan --port <PORT> [OPTIONS]

Options

FlagShortDefaultDescription
--port <PORT>-p(required)Serial port, e.g. /dev/ttyACM0
--mode <MODE>-madvertiserScan mode (see table above)
--filter <VALUE>--OUI prefix or vendor name (required for oui/vendor modes)
--duration <SECS>-d10Scan duration in seconds
--baud-rate <BAUD>-b115200Serial baud rate
--timeout-ms <MS>-t5000Prompt wait timeout in ms
--output <FILE>-o-Save result to a file
--format <FORMAT>-texttext or json
--verbose-v-Increase log verbosity

Examples

$ iottack ghostesp blescan --port /dev/ttyACM1 --mode advertiser --duration 15

Plugin name:    ghostesp/blescan
Execution time: 15.42 s
Status:         pass

[INFO] 4 BLE observation(s) — advertiser mode
  [ADV] AA:BB:CC:11:22:33 (Apple, Inc.) RSSI: -62 dBm
  [ADV] DD:EE:FF:44:55:66 (Samsung Electronics) RSSI: -74 dBm
  [ADV] 11:22:33:AA:BB:CC (Unknown) RSSI: -81 dBm
  [ADV] 44:55:66:DD:EE:FF (Google) RSSI: -69 dBm
$ iottack ghostesp blescan --port /dev/ttyACM1 --mode flipper --duration 10

Plugin name:    ghostesp/blescan
Execution time: 10.38 s
Status:         pass

[INFO] 1 BLE observation(s) — flipper mode
  [FLIPPER] AA:BB:CC:DD:EE:FF "xXx_FlipperZero_xXx" RSSI: -55 dBm
$ iottack ghostesp blescan --port /dev/ttyACM1 --mode vendor --filter Apple --duration 20

Plugin name:    ghostesp/blescan
Execution time: 20.15 s
Status:         pass

[INFO] 2 BLE observation(s) — vendor mode
  [ADV] AA:BB:CC:11:22:33 (Apple, Inc.) RSSI: -62 dBm
  [ADV] 44:55:66:DD:EE:FF (Apple, Inc.) RSSI: -70 dBm