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

ble scan

Starts an active BLE discovery session on the selected adapter and listens for advertising packets for the configured duration. Each newly seen device address triggers a finding that captures:

  • Address: Bluetooth MAC address of the device
  • Name: advertised device name (falls back to alias if name is absent)
  • Connected: whether the device currently has an active connection
  • Paired: whether the device is already paired with the host
  • RSSI: received signal strength in dBm (when reported by the adapter)
  • TX Power: transmit power level in dBm (when included in the advertisement)
  • UUIDs: advertised GATT service UUIDs

Findings are classified as follows:

FindingSeverityCondition
Device detailsMediumDevice is connected or paired
Device detailsInfoUnknown / unrecognised device
Summary countInfoAlways emitted at end of scan
No devices foundInfoScan completed with zero results
Bluetooth not availableInfoBlueZ daemon unreachable
No adapters foundInfoNo Bluetooth hardware detected
Cannot start scanInfoAdapter powered off or busy

Requirements

  • BlueZ daemon (bluetoothd) must be running.
  • The D-Bus system bus must be accessible (no special privileges required).
  • At least one powered Bluetooth adapter must be present on the host.

Usage

iottack ble scan

Options

FlagShortDefaultDescription
--timeout <SECS>-t10Scan duration in seconds
--adapter <NAME>-afirst availableAdapter to use, e.g. hci0
--output <FILE>-o-Save result to a file
--format <FORMAT>-texttext or json
--verbose-v-Increase log verbosity

Examples

Scan with the default 10-second window:

iottack ble scan

Scan for 30 seconds using a specific adapter:

iottack ble scan --timeout 30 --adapter hci1

Save results as JSON:

iottack ble scan --timeout 20 --format json --output results.json

Example output:

$ iottack ble scan --timeout 5

Plugin name:    ble/scan
Execution time: 5.03 s
Status:         pass

[INFO] AA:BB:CC:11:22:33
  Address:   AA:BB:CC:11:22:33
  Name:      n/a
  Connected: no
  Paired:    no
  RSSI:      -74 dBm

[MEDIUM] My Phone (DD:EE:FF:44:55:66)
  Address:   DD:EE:FF:44:55:66
  Name:      My Phone
  Connected: yes
  Paired:    yes
  RSSI:      -52 dBm
  TX Power:  4 dBm
  UUIDs:     0000110b-0000-1000-8000-00805f9b34fb, 0000110e-0000-1000-8000-00805f9b34fb

[INFO] 2 BLE device(s) discovered
  Scan completed on adapter hci0 after 5 second(s).

Remediation

Devices appearing as Medium are already connected or paired with the host. Unpair devices that are no longer in use:

bluetoothctl remove <ADDRESS>

For devices with sensitive service UUIDs, verify the device is authorised before allowing further interaction.