praetorian-inc/caeruleus
GitHub: praetorian-inc/caeruleus
Caeruleus 是一款整合了 BLE 设备发现、GATT 交互、模糊测试和安全评估全流程的单一 Go 二进制工具包，旨在替代碎片化的传统蓝牙测试工具链。
Stars: 28 | Forks: 2
# Caeruleus：BLE 测试工具包
[](https://go.dev)
[](LICENSE)
[](https://goreportcard.com/report/github.com/praetorian-inc/caeruleus)
[](https://github.com/praetorian-inc/caeruleus/releases)
**Caeruleus** 将低功耗蓝牙（BLE）安全测试整合到了一个基于 Linux BlueZ 协议栈构建的单一 Go 二进制文件中。它通过 BlueZ D-Bus 和原始 L2CAP/HCI 套接字与外围设备进行通信，并涵盖了整个生命周期：发现设备、浏览并读写 GATT 树、捕获通知、对可写特征进行模糊测试，以及运行可重复的安全评估工作流。每个命令都会输出结构化的 `-o json` / `-o jsonl` 结果，方便用于脚本编写、报告生成和 LLM 代理。
Caeruleus 由攻击性安全工程师构建，旨在取代通常堆积使用的 `bettercap`、`gatttool`、`hcitool`、`bluetoothctl` 以及一次性的 Bleak 脚本，它将抽象层级保持在人类或代理实际工作的层面上。
*caeruleus*：拉丁语，意为低功耗蓝牙（Bluetooth Low Energy）中的“蓝色”
## 目录
- [为什么使用 Caeruleus？](#why-caeruleus)
- [功能](#features)
- [欢迎代理使用](#agents-welcome)
- [安装说明](#installation)
- [快速开始](#quick-start)
- [命令参考](#command-reference)
- [评估工作流](#assessment-workflows)
- [扩展 Caeruleus](#extending-caeruleus)
- [局限性](#limitations)
- [Praetorian 工具包的一部分](#part-of-the-praetorian-toolkit)
- [常见问题](#faq)
- [贡献](#contributing)
- [安全](#security)
- [License](#license)
## 为什么使用 Caeruleus？
标准的 BLE 安全测试工作流就像是在一堆从未被设计为协同工作的工具中进行寻宝：
- **`hcitool` / `hciconfig`** 用于适配器配置和发现，这两者均已被 BlueZ 弃用，且在许多现代发行版中已不复存在。
- **`bettercap`** 用于 `ble.recon` 和 `ble.enum`。功能强大，但你仅仅为了浏览 GATT 树就得安装一整套完整的网络攻击框架。
- **`gatttool`** 用于读写句柄，已被弃用多年，但依然存在于每一篇教程中。
- **自定义的 Bleak / pygatt 脚本** 用于更深层次的操作。
每种工具都讲着各自的“方言”，并且没有任何一种能输出你可以通过管道传递给下一步的机器可读输出结果，因此你成了集成层，只能手动在终端之间复制 MAC 地址和句柄。BlueZ 自身支持的前端工具（`bluetoothctl`、`btmgmt`）是通用管理工具，其抽象层级并不适合评估工作。
Caeruleus 用一个一致的命令界面取代了这一大堆工具：
| 使用场景 | 原有方法 | 使用 Caeruleus |
|---|---|---|
| 发现附近设备 | `hcitool lescan` / `bettercap ble.recon` / `bluetoothctl scan on` | `caeruleus scan` |
| 列出并读取服务/特征 | `bettercap ble.enum
` | `caeruleus enumerate -b --values` |
| 交互式会话 | `gatttool -I` / `bluetoothctl` | `caeruleus shell -b ` |
| 读取句柄 | `gatttool --char-read-hnd 0x0013` | `caeruleus read -b -a 0x0013` |
| 写入句柄 | `gatttool -b --char-write-req -a 0x002c -n $(...)` | `caeruleus write -b -a 0x002c --req -s "value"` |
| 捕获通知 | 自定义 Bleak 日志记录器 | `caeruleus listen -b -a ` |
| 审计未授权暴露面 | 自定义 Bleak 审计脚本 | `caeruleus recon` / `caeruleus assess ...` |
| 对特征进行模糊测试 | 自定义模糊测试工具 / boofuzz | `caeruleus fuzz write -b -a ` |
| 连接参数，MTU | `hcitool con` / `btmgmt con-info` | `caeruleus conn-params -b ` |
| 适配器电源与恢复 | `btmgmt power` / `hciconfig reset` / `rfkill` | `caeruleus doctor` / `caeruleus adapter power cycle` |
## 功能
**随处可见的结构化输出。** 每个产生输出的命令都支持 `-o text|json|jsonl`。JSON 是标准的表示形式，而不是次要的导出格式；`jsonl` 为 `scan --live` 和 `listen` 按每个事件流式传输一条记录。`enumerate --compact` 按每个特征输出一行 `key=value`，便于 grep 或用于 LLM 的上下文窗口。
**BLE 协议栈健康检查。** `caeruleus doctor` 会遍历 BlueZ 和内核状态，并打印出 OK/WARN/FAIL 检查清单：bluetoothd 是否运行、适配器是否通电、无泄露的发现会话、BlueZ 缓存的地址与 MGMT 芯片实时地址的对比、一次 2 秒的实时扫描探测，以及处于安全范围内的 ExchangeMTU。每一个非 OK 的检查结果都附带具体的修复命令，并且退出代码遵循 grep/diff 惯例（0 表示正常，2 表示失败）。
**干净的清理机制。** 在收到 `SIGTERM`/`SIGHUP` 信号时，该工具会执行断开连接路径并轮询，直到 `Connected=false` 状态通过 BlueZ 传播完毕，这样外围设备会立即重新广播，而不是因为其监督超时而陷入停滞。崩溃后不再有“幽灵连接”。
**脚本编写与自动化。** `serve`/`send` 通过 Unix 套接字保持一条 GATT 链路开启，从而避免脚本或代理为每个命令付出约 1.5 秒的重连成本；`batch` 通过单一持久连接运行来自 stdin 的命令；`listen --trigger-value` 会设置一个通知，触发一次写入，并以原子方式捕获响应。
**便捷细节。** 基于 GAP Appearance 和广播的服务进行设备类型推断（手表会显示为“Smartwatch”，而不是原始的外观代码）；宽容的输入解析（句柄可以是 `0x002a`、`0X2A` 或 `42`；十六进制可以是 `deadbeef`、`de:ad:be:ef` 或 `0xdeadbeef`）；`caeruleus recipes` 列出并支持对 19 种常见工作流进行关键字搜索；`conn-params` 显示协商好的间隔、延迟和监督超时，这些是 gatttool 和 bettercap 都无法提供的信息。
## 欢迎代理使用
Caeruleus 将 LLM 代理视为一等公民。`-o json` / `-o jsonl` 提供了 token 消耗少且结构化的输出，代理无需费力解析人类格式的表格即可直接读取，并且该仓库附带了一个可移植的 [Agent Skill](https://agentskills.io)（`skills/caeruleus/SKILL.md`），它可以向任何兼容 Agent Skills 的助手传授命令界面和推荐的评估方法。只需将代理指向一个设备，它就能端到端地运行整套方法。
在我们的基准测试中，配备 Caeruleus 及其技能的 Opus 4.8 (xHigh) 在**前者 62% 的时间和 70% 的 token 消耗**内完成了任务，而相同的模型在自由选择工具时（倾向于使用 `hcitool` 和 Bleak 脚本）则耗时更长。
## 安装说明
Caeruleus 专为 **Linux 与 BlueZ**（`bluetoothd`）环境及标准 BLE 适配器设计。它无法在 macOS 或 Windows 上构建或运行。少数原始套接字命令需要 root 权限。
**使用 Go 工具链：**
```
go install github.com/praetorian-inc/caeruleus/cmd/caeruleus@latest
```
**预编译的发布二进制文件**（x86_64 和 arm64）：从 [Releases](https://github.com/praetorian-inc/caeruleus/releases) 页面下载适用于您架构的压缩包，解压后将 `caeruleus` 放入您的 `$PATH` 中。
**从源码构建：**
```
git clone https://github.com/praetorian-inc/caeruleus
cd caeruleus
make build # -> ./caeruleus
make test # unit tests + shell tests
```
## 快速开始
检查适配器状态，然后发现附近的设备：
```
$ caeruleus doctor
adapter: hci0
[ OK] bluetoothd active
[ OK] Powered true
[ OK] Discovering false
[ OK] Address agreement 00:1A:7D:DA:71:13
[ OK] LE scan healthy saw advertisements
[ OK] ExchangeMTU 247
$ caeruleus scan
ADDRESS TYPE RSSI DEVICE NAME
------------------------------------------------------------
9C:9C:1F:F2:88:86 public -32 BLECTF_JohnsonSpace
C4:C0:B0:3B:5B:EF random -59 Aranet4 06D4B
DC:FD:B4:CA:B4:E9 random -62 JBL Boombox 2
```
一次性浏览完整的 GATT 树并读取每个特征，然后试探具体的句柄：
```
$ caeruleus enumerate -b 9C:9C:1F:F2:88:86 --values
SVC HND CHR HND CHR UUID PROPS HEX ASCII
0x0014 0x0015 0x2A00 R 424c457b46... BLE{F4K3_1D3NT1TY}
0x0028 0x002d 0xFF03 R 424c457b50... BLE{T0K3N_S4V3R}
0x0028 0x002f 0xFF05 R,W 577269746... Write anything here
$ caeruleus read -b 9C:9C:1F:F2:88:86 -a 0x002d
0x002d hex=424c457b503447335f5455524e33527d ascii="BLE{T0K3N_S4V3R}"
$ caeruleus write -b 9C:9C:1F:F2:88:86 -a 0x002f -s "praetorian"
0x002f written=10 type=request
```
当您需要在多次操作中保持单一连接时，可以使用交互式的 `shell`（gatttool 风格的命令）、stdin `batch` 模式，以及作为热连接守护进程的 `serve`/`send`。
## 命令参考
| 分组 | 命令 |
|---|---|
| 发现 | `scan`, `enumerate`, `primary`, `characteristics` |
| GATT 操作 | `read`, `write`, `raw-write`, `listen`, `cccd`, `mtu` |
| 连接管理 | `pair`/`unpair`, `conn-params`, `disconnect`, `forget` |
| 脚本与自动化 | `shell`, `batch`, `serve`/`send` |
| 安全评估 | `recon`, `assess check-auth`, `assess encryption`, `assess pairing`, `assess wwr`, `assess dfu` |
| 模糊测试 | `fuzz write`（包含 `--raw`）, `fuzz replay` |
| 适配器与诊断 | `doctor`, `adapter`, `bdaddr`, `monitor` |
每个命令的全局 flags：`-b/--bdaddr`, `-i/--adapter`（默认为 `hci0`）, `-t/--timeout`, `-o/--format`, `-q/--quiet`, `-v/--verbose`。特权命令（`conn-params`, `monitor`, `fuzz write --raw`, `cccd --raw`, `raw-write`, `mtu --set`, `bdaddr --set`）需要 root 权限。
初次使用该工具，或者刚从 bettercap / gatttool / bluetoothctl / nRF Connect / Bleak 转换过来？运行 `caeruleus recipes` 查看以用例为先的示例。有关完整的逐命令参考、评估方法以及硬件/适配器注意事项，请参阅 [**Wiki**](https://github.com/praetorian-inc/caeruleus/wiki) 和 [`skills/caeruleus/SKILL.md`](skills/caeruleus/SKILL.md)。
## 评估工作流
读写句柄是最简单的部分。Caeruleus 将临时性的“让我检查几样东西”阶段转化为可重复、结构化的评估。`recon` 会对设备进行指纹识别并审计其 GATT 树；每个 `assess` 子命令会探测一类弱点：
- **`assess check-auth`** — 未经配对的攻击者可以读取哪些内容（或者在使用 `--probe-write` 时可以写入哪些内容）
- **`assess encryption`** — 配对/加密要求是否真正得到了执行
- **`assess pairing`** — SMP 配对特性交换及抗降级能力
- **`assess wwr`** — 无响应写入（write-without-response）溢出与快速连发抗压能力
- **`assess dfu`** — 暴露的、未经身份验证的固件更新入口点
每次评估都会生成相同结构的结果：`{address, test, summary, findings[]}`，其中包含每个发现结果的 `severity`、`handle`、`uuid` 和 `evidence`。疑似秘密的值会与 Praetorian 的 [Titus](https://github.com/praetorian-inc/titus) 规则集进行交叉检查：在未配对链路上读取到的硬编码密钥会被直接提升为高严重性级别的发现。
```
$ caeruleus assess check-auth -b CC:B6:0E:3C:97:0B -o json | jq '.findings[] | select(.severity=="high")'
{
"title": "Secret readable without authentication",
"severity": "high",
"handle": 19,
"uuid": "00ca0001-bede-ad43-4145-52554c455500",
"evidence": "6177735f...774a61 (\"aws_access_key_id=AKIA... aws_secret_access_key=wJa\") +37 bytes",
"detail": "Titus matched rule \"AWS API Credentials\"; value read over an unpaired, unencrypted link."
}
```
当您发现一个值得进行压力测试的可写特征时，`fuzz write` 会利用磁盘上的语料库和自动的崩溃/挂起分类来对其进行输入变异；`fuzz replay` 可以重放您发现的任何崩溃：
```
$ sudo caeruleus fuzz write -b CC:B6:0E:3C:97:0B -a 0x0015 --raw --max-iter 20 --max-time 15s
[+] target=0x0015 liveness=0x0002 seeds=13 out=fuzz-out-20260701T144803Z
[+] done iter=2 states=2 queue=2 crashes=1 hangs=0 elapsed=1m2s
```
## 扩展 Caeruleus
`assess` 子命令建立在共享的基础组件之上：BLE 会话管理、发现结果 schema、机密检测和结构化输出。每项评估都是一个自包含的 Go 文件，遵循相同的模式。当您的团队不断重复进行某项手动检查时，将其添加为新的 `assess` 工作流意味着只需新增一个 Go 文件并在 `assess.go` 中添加一行代码；在下次构建时每个人都能用上它，并且自带结构化输出和代理驱动能力。我们特别欢迎对工作流的贡献。
## 局限性
Caeruleus 具有明确的导向：它使 BLE 交互中最常见的部分变得快速、可脚本化且对代理友好，并刻意排除了一些功能。它在 BLE 模型中仅作为 **central** 运行，而不能作为外围设备（peripheral），它也不进行 BLE 流量嗅探、执行主动的攻击者中间人（AITM/MITM）攻击，或克隆外围设备。
## Praetorian 工具包的一部分
Caeruleus 集成了 Praetorian 的 [Titus](https://github.com/praetorian-inc/titus) 用于机密检测，并加入了 Praetorian 不断壮大的开源攻击性工具家族，包括 [Nerva](https://github.com/praetorian-inc/nerva)（服务指纹识别）、[Vespasian](https://github.com/praetorian-inc/vespasian)（API 发现）、[Hadrian](https://github.com/praetorian-inc/hadrian)（API 授权测试）和 [Brutus](https://github.com/praetorian-inc/brutus)（凭据测试）。秉承相同的理念：提供具有结构化输出且无依赖地狱的单一二进制文件，并将其带到了 RF 层面。
## 常见问题
**Caeruleus 是什么？**
这是 Praetorian 推出的一款免费、开源的 BLE 安全测试工具：一个基于 Linux/BlueZ 构建的单一 Go 二进制文件，涵盖了整个 BLE 生命周期（扫描、枚举、读/写/通知、模糊测试以及结构化评估）。
**它与 bettercap、gatttool 和 hcitool 有什么不同？**
这些工具从未被设计为协同工作，也不输出机器可读的结果。Caeruleus 将工作流整合到一个二进制文件中，提供一致的命令、JSON/JSONL 输出，且不存在依赖地狱。
**AI 代理可以使用 Caeruleus 吗？**
是的。它输出 token 消耗极少的结构化数据，并提供了一个兼容 Agent Skills 的技能文件，用于传授命令界面和方法论。在我们的基准测试中，使用 Caeruleus 的代理在耗时仅为自由选择工具时的 62%，token 消耗仅为 70% 的情况下完成了任务。
**它有什么局限性？**
仅支持作为 central（不能作为 peripheral）；不支持流量嗅探、主动 MITM 或 peripheral 克隆。
**我该如何安装它？**
运行 `go install github.com/praetorian-inc/caeruleus/cmd/caeruleus@latest`，或者获取发布版的二进制文件。您需要配备 BlueZ 的 Linux 环境和一个 BLE 适配器；部分原始套接字命令需要 root 权限。请先运行 `caeruleus doctor`，然后再运行 `caeruleus scan`。
## 安全
Caeruleus 专为**授权的安全测试**而设计。请仅针对您拥有或已获得明确评估权限的设备使用它；扫描、连接以及向 BLE 外围设备写入数据会影响到真实的硬件。
## License
请参阅 [LICENSE](LICENSE)。标签：BlueZ, EVTX分析, GauPlus, Go, Ruby工具, 安全测试, 攻击性安全, 日志审计, 蓝牙低功耗