diff --git a/docs/running-clusterfuzzlite/github_actions.md b/docs/running-clusterfuzzlite/github_actions.md index 08587a5..996eb02 100644 --- a/docs/running-clusterfuzzlite/github_actions.md +++ b/docs/running-clusterfuzzlite/github_actions.md @@ -102,6 +102,7 @@ Optionally, edit the following fields to customize your settings: - `language` Change to the language of your target code. - `sanitizers` Change or enable more sanitizers. - `fuzz-seconds` Change the amount of time spent fuzzing. +- `parallel-fuzzing`: Use all available CPU cores for fuzzing. - `storage-repo`, `storage-repo-branch`, `storage-repo-branch-coverage` Enable a [storage repo] (not necessary for initial runs, but a useful feature discussed [later on]). @@ -168,6 +169,7 @@ Optionally, edit the following fields to customize your settings: - `cron` Change how frequently batch fuzzing is run. See [GitHub's documentation] on this. - `sanitizers` Change or enable more sanitizers. - `fuzz-seconds` Change the amount of time spent fuzzing. +- `parallel-fuzzing`: Use all available CPU cores for fuzzing. - `storage-repo`, `storage-repo-branch`, `storage-repo-branch-coverage` Enable a [storage repo]. diff --git a/docs/running-clusterfuzzlite/gitlab.md b/docs/running-clusterfuzzlite/gitlab.md index e93a9d9..017f06a 100644 --- a/docs/running-clusterfuzzlite/gitlab.md +++ b/docs/running-clusterfuzzlite/gitlab.md @@ -87,6 +87,7 @@ Optionally, edit the following variables to customize your settings: - `CFL_BRANCH` Branch to fuzz, default is `CI_DEFAULT_BRANCH`. - `FILESTORE` storage for files: builds, corpus, coverage and crashes. - `FUZZ_SECONDS` Change the amount of time spent fuzzing. +- `PARALLEL_FUZZING` Use all available cores when fuzzing. - `CFL_ARTIFACTS_DIR` To save your artifacts in a different directory than `artifacts` ### Batch fuzzing and corpus pruning @@ -136,8 +137,8 @@ keyword to avoid duplicating most of the common parameters between the different The continuous build task causes a build to be triggered and uploaded whenever a new push is done to main/default branches. -Continuous builds are used when a crash is found during PR fuzzing to determine whether the crash was newly introduced. -If the crash was not newly introduced, PR fuzzing will not report it. +Continuous builds are used when a crash is found during MR fuzzing to determine whether the crash was newly introduced. +If the crash was not newly introduced, MR fuzzing will not report it. This means that there will be fewer unrelated failures when running code change fuzzing. @@ -212,7 +213,7 @@ From a performance point of view, it is recommended to use a `docker` gitlab run See this [doc](https://docs.gitlab.com/ee/ci/docker/using_docker_build.html#use-docker-socket-binding) for more information. -To do so, if you have such a runner ready, you simply need to remove the following lines from the configuration : +To do so, if you have such a runner ready, you simply need to remove the following lines from the configuration: {% raw %} ```yaml variables: @@ -249,7 +250,7 @@ For continuous builds, you need to use a [cache](https://docs.gitlab.com/ee/ci/c - cfl-cache/ ``` {% endraw %} -The cache directory needs to defined as `CFL_CACHE_DIR` to be used by ClusterFuzzLite. +The cache directory needs to be defined as `CFL_CACHE_DIR` to be used by ClusterFuzzLite. If it is not defined, the default value is `cache`. You should ensure that the runners share the access to the cache. @@ -263,7 +264,7 @@ project access token, due to your Gitlab license. ![gitlab-project-token] -And this token should be used from the fuzzed repository as a CI/CD variable. +Add the token as a CI/CD variable to your GitLab project. You can name this variable as you like, in the following example it is named `CFL_TOKEN`. This variable should be defined as masked to avoid leaks. It should not be protected if you need it on unprotected branches. diff --git a/docs/running_clusterfuzzlite.md b/docs/running_clusterfuzzlite.md index 0771c6e..928cd8b 100644 --- a/docs/running_clusterfuzzlite.md +++ b/docs/running_clusterfuzzlite.md @@ -153,6 +153,26 @@ specific CI system. coverage report generation). The default is `'address'`. See [Sanitizers] for more information. +- `parallel-fuzzing`: Whether to use all available CPU cores for fuzzing. + The default value is `false`, which only uses a single CPU core. + When set to `true`, ClusterFuzzLite runs multiple fuzzer processes + in parallel with a shared corpus directory. New inputs found by one + fuzzer process will be available to the other fuzzer processes. + The number of cores available depends on your specific CI system. + +- `report-unreproducible-crashes`: Whether to report unreproducible crashes. + The default value is `false`. ClusterFuzzLite will always attempt to reproduce + new crashes. Sometimes crashes can not be reproduced reliably, e.g., + because the fuzz target is in a different state. Read more on + non-reproducible bugs in + [this section](https://google.github.io/oss-fuzz/advanced-topics/bug-fixing-guidance#non-reproducible-bugs). + When set to `true`, even non-reproducable bugs will be reported a + as failure. + +- `minimize-crashes`: If `true`, reportable crashes will be minimized. + The default value is `false`. Minimizing crashes reduces fuzzing time + in batch fuzzing. + - `mode`: The mode for ClusterFuzzLite to execute. `code-change` by default. See [ClusterFuzzLite modes] for more details on how to run different modes.