Caeruleus packs the entire Linux/BlueZ Bluetooth Low Energy assessment workflow — scanning, GATT enumeration, fuzzing, and structured security checks — into a single Go binary for authorized testers.
| Tool | praetorian-inc/caeruleus — single-binary BLE security testing toolkit for Linux/BlueZ written in Go |
| Category | Bluetooth Low Energy assessment and fuzzing tooling |
| Primary Use | Discovering peripherals, enumerating and exercising GATT trees, and running structured assessments (recon, assess, fuzz) with JSON output during authorized engagements |
| Safe Use | Intended for penetration testers and security engineers auditing devices they own or are explicitly authorized to assess, plus lab and defensive research on BLE exposure |
| Telemetry Note | Active scanning and GATT connections are visible to targets as BLE advertisements probes, pairing exchanges, and connection events; assess findings include per-test evidence records useful for defensive baselining of unauthorized unpaired reads |
Bluetooth Low Energy assessments on Linux have historically been an exercise in tool archaeology. The README of praetorian-inc/caeruleus opens by naming the problem directly: practitioners stitch together deprecated utilities like hcitool, hciconfig, and gatttool, pull in a full network-attack framework like bettercap just to browse a GATT tree, and then write one-off Bleak or pygatt scripts for anything deeper. Caeruleus, built by Praetorian's offensive security engineers, replaces that pile with a single Go binary that talks to peripherals over BlueZ D-Bus and raw L2CAP/HCI sockets, covering the full lifecycle from discovery through fuzzing and repeatable assessment workflows.
The command surface is organized into coherent groups. Discovery is handled by scan, enumerate, primary, and characteristics; GATT operations by read, write, raw-write, listen, cccd, and mtu; connection management by pair/unpair, conn-params, disconnect, and forget. Scripting gets shell, batch, and a serve/send pair, while assessment work maps to recon and a family of assess subcommands. Global flags like -b/--bdaddr, -i/--adapter (defaulting to hci0), -t/--timeout, and -o/--format apply uniformly, which means muscle memory transfers across the whole toolkit rather than resetting per tool.
What stands out architecturally is the commitment to structured output. Every command that produces output supports -o text|json|jsonl, and the README is explicit that JSON is the canonical representation, not an afterthought export. The jsonl mode streams one record per event for live workflows like scan --live and listen, and enumerate --compact emits one key=value line per characteristic — a deliberate nod toward grep pipelines and LLM context windows. This design choice quietly redefines the tool as infrastructure for automation rather than just another interactive client.
That agent orientation is not incidental; the README devotes a full section to it. The repo ships a portable Agent Skill at skills/caeruleus/SKILL.md that teaches any Agent Skills-compatible assistant the command surface and a recommended assessment methodology, letting an agent run the full workflow end to end against a device. The authors report a benchmark where an LLM equipped with Caeruleus and its skill completed a task in 62% of the time and 70% of the tokens of the same model freely choosing tools, which they attribute to structured output eliminating table-scraping and hand-rolled script generation.
Operational hygiene gets unusual attention. The doctor command walks BlueZ and kernel state and prints an OK/WARN/FAIL checklist covering bluetoothd status, adapter power, leaked discovery sessions, agreement between the BlueZ-cached address and the MGMT chip-live address, a live two-second scan probe, and whether ExchangeMTU sits in a safe band. Each non-OK finding ships with a concrete fix command, and the exit code follows the grep/diff convention — zero when clear, two on failure — so it composes cleanly with CI or pre-flight scripts.
Connection lifecycle management is similarly thoughtful. On SIGTERM/SIGHUP, Caeruleus runs the disconnect path and polls until Connected=false propagates through BlueZ, so the peripheral re-advertises immediately instead of stalling through its supervision timeout. The README frames this as eliminating "ghost connections" after a crash — a small detail, but one anyone who has watched a test device refuse new connections for thirty seconds after a client segfault will immediately appreciate. The serve/send daemon holds one GATT link open over a Unix socket specifically to amortize the roughly 1.5-second reconnect cost per command.
The assessment layer is where the tool differentiates most from its predecessors. recon fingerprints a device and audits its GATT tree, and each assess subcommand probes one class of weakness: assess check-auth maps what an unpaired attacker can read or write, assess encryption verifies whether pairing and encryption requirements are actually enforced, assess pairing inspects the SMP feature exchange and downgrade resistance, assess wwr tests write-without-response resilience, and assess dfu looks for exposed, unauthenticated firmware-update entry points. Every assessment emits the same {address, test, summary, findings[]} shape with per-finding severity, handle, uuid, and evidence.
A particularly smart integration sits inside the findings pipeline: secret-looking values read from characteristics are cross-checked against Praetorian's Titus rule set, so a hardcoded credential read over an unpaired link is escalated to a high-severity finding on its own. The README demonstrates this with an example where an aws_access_key_id pattern surfaced in characteristic data at handle 19 becomes a self-contained finding with evidence bytes. This turns the tool from a GATT browser into something that performs automated secret-detection triage during hardware engagements.
Installation is straightforward for the target platform. The tool requires Linux with BlueZ (bluetoothd) and a standard BLE adapter, and the README is blunt that it does not build or run on macOS or Windows; a handful of raw-socket commands such as conn-params, monitor, fuzz write --raw, and bdaddr --set need root. The simplest path is go install github.com/praetorian-inc/caeruleus/cmd/caeruleus@latest, though prebuilt x86_64 and arm64 release binaries and a make build source path are also available.
Fuzzing support covers writable characteristics via fuzz write (including a --raw mode) and a fuzz replay capability for captured traffic. The README also documents a compatibility escape hatch for older BlueZ versions like 5.55 that hide remote GAP/GATT services from the D-Bus tree: enumerate --raw, run as root, discovers the attribute database directly over the ATT channel, yielding a complete host-independent view with the device's true handles. Convenience touches like device-type inference from GAP Appearance, forgiving hex and handle input parsing, and caeruleus recipes listing 19 searchable workflows round out the daily-driver feel.
For defenders and device manufacturers, the telemetry implications are worth noting. Caeruleus's activity is observable at the radio level: scanning appears as advertisement requests, GATT operations require connection events, and pairing probes generate SMP exchanges that can be logged by instrumented firmware or BLE sniffers positioned near the target. The structured findings format also doubles as a defensive artifact — product teams can run the same assess battery against their own firmware before shipment to verify that authentication, encryption enforcement, and DFU gating hold up as designed.
Licensed under Apache-2.0 and written in Go 1.25+, the project is positioned as part of the broader Praetorian toolkit alongside Titus. With 55 stars it is early in its public life, but the README's depth — a full command reference, assessment methodology, adapter hardware notes on the wiki, and a documented migration table from bettercap, gatttool, and bluetoothctl idioms — signals a tool built from real engagement friction rather than resume-driven development. For authorized BLE work on Linux, it is a credible consolidation play.
praetorian-inc/caeruleus.Educational analysis for authorized security professionals. Use only in controlled, authorized environments.
Related coverage
0 comentários:
Post a Comment
Note: Only a member of this blog may post a comment.