MQTwister

Table of Contents

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

About this project

MQTwister is an open-source tool for performing Man-in-the-Middle attacks on IoT systems based on the MQTT protocol.

To do this, MQTwister scans incoming packets and applies user-defined substitution rules in real time using its own syntax. In the case of connection packets, MQTwister also records the credentials (ID, username, and password), allowing for network information gathering.

MQTwister is primarily focused on packet processing and is expected to be used after performing the necessary preliminary actions to allow the running machine to intercept communication between an MQTT client and the broker.

Setup

Install from PyPI

MQTwister is published on PyPI, install it with:

python -m pip install mqtwister

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
   

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

To use MQTwister follow the next steps:

1. Configure the tool by editing the mqtwister/config.py with your preferences (such as default network interface, target port, logging level and language).

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

   python -m mqtwister
   

3. Configure session parameters using the user interface.

4. Add substitution rules using the ad hoc syntax item="value" item.action(args), in which "item" may be topic or payload and "action" one of the available options (more info in substitution_rules.md).

5. Start the sniffer to begin the message tampering and credential collection.

License

📃 This project is and its code are licensed under the GNU General Public License version 2 (GPL-2.0). The documentation files and other resources are licensed under the Creative Commons Attribution Share Alike 4.0 International License (CC-BY-SA-4.0). A copy of these licenses can be found in the LICENSE file, and in the LICENSES folder.

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!