feat(path-traversal): add stack suppressions

Let users silence expected traversal callsites with the same
shown-stack rules used by code-injection findings.

Author: oetr

docs/bug-detectors.md

@@ -25,6 +25,30 @@ using Jest in `.jazzerjsrc.json`:
 Hooks all relevant functions of the built-in modules `fs` and `path` and reports
 a finding if the fuzzer could pass a special path to any of the functions.
 
+The Path Traversal bug detector can be configured in the
+[custom hooks](./fuzz-settings.md#customhooks--arraystring) file.
+
+- `ignore(rule)` - suppresses findings from callsites matching the shown stack
+  excerpt.
+- `stackPattern` accepts either a string or a `RegExp` and is matched against
+  the shown stack excerpt after removing the leading `Error` line and Jazzer.js
+  frames. The remaining stack text is matched as shown, including path
+  separators and column numbers.
+
+Here is an example configuration in the
+[custom hooks](./fuzz-settings.md#customhooks--arraystring) file:
+
+```javascript
+const { getBugDetectorConfiguration } = require("@jazzer.js/bug-detectors");
+
+getBugDetectorConfiguration("path-traversal")?.ignore({
+	stackPattern: "safe-path-wrapper.js:41",
+});
+```
+
+Findings also print a generic example suppression snippet. Copy/paste it and
+adapt `stackPattern` to the shown stack excerpt.
+
 _Disable with:_ `--disableBugDetectors=path-traversal` in CLI mode; or when
 using Jest in `.jazzerjsrc.json`:
 

packages/bug-detectors/internal/path-traversal.ts

@@ -20,12 +20,53 @@ import {
 } from "@jazzer.js/core";
 import { callSiteId, registerBeforeHook } from "@jazzer.js/hooking";
 
+import { bugDetectorConfigurations } from "../configuration";
+
+import {
+	buildGenericSuppressionSnippet,
+	captureStack,
+	getUserFacingStackLines,
+	IgnoreList,
+	type IgnoreRule,
+} from "../shared/finding-suppression";
+
 /**
  * Importing this file adds "before-hooks" for all functions in the built-in `fs`, `fs/promises`, and `path` module and guides
  * the fuzzer towards the uniquely chosen `goal` string `"../../jaz_zer"`. If the goal is found in the first argument
  * of any hooked function, a `Finding` is reported.
  */
 const goal = "../../jaz_zer";
+
+export type { IgnoreRule } from "../shared/finding-suppression";
+
+/**
+ * Configuration for the Path Traversal bug detector.
+ * Controls suppression of matched path traversal findings.
+ */
+export interface PathTraversalConfig {
+	/**
+	 * Suppresses findings that match the provided rule.
+	 * Use this to silence known-safe callsites in your test environment.
+	 */
+	ignore(rule: IgnoreRule): this;
+}
+
+class PathTraversalConfigImpl implements PathTraversalConfig {
+	private readonly _ignoredRules = new IgnoreList();
+
+	ignore(rule: IgnoreRule): this {
+		this._ignoredRules.add(rule);
+		return this;
+	}
+
+	shouldReport(stack: string): boolean {
+		return !this._ignoredRules.matches(stack);
+	}
+}
+
+const config = new PathTraversalConfigImpl();
+bugDetectorConfigurations.set("path-traversal", config);
+
 const modulesToHook = [
 	{
 		moduleName: "fs",
@@ -208,11 +249,38 @@ function detectFindingAndGuideFuzzing(
 	) {
 		const argument = input.toString();
 		if (argument.includes(goal)) {
+			const stack = captureStack();
+			if (!config.shouldReport(stack)) {
+				return;
+			}
 			reportAndThrowFinding(
-				"Path Traversal\n" +
-					`    in ${functionName}(): called with '${argument}'`,
+				buildFindingMessage(functionName, argument, stack),
+				false,
 			);
 		}
 		guideTowardsContainment(argument, goal, hookId);
 	}
 }
+
+function buildFindingMessage(
+	functionName: string,
+	argument: string,
+	stack: string,
+): string {
+	const relevantStackLines = getUserFacingStackLines(stack);
+	const message = [
+		"Path Traversal",
+		`    in ${functionName}(): called with '${argument}'`,
+	];
+	if (relevantStackLines.length > 0) {
+		message.push(...relevantStackLines);
+	}
+	message.push(
+		"",
+		"[!] If this callsite is expected in your test environment, suppress it:",
+		"    Example only: copy/paste it and adapt `stackPattern` to your needs.",
+		"",
+		buildGenericSuppressionSnippet("path-traversal", "ignore"),
+	);
+	return message.join("\n");
+}

tests/bug-detectors/path-traversal.test.js

@@ -27,9 +27,11 @@ describe("Path Traversal", () => {
 	const SAFE = "../safe_path/";
 	const EVIL = "../evil_path/";
 	const bugDetectorDirectory = path.join(__dirname, "path-traversal");
+	const goalPath = path.join(bugDetectorDirectory, "../../jaz_zer");
 
 	beforeEach(async () => {
 		fs.rmSync(SAFE, { recursive: true, force: true });
+		fs.rmSync(goalPath, { recursive: true, force: true });
 		await cleanCrashFilesIn(bugDetectorDirectory);
 	});
 
@@ -190,6 +192,66 @@ describe("Path Traversal", () => {
 			.build();
 		fuzzTest.execute();
 	});
+
+	it("prints a generic suppression example", () => {
+		const fuzzTest = new FuzzTestBuilder()
+			.runs(0)
+			.sync(true)
+			.fuzzEntryPoint("PathTraversalFsMkdirEvilSync")
+			.dir(bugDetectorDirectory)
+			.build();
+		expect(() => {
+			fuzzTest.execute();
+		}).toThrow(FuzzingExitCode);
+		expect(fuzzTest.stderr).toContain(
+			'getBugDetectorConfiguration("path-traversal")',
+		);
+		expect(fuzzTest.stderr).toContain(
+			"Example only: copy/paste it and adapt `stackPattern` to your needs.",
+		);
+		expect(fuzzTest.stderr).toContain(
+			"// Example only: adapt `stackPattern` to the shown stack above.",
+		);
+		expect(fuzzTest.stderr).toContain("?.ignore({");
+		expect(fuzzTest.stderr).toContain('stackPattern: "test.js:10"');
+	});
+
+	it("suppresses findings when a stack pattern matches the fs callsite", () => {
+		const fuzzTest = new FuzzTestBuilder()
+			.runs(0)
+			.sync(true)
+			.fuzzEntryPoint("PathTraversalFsMkdirEvilSync")
+			.customHooks(["ignore-fs-stack.config.js"])
+			.dir(bugDetectorDirectory)
+			.build();
+		fuzzTest.execute();
+		expect(fs.existsSync(goalPath)).toBeTruthy();
+	});
+
+	it("suppresses findings when stack pattern matches", () => {
+		const fuzzTest = new FuzzTestBuilder()
+			.runs(0)
+			.sync(true)
+			.fuzzEntryPoint("PathTraversalJoinEvilSync")
+			.customHooks(["ignore-by-stack.config.js"])
+			.dir(bugDetectorDirectory)
+			.build();
+		fuzzTest.execute();
+	});
+
+	it("still reports when ignore rule does not match", () => {
+		const fuzzTest = new FuzzTestBuilder()
+			.runs(0)
+			.sync(true)
+			.fuzzEntryPoint("PathTraversalJoinEvilSync")
+			.customHooks(["ignore-no-match.config.js"])
+			.dir(bugDetectorDirectory)
+			.build();
+		expect(() => {
+			fuzzTest.execute();
+		}).toThrow(FuzzingExitCode);
+		expect(fuzzTest.stderr).toContain("Path Traversal");
+	});
 });
 
 describe("Path Traversal invalid input", () => {

tests/bug-detectors/path-traversal/ignore-by-stack.config.js

@@ -0,0 +1,23 @@
+/*
+ * Copyright 2026 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.
+ */
+
+const {
+	getBugDetectorConfiguration,
+} = require("../../../packages/bug-detectors");
+
+getBugDetectorConfiguration("path-traversal")?.ignore({
+	stackPattern: "Object.join",
+});

tests/bug-detectors/path-traversal/ignore-fs-stack.config.js

@@ -0,0 +1,23 @@
+/*
+ * Copyright 2026 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.
+ */
+
+const {
+	getBugDetectorConfiguration,
+} = require("../../../packages/bug-detectors");
+
+getBugDetectorConfiguration("path-traversal")?.ignore({
+	stackPattern: "at fn (",
+});

tests/bug-detectors/path-traversal/ignore-no-match.config.js

@@ -0,0 +1,23 @@
+/*
+ * Copyright 2026 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.
+ */
+
+const {
+	getBugDetectorConfiguration,
+} = require("../../../packages/bug-detectors");
+
+getBugDetectorConfiguration("path-traversal")?.ignore({
+	stackPattern: "never-match",
+});