mqtt-packet-fuzzy

A radamsa fuzzer-enabled version of mqtt-packet@5.6.0 for testing.

mqtt-packet-fuzzy is a fork of mqttjs/mqtt-packet@5.6.0 which instruments the writeToStream functionality of mqtt-packet with a radamsa-backed fuzzing system. This allows security testers to fuzz MQTT protocols without having to dump testcases, circumvent pinning, strip TLS, et cetera. Take a real Node.js MQTT client that depends on mqtt-packet@^5.0.0, replace mqtt-packet with this package, and let the low-level hooking do all the fuzzing for you.

mqtt-packet-fuzzy does not require an existing radamsa fuzzer to be on the device path; it uses sinkdweller to handle radamsa offload, which works on Windows, Linux and macOS at the time of this writing.

Usage

For an existing client that uses mqtt-packet, do a normal npm install. Then, remove the mqtt-packet in the node_modules folder and replace it with the contents of this repository. Since it is mqtt-packet, nothing changes except for its output. Then, simply enable the fuzzing for your client with the environment variable:

$ MQTT_FUZZ_ENABLE=1 node /path/to/my/client.js

Most of the fuzzer code is in fuzzMaybe.js.

Customizing the fuzzer

In order to stay as much out of the way as possible but still allow customization, mqtt-packet-fuzzy options can be modified by using environment variables. This allows your tests to omit some packet types, payloads, or specific strings, which may be useful to get further down a logic tree than you would get simply spewing MQTT chaos over the wire.

Enabling the fuzzer

• MQTT_FUZZ_ENABLE — {0, 1} — Whether or not to enable the fuzzer. The fuzzer will not run unless MQTT_FUZZ_ENABLE=1. Default: 0

Protocol-specific options (default all to 1 (on))

• MQTT_FUZZ_FLAGS — {0, 1} — Fuzz MQTT control flags.
• MQTT_FUZZ_HEADERS — {0, 1} — Fuzz control headers.
• MQTT_FUZZ_LENGTHS — {0, 1} — Fuzz packet lengths.
• MQTT_FUZZ_NUMBERS — {0, 1} — Fuzz any number being written.
• MQTT_FUZZ_PROTOCOL_VERSION — {0, 1} — Fuzz protocol versions.
• MQTT_FUZZ_STRINGS — {0, 1} — Fuzz strings (payloads).

Fuzzer control options

• MQTT_FUZZ_SEED — {'timestamp', Number} — Set the radamsa seed. timestamp will use the current timestamp from new Date().getTime() as the radamsa seed. This is useful for fuzzing when you can see logs on the other side and correlate crashes to timestamps, as it helps in reproducing a testcase. Default timestamp
• MQTT_FUZZ_SHOW_IO — {0, 1} — Show input/output on console.debug. Useful when using traceback to save or parse testcases. Default 0
• MQTT_FUZZ_SKIP_CONTAINING — {String} — Skip any strings containing this string, and do not fuzz the input. This is useful to skip over auth tokens, etc. where you may need to have them complete to move further in the broker logic. Default ''
• MQTT_FUZZ_SKIP_FIRST_INPUTS — {Number} — Skip the first n inputs. Useful for running the fuzzer where the beginning few MQTT messages need to be proper in order to set up a connection and do more. Default 0

License

© 2019 rarecoil. MIT.