feat(bug-detectors): simplify stack-based suppressions

Match stackPattern against normalized relevant stacks and print generic example snippets so users can adapt suppressions without brittle frame guessing.

Author: oetr

docs/bug-detectors.md

@@ -30,6 +30,9 @@ The Path Traversal bug detector can be configured in the
 
 - `ignore(rule)` - suppresses findings matching a file, function, or stack
   pattern. Multiple properties in one rule are matched as a logical AND.
+- `stackPattern` accepts either a string or a `RegExp` and is matched against
+  the relevant stack trace with Jazzer.js frames removed and column numbers
+  stripped.
 
 Here is an example configuration in the
 [custom hooks](./fuzz-settings.md#customhooks--arraystring) file:
@@ -38,11 +41,13 @@ Here is an example configuration in the
 const { getBugDetectorConfiguration } = require("@jazzer.js/bug-detectors");
 
 getBugDetectorConfiguration("path-traversal")?.ignore({
-	filePattern: /src[\\/]safe-path-wrapper\.js$/,
-	functionPattern: /^sanitizePath$/,
+	stackPattern: "safe-path-wrapper.js:41",
 });
 ```
 
+Findings also print a generic example suppression snippet. Copy/paste it and
+adapt `stackPattern` to your stack trace.
+
 _Disable with:_ `--disableBugDetectors=path-traversal` in CLI mode; or when
 using Jest in `.jazzerjsrc.json`:
 
@@ -138,6 +143,9 @@ The detector can be configured in the
   or stack pattern.
 - `ignoreInvocation(rule)` - suppresses stage-2 findings matching a file,
   function, or stack pattern.
+- `stackPattern` accepts either a string or a `RegExp` and is matched against
+  the relevant stack trace with Jazzer.js frames removed and column numbers
+  stripped.
 
 Here is an example configuration in the
 [custom hooks](./fuzz-settings.md#customhooks--arraystring) file:
@@ -147,12 +155,14 @@ const { getBugDetectorConfiguration } = require("@jazzer.js/bug-detectors");
 
 getBugDetectorConfiguration("code-injection")
 	?.ignoreAccess({
-		filePattern: /handlebars[\\/]dist[\\/]cjs[\\/]runtime\.js$/,
-		functionPattern: /^lookupProperty$/,
+		stackPattern: "handlebars/runtime.js:87",
 	})
 	?.disableInvocationReporting();
 ```
 
+Findings print a generic example suppression snippet. Copy/paste it and adapt
+`stackPattern` to a stable substring or `RegExp` from the stack trace above.
+
 _Disable with:_ `--disableBugDetectors=code-injection` in CLI mode; or when
 using Jest in `.jazzerjsrc.json`:
 

packages/bug-detectors/internal/code-injection.ts

@@ -24,14 +24,15 @@ import {
 import { registerBeforeHook } from "@jazzer.js/hooking";
 
 import { bugDetectorConfigurations } from "../configuration";
+
 import {
-	buildSuppressionSnippet,
+	buildGenericSuppressionSnippet,
 	captureStack,
 	getRelevantStackLines,
-	matchesIgnoreRules,
-	parseOriginFrame,
 	type IgnoreRule,
+	matchesIgnoreRules,
 	type OriginFrame,
+	parseOriginFrame,
 } from "./finding-suppression";
 
 const BASE_CANARY_NAME = "jaz_zer";
@@ -212,7 +213,6 @@ function createCanaryDescriptor(canaryName: string): PropertyDescriptor {
 						"Potential Code Injection (Canary Accessed)",
 						`accessed canary: ${canaryName}`,
 						accessStack,
-						accessOrigin,
 						"ignoreAccess",
 						"If this is a safe heuristic read, suppress it to continue fuzzing for code execution. Add this to your custom hooks:",
 					),
@@ -229,7 +229,6 @@ function createCanaryDescriptor(canaryName: string): PropertyDescriptor {
 							"Confirmed Code Injection (Canary Invoked)",
 							`invoked canary: ${canaryName}`,
 							invocationStack,
-							invocationOrigin,
 							"ignoreInvocation",
 							"If this execution sink is expected in your test environment, suppress it:",
 						),
@@ -247,7 +246,6 @@ function buildFindingMessage(
 	title: string,
 	action: string,
 	stack: string,
-	originFrame: OriginFrame | undefined,
 	suppressionMethod: "ignoreAccess" | "ignoreInvocation",
 	hint: string,
 ): string {
@@ -262,13 +260,9 @@ function buildFindingMessage(
 	message.push(
 		"",
 		`[!] ${hint}`,
+		"    Example only: copy/paste it and adapt `stackPattern` to your needs.",
 		"",
-		buildSuppressionSnippet(
-			"code-injection",
-			suppressionMethod,
-			originFrame,
-			stack,
-		),
+		buildGenericSuppressionSnippet("code-injection", suppressionMethod),
 	);
 	return message.join("\n");
 }

packages/bug-detectors/internal/finding-suppression.test.ts

@@ -0,0 +1,83 @@
+/*
+ * 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.
+ */
+
+import {
+	buildGenericSuppressionSnippet,
+	getNormalizedRelevantStack,
+	matchesIgnoreRules,
+	parseOriginFrame,
+} from "./finding-suppression";
+
+describe("finding suppression", () => {
+	const stack = [
+		"Error",
+		"    at renderTemplate (C:\\repo\\tests\\bug-detectors\\sample.test.js:10:42)",
+		"    at handleRequest (/repo/src/server.js:20:7)",
+		"    at internal (/repo/jazzer.js/packages/core/core.js:30:1)",
+	].join("\n");
+
+	test("normalizes relevant stacks for full-stack matching", () => {
+		expect(getNormalizedRelevantStack(stack)).toBe(
+			[
+				"at renderTemplate (C:/repo/tests/bug-detectors/sample.test.js:10)",
+				"at handleRequest (/repo/src/server.js:20)",
+			].join("\n"),
+		);
+	});
+
+	test("matches string stack patterns against the normalized stack", () => {
+		const originFrame = parseOriginFrame(stack);
+
+		expect(
+			matchesIgnoreRules(
+				[{ stackPattern: "sample.test.js:10" }],
+				originFrame,
+				stack,
+			),
+		).toBe(true);
+		expect(
+			matchesIgnoreRules(
+				[{ stackPattern: "sample.test.js:11" }],
+				originFrame,
+				stack,
+			),
+		).toBe(false);
+	});
+
+	test("matches regex stack patterns against the normalized stack", () => {
+		const originFrame = parseOriginFrame(stack);
+
+		expect(
+			matchesIgnoreRules(
+				[{ stackPattern: /handleRequest \(\/repo\/src\/server\.js:20\)/ }],
+				originFrame,
+				stack,
+			),
+		).toBe(true);
+	});
+
+	test("prints generic example snippets with optional chaining", () => {
+		expect(
+			buildGenericSuppressionSnippet("code-injection", "ignoreInvocation"),
+		).toContain('getBugDetectorConfiguration("code-injection")');
+		expect(
+			buildGenericSuppressionSnippet("code-injection", "ignoreInvocation"),
+		).toContain("?.ignoreInvocation({");
+		expect(
+			buildGenericSuppressionSnippet("code-injection", "ignoreInvocation"),
+		).toContain('stackPattern: "test.js:10"');
+	});
+});

packages/bug-detectors/internal/finding-suppression.ts

@@ -40,10 +40,12 @@ export interface IgnoreRule {
 	 */
 	functionPattern?: RegExp;
 	/**
-	 * A regular expression matching the raw stack trace string.
-	 * Use this as a fallback if file or function names are minified or missing.
+	 * A string or regular expression matching the normalized relevant stack trace.
+	 * Use this when you want to match the full call chain rather than one frame.
+	 * @example "src/templates.js:41"
+	 * @example /renderTemplate.*handleRequest/s
 	 */
-	stackPattern?: RegExp;
+	stackPattern?: string | RegExp;
 }
 
 export type OriginFrame = {
@@ -60,39 +62,35 @@ export function matchesIgnoreRules(
 	return rules.some((rule) => matchesIgnoreRule(rule, originFrame, stack));
 }
 
-export function buildSuppressionSnippet(
+export function buildGenericSuppressionSnippet(
 	detectorName: string,
 	suppressionMethod: string,
-	originFrame: OriginFrame | undefined,
-	stack: string,
 ): string {
-	const ruleLines: string[] = [];
-	const filePattern =
-		originFrame?.filePath && buildFilePattern(originFrame.filePath);
-	if (filePattern) {
-		ruleLines.push(`filePattern: ${filePattern}`);
-	}
-	if (originFrame?.functionName) {
-		ruleLines.push(
-			`functionPattern: ${buildExactRegex(originFrame.functionName)}`,
-		);
-	}
-	if (ruleLines.length === 0) {
-		ruleLines.push(`stackPattern: ${buildStackPattern(stack)}`);
-	}
-
 	return [
 		'const { getBugDetectorConfiguration } = require("@jazzer.js/bug-detectors");',
 		"",
+		"// Example only: adapt `stackPattern` to the stack trace above.",
 		`getBugDetectorConfiguration("${detectorName}")`,
-		`  .${suppressionMethod}({`,
-		...ruleLines.map(
-			(line, index) => `    ${line}${index < ruleLines.length - 1 ? "," : ""}`,
-		),
+		`  ?.${suppressionMethod}({`,
+		'    stackPattern: "test.js:10",',
 		"  });",
 	].join("\n");
 }
 
+export function getNormalizedRelevantStack(stack: string): string {
+	return getRelevantStackLines(stack)
+		.map((line) => normalizeStackLine(line))
+		.join("\n");
+}
+
+function normalizeStackLine(line: string): string {
+	return line
+		.replace(/\\/g, "/")
+		.replace(/:(\d+):\d+(?=[)\s]|$)/g, ":$1")
+		.replace(/\s+/g, " ")
+		.trim();
+}
+
 export function captureStack(): string {
 	return new Error().stack ?? "";
 }
@@ -138,7 +136,11 @@ function matchesIgnoreRule(
 	originFrame: OriginFrame | undefined,
 	stack: string,
 ): boolean {
-	if (rule.stackPattern && !matchesPattern(rule.stackPattern, stack)) {
+	const normalizedStack = getNormalizedRelevantStack(stack);
+	if (
+		rule.stackPattern &&
+		!matchesStackPattern(rule.stackPattern, normalizedStack)
+	) {
 		return false;
 	}
 	if (rule.filePattern) {
@@ -160,43 +162,6 @@ function matchesIgnoreRule(
 	return Boolean(rule.stackPattern || rule.filePattern || rule.functionPattern);
 }
 
-function buildFilePattern(filePath: string): string | undefined {
-	if (filePath.startsWith("node:")) {
-		return undefined;
-	}
-
-	const normalized = filePath.replace(/\\/g, "/");
-	let parts = normalized.split("/").filter(Boolean);
-	if (parts.length === 0) {
-		return undefined;
-	}
-	if (/^[A-Za-z]:$/.test(parts[0])) {
-		parts = parts.slice(1);
-	}
-
-	const nodeModulesIndex = parts.indexOf("node_modules");
-	if (nodeModulesIndex !== -1) {
-		parts = parts.slice(nodeModulesIndex + 1);
-	} else {
-		parts = parts.slice(-Math.min(2, parts.length));
-	}
-
-	return `/${parts.map(escapeRegex).join("[\\\\/]")}$/`;
-}
-
-function buildExactRegex(text: string): string {
-	return `/^${escapeRegex(text)}$/`;
-}
-
-function buildStackPattern(stack: string): string {
-	const stackLine = getRelevantStackLines(stack)[0] ?? "  at <unknown>";
-	const normalized = stackLine
-		.replace(/:\d+:\d+/g, "")
-		.replace(/^\s*at\s+/, "")
-		.trim();
-	return `/${escapeRegex(normalized)}/`;
-}
-
 function normalizeFunctionName(functionName: string): string {
 	const trimmed = functionName.trim();
 	if (trimmed.length === 0 || trimmed === "<anonymous>") {
@@ -233,6 +198,9 @@ function matchesPattern(pattern: RegExp, value: string): boolean {
 	return pattern.test(value);
 }
 
-function escapeRegex(value: string): string {
-	return value.replace(/[|\\{}()[\]^$+*?./]/g, "\\$&");
+function matchesStackPattern(pattern: string | RegExp, value: string): boolean {
+	if (typeof pattern === "string") {
+		return value.includes(pattern.replace(/\\/g, "/"));
+	}
+	return matchesPattern(pattern, value);
 }

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

@@ -21,14 +21,15 @@ import {
 import { callSiteId, registerBeforeHook } from "@jazzer.js/hooking";
 
 import { bugDetectorConfigurations } from "../configuration";
+
 import {
-	buildSuppressionSnippet,
+	buildGenericSuppressionSnippet,
 	captureStack,
 	getRelevantStackLines,
-	matchesIgnoreRules,
-	parseOriginFrame,
 	type IgnoreRule,
+	matchesIgnoreRules,
 	type OriginFrame,
+	parseOriginFrame,
 } from "./finding-suppression";
 
 /**
@@ -257,7 +258,7 @@ function detectFindingAndGuideFuzzing(
 				return;
 			}
 			reportAndThrowFinding(
-				buildFindingMessage(functionName, argument, stack, originFrame),
+				buildFindingMessage(functionName, argument, stack),
 				false,
 			);
 		}
@@ -269,7 +270,6 @@ function buildFindingMessage(
 	functionName: string,
 	argument: string,
 	stack: string,
-	originFrame: OriginFrame | undefined,
 ): string {
 	const relevantStackLines = getRelevantStackLines(stack).slice(
 		0,
@@ -285,8 +285,9 @@ function buildFindingMessage(
 	message.push(
 		"",
 		"[!] If this path is expected in your test environment, suppress it:",
+		"    Example only: copy/paste it and adapt `stackPattern` to your needs.",
 		"",
-		buildSuppressionSnippet("path-traversal", "ignore", originFrame, stack),
+		buildGenericSuppressionSnippet("path-traversal", "ignore"),
 	);
 	return message.join("\n");
 }