mirror of
https://github.com/RIOT-OS/RIOT.git
synced 2024-12-29 04:50:03 +01:00
87 lines
3.6 KiB
Markdown
87 lines
3.6 KiB
Markdown
# Fuzzing
|
|
|
|
Automated fuzzing tests for RIOT network applications.
|
|
|
|
## Setup
|
|
|
|
The following additional dependencies are required:
|
|
|
|
* [afl][afl homepage]
|
|
* [libasan][sanitizers github] (optional but recommended)
|
|
|
|
## Writing a fuzzing application
|
|
|
|
The fuzzing setup relies heavily on RIOT's [netapi][netapi doc]
|
|
interface, or more generally RIOT's message passing algorithm. RIOT
|
|
modules implementing network protocols usually start a single thread
|
|
which receives messages via message passing and interprets these as
|
|
protocol messages for further processing. This software architecture is
|
|
utilized by the fuzzing setup by sending random data to network modules
|
|
using message passing.
|
|
|
|
For each network module which should be fuzzed a protocol specific
|
|
fuzzing application needs to be written. This application must
|
|
initialize the network module and make sure that the thread is started
|
|
and configured correctly. Afterwards, the application must read from
|
|
standard input where random data is provided by AFL which must be
|
|
converted to a `gnrc_pktsnip_t` by the application. The fuzzing module
|
|
provides a utility function (`fuzzing_read_packet`) for this purpose.
|
|
|
|
Additionally, the fuzzing application is responsible for ensuring the
|
|
correct protocol specific encapsulation for the `gnrc_pktsnip_t` type.
|
|
For instance, the `gnrc_tcp` module expects each packet, received
|
|
via message passing, to be encapsulated in an IP datagram. This
|
|
encapsulation is created by the fuzzing application.
|
|
|
|
Afterwards, the created `gnrc_pktsnip_t` is dispatched to the started
|
|
network module thread using `netapi`. As soon as the network module
|
|
finished processing the packet, i.e. frees it (or requests the next one
|
|
when using the `sock` API), the fuzzing application is terminated and
|
|
started again with new random input by AFL. Currently, only a single
|
|
packet can be processed per invocation.
|
|
|
|
## Input Corpus
|
|
|
|
AFL utilizes mutation-based input generation and as such requires an
|
|
initial input corpus. Refer to the [AFL manual][afl-fuzz approach] for
|
|
further information an AFL's input generation algorithm. The input
|
|
corpus should consist of valid protocol messages and should be as small
|
|
as possible. The input corpus for a given fuzzing application is located
|
|
in the `input/` subdirectory, each file in this directory represents a
|
|
single protocol message. Depending on the specific protocol, an input
|
|
corpus may be generated using a script or by extracting packets from a
|
|
sniffed sample communication (e.g. using `wireshark`).
|
|
|
|
When creating a new fuzzing application, it is advisable to test that
|
|
packets of the input corpus are successfully processed. This can be done
|
|
by setting `ENABLE_DEBUG` for the tested module and running:
|
|
|
|
make -C fuzzing/<application> term < fuzzing/<application>/input/<packet>
|
|
|
|
## Invocation
|
|
|
|
Before fuzzing an application it needs to be compiled, to ease detection
|
|
of unwanted behaviour (e.g. out-of-bounds buffer accesses), compiling
|
|
with `all-asan` is highly recommended. For example:
|
|
|
|
make -C fuzzing/<application> all-asan
|
|
|
|
Afterwards invoke afl using:
|
|
|
|
make -C fuzzing/<application> fuzz
|
|
|
|
### Parallel Fuzzing
|
|
|
|
Parallel fuzzing is supported through `FLAGS_FOR_AFL`, e.g.:
|
|
|
|
# Start first AFL instance
|
|
FLAGS_FOR_AFL="-M fuzzer01" make -C fuzzing/gnrc_tcp/ fuzz
|
|
|
|
# Start second AFL instance in a different terminal
|
|
FLAGS_FOR_AFL="-S fuzzer02" make -C fuzzing/gnrc_tcp/ fuzz
|
|
|
|
[sanitizers github]: https://github.com/google/sanitizers
|
|
[afl homepage]: http://lcamtuf.coredump.cx/afl/
|
|
[netapi doc]: https://riot-os.org/api/netapi_8h.html
|
|
[afl-fuzz approach]: https://github.com/google/AFL/blob/ca01f9a4c4ccb59d349c729ad3018e339f9aae0c/README.md#2-the-afl-fuzz-approach
|