Contributing and Extending

Contributing & Extending

Issues and pull requests are welcome, especially new assess workflows. Please run make test before opening a PR.

Build & test

git clone https://github.com/praetorian-inc/caeruleus
cd caeruleus
make build        # -> ./caeruleus
make test         # unit tests + shell tests

Adding a new assess workflow

The assess subcommand is built on shared primitives — BLE session management, the findings schema, secret detection, and structured output — so a new check is small and inherits JSON output and agent-drivability for free.

Each assessment is a self-contained Go file that follows the same pattern:

1. Open a session to the target, do your probing.
2. Build findings[], each with severity (info/low/medium/high/critical), handle, uuid, evidence, detail.
3. Return {address, test, summary, findings[]}.

Then wire it in: one Go file plus one line in assess.go, and everyone gets the new check in the next build, with -o json/jsonl and the shared findings shape included. When your team keeps repeating a manual check, this is the way to make it repeatable for everyone.

Keep new checks:

• Non-destructive by default. If a check can reset or crash the target, gate the destructive part behind an explicit flag (as assess dfu --probe-entry and assess wwr do) and document it.
• Consistent with the schema. Reuse the existing findings fields and severity scale so results correlate with the other assessments.
• Secret-aware where relevant. Read values can be run through the Titus rule set for automatic secret escalation, the same as check-auth and recon.

Scope

Caeruleus is deliberately opinionated: it makes the most common facets of BLE interaction fast, scriptable, and agent-friendly, as the central only. Out of scope by design: traffic sniffing of other devices, active MITM, and peripheral cloning. Contributions that fit the central-side, structured-output philosophy are the best fit.