{"id":36027485,"url":"https://github.com/WithSecureOpenSource/mqtt_fuzz","last_synced_at":"2026-01-11T20:00:39.893Z","repository":{"id":31655276,"uuid":"35220613","full_name":"WithSecureOpenSource/mqtt_fuzz","owner":"WithSecureOpenSource","description":"A simple fuzzer for the MQTT protocol","archived":false,"fork":false,"pushed_at":"2022-03-21T08:38:51.000Z","size":18,"stargazers_count":80,"open_issues_count":1,"forks_count":20,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-06-24T21:29:22.507Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WithSecureOpenSource.png","metadata":{"files":{"readme":"readme.txt","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-05-07T13:08:51.000Z","updated_at":"2025-06-20T07:07:08.000Z","dependencies_parsed_at":"2022-08-03T08:46:10.714Z","dependency_job_id":null,"html_url":"https://github.com/WithSecureOpenSource/mqtt_fuzz","commit_stats":null,"previous_names":["withsecureopensource/mqtt_fuzz","f-secure/mqtt_fuzz"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/WithSecureOpenSource/mqtt_fuzz","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WithSecureOpenSource%2Fmqtt_fuzz","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WithSecureOpenSource%2Fmqtt_fuzz/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WithSecureOpenSource%2Fmqtt_fuzz/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WithSecureOpenSource%2Fmqtt_fuzz/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WithSecureOpenSource","download_url":"https://codeload.github.com/WithSecureOpenSource/mqtt_fuzz/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WithSecureOpenSource%2Fmqtt_fuzz/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28321263,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-11T18:42:50.174Z","status":"ssl_error","status_checked_at":"2026-01-11T18:39:13.842Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-10T15:00:40.726Z","updated_at":"2026-01-11T20:00:39.871Z","avatar_url":"https://github.com/WithSecureOpenSource.png","language":"Python","readme":"mqtt_fuzz\n=========\n\nThis is a simple fuzzer for the MQTT (http://mqtt.org) protocol. It\ndoes not try to implement any fancy protocol processing; instead, it\nplays back recorded MQTT control packets, and once in a while, sends a\nfuzzed control packet.\n\nRequirements\n------------\n\nYou need to obtain and compile Radamsa\n(https://github.com/aoh/radamsa). Fuzz cases are generated using\nRadamsa. The tool has been tested with version 0.4a. Earlier versions\nmay have different command line parameters and thus may not work.\n\nYou need to install Python Twisted. Do this either through pip or from\nhttps://twistedmatrix.com/trac/wiki/Downloads.\n\nUsage\n-----\n\nDO NOT RUN THE TOOL AGAINST A TARGET THAT YOU DO NOT HAVE AN\nAUTHORIZATION TO TEST.\n\nChoose which MQTT server (broker) you want to test. You might want to\nconsider linking it with address sanitizer (ASan, e.g.,\n-fsanitize=address). ASan helps to ensure that the target truly\ncrashes if the fuzz cases cause corruption.\n\nIt is suggested that you run the target under the debugger so when it\ncrashes, you get a stack trace. You can also run the GDB 'exploitable'\ncommand (https://github.com/jfoote/exploitable) to quickly determine\nhow worried you need to be.\n\nRun the tool. For command line options, run\n\n  python mqtt_fuzz.py --help\n\nThe tool sends a series of pre-defined sequences of MQTT control\npackets. You can change these sequences, and extend the control packet\nsupport (see 'Extending mqtt_fuzz', below).\n\nThe ratio of valid:fuzzed control packets controls how quickly the\nfuzz cases are being sent. Sending too many fuzzed packets may\ndecrease the test effectiveness - for example, if all your CONNECT\npackets are always fuzzed, you might not ever get to tickle the\nserver's state machine beyond the CONNECT.\n\nThe tool will run until the server stops responding to new\nconnections.\n\nEach control packet sequence ('session') will have a unique UUID tag\nand all messages will be timestamped on the output. Ensure that the\ntarget and fuzzer hosts' clocks are synchronised, and you can find the\nmessages that caused problems using the timestamp. The process is as\nfollows:\n\n1) Detect a crash and get a UNIX epoch timestamp of the crash (shown\n   in gdb by default).\n2) Select all the lines from the fuzzer's output log that have that\n   timestamp.\n3) Determine all the session UUIDs that are listed on those lines.\n4) Extract all the lines from the fuzzer's output log that have one of\n   these UUIDs (those sessions may start or end before and after the\n   timestamp).\n5) Now you have all the control messages that were sent, and their\n   ordering.\n\nIf you run the fuzzer in test automation, you would likely want to\nautomate this analysis step.\n\nThe control messages that are sent are output to the log using base64\nencoding. The wire protocol of MQTT is binary; base64 is used here\njust to enable easier copy-pasting of the control messages in a format\nthat is less likely to cause problems.\n\nOnce you have found a sequence of control messages that caused the\ncrash, you can extract all the control messages from the log and put\nthem into reprotool.py. This tool will send those messages to the\nhost. Edit the number and order of the messages so that you can\nreproduce the crash running reprotool.py. Once you have the minimal\nset that triggers the crash, you have a suitable PoC for the MQTT\nserver developers.\n\nExtending mqtt_fuzz\n-------------------\n\nMQTT tests MQTT servers by acting as a client.\n\nThe default installation currently has the following control packets [*]:\n\nCONNECT\nCONNACK\nPUBLISH\nPUBACK\nSUBSCRIBE\nPUBCOMP\nPUBREL\nPUBREC\nDISCONNECT\n\nSpecifically, the following control packets are missing:\n\nUNSUBSCRIBE\nUNSUBACK\nPINGREQ\nPINGRESP\nSUBACK\n\nSome of the missing packets are server-to-client packets, so in theory\nshouldn't be in scope. However, for fuzzing, they should be fair game\nand should be sent to the server during testing.\n\nYour application might also process data on higher protocol layers\n(that is, data that is published and subscribed to using MQTT). That\ncode would usually benefit from fuzz testing, too. Although it would\nbe preferable to use valid MQTT and just fuzz the higher-level\nprotocol, mqtt_fuzz can be used here by adding new control packets\nthat carry the higher-level protocol data. You are likely to require\nlonger fuzz test runs.\n\nYou can add new control packets simply by creating a new directory\n(with an arbitrary name) under mqtt_fuzz/valid-cases, and putting\nexamples of valid control packets in that directory. You can obtain\nthose examples, for example, by sniffing traffic with Wireshark (\u003e\n1.12.0) and by extracting the raw MQTT protocol layer data into files\nin that directory. In addition, you need to add a new session in the\nsession_structures list that actually uses that control packet.\n\nAs an example, assume you want to add a new control packet where you\nhave your own payload within the PUBLISH message, and you want to fuzz\nthese kind of messages. You could create a directory\nvalid-cases/publish-with-payload, copy raw example valid cases into\nthis directory (minimum of one, optimally around 15), and then add the\nfollowing list in the session_structures:\n\n['connect', 'publish-with-payload', 'disconnect']\n\nNow you have a new control packet added. Fuzz case generation will be\nautomatic.\n\nLegal\n-----\n\nSee LICENCE.\n\nContact: opensource@f-secure.com.\nOriginal tool author: Antti Vähä-Sipilä.\n\n[*] The control packet examples in the tool's valid case directories\nhave been sniffed with Wireshark from traffic that was generated by\nEclipse Paho MQTT interoperability testing tool (client_test.py) at\nhttps://git.eclipse.org/c/paho/org.eclipse.paho.mqtt.testing.git/.  To\nclarify, the valid cases only constitute of output whose syntax is\ngoverned by the MQTT protocol specification, and do not include any\ncode from the tool itself. If you have further MQTT control packet\nexamples that you'd like to contribute, please send a pull request.\n","funding_links":[],"categories":["Tools"],"sub_categories":["Talks"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FWithSecureOpenSource%2Fmqtt_fuzz","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FWithSecureOpenSource%2Fmqtt_fuzz","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FWithSecureOpenSource%2Fmqtt_fuzz/lists"}