/IOXY

MQTT intercepting proxy

Primary LanguageGoGNU General Public License v3.0GPL-3.0

Ioxy logo

IOXY - MQTT intercepting proxy

What?

IOXY (IoT + Proxy) is an MQTT intercepting proxy written in Golang. It supports MQTT, MQTTS and MQTT over WebSockets and has both a CLI and a GUI.

Why?

We frequently perform security assessment on IoT devices using MQTT to communicate with their backend. We wanted a tool that allows us to intercept, inspect and tamper with MQTT communications with the same ease as other intercepting proxies, like Burp and Zap, do for HTTP.

This is why we started working on IOXY. We put a lot of effort in this tool, and hope it will be useful to the community!

Quick start

The only prerequisite for using IOXY is a working Golang environment. Then, just clone the repo and build the IOXY binary:

git clone https://github.com/NVISO-BE/IOXY
cd IOXY/ioxy && go build .

Finally, fire up the GUI and use the Settings screen to set up the intercepting server:

./ioxy gui

CLI

Usage : ioxy ACOMMAND BCOMMAND [CCOMMAND] [DCOMMAND]

[] = optional

ACommands:
  mqtt	  	Create a mqtt server (0.0.0.0:1883 by default)
  mqtts	  	Create a mqtts server (0.0.0.0:8883 by default)
  http	  	Create a http server (0.0.0.0:8080 by default)
  https	  	Create a https server	(0.0.0.0:8081 by default)

BCommands :
  broker  	Used to set up the distant broker settings

CCommands :
  mitm-opt 	Mitm options like intercept

DCOMMAND :
  gui

Run 'ioxy COMMAND -h' for more information on a command.

Examples

Check the examples below for a walkthrough on IOXY's features.

AWS

Features

Below you'll find a quick overview of the features provided by IOXY. Legend:

✅ Implemented, tested
❓ Implemented, not tested

  • Gui ✅

app settings logs

  • Packet storing in SQLite Database ✅

      Tables
      ├── session_mgmt
      │   ├── client_id
      │   ├── session_id
      │   ├── username
      │   └── password
      └── messages
          ├── session_id
          ├── topic
          ├── payload
          ├── dup_flag
          ├── retain_flag
          ├── qos_flag
          └── timestamp
    
  • Live packet modification ✅

messages table

  • Amazon ALPN support ✅

Supported Protocols

  • Client → Proxy

    ✅ MQTT
    ✅ MQTTS
    ❓ HTTP (WebSocket)
    ❓ HTTPS (Secure WebSocket)

  • Proxy → Broker

    ✅ MQTT
    ✅ MQTTS
    ❓ HTTP (WebSocket)
    ❓ HTTPS (Secure WebSocket)

Bugs and contributions

Found a bug? Have an idea for a new feature? Please create an issue. We are monitoring the issue tracker and will follow up on any bug reports or new feature requests. More detailed information about code contributions to IOXY will be available soon.

Acknowledgments

This project was made possible thanks to Innoviris and SCRATCh, an ITEA3 project.

Innoviris logo ITEA3 logo

Axway's "mqtt-proxy" repo provided a solid base for this project. IOXY's GUI uses "Gorilla WebSocket".

Authors

  • Julian Dotreppe (hutchYy) - Initial work
  • Cédric Bassem (cbassem) - Maintainer
  • Théo Rigas (windBlaze) - Maintainer

Useful resources and documentation

Network Attacks GitHub

SANS

AWS

MQTT[.]org

MQTT-PWN

Other