This is an automated email from the ASF dual-hosted git repository. centic9 pushed a commit to branch add_fuzzing_readme_and_fix_npe in repository https://gitbox.apache.org/repos/asf/poi.git
commit d7da99d268355e93703cf64d70ac89c84f4ca8aa Author: Dominik Stadler <[email protected]> AuthorDate: Thu Oct 22 09:18:44 2026 +0200 Add README and dependencies to run fuzzing locally Allow to build a shadowJar Add zstd dependency Also ignore corpus and jazzer-binaries which are produced during fuzzing runs --- .gitignore | 4 ++ poi-fuzz/README.md | 175 ++++++++++++++++++++++++++++++++++++++++++++++++++ poi-fuzz/build.gradle | 17 +++++ 3 files changed, 196 insertions(+) diff --git a/.gitignore b/.gitignore index ed8a7870af..6fb7c81cb0 100644 --- a/.gitignore +++ b/.gitignore @@ -37,3 +37,7 @@ TEST-org.apache.poi*.xml /*/build/ dist lib/ +/poi-fuzz/jazzer +/poi-fuzz/jazzer-linux-x86-64-0.30.0.tar.gz +/poi-fuzz/jazzer_standalone.jar +/poi-fuzz/corpus*/ diff --git a/poi-fuzz/README.md b/poi-fuzz/README.md new file mode 100644 index 0000000000..9de802fcf7 --- /dev/null +++ b/poi-fuzz/README.md @@ -0,0 +1,175 @@ +This is a small sub-project for fuzzing [Apache POI](https://poi.apache.org/) +with the [jazzer](https://github.com/CodeIntelligenceTesting/jazzer/) fuzzing tool. + +See [Fuzzing](https://en.wikipedia.org/wiki/Fuzzing) for a general description of the theory behind fuzzy testing. + +Because Java uses a runtime environment which does not crash on invalid actions of an +application (unless native code is invoked), Fuzzing of Java-based applications +focuses on the following: + +* verify if only expected exceptions are thrown +* verify any JNI or native code calls +* find cases of unbounded memory allocations + +Apache POI does not use JNI or native code, therefore the fuzzing target mainly +tries to trigger unexpected exceptions and unbounded memory allocations. + +# oss-fuzz + +These sources are also used to run large-scale fuzzing via [oss-fuzz](https://google.github.io/oss-fuzz/). + +# How to fuzz + +Build the fuzzing target: + + ../gradlew shadowJar + +Copy the corpus of test-files from the sources + + cp -a ../test-data corpus + +You can add more documents to the corpus to help Jazzer in producing "nearly" +proper documents which will improve fuzzing a lot. Slightly broken documents +seem to be a good seed for fuzzing as well. + +Download Jazzer from the [releases page](https://github.com/CodeIntelligenceTesting/jazzer/releases), +choose the latest version and select the file `jazzer-<os>-<version>.tar.gz` + +Unpack the archive: + + tar xzf jazzer-*.tar.gz + +Invoke the fuzzing: + + ./jazzer --cp=build/libs/poi-fuzz-6.0.0-all.jar "--instrumentation_includes=org.apache.poi.**:org.apache.xmlbeans.**" --target_class=org.apache.poi.fuzz.POIFuzzer -rss_limit_mb=2560 corpus + +On Windows/Cygwin use the following: + + ./jazzer --cp=build/libs/poi-fuzz-6.0.0-all.jar "--instrumentation_includes=org.apache.poi.**;org.apache.xmlbeans.**" --target_class=org.apache.poi.fuzz.POIFuzzer -rss_limit_mb=2560 corpus + +In this mode Jazzer will stop whenever it detects an unexpected exception +or crashes. + +You can use `--keep_going=10` to report a given number of exceptions before stopping. + +See `./jazzer` for options which can control details of how Jazzer operates. + +# Fuzzing via Jazzer Docker image + +You can use a ready-made Docker image for running the fuzzing in a container. + +This shields the fuzzing from performing unexpected actions on your local machine +or allows to run it in a container-based infrastructure. + + docker run -v `pwd`:/fuzzing cifuzz/jazzer --cp=build/libs/poi-fuzz-6.0.0-all.jar "--instrumentation_includes=org.apache.poi.**:org.apache.xmlbeans.**" --target_class=org.apache.poi.fuzz.POIFuzzer -rss_limit_mb=2560 corpus + +# Fuzzing single file formats + +## HSLF + + mkdir corpusHSLF + cp corpus/slideshow/*.ppt corpusHSLF/ + ../gradlew shadowJar && ./jazzer --cp=build/libs/poi-fuzz-6.0.0-all.jar "--instrumentation_includes=org.apache.poi.**:org.apache.xmlbeans.**" --target_class=org.apache.poi.fuzz.POIHSLFFuzzer -rss_limit_mb=2560 corpusHSLF + +## HSSF + + mkdir corpusHSSF + cp corpus/spreadsheet/*.xls corpusHSSF/ + ../gradlew shadowJar && ./jazzer --cp=build/libs/poi-fuzz-6.0.0-all.jar "--instrumentation_includes=org.apache.poi.**:org.apache.xmlbeans.**" --target_class=org.apache.poi.fuzz.POIHSSFFuzzer -rss_limit_mb=2560 corpusHSSF + +## HWPF + + mkdir corpusHWPF + cp corpus/document/*.doc corpus/document/*.DOC corpusHWPF/ + ../gradlew shadowJar && ./jazzer --cp=build/libs/poi-fuzz-6.0.0-all.jar "--instrumentation_includes=org.apache.poi.**:org.apache.xmlbeans.**" --target_class=org.apache.poi.fuzz.POIHWPFFuzzer -rss_limit_mb=2560 corpusHWPF + +## OldExcel + + mkdir corpusOldExcel + cp corpus/spreadsheet/*.xls corpus/spreadsheet/*.bin corpusOldExcel/ + ../gradlew shadowJar && ./jazzer --cp=build/libs/poi-fuzz-6.0.0-all.jar "--instrumentation_includes=org.apache.poi.**:org.apache.xmlbeans.**" --target_class=org.apache.poi.fuzz.POIOldExcelFuzzer -rss_limit_mb=2560 corpusOldExcel + +## XSLF + + mkdir corpusXSLF + cp corpus/slideshow/* corpus/integration/*.pptx corpusXSLF/ + ../gradlew shadowJar && ./jazzer --cp=build/libs/poi-fuzz-6.0.0-all.jar "--instrumentation_includes=org.apache.poi.**:org.apache.xmlbeans.**" --target_class=org.apache.poi.fuzz.POIXSLFFuzzer -rss_limit_mb=2560 corpusXSLF + +## XSSF + + mkdir corpusXSSF + cp corpus/spreadsheet/* corpus/integration/*.xlsx corpusXSSF/ + ../gradlew shadowJar && ./jazzer --cp=build/libs/poi-fuzz-6.0.0-all.jar "--instrumentation_includes=org.apache.poi.**:org.apache.xmlbeans.**" --target_class=org.apache.poi.fuzz.POIXSSFFuzzer -rss_limit_mb=2560 corpusXSSF + +## XLSX2CSV + +Can re-use XSSF-corpus as the same files are processed here + + mkdir corpusXSSF + cp corpus/spreadsheet/* corpusXSSF/ + ../gradlew shadowJar && ./jazzer --cp=build/libs/poi-fuzz-6.0.0-all.jar "--instrumentation_includes=org.apache.poi.**:org.apache.xmlbeans.**" --target_class=org.apache.poi.fuzz.XLSX2CSVFuzzer -rss_limit_mb=2560 corpusXSSF + +## XWPF + + mkdir corpusXWPF + cp corpus/document/* corpus/integration/*.docx corpusXWPF/ + ../gradlew shadowJar && ./jazzer --cp=build/libs/poi-fuzz-6.0.0-all.jar "--instrumentation_includes=org.apache.poi.**:org.apache.xmlbeans.**" --target_class=org.apache.poi.fuzz.POIXWPFFuzzer -rss_limit_mb=2560 corpusXWPF + +## Visio + + mkdir corpusVisio + cp corpus/diagram/* corpusVisio/ + ../gradlew shadowJar && ./jazzer --cp=build/libs/poi-fuzz-6.0.0-all.jar "--instrumentation_includes=org.apache.poi.**:org.apache.xmlbeans.**" --target_class=org.apache.poi.fuzz.POIVisioFuzzer -rss_limit_mb=2560 corpusVisio + +## HDGF + + mkdir corpusHDGF + cp corpus/diagram/*.vsd corpusHDGF/ + ../gradlew shadowJar && ./jazzer --cp=build/libs/poi-fuzz-6.0.0-all.jar "--instrumentation_includes=org.apache.poi.**:org.apache.xmlbeans.**" --target_class=org.apache.poi.fuzz.POIHDGFFuzzer -rss_limit_mb=2560 corpusHDGF + +## HPSF + + mkdir corpusHPSF + cp corpus/hpsf/* corpusHPSF/ + ../gradlew shadowJar && ./jazzer --cp=build/libs/poi-fuzz-6.0.0-all.jar "--instrumentation_includes=org.apache.poi.**:org.apache.xmlbeans.**" --target_class=org.apache.poi.fuzz.POIHPSFFuzzer -rss_limit_mb=2560 corpusHPSF + +## HMEF + + mkdir corpusHMEF + cp -a corpus/hmef/* corpusHMEF/ + ../gradlew shadowJar && ./jazzer --cp=build/libs/poi-fuzz-6.0.0-all.jar "--instrumentation_includes=org.apache.poi.**:org.apache.xmlbeans.**" --target_class=org.apache.poi.fuzz.POIHMEFFuzzer -rss_limit_mb=2560 corpusHMEF + +## HPBF + + mkdir corpusHPBF + cp -a corpus/publisher/* corpusHPBF/ + ../gradlew shadowJar && ./jazzer --cp=build/libs/poi-fuzz-6.0.0-all.jar "--instrumentation_includes=org.apache.poi.**:org.apache.xmlbeans.**" --target_class=org.apache.poi.fuzz.POIHPBFFuzzer -rss_limit_mb=2560 corpusHPBF + +## HSMF + + mkdir corpusHSMF + cp -a corpus/hsmf/* corpusHSMF/ + ../gradlew shadowJar && ./jazzer --cp=build/libs/poi-fuzz-6.0.0-all.jar "--instrumentation_includes=org.apache.poi.**:org.apache.xmlbeans.**" --target_class=org.apache.poi.fuzz.POIHSMFFuzzer -rss_limit_mb=2048 corpusHSMF + +## EncryptDecrypt + + mkdir corpusEncryptDecrypt + ../gradlew shadowJar && ./jazzer --cp=build/libs/poi-fuzz-6.0.0-all.jar "--instrumentation_includes=org.apache.poi.**:org.apache.xmlbeans.**" --target_class=org.apache.poi.fuzz.EncryptDecryptFuzzer -rss_limit_mb=2560 corpusEncryptDecrypt + +## FormulaParser + + mkdir corpusFormulaParser + ../gradlew shadowJar && ./jazzer --cp=build/libs/poi-fuzz-6.0.0-all.jar "--instrumentation_includes=org.apache.poi.**:org.apache.xmlbeans.**" --target_class=org.apache.poi.fuzz.FormulaParserFuzzer -rss_limit_mb=2560 corpusFormulaParser + +# Detected issues + +* Many of the exceptions are not declared as being thrown in the JavaDoc of Apache POI, + thus making it hard to write proper defensive try-catches when using Apache POI, for now + you will need to catch `RuntimeException` and any declared ones. +* The RuntimeExceptions do not have a common base class which would allow to + only catch this one type of exception to capture all expected ones +* Some places throw an IllegalArgumentException or IllegalStateException where a dedicated class + deriving from RuntimeException would be preferable. This currently leads to a very + general catching of these exceptions in the fuzz target. +* Some memory allocations are not bounded, i.e. causing out-of-memory on certain + broken documents. Some more memory guards need to be put in place diff --git a/poi-fuzz/build.gradle b/poi-fuzz/build.gradle index ea97d05e32..e7f0a0fb97 100644 --- a/poi-fuzz/build.gradle +++ b/poi-fuzz/build.gradle @@ -19,6 +19,10 @@ // Jazzer is provided at runtime by the OSS-Fuzz build environment; we only // need the API jar at compile time. +plugins { + id 'com.gradleup.shadow' version '9.2.2' +} + dependencies { implementation project(':poi') implementation project(':poi-scratchpad') @@ -26,6 +30,8 @@ dependencies { implementation project(path:':poi-integration', configuration:'tests') implementation "org.apache.logging.log4j:log4j-core:${log4jVersion}" + // fuzzing can trigger zstd-code in commons-compress + implementation 'com.github.luben:zstd-jni:1.5.7-24' implementation 'org.apache.commons:commons-lang3:3.21.0' implementation 'org.opentest4j:opentest4j:1.3.0' implementation 'com.code-intelligence:jazzer-api:0.30.0' @@ -38,6 +44,17 @@ dependencies { javadoc.enabled = false sourcesJar.enabled = false +// Merging all dependency jars inevitably pulls in duplicate META-INF entries +// (LICENSE, NOTICE, ...) from several POI modules. +// The fat jar is not a Maven-published artifact, so keep it out of +// "../build/dist/maven/${archivesName}" - the root build.gradle's doLast +// cleanup for that directory only expects plain "<name>-<version>.jar" style +// artifacts and would delete this "-all.jar" right after it is built. +shadowJar { + duplicatesStrategy = DuplicatesStrategy.EXCLUDE + destinationDirectory = layout.buildDirectory.dir('libs') +} + generateMetadataFileForPOIPublication.enabled = false publishPOIPublicationToMavenLocal.enabled = false --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
