diff --git a/docs/fuzz-targets.md b/docs/fuzz-targets.md index fe63fbff..faef3d86 100644 --- a/docs/fuzz-targets.md +++ b/docs/fuzz-targets.md @@ -163,16 +163,16 @@ jazzer [corpus...] [-- ] Detailed documentation and some example calls are available using the `--help` flag, so that only the most important parameters are discussed here. -| Parameter | Description | -| ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `` | Import path to the fuzz target module. | -| `[corpus...]` | Paths to the corpus directories. If not given, no initial seeds are used nor interesting inputs saved. | -| `-f`, `--fuzz_function` | Name of the fuzz test entry point. It must be an exported function with a single [Buffer](https://nodejs.org/api/buffer.html) parameter. Default is `fuzz`. | -| `-i`, `--instrumentation_includes` / `-e`, `--instrumentation_excludes` | Part of filepath names to include/exclude in the instrumentation. A tailing `/` should be used to include directories and prevent confusion with filenames. `*` can be used to include all files. Can be specified multiple times. Default will include everything outside the `node_modules` directory. | -| `--sync` | Enables synchronous fuzzing. **May only be used for entirely synchronous code**. | -| `-h`, `--custom_hooks` | Filenames with custom hooks. Several hooks per file are possible. See further details in [docs/fuzz-settings.md](fuzz-settings.md). | -| `--help` | Detailed help message containing all flags. | -| `-- ` | Parameters after `--` are forwarded to the internal fuzzing engine (`libFuzzer`). Available settings can be found in its [options documentation](https://www.llvm.org/docs/LibFuzzer.html#options). | +| Parameter | Description | +| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `` | Import path to the fuzz target module. | +| `[corpus...]` | Paths to the corpus directories. If not given, no initial seeds are used nor interesting inputs saved. | +| `-f`, `--fuzz_function` | Name of the fuzz test entry point. It must be an exported function with a single [Buffer](https://nodejs.org/api/buffer.html) parameter. Default is `fuzz`. | +| `-i`, `--instrumentation_includes` / `-e`, `--instrumentation_excludes` | Part of filepath names to include/exclude in the instrumentation. A tailing `/` should be used to include directories and prevent confusion with filenames. `*` can be used to include all files. Can be specified multiple times. Default will include everything outside the `node_modules` directory. If either of these flags are set the default value for the other is ignored. | +| `--sync` | Enables synchronous fuzzing. **May only be used for entirely synchronous code**. | +| `-h`, `--custom_hooks` | Filenames with custom hooks. Several hooks per file are possible. See further details in [docs/fuzz-settings.md](fuzz-settings.md). | +| `--help` | Detailed help message containing all flags. | +| `-- ` | Parameters after `--` are forwarded to the internal fuzzing engine (`libFuzzer`). Available settings can be found in its [options documentation](https://www.llvm.org/docs/LibFuzzer.html#options). | ## Coverage report generation @@ -188,14 +188,14 @@ Alternatively, you can add a new script to your package.json: ```json "scripts": { - "coverage": "jazzer -d -i target -i another_target -e nothing --corpus --coverage -- " + "coverage": "jazzer -d -i target -i another_target --corpus --coverage -- " } ``` -Files matched by the flags `--include` or `--custom_hooks`, and not matched by -the flag `--exclude` will be included in the coverage report. It is recommended -to disable coverage report generation during fuzzing, because of the substantial -overhead that it adds. +Files matched by the flags `--instrumentation_includes` or `--custom_hooks`, and +not matched by the flag `--instrumentation_excludes` will be included in the +coverage report. It is recommended to disable coverage report generation during +fuzzing, because of the substantial overhead that it adds. ### Coverage report directory diff --git a/examples/custom-hooks/package.json b/examples/custom-hooks/package.json index ea0af690..1fa6e8dc 100644 --- a/examples/custom-hooks/package.json +++ b/examples/custom-hooks/package.json @@ -7,9 +7,9 @@ "jpeg-js": "^0.4.4" }, "scripts": { - "fuzz": "jazzer fuzz -i jpeg-js -e nothing -h custom-hooks --sync", - "dryRun": "jazzer fuzz -i jpeg-js -e nothing --sync -h custom-hooks -- -runs=100 -seed=123456789", - "coverage": "jazzer fuzz -i jpeg-js -i fuzz.js -i custom-hooks.js -e nothing -h custom-hooks --sync --coverage -- -max_total_time=10" + "fuzz": "jazzer fuzz -i jpeg-js -h custom-hooks --sync", + "dryRun": "jazzer fuzz -i jpeg-js --sync -h custom-hooks -- -runs=100 -seed=123456789", + "coverage": "jazzer fuzz -i jpeg-js -i fuzz.js -i custom-hooks.js -h custom-hooks --sync --coverage -- -max_total_time=10" }, "devDependencies": { "@jazzer.js/core": "file:../../packages/core" diff --git a/examples/jpeg/package.json b/examples/jpeg/package.json index 7dd23fc5..58c9293a 100644 --- a/examples/jpeg/package.json +++ b/examples/jpeg/package.json @@ -9,9 +9,9 @@ "jpeg-js": "^0.4.4" }, "scripts": { - "fuzz": "jazzer fuzz -i jpeg-js -e nothing --sync", - "dryRun": "jazzer fuzz -i jpeg-js -e nothing --sync -- -runs=100 -seed=123456789", - "coverage": "jazzer fuzz -i jpeg-js/lib -i fuzz.js -e nothing --sync --coverage -- -max_total_time=1 -seed=123456789" + "fuzz": "jazzer fuzz -i jpeg-js --sync", + "dryRun": "jazzer fuzz -i jpeg-js --sync -- -runs=100 -seed=123456789", + "coverage": "jazzer fuzz -i jpeg-js/lib -i fuzz.js --sync --coverage -- -max_total_time=1 -seed=123456789" }, "devDependencies": { "@jazzer.js/core": "file:../../packages/core" diff --git a/examples/jpeg_es6/package.json b/examples/jpeg_es6/package.json index 199e5814..a43b1530 100644 --- a/examples/jpeg_es6/package.json +++ b/examples/jpeg_es6/package.json @@ -10,8 +10,8 @@ "jpeg-js": "^0.4.4" }, "scripts": { - "fuzz": "jazzer fuzz -i jpeg-js -e nothing --sync", - "dryRun": "jazzer fuzz -i jpeg-js -e nothing --sync -- -runs=100 -seed=123456789" + "fuzz": "jazzer fuzz -i jpeg-js --sync", + "dryRun": "jazzer fuzz -i jpeg-js --sync -- -runs=100 -seed=123456789" }, "devDependencies": { "@jazzer.js/core": "file:../../packages/core" diff --git a/examples/js-yaml/package.json b/examples/js-yaml/package.json index b51dca7e..93a0a4e6 100644 --- a/examples/js-yaml/package.json +++ b/examples/js-yaml/package.json @@ -4,8 +4,8 @@ "description": "An example showing how Jazzer.js integrates with TypeScript to fuzz js-yaml", "scripts": { "build": "tsc", - "fuzz": "npm run build && jazzer dist/fuzz -i js-yaml -e nothing -- -use_value_profile=1", - "dryRun": "npm run build && jazzer dist/fuzz -i js-yaml -e nothing -- -use_value_profile=1 -runs=100 -seed=123456789" + "fuzz": "npm run build && jazzer dist/fuzz -i js-yaml -- -use_value_profile=1", + "dryRun": "npm run build && jazzer dist/fuzz -i js-yaml -- -use_value_profile=1 -runs=100 -seed=123456789" }, "devDependencies": { "@jazzer.js/core": "file:../../packages/core", diff --git a/examples/protobufjs/package.json b/examples/protobufjs/package.json index 239f4811..26859ac1 100644 --- a/examples/protobufjs/package.json +++ b/examples/protobufjs/package.json @@ -3,8 +3,8 @@ "version": "0.0.0", "type": "module", "scripts": { - "fuzz": "npx jazzer fuzz --sync -i protobuf -e nothing", - "dryRun": "npx jazzer fuzz -d --sync -i protobuf -e nothing -- -runs=100 -seed=123456789" + "fuzz": "npx jazzer fuzz --sync -i protobuf", + "dryRun": "npx jazzer fuzz -d --sync -i protobuf -- -runs=100 -seed=123456789" }, "dependencies": { "protobufjs": "^7.0.0", diff --git a/examples/spectral/package.json b/examples/spectral/package.json index 1cd2e05a..d2480226 100644 --- a/examples/spectral/package.json +++ b/examples/spectral/package.json @@ -2,8 +2,8 @@ "name": "jazzerjs-spectral-example", "version": "1.0.0", "scripts": { - "fuzz": "jazzer spectral-example -i spectral -e nothing --sync", - "dryRun": "jazzer spectral-example -i spectral -e nothing --sync -- -runs=100 -seed=123456789" + "fuzz": "jazzer spectral-example -i spectral --sync", + "dryRun": "jazzer spectral-example -i spectral --sync -- -runs=100 -seed=123456789" }, "dependencies": { "@stoplight/spectral-parsers": "^1.0.1" diff --git a/examples/xml/package.json b/examples/xml/package.json index b3aba572..513becc2 100644 --- a/examples/xml/package.json +++ b/examples/xml/package.json @@ -7,8 +7,8 @@ "xml2js": "^0.4.23" }, "scripts": { - "fuzz": "jazzer fuzz -i xml -e nothing", - "dryRun": "jazzer fuzz -i xml -e nothing -- -runs=100 -seed=123456789" + "fuzz": "jazzer fuzz -i xml", + "dryRun": "jazzer fuzz -i xml -- -runs=100 -seed=123456789" }, "devDependencies": { "@jazzer.js/core": "file:../../packages/core" diff --git a/packages/core/cli.ts b/packages/core/cli.ts index 35aa872d..b89d2edf 100644 --- a/packages/core/cli.ts +++ b/packages/core/cli.ts @@ -98,11 +98,11 @@ yargs(process.argv.slice(2)) "Part of filepath names to include in the instrumentation. " + 'A tailing "/" should be used to include directories and prevent ' + 'confusion with filenames. "*" can be used to include all files.\n' + - "Can be specified multiple times.", + "Can be specified multiple times. By default all files will be" + + "included.", type: "string", alias: "i", group: "Fuzzer:", - default: ["*"], }) .array("instrumentation_excludes") @@ -111,11 +111,11 @@ yargs(process.argv.slice(2)) "Part of filepath names to exclude in the instrumentation. " + 'A tailing "/" should be used to exclude directories and prevent ' + 'confusion with filenames. "*" can be used to exclude all files.\n' + - "Can be specified multiple times.", + 'Can be specified multiple times. By default, "node_modules/" will' + + "be excluded.", type: "string", alias: "e", group: "Fuzzer:", - default: ["node_modules"], }) .option("dry_run", { describe: diff --git a/packages/instrumentor/instrument.test.ts b/packages/instrumentor/instrument.test.ts index 66fc131a..afb692bf 100644 --- a/packages/instrumentor/instrument.test.ts +++ b/packages/instrumentor/instrument.test.ts @@ -37,8 +37,8 @@ describe("shouldInstrument check", () => { ).toBeFalsy(); }); - it("should include everything with *", () => { - const instrumentor = new Instrumentor(["*"], []); + it("should include everything by default", () => { + const instrumentor = new Instrumentor(); expect(instrumentor.shouldInstrumentForFuzzing("include")).toBeTruthy(); expect( instrumentor.shouldInstrumentForFuzzing("/something/else") @@ -46,7 +46,7 @@ describe("shouldInstrument check", () => { }); it("should include nothing with emtpy string", () => { - const instrumentorWithEmptyInclude = new Instrumentor(["include", ""], []); + const instrumentorWithEmptyInclude = new Instrumentor(["include", ""]); expect( instrumentorWithEmptyInclude.shouldInstrumentForFuzzing("include") ).toBeTruthy(); diff --git a/packages/instrumentor/instrument.ts b/packages/instrumentor/instrument.ts index 3fbe6c41..f1c13092 100644 --- a/packages/instrumentor/instrument.ts +++ b/packages/instrumentor/instrument.ts @@ -44,13 +44,21 @@ export { export class Instrumentor { constructor( - private readonly includes: string[] = ["*"], - private readonly excludes: string[] = ["node_modules"], + private readonly includes: string[] = [], + private readonly excludes: string[] = [], private readonly customHooks: string[] = [], private readonly shouldCollectSourceCodeCoverage = false, private readonly isDryRun = false, private readonly idStrategy: EdgeIdStrategy = new MemorySyncIdStrategy() - ) {} + ) { + // This is our default case where we want to include everthing and exclude the "node_modules" folder. + if (includes.length === 0 && excludes.length === 0) { + includes.push("*"); + excludes.push("node_modules"); + } + this.includes = Instrumentor.cleanup(includes); + this.excludes = Instrumentor.cleanup(excludes); + } init(): () => void { if (this.includes.includes("jazzer.js")) { @@ -156,6 +164,7 @@ export class Instrumentor { delete require.cache[require.resolve(module)]; }); } + shouldInstrumentForFuzzing(filepath: string): boolean { return ( !this.isDryRun && @@ -176,14 +185,10 @@ export class Instrumentor { includes: string[], excludes: string[] ): boolean { - const cleanedIncludes = Instrumentor.cleanup(includes); - const cleanedExcludes = Instrumentor.cleanup(excludes); const included = - cleanedIncludes.find((include) => filepath.includes(include)) !== - undefined; + includes.find((include) => filepath.includes(include)) !== undefined; const excluded = - cleanedExcludes.find((exclude) => filepath.includes(exclude)) !== - undefined; + excludes.find((exclude) => filepath.includes(exclude)) !== undefined; return included && !excluded; }