1## Introduction
2This test uses [american fuzzy lop](http://lcamtuf.coredump.cx/afl/) to mangle real dns, dhcp client, dhcp server packets and look for exceptions caused by the parser.
3
4A few actual packets are collected and exported as bins in the ```in_dns, in_dhcp_client, in_dhcp_server``` folders, which is then passed as input to AFL when testing. The setup procedure for the test includes all possible services and scenarios that could be used with the given input packets. The output of the parser before fuzzing can be found in [input_packets.txt](input_packets.txt)
5
6## Building and running the tests using AFL
7To build and run the tests using AFL(afl-clang-fast) instrumentation
8
9```bash
10cd $IDF_PATH/components/lwip/test_afl_host
11make fuzz MODE=dns/dhcp_client/dhcp_server
12```
13
14(Please note you have to install AFL instrumentation first, check `Installing AFL` section)
15
16## Building the tests using GCC INSTR(off)
17To build the tests without AFL instrumentations and instead of that use GCC compiler(In this case it will only check for compilation issues and will not run AFL tests).
18
19```bash
20cd $IDF_PATH/components/lwip/test_afl_host
21make INSTR=off MODE=dns/dhcp_client/dhcp_server
22```
23
24## Installing AFL
25To run the test yourself, you need to download the [latest afl archive](http://lcamtuf.coredump.cx/afl/releases/afl-latest.tgz) and extract it to a folder on your computer.
26
27The rest of the document will refer to that folder as ```PATH_TO_AFL```.
28
29### Preparation
30- On Mac, you will need to install the latest Xcode and llvm support from [Homebrew](https://brew.sh)
31
32    ```bash
33    /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
34    brew install --with-clang --with-lld --HEAD llvm
35    export PATH="/usr/local/opt/llvm/bin:$PATH"
36    ```
37
38- On Ubuntu you need the following packages:
39
40    ```bash
41    sudo apt-get install make clang-4.0(or <=4.0) llvm-4.0(or <=4.0) libbsd-dev
42    ```
43
44Please note that if specified package version can't be installed(becouse the system is newer than 2017), you can install it from source.
45
46### Compile AFL
47Compiling AFL is as easy as running make:
48
49```bash
50cd [PATH_TO_AFL]
51make
52cd llvm_mode/
53make
54```
55
56After successful compilation, you can export the following variables to your shell (you can also add them to your profile if you want to use AFL in other projects).
57
58```bash
59export AFL_PATH=[PATH_TO_AFL]
60export PATH="$AFL_PATH:$PATH"
61```
62
63Please note LLVM must be <=4.0.0, otherwise afl does not compile, as there are some limitations with building AFL on MacOS/Linux with the latest LLVM. Also, Windows build on cygwin is not fully supported.
64
65## Additional info
66Apple has a crash reporting service that could interfere with AFL's normal operation. To turn that off, run the following command:
67
68```bash
69launchctl unload -w /System/Library/LaunchAgents/com.apple.ReportCrash.plist
70sudo launchctl unload -w /System/Library/LaunchDaemons/com.apple.ReportCrash.Root.plist
71```
72
73Ubuntu has a similar service. To turn that off, run as root:
74
75```bash
76echo core >/proc/sys/kernel/core_pattern
77```
78