tests/fuzz/README.md

   1 # Fuzzing target for cryptsetup project
   2
   3 This directory contains experimental targets for fuzzing testing.
   4 It can be run in the OSS-Fuzz project but also compiled separately.
   5
   6 # Requirements
   7
   8 Fuzzers use address sanitizer. To properly detect problems, all
   9 important libraries must be compiled statically with sanitizer enabled.
  10
  11 Compilation requires *clang* and *clang++* compilers (gcc is not
  12 supported yet).
  13
  14 # Standalone build
  15
  16 The script `oss-fuzz-build.sh` can be used to prepare the tree
  17 with pre-compiled library dependencies.
  18 We use upstream git for projects, which can clash with locally
  19 installed versions. The best is to use only basic system installation
  20 without development packages (script will use custom include, libs,
  21 and pkg-config paths).
  22
  23 # Build Docker image and fuzzers
  24
  25 You can also run OSS-Fuzz in a Docker image, use these commands
  26 to prepare fuzzers:
  27 ```
  28 sudo python3 infra/helper.py build_image cryptsetup
  29 sudo python3 infra/helper.py build_fuzzers cryptsetup
  30 ```
  31 On SELinux systems also add (https://github.com/google/oss-fuzz/issues/30):
  32 ```
  33 sudo chcon -Rt svirt_sandbox_file_t build/
  34 ```
  35
  36 # Run LUKS2 fuzzer
  37 `FUZZER_NAME` can be one of: `crypt2_load_fuzz`, `crypt2_load_proto_fuzz`, `crypt2_load_proto_plain_json_fuzz`
  38 ```
  39 FUZZER_NAME="crypt2_load_proto_plain_json_fuzz"
  40 sudo mkdir -p build/corpus/cryptsetup/$FUZZER_NAME
  41 sudo python infra/helper.py run_fuzzer --corpus-dir build/corpus/cryptsetup/$FUZZER_NAME/ --sanitizer address cryptsetup $FUZZER_NAME '-jobs=8 -workers=8'
  42 ```
  43
  44 The output of the parallel threads will be written to `fuzz-<N>.log` (where `<N>` is the number of the process).
  45 You can watch it using e.g.:
  46 ```
  47 tail -f build/out/cryptsetup/fuzz-*
  48 ```
  49
  50 Optionally, you can use experimental `fork` mode for parallelization and the output will be displayed directly on the terminal:
  51 ```
  52 sudo python infra/helper.py run_fuzzer --corpus-dir build/corpus/cryptsetup/$FUZZER_NAME/ --sanitizer address cryptsetup $FUZZER_NAME '-fork=8 '
  53 ```
  54
  55 # Rebuild fuzz targets for coverage
  56 ```
  57 sudo python infra/helper.py build_fuzzers --sanitizer coverage cryptsetup
  58 ```
  59
  60 # Generate coverage report
  61 ```
  62 sudo python infra/helper.py coverage cryptsetup --no-corpus-download --fuzz-target $FUZZER_NAME
  63 ```
  64
  65 # Further information
  66 For more details, you can look into the [Using fuzzing for Linux disk encryption tools](https://is.muni.cz/th/bum03/?lang=en) thesis.