Files
meshcore-tth/tools/mesh_sniffer.py
T

446 lines
18 KiB
Python
Executable File

#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Passive MeshCore sniffer -- every frame the radio hears, decoded on the host.
tools/mesh_sniffer.py --board 0 --preset cz [--jsonl cap.jsonl] [--pcap cap.pcap]
[--psk <hex>] [--seconds 600]
Needs a board running the openHop modem firmware (openhop-dev/openhop_modem) and
`pip install openhop-core` -- the Python reimplementation of the MeshCore stack.
The board is a dumb SX1262 PHY: it hands up EVERY frame that passes CRC, tagged
with RSSI/SNR, and all decoding happens here.
Why this exists, when we already have a node + BLE bridge feeding the analyzer:
* A companion node only ever surfaces what ITS firmware decided to process --
its own channels and DMs, adverts, packets addressed to it. Foreign-PSK
channel traffic and DIRECT packets for other destinations are dropped before
the companion protocol ever sees them. The modem has no such opinion, so
"SDR sees twice what the observer decodes" (docs, measured) becomes a
testable claim instead of a mystery: the modem's own rx_count is printed
next to the number of frames we managed to parse.
* No BLE anywhere on the path -- no dock-quiet interaction, no BlueZ holding
the link, no MC_BLE_OFF_INTERVAL windows costing 42 % of the capture.
RECEIVE ONLY, by construction. There is no call to radio.send() in this file and
no dispatcher/handler is registered, so nothing can answer, ACK or forward. That
matters on 869.432: an unannounced node that starts answering confuses routing.
The modem is left with tx_power at its floor as a second line of defence.
Two traps that shaped the code, both worth keeping in mind if you extend it:
* openhop_core's own Dispatcher runs a PacketFilter that swallows byte-identical
frames for 30 s. That is right for a repeater and wrong for a sniffer -- two
neighbours relaying the same flood is exactly the observation we are after.
So this script parses packets itself instead of going through the dispatcher,
and counts duplicates instead of hiding them.
* USBLoRaRadio's rx_callback is handed only the payload; RSSI/SNR live in
radio.last_rssi/last_snr, which the NEXT packet overwrites before a queued
callback runs. So we override _dispatch_frame and take the metadata straight
out of the CMD_RX_PACKET frame, where it is atomic with the bytes.
"""
from __future__ import annotations
import argparse
import glob
import hashlib
import hmac
import json
import os
import socket
import struct
import sys
import threading
import time
from collections import Counter
try:
from openhop_core.hardware.usb_radio import CMD_RX_PACKET, USBLoRaRadio
from openhop_core.protocol import decode_appdata, parse_advert_payload
from openhop_core.protocol.packet import Packet
except ImportError:
# --help má jít i bez závislostí: aspoň hlavička (plné volby až s openhop-core).
if {"-h", "--help"} & set(sys.argv[1:]):
print(__doc__.strip())
sys.exit(0)
sys.exit(
"chybi openhop-core: python3 -m venv .venv && .venv/bin/pip install openhop-core pyserial"
)
# Fleet shorthand, same numbering as tools/xiao_uf2_flash.sh. Keyed on serial
# number because the by-id NAME changes with the firmware: the modem build
# renames the port from usb-Seeed_Studio_XIAO_nRF52840_<sn> to
# usb-Seeed_XIAO-Wio-SX1262_<sn>, so anything matching on the name breaks the
# moment the board becomes a modem.
# Tabulka žije v fleet.py, ať se pátá kopie nerozejde s deskami.
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
from fleet import FLEET_BARE as FLEET
# freq_hz, bandwidth_hz, sf, cr -- mirrored from platformio.ini / .local.ini so a
# capture cannot silently run on the wrong parameters. Two boards on different
# spreading factors simply cannot hear each other.
PRESETS = {
"cz": (869_432_000, 62_500, 7, 5), # live CZ mesh, [cz_radio]
"bench": (866_500_000, 62_500, 8, 5), # test band, [test_radio] + committed defaults
"prod": (869_618_000, 62_500, 8, 5), # committed platformio.ini default
}
ROUTE_TYPES = {0: "TRANSPORT_FLOOD", 1: "FLOOD", 2: "DIRECT", 3: "TRANSPORT_DIRECT"}
PAYLOAD_TYPES = {
0x00: "REQ",
0x01: "RESPONSE",
0x02: "TXT_MSG",
0x03: "ACK",
0x04: "ADVERT",
0x05: "GRP_TXT",
0x06: "GRP_DATA",
0x07: "ANON_REQ",
0x08: "PATH",
0x09: "TRACE",
0x0A: "MULTIPART",
0x0B: "CONTROL",
0x0F: "RAW_CUSTOM",
}
ADVERT_ROLES = {0x01: "chat", 0x02: "repeater", 0x03: "room", 0x04: "sensor"}
LINKTYPE_USER0 = 147 # what openhop_core's own wireshark example uses
def resolve_port(board: str, port: str | None) -> str:
"""Map a fleet number or serial number to a /dev/serial/by-id path."""
if port:
return port
serial_no = FLEET.get(board, board)
matches = [p for p in glob.glob("/dev/serial/by-id/*") if serial_no in p]
if not matches:
sys.exit(f"zadny port pro sn {serial_no} -- pripojena deska? (ls /dev/serial/by-id/)")
if len(matches) > 1:
sys.exit(f"vic portu pro sn {serial_no}: {matches}")
return matches[0]
class SnifferRadio(USBLoRaRadio):
"""USBLoRaRadio that hands RX frames straight to a callback, metadata included.
See the module docstring: the stock rx_callback loses the RSSI/SNR pairing
under load, and it is scheduled onto an asyncio loop we do not want to run.
"""
def __init__(self, *args, on_frame=None, **kwargs):
super().__init__(*args, **kwargs)
self._on_frame = on_frame
def _dispatch_frame(self, cmd: int, payload: bytes):
if cmd == CMD_RX_PACKET and len(payload) >= 6:
# Keep the driver's own bookkeeping up to date -- get_status() is our
# honest denominator -- but do NOT delegate to super() here: with no
# rx_callback set it logs "RX packet but no callback registered" for
# every single frame, which is noise in a capture.
rssi, snr_x10, signal_rssi = struct.unpack("<hhh", payload[0:6])
self.last_rssi, self.last_snr = rssi, snr_x10 / 10.0
self.last_signal_rssi = signal_rssi
self._rx_count += 1
if self._on_frame:
self._on_frame(payload[6:], rssi, snr_x10 / 10.0, signal_rssi)
return
super()._dispatch_frame(cmd, payload)
class PcapWriter:
"""Minimal pcap writer/streamer. Payload is the raw MeshCore frame.
LINKTYPE_USER0 means Wireshark shows the bytes but does not dissect them --
good enough for eyeballing lengths and repeats, and the decoded fields are in
the JSONL anyway. A Lua dissector for USER0 would be the next step.
"""
def __init__(self, path: str | None, udp: str | None):
self.fh = None
self.sock = None
self.dest = None
header = struct.pack("<IHHiIII", 0xA1B2C3D4, 2, 4, 0, 0, 65535, LINKTYPE_USER0)
if path:
self.fh = open(path, "wb")
self.fh.write(header)
if udp:
host, _, port = udp.partition(":")
self.dest = (host, int(port or 5555))
self.sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
self.sock.sendto(header, self.dest)
def write(self, data: bytes, ts: float):
if not (self.fh or self.sock):
return
rec = struct.pack("<IIII", int(ts), int((ts % 1) * 1e6), len(data), len(data)) + data
if self.fh:
self.fh.write(rec)
self.fh.flush()
if self.sock and self.dest:
self.sock.sendto(rec, self.dest)
def close(self):
if self.fh:
self.fh.close()
if self.sock:
self.sock.close()
def channel_keys(psk_hex: str) -> tuple[int, bytes]:
"""(channel hash, 32B secret) from a hex PSK, matching the firmware.
The firmware hashes only the first 16 bytes when the second 16 are zero, so a
128-bit key written out as 32 hex bytes still derives the right hash.
"""
secret = bytes.fromhex(psk_hex)
if len(secret) >= 32 and secret[16:32] == b"\x00" * 16:
hashed = secret[:16]
else:
hashed = secret[:32]
master = hashlib.sha256(hashed).digest()
secret32 = (secret + b"\x00" * 32)[:32]
return master[0], secret32
def try_decrypt_channel(payload: bytes, keys: dict[int, list[bytes]]) -> dict | None:
"""MeshCore group text: hash(1) | mac(2) | AES-128-ECB ciphertext."""
if len(payload) < 4:
return None
chan_hash, mac, ciphertext = payload[0], payload[1:3], payload[3:]
for secret32 in keys.get(chan_hash, []):
if hmac.new(secret32, ciphertext, hashlib.sha256).digest()[:2] != mac:
continue # 1-byte hash collides; the HMAC is the real test
from Crypto.Cipher import AES # pycryptodome, pulled in by openhop-core
padded = ciphertext + b"\x00" * (-len(ciphertext) % 16)
plain = AES.new(secret32[:16], AES.MODE_ECB).decrypt(padded)[: len(ciphertext)]
if len(plain) < 5:
return None
return {
"timestamp": int.from_bytes(plain[:4], "little"),
"flags": plain[4],
"text": plain[5:].decode("utf-8", errors="replace").rstrip("\x00"),
}
return None
def decode(data: bytes, keys: dict[int, list[bytes]]) -> dict:
"""Parse one raw frame into a flat dict. Never raises."""
out: dict = {"len": len(data), "raw": data.hex()}
pkt = Packet()
try:
pkt.read_from(data)
except Exception as exc: # truncated, bad version, bogus path_len
out["error"] = str(exc)
return out
hash_size = pkt.get_path_hash_size()
hash_count = pkt.get_path_hash_count()
payload_type = pkt.get_payload_type()
path = bytes(pkt.path)
out.update(
{
"route": ROUTE_TYPES.get(pkt.get_route_type(), "?"),
"type": PAYLOAD_TYPES.get(payload_type, f"0x{payload_type:02X}"),
"ver": pkt.get_payload_ver(),
# Hash width is chosen by the SENDER and carried in bits 6-7 of
# path_len, so a 2B/3B-path-hash node decodes here without a rebuild.
"hash_size": hash_size,
"hops": hash_count,
"path": ":".join(
path[i : i + hash_size].hex() for i in range(0, hash_size * hash_count, hash_size)
),
}
)
if pkt.has_transport_codes():
out["transport_codes"] = list(pkt.transport_codes)
payload = bytes(pkt.payload)
name = out["type"]
try:
if name == "ADVERT":
adv = parse_advert_payload(payload)
app = decode_appdata(adv["appdata"]) if adv["appdata"] else {}
out["advert"] = {
"pubkey": adv["pubkey"],
"path_hash": adv["pubkey"][: hash_size * 2],
"timestamp": adv["timestamp"],
"name": app.get("node_name"),
"role": ADVERT_ROLES.get(app.get("flags", 0) & 0x0F),
"lat": app.get("latitude"),
"lon": app.get("longitude"),
}
elif name in ("GRP_TXT", "GRP_DATA"):
out["channel_hash"] = f"{payload[0]:02x}"
decrypted = try_decrypt_channel(payload, keys)
if decrypted:
out["channel_msg"] = decrypted
elif name == "ACK":
out["ack_crc"] = payload[:4].hex()
elif name in ("TXT_MSG", "RESPONSE", "REQ"):
# dest hash | src hash | mac | ciphertext, hashes as wide as the sender chose
out["dest"] = payload[:hash_size].hex()
out["src"] = payload[hash_size : hash_size * 2].hex()
elif name == "PATH":
out["dest"] = payload[:hash_size].hex()
elif name == "TRACE":
tag, auth, flags = struct.unpack("<IIB", payload[:9])
out["trace"] = {"tag": f"{tag:08x}", "auth": f"{auth:08x}", "flags": flags}
elif name == "ANON_REQ":
out["dest"] = payload[:hash_size].hex()
out["src_pubkey"] = payload[hash_size : hash_size + 32].hex()
except Exception as exc:
out["decode_error"] = f"{name}: {exc}"
return out
def format_line(rec: dict) -> str:
"""One packet, one terminal line, most-identifying field last."""
head = (
f"{time.strftime('%H:%M:%S', time.localtime(rec['ts']))} "
f"{rec['rssi']:>4}dBm {rec['snr']:>5.1f}dB {rec['len']:>3}B "
f"{rec.get('route', '?'):<15} {rec.get('type', '?'):<9} "
f"{rec.get('hops', 0)}hop/{rec.get('hash_size', 0)}B"
)
if rec.get("dup"):
head += f" dup#{rec['dup']}"
if "error" in rec:
return f"{head} UNPARSED: {rec['error']} {rec['raw'][:48]}"
tail = []
if rec.get("path"):
tail.append(f"path={rec['path']}")
adv = rec.get("advert")
if adv:
tail.append(f"{adv.get('role') or 'node'} {adv.get('name') or '?'} [{adv['path_hash']}]")
if adv.get("lat"):
tail.append(f"{adv['lat']:.4f},{adv['lon']:.4f}")
if rec.get("channel_hash"):
tail.append(f"chan={rec['channel_hash']}")
if rec.get("channel_msg"):
tail.append(f"msg={rec['channel_msg']['text']!r}")
for key in ("dest", "src", "ack_crc"):
if rec.get(key):
tail.append(f"{key}={rec[key]}")
if rec.get("trace"):
tail.append(f"trace tag={rec['trace']['tag']}")
return f"{head} " + " ".join(tail)
def main() -> int:
ap = argparse.ArgumentParser(description=(__doc__ or "").split("\n")[0])
ap.add_argument("--board", default="0", help="fleet number or serial number (default 0)")
ap.add_argument("--port", help="explicit /dev/serial/by-id path, overrides --board")
ap.add_argument("--preset", choices=sorted(PRESETS), default="cz")
ap.add_argument("--freq", type=float, help="MHz, overrides preset")
ap.add_argument("--bw", type=float, help="kHz, overrides preset")
ap.add_argument("--sf", type=int, help="overrides preset")
ap.add_argument("--cr", type=int, help="overrides preset")
ap.add_argument("--psk", action="append", default=[], help="channel PSK hex, repeatable")
ap.add_argument("--jsonl", help="append decoded packets here, one JSON per line")
ap.add_argument("--pcap", help="write raw frames as pcap (LINKTYPE_USER0)")
ap.add_argument("--wireshark", help="also stream pcap over UDP, host:port")
ap.add_argument("--seconds", type=float, help="stop after N seconds")
ap.add_argument("--status-interval", type=float, default=60.0, help="0 disables")
ap.add_argument("--quiet", action="store_true", help="no per-packet stdout")
args = ap.parse_args()
freq, bw, sf, cr = PRESETS[args.preset]
if args.freq:
freq = int(args.freq * 1e6)
if args.bw:
bw = int(args.bw * 1000)
sf, cr = args.sf or sf, args.cr or cr
port = resolve_port(args.board, args.port)
keys: dict[int, list[bytes]] = {}
for psk in args.psk:
chan_hash, secret32 = channel_keys(psk)
keys.setdefault(chan_hash, []).append(secret32)
stats: Counter[str] = Counter()
seen: dict[str, int] = {}
lock = threading.Lock()
jsonl = open(args.jsonl, "a") if args.jsonl else None
pcap = PcapWriter(args.pcap, args.wireshark)
def on_frame(data: bytes, rssi: int, snr: float, signal_rssi: int):
ts = time.time()
with lock:
stats["heard"] += 1
rec = decode(data, keys)
rec.update({"ts": ts, "rssi": rssi, "snr": snr, "signal_rssi": signal_rssi})
digest = hashlib.sha256(data).hexdigest()[:16]
seen[digest] = seen.get(digest, 0) + 1
if seen[digest] > 1:
rec["dup"] = seen[digest]
stats["dup"] += 1
stats["parsed" if "error" not in rec else "unparsed"] += 1
stats[f"type:{rec.get('type', 'BAD')}"] += 1
pcap.write(data, ts)
if jsonl:
jsonl.write(json.dumps(rec, default=str) + "\n")
jsonl.flush()
if not args.quiet:
print(format_line(rec), flush=True)
print(
f"== port {os.path.basename(port)}\n"
f"== {freq / 1e6:.3f} MHz BW {bw / 1000:g} kHz SF{sf} CR{cr}"
f" ({args.preset}){' +' + str(len(args.psk)) + ' PSK' if args.psk else ''}",
flush=True,
)
radio = SnifferRadio(
port=port,
frequency=freq,
bandwidth=bw,
spreading_factor=sf,
coding_rate=cr,
tx_power=2, # receive-only tool; keep the floor as a second safety net
lbt_enabled=False,
on_frame=on_frame,
)
if not radio.begin():
sys.exit(f"modem na {port} neodpovedel -- bezi na desce openHop modem firmware?")
print("== RX only, nic nevysilam. Ctrl-C ukonci a vypise souhrn.\n", flush=True)
t0 = time.time()
next_status = t0 + args.status_interval if args.status_interval else None
try:
while True:
time.sleep(0.25)
now = time.time()
if args.seconds and now - t0 >= args.seconds:
break
if next_status and now >= next_status:
next_status = now + args.status_interval
# The modem's own counter is the honest denominator: it counted a
# CRC-clean frame even when nothing here could parse it.
modem = radio.get_status()
with lock:
print(
f"-- {now - t0:6.0f}s modem rx={modem.get('rx_count')} "
f"crc_err={modem.get('crc_errors')} heard={stats['heard']} "
f"parsed={stats['parsed']} unparsed={stats['unparsed']} "
f"dup={stats['dup']}",
flush=True,
)
except KeyboardInterrupt:
pass
finally:
radio.cleanup()
pcap.close()
if jsonl:
jsonl.close()
elapsed = time.time() - t0
print(f"\n== {elapsed:.0f}s, {stats['heard']} frames heard, {stats['dup']} duplicates")
print(f"== parsed {stats['parsed']}, unparsed {stats['unparsed']}")
for key, count in sorted(stats.items()):
if key.startswith("type:"):
print(f" {key[5:]:<10} {count}")
return 0
if __name__ == "__main__":
sys.exit(main())