1Fuzz Tests for CPython 2====================== 3 4These fuzz tests are designed to be included in Google's `oss-fuzz`_ project. 5 6oss-fuzz works against a library exposing a function of the form 7``int LLVMFuzzerTestOneInput(const uint8_t* data, size_t length)``. We provide 8that library (``fuzzer.c``), and include a ``_fuzz`` module for testing with 9some toy values -- no fuzzing occurs in Python's test suite. 10 11oss-fuzz will regularly pull from CPython, discover all the tests in 12``fuzz_tests.txt``, and run them -- so adding a new test here means it will 13automatically be run in oss-fuzz, while also being smoke-tested as part of 14CPython's test suite. 15 16Adding a new fuzz test 17---------------------- 18 19Add the test name on a new line in ``fuzz_tests.txt``. 20 21In ``fuzzer.c``, add a function to be run:: 22 23 int $test_name (const char* data, size_t size) { 24 ... 25 return 0; 26 } 27 28 29And invoke it from ``LLVMFuzzerTestOneInput``:: 30 31 #if _Py_FUZZ_YES(fuzz_builtin_float) 32 rv |= _run_fuzz(data, size, fuzz_builtin_float); 33 #endif 34 35``LLVMFuzzerTestOneInput`` will run in oss-fuzz, with each test in 36``fuzz_tests.txt`` run separately. 37 38Seed data (corpus) for the test can be provided in a subfolder called 39``<test_name>_corpus`` such as ``fuzz_json_loads_corpus``. A wide variety 40of good input samples allows the fuzzer to more easily explore a diverse 41set of paths and provides a better base to find buggy input from. 42 43Dictionaries of tokens (see oss-fuzz documentation for more details) can 44be placed in the ``dictionaries`` folder with the name of the test. 45For example, ``dictionaries/fuzz_json_loads.dict`` contains JSON tokens 46to guide the fuzzer. 47 48What makes a good fuzz test 49--------------------------- 50 51Libraries written in C that might handle untrusted data are worthwhile. The 52more complex the logic (e.g. parsing), the more likely this is to be a useful 53fuzz test. See the existing examples for reference, and refer to the 54`oss-fuzz`_ docs. 55 56.. _oss-fuzz: https://github.com/google/oss-fuzz 57