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 write

Writes a value to a specific GATT characteristic on a Bluetooth Low Energy device or fuzzes it with the built-in payload set.

The plugin connects to the given device, locates the characteristic by UUID across all GATT services and operates in one of two modes:

Single-write mode (default): writes the supplied --value once and reports success or failure. The value is treated as a UTF-8 string. Pass --hex to supply raw bytes.

Fuzz mode (--fuzz): iterates the built-in payload set (null bytes, long strings, format strings, boundary values, control characters) and writes each one to the characteristic. After each write the characteristic is read back if it is readable, and the response is scanned for error strings, crash indicators and shell prompts. A --wordlist or --charset can replace the built-in set.

Findings are classified as follows:

FindingSeverityCondition
Write successfulInfoSingle write completed
Write failedLowWrite rejected by the device
Interesting responseMedium–CriticalFuzz response matched a pattern
No interesting responsesInfoFuzz completed with no matches
Characteristic not writableLowCharacteristic lacks write property
Characteristic not foundInfoUUID absent from device profile
Cannot connectInfoDevice unreachable or out of range
Bluetooth not availableInfoBlueZ daemon unreachable

Requirements

  • BlueZ daemon (bluetoothd) must be running.
  • The D-Bus system bus must be accessible (no special privileges required).
  • The target device must be advertising and within range.

Usage

iottack ble write --address <ADDR> --characteristic <UUID> --value <DATA>
iottack ble write --address <ADDR> --characteristic <UUID> --fuzz

Options

FlagShortDefaultDescription
--address <ADDR>-drequiredBluetooth address of the target device
--characteristic <UUID>-crequiredGATT characteristic UUID to write
--value <DATA>-V""Value to write (ignored with --fuzz)
--hex-xoffTreat --value as hex bytes, e.g., ff00ab
--no-response-noffWrite-without-response for every write
--adapter <NAME>-afirst availableAdapter to use, e.g., hci0
--no-disconnect-offLeave device connected after the operation
--fuzz-foffEnable fuzz mode
--iterations <N>-1Times to repeat the payload set (fuzz mode)
--charset <CHARS>--Characters to fuzz (fuzz mode)
--length <N>-l16Max repeat length for charset payloads
--wordlist <PATH>-w-Wordlist file. Replaces built-in payloads
--delay-ms <MS>-0Delay between payloads in ms (fuzz mode)
--suffix <BYTES>-s-Bytes appended to every payload, e.g., \r\n
--pattern <STRING>--Extra response pattern to flag (fuzz mode)
--output <FILE>-o-Save result to a file
--format <FORMAT>-texttext or json
--verbose-v-Increase log verbosity

Examples

Write the string R to set an LED color on the IoTTack target board:

iottack ble write \
  --address DD:EE:FF:44:55:66 \
  --characteristic 19b10001-e8f2-537e-4f6c-d104768a1214 \
  --value R

Write raw bytes using hex notation:

iottack ble write \
  --address DD:EE:FF:44:55:66 \
  --characteristic 19b10001-e8f2-537e-4f6c-d104768a1214 \
  --value "52 00" --hex

Fuzz with the built-in payload set:

iottack ble write \
  --address DD:EE:FF:44:55:66 \
  --characteristic 19b10001-e8f2-537e-4f6c-d104768a1214 \
  --fuzz

Fuzz with a custom wordlist and a 50 ms delay between payloads:

iottack ble write \
  --address DD:EE:FF:44:55:66 \
  --characteristic 19b10001-e8f2-537e-4f6c-d104768a1214 \
  --fuzz --wordlist payloads.txt --delay_ms 50

Example output, single write:

$ iottack ble write \
    --address DD:EE:FF:44:55:66 \
    --characteristic 19b10001-e8f2-537e-4f6c-d104768a1214 \
    --value R

Plugin name:    ble/write
Execution time: 1.42 s
Status:         pass

[INFO] Write successful to 19b10001-e8f2-537e-4f6c-d104768a1214
  Device:         DD:EE:FF:44:55:66
  Characteristic: 19b10001-e8f2-537e-4f6c-d104768a1214
  Method:         write-with-response
  Bytes written:  1
  Payload (hex):  52

IoTTack Target Bluetooth

The IoTTack Target Bluetooth board advertises a custom LED control service. Use iottack ble scan to find the board’s address, then iottack ble device to confirm the characteristic UUID, then use ble write to control the LED or fuzz the characteristic.

PropertyValue
Device nameIoTTack Target Bluetooth
Service UUID19b10000-e8f2-537e-4f6c-d104768a1214
Characteristic UUID19b10001-e8f2-537e-4f6c-d104768a1214
Propertiesread, write, write-no-rsp

Accepted commands:

ValueEffect
RSet NeoPixel to red
GSet NeoPixel to green
BSet NeoPixel to blue
OTurn NeoPixel off

Turn the LED red:

iottack ble write \
  --address <ADDR> \
  --characteristic 19b10001-e8f2-537e-4f6c-d104768a1214 \
  --value R

Cycle through all colors in sequence:

for cmd in R G B O; do
  iottack ble write \
    --address <ADDR> \
    --characteristic 19b10001-e8f2-537e-4f6c-d104768a1214 \
    --value "$cmd"
done

Write the same commands using raw HEX bytes (R=52, G=47, B=42, O=4f):

iottack ble write \
  --address <ADDR> \
  --characteristic 19b10001-e8f2-537e-4f6c-d104768a1214 \
  --value 52 --hex

Multi-byte hex payloads are also accepted using space, colon, or no separator:

iottack ble write \
  --address <ADDR> \
  --characteristic 19b10001-e8f2-537e-4f6c-d104768a1214 \
  --value "52 00 00" --hex

Fuzz the characteristic to check how the firmware handles unexpected input:

iottack ble write \
  --address <ADDR> \
  --characteristic 19b10001-e8f2-537e-4f6c-d104768a1214 \
  --fuzz --delay-ms 100

The target prints every received write command to its serial output, so connect a serial monitor to observe how each payload is handled at the firmware level.

Example output, single write to the target:

$ iottack ble write \
    --address AA:BB:CC:DD:EE:FF \
    --characteristic 19b10001-e8f2-537e-4f6c-d104768a1214 \
    --value G

Plugin name:    ble/write
Execution time: 1.38 s
Status:         pass

[INFO] Write successful to 19b10001-e8f2-537e-4f6c-d104768a1214
  Device:         AA:BB:CC:DD:EE:FF
  Characteristic: 19b10001-e8f2-537e-4f6c-d104768a1214
  Method:         write-with-response
  Bytes written:  1
  Payload (hex):  47

Serial output on the target board after receiving the write:

[BLE Write] Raw: 'G'  Parsed: 'G'
[Action Executed] Onboard LED configured to GREEN.

Example output, fuzz mode:

$ iottack ble write \
    --address DD:EE:FF:44:55:66 \
    --characteristic 19b10001-e8f2-537e-4f6c-d104768a1214 \
    --fuzz

Plugin name:    ble/write
Execution time: 38.7 s
Status:         pass

[INFO] No interesting responses
  All payloads x 1 iteration(s) produced no interesting response
  from DD:EE:FF:44:55:66/19b10001-e8f2-537e-4f6c-d104768a1214.