Seraph

Divine fire for buggy stacks.

Battle-tested Bluetooth + IoT protocol fuzzer built on boofuzz. Single- file launcher, no pip install ceremony. Run it as:

sudo python3 seraph.py <subcommand> [options]

What it does

• L2CAP signaling fuzzer covering every Core 5.4 Vol 3 Part A signaling command code (cmd reject, connection req, config req with full MTU/Flush/RFC/FCS option TLV mutation, info req, echo, create/ move channel, LE credit-based + enhanced credit-based connection, reconfigure).
• ATT/GATT fuzzer covering every ATT opcode in Core 5.4 Vol 3 Part F (incl. 5.3+ Read Multiple Variable, Signed Write).
• SDP fuzzer with proper data-element encoding (UUID16/32, sequences, continuation state).
• HCI command fuzzer through HCI_CHANNEL_USER for fuzzing the controller / kernel HCI path directly.
• Real-time stats on a single TTY line: cases/sec, crashes (unique vs total), timeouts, bytes transmitted.
• Crash dedup by hashed KASAN top-of-stack - every unique splat is filed once.
• Per-case btmon capture so every failure ships with the HCI traffic that produced it.
• KCOV monitor for visibility into kernel coverage growth (does not feed back into mutation; boofuzz is generation-based).
• Crash minimizer that ddmin-reduces a captured frame sequence down to the smallest set that still triggers the bug.
• Pcap replay of any btmon capture so reproducers do not need Seraph or boofuzz to run.
• Pre-flight that checks root, adapter state, rfkill, kernel debug config, and target reachability before a campaign starts.

Subcommands

sudo python3 seraph.py preflight --hci 0 --bdaddr AA:BB:CC:DD:EE:FF
sudo python3 seraph.py l2cap     --bdaddr AA:BB:CC:DD:EE:FF
sudo python3 seraph.py att       --bdaddr AA:BB:CC:DD:EE:FF --addr-type public
sudo python3 seraph.py sdp       --bdaddr AA:BB:CC:DD:EE:FF
sudo python3 seraph.py hci       --hci 0
sudo python3 seraph.py replay    capture.pcap --bdaddr AA:BB:CC:DD:EE:FF --cid 0x0001
sudo python3 seraph.py minimize  repro/repro_abc123.py --bdaddr AA:BB:CC:DD:EE:FF

Run python3 seraph.py <subcommand> --help for the full option list.

Install

Only boofuzz is required externally:

python3 -m venv .venv
source .venv/bin/activate
pip install boofuzz

Then just run python3 seraph.py .... No editable install, no entry points.

Layout

seraph.py              # entry point - argparse, no third-party CLI dep
seraph/
  ui.py                # banner, ANSI logging, live stats counter
  preflight.py         # pre-flight checks
  replay.py            # pcap replay
  minimizer.py         # ddmin crash minimizer
  transports/
    l2cap.py           # AF_BLUETOOTH/L2CAP w/ reconnect, BR/EDR + LE
    hci.py             # HCI_CHANNEL_USER raw transport
  monitors/
    dmesg.py           # KASAN/UBSAN/oops detector with dedup ledger
    btmon.py           # per-case pcap capture
    daemon.py          # bluetoothd liveness ping
    kcov.py            # /sys/kernel/debug/kcov coverage reader
  protocols/
    l2cap_signaling.py # full Core 5.4 signaling coverage
    att.py             # full ATT opcode coverage
    sdp.py             # SDP PDUs with data-element encoding
    hci_cmd_fuzz.py    # HCI command opcode space
  utils/
    repro.py           # standalone reproducer emitter
    pcap.py            # libpcap reader
    dedup.py           # JSON-backed crash signature ledger
corpus/                # seed pcaps
repro/                 # auto-generated reproducers
tests/                 # pytest smoke suite (12 tests, hardware-free)
docs/                  # ROADMAP.md, SETUP.md

Hard rules

• Never fork boofuzz; only subclass and import.
• Every crash gets a standalone reproducer that does not depend on boofuzz to replay.
• One protocol working end-to-end beats five half-done.
• Use inside a disposable VM. Fuzzing crashes the target by design.

Status

Phase 1 + 2 + 3 (per docs/ROADMAP.md): real transports, real monitors, four real protocol modules, real-time UI, minimizer, replay, pre-flight, KCOV. Ready for first campaign.