Skip to content

Mesh.md

Latest commit

 

History

History
89 lines (59 loc) · 3.1 KB

Mesh.md

File metadata and controls

89 lines (59 loc) · 3.1 KB
Raw

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