🐝 SWARM

Security Weakness Analyser for MQTT Reconnaissance and Mapping

AI-powered MQTT security auditor combining live broker probing, SSH auto-fetch, Claude Sonnet analysis, Haiku validation, and professional PDF + DOT/PNG/SVG output.

The One File You Need

swarm.py

That's it. One file, six modes, everything built in.

Install Dependencies

pip install paho-mqtt reportlab anthropic paramiko

Optional (for rendering topology graphs locally):

sudo apt install graphviz # Debian/Ubuntu/Kali/RPi OS
brew install graphviz # macOS

Get an Anthropic API Key

Go to console.anthropic.com
Add a credit card (you get $5 free credits - enough for ~200 audit runs)
API Keys → Create Key → copy it

Store it as an environment variable so you don't have to type it every time:

export ANTHROPIC_API_KEY=sk-ant-...

Quick Start

Interactive menu (easiest)

python3 swarm.py

Shows a numbered menu. Pick a mode, answer the prompts - no flags needed.

Direct mode (for scripting / automation)

python3 swarm.py <mode> [options]

The 6 Modes

Mode 1 - Manual Testing Guide

python3 swarm.py manual

Opens the mqtt-ust lab guide - a structured set of DIY attack scenarios for hands-on learning. No broker connection needed.

What you get: Step-by-step instructions for 5 attack scenarios (auth bypass, ACL abuse, retained message injection, wildcard snooping, DoS flooding) + CVE-2021-34432 root cause analysis.

Mode 2 - AI Audit ⭐ (Core Feature)

# Minimum - live probing only (no SSH)
python3 swarm.py audit \
--host 192.168.1.100 \
--api-key sk-ant-...
# Full audit - live probing + SSH auto-fetch of all config files
python3 swarm.py audit \
--host 192.168.1.100 \
--mqtt-user admin --mqtt-pass secret \
--ssh-user pi --ssh-pass raspberry \
--api-key sk-ant-...
# TLS broker
python3 swarm.py audit \
--host 192.168.1.100 --mqtt-port 8883 --tls \
--mqtt-user admin --mqtt-pass secret \
--ssh-user pi --ssh-key ~/.ssh/id_rsa \
--api-key sk-ant-...

What happens automatically:

Phase 1 Live MQTT probing (10 checks)
→ anonymous access, default credentials, TLS status,
wildcard subscriptions, retained persistence,
flood rate, oversized payload, client ID collision
Phase 2 SSH into broker host (auto-discovers everything)
→ mosquitto.conf, include_dir/*.conf
→ ACL file (path parsed from conf)
→ password file (user list, not hashes)
→ broker logs (tail 500 lines or journalctl)
→ mosquitto version, service status, world-readable files
Phase 3 Claude Sonnet deep analysis
→ Cross-references live data with static files
→ Finds discrepancies (e.g. conf says auth enabled but anon works)
→ Produces severity-rated findings with evidence + remediation
Claude Haiku validation judge
→ Independently validates each finding
→ Flags false positives
→ Adds confidence score (0–100%) to every finding
Phase 4 Report generation
→ PDF - professional pentest-style report
→ DOT - Graphviz topology source
→ PNG - rendered topology graph
→ SVG - scalable vector topology graph

Output files:

swarm_<host>_<timestamp>_report.pdf
swarm_<host>_<timestamp>_topology.dot
swarm_<host>_<timestamp>_topology.png
swarm_<host>_<timestamp>_topology.svg

Mode 3 - Fuzz with FUME

# Show FUME commands for your broker (installs FUME if needed)
python3 swarm.py fume \
--host 192.168.1.100 \
--mqtt-user admin --mqtt-pass secret \
--fume-path ./FUME-Fuzzing-MQTT-Brokers
# Install FUME first:
git clone https://github.com/PBearson/FUME-Fuzzing-MQTT-Brokers
cd FUME-Fuzzing-MQTT-Brokers && pip install -r requirements.txt
cd ..

What you get: Ready-to-run FUME commands pre-configured for your broker covering CONNECT fuzzing, topic fuzzing, payload size fuzzing, QoS/retain flag fuzzing, and CVE-2021-34432 style zero-length topic testing.

Mode 4 - SmartFuzz (AI-Powered Fuzzing Strategy)

# Interactive - asks you about your deployment, generates a targeted plan
python3 swarm.py smartfuzz \
--api-key sk-ant-...
# With SSH to also pull live config into the strategy
python3 swarm.py smartfuzz \
--host 192.168.1.100 \
--ssh-user pi --ssh-pass raspberry \
--api-key sk-ant-...
# With architecture diagram / context file
python3 swarm.py smartfuzz \
--host 192.168.1.100 \
--context-file ./architecture.txt \
--api-key sk-ant-...

What it asks you:

[?] Number of MQTT clients in deployment: 12
[?] Device types: ESP32 temperature sensors, Raspberry Pi gateway
[?] Deployment purpose: Industrial HVAC control
[?] Crown jewel (most critical asset): HVAC control actuator topics
[?] Specific concerns (optional): Rogue device injection
[?] Architecture file (optional): ./arch_diagram.txt

What Claude Sonnet generates + Haiku validates:

Priority fuzz targets specific to your deployment
Pre-built FUME commands tailored to your setup
Crown jewel attack paths (step-by-step)
Custom payloads for your device types
Saved to swarm_smartfuzz_*_strategy.txt

Mode 5 - Expert Chat (AI Chatbot)

# Without live context (general MQTT security expert)
python3 swarm.py chat \
--api-key sk-ant-...
# With live broker context (recommended - loads real config/ACL/logs)
python3 swarm.py chat \
--host 192.168.1.100 \
--ssh-user pi --ssh-pass raspberry \
--api-key sk-ant-...
# With additional context file
python3 swarm.py chat \
--host 192.168.1.100 \
--ssh-user pi --ssh-pass raspberry \
--context-file ./pentest_notes.txt \
--api-key sk-ant-...

What the chatbot knows:

Your live mosquitto.conf, ACL file, and broker logs (if SSH provided)
All MQTT protocol vulnerabilities and CVEs
Mosquitto-specific hardening techniques
MQTT Mayhem attack scenarios
OT/ICS and IoT security context
OWASP IoT Top 10, IEC 62443, NIST IoT

Chat commands:

clear Reset conversation history
save Save transcript to swarm_chat_<timestamp>.txt
exit End the session

Example session:

You: Is my ACL file stopping wildcard subscriptions?
SWARM: Looking at your ACL file, line 7 grants 'topic read #' to user 'device01'...
You: What CVEs affect my version of Mosquitto?
SWARM: Your broker is running 1.6.9 (from the version info collected). This version...

Mode 6 - Topology Diagram

# With live probing (recommended)
python3 swarm.py diagram \
--host 192.168.1.100 \
--mqtt-user admin --mqtt-pass secret \
--ssh-user pi --ssh-pass raspberry \
--api-key sk-ant-...
# Standalone - generates a template diagram without live data
python3 swarm.py diagram

Generates DOT + PNG + SVG topology maps showing the broker, connected clients, observed topics, and security findings - all colour-coded.

Colour Coding Reference

Colour	Meaning
🔴 Red	CRITICAL or HIGH finding / anonymous client / sensitive topic
🟠 Orange	HIGH risk / wildcard subscriber / default credential client
🟡 Amber	MEDIUM risk / `$SYS` broker internal topic
🟢 Green	Secure / authenticated / TLS enabled
🟣 Purple	SWARM audit tool node itself

All Options Reference

python3 swarm.py <mode> [options]
MODES:
manual No options needed
audit All common options apply
fume --fume-path
smartfuzz --context-file
chat --context-file
diagram All common options apply
COMMON OPTIONS:
--host Broker IP or hostname
--mqtt-port MQTT port (default: 1883)
--mqtt-user MQTT username
--mqtt-pass MQTT password
--tls Enable TLS for MQTT connection
--ssh-user SSH username (enables Phase 2 file auto-fetch)
--ssh-pass SSH password
--ssh-key SSH private key path (e.g. ~/.ssh/id_rsa)
--ssh-port SSH port (default: 22)
--api-key Anthropic API key (or set ANTHROPIC_API_KEY env var)
--output Output file prefix (default: swarm_<host>_<timestamp>)
MODE-SPECIFIC:
fume:
--fume-path Path to FUME installation (default: ./FUME-Fuzzing-MQTT-Brokers)
smartfuzz / chat:
--context-file Path to additional context file (architecture notes, etc.)

What Gets Checked (Mode 2 - Audit)

Check	What SWARM Does
Anonymous Access	Connects with no credentials - CRITICAL if accepted
Default Credentials	Tests 15 common pairs (admin/admin, pi/raspberry, etc.)
Supplied Credentials	Validates your provided credentials
TLS / Encryption	Probes port 8883, checks cipher and TLS version
Plain-text Exposure	Flags if both 1883 and 8883 are open simultaneously
Wildcard Subscription	Subscribes to `#` and `$SYS/#`, reports what leaks
Retained Message Abuse	Publishes retained msg, reconnects, confirms persistence
Topic ACL Isolation	Attempts publish to `/admin/cmd` and other sensitive topics
Rate Limiting / Flood	Sends 200-message burst, measures accepted msg/s
Oversized Payload	Sends 512 KB message, checks if `message_size_limit` is set
Client ID Collision	Connects twice with same ID, detects session hijack risk
mosquitto.conf	Checks every security-relevant directive via SSH
ACL file	Checks for wildcard abuse, missing restrictions, `$SYS` access
Broker logs	Detects brute force, flooding, denied access, suspicious patterns

AI Architecture

┌─────────────────────────────────────────────┐
│ Claude Sonnet 4.6 │
│ Deep analysis, findings generation, │
│ fuzzing strategy, chat responses │
└────────────────────┬────────────────────────┘
│ findings + evidence
▼
┌─────────────────────────────────────────────┐
│ Claude Haiku 4.5 │
│ Independent validation judge: │
│ · Is evidence accurate? │
│ · Is severity correctly calibrated? │
│ · Flag false positives │
│ · Confidence score per finding (0–100%) │
└─────────────────────────────────────────────┘

Every finding in the report shows its Haiku confidence score. Low confidence findings are clearly marked for manual review.

Example Workflow (Full Engagement)

# Step 1: Understand the manual lab first
python3 swarm.py manual
# Step 2: Run the full AI audit against your target
python3 swarm.py audit \
--host 192.168.1.100 \
--mqtt-user admin --mqtt-pass secret \
--ssh-user pi --ssh-pass raspberry
# Step 3: Chat with the expert about specific findings
python3 swarm.py chat \
--host 192.168.1.100 \
--ssh-user pi --ssh-pass raspberry
# Step 4: Build a targeted fuzzing plan
python3 swarm.py smartfuzz \
--host 192.168.1.100 \
--ssh-user pi --ssh-pass raspberry
# Step 5: Execute fuzzing with FUME
python3 swarm.py fume \
--host 192.168.1.100 \
--mqtt-user admin --mqtt-pass secret
# Step 6: Generate standalone diagram for the report
python3 swarm.py diagram \
--host 192.168.1.100 \
--ssh-user pi --ssh-pass raspberry

Output Files Summary

File	Mode	Description
`swarm_*_report.pdf`	audit, smartfuzz	Full security report with findings, Haiku scores, remediation
`swarm_*_topology.dot`	audit, diagram, smartfuzz	Graphviz source file
`swarm_*_topology.png`	audit, diagram, smartfuzz	Rendered topology image
`swarm_*_topology.svg`	audit, diagram, smartfuzz	Scalable vector topology
`swarm_smartfuzz_*_strategy.txt`	smartfuzz	Full AI fuzzing strategy JSON
`swarm_chat_*.txt`	chat	Saved conversation transcript

Troubleshooting

paho-mqtt not installed

pip install paho-mqtt

paramiko not installed (SSH Phase 2 skips silently)

pip install paramiko

graphviz not installed (DOT file still saved, just not auto-rendered)

sudo apt install graphviz # Linux
brew install graphviz # macOS# Then manually render:
dot -Tpng topology.dot -o topology.png
dot -Tsvg topology.dot -o topology.svg
# Or paste .dot content into: https://dreampuf.github.io/GraphvizOnline/

SSH connection refused

Ensure SSH is running on the broker host: sudo systemctl start ssh
Ensure the SSH user has read access to /etc/mosquitto/
Try --ssh-key instead of --ssh-pass for key-based auth

API key errors

Verify key starts with sk-ant-
Check you have credits at console.anthropic.com
Or set: export ANTHROPIC_API_KEY=sk-ant-...

Comparison with Existing Tools

Feature	SWARM	MQTTSA	MQTT Explorer	mqttui
Live security probing	✅	✅	❌	❌
SSH auto-fetch config/ACL/logs	✅	❌	❌	❌
AI-powered analysis (Claude)	✅	❌	❌	❌
Dual-model validation (Haiku judge)	✅	❌	❌	❌
PDF pentest report	✅	✅	❌	❌
DOT/PNG/SVG topology with security colour coding	✅	❌	❌	❌
AI-powered fuzzing strategy	✅	❌	❌	❌
Expert AI chatbot with live context	✅	❌	❌	❌
Interactive CLI menu	✅	❌	❌	❌

References

Legal

For authorised security testing and educational purposes only. Do not run against brokers you do not own or have explicit written permission to test.

Powered by Claude Sonnet 4.6 (analysis) + Claude Haiku 4.5 (validation judge)

Name		Name	Last commit message	Last commit date
README.md		README.md
swarm.py		swarm.py

Navigation Menu

Uh oh!

Repository files navigation

🐝 SWARM

Security Weakness Analyser for MQTT Reconnaissance and Mapping

The One File You Need

Install Dependencies

Get an Anthropic API Key

Quick Start

Interactive menu (easiest)

Direct mode (for scripting / automation)

The 6 Modes

Mode 1 - Manual Testing Guide

Mode 2 - AI Audit ⭐ (Core Feature)

Mode 3 - Fuzz with FUME

Mode 4 - SmartFuzz (AI-Powered Fuzzing Strategy)

Mode 5 - Expert Chat (AI Chatbot)

Mode 6 - Topology Diagram

Colour Coding Reference

All Options Reference

What Gets Checked (Mode 2 - Audit)

AI Architecture

Example Workflow (Full Engagement)

Output Files Summary

Troubleshooting

Comparison with Existing Tools

References

Legal

About

Releases

Packages

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

🐝 SWARM

Security Weakness Analyser for MQTT Reconnaissance and Mapping

The One File You Need

Install Dependencies

Get an Anthropic API Key

Quick Start

Interactive menu (easiest)

Direct mode (for scripting / automation)

The 6 Modes

Mode 1 - Manual Testing Guide

Mode 2 - AI Audit ⭐ (Core Feature)

Mode 3 - Fuzz with FUME

Mode 4 - SmartFuzz (AI-Powered Fuzzing Strategy)

Mode 5 - Expert Chat (AI Chatbot)

Mode 6 - Topology Diagram

Colour Coding Reference

All Options Reference

What Gets Checked (Mode 2 - Audit)

AI Architecture

Example Workflow (Full Engagement)

Output Files Summary

Troubleshooting

Comparison with Existing Tools

References

Legal

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages