🐝 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
Latest commit History 2 Commits
README.md		README.md
swarm.py		swarm.py

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Uh oh!

Folders and files

Latest commit

History

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

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages