sherscan 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NightWiing
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,188 @@
+# 🔍 sherscan
+
+**AI-aware security scanner**, finds exposed secrets in your codebase and checks whether your AI coding agent (Cursor, Copilot, Windsurf, Claude Code, etc.) can actually read your sensitive files.
+
+Most secret scanners stop at "you have a `.env` file." sherscan goes one step further: it checks whether that file is actually **blocked from AI agents** via `.cursorignore`, `.aiexclude`, `.clineignore`, Claude Code's deny rules.
+
+## Why
+
+AI coding assistants can read almost any file in your project by default. If your `.env`, private keys, or credentials aren't explicitly excluded, your AI agent (and anything it shares context with) can see them. sherscan audits this blind spot in seconds.
+
+## Features
+
+- 🔎 **Sensitive file detection**, flags `.env` files, private keys (`.pem`, `.key`, `id_rsa`), cloud credentials (`.aws/credentials`, `.npmrc`), keystores, and more.
+- 🔑 **Secret scanning**, greps file contents for real leaked credentials: AWS keys, GitHub tokens, Stripe keys, Supabase keys, Anthropic keys, SendGrid keys, private key blocks, JWTs, and generic hardcoded secrets.
+- 🤖 **AI exposure check**, cross-references every sensitive file against the ignore files of 9+ AI tools (Cursor, Windsurf, Cline, Gemini, Codeium, Copilot, Claude Code, and generic `.aiignore`) to see if it's actually protected.
+- 🛡️ **Masked previews**, secrets are shown masked (e.g. `AKIA********MNOP`) so reports are safe to share/paste.
+- 📊 **Readable or machine output**, pretty colored terminal report by default, or `--json` for scripting.
+- 🚦 **CI-friendly**, `--ci` flag exits with code `1` when exposed secrets are found, so you can fail a pipeline on real risk.
+
+## Installation
+
+Run it directly without installing anything (recommended):
+
+```bash
+npx sherscan
+```
+
+Or install globally:
+
+```bash
+npm install -g sherscan
+```
+
+Or add it as a dev dependency to run via npm scripts:
+
+```bash
+npm install --save-dev sherscan
+```
+
+## Usage
+
+Scan the current directory:
+
+```bash
+npx sherscan
+```
+
+Scan a specific project path:
+
+```bash
+npx sherscan ./path/to/project
+```
+
+Output JSON (for scripting or piping into other tools):
+
+```bash
+npx sherscan --json
+```
+
+Fail CI when a sensitive file with no AI-ignore coverage is found:
+
+```bash
+npx sherscan --ci
+```
+
+### Options
+
+| Flag            | Description                                                   |
+| --------------- | ------------------------------------------------------------- |
+| `[path]`        | Project directory to scan (defaults to `.`)                   |
+| `--json`        | Output results as JSON instead of a colored report            |
+| `--ci`          | Exit with code `1` if any fully-exposed findings are detected |
+| `-V, --version` | Print the version number                                      |
+| `-h, --help`    | Print usage help                                              |
+
+## Example output
+
+```
+────────────────────────────────────────────────────
+  🔍 sherscan  · AI-aware security scanner
+────────────────────────────────────────────────────
+
+────────────────────────────────── SUMMARY ──────────────────────────────────
+
+  Sensitive files found       1
+  Secrets in content          1
+  Files exposed to AI agents  1
+
+    HIGH      1 file(s)
+
+────────────────────────────── SECRETS DETECTED ─────────────────────────────
+
+    HIGH    .env
+           Line 1  ·  AWS Access Key
+           Preview: SECRET_KEY=AKIA********MNOP
+
+──────────────────────────────── AI EXPOSURE ────────────────────────────────
+
+    HIGH    .env
+           Status   fully exposed   has secret
+
+──────────────────────────────── RECOMMENDATIONS ────────────────────────────
+
+  ✖  No AI ignore files found in this project
+
+  →  Create a .aiignore or .cursorignore and add:
+       .env
+
+  ⚠   Rotate these credentials immediately:
+      .env
+
+────────────────────────────────────────────────────
+  ✖  Issues found — review recommendations above
+────────────────────────────────────────────────────
+```
+
+## What it checks
+
+### Sensitive files
+
+sherscan flags files matching common sensitive-file patterns, including:
+
+- `.env`, `.env.*` (any environment file)
+- `*.pem`, `*.key`, `id_rsa*`, `id_ed25519*` (private keys)
+- `*.p12`, `*.pfx`, `*.keystore` (certificates/keystores)
+- `credentials.json`, `secrets.*`
+- `.npmrc`
+- `.aws/credentials`, `.aws/config`
+- Supabase's `supabase/.temp/**` directory
+
+### Secret patterns
+
+File contents (for common source/config file types under 500 KB, skipping binaries) are scanned for:
+
+- AWS Access Keys
+- GitHub Tokens
+- Stripe Live/Test Keys
+- Supabase Keys
+- Anthropic API Keys
+- SendGrid Keys
+- Private key blocks (`-----BEGIN ... PRIVATE KEY-----`)
+- Generic JWTs
+- Hardcoded `SECRET` / `API_KEY` / `PRIVATE_KEY` / `AUTH_TOKEN` assignments
+
+Matches inside comments are skipped, and all detected secrets are masked in the report.
+
+### AI exposure
+
+For every sensitive file found, sherscan checks whether it's covered by any of these AI-tool ignore mechanisms:
+
+| Tool        | Ignore file                                        |
+| ----------- | -------------------------------------------------- |
+| Cursor      | `.cursorignore`, `.cursorindexingignore`           |
+| Windsurf    | `.windsurfignore`                                  |
+| Cline       | `.clineignore`                                     |
+| Gemini      | `.aiexclude`, `.geminiignore`                      |
+| Codeium     | `.codeiumignore`                                   |
+| Copilot     | `.copilotignore`                                   |
+| Claude Code | `.claude/settings.json` (`permissions.deny` rules) |
+| Generic     | `.aiignore`                                        |
+
+A file is marked **fully exposed** if none of the detected AI tools' ignore rules cover it — meaning an AI agent working in that project could read it.
+
+## Using in CI
+
+Add sherscan to your pipeline to catch exposed secrets before they ship:
+
+```yaml
+# .github/workflows/security.yml
+name: Security check
+on: [push, pull_request]
+jobs:
+  sherscan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: npx sherscan --ci
+```
+
+The command exits with code `1` if any sensitive file is fully exposed to an AI agent, failing the build.
+
+## Requirements
+
+- Node.js >= 18
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import path from "node:path";
+import fs from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { scan } from "../src/scanner.js";
+import { findSensitiveFiles } from "../src/sensitive-files.js";
+import { findSecrets } from "../src/secrets.js";
+import { checkAiExposure } from "../src/ai-exposure.js";
+import { printJsonReport, printReport } from "../src/report.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(
+  await fs.readFile(path.join(__dirname, "..", "package.json"), "utf-8"),
+);
+
+const program = new Command();
+
+program
+  .name("sherscan")
+  .description("A tool to check the integrity of your files")
+  .version(pkg.version)
+  .argument("[path]", "project directory to scan", ".")
+  .option("--json", "output results as JSON instead of colored text")
+  .option("--ci", "exit with code 1 if any findings are detected")
+  .action((targetPath, options) => {
+    const resolvedPath = path.resolve(targetPath);
+    runScan(resolvedPath, options);
+  });
+
+program.parse();
+
+async function runScan(resolvedPath, options) {
+  const files = await scan(resolvedPath);
+  const sensitive = findSensitiveFiles(files);
+  const secrets = await findSecrets(files, resolvedPath);
+  const aiExposure = await checkAiExposure(sensitive, secrets, resolvedPath);
+
+  if (options.json) {
+    printJsonReport(sensitive, secrets, aiExposure);
+  } else {
+    printReport(sensitive, secrets, aiExposure);
+  }
+
+  // exit code 1 for CI pipelines
+  if (options.ci && aiExposure.some((e) => e.fullyExposed)) {
+    process.exit(1);
+  }
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "sherscan",
+  "version": "0.1.0",
+  "description": "AI-aware security scanner — finds exposed secrets and checks if your AI agent can read sensitive files",
+  "type": "module",
+  "bin": {
+    "sherscan": "./bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "dependencies": {
+    "commander": "^15.0.0",
+    "fast-glob": "^3.3.3",
+    "ignore": "^7.0.5",
+    "micromatch": "^4.0.8",
+    "picocolors": "^1.1.1"
+  },
+  "keywords": [
+    "security",
+    "secrets",
+    "ai",
+    "cursor",
+    "copilot",
+    "env",
+    "scanner",
+    "cli"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nightwiing/sherscan.git"
+  },
+  "homepage": "https://github.com/nightwiing/sherscan#readme",
+  "bugs": {
+    "url": "https://github.com/nightwiing/sherscan/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/ai-exposure.js

@@ -0,0 +1,159 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import ignore from "ignore";
+
+// ─── Config ──────────────────────────────────────────────────────────────────
+
+const AI_IGNORE_FILES = [
+  { file: ".cursorignore", tool: "Cursor" },
+  { file: ".cursorindexingignore", tool: "Cursor" },
+  { file: ".aiexclude", tool: "Gemini" },
+  { file: ".aiignore", tool: "Generic" },
+  { file: ".clineignore", tool: "Cline" },
+  { file: ".windsurfignore", tool: "Windsurf" },
+  { file: ".geminiignore", tool: "Gemini" },
+  { file: ".codeiumignore", tool: "Codeium" },
+  { file: ".copilotignore", tool: "Copilot" },
+];
+
+const AI_TOOL_DIRS = [
+  { dir: ".cursor", tool: "Cursor" },
+  { dir: ".windsurf", tool: "Windsurf" },
+  { dir: ".claude", tool: "Claude Code" },
+  { dir: ".codeium", tool: "Codeium" },
+  { dir: ".gemini", tool: "Gemini" },
+  { dir: ".vscode", tool: "VS Code / Copilot" },
+];
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+// detect which AI tools are actually being used in the project
+async function detectTools(rootPath) {
+  const detected = [];
+
+  await Promise.all(
+    AI_TOOL_DIRS.map(async ({ dir, tool }) => {
+      try {
+        await fs.access(path.join(rootPath, dir));
+        detected.push(tool);
+      } catch {
+        // directory doesn't exist, tool not in use
+      }
+    }),
+  );
+
+  return detected;
+}
+
+// parse a single gitignore-style AI ignore file
+// returns { tool, ig } where ig is an ignore instance, or null if file doesn't exist
+async function parseIgnoreFile(rootPath, { file, tool }) {
+  try {
+    const content = await fs.readFile(path.join(rootPath, file), "utf-8");
+    const ig = ignore().add(content);
+    return { tool, file, ig };
+  } catch {
+    return null;
+  }
+}
+
+// parse Claude Code's settings.json separately — it uses JSON, not gitignore syntax
+async function parseClaudeSettings(rootPath) {
+  try {
+    const content = await fs.readFile(
+      path.join(rootPath, ".claude", "settings.json"),
+      "utf-8",
+    );
+    const settings = JSON.parse(content);
+    const denyRules = settings?.permissions?.deny ?? [];
+    return denyRules;
+  } catch {
+    return [];
+  }
+}
+
+// check if a Claude Code deny rule covers a given file
+// deny rules look like: "Read(.env)" or "Read(secrets/**)"
+function isClaudeDenied(file, denyRules) {
+  return denyRules.some((rule) => {
+    const match = rule.match(/^Read\((.+)\)$/);
+    if (!match) return false;
+    const pattern = match[1];
+    // exact match or simple wildcard
+    if (pattern === file) return true;
+    if (pattern.endsWith("/**") && file.startsWith(pattern.slice(0, -3)))
+      return true;
+    if (pattern.startsWith("*.") && file.endsWith(pattern.slice(1)))
+      return true;
+    return false;
+  });
+}
+
+// decide severity based on whether a real secret was found inside this file
+function getSeverity(file, secrets, isTempFile) {
+  if (isTempFile) return "low";
+  const hasSecret = secrets.some((s) => s.file === file);
+  return hasSecret ? "high" : "medium";
+}
+
+// ─── Main ────────────────────────────────────────────────────────────────────
+
+export async function checkAiExposure(sensitiveFiles, secrets, rootPath) {
+  // 1. detect which AI tools are present in this project
+  const detectedTools = await detectTools(rootPath);
+
+  // 2. parse all AI ignore files that exist
+  const parsedIgnoreFiles = (
+    await Promise.all(
+      AI_IGNORE_FILES.map((entry) => parseIgnoreFile(rootPath, entry)),
+    )
+  ).filter(Boolean); // drop nulls (files that don't exist)
+
+  // 3. parse Claude Code settings separately
+  const claudeDenyRules = await parseClaudeSettings(rootPath);
+
+  // 4. cross-check each sensitive file
+  const exposure = sensitiveFiles.map(({ file }) => {
+    const coveredBy = [];
+    const notCoveredBy = [];
+
+    // check each gitignore-style ignore file
+    for (const { tool, file: ignoreFile, ig } of parsedIgnoreFiles) {
+      try {
+        if (ig.ignores(file)) {
+          coveredBy.push(ignoreFile);
+        } else {
+          notCoveredBy.push(ignoreFile);
+        }
+      } catch {
+        // ignore package throws on some edge case paths — treat as not covered
+        notCoveredBy.push(ignoreFile);
+      }
+    }
+
+    // check Claude Code deny rules
+    if (claudeDenyRules.length > 0) {
+      if (isClaudeDenied(file, claudeDenyRules)) {
+        coveredBy.push(".claude/settings.json");
+      } else {
+        notCoveredBy.push(".claude/settings.json");
+      }
+    }
+
+    const isTempFile = file.includes(".temp/");
+    const hasSecret = secrets.some((s) => s.file === file);
+
+    return {
+      file,
+      severity: getSeverity(file, secrets, isTempFile),
+      coveredBy,
+      notCoveredBy,
+      detectedTools,
+      hasSecret,
+      // fully exposed = no AI ignore file covers it at all
+      fullyExposed: coveredBy.length === 0,
+    };
+  });
+
+  return exposure;
+}

package/src/report.js

@@ -0,0 +1,216 @@
+import pc from "picocolors";
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function divider(char = "─", length = 50) {
+  return pc.dim(char.repeat(length));
+}
+
+function severityBadge(severity) {
+  if (severity === "high") return pc.bgRed(pc.white("  HIGH  "));
+  if (severity === "medium") return pc.bgYellow(pc.black(" MEDIUM "));
+  return pc.bgBlackBright(pc.white("  LOW   "));
+}
+
+function sectionHeader(title) {
+  console.log(`\n${divider()} ${pc.bold(title)} ${divider()}\n`);
+}
+
+// ─── Sections ────────────────────────────────────────────────────────────────
+
+function printBanner() {
+  console.log("\n" + divider("─", 52));
+  console.log(
+    pc.bold("  🔍 sherscan") + pc.dim("  · AI-aware security scanner"),
+  );
+  console.log(divider("─", 52));
+}
+
+function printSummary(sensitive, secrets, exposure) {
+  sectionHeader("SUMMARY");
+
+  const exposed = exposure.filter((e) => e.fullyExposed).length;
+  const highCount = exposure.filter((e) => e.severity === "high").length;
+  const mediumCount = exposure.filter((e) => e.severity === "medium").length;
+  const lowCount = exposure.filter((e) => e.severity === "low").length;
+
+  const sensitiveLabel =
+    sensitive.length > 0
+      ? pc.yellow(sensitive.length)
+      : pc.green(sensitive.length);
+
+  const secretsLabel =
+    secrets.length > 0
+      ? pc.red(pc.bold(secrets.length))
+      : pc.green(secrets.length);
+
+  const exposedLabel =
+    exposed > 0 ? pc.red(pc.bold(exposed)) : pc.green(exposed);
+
+  console.log(`  Sensitive files found       ${sensitiveLabel}`);
+  console.log(`  Secrets in content          ${secretsLabel}`);
+  console.log(`  Files exposed to AI agents  ${exposedLabel}`);
+  console.log();
+
+  if (highCount > 0)
+    console.log(`  ${severityBadge("high")}    ${highCount} file(s)`);
+  if (mediumCount > 0)
+    console.log(`  ${severityBadge("medium")}   ${mediumCount} file(s)`);
+  if (lowCount > 0)
+    console.log(`  ${severityBadge("low")}    ${lowCount} file(s)`);
+
+  if (highCount === 0 && mediumCount === 0 && lowCount === 0) {
+    console.log(`  ${pc.green("✔")}  No exposure issues found`);
+  }
+}
+
+function printSecrets(secrets) {
+  if (secrets.length === 0) return;
+
+  sectionHeader("SECRETS DETECTED");
+
+  for (const secret of secrets) {
+    console.log(`  ${severityBadge("high")}  ${pc.bold(pc.red(secret.file))}`);
+    console.log(
+      `           ${pc.dim("Line " + secret.line + "  ·  " + secret.rule)}`,
+    );
+    console.log(
+      `           ${pc.dim("Preview: ")}${pc.yellow(secret.preview)}`,
+    );
+    console.log();
+  }
+}
+
+function printExposure(exposure) {
+  sectionHeader("AI EXPOSURE");
+
+  if (exposure.length === 0) {
+    console.log(`  ${pc.green("✔")}  No sensitive files found\n`);
+    return;
+  }
+
+  for (const item of exposure) {
+    const badge = severityBadge(item.severity);
+
+    const statusText = item.fullyExposed
+      ? pc.red("fully exposed")
+      : pc.green("protected");
+
+    const secretTag = item.hasSecret
+      ? "  " + pc.bgRed(pc.white(" has secret "))
+      : "";
+
+    console.log(`  ${badge}  ${pc.bold(item.file)}`);
+    console.log(`           Status   ${statusText}${secretTag}`);
+
+    if (item.detectedTools.length > 0) {
+      console.log(
+        `           Tools    ${pc.dim(item.detectedTools.join(", "))}`,
+      );
+    }
+
+    if (item.coveredBy.length > 0) {
+      console.log(`           Covered  ${pc.green(item.coveredBy.join(", "))}`);
+    }
+
+    if (item.notCoveredBy.length > 0) {
+      console.log(
+        `           Missing  ${pc.red(item.notCoveredBy.join(", "))}`,
+      );
+    }
+
+    console.log();
+  }
+}
+
+function printRecommendations(exposure) {
+  sectionHeader("RECOMMENDATIONS");
+
+  const exposed = exposure.filter((e) => e.fullyExposed);
+
+  if (exposed.length === 0) {
+    console.log(`  ${pc.green("✔")}  All sensitive files are protected\n`);
+    return;
+  }
+
+  // detect which tools are present across all findings
+  const detectedTools = [...new Set(exposure.flatMap((e) => e.detectedTools))];
+
+  // check if the project has zero AI ignore files at all
+  const noIgnoreFiles = exposure.every(
+    (e) => e.coveredBy.length === 0 && e.notCoveredBy.length === 0,
+  );
+
+  if (noIgnoreFiles) {
+    console.log(`  ${pc.red("✖")}  No AI ignore files found in this project\n`);
+  }
+
+  // tool-specific suggestions
+  const toolIgnoreMap = {
+    Cursor: ".cursorignore",
+    Windsurf: ".windsurfignore",
+    Cline: ".clineignore",
+    Gemini: ".aiexclude",
+    Codeium: ".codeiumignore",
+    "VS Code / Copilot": ".copilotignore",
+    "Claude Code": ".claude/settings.json  (permissions.deny)",
+    Generic: ".aiignore",
+  };
+
+  const exposedFiles = exposed.map((e) => e.file);
+
+  for (const tool of detectedTools) {
+    const ignoreFile = toolIgnoreMap[tool];
+    if (!ignoreFile) continue;
+
+    console.log(`  ${pc.cyan("→")}  Add these to your ${pc.bold(ignoreFile)}:`);
+    exposedFiles.forEach((f) => console.log(`       ${pc.yellow(f)}`));
+    console.log();
+  }
+
+  // if no specific tool detected, give a generic recommendation
+  if (detectedTools.length === 0) {
+    console.log(
+      `  ${pc.cyan("→")}  Create a ${pc.bold(".aiignore")} or ${pc.bold(".cursorignore")} and add:`,
+    );
+    exposedFiles.forEach((f) => console.log(`       ${pc.yellow(f)}`));
+    console.log();
+  }
+
+  // rotate credentials warning
+  const highExposed = exposed.filter((e) => e.severity === "high");
+  if (highExposed.length > 0) {
+    console.log(pc.red(pc.bold("  ⚠   Rotate these credentials immediately:")));
+    highExposed.forEach((e) => console.log(`      ${pc.red(pc.bold(e.file))}`));
+    console.log();
+  }
+}
+
+function printFooter(exposure) {
+  const hasIssues = exposure.some((e) => e.fullyExposed);
+
+  console.log(divider("─", 52));
+  if (hasIssues) {
+    console.log(pc.red("  ✖  Issues found — review recommendations above"));
+  } else {
+    console.log(pc.green("  ✔  Project looks clean"));
+  }
+  console.log(divider("─", 52) + "\n");
+}
+
+// ─── Main export ─────────────────────────────────────────────────────────────
+
+export function printReport(sensitive, secrets, exposure) {
+  printBanner();
+  printSummary(sensitive, secrets, exposure);
+  printSecrets(secrets);
+  printExposure(exposure);
+  printRecommendations(exposure);
+  printFooter(exposure);
+}
+
+// ─── JSON mode export ─────────────────────────────────────────────────────────
+
+export function printJsonReport(sensitive, secrets, exposure) {
+  console.log(JSON.stringify({ sensitive, secrets, exposure }, null, 2));
+}

package/src/scanner.js

@@ -0,0 +1,27 @@
+import fg from "fast-glob";
+
+export async function scan(path) {
+  const files = await fg("**/*", {
+    cwd: path,
+    dot: true,
+    onlyFiles: true,
+    ignore: [
+      ".DS_Store",
+      "node_modules",
+      ".git",
+      "dist",
+      "build",
+      "out",
+      "target",
+      "tmp",
+      "package-lock.json",
+      "yarn.lock",
+      "pnpm-lock.yaml",
+      "bun.lockb",
+      ".output",
+      ".nuxt",
+      "*/.nuxt/**",
+    ],
+  });
+  return files;
+}

package/src/secrets.js

@@ -0,0 +1,230 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+
+const ALLOWED_FILENAMES = new Set([
+  "Dockerfile",
+  "Makefile",
+  "Procfile",
+  "Jenkinsfile",
+  "Brewfile",
+]);
+
+const ALLOWED_EXTENSIONS = new Set([
+  // JavaScript / TypeScript
+  ".js",
+  ".mjs",
+  ".cjs",
+  ".ts",
+  ".mts",
+  ".cts",
+  ".jsx",
+  ".tsx",
+  // Frameworks
+  ".vue",
+  ".svelte",
+  // Config formats
+  ".json",
+  ".yaml",
+  ".yml",
+  ".toml",
+  ".ini",
+  ".cfg",
+  ".conf",
+  ".xml",
+  ".properties",
+  // Shell
+  ".sh",
+  ".bash",
+  ".zsh",
+  ".fish",
+  // Other languages
+  ".py",
+  ".rb",
+  ".php",
+  ".go",
+  ".rs",
+  ".java",
+  ".cs",
+  // Docs / text
+  ".md",
+  ".mdx",
+  ".txt",
+  // Web
+  ".env",
+]);
+
+const SECRET_PATTERNS = [
+  { name: "AWS Access Key", regex: /AKIA[0-9A-Z]{16}/g },
+  { name: "GitHub Token", regex: /gh[pousr]_[A-Za-z0-9]{36,}/g },
+  { name: "Stripe Live Key", regex: /sk_live_[0-9a-zA-Z]{24,}/g },
+  { name: "Stripe Test Key", regex: /sk_test_[0-9a-zA-Z]{24,}/g },
+  { name: "Supabase Key", regex: /sbp_[a-zA-Z0-9]{40,}/g },
+  { name: "Anthropic Key", regex: /sk-ant-[a-zA-Z0-9\-]{32,}/g },
+  { name: "SendGrid Key", regex: /SG\.[a-zA-Z0-9]{22}\.[a-zA-Z0-9]{43}/g },
+  {
+    name: "Private Key Block",
+    regex: /-----BEGIN (RSA |EC |OPENSSH |PGP )?PRIVATE KEY-----/g,
+  },
+  {
+    name: "Generic JWT",
+    regex: /eyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g,
+  },
+  {
+    name: "Hardcoded Secret",
+    regex:
+      /(SECRET|API_KEY|PRIVATE_KEY|AUTH_TOKEN)\s*[:=]\s*["']?[A-Za-z0-9_\-]{16,}["']?/gi,
+  },
+];
+
+const MAX_FILE_SIZE = 500 * 1024;
+const SNIFF_BYTES = 512;
+
+async function isBinaryFile(filePath) {
+  const handle = await fs.open(filePath, "r");
+  try {
+    const buffer = Buffer.alloc(SNIFF_BYTES);
+    const { bytesRead } = await handle.read(buffer, 0, SNIFF_BYTES, 0);
+    return buffer.subarray(0, bytesRead).includes(0);
+  } finally {
+    await handle.close();
+  }
+}
+
+const MASK_VISIBLE_CHARS = 4;
+const MASK_FILLER = "*".repeat(8);
+
+function maskSecret(secret) {
+  if (secret.length <= MASK_VISIBLE_CHARS * 2) {
+    return "*".repeat(secret.length);
+  }
+  return `${secret.slice(0, MASK_VISIBLE_CHARS)}${MASK_FILLER}${secret.slice(-MASK_VISIBLE_CHARS)}`;
+}
+
+function maskLine(line, matches) {
+  let masked = line;
+  for (const match of matches) {
+    masked = masked.split(match).join(maskSecret(match));
+  }
+  return masked.trim();
+}
+
+const COMMENT_PREFIXES = ["#", "//", ";"];
+const BLOCK_COMMENT_MARKERS = [
+  { start: "/*", end: "*/" },
+  { start: "<!--", end: "-->" },
+];
+
+function isCommentLine(line) {
+  const trimmed = line.trim();
+  return COMMENT_PREFIXES.some((prefix) => trimmed.startsWith(prefix));
+}
+
+async function scanContent(content, file) {
+  const lines = content.split("\n");
+  const findings = [];
+
+  const isEnvFile = path.basename(file).startsWith(".env");
+  const patterns = isEnvFile
+    ? SECRET_PATTERNS.filter((p) => p.name !== "Hardcoded Secret")
+    : SECRET_PATTERNS;
+
+  let activeBlockCommentEnd = null;
+
+  lines.forEach((lineText, index) => {
+    const trimmed = lineText.trim();
+
+    // still inside a multi-line block comment (e.g. /* ... */, <!-- ... -->)
+    if (activeBlockCommentEnd) {
+      if (trimmed.includes(activeBlockCommentEnd)) {
+        activeBlockCommentEnd = null;
+      }
+      return;
+    }
+
+    // line opens a block comment — skip it, and keep skipping until it closes
+    const opener = BLOCK_COMMENT_MARKERS.find((marker) =>
+      trimmed.startsWith(marker.start),
+    );
+    if (opener) {
+      const closesOnSameLine = trimmed
+        .slice(opener.start.length)
+        .includes(opener.end);
+      if (!closesOnSameLine) {
+        activeBlockCommentEnd = opener.end;
+      }
+      return;
+    }
+
+    if (isCommentLine(lineText)) return;
+
+    for (const pattern of patterns) {
+      const matches = lineText.match(pattern.regex);
+      if (!matches) continue;
+
+      findings.push({
+        file,
+        line: index + 1,
+        rule: pattern.name,
+        match: matches.map(maskSecret),
+        preview: maskLine(lineText, matches),
+      });
+    }
+  });
+
+  return findings;
+}
+
+function getExtension(file) {
+  const basename = path.basename(file);
+  if (basename === ".env" || basename.startsWith(".env.")) {
+    return ".env";
+  }
+  return path.extname(basename).toLowerCase();
+}
+
+export async function findSecrets(files, rootPath) {
+  // Gate 1 — extension/filename check
+  const matchingExtension = files.filter(
+    (file) =>
+      ALLOWED_EXTENSIONS.has(getExtension(file)) ||
+      ALLOWED_FILENAMES.has(path.basename(file)),
+  );
+
+  // Gate 2 — size check
+  const sizeChecked = await Promise.all(
+    matchingExtension.map(async (file) => {
+      try {
+        const stat = await fs.stat(path.join(rootPath, file));
+        return stat.isFile() && stat.size <= MAX_FILE_SIZE ? file : null;
+      } catch {
+        return null;
+      }
+    }),
+  );
+  const withinSizeLimit = sizeChecked.filter(Boolean);
+
+  // Gate 3 — binary sniff (first 512 bytes, null-byte heuristic)
+  const binaryChecked = await Promise.all(
+    withinSizeLimit.map(async (file) => {
+      try {
+        const binary = await isBinaryFile(path.join(rootPath, file));
+        return binary ? null : file;
+      } catch {
+        return null;
+      }
+    }),
+  );
+
+  const findings = await Promise.all(
+    binaryChecked.map(async (file) => {
+      try {
+        const content = await fs.readFile(path.join(rootPath, file), "utf8");
+        return scanContent(content, file);
+      } catch {
+        return [];
+      }
+    }),
+  );
+
+  return findings.flat();
+}

package/src/sensitive-files.js

@@ -0,0 +1,32 @@
+import mm from "micromatch";
+
+const SENSITIVE_PATTERNS = [
+  ".env",
+  ".env.*",
+  "**/.env",
+  "**/.env.*",
+  "*.pem",
+  "*.key",
+  "id_rsa*",
+  "id_ed25519*",
+  "credentials.json",
+  "**/credentials.json",
+  "*.p12",
+  "*.pfx",
+  ".npmrc",
+  "**/.aws/credentials",
+  "**/.aws/config",
+  "*.keystore",
+  "secrets.*",
+  "**/secrets.*",
+  "**/supabase/.temp/**",
+];
+
+export function findSensitiveFiles(files) {
+  return files
+    .filter((file) => mm.isMatch(file, SENSITIVE_PATTERNS, { dot: true }))
+    .map((file) => ({
+      file,
+      reason: "matched sensitive filename pattern",
+    }));
+}