@coo-quack/sensitive-canary 0.5.3 → 0.6.0

package/CHANGELOG.md

@@ -1,11 +1,27 @@
-## v0.5.2 (2026-03-31)
+# Changelog
 
-### Security
+## v0.6.0 (2026-08-02)
 
-- Add `minimumReleaseAge` to renovate.json to prevent supply chain attacks
-  - Waits 7 days before auto-merging dependency updates
-  - Reduces risk of package takeover attacks
-  - Blocks immediate auto-merge of newly published packages
+### Features
+
+- Add `SENSITIVE_CANARY_CATEGORIES` environment variable to limit which rule categories are active
+  - Accepts `secret`, `pii`, `secret,pii`, or `all` (comma-separated, case-insensitive); unset/empty/invalid means all categories
+  - Useful for reducing PII false positives (e.g. credit card or phone number rules firing on test fixtures) by scanning secrets only
+  - The name-based `.env`/`.env.*` block is a secret guard and is disabled when the `secret` category is not enabled
+
+---
+
+## v0.5.3 (2026-06-27)
+
+### CI
+
+- Rework the main→develop sync to open a PR with auto-merge, using a minted GitHub App token so the created PR triggers CI
+- Disable persist-credentials in the sync workflow so the App token push works
+
+### Dependencies
+
+- Pin pnpm via the `packageManager` field and update pnpm to v11 (security)
+- Update node to v24, vite to v8, typescript to v6, and other dev dependencies and GitHub Actions
 
 ---
 
@@ -20,8 +36,6 @@
 
 ---
 
-# Changelog
-
 ## v0.5.1 (2026-03-15)
 
 ### Fixes

package/README.md

@@ -183,7 +183,7 @@ To allow it through, add the suggested tag:
 
 ### .env file blocked
 
-`.env` / `.env.*` files are blocked unconditionally, regardless of their contents.
+`.env` / `.env.*` files are blocked by filename, regardless of their contents. This name-based block is a secret guard and only applies while the `secret` category is enabled (the default).
 
 ```
 > Read .env
@@ -228,6 +228,32 @@ To intentionally bypass a block, include the appropriate tag in your **current p
 
 ---
 
+## Configuration
+
+### `SENSITIVE_CANARY_CATEGORIES`
+
+Limit which rule categories are active. Set it in the `env` block of your Claude Code `settings.json`:
+
+```json
+{
+  "env": {
+    "SENSITIVE_CANARY_CATEGORIES": "secret"
+  }
+}
+```
+
+| Value | Effect |
+|---|---|
+| `secret` | Scan for secrets only — PII rules are disabled |
+| `pii` | Scan for PII only — secret rules and the name-based `.env`/`.env.*` block are disabled |
+| `secret,pii` / `all` | Scan everything (default) |
+
+Values are comma-separated and case-insensitive. Unset, empty, or containing no valid token means all categories are enabled.
+
+This is a persistent filter, unlike allow tags which apply per prompt. The category filter is applied first, then allow tags. A typical use is setting `secret` when PII rules (credit card numbers, phone numbers, …) are too noisy against test fixtures.
+
+---
+
 ## Detection rules
 
 ### Secrets (24 rules)
@@ -302,7 +328,7 @@ Claude calls Read / Bash tool
 PreToolUse hook
       ↓
       ── Read tool ─────────────────────────────────────────────────────
-      │  1. filename is .env / .env.* → blocked unconditionally
+      │  1. filename is .env / .env.* → blocked (secret category only)
       │  2. file contents contain secret / PII → blocked
       └─ Bash tool ─────────────────────────────────────────────────────
          1. env var values referenced in the command contain secret / PII → blocked
@@ -317,7 +343,7 @@ The terminal also receives a direct message (via `/dev/tty`).
 
 ## Allow Tags (detailed)
 
-Allow tags filter the scan results — the scan itself always runs. The `.env`/`.env.*` name block is the only exception: when an allow tag is present, the file is passed through immediately without scanning.
+Allow tags filter the scan results — the scan still runs. The `.env`/`.env.*` name block is the only exception: when an allow tag is present, the file is passed through immediately without scanning.
 
 ### Mask tags
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coo-quack/sensitive-canary",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "description": "Claude Code hooks that block secrets and PII before they reach the Anthropic API",
   "homepage": "https://coo-quack.github.io/sensitive-canary/",
   "type": "module",
@@ -20,11 +20,11 @@
     "node": ">=22.6.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.4",
-    "@types/node": "^25.3.0",
-    "typescript": "^6.0.0",
-    "vitepress": "^1.6.4",
-    "vitest": "^4.0.18"
+    "@biomejs/biome": "2.5.6",
+    "@types/node": "25.9.5",
+    "typescript": "7.0.2",
+    "vitepress": "2.0.0-alpha.18",
+    "vitest": "4.1.10"
   },
   "scripts": {
     "test": "vitest run",

package/src/__tests__/pre-tool-use-hook.test.ts

@@ -1,5 +1,5 @@
 import { spawnSync } from "node:child_process";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
@@ -58,7 +58,7 @@ function writeTranscriptWithToolResults(
 function runHook(
   toolName: string,
   filePath: string,
-  opts?: { transcriptPath?: string },
+  opts?: { env?: Record<string, string>; transcriptPath?: string },
 ) {
   const input = JSON.stringify({
     transcript_path: opts?.transcriptPath,
@@ -68,6 +68,7 @@ function runHook(
   const result = spawnSync("node", [...NODE_FLAGS, HOOK], {
     input,
     encoding: "utf8",
+    env: { ...process.env, ...opts?.env },
   });
   const { decision, reason } = parseHookOutput(result.stdout);
   return {
@@ -135,9 +136,9 @@ describe("pre-tool-use-hook — non-Read/non-Bash tools", () => {
   });
 });
 
-// ── .env / .env.* — unconditional name block ──────────────────────────────────
+// ── .env / .env.* — secret name block ─────────────────────────────────────────
 
-describe("pre-tool-use-hook — .env/.env.* unconditional block", () => {
+describe("pre-tool-use-hook — .env/.env.* name block (secret category)", () => {
   it("blocks .env regardless of content", () => {
     const p = writeFixture(".env", "DEBUG=true\nNODE_ENV=development\n");
     const { exitCode, decision } = runHook("Read", p);
@@ -386,23 +387,18 @@ describe("pre-tool-use-hook — Bash tool (command string)", () => {
 // ── Bash tool — file-reading command blocking ─────────────────────────────────
 
 describe("pre-tool-use-hook — Bash tool (file-reading commands)", () => {
-  it.each([
-    "cat",
-    "head",
-    "tail",
-    "less",
-    "more",
-    "bat",
-    "nl",
-  ])("blocks %s on a file with secrets", (cmd) => {
-    const p = writeFixture(
-      `creds-${cmd}.txt`,
-      "AWS_KEY=AKIAIOSFODNN7EXAMPLE\n",
-    );
-    const { exitCode, decision } = runBashHook(`${cmd} ${p}`);
-    expect(exitCode).toBe(2);
-    expect(decision).toBe("block");
-  });
+  it.each(["cat", "head", "tail", "less", "more", "bat", "nl"])(
+    "blocks %s on a file with secrets",
+    (cmd) => {
+      const p = writeFixture(
+        `creds-${cmd}.txt`,
+        "AWS_KEY=AKIAIOSFODNN7EXAMPLE\n",
+      );
+      const { exitCode, decision } = runBashHook(`${cmd} ${p}`);
+      expect(exitCode).toBe(2);
+      expect(decision).toBe("block");
+    },
+  );
 
   it("blocks cat on a file with PII", () => {
     const p = writeFixture("contacts-bash.txt", "Email: user@example.com\n");
@@ -711,3 +707,73 @@ describe("pre-tool-use-hook — malformed input", () => {
     expect(result.status).toBe(0);
   });
 });
+
+// ── SENSITIVE_CANARY_CATEGORIES ───────────────────────────────────────────────
+
+describe("pre-tool-use-hook — SENSITIVE_CANARY_CATEGORIES", () => {
+  it("pii-only: allows reading .env files (secret guard disabled)", () => {
+    const dir = join(tmpDir, "pii-only-env");
+    mkdirSync(dir, { recursive: true });
+    const p = join(dir, ".env");
+    writeFileSync(p, "DEBUG=true\n", "utf8");
+    const { exitCode } = runHook("Read", p, {
+      env: { SENSITIVE_CANARY_CATEGORIES: "pii" },
+    });
+    expect(exitCode).toBe(0);
+  });
+
+  it("pii-only: allows a file containing only secrets", () => {
+    const p = writeFixture("pii-only-secret.txt", "key=AKIAIOSFODNN7EXAMPLE");
+    const { exitCode } = runHook("Read", p, {
+      env: { SENSITIVE_CANARY_CATEGORIES: "pii" },
+    });
+    expect(exitCode).toBe(0);
+  });
+
+  it("pii-only: still blocks a file containing PII", () => {
+    const p = writeFixture("pii-only-pii.txt", "card: 4111111111111111");
+    const { exitCode, decision } = runHook("Read", p, {
+      env: { SENSITIVE_CANARY_CATEGORIES: "pii" },
+    });
+    expect(exitCode).toBe(2);
+    expect(decision).toBe("block");
+  });
+
+  it("secret-only: allows a file containing only PII", () => {
+    const p = writeFixture("secret-only-pii.txt", "card: 4111111111111111");
+    const { exitCode } = runHook("Read", p, {
+      env: { SENSITIVE_CANARY_CATEGORIES: "secret" },
+    });
+    expect(exitCode).toBe(0);
+  });
+
+  it("secret-only: still blocks a file containing secrets", () => {
+    const p = writeFixture(
+      "secret-only-secret.txt",
+      "key=AKIAIOSFODNN7EXAMPLE",
+    );
+    const { exitCode, decision } = runHook("Read", p, {
+      env: { SENSITIVE_CANARY_CATEGORIES: "secret" },
+    });
+    expect(exitCode).toBe(2);
+    expect(decision).toBe("block");
+  });
+
+  it("secret-only: allows a bash command containing only PII", () => {
+    const { exitCode } = runBashHook("echo 4111111111111111", {
+      env: { SENSITIVE_CANARY_CATEGORIES: "secret" },
+    });
+    expect(exitCode).toBe(0);
+  });
+
+  it("unset: blocks both secrets and PII (default behavior)", () => {
+    const p = writeFixture(
+      "default-both.txt",
+      "key=AKIAIOSFODNN7EXAMPLE\ncard: 4111111111111111",
+    );
+    const { exitCode, reason } = runHook("Read", p);
+    expect(exitCode).toBe(2);
+    expect(reason).toContain("aws-access-key");
+    expect(reason).toContain("pii-credit-card");
+  });
+});

package/src/__tests__/user-prompt-submit-hook.test.ts

@@ -4,10 +4,11 @@ import { describe, expect, it } from "vitest";
 const HOOK = new URL("../user-prompt-submit-hook.ts", import.meta.url).pathname;
 const NODE_FLAGS = ["--experimental-strip-types"];
 
-function runHook(prompt: string) {
+function runHook(prompt: string, opts?: { env?: Record<string, string> }) {
   const result = spawnSync("node", [...NODE_FLAGS, HOOK], {
     input: JSON.stringify({ prompt }),
     encoding: "utf8",
+    env: { ...process.env, ...opts?.env },
   });
   return {
     exitCode: result.status ?? -1,
@@ -253,3 +254,44 @@ describe("user-prompt-submit-hook — malformed input", () => {
     expect(result.status).toBe(0);
   });
 });
+
+describe("user-prompt-submit-hook — SENSITIVE_CANARY_CATEGORIES", () => {
+  it("pii-only: passes a prompt containing only secrets", () => {
+    const { exitCode } = runHook("my key is AKIAIOSFODNN7EXAMPLE", {
+      env: { SENSITIVE_CANARY_CATEGORIES: "pii" },
+    });
+    expect(exitCode).toBe(0);
+  });
+
+  it("pii-only: still blocks a prompt containing PII", () => {
+    const { exitCode, stderr } = runHook("my card is 4111111111111111", {
+      env: { SENSITIVE_CANARY_CATEGORIES: "pii" },
+    });
+    expect(exitCode).toBe(2);
+    expect(stderr).toContain("sensitive data detected");
+  });
+
+  it("secret-only: passes a prompt containing only PII", () => {
+    const { exitCode } = runHook("my card is 4111111111111111", {
+      env: { SENSITIVE_CANARY_CATEGORIES: "secret" },
+    });
+    expect(exitCode).toBe(0);
+  });
+
+  it("secret-only: still blocks a prompt containing secrets", () => {
+    const { exitCode, stderr } = runHook("my key is AKIAIOSFODNN7EXAMPLE", {
+      env: { SENSITIVE_CANARY_CATEGORIES: "secret" },
+    });
+    expect(exitCode).toBe(2);
+    expect(stderr).toContain("sensitive data detected");
+  });
+
+  it("unset: blocks both secrets and PII (default behavior)", () => {
+    const { exitCode, stderr } = runHook(
+      "key AKIAIOSFODNN7EXAMPLE card 4111111111111111",
+    );
+    expect(exitCode).toBe(2);
+    expect(stderr).toContain("aws-access-key");
+    expect(stderr).toContain("pii-credit-card");
+  });
+});

package/src/lib/__tests__/rules.test.ts

@@ -1,5 +1,12 @@
-import { describe, expect, it } from "vitest";
-import { entropy, luhn, redact, scan } from "../rules.ts";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  enabledCategoriesFromEnv,
+  entropy,
+  luhn,
+  parseCategories,
+  redact,
+  scan,
+} from "../rules.ts";
 
 // ── luhn ──────────────────────────────────────────────────────────────────────
 
@@ -350,3 +357,92 @@ describe("scan — PII", () => {
     expect(findings.some((f) => f.ruleId === "pii-ipv4")).toBe(false);
   });
 });
+
+// ── parseCategories ───────────────────────────────────────────────────────────
+
+describe("parseCategories", () => {
+  it("defaults to all categories when unset", () => {
+    expect(parseCategories(undefined)).toEqual(new Set(["secret", "pii"]));
+  });
+
+  it("defaults to all categories when empty", () => {
+    expect(parseCategories("")).toEqual(new Set(["secret", "pii"]));
+  });
+
+  it("parses a single category", () => {
+    expect(parseCategories("secret")).toEqual(new Set(["secret"]));
+    expect(parseCategories("pii")).toEqual(new Set(["pii"]));
+  });
+
+  it("parses a comma-separated list", () => {
+    expect(parseCategories("secret,pii")).toEqual(new Set(["secret", "pii"]));
+  });
+
+  it("treats 'all' as every category", () => {
+    expect(parseCategories("all")).toEqual(new Set(["secret", "pii"]));
+    expect(parseCategories("secret,all")).toEqual(new Set(["secret", "pii"]));
+  });
+
+  it("is case-insensitive and trims whitespace", () => {
+    expect(parseCategories(" Secret , PII ")).toEqual(
+      new Set(["secret", "pii"]),
+    );
+  });
+
+  it("falls back to all when no valid token is present", () => {
+    expect(parseCategories("foo,bar")).toEqual(new Set(["secret", "pii"]));
+  });
+});
+
+// ── scan: category filter ─────────────────────────────────────────────────────
+
+describe("scan — category filter", () => {
+  const text = "key=AKIAIOSFODNN7EXAMPLE card: 4111111111111111";
+
+  it("scans all categories by default", () => {
+    const findings = scan(text);
+    expect(findings.some((f) => f.ruleId === "aws-access-key")).toBe(true);
+    expect(findings.some((f) => f.ruleId === "pii-credit-card")).toBe(true);
+  });
+
+  it("scans only secrets when limited to the secret category", () => {
+    const findings = scan(text, new Set(["secret"]));
+    expect(findings.some((f) => f.ruleId === "aws-access-key")).toBe(true);
+    expect(findings.some((f) => f.ruleId === "pii-credit-card")).toBe(false);
+  });
+
+  it("scans only PII when limited to the pii category", () => {
+    const findings = scan(text, new Set(["pii"]));
+    expect(findings.some((f) => f.ruleId === "aws-access-key")).toBe(false);
+    expect(findings.some((f) => f.ruleId === "pii-credit-card")).toBe(true);
+  });
+
+  it("returns nothing when no categories are enabled", () => {
+    expect(scan(text, new Set())).toEqual([]);
+  });
+});
+
+// ── enabledCategoriesFromEnv ──────────────────────────────────────────────────
+
+describe("enabledCategoriesFromEnv", () => {
+  const ENV_KEY = "SENSITIVE_CANARY_CATEGORIES";
+  const original = process.env[ENV_KEY];
+
+  afterEach(() => {
+    if (original === undefined) {
+      delete process.env[ENV_KEY];
+    } else {
+      process.env[ENV_KEY] = original;
+    }
+  });
+
+  it("returns all categories when the env var is unset", () => {
+    delete process.env[ENV_KEY];
+    expect(enabledCategoriesFromEnv()).toEqual(new Set(["secret", "pii"]));
+  });
+
+  it("returns the parsed categories when the env var is set", () => {
+    process.env[ENV_KEY] = "pii";
+    expect(enabledCategoriesFromEnv()).toEqual(new Set(["pii"]));
+  });
+});

package/src/lib/rules.ts

@@ -1,7 +1,9 @@
+export type Category = "secret" | "pii";
+
 export interface Finding {
   ruleId: string;
   description: string;
-  category: "secret" | "pii";
+  category: Category;
   matchRedacted: string;
   secretValue: string;
 }
@@ -13,7 +15,30 @@ interface Rule {
   secretGroup?: number;
   entropyThreshold?: number;
   validate?: (str: string) => boolean;
-  category: "secret" | "pii";
+  category: Category;
+}
+
+const ALL_CATEGORIES: ReadonlySet<Category> = new Set(["secret", "pii"]);
+
+// Parse the SENSITIVE_CANARY_CATEGORIES env var: a comma-separated list of
+// "secret", "pii", or "all" (e.g. "secret" or "secret,pii"). Unset, empty, or
+// containing no valid token means all categories are enabled.
+export function parseCategories(value: string | undefined): Set<Category> {
+  const categories = new Set<Category>();
+  for (const token of (value ?? "").split(",")) {
+    const normalized = token.trim().toLowerCase();
+    if (normalized === "all") return new Set(ALL_CATEGORIES);
+    if (normalized === "secret" || normalized === "pii")
+      categories.add(normalized);
+  }
+  return categories.size > 0 ? categories : new Set(ALL_CATEGORIES);
+}
+
+// Rule categories enabled for this process, from SENSITIVE_CANARY_CATEGORIES
+// ("secret", "pii", "secret,pii", or "all"; default: all).
+export function enabledCategoriesFromEnv(): Set<Category> {
+  const { SENSITIVE_CANARY_CATEGORIES } = process.env;
+  return parseCategories(SENSITIVE_CANARY_CATEGORIES);
 }
 
 // Luhn algorithm checksum validation. Returns true if the number (digits only) passes.
@@ -292,10 +317,14 @@ export function redact(str: string): string {
   return `${str.slice(0, 4)}****${str.slice(-4)}`;
 }
 
-export function scan(text: string): Finding[] {
+export function scan(
+  text: string,
+  categories: ReadonlySet<Category> = ALL_CATEGORIES,
+): Finding[] {
   const findings: Finding[] = [];
 
   for (const rule of RULES) {
+    if (!categories.has(rule.category)) continue;
     for (const match of text.matchAll(rule.regex)) {
       const secretValue =
         rule.secretGroup != null ? match[rule.secretGroup] : match[0];

package/src/pre-tool-use-hook.ts

@@ -10,7 +10,7 @@ import {
   parseAllowTags,
   randomBird,
 } from "./lib/inspector.ts";
-import { type Finding, scan } from "./lib/rules.ts";
+import { enabledCategoriesFromEnv, type Finding, scan } from "./lib/rules.ts";
 
 interface HookInput {
   transcript_path?: string;
@@ -30,6 +30,8 @@ interface TranscriptLine {
 // Maximum bytes to read from the tail of a transcript file.
 const MAX_TRANSCRIPT_TAIL_BYTES = 65_536; // 64 KB
 
+const ENABLED_CATEGORIES = enabledCategoriesFromEnv();
+
 // ── Transcript ────────────────────────────────────────────────────────────────
 
 // Returns true when the message contains at least one text content block
@@ -150,7 +152,8 @@ function extractFilePathsFromCommand(command: string): string[] {
 
 // ── .env pattern ──────────────────────────────────────────────────────────────
 
-// .env and .env.* (e.g. .env.local, .env.production) are blocked unconditionally.
+// .env and .env.* (e.g. .env.local, .env.production) match the env filename pattern.
+// The block only applies while the "secret" category is enabled (see shouldBlockEnvFile).
 // Files that merely end in .env (e.g. production.env) are handled by content scanning.
 function isBlockedEnvFile(filePath: string): boolean {
   if (!filePath) return false;
@@ -158,6 +161,12 @@ function isBlockedEnvFile(filePath: string): boolean {
   return base === ".env" || base.startsWith(".env.");
 }
 
+// The .env name-based block is a secret guard: it only applies while the
+// "secret" category is enabled.
+function shouldBlockEnvFile(filePath: string): boolean {
+  return ENABLED_CATEGORIES.has("secret") && isBlockedEnvFile(filePath);
+}
+
 // ── Output helpers ────────────────────────────────────────────────────────────
 
 // Build the allow-tag hint lines shown to Claude.
@@ -239,7 +248,7 @@ function block(
 // ── Core scan logic ───────────────────────────────────────────────────────────
 
 function scanFile(filePath: string, allowTags: Set<string>): void {
-  if (isBlockedEnvFile(filePath)) {
+  if (shouldBlockEnvFile(filePath)) {
     if (allowTags.size > 0) return;
     block(
       filePath,
@@ -263,7 +272,10 @@ function scanFile(filePath: string, allowTags: Set<string>): void {
     return;
   }
 
-  const findings = applyAllowTags(dedupeFindings(scan(content)), allowTags);
+  const findings = applyAllowTags(
+    dedupeFindings(scan(content, ENABLED_CATEGORIES)),
+    allowTags,
+  );
   if (findings.length === 0) return;
 
   block(
@@ -308,7 +320,10 @@ process.stdin.on("end", () => {
     for (const varName of extractEnvVarNames(command)) {
       const value = process.env[varName];
       if (!value) continue;
-      const findings = applyAllowTags(dedupeFindings(scan(value)), allowTags);
+      const findings = applyAllowTags(
+        dedupeFindings(scan(value, ENABLED_CATEGORIES)),
+        allowTags,
+      );
       if (findings.length === 0) continue;
       block(
         `bash command: ${command.slice(0, 80)}`,
@@ -322,7 +337,7 @@ process.stdin.on("end", () => {
     }
 
     const cmdFindings = applyAllowTags(
-      dedupeFindings(scan(command)),
+      dedupeFindings(scan(command, ENABLED_CATEGORIES)),
       allowTags,
     );
     if (cmdFindings.length > 0) {

package/src/user-prompt-submit-hook.ts

@@ -8,12 +8,14 @@ import {
   randomBird,
   resolveTagPriority,
 } from "./lib/inspector.ts";
-import { scan } from "./lib/rules.ts";
+import { enabledCategoriesFromEnv, scan } from "./lib/rules.ts";
 
 interface HookInput {
   prompt?: string;
 }
 
+const ENABLED_CATEGORIES = enabledCategoriesFromEnv();
+
 let raw = "";
 process.stdin.setEncoding("utf8");
 process.stdin.on("data", (chunk: string) => (raw += chunk));
@@ -27,7 +29,7 @@ process.stdin.on("end", () => {
 
   const prompt = data.prompt ?? "";
 
-  const allFindings = scan(prompt);
+  const allFindings = scan(prompt, ENABLED_CATEGORIES);
 
   if (allFindings.length === 0) process.exit(0);