ai-saas-guard 0.6.0 → 0.7.0

package/README.md

@@ -51,8 +51,8 @@ The CLI is published on npm as `ai-saas-guard`, and the GitHub Action is availab
 | JSON and SARIF output | Available |
 | Composite GitHub Action | Available |
 | Project config | `.ai-saas-guard.json` rule toggles, severity overrides, and fail thresholds |
-| Versioned Action tags | `v0.6.0`, `v0` |
-| npm package | `ai-saas-guard@0.6.0` |
+| Versioned Action tags | `v0.7.0`, `v0` |
+| npm package | `ai-saas-guard@0.7.0` |
 | npm publishing | Trusted Publisher/OIDC, no long-lived publish token |
 
 ## Quick Start
@@ -189,17 +189,26 @@ Add `.ai-saas-guard.json` at the repository root to tune findings without changi
     "stripe.webhook.missing-signature": "off",
     "stripe.webhook.missing-idempotency": "critical",
     "deploy.env.example-missing": "info"
-  }
+  },
+  "suppressions": [
+    {
+      "ruleId": "stripe.webhook.missing-idempotency",
+      "paths": ["app/api/stripe/webhook/route.ts"],
+      "reason": "Temporary launch exception with duplicate-event coverage in integration tests."
+    }
+  ]
 }
 ```
 
 `rules` is keyed by published rule ID from [docs/rules.md](docs/rules.md). Set a rule to `off` to remove matching findings from terminal, JSON, SARIF, and markdown output. Set a rule to `critical`, `high`, `medium`, `low`, or `info` to override severity before summaries and `--fail-on` are evaluated.
 
+Use `suppressions` for narrower false-positive handling when one rule is noisy only for specific generated files, fixtures, or reviewed exceptions. Each suppression must name a known `ruleId` and one or more relative `paths` globs, such as `generated/**` or `app/api/stripe/webhook/route.ts`.
+
 `failOn` sets the default CI failure threshold for the project. A CLI `--fail-on` value takes precedence, so local runs can still use `--fail-on none` or a stricter threshold.
 
 ## GitHub Action
 
-The repo includes a composite Action. Use `v0` for the latest compatible pre-1.0 Action, a specific release tag such as `v0.6.0` for controlled upgrades, or pin a reviewed commit SHA for stricter supply-chain control:
+The repo includes a composite Action. Use `v0` for the latest compatible pre-1.0 Action, a specific release tag such as `v0.7.0` for controlled upgrades, or pin a reviewed commit SHA for stricter supply-chain control:
 
 ```yaml
 name: ai-saas-guard
@@ -328,7 +337,6 @@ Open-source core:
 
 Near-term priorities:
 
-- false-positive suppression and rule stability labels
 - GitHub App design note for the potential hosted layer
 
 Potential paid layer later:

package/dist/config.d.ts

@@ -1,10 +1,16 @@
 import type { BaseReport, Severity } from "./types.js";
 export declare const defaultConfigFileName = ".ai-saas-guard.json";
 export type RuleConfigValue = "off" | Severity;
+export interface FindingSuppression {
+    ruleId: string;
+    paths: string[];
+    reason?: string;
+}
 export interface GuardConfig {
     sourcePath?: string;
     failOn?: Severity | "none";
     rules: Record<string, RuleConfigValue>;
+    suppressions?: FindingSuppression[];
 }
 export declare function loadGuardConfig(rootDir: string, explicitPath?: string): Promise<GuardConfig>;
 export declare function applyGuardConfig<T extends BaseReport>(report: T, config: GuardConfig): T;

package/dist/config.js

@@ -11,22 +11,22 @@ export async function loadGuardConfig(rootDir, explicitPath) {
     }
     catch (error) {
         if (!explicitPath && isNotFoundError(error))
-            return { rules: {} };
+            return { rules: {}, suppressions: [] };
         throw new Error(`Could not read config file ${sourcePath}: ${errorMessage(error)}`);
     }
     return parseGuardConfig(content, sourcePath);
 }
 export function applyGuardConfig(report, config) {
     const configuredRuleIds = Object.keys(config.rules);
-    if (configuredRuleIds.length === 0)
+    const suppressions = config.suppressions ?? [];
+    if (configuredRuleIds.length === 0 && suppressions.length === 0)
         return report;
     const findings = sortFindings(report.findings.flatMap((finding) => {
         const ruleConfig = config.rules[finding.ruleId];
-        if (!ruleConfig)
-            return [finding];
         if (ruleConfig === "off")
             return [];
-        return [{ ...finding, severity: ruleConfig }];
+        const configuredFinding = ruleConfig ? { ...finding, severity: ruleConfig } : finding;
+        return isSuppressed(configuredFinding, suppressions) ? [] : [configuredFinding];
     }));
     return {
         ...report,
@@ -63,12 +63,84 @@ function parseGuardConfig(content, sourcePath) {
         }
         rules[ruleId] = value;
     }
+    const rawSuppressions = parsed.suppressions ?? [];
+    if (!Array.isArray(rawSuppressions)) {
+        throw new Error("Invalid config suppressions: expected an array");
+    }
+    const suppressions = rawSuppressions.map((value, index) => parseSuppression(value, index));
     return {
         sourcePath,
         failOn,
-        rules
+        rules,
+        suppressions
+    };
+}
+function parseSuppression(value, index) {
+    if (!isPlainObject(value)) {
+        throw new Error(`Invalid config suppressions[${index}]: expected an object`);
+    }
+    const ruleId = value.ruleId;
+    if (typeof ruleId !== "string" || ruleId.length === 0) {
+        throw new Error(`Invalid config suppressions[${index}].ruleId: expected a rule ID`);
+    }
+    if (!getRuleMetadata(ruleId)) {
+        throw new Error(`Unknown rule ID in suppression: ${ruleId}`);
+    }
+    const paths = value.paths;
+    if (!Array.isArray(paths) || paths.length === 0 || !paths.every((path) => typeof path === "string" && path.length > 0)) {
+        throw new Error(`Invalid config suppressions[${index}].paths: expected a non-empty array of path globs`);
+    }
+    const reason = value.reason;
+    if (reason !== undefined && typeof reason !== "string") {
+        throw new Error(`Invalid config suppressions[${index}].reason: expected a string`);
+    }
+    return {
+        ruleId,
+        paths,
+        reason
     };
 }
+function isSuppressed(finding, suppressions) {
+    return suppressions.some((suppression) => suppression.ruleId === finding.ruleId &&
+        finding.evidence.some((evidence) => suppression.paths.some((pattern) => pathMatches(pattern, evidence.file))));
+}
+function pathMatches(pattern, filePath) {
+    return globToRegExp(normalizeConfigPath(pattern)).test(normalizeConfigPath(filePath));
+}
+function normalizeConfigPath(path) {
+    return path.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+function globToRegExp(pattern) {
+    let expression = "^";
+    for (let index = 0; index < pattern.length; index += 1) {
+        const char = pattern[index];
+        if (char === "*") {
+            const next = pattern[index + 1];
+            const afterNext = pattern[index + 2];
+            if (next === "*" && afterNext === "/") {
+                expression += "(?:.*/)?";
+                index += 2;
+            }
+            else if (next === "*") {
+                expression += ".*";
+                index += 1;
+            }
+            else {
+                expression += "[^/]*";
+            }
+        }
+        else if (char === "?") {
+            expression += "[^/]";
+        }
+        else {
+            expression += escapeRegExp(char);
+        }
+    }
+    return new RegExp(`${expression}$`);
+}
+function escapeRegExp(value) {
+    return value.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
+}
 function isRuleConfigValue(value) {
     return value === "off" || isSeverity(value);
 }

package/dist/index.d.ts

@@ -8,5 +8,5 @@ export { createScanContext } from "./context.js";
 export { getRuleMetadata, RULE_CATALOG } from "./rules/catalog.js";
 export type { BaseReport, CommandName, Evidence, Finding, McpReport, McpServerInventory, PrRiskFile, PrRiskReport, ScanOptions, StripeReport, SupabaseReport } from "./types.js";
 export type { ScanContext, ScanInput } from "./context.js";
-export type { GuardConfig, RuleConfigValue } from "./config.js";
+export type { FindingSuppression, GuardConfig, RuleConfigValue } from "./config.js";
 export type { RuleMetadata, RuleStability } from "./rules/catalog.js";

package/dist/report/sarif.js

@@ -5,13 +5,18 @@ export function formatSarifReport(report) {
         if (rules.has(finding.ruleId))
             continue;
         const metadata = getRuleMetadata(finding.ruleId);
+        const stability = metadata?.stability ?? "default";
         rules.set(finding.ruleId, {
             id: finding.ruleId,
             name: finding.ruleId,
             shortDescription: { text: metadata?.title ?? finding.title },
             fullDescription: { text: metadata?.why ?? finding.why },
             help: { text: `${finding.suggestedVerification}\n\nFix direction: ${finding.suggestedFix}` },
-            defaultConfiguration: { level: sarifLevel(finding) }
+            defaultConfiguration: { level: sarifLevel(finding) },
+            properties: {
+                "ai-saas-guard/stability": stability,
+                tags: [`stability:${stability}`]
+            }
         });
     }
     return `${JSON.stringify({

package/dist/rules/catalog.js

@@ -4,14 +4,14 @@ export const RULE_CATALOG = {
         severity: "high",
         title: "Secret-like value detected",
         why: "Credentials committed to source, config, or examples can be exposed before launch.",
-        stability: "default"
+        stability: "strict"
     },
     "next.env.public-secret": {
         ruleId: "next.env.public-secret",
         severity: "high",
         title: "Risky NEXT_PUBLIC environment variable",
         why: "Next.js exposes NEXT_PUBLIC variables to browser code, so secret-like values can leak to users.",
-        stability: "default"
+        stability: "strict"
     },
     "stripe.webhook.missing-route": {
         ruleId: "stripe.webhook.missing-route",
@@ -25,7 +25,7 @@ export const RULE_CATALOG = {
         severity: "critical",
         title: "Stripe webhook does not verify the Stripe signature",
         why: "Unsigned webhook handlers can accept forged billing events.",
-        stability: "default"
+        stability: "strict"
     },
     "stripe.webhook.raw-body-risk": {
         ruleId: "stripe.webhook.raw-body-risk",
@@ -39,7 +39,7 @@ export const RULE_CATALOG = {
         severity: "critical",
         title: "Stripe signing secret appears public",
         why: "Public Stripe secrets can be bundled into client code and abused.",
-        stability: "default"
+        stability: "strict"
     },
     "stripe.webhook.missing-idempotency": {
         ruleId: "stripe.webhook.missing-idempotency",
@@ -53,7 +53,7 @@ export const RULE_CATALOG = {
         severity: "medium",
         title: "Stripe webhook does not show an entitlement update path",
         why: "Returning HTTP 200 is not the same as changing application access state.",
-        stability: "default"
+        stability: "experimental"
     },
     "stripe.webhook.missing-critical-event": {
         ruleId: "stripe.webhook.missing-critical-event",
@@ -67,7 +67,7 @@ export const RULE_CATALOG = {
         severity: "critical",
         title: "Broad Supabase RLS policy",
         why: "`USING (true)` or `WITH CHECK (true)` can turn login into broad data access or writes.",
-        stability: "default"
+        stability: "strict"
     },
     "supabase.rls.missing-ownership-filter": {
         ruleId: "supabase.rls.missing-ownership-filter",
@@ -95,7 +95,7 @@ export const RULE_CATALOG = {
         severity: "critical",
         title: "Sensitive table does not enable row level security",
         why: "User-data tables should enable row level security.",
-        stability: "default"
+        stability: "strict"
     },
     "supabase.storage.public-bucket": {
         ruleId: "supabase.storage.public-bucket",
@@ -109,14 +109,14 @@ export const RULE_CATALOG = {
         severity: "medium",
         title: "Sensitive API route lacks obvious rate limiting",
         why: "Login, checkout, upload, AI, and webhook routes are common abuse targets.",
-        stability: "default"
+        stability: "experimental"
     },
     "api.route.auth-without-ownership": {
         ruleId: "api.route.auth-without-ownership",
         severity: "high",
         title: "API route checks auth but lacks an ownership guard",
         why: "Login checks do not prove resource ownership checks.",
-        stability: "default"
+        stability: "experimental"
     },
     "deploy.next.static-export-api-risk": {
         ruleId: "deploy.next.static-export-api-risk",
@@ -137,14 +137,14 @@ export const RULE_CATALOG = {
         severity: "low",
         title: "Important runtime env var is not documented",
         why: "Missing env docs cause local-success, production-failure deploys.",
-        stability: "default"
+        stability: "experimental"
     },
     "mcp.config.invalid-json": {
         ruleId: "mcp.config.invalid-json",
         severity: "medium",
         title: "MCP config is not valid JSON",
         why: "Broken MCP configs hide the actual tool inventory.",
-        stability: "default"
+        stability: "strict"
     },
     "mcp.config.plaintext-secret": {
         ruleId: "mcp.config.plaintext-secret",
@@ -200,7 +200,7 @@ export const RULE_CATALOG = {
         severity: "medium",
         title: "Review first sensitive PR surface",
         why: "AI-generated PRs often bury trust-boundary changes inside larger diffs.",
-        stability: "default"
+        stability: "experimental"
     },
     "pr-risk.diff-unavailable": {
         ruleId: "pr-risk.diff-unavailable",

package/docs/github-action.md

@@ -2,7 +2,7 @@
 
 `ai-saas-guard` ships as a composite GitHub Action for pull request and code scanning workflows.
 
-Use `zr9959/ai-saas-guard@v0` for the latest compatible pre-1.0 Action. Use a specific tag such as `v0.6.0` or a reviewed commit SHA when reproducibility is more important than automatic minor updates.
+Use `zr9959/ai-saas-guard@v0` for the latest compatible pre-1.0 Action. Use a specific tag such as `v0.7.0` or a reviewed commit SHA when reproducibility is more important than automatic minor updates.
 
 ## PR Summary
 
@@ -50,7 +50,7 @@ The Action auto-loads `.ai-saas-guard.json` from `root` when the file exists. Us
           fail-on: none
 ```
 
-Project config can disable noisy rules, override severity by rule ID, and set a default `failOn` threshold. A workflow `fail-on` input overrides the config threshold for that run.
+Project config can disable noisy rules, override severity by rule ID, apply path-specific `suppressions`, and set a default `failOn` threshold. A workflow `fail-on` input overrides the config threshold for that run.
 
 ## SARIF Upload
 

package/docs/npm-publishing.md

@@ -5,10 +5,10 @@
 ## Current State
 
 - Package name: `ai-saas-guard`
-- Current version: `0.6.0`
+- Current version: `0.7.0`
 - npm registry state: published at <https://www.npmjs.com/package/ai-saas-guard>
 - First npm-published version: `0.1.1`
-- GitHub Release: `v0.6.0`
+- GitHub Release: `v0.7.0`
 - Publish workflow: `.github/workflows/npm-publish.yml`
 - Trusted Publisher: GitHub Actions, `zr9959/ai-saas-guard`, workflow `npm-publish.yml`, allowed action `npm publish`
 - Long-lived npm publish token: not required
@@ -17,7 +17,7 @@
 
 Use GitHub Actions with npm Trusted Publisher/OIDC:
 
-1. Create and review a release tag such as `v0.6.0`.
+1. Create and review a release tag such as `v0.7.0`.
 2. Publish from the GitHub Release or run the `Publish npm` workflow manually with `ref` set to that tag.
 3. Keep `permissions.id-token: write` in the workflow so npm can exchange the GitHub Actions OIDC identity for a short-lived publish credential.
 4. Run `npm publish --access public` from the workflow. Trusted publishing automatically generates provenance for this public package from this public repository.

package/docs/project-handoff.md

@@ -49,7 +49,8 @@ Implemented surfaces:
 - PR diff risk triage for auth, billing, RLS, env, tests removed, and large mixed diffs
 - PR diff diagnostics when a base ref or shallow checkout prevents comparison
 - PR-focused markdown summary output for GitHub step summaries or PR comments
-- project-local `.ai-saas-guard.json` config for rule toggles, severity overrides, and default fail thresholds
+- project-local `.ai-saas-guard.json` config for rule toggles, severity overrides, path-specific suppressions, and default fail thresholds
+- rule stability labels in catalog metadata, public rule docs, and SARIF rule properties
 - JSON output
 - SARIF output
 - composite GitHub Action wrapper
@@ -101,7 +102,7 @@ GitHub Project:
 
 Current issue set:
 
-- No open roadmap issues after the `v0.6.0` checklist release.
+- No open roadmap issues after the `v0.7.0` suppression and stability release.
 
 CI:
 
@@ -113,7 +114,7 @@ CI:
 Publishing:
 
 - npm package: `ai-saas-guard`
-- Current release line: `v0.6.0`
+- Current release line: `v0.7.0`
 - Publish workflow: `.github/workflows/npm-publish.yml`
 - Trusted Publisher: GitHub Actions for `zr9959/ai-saas-guard`, workflow `npm-publish.yml`
 - Long-lived npm publish tokens should not be required.
@@ -140,8 +141,7 @@ Not allowed:
 
 Recommended order:
 
-1. Improve false-positive suppression and rule stability labels.
-2. Add a GitHub App design note for the potential hosted layer.
+1. Add a GitHub App design note for the potential hosted layer.
 
 For every feature, keep the scanner evidence-first:
 

package/docs/rules.md

@@ -2,7 +2,37 @@
 
 `ai-saas-guard` rules are deterministic heuristics. They are designed to produce a focused verification queue, not a complete vulnerability list.
 
-Rule metadata is centralized in `src/rules/catalog.ts` and covered by tests so SARIF output, public docs, and future config work can share stable rule IDs. Current published rules use the `default` stability level.
+Rule metadata is centralized in `src/rules/catalog.ts` and covered by tests so SARIF output, public docs, and config work can share stable rule IDs, default severities, and stability labels.
+
+## Stability Labels
+
+Stability labels describe how much confidence reviewers should place in a finding before manual verification. They are not severity levels.
+
+| Stability | Meaning | Examples |
+| --- | --- | --- |
+| Strict | High-confidence evidence that should rarely be suppressed without a written reason. | Committed secret-like values, public Stripe secrets, unsigned Stripe webhooks, broad Supabase RLS policies. |
+| Default | Routine launch-readiness heuristic with useful evidence and an expected manual verification step. | Missing Stripe lifecycle events, weak Supabase ownership checks, MCP side-effect inventory. |
+| Experimental | Higher-noise heuristic meant to prioritize review, not prove a defect. | API ownership hints, rate-limit hints, missing env docs, PR risk triage. |
+
+SARIF output includes the rule stability in `properties["ai-saas-guard/stability"]` and a `stability:<level>` tag for code scanning consumers.
+
+## Suppressing False Positives
+
+Prefer fixing risky code over suppressing findings. When a finding is a reviewed false positive for a specific generated file, fixture, or documented launch exception, use path-specific `suppressions` in `.ai-saas-guard.json` instead of disabling the whole rule:
+
+```json
+{
+  "suppressions": [
+    {
+      "ruleId": "stripe.webhook.missing-idempotency",
+      "paths": ["app/api/stripe/webhook/route.ts"],
+      "reason": "Temporary exception; duplicate-event behavior is covered by integration tests."
+    }
+  ]
+}
+```
+
+`paths` are relative globs. Examples: `generated/**`, `tests/fixtures/**`, and `app/api/stripe/webhook/route.ts`.
 
 ## Secrets And Public Env
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-saas-guard",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Repo-local launch-readiness scanner for AI-built SaaS apps.",
   "type": "module",
   "homepage": "https://github.com/zr9959/ai-saas-guard#readme",