Shadowbroker/Mesh.md

ShadowBroker — Meshtastic MQTT Remediation

Version: 0.9.6
Date: 2026-04-12
Re: meshtastic/firmware#6131 — Excessive MQTT traffic from ShadowBroker clients

---

What happened

ShadowBroker is an open-source OSINT situational awareness platform that includes a Meshtastic MQTT listener for displaying mesh network activity on a global map. In prior versions, the MQTT bridge:

• Subscribed to 28 wildcard topics (msh/{region}/#) covering every known official and community root on startup
• Used an aggressive reconnect policy (min 1s / max 30s backoff)
• Set keepalive to 30 seconds
• Had no client-side rate limiting on inbound messages
• Auto-started on every launch with no opt-out

This produced 1-2 orders of magnitude more traffic than typical Meshtastic clients on the public broker at mqtt.meshtastic.org.

---

What we fixed

1. Bridge disabled by default

The MQTT bridge no longer starts automatically. Operators must explicitly opt in:

MESH_MQTT_ENABLED=true

2. US-only default subscription

When enabled, the bridge subscribes to 1 topic (msh/US/#) instead of 28. Additional regions are opt-in:

MESH_MQTT_EXTRA_ROOTS=EU_868,ANZ

The UI still displays all regions in its dropdown — only the MQTT subscription scope changed.

3. Client-side rate limiter

Inbound messages are capped at 100 messages per minute using a sliding window. Excess messages are silently dropped. A warning is logged periodically when the limiter activates so operators are aware.

4. Conservative connection parameters

Parameter	Before	After
Keepalive	30s	120s
Reconnect min delay	1s	15s
Reconnect max delay	30s	300s
QoS	0	0 (unchanged)

5. Versioned client ID

Client IDs changed from sbmesh-{uuid} to sb096-{uuid} so the Meshtastic team can identify ShadowBroker clients and track adoption of the fix by version.

---

Configuration reference

Variable	Default	Description
MESH_MQTT_ENABLED	false	Master switch for the MQTT bridge
MESH_MQTT_EXTRA_ROOTS	(empty)	Comma-separated additional region roots (e.g. EU_868,ANZ,JP)
MESH_MQTT_INCLUDE_DEFAULT_ROOTS	true	Include US in subscriptions
MESH_MQTT_BROKER	mqtt.meshtastic.org	Broker hostname
MESH_MQTT_PORT	1883	Broker port
MESH_MQTT_USER	meshdev	Broker username
MESH_MQTT_PASS	large4cats	Broker password
MESH_MQTT_PSK	(empty)	Hex-encoded PSK (empty = default LongFast key)

---

Files changed

• backend/services/config.py — Added MESH_MQTT_ENABLED flag
• backend/services/mesh/meshtastic_topics.py — Reduced default roots to US-only
• backend/services/sigint_bridge.py — Rate limiter, keepalive/backoff tuning, versioned client ID, opt-in gate
• backend/.env.example — Documented all MQTT options

---

Contact

Repository: github.com/BigBodyCobain/Shadowbroker
Maintainer: BigBodyCobain