Instructions for running the AFL tools -------------------------------------- 1. The folder mafl-2.35b contains a slightly modified version of afl-gcc, that we have produced. The changes are as follows: (a) code optimizations are disabled in this version of afl-gcc (these make the assembly code hard to understand), and (b) this version of afl-gcc emits a file random-loc.txt. This file contains information about trampolines, and is required by the script xor.py. We have also modified afl-showmap. We describe the modification later in this writeup. Even though we have not modified the other AFL tools, like afl-fuzz, you should use the tools in this folder only and should not directly download AFL from the AFL site. Note, you may need to run a "make" within this folder on your system. 2. Before running afl-gcc, in the same terminal, run the following commands: export AFL_PATH=/full/path/to/mafl-2.35b/ export AFL_KEEP_ASSEMBLY=1 export TMPDIR=. The last two commands above basically instruct afl-gcc to not throw away the assembly language file that it produces. The assembly language file's name will begin with a "." (so, it will be a hidden file). The file will be present in the same directory where you run afl-gcc. Note that if several assembly language files are present corresponding to your program, then you can ignore all but the most recent version. 3. To run afl-gcc on a file pgm.c, run the following: /full/path/to/mafl-2.35b/afl-gcc pgm.c -o pgm In addition to producing the executable file "pgm", this run also produces the file random-loc.txt, as well as the assembly language file (for human inspection). 4. Before running afl-fuzz, you need to use "sudo cpufreq-set" to set the frequency governors of *all* your cores to the "performance" governor. (Some distributions of Ubuntu may have UI based controls to do the same thing.) If for some reason you are not able to do the step above, then run the following command in the same terminal from which you plan to run afl-fuzz: export AFL_SKIP_CPUFREQ=1 Also, you may need to set export AFL_I_DONT_CARE_ABOUT_MISSING_CRASHES=1 Note that setting the flag above can cause crashing inputs to appear in the "hangs" sub-folder. 5. Run afl-fuzz as follows: /full/path/to/mafl-2.35b/afl-fuzz -i pgmIn -o pgmOut ./pgm The directory pgmIn should contain the seed file(s) that you supply. pgmOut will contain the output files produced by afl. The "queue" folder within this directory contains all the non-crashing non-hanging test inputs that were placed in the Q by afl-fuzz. Note that the name of each test input file in this directory encodes the sequence number of creation of this file (the "id" field), the test input(s) that served as parents for this test input (the "src" field), the mutation operation that was used to produce this input (the "op" field), and the position in the parent test input where the mutation was performed (the "pos" field), and the number of locations where the mutation was performed (the "rep" field, for non-deterministic mutations). The "hangs" folder will contain the test inputs that caused the program to hang (i.e., take more than 20 milliseconds to finish executing). This default timeout can be changed using an option of afl-fuzz. The "crashes" folder will contain the test inputs that caused the program to crash. 6. To see the final branch map table at the end of a run on a test input file t, run the following command: /full/path/to/mafl-2.35b/afl-showmap -o showmap-result.txt ./pgm < t We have modified afl-showmap compared to its original version. The output file showmap-result.txt will contain two columns. The first column in the branch-pair index (i.e., the xor operation's result), while the second column shows the EXACT number of times this branch pair was traversed in the run (without any rounding off). Unvisited branch pairs are omitted. (The original version of afl-showmap shows the log to the base 2 of the rounded value of the visit count, not the exact visit count.) 7. To understand the contents of showmap-result.txt, you can run our script /full/path/to/mafl-2.35b/xor.py. This script takes no arguments. (python2 needs to be installed on your computer.) xor.py needs random-loc.txt and showmap-result.txt to be present in the same directory from where you invoked xor.py. The output from xor.py is a file Table.txt. Each row in this table corresponds to a branch pair (i.e., to a unique pair of trampolines) in the assembly file. "Prev Random" is the random number corresponding to the previous trampoline visited, while "Curr Random" corresponds to the current trampoline being visited. "Table Index" is the branch-pair index. That is, it is nothing but "Prev Random">>1 XOR "Curr Random", and serves as the index into the Shm array that is accessed and incremented during the current visit to the trampoline. Note that the visit to the very first trampoline (where prev_random is zero) is not recorded in Table.txt (it is present in showmap-result.txt). Note that in case you re-compile your program using afl-gcc, a latest assembly language file (with a fresh set of random numbers in the trampolines will be produced). Therefore, to generate fresh results that are consistent with this assembly language file, you would need to run afl-showmap and xor.py once again. Contents of the directory ForClassWhile --------------------------------------- This directory contains the sample program that we used in class. The files in this directory are: - The program for-class-while.c. - The executable for-class-while. - The assembly language file .afl-3937-1490849217.s - A manually created file assembly-program-in-brief.s, which describes the high-level structure of the assembly language file mentioned above. - random-loc.txt, as discussed above. - The directories whileIn and whileOut. whileIn contains the seed file. whileOut contains the output of afl-fuzz. - showmap-result.txt, as produced using the following test input file: whileOut/queue/id\:000001\,src\:000000\,op\:flip1\,pos\:0 - Table.txt, produced by xor.py, from showmap-result.txt mentioned above.