Add SIGINT handlers for sync and async modes

In async mode, we can register a callback directly in Node.  In sync
mode, the event loop is blocked until the fuzzing process has
finished. Hence, we register the callback for SIGINT directly in our
native addon.

Author: oetr

packages/core/core.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright 2022 Code Intelligence GmbH
+ * Copyright 2023 Code Intelligence GmbH
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -14,7 +14,6 @@
  * limitations under the License.
  */
 import path from "path";
-import * as process from "process";
 import * as tmp from "tmp";
 import * as fs from "fs";
 
@@ -169,14 +168,40 @@ export async function startFuzzingNoInit(
 	fuzzFn: fuzzer.FuzzTarget,
 	options: Options,
 ) {
+	// Signal handler that stops fuzzing when the process receives a SIGINT,
+	// necessary to generate coverage reports and print debug information.
+	// The handler stops the process via `stopFuzzing`, as resolving the "fuzzing
+	// promise" does not work in sync mode due to the blocked event loop.
+	const signalHandler = () => {
+		stopFuzzing(
+			undefined,
+			options.expectedErrors,
+			options.coverageDirectory,
+			options.coverageReporters,
+			options.sync,
+			0,
+		);
+	};
+
 	const fuzzerOptions = buildFuzzerOptions(options);
 	logInfoAboutFuzzerOptions(fuzzerOptions);
-	const fuzzerFn = options.sync
-		? Fuzzer.startFuzzing
-		: Fuzzer.startFuzzingAsync;
-	// Wrap the potentially sync fuzzer call, so that resolve and exception
-	// handlers are always executed.
-	return Promise.resolve().then(() => fuzzerFn(fuzzFn, fuzzerOptions));
+
+	if (options.sync) {
+		return Promise.resolve().then(() =>
+			Fuzzer.startFuzzing(
+				fuzzFn,
+				fuzzerOptions,
+				// In synchronous mode, we cannot use the SIGINT handler in Node,
+				// because it won't be called until the fuzzing process is finished.
+				// Hence, we pass a callback function to the native fuzzer.
+				signalHandler,
+			),
+		);
+	} else {
+		// Add a Node SIGINT handler to stop fuzzing gracefully.
+		process.on("SIGINT", signalHandler);
+		return Fuzzer.startFuzzingAsync(fuzzFn, fuzzerOptions);
+	}
 }
 
 function prepareLibFuzzerArg0(fuzzerOptions: string[]): string {
@@ -238,6 +263,7 @@ function stopFuzzing(
 	coverageDirectory: string,
 	coverageReporters: reports.ReportType[],
 	sync: boolean,
+	forceShutdownWithCode?: number,
 ) {
 	const stopFuzzing = sync ? Fuzzer.stopFuzzing : Fuzzer.stopFuzzingAsync;
 	if (process.env.JAZZER_DEBUG) {
@@ -257,13 +283,15 @@ function stopFuzzing(
 		);
 	}
 
-	// No error found, check if one is expected.
+	// No error found, check if one is expected or an exit code should be enforced.
 	if (!err) {
 		if (expectedErrors.length) {
 			console.error(
 				`ERROR: Received no error, but expected one of [${expectedErrors}].`,
 			);
 			stopFuzzing(ERROR_UNEXPECTED_CODE);
+		} else if (forceShutdownWithCode !== undefined) {
+			stopFuzzing(forceShutdownWithCode);
 		}
 		return;
 	}

packages/fuzzer/addon.ts

@@ -27,6 +27,7 @@ export type FuzzOpts = string[];
 export type StartFuzzingSyncFn = (
 	fuzzFn: FuzzTarget,
 	fuzzOpts: FuzzOpts,
+	sigintCallback: () => void,
 ) => void;
 export type StartFuzzingAsyncFn = (
 	fuzzFn: FuzzTarget,

packages/fuzzer/fuzzing_sync.cpp

@@ -1,4 +1,4 @@
-// Copyright 2022 Code Intelligence GmbH
+// Copyright 2023 Code Intelligence GmbH
 //
 //  Licensed under the Apache License, Version 2.0 (the "License");
 //  you may not use this file except in compliance with the License.
@@ -15,6 +15,7 @@
 #include "fuzzing_sync.h"
 #include "shared/libfuzzer.h"
 #include "utils.h"
+#include <csignal>
 #include <cstdlib>
 #include <optional>
 
@@ -23,14 +24,22 @@ namespace {
 struct FuzzTargetInfo {
   Napi::Env env;
   Napi::Function target;
+  Napi::Function stopFunction;
 };
 
 // The JS fuzz target. We need to store the function pointer in a global
 // variable because libfuzzer doesn't give us a way to feed user-provided data
 // to its target function.
 std::optional<FuzzTargetInfo> gFuzzTarget;
+
+// Track if SIGINT signal handler was called.
+// This is only necessary in the sync fuzzing case, as async can be handled
+// much nicer directly in JavaScript.
+volatile std::sig_atomic_t gSignalStatus;
 } // namespace
 
+void sigintHandler(int signum) { gSignalStatus = signum; }
+
 // The libFuzzer callback when fuzzing synchronously
 int FuzzCallbackSync(const uint8_t *Data, size_t Size) {
   // Create a new active scope so that handles for the buffer objects created in
@@ -60,6 +69,12 @@ int FuzzCallbackSync(const uint8_t *Data, size_t Size) {
   } else {
     SyncReturnsHandler();
   }
+
+  // Execute the signal handler in context of the node application.
+  if (gSignalStatus != 0) {
+    gFuzzTarget->stopFunction.Call({});
+  }
+
   return EXIT_SUCCESS;
 }
 
@@ -71,17 +86,24 @@ int FuzzCallbackSync(const uint8_t *Data, size_t Size) {
 // parameter; the fuzz target's return value is ignored. The second argument
 // is an array of (command-line) arguments to pass to libfuzzer.
 void StartFuzzing(const Napi::CallbackInfo &info) {
-  if (info.Length() != 2 || !info[0].IsFunction() || !info[1].IsArray()) {
-    throw Napi::Error::New(info.Env(),
-                           "Need two arguments, which must be the fuzz target "
-                           "function and an array of libfuzzer arguments");
+  if (info.Length() != 3 || !info[0].IsFunction() || !info[1].IsArray() ||
+      !info[2].IsFunction()) {
+    throw Napi::Error::New(
+        info.Env(),
+        "Need three arguments, which must be the fuzz target "
+        "function, an array of libfuzzer arguments, and a callback function "
+        "that the fuzzer will call in case of SIGINT or a segmentation fault");
   }
 
   auto fuzzer_args = LibFuzzerArgs(info.Env(), info[1].As<Napi::Array>());
 
   // Store the JS fuzz target and corresponding environment globally, so that
-  // our C++ fuzz target can use them to call back into JS.
-  gFuzzTarget = {info.Env(), info[0].As<Napi::Function>()};
+  // our C++ fuzz target can use them to call back into JS. Also store the stop
+  // function that will be called in case of a SIGINT.
+  gFuzzTarget = {info.Env(), info[0].As<Napi::Function>(),
+                 info[2].As<Napi::Function>()};
+
+  signal(SIGINT, sigintHandler);
 
   StartLibFuzzer(fuzzer_args, FuzzCallbackSync);
   // Explicitly reset the global function pointer because the JS
@@ -93,9 +115,9 @@ void StartFuzzing(const Napi::CallbackInfo &info) {
 void StopFuzzing(const Napi::CallbackInfo &info) {
   int exitCode = StopFuzzingHandleExit(info);
 
-  // If we ran in async mode and we only ever encountered synchronous results
+  // If we ran in async mode, and we only ever encountered synchronous results
   // we'll give an indicator that running in synchronous mode is likely
-  // benefical
+  // beneficial.
   ReturnValueInfo(true);
 
   // We call _Exit to immediately terminate the process without performing any

packages/fuzzer/utils.cpp

@@ -1,4 +1,4 @@
-// Copyright 2022 Code Intelligence GmbH
+// Copyright 2023 Code Intelligence GmbH
 //
 //  Licensed under the Apache License, Version 2.0 (the "License");
 //  you may not use this file except in compliance with the License.
@@ -17,8 +17,6 @@
 #include "shared/libfuzzer.h"
 #include <iostream>
 
-#define btoa(x) ((x) ? "true" : "false")
-
 void StartLibFuzzer(const std::vector<std::string> &args,
                     fuzzer::UserCallback fuzzCallback) {
   std::vector<char *> fuzzer_arg_pointers;

tests/helpers.js

@@ -27,6 +27,7 @@ const assert = require("assert");
 // `fuzzEntryPoint` (which would return a "1")
 const FuzzingExitCode = "77";
 const JestRegressionExitCode = "1";
+const WindowsExitCode = "1";
 
 class FuzzTest {
 	sync;
@@ -323,5 +324,6 @@ function callWithTimeout(fn, timeout) {
 module.exports.FuzzTestBuilder = FuzzTestBuilder;
 module.exports.FuzzingExitCode = FuzzingExitCode;
 module.exports.JestRegressionExitCode = JestRegressionExitCode;
+module.exports.WindowsExitCode = WindowsExitCode;
 module.exports.makeFnCalledOnce = makeFnCalledOnce;
 module.exports.callWithTimeout = callWithTimeout;

tests/signal_handlers/SIGINT/.gitignore

@@ -0,0 +1,2 @@
+tests.fuzz
+.jazzerjsrc.json

tests/signal_handlers/SIGINT/fuzz.js

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2023 Code Intelligence GmbH
+ *
+ * Licensed 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.
+ */
+
+let i = 0;
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+module.exports.SIGINT_SYNC = (data) => {
+	if (i === 1000) {
+		console.log("kill with SIGINT");
+		process.kill(process.pid, "SIGINT");
+	}
+	if (i > 1000) {
+		console.log("SIGINT has not stopped the fuzzing process");
+	}
+	i++;
+};
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+module.exports.SIGINT_ASYNC = (data) => {
+	// Raising SIGINT in async mode does not stop the fuzzer directly,
+	// as the event is handled asynchronously in the event loop.
+	if (i === 1000) {
+		console.log("kill with SIGINT");
+		process.kill(process.pid, "SIGINT");
+	}
+	i++;
+};

tests/signal_handlers/SIGINT/package.json

@@ -0,0 +1,26 @@
+{
+	"name": "jazzerjs-signal-handler-tests",
+	"version": "1.0.0",
+	"description": "Tests for the SIGINT signal handler",
+	"scripts": {
+		"test": "jest",
+		"fuzz": "JAZZER_FUZZ=1 jest"
+	},
+	"devDependencies": {
+		"@jazzer.js/jest-runner": "file:../../packages/jest-runner"
+	},
+	"jest": {
+		"projects": [
+			{
+				"runner": "@jazzer.js/jest-runner",
+				"displayName": {
+					"name": "Jazzer.js",
+					"color": "cyan"
+				},
+				"testMatch": [
+					"<rootDir>/**/*.fuzz.js"
+				]
+			}
+		]
+	}
+}

tests/signal_handlers/SIGINT/tests.fuzz.js

@@ -0,0 +1,25 @@
+/*
+ * Copyright 2023 Code Intelligence GmbH
+ *
+ * Licensed 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.
+ */
+
+/* eslint no-undef: 0 */
+/* eslint-disable @typescript-eslint/no-var-requires */
+
+const { SIGINT_SYNC, SIGINT_ASYNC } = require("./fuzz.js");
+
+describe("Jest", () => {
+	it.fuzz("Sync", SIGINT_SYNC);
+	it.fuzz("Async", SIGINT_ASYNC);
+});

tests/signal_handlers/package.json

@@ -0,0 +1,12 @@
+{
+	"name": "jazzer-js-tests-for-signal-handlers",
+	"version": "1.0.0",
+	"description": "Tests for Jazzer.js' signal handlers",
+	"scripts": {
+		"fuzz": "jest --verbose",
+		"test": "jest --verbose"
+	},
+	"devDependencies": {
+		"@jazzer.js/core": "file:../../packages/core"
+	}
+}