Home

Caeruleus Wiki

Caeruleus consolidates Bluetooth Low Energy (BLE) security testing into a single Go binary built on the Linux BlueZ stack: discover devices, browse and read/write the GATT tree, capture notifications, fuzz writable characteristics, and run repeatable, structured security-assessment workflows. Every command emits -o json / -o jsonl for scripts, reports, and LLM agents.

This wiki is the deep reference. For the project overview, install one-liner, and feature tour, see the README.

Start here

• New to the tool? Installation & Setup, then the Recipes.
• Coming from bettercap / gatttool / hcitool / nRF Connect / Bleak? Coming from Another Tool maps your habits to caeruleus commands.
• Scripting or driving it from an agent? Output & Automation and Agents & LLM Usage.

Pages

Page	What's in it
Installation & Setup	Requirements, install methods, root commands, sudoers, first run
Coming from Another Tool	Migration table from bettercap/gatttool/hcitool/nRF Connect/Bleak
Command Reference	Every command and its flags, grouped, with the handles rules
Recipes	Copy-paste command examples for common BLE testing workflows
Output & Automation	JSON/JSONL, serve/send, batch, shell, trigger-capture
Hardware, Adapters & Troubleshooting	Adapters, doctor, recovery, addr types, MTU, FAQ
Agents & LLM Usage	The Agent Skill, structured output, methodology, benchmark
Contributing & Extending	Build/test and adding a new assess workflow

The 30-second tour

scan        find devices            recon        profile + audit (read-only)
enumerate   browse the GATT tree    assess ...   check-auth | encryption | pairing | dfu | wwr
read/write  poke a handle/UUID      pair/unpair  bond / drop bond
listen      capture notifications   fuzz write   fuzz a writable characteristic
shell       interactive REPL        doctor       adapter health + suggested fixes

Caeruleus operates only as the central in the BLE model. It does not sniff other devices' traffic, perform active MITM, or clone peripherals. Use dedicated hardware for those.