feat(path-traversal): add finding suppression rules

Expose path-traversal.ignore(rule) with the same file, function, and
stack matching semantics as code injection.

Emit copy-paste suppression snippets in findings, and cover the new
rules in the integration tests and detector docs.

Author: oetr

docs/bug-detectors.md

@@ -25,6 +25,24 @@ 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 matching a file, function, or stack
+  pattern. Multiple properties in one rule are matched as a logical AND.
+
+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({
+	filePattern: /src[\\/]safe-path-wrapper\.js$/,
+	functionPattern: /^sanitizePath$/,
+});
+```
+
 _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,55 @@ import {
 } from "@jazzer.js/core";
 import { callSiteId, registerBeforeHook } from "@jazzer.js/hooking";
 
+import { bugDetectorConfigurations } from "../configuration";
+import {
+	buildSuppressionSnippet,
+	captureStack,
+	getRelevantStackLines,
+	matchesIgnoreRules,
+	parseOriginFrame,
+	type IgnoreRule,
+	type OriginFrame,
+} from "./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";
+const MAX_STACK_LINES = 8;
+
+export type { IgnoreRule } from "./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 paths in your test environment.
+	 */
+	ignore(rule: IgnoreRule): this;
+}
+
+class PathTraversalConfigImpl implements PathTraversalConfig {
+	private readonly _ignoredRules: IgnoreRule[] = [];
+
+	ignore(rule: IgnoreRule): this {
+		this._ignoredRules.push(rule);
+		return this;
+	}
+
+	shouldReport(originFrame: OriginFrame | undefined, stack: string): boolean {
+		return !matchesIgnoreRules(this._ignoredRules, originFrame, stack);
+	}
+}
+
+const config = new PathTraversalConfigImpl();
+bugDetectorConfigurations.set("path-traversal", config);
+
 const modulesToHook = [
 	{
 		moduleName: "fs",
@@ -208,11 +251,42 @@ function detectFindingAndGuideFuzzing(
 	) {
 		const argument = input.toString();
 		if (argument.includes(goal)) {
+			const stack = captureStack();
+			const originFrame = parseOriginFrame(stack);
+			if (!config.shouldReport(originFrame, stack)) {
+				return;
+			}
 			reportAndThrowFinding(
-				"Path Traversal\n" +
-					`    in ${functionName}(): called with '${argument}'`,
+				buildFindingMessage(functionName, argument, stack, originFrame),
+				false,
 			);
 		}
 		guideTowardsContainment(argument, goal, hookId);
 	}
 }
+
+function buildFindingMessage(
+	functionName: string,
+	argument: string,
+	stack: string,
+	originFrame: OriginFrame | undefined,
+): string {
+	const relevantStackLines = getRelevantStackLines(stack).slice(
+		0,
+		MAX_STACK_LINES,
+	);
+	const message = [
+		"Path Traversal",
+		`    in ${functionName}(): called with '${argument}'`,
+	];
+	if (relevantStackLines.length > 0) {
+		message.push(...relevantStackLines);
+	}
+	message.push(
+		"",
+		"[!] If this path is expected in your test environment, suppress it:",
+		"",
+		buildSuppressionSnippet("path-traversal", "ignore", originFrame, stack),
+	);
+	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,63 @@ describe("Path Traversal", () => {
 			.build();
 		fuzzTest.execute();
 	});
+
+	it("prints a copy-paste suppression snippet", () => {
+		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(".ignore({");
+		expect(fuzzTest.stderr).toContain(
+			"filePattern: /path-traversal[\\\\/]fuzz\\.js$/",
+		);
+		expect(fuzzTest.stderr).toContain("functionPattern: /^fn$/");
+	});
+
+	it("suppresses findings when file and function both match", () => {
+		const fuzzTest = new FuzzTestBuilder()
+			.runs(0)
+			.sync(true)
+			.fuzzEntryPoint("PathTraversalFsMkdirEvilSync")
+			.customHooks(["ignore-by-frame.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-frame.config.js

@@ -0,0 +1,24 @@
+/*
+ * 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({
+	filePattern: /path-traversal[\\/]fuzz\.js$/,
+	functionPattern: /^fn$/,
+});

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-no-match.config.js

@@ -0,0 +1,24 @@
+/*
+ * 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({
+	filePattern: /never-match\.js$/,
+	functionPattern: /^neverMatch$/,
+});