1# JS-Fuzzer 2 3Javascript fuzzer for stand-alone shells like D8, Chakra, JSC or Spidermonkey. 4 5Original author: Oliver Chang 6 7# Building 8 9This fuzzer may require versions of node that are newer than available on 10ClusterFuzz, so we use [pkg](https://github.com/zeit/pkg) to create a self 11contained binary) out of this. 12 13## Prereqs 14You need to intall nodejs and npm. Run `npm install` in this directory. 15 16## Fuzzing DB 17This fuzzer requires a fuzzing DB. To build one, get the latest `web_tests.zip` 18from [gs://clusterfuzz-data/web_tests.zip]( 19https://storage.cloud.google.com/clusterfuzz-data/web_tests.zip) and unzip it 20(note https://crbug.com/v8/10891 for making this data publicly available). 21Then run: 22 23```bash 24$ mkdir db 25$ node build_db.js -i /path/to/web_tests -o db chakra v8 spidermonkey WebKit/JSTests 26``` 27 28This may take a while. Optionally test the fuzzing DB with: 29 30```bash 31$ node test_db.js -i db 32``` 33 34## Building fuzzer 35Then, to build the fuzzer, 36```bash 37$ ./node_modules/.bin/pkg -t node10-linux-x64 . 38``` 39 40Replace "linux" with either "win" or "macos" for those platforms. 41 42This builds a binary named `ochang_js_fuzzer` for Linux / macOS OR 43`ochang_js_fuzzer.exe` for Windows. 44 45## Packaging 46Use `./package.sh`, `./package.sh win` or `./package.sh macos` to build and 47create the `output.zip` archive or use these raw commands: 48```bash 49$ mkdir output 50$ cd output 51$ ln -s ../db db 52$ ln -s ../ochang_js_fuzzer run 53$ zip -r /path/output.zip * 54``` 55 56**NOTE**: Add `.exe` to `ochang_js_fuzzer` and `run` filename above if archiving 57for Windows platform. 58 59# Development 60 61Run the tests with: 62 63```bash 64$ npm test 65``` 66 67When test expectations change, generate them with: 68 69```bash 70$ GENERATE=1 npm test 71``` 72 73# Generating exceptional configurations 74 75Tests that fail to parse or show very bad performance can be automatically 76skipped or soft-skipped with the following script (takes >1h): 77 78```bash 79$ WEB_TESTS=/path/to/web_tests OUTPUT=/path/to/output/folder ./gen_exceptions.sh 80``` 81 82# Experimenting (limited to differential fuzzing) 83 84To locally evaluate the fuzzer, setup a work directory as follows: 85 86```bash 87$ workdir/ 88$ workdir/app_dir 89$ workdir/fuzzer 90$ workdir/input 91$ workdir/output 92``` 93 94The `app_dir` folder can be a symlink or should contain the bundled 95version of `d8` with all files required for execution. 96Copy the packaged `ochang_js_fuzzer` executable and the `db` folder 97to the `fuzzer` directory or use a symlink. 98The `input` directory is the root folder of the corpus, i.e. pointing 99to the unzipped data of `gs://clusterfuzz-data/web_tests.zip`. 100The `output` directory is expected to be empty. It'll contain all 101output of the fuzzing session. Start the experiments with: 102 103```bash 104$ # Around ~40000 corresponds to 24h of fuzzing on a workstation. 105$ NUM_RUNS = 40000 106$ python tools/workbench.py $NUM_RUNS 107``` 108 109You can check current stats with: 110 111```bash 112$ cat workdir/output/stats.json | python -m json.tool 113``` 114 115When failures are found, you can forge minimization command lines with: 116 117```bash 118$ MINIMIZER_PATH = path/to/minimizer 119$ python tools/minimize.py $MINIMIZER_PATH 120``` 121 122The path should point to a local checkout of the [minimizer](https://chrome-internal.googlesource.com/chrome/tools/clusterfuzz/+/refs/heads/master/src/python/bot/minimizer/). 123