| //// |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| //// |
| |
| Log4j contains fuzz tests implemented using https://github.com/CodeIntelligenceTesting/jazzer[Jazzer]footnote:[ |
| We are aware that https://github.com/google/oss-fuzz/discussions/12195[Jazzer is discontinued]. |
| Yet it is still the only mature fuzzing framework in Java and https://google.github.io/oss-fuzz/getting-started/new-project-guide/jvm-lang/#jazzer[the recommended library by OSS-Fuzz].]. |
| These tests are located in `-fuzz-test` prefixed modules; `log4j-core-fuzz-test`, `log4j-layout-template-json-fuzz-test`, etc. |
| |
| [#oss-fuzz] |
| == Google OSS-Fuzz |
| |
| https://github.com/google/oss-fuzz[OSS-Fuzz] is a Google service that continuously runs fuzz tests of critical F/OSS projects on a beefy cluster and reports its findings (bugs, vulnerabilities, etc.) privately to project maintainers. |
| Log4j provides OSS-Fuzz integration with following helpers: |
| |
| - https://github.com/google/oss-fuzz/tree/master/projects/log4j2/Dockerfile[Dockerfile] to create a container image for running tests |
| - link:oss-fuzz-build.sh[`oss-fuzz-build.sh`] to generate fuzz test runner scripts along with all necessary dependencies |
| |
| [#faq] |
| == F.A.Q. |
| |
| Below we will try to answer some frequently asked questions. |
| |
| [#running] |
| === How can I run fuzz tests locally? |
| |
| . Clone the OSS-Fuzz repository: |
| + |
| [source,bash] |
| ---- |
| git clone --depth 1 https://github.com/google/oss-fuzz google-oss-fuzz && cd $_ |
| ---- |
| |
| . Build the container image: |
| + |
| [source,bash] |
| ---- |
| python infra/helper.py build_image log4j2 |
| ---- |
| |
| . Run the container image to build the Log4j project and generate runner scripts along with dependencies: |
| + |
| [source,bash] |
| ---- |
| python infra/helper.py build_fuzzers \ |
| --sanitizer address --engine libfuzzer --architecture x86_64 \ |
| log4j2 |
| ---- |
| |
| . List generated runner scripts: |
| + |
| [source,bash] |
| ---- |
| ls -al build/out/log4j2 |
| ---- |
| |
| . Check one of the generated runner scripts: |
| + |
| [source,bash] |
| ---- |
| python infra/helper.py check_build \ |
| --sanitizer address --engine libfuzzer --architecture x86_64 \ |
| log4j2 log4j-core-fuzz-test-PatternLayoutFuzzer |
| ---- |
| |
| . Execute one of the generated runner scripts: |
| + |
| [source,bash] |
| ---- |
| python infra/helper.py run_fuzzer \ |
| --sanitizer address --engine libfuzzer --architecture x86_64 \ |
| log4j2 log4j-core-fuzz-test-PatternLayoutFuzzer |
| ---- |
| |
| [#view] |
| === How can I view fuzzing failures detected by OSS-Fuzz? |
| |
| The system running fuzzers registered to OSS-Fuzz is called *ClusterFuzz*, which provides https://oss-fuzz.com/[a web interface] for maintainers to monitor the fuzzing results. |
| Tests outputs and <<#reproduce,reproduction>> inputs for failed tests are stored in https://console.cloud.google.com/storage/browser/log4j2-logs.clusterfuzz-external.appspot.com[a Google Cloud Storage bucket]. |
| Access to both the web interface and the bucket is restricted, and only allowed to https://github.com/google/oss-fuzz/blob/master/projects/log4j2/project.yaml[those configured for the project]. |
| |
| [#reproduce] |
| === How can I reproduce fuzzing failures detected by OSS-Fuzz? |
| |
| Download the associated `.testcase` file from https://console.cloud.google.com/storage/browser/log4j2-logs.clusterfuzz-external.appspot.com[the Google Cloud Storage bucket], and run the following command: |
| |
| [source,bash] |
| ---- |
| python infra/helper.py reproduce \ |
| log4j2 <FUZZ-TARGET-NAME> <TESTCASE-FILE-PATH> |
| ---- |
| |
| Refer to https://google.github.io/oss-fuzz/advanced-topics/reproducing/[the related OSS-Fuzz documentation] for details. |