patar56/mqtt-fuzzer

# MQTT 安全 Agent **UCLA ECE 202C — IoT 安全期末项目** 一款基于 **Claude Code**（Anthropic 的 CLI）构建的 AI 驱动 MQTT broker 安全评估工具。该 agent 能够自主设计模糊测试活动、构建原始 MQTT 数据包、针对 Docker 托管的在线 broker 执行有状态的多客户端攻击，并生成结构化的漏洞报告——所有这些都完全通过 Claude Code 终端中的自然语言提示词来驱动。 ## 工作原理 本项目使用了一个在 `.claude/agents/mqtt-protocol-fuzzer.md` 中定义的**自定义 Claude Code 子代理**（`mqtt-protocol-fuzzer`）。与运行传统的 Python CLI 不同，你可以使用 `@agent-mqtt-protocol-fuzzer` 提示词直接通过 Claude Code 终端与 agent 进行交互。该 agent 能够对 MQTT 协议进行推理，编写并执行模糊测试脚本，启动 Docker 容器，并生成报告——所有这一切都可以在一个对话轮次中自主完成。 ``` You (Claude Code terminal) │ └─ @agent-mqtt-protocol-fuzzer │ ├─ Reasons about MQTT protocol state machines ├─ Writes fuzzing scripts (raw TCP, no paho dependency) ├─ Spins up / verifies Docker broker containers ├─ Executes multi-client coordinated attack scenarios ├─ Analyzes broker responses and classifies vulnerabilities └─ Writes campaign reports to reports/ ``` ## 研究基础 本项目综合了以下五篇论文的发现与技术： | 论文 | 贡献 | |---|---| | [Burglars' IoT Paradise](https://ieeexplore.ieee.org/document/9152645) (IEEE S&P 2020) | MQTT 漏洞分类法 (V1–V6) | | [MQTTactic](https://www.usenix.org/conference/usenixsecurity22/presentation/chen-bin-mqtt) (USENIX Sec 2022) | 授权逻辑缺陷类别 | | [FUME](https://dl.acm.org/doi/10.1145/3548606.3560570) (CCS 2022) | 带有响应反馈的有状态模糊测试引擎 | | [MGPTFuzz / LLM Protocol Fuzzing](https://www.ndss-symposium.org/ndss-paper/large-language-model-guided-protocol-fuzzing/) (NDSS 2024) | LLM 引导的协议规范解析 → FSM 提取 | | FirmAgent (2026) | 混合模糊测试 + LLM agent 推理循环 | ## 仓库结构 ``` mqtt-security-agent/ ├── .claude/ │ └── agents/ │ └── mqtt-protocol-fuzzer.md # Subagent definition (tools, system prompt) ├── agent/ │ ├── spec/mqtt_spec.py # Protocol FSM, vulnerability taxonomy │ ├── fuzzing/engine.py # Campaign 1 fuzzing engine │ ├── vulnerabilities/attacks.py # 7 targeted attack classes (V1–V7) │ └── broker/ │ ├── connector.py # Raw TCP MQTT packet builder │ └── docker_mgr.py # Docker broker lifecycle management ├── campaign2_fuzzer.py # Campaign 2 fuzzing engine ├── campaign3_fuzzer.py # Campaign 3 multi-broker fuzzer ├── campaign_final_fuzzer.py # Final campaign: multi-client differential fuzzer ├── config/ │ ├── mosquitto_hardened_final.conf # Hardened Mosquitto configuration │ ├── acl_hardened_final.conf # Hardened ACL file │ ├── emqx_hardened_final.conf # Hardened EMQX configuration (HOCON) │ ├── nanomq_hardened_final.conf # Hardened NanoMQ configuration │ └── hivemq_hardening_notes.md # HiveMQ hardening guidance (XML-based) ├── scripts/ │ ├── verify_mitigations.py # Campaign 3 PASS/FAIL verifier │ └── verify_mitigations_final.py # Final campaign verifier (28 checks, 4 brokers) ├── reports/ # All campaign outputs (see below) ├── docker/ │ ├── docker-compose.yml │ └── mosquitto/mosquitto.conf # Intentionally permissive config for research └── tests/ └── test_packet_builder.py # 37 unit tests (protocol encoding) ``` ## 前置条件 - 已安装并完成身份验证的 [Claude Code CLI](https://claude.ai/code) - 正在运行的 Docker Desktop - Python 3.10+（用于 agent 执行的模糊测试脚本） - Python 包：`paho-mqtt`（仅用于活动 1 的分析——后续活动使用原始套接字） ``` git clone https://github.com/patar56/mqtt-security-agent.git cd mqtt-security-agent pip install -r requirements.txt ``` ## 使用方法 所有交互均通过 **Claude Code 终端**进行。在此项目目录中打开 Claude Code，并使用 `@agent-mqtt-protocol-fuzzer` 调用模糊测试 agent。 ### 启动模糊测试活动 ``` @agent-mqtt-protocol-fuzzer Spin up a Docker container with an MQTT broker and launch a fuzzing campaign to find vulnerabilities. ``` 该 agent 将会： 1. 在 Docker 中拉取并启动 `eclipse-mosquitto:2.0.18`，并使用宽松的配置 2. 运行基于生成和基于变异的模糊测试 3. 执行来自学术文献的针对性漏洞攻击 4. 将结果写入 `reports/` ### 针对特定的 broker 或漏洞类别 ``` @agent-mqtt-protocol-fuzzer Run the session hijacking attack (V3) against the broker on localhost:1884. ``` ### 多 broker 活动 ``` @agent-mqtt-protocol-fuzzer Run a fuzzing campaign against Mosquitto, EMQX, HiveMQ CE, and NanoMQ. Produce a cross-broker comparison matrix. ``` ### 请求缓解措施 ``` @agent-mqtt-protocol-fuzzer Produce hardened configs and a mitigation guide for all confirmed vulnerabilities. ``` ### 继续先前的活动 该 agent 会在会话之间保持记忆。结合任何后续提示词使用 `@agent-mqtt-protocol-fuzzer`，它将会从先前的发现处继续执行。 ## 活动历史与结果 本项目共进行了四次活动，每一次都在先前的方法论基础上进行了构建。 ### 活动 1 — Mosquitto 2.0.18（285 个测试用例） 基于语法的生成式模糊测试 + 变异模糊测试 + 学术漏洞复现。 | 漏洞 | 名称 | CVSS | 结果 | |------|------|------|--------| | V1 | Unauthorized Will Message Exploitation | 7.5 | 已确认 | | V2 | Retained Message Poisoning | 6.5 | 已确认 | | V3 | ClientID Session Hijacking | 8.1 | 已确认 | | V4 | Wildcard Subscription Eavesdrop (`#`) | 7.2 | 已确认 | | V5 | QoS 2 Duplicate Message Injection | 5.3 | 未确认（符合规范） | | V6 | $SYS Topic Information Disclosure | 4.3 | 已确认 | | V7 | Zero-Length ClientID Spec Violation | 6.0 | 未确认（符合规范） | **异常率：** 41.4% (118/285) | **Broker 崩溃次数：** 0 ### 活动 2 — Mosquitto 2.0.18（84 个测试用例） 扩展了攻击面：凭据字段、共享订阅、QoS 状态机、连接泛洪、指纹识别。 | 漏洞 | 名称 | CVSS | 结果 | |------|------|------|--------| | V8 | Unauthenticated Credential Acceptance | 6.5 | 已确认 | | V9 | Shared Subscription Namespace Abuse | 5.4 | 已确认 | | V10 | QoS State Machine Leniency (PID=0) | 4.3 | 已确认 | | V11 | Session Persistence Resource Accumulation | 5.3 | 已确认 | | V17 | Broker Configuration Fingerprinting | 3.7 | 已确认 | **累计已确认漏洞：10** ### 活动 3 — 4 个 Broker，978 个测试用例 多 broker 测试：Mosquitto、NanoMQ、HiveMQ CE 2024.3、EMQX 5.0.0。外加 10 个新的漏洞类别以及针对所有先前发现的具体缓解措施。 | 漏洞 | 名称 | CVSS | |------|------|------| | V18 | Oversized CONNECT silent drop | 6.5 | | V19 | 500 subscriptions per packet granted | 5.3 | | V20 | 104,931 PUBLISH/sec — no rate limiting | 7.5 | | V21 | PINGREQ keepalive abuse | 5.3 | | V22 | QoS 2 silently downgraded to QoS 0 | 5.4 | | V24 | 1 PUBLISH → 263 copies (overlapping subs) | 7.5 | | V26 | Null bytes / invalid UTF-8 in topic names | 6.5 | | V27 | keepalive timeout enforcement gap | 5.3 | | V28 | Will self-delivery cross-client injection | 6.8 | | V31 | QoS 2 in-flight session hijacking | 8.1 | **累计已确认漏洞：20** **跨 broker 重点：** - V1、V3、V8、V11 在**全部四个 broker** 上均已确认——属于 MQTT 协议设计默认值，而非实现 bug - EMQX 5.0.0：§2.3.1 的最严重违规者（接受 PUBACK/PUBREC/PUBREL/PUBCOMP 中的 PID=0） - HiveMQ CE：唯一能正确拒绝 PID=0 的 broker - EMQX：正确阻止了 `#` 通配符订阅（V4 未确认） ### 最终活动 — 全部 4 个 Broker，差分模糊测试（100 次 broker 运行） 从根本上重新设计的模糊测试工具（`campaign_final_fuzzer.py`，1,849 行代码，使用原始套接字，无 paho 依赖）。相较于先前活动的主要改进： - **有状态多客户端协调** — 通过 `threading.Barrier` 实现 Publisher / Subscriber / Attacker / Observer 角色 - **差分测试** — 将相同输入并行扇出到所有 4 个 broker；自动对比响应特征 - **7 个模糊测试模块：** 多客户端 (M)、竞态/时序 (R)、MQTT v5 滥用 (V5)、QoS 2 深度状态 (Q)、版本混合 (X)、状态反馈变异 (SFB)、链式攻击 (C) **最终活动新发现：** | 发现 | 细节 | Broker | |---------|--------|-----------| | R1 | 当 DUP 与 PUBREL 发生竞态时，NanoMQ 会发送 2 份 QoS 2 PUBLISH | NanoMQ | | C2 | 消息放大：在 4 个重叠过滤器下，EMQX 3倍，NanoMQ 4倍 | EMQX, NanoMQ | | V51 | 接受无限制的 `SessionExpiry`（MQTT v5） | EMQX | | V52 | 无限制地接受 `UserProperty` 泛洪 | EMQX, HiveMQ | | V53 | 针对越界 Topic Alias 的分歧 reason code | EMQX vs HiveMQ | | V54 | v3.1.1 broker 静默接受 v5 CONNECT 字段 | Mosquitto, NanoMQ | **分歧率：** 64%（16/25 的差分测试显示出 broker 分歧） **最终 broker 风险排名：** HiveMQ CE 2024.3（最低） < EMQX 5.0.0 < Mosquitto 2.0.18 ≈ NanoMQ ## 项目总计 | 指标 | 数值 | |--------|-------| | 活动次数 | 4 | | 总测试用例 | 1,447 | | 已测试 MQTT broker | 4 (Mosquitto, NanoMQ, HiveMQ CE, EMQX) | | 已确认漏洞 | 20+ | | Broker 崩溃次数 | 0 | | 生成的加固配置 | 4（每个 broker 一份） | ## 报告与输出 所有报告均位于 `reports/`。包含原始 JSON 结果以供复现。 | 文件 | 描述 | |------|-------------| | `fuzzing_campaign_report.md` | 活动 1 叙述报告 | | `vulnerability_report.md` | 活动 1 漏洞深度分析 | | `fuzzing_campaign2_report.md` | 活动 2 叙述报告 | | `vulnerability_report_campaign2.md` | V8–V17 深度分析 | | `fuzzing_campaign3_report.md` | 活动 3 叙述报告 | | `vulnerability_report_campaign3.md` | V18–V31 深度分析 | | `mitigations_campaign3.md` | V1–V17 缓解指南 | | `multi_broker_report_campaign3.md` | 跨 broker 对比矩阵 (C3) | | `fuzzing_final_campaign_report.md` | **主叙述报告 — 包含全部 4 次活动** | | `vulnerability_report_final.md` | **最终漏洞目录** | | `multi_broker_final_report.md` | **最终的跨 broker 分析** | | `ai_conversation_log.md` | 用于提交的完整 AI 交互日志 | | `figures/*.png` | 6 项可视化（记分卡、时间线、矩阵） | | `fuzzing_raw_results*.json` | 每次活动的原始测试数据 | ## 纵深防御模型 缓解措施分层跨越 4 个层级，加固配置位于 `config/`： | 层级 | 控制 | 实现 | |------|---------|----------------| | 1 — 身份验证 | 谁可以连接 | `allow_anonymous false`、密码文件、TLS 客户端证书 | | 2 — 授权 | 谁能向何处发布/订阅何种内容 | ACL 文件、拒绝通配符、拒绝 `$SYS/#`、按客户端划分的命名空间 | | 3 — 资源控制 | 防范 DoS | `max_connections`、`max_inflight_messages`、`message_size_limit`、`persistent_client_expiration` | | 4 — 网络 | 边界防御 | 要求使用 mTLS、broker 位于私有网络、防火墙在外部阻断端口 1883 | 运行自动化验证器以检查缓解状态： ``` python scripts/verify_mitigations_final.py # 在所有 4 个 brokers 上运行 28 项检查，输出 PASS/FAIL + JSON ``` ## 运行单元测试 ``` python -m pytest tests/ -v # 37 项通过 (protocol packet encoding) ```

标签：CISA项目, Claude Code, MQTT协议, 人工智能代理, 物联网安全, 请求拦截, 逆向工具