# kavinsuriya3107-cyber/mqtt-security-auditor architecture

> Architecture diagram of the GitHub repository kavinsuriya3107-cyber/mqtt-security-auditor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kavinsuriya3107-cyber/mqtt-security-auditor
- Repository: https://github.com/kavinsuriya3107-cyber/mqtt-security-auditor

## Overview

MQTT Security Auditor is a CLI tool that assesses an MQTT broker and produces prioritized findings plus an HTML report. The main workflow is user request → configuration and scan orchestration → broker discovery, authentication, topic and ACL analysis, TLS auditing, and resilience checks → risk scoring → terminal and HTML results. The orchestrator shares scan context across modules; authentication also uses a configurable credential wordlist. The README documents the full capability set, while some module internals were only sampled, so those relationships rely on documented behavior rather than inferred calls.

Main entry points: [`mqtt_auditor/orchestrator.py`](https://github.com/kavinsuriya3107-cyber/mqtt-security-auditor/blob/main/mqtt_auditor/orchestrator.py) (Scan orchestrator), [`mqtt_auditor/scorer.py`](https://github.com/kavinsuriya3107-cyber/mqtt-security-auditor/blob/main/mqtt_auditor/scorer.py) (Risk scorer), [`mqtt_auditor/modules/base.py`](https://github.com/kavinsuriya3107-cyber/mqtt-security-auditor/blob/main/mqtt_auditor/modules/base.py) (Module interface), [`mqtt_auditor/cli.py`](https://github.com/kavinsuriya3107-cyber/mqtt-security-auditor/blob/main/mqtt_auditor/cli.py) (Scan CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and configuration"]
  node_cli["Scan CLI<br/>[cli.py]"]
  node_configmgr["Config loader<br/>[config.py]"]
  node_profile["Default profile<br/>[default.yaml]"]
  node_wordlist["Credential list<br/>[mqtt_defaults.txt]"]
end

subgraph group_audit["Broker audit"]
  node_orchestrator["Scan orchestrator<br/>[orchestrator.py]"]
  node_base["Module interface<br/>[base.py]"]
  node_discovery["Broker discovery<br/>[discovery.py]"]
  node_auth["Authentication audit<br/>[auth.py]"]
  node_topics["Topic analysis<br/>[topics.py]"]
  node_acl["ACL checks<br/>[acl.py]"]
  node_tls["TLS audit<br/>[tls_audit.py]"]
  node_dos["Resilience checks<br/>[dos.py]"]
end

subgraph group_analysis["Findings and reports"]
  node_scorer["Risk scorer<br/>[scorer.py]"]
  node_terminal["Terminal findings<br/>[cli.py]"]
  node_reporter["HTML reporter<br/>[html_report.py]"]
  node_template["Report template<br/>[report.html]"]
end

node_user(("Operator"))
node_broker(("MQTT broker"))

node_user -->|"starts scan"| node_cli
node_cli -->|"loads settings"| node_configmgr
node_configmgr -->|"loads profile"| node_profile
node_cli -->|"starts scan"| node_orchestrator
node_orchestrator -->|"runs first"| node_discovery
node_orchestrator -->|"runs audit"| node_auth
node_orchestrator -->|"runs audit"| node_topics
node_orchestrator -->|"runs audit"| node_acl
node_orchestrator -->|"runs audit"| node_tls
node_orchestrator -->|"runs audit"| node_dos
node_orchestrator -->|"creates scorer"| node_scorer
node_auth -->|"reads credentials"| node_wordlist
node_discovery -->|"probes service"| node_broker
node_auth -->|"tests access"| node_broker
node_topics -->|"subscribes topics"| node_broker
node_acl -->|"tests permissions"| node_broker
node_tls -->|"checks TLS"| node_broker
node_dos -->|"tests resilience"| node_broker
node_discovery -->|"extends interface"| node_base
node_auth -->|"extends interface"| node_base
node_topics -->|"extends interface"| node_base
node_acl -->|"extends interface"| node_base
node_tls -->|"extends interface"| node_base
node_dos -->|"extends interface"| node_base
node_auth -->|"registers findings"| node_scorer
node_topics -->|"registers findings"| node_scorer
node_acl -->|"registers findings"| node_scorer
node_tls -->|"registers findings"| node_scorer
node_dos -->|"registers findings"| node_scorer
node_scorer -->|"returns results"| node_orchestrator
node_cli -->|"prints summary"| node_terminal
node_cli -->|"generates report"| node_reporter
node_reporter -->|"renders template"| node_template

click node_cli "https://github.com/kavinsuriya3107-cyber/mqtt-security-auditor/blob/main/mqtt_auditor/cli.py"
click node_configmgr "https://github.com/kavinsuriya3107-cyber/mqtt-security-auditor/blob/main/mqtt_auditor/config.py"
click node_profile "https://github.com/kavinsuriya3107-cyber/mqtt-security-auditor/blob/main/configs/default.yaml"
click node_wordlist "https://github.com/kavinsuriya3107-cyber/mqtt-security-auditor/blob/main/wordlists/mqtt_defaults.txt"
click node_orchestrator "https://github.com/kavinsuriya3107-cyber/mqtt-security-auditor/blob/main/mqtt_auditor/orchestrator.py"
click node_base "https://github.com/kavinsuriya3107-cyber/mqtt-security-auditor/blob/main/mqtt_auditor/modules/base.py"
click node_discovery "https://github.com/kavinsuriya3107-cyber/mqtt-security-auditor/blob/main/mqtt_auditor/modules/discovery.py"
click node_auth "https://github.com/kavinsuriya3107-cyber/mqtt-security-auditor/blob/main/mqtt_auditor/modules/auth.py"
click node_topics "https://github.com/kavinsuriya3107-cyber/mqtt-security-auditor/blob/main/mqtt_auditor/modules/topics.py"
click node_acl "https://github.com/kavinsuriya3107-cyber/mqtt-security-auditor/blob/main/mqtt_auditor/modules/acl.py"
click node_tls "https://github.com/kavinsuriya3107-cyber/mqtt-security-auditor/blob/main/mqtt_auditor/modules/tls_audit.py"
click node_dos "https://github.com/kavinsuriya3107-cyber/mqtt-security-auditor/blob/main/mqtt_auditor/modules/dos.py"
click node_scorer "https://github.com/kavinsuriya3107-cyber/mqtt-security-auditor/blob/main/mqtt_auditor/scorer.py"
click node_terminal "https://github.com/kavinsuriya3107-cyber/mqtt-security-auditor/blob/main/mqtt_auditor/cli.py"
click node_reporter "https://github.com/kavinsuriya3107-cyber/mqtt-security-auditor/blob/main/mqtt_auditor/reporter/html_report.py"
click node_template "https://github.com/kavinsuriya3107-cyber/mqtt-security-auditor/blob/main/mqtt_auditor/reporter/templates/report.html"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_configmgr,node_profile,node_wordlist toneBlue
class node_orchestrator,node_base,node_discovery,node_auth,node_topics,node_acl,node_tls,node_dos toneAmber
class node_scorer,node_terminal,node_reporter,node_template toneMint
class node_user,node_broker toneIndigo
```

## Components

### CLI and configuration

- [Scan CLI](https://github.com/kavinsuriya3107-cyber/mqtt-security-auditor/blob/main/mqtt_auditor/cli.py): `mqtt_auditor/cli.py`
- [Config loader](https://github.com/kavinsuriya3107-cyber/mqtt-security-auditor/blob/main/mqtt_auditor/config.py): `mqtt_auditor/config.py`
- [Default profile](https://github.com/kavinsuriya3107-cyber/mqtt-security-auditor/blob/main/configs/default.yaml): `configs/default.yaml`
- [Credential list](https://github.com/kavinsuriya3107-cyber/mqtt-security-auditor/blob/main/wordlists/mqtt_defaults.txt): `wordlists/mqtt_defaults.txt`

### Broker audit

- [Scan orchestrator](https://github.com/kavinsuriya3107-cyber/mqtt-security-auditor/blob/main/mqtt_auditor/orchestrator.py): `mqtt_auditor/orchestrator.py`
- [Module interface](https://github.com/kavinsuriya3107-cyber/mqtt-security-auditor/blob/main/mqtt_auditor/modules/base.py): `mqtt_auditor/modules/base.py`
- [Broker discovery](https://github.com/kavinsuriya3107-cyber/mqtt-security-auditor/blob/main/mqtt_auditor/modules/discovery.py): `mqtt_auditor/modules/discovery.py`
- [Authentication audit](https://github.com/kavinsuriya3107-cyber/mqtt-security-auditor/blob/main/mqtt_auditor/modules/auth.py): `mqtt_auditor/modules/auth.py`
- [Topic analysis](https://github.com/kavinsuriya3107-cyber/mqtt-security-auditor/blob/main/mqtt_auditor/modules/topics.py): `mqtt_auditor/modules/topics.py`
- [ACL checks](https://github.com/kavinsuriya3107-cyber/mqtt-security-auditor/blob/main/mqtt_auditor/modules/acl.py): `mqtt_auditor/modules/acl.py`
- [TLS audit](https://github.com/kavinsuriya3107-cyber/mqtt-security-auditor/blob/main/mqtt_auditor/modules/tls_audit.py): `mqtt_auditor/modules/tls_audit.py`
- [Resilience checks](https://github.com/kavinsuriya3107-cyber/mqtt-security-auditor/blob/main/mqtt_auditor/modules/dos.py): `mqtt_auditor/modules/dos.py`

### Findings and reports

- [Risk scorer](https://github.com/kavinsuriya3107-cyber/mqtt-security-auditor/blob/main/mqtt_auditor/scorer.py): `mqtt_auditor/scorer.py`
- [Terminal findings](https://github.com/kavinsuriya3107-cyber/mqtt-security-auditor/blob/main/mqtt_auditor/cli.py): `mqtt_auditor/cli.py`
- [HTML reporter](https://github.com/kavinsuriya3107-cyber/mqtt-security-auditor/blob/main/mqtt_auditor/reporter/html_report.py): `mqtt_auditor/reporter/html_report.py`
- [Report template](https://github.com/kavinsuriya3107-cyber/mqtt-security-auditor/blob/main/mqtt_auditor/reporter/templates/report.html): `mqtt_auditor/reporter/templates/report.html`

### Other components

- **Operator**
- **MQTT broker**

## Connections

- Operator → Scan CLI: starts scan (evidence: `README.md`)
- Scan CLI → Config loader: loads settings (evidence: `mqtt_auditor/cli.py`)
- Config loader → Default profile: loads profile (evidence: `README.md`)
- Scan CLI → Scan orchestrator: starts scan (evidence: `mqtt_auditor/cli.py`)
- Scan orchestrator → Broker discovery: runs first (evidence: `mqtt_auditor/orchestrator.py`)
- Scan orchestrator → Authentication audit: runs audit (evidence: `mqtt_auditor/orchestrator.py`)
- Scan orchestrator → Topic analysis: runs audit (evidence: `mqtt_auditor/orchestrator.py`)
- Scan orchestrator → ACL checks: runs audit (evidence: `mqtt_auditor/orchestrator.py`)
- Scan orchestrator → TLS audit: runs audit (evidence: `mqtt_auditor/orchestrator.py`)
- Scan orchestrator → Resilience checks: runs audit (evidence: `mqtt_auditor/orchestrator.py`)
- Scan orchestrator → Risk scorer: creates scorer (evidence: `mqtt_auditor/orchestrator.py`)
- Authentication audit → Credential list: reads credentials (evidence: `mqtt_auditor/modules/auth.py`)
- Broker discovery → MQTT broker: probes service (evidence: `mqtt_auditor/modules/discovery.py`)
- Authentication audit → MQTT broker: tests access (evidence: `mqtt_auditor/modules/auth.py`)
- Topic analysis → MQTT broker: subscribes topics (evidence: `mqtt_auditor/modules/topics.py`)
- ACL checks → MQTT broker: tests permissions (evidence: `mqtt_auditor/modules/acl.py`)
- TLS audit → MQTT broker: checks TLS (evidence: `mqtt_auditor/modules/tls_audit.py`)
- Resilience checks → MQTT broker: tests resilience (evidence: `mqtt_auditor/modules/dos.py`)
- Broker discovery → Module interface: extends interface (evidence: `README.md`)
- Authentication audit → Module interface: extends interface (evidence: `mqtt_auditor/modules/auth.py`)
- Topic analysis → Module interface: extends interface (evidence: `mqtt_auditor/modules/topics.py`)
- ACL checks → Module interface: extends interface (evidence: `mqtt_auditor/modules/acl.py`)
- TLS audit → Module interface: extends interface (evidence: `mqtt_auditor/modules/tls_audit.py`)
- Resilience checks → Module interface: extends interface (evidence: `mqtt_auditor/modules/dos.py`)
- Authentication audit → Risk scorer: registers findings (evidence: `mqtt_auditor/modules/auth.py`)
- Topic analysis → Risk scorer: registers findings (evidence: `README.md`)
- ACL checks → Risk scorer: registers findings (evidence: `README.md`)
- TLS audit → Risk scorer: registers findings (evidence: `mqtt_auditor/modules/tls_audit.py`)
- Resilience checks → Risk scorer: registers findings (evidence: `README.md`)
- Risk scorer → Scan orchestrator: returns results (evidence: `README.md`)
- Scan CLI → Terminal findings: prints summary (evidence: `mqtt_auditor/cli.py`)
- Scan CLI → HTML reporter: generates report (evidence: `mqtt_auditor/cli.py`)
- HTML reporter → Report template: renders template (evidence: `mqtt_auditor/reporter/html_report.py`)
