Recipes

Recipes

Copy-paste command examples for common BLE testing workflows. This is the same catalog caeruleus recipes prints; run caeruleus recipes <keyword> to filter (e.g. recipes trigger, recipes llm, recipes fuzz). Set ADDR to your target first (ADDR=AA:BB:CC:DD:EE:FF, from caeruleus scan).

Discover nearby devices

caeruleus scan
caeruleus scan --duration 30          # longer window
caeruleus scan -o json                # structured output

Map a device's GATT tree

caeruleus enumerate -b $ADDR
caeruleus enumerate -b $ADDR --values   # also read every characteristic

Read a characteristic

caeruleus read -b $ADDR -a 0x0029
caeruleus read -b $ADDR -u 00002a00-0000-1000-8000-00805f9b34fb

Write to a characteristic

caeruleus write -b $ADDR -a 0x002c -n deadbeef
caeruleus write -b $ADDR -a 0x002c -s "hello"       # ASCII
caeruleus write -b $ADDR -a 0x002c -n 01 --req       # write-with-response

Write to one handle, capture notification on another

# Subscribe on 0x0083, then write to 0x0081, then capture the response:
caeruleus listen -b $ADDR -a 0x0083 \
  --trigger-handle 0x0081 --trigger-value FEDCBA0003000101EF

# Capture multiple responses from repeated triggers:
caeruleus listen -b $ADDR -a 0x0083 \
  --trigger-handle 0x0081 --trigger-value 01 \
  --trigger-count 5 --count 0

Capture notifications (passive)

caeruleus listen -b $ADDR -a 0x0025
caeruleus listen -b $ADDR -a 0x0025 -d 30 --count 10   # up to 10 events or 30s
caeruleus listen -b $ADDR -a 0x0025 --extract           # hex-only (pipeable)

Capture notifications on chars that hide the NOTIFY property

# Use the HCI monitor socket to see wire events BlueZ hides:
sudo caeruleus listen -b $ADDR -a 0x0025 --hidden --monitor on

Sniff all notifications passively (no connection needed)

# Raw HCI monitor (like btmon, but decoded ATT only):
sudo caeruleus monitor -d 30
sudo caeruleus monitor --handle 0x0025 --count 5

Interactive exploration (human)

caeruleus shell -b $ADDR
# Then: enumerate, read 0x0029, write 0x002c deadbeef, listen 0x0025, etc.

Scripted exploration (LLM / automation)

# Terminal 1: start daemon with persistent connection
sudo caeruleus serve -b $ADDR

# Terminal 2 (or from an LLM agent via Bash):
caeruleus send "enumerate"
caeruleus send "read 0x0029"
caeruleus send "write 0x002c deadbeef"
caeruleus send "read 0x002c"              # read back after write

Batch multiple operations over one connection

caeruleus batch -b $ADDR <<'EOF'
read 0x0015
write 0x002b -s "test" --req
read 0x0029
EOF

Pipe multiple payloads to one handle

echo -e "deadbeef\ncafebabe\n01020304" | \
  caeruleus write -b $ADDR -a 0x002c --each-line

Brute-force a byte range and observe responses

# In shell/batch: write 0x00..0xFF to 0x002c, read 0x0029 each time:
caeruleus batch -b $ADDR <<'EOF'
brute 0x002c 0x0029 0 255
EOF

Pair / bond to access protected characteristics

caeruleus pair -b $ADDR                      # Just Works
caeruleus pair -b $ADDR --passkey 123456     # Passkey Entry

Run a full security recon

caeruleus recon -b $ADDR
caeruleus recon -b $ADDR -o json             # structured output

Check what's readable without pairing

caeruleus assess check-auth -b $ADDR
caeruleus assess check-auth -b $ADDR --probe-write  # also probe writes

Test write-without-response resilience (DoS)

caeruleus assess wwr -b $ADDR
caeruleus assess wwr -b $ADDR --burst 200   # heavier rapid-fire burst

Fuzz a writable characteristic

caeruleus fuzz write -b $ADDR -a 0x002c --seed deadbeef --max-iter 1000

Troubleshoot adapter issues

caeruleus doctor
caeruleus adapter info
sudo caeruleus adapter power off && sudo caeruleus adapter power on