From: Daan De Meyer Date: Thu, 19 Dec 2024 10:26:25 +0000 (+0100) Subject: docs: Move fuzzers documentation to test README.md X-Git-Tag: v258-rc1~1797^2~8 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=3ee5cab49000191743f457b88e2ef0ecafa72891;p=thirdparty%2Fsystemd.git docs: Move fuzzers documentation to test README.md --- diff --git a/docs/HACKING.md b/docs/HACKING.md index cedf35fef0b..2f4765b3938 100644 --- a/docs/HACKING.md +++ b/docs/HACKING.md @@ -201,67 +201,6 @@ Those are not useful when compiling for distribution and can be disabled by sett See [Testing systemd using sanitizers](/TESTING_WITH_SANITIZERS) for more information on how to build with sanitizers enabled in mkosi. -## Fuzzers - -systemd includes fuzzers in `src/fuzz/` that use libFuzzer and are automatically run by [OSS-Fuzz](https://github.com/google/oss-fuzz) with sanitizers. -To add a fuzz target, create a new `src/fuzz/fuzz-foo.c` file with a `LLVMFuzzerTestOneInput` function and add it to the list in `src/fuzz/meson.build`. - -Whenever possible, a seed corpus and a dictionary should also be added with new fuzz targets. -The dictionary should be named `src/fuzz/fuzz-foo.dict` and the seed corpus should be built and exported as `$OUT/fuzz-foo_seed_corpus.zip` in `tools/oss-fuzz.sh`. - -The fuzzers can be built locally if you have libFuzzer installed by running `tools/oss-fuzz.sh`, or by running: - -```sh -CC=clang CXX=clang++ \ -meson setup build-libfuzz -Dllvm-fuzz=true -Db_sanitize=address,undefined -Db_lundef=false \ --Dc_args='-fno-omit-frame-pointer -DFUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION' -ninja -C build-libfuzz fuzzers -``` - -Each fuzzer then can be then run manually together with a directory containing the initial corpus: - -``` -export UBSAN_OPTIONS=print_stacktrace=1:print_summary=1:halt_on_error=1 -build-libfuzz/fuzz-varlink-idl test/fuzz/fuzz-varlink-idl/ -``` - -Note: the `halt_on_error=1` UBSan option is especially important, -otherwise the fuzzer won't crash when undefined behavior is triggered. - -You should also confirm that the fuzzers can be built and run using -[the OSS-Fuzz toolchain](https://google.github.io/oss-fuzz/advanced-topics/reproducing/#building-using-docker): - -```sh -path_to_systemd=... - -git clone --depth=1 https://github.com/google/oss-fuzz -cd oss-fuzz - -for sanitizer in address undefined memory; do -for engine in libfuzzer afl honggfuzz; do -./infra/helper.py build_fuzzers --sanitizer "$sanitizer" --engine "$engine" \ ---clean systemd "$path_to_systemd" - -./infra/helper.py check_build --sanitizer "$sanitizer" --engine "$engine" \ --e ALLOWED_BROKEN_TARGETS_PERCENTAGE=0 systemd -done -done - -./infra/helper.py build_fuzzers --clean --architecture i386 systemd "$path_to_systemd" -./infra/helper.py check_build --architecture i386 -e ALLOWED_BROKEN_TARGETS_PERCENTAGE=0 systemd - -./infra/helper.py build_fuzzers --clean --sanitizer coverage systemd "$path_to_systemd" -./infra/helper.py coverage --no-corpus-download systemd -``` - -If you find a bug that impacts the security of systemd, -please follow the guidance in [CONTRIBUTING.md](/CONTRIBUTING) on how to report a security vulnerability. - -For more details on building fuzzers and integrating with OSS-Fuzz, visit: - -- [Setting up a new project - OSS-Fuzz](https://google.github.io/oss-fuzz/getting-started/new-project-guide/) -- [Tutorials - OSS-Fuzz](https://google.github.io/oss-fuzz/reference/useful-links/#tutorials) - ## Debugging binaries that need to run as root in vscode When trying to debug binaries that need to run as root, diff --git a/test/README.md b/test/README.md index fc1c9f136d1..7f7a7e658cb 100644 --- a/test/README.md +++ b/test/README.md @@ -459,3 +459,72 @@ test unit (be it a static one or a transient one created via systemd-run), with main mount namespace - in that case use `IGNORE_MISSING_COVERAGE=yes` in the test definition (i.e. `TEST-*-NAME/test.sh`), which will skip the post-test check for missing coverage for the respective test. + +## Fuzzers + +systemd includes fuzzers in `src/fuzz/` that use libFuzzer and are automatically +run by [OSS-Fuzz](https://github.com/google/oss-fuzz) with sanitizers. To add a +fuzz target, create a new `src/fuzz/fuzz-foo.c` file with a +`LLVMFuzzerTestOneInput` function and add it to the list in +`src/fuzz/meson.build`. + +Whenever possible, a seed corpus and a dictionary should also be added with new +fuzz targets. The dictionary should be named `src/fuzz/fuzz-foo.dict` and the +seed corpus should be built and exported as `$OUT/fuzz-foo_seed_corpus.zip` in +`tools/oss-fuzz.sh`. + +The fuzzers can be built locally if you have libFuzzer installed by running +`tools/oss-fuzz.sh`, or by running: + +```sh +CC=clang CXX=clang++ \ +meson setup build-libfuzz -Dllvm-fuzz=true -Db_sanitize=address,undefined -Db_lundef=false \ +-Dc_args='-fno-omit-frame-pointer -DFUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION' +ninja -C build-libfuzz fuzzers +``` + +Each fuzzer then can be then run manually together with a directory containing +the initial corpus: + +``` +export UBSAN_OPTIONS=print_stacktrace=1:print_summary=1:halt_on_error=1 +build-libfuzz/fuzz-varlink-idl test/fuzz/fuzz-varlink-idl/ +``` + +Note: the `halt_on_error=1` UBSan option is especially important, otherwise the +fuzzer won't crash when undefined behavior is triggered. + +You should also confirm that the fuzzers can be built and run using +[the OSS-Fuzz toolchain](https://google.github.io/oss-fuzz/advanced-topics/reproducing/#building-using-docker): + +```sh +path_to_systemd=... + +git clone --depth=1 https://github.com/google/oss-fuzz +cd oss-fuzz + +for sanitizer in address undefined memory; do +for engine in libfuzzer afl honggfuzz; do +./infra/helper.py build_fuzzers --sanitizer "$sanitizer" --engine "$engine" \ +--clean systemd "$path_to_systemd" + +./infra/helper.py check_build --sanitizer "$sanitizer" --engine "$engine" \ +-e ALLOWED_BROKEN_TARGETS_PERCENTAGE=0 systemd +done +done + +./infra/helper.py build_fuzzers --clean --architecture i386 systemd "$path_to_systemd" +./infra/helper.py check_build --architecture i386 -e ALLOWED_BROKEN_TARGETS_PERCENTAGE=0 systemd + +./infra/helper.py build_fuzzers --clean --sanitizer coverage systemd "$path_to_systemd" +./infra/helper.py coverage --no-corpus-download systemd +``` + +If you find a bug that impacts the security of systemd, please follow the +guidance in [CONTRIBUTING.md](/CONTRIBUTING) on how to report a security +vulnerability. + +For more details on building fuzzers and integrating with OSS-Fuzz, visit: + +- [Setting up a new project - OSS-Fuzz](https://google.github.io/oss-fuzz/getting-started/new-project-guide/) +- [Tutorials - OSS-Fuzz](https://google.github.io/oss-fuzz/reference/useful-links/#tutorials)