xref: /PHP-8.2/sapi/fuzzer/README.md (revision 093d3346)
1Fuzzing SAPI for PHP
2--------------------
3
4The following `./configure` options can be used to enable the fuzzing SAPI, as well as all available fuzzers. If you don't build the exif/json/mbstring extensions, fuzzers for these extensions will not be built.
5
6```sh
7CC=clang CXX=clang++ \
8./configure \
9    --disable-all \
10    --enable-fuzzer \
11    --with-pic \
12    --enable-debug-assertions \
13    --enable-address-sanitizer \
14    --enable-exif \
15    --enable-mbstring
16```
17
18The `--with-pic` option is required to avoid a linking failure. The `--enable-debug-assertions` option can be used to enable debug assertions despite the use of a release build.
19
20You can combine fuzzing with `--enable-address-sanitizer`, `--enable-undefined-sanitizer` or `--enable-memory-sanitizer`. The first two options can also be used together.
21
22You will need a recent version of clang that supports the `-fsanitize=fuzzer-no-link` option.
23
24When running `make` it creates these binaries in `sapi/fuzzer/`:
25
26* `php-fuzz-parser`: Fuzzing language parser and compiler
27* `php-fuzz-unserialize`: Fuzzing unserialize() function
28* `php-fuzz-unserializehash`: Fuzzing unserialize() for HashContext objects
29* `php-fuzz-json`: Fuzzing JSON parser
30* `php-fuzz-exif`: Fuzzing `exif_read_data()` function (requires --enable-exif)
31* `php-fuzz-mbstring`: Fuzzing `mb_convert_encoding()` (requires `--enable-mbstring`)
32* `php-fuzz-mbregex`: Fuzzing `mb_ereg[i]()` (requires --enable-mbstring)
33* `php-fuzz-execute`: Fuzzing the executor
34* `php-fuzz-function-jit`: Fuzzing the function JIT (requires --enable-opcache)
35* `php-fuzz-tracing-jit`: Fuzzing the tracing JIT (requires --enable-opcache)
36
37Some fuzzers have a seed corpus in `sapi/fuzzer/corpus`. You can use it as follows:
38
39```sh
40cp -r sapi/fuzzer/corpus/exif ./my-exif-corpus
41sapi/fuzzer/php-fuzz-exif ./my-exif-corpus
42```
43
44For the unserialize fuzzer, a dictionary of internal classes should be generated first:
45
46```sh
47sapi/cli/php sapi/fuzzer/generate_unserialize_dict.php
48cp -r sapi/fuzzer/corpus/unserialize ./my-unserialize-corpus
49sapi/fuzzer/php-fuzz-unserialize -dict=$PWD/sapi/fuzzer/dict/unserialize ./my-unserialize-corpus
50```
51
52For the unserializehash fuzzer, generate a corpus of initial hash serializations:
53
54```sh
55sapi/cli/php sapi/fuzzer/generate_unserializehash_corpus.php
56cp -r sapi/fuzzer/corpus/unserializehash ./my-unserialize-corpus
57sapi/fuzzer/php-fuzz-unserializehash ./my-unserialize-corpus
58```
59
60For the parser fuzzer, a corpus may be generated from Zend test files:
61
62```sh
63sapi/cli/php sapi/fuzzer/generate_parser_corpus.php
64mkdir ./my-parser-corpus
65sapi/fuzzer/php-fuzz-parser -merge=1 ./my-parser-corpus sapi/fuzzer/corpus/parser
66sapi/fuzzer/php-fuzz-parser -only_ascii=1 ./my-parser-corpus
67```
68
69For the execute, function-jit and tracing-jit fuzzers, a corpus may be generated from any set of test files:
70
71```sh
72sapi/cli/php sapi/fuzzer/generate_execute_corpus.php ./execute-corpus Zend/tests ext/opcache/tests/jit
73sapi/fuzzer/php-fuzzer-function-jit ./execute-corpus
74```
75
76For the mbstring fuzzer, a dictionary of encodings should be generated first:
77
78```sh
79sapi/cli/php sapi/fuzzer/generate_mbstring_dict.php
80sapi/fuzzer/php-fuzz-mbstring -dict=$PWD/sapi/fuzzer/dict/mbstring ./my-mbstring-corpus
81```
82
83For the mbregex fuzzer, you may want to build the libonig dependency with instrumentation. At this time, libonig is not clean under ubsan, so only the fuzzer and address sanitizers may be used.
84
85```sh
86git clone https://github.com/kkos/oniguruma.git
87pushd oniguruma
88autoreconf -vfi
89./configure CC=clang CFLAGS="-fsanitize=fuzzer-no-link,address -O2 -g"
90make
91popd
92
93export ONIG_CFLAGS="-I$PWD/oniguruma/src"
94export ONIG_LIBS="-L$PWD/oniguruma/src/.libs -l:libonig.a"
95```
96
97This will link an instrumented libonig statically into the PHP binary.
98