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 38What makes a good fuzz test 39--------------------------- 40 41Libraries written in C that might handle untrusted data are worthwhile. The 42more complex the logic (e.g. parsing), the more likely this is to be a useful 43fuzz test. See the existing examples for reference, and refer to the 44`oss-fuzz`_ docs. 45 46.. _oss-fuzz: https://github.com/google/oss-fuzz 47