X-Git-Url: http://plrg.eecs.uci.edu/git/?a=blobdiff_plain;f=docs%2FLibFuzzer.rst;h=cbb97e78107bbb7faf07f1c4240eed641858c05d;hb=43be5f580c428d40c794917273256226e8ee391c;hp=519c651bf00851043d36f8a8c69bbe449a20dae9;hpb=6cc3ed7cdddcd09a5905039054fbd306e414202d;p=oota-llvm.git diff --git a/docs/LibFuzzer.rst b/docs/LibFuzzer.rst index 519c651bf00..cbb97e78107 100644 --- a/docs/LibFuzzer.rst +++ b/docs/LibFuzzer.rst @@ -21,7 +21,8 @@ This library is intended primarily for in-process coverage-guided fuzz testing optimizations options (e.g. -O0, -O1, -O2) to diversify testing. * Build a test driver using the same options as the library. The test driver is a C/C++ file containing interesting calls to the library - inside a single function ``extern "C" void LLVMFuzzerTestOneInput(const uint8_t *Data, size_t Size);`` + inside a single function ``extern "C" int LLVMFuzzerTestOneInput(const uint8_t *Data, size_t Size);``. + Currently, the only expected return value is 0, others are reserved for future. * Link the Fuzzer, the library and the driver together into an executable using the same sanitizer options as for the library. * Collect the initial corpus of inputs for the @@ -60,15 +61,18 @@ The most important flags are:: cross_over 1 If 1, cross over inputs. mutate_depth 5 Apply this number of consecutive mutations to each input. timeout 1200 Timeout in seconds (if positive). If one unit runs more than this number of seconds the process will abort. + max_total_time 0 If positive, indicates the maximal total time in seconds to run the fuzzer. help 0 Print help. - save_minimized_corpus 0 If 1, the minimized corpus is saved into the first input directory + save_minimized_corpus 0 If 1, the minimized corpus is saved into the first input directory. Example: ./fuzzer -save_minimized_corpus=1 NEW_EMPTY_DIR OLD_CORPUS + merge 0 If 1, the 2-nd, 3-rd, etc corpora will be merged into the 1-st corpus. Only interesting units will be taken. jobs 0 Number of jobs to run. If jobs >= 1 we spawn this number of jobs in separate worker processes with stdout/stderr redirected to fuzz-JOB.log. workers 0 Number of simultaneous worker processes to run the jobs. If zero, "min(jobs,NumberOfCpuCores()/2)" is used. sync_command 0 Execute an external command " " to synchronize the test corpus. sync_timeout 600 Minimum timeout between syncs. use_traces 0 Experimental: use instruction traces only_ascii 0 If 1, generate only ASCII (isprint+isspace) inputs. - + test_single_input "" Use specified file content as test input. Test will be run only once. Useful for debugging a particular case. + artifact_prefix "" Write fuzzing artifacts (crash, timeout, or slow inputs) as $(artifact_prefix)file For the full list of flags run the fuzzer binary with ``-help=1``. @@ -81,11 +85,12 @@ Toy example A simple function that does something interesting if it receives the input "HI!":: cat << EOF >> test_fuzzer.cc - extern "C" void LLVMFuzzerTestOneInput(const unsigned char *data, unsigned long size) { + extern "C" int LLVMFuzzerTestOneInput(const unsigned char *data, unsigned long size) { if (size > 0 && data[0] == 'H') if (size > 1 && data[1] == 'I') if (size > 2 && data[2] == '!') __builtin_trap(); + return 0; } EOF # Get lib/Fuzzer. Assuming that you already have fresh clang in PATH. @@ -117,8 +122,8 @@ Here we show how to use lib/Fuzzer on something real, yet simple: pcre2_:: cat << EOF > pcre_fuzzer.cc #include #include "pcre2posix.h" - extern "C" void LLVMFuzzerTestOneInput(const unsigned char *data, size_t size) { - if (size < 1) return; + extern "C" int LLVMFuzzerTestOneInput(const unsigned char *data, size_t size) { + if (size < 1) return 0; char *str = new char[size+1]; memcpy(str, data, size); str[size] = 0; @@ -128,6 +133,7 @@ Here we show how to use lib/Fuzzer on something real, yet simple: pcre2_:: regfree(&preg); } delete [] str; + return 0; } EOF clang++ -g -fsanitize=address $COV_FLAGS -c -std=c++11 -I inst/include/ pcre_fuzzer.cc @@ -225,7 +231,7 @@ to find Heartbleed with LibFuzzer:: assert (SSL_CTX_use_PrivateKey_file(sctx, "server.key", SSL_FILETYPE_PEM)); return 0; } - extern "C" void LLVMFuzzerTestOneInput(unsigned char *Data, size_t Size) { + extern "C" int LLVMFuzzerTestOneInput(unsigned char *Data, size_t Size) { static int unused = Init(); SSL *server = SSL_new(sctx); BIO *sinbio = BIO_new(BIO_s_mem()); @@ -235,9 +241,10 @@ to find Heartbleed with LibFuzzer:: BIO_write(sinbio, Data, Size); SSL_do_handshake(server); SSL_free(server); + return 0; } EOF - # Build the fuzzer. + # Build the fuzzer. clang++ -g handshake-fuzz.cc -fsanitize=address \ openssl-1.0.1f/libssl.a openssl-1.0.1f/libcrypto.a Fuzzer*.o # Run 20 independent fuzzer jobs. @@ -350,6 +357,24 @@ llvm-as-fuzzer Tracking bug: https://llvm.org/bugs/show_bug.cgi?id=24639 +llvm-mc-fuzzer +-------------- + +This tool fuzzes the MC layer. Currently it is only able to fuzz the +disassembler but it is hoped that assembly, and round-trip verification will be +added in future. + +When run in dissassembly mode, the inputs are opcodes to be disassembled. The +fuzzer will consume as many instructions as possible and will stop when it +finds an invalid instruction or runs out of data. + +Please note that the command line interface differs slightly from that of other +fuzzers. The fuzzer arguments should follow ``--fuzzer-args`` and should have +a single dash, while other arguments control the operation mode and target in a +similar manner to ``llvm-mc`` and should have two dashes. For example:: + + llvm-mc-fuzzer --triple=aarch64-linux-gnu --disassemble --fuzzer-args -max_len=4 -jobs=10 + Buildbot -------- @@ -433,23 +458,27 @@ Trophies * http://git.musl-libc.org/cgit/musl/commit/?id=39dfd58417ef642307d90306e1c7e50aaec5a35c * http://www.openwall.com/lists/oss-security/2015/03/30/3 -* pugixml: https://github.com/zeux/pugixml/issues/39 +* `pugixml `_ -* PCRE: Search for "LLVM fuzzer" in http://vcs.pcre.org/pcre2/code/trunk/ChangeLog?view=markup +* PCRE: Search for "LLVM fuzzer" in http://vcs.pcre.org/pcre2/code/trunk/ChangeLog?view=markup; + also in `bugzilla `_ -* ICU: http://bugs.icu-project.org/trac/ticket/11838 +* `ICU `_ -* LLVM: +* `Freetype `_ - * Clang: https://llvm.org/bugs/show_bug.cgi?id=23057 +* `Harfbuzz `_ - * Clang-format: https://llvm.org/bugs/show_bug.cgi?id=23052 +* `SQLite `_ - * libc++: https://llvm.org/bugs/show_bug.cgi?id=24411 +* `Python `_ - * llvm-as: https://llvm.org/bugs/show_bug.cgi?id=24639 +* `Libxml2 + `_ +* `Linux Kernel's BPF verifier `_ +* LLVM: `Clang `_, `Clang-format `_, `libc++ `_, `llvm-as `_, Disassembler: http://reviews.llvm.org/rL247405, http://reviews.llvm.org/rL247414, http://reviews.llvm.org/rL247416, http://reviews.llvm.org/rL247417, http://reviews.llvm.org/rL247420, http://reviews.llvm.org/rL247422. .. _pcre2: http://www.pcre.org/