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
⚠️ IMPORTANT NOTE⚠️ If you are using Windows to compile IOXY you might need to install TDM-GCC(http://tdm-gcc.tdragon.net/download)
The only prerequisite for using IOXY is a working Golang environment. The steps below install Golang and build the IOXY binary, and have been tested on clean installation of Kali Linux (2022.03 x64):
sudo apt update && sudo apt install -y golang-go
git clone https://github.com/NVISOsecurity/IOXY.git
cd IOXY/ioxy
CGO_CFLAGS="-g -O2 -Wno-return-local-addr" go build -ldflags="-s -w" .
./ioxy gui
⚠️ NOTE⚠️ On some architectures, compiling with the default Golang compiler causes a "panic: runtime error" crash when attempting to run IOXY. In case that happens, uninstall golang-go and install the gccgo-go compiler (sudo apt --purge autoremove golang-go & sudo apt install gccgo-go), then repeat the "go build" step. This should fix the crash. See #11 .
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:
- Gui
✅
-
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
✅
- 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.
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