shercheck 0.1.0

package/bin/cli.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import path from "node:path";
+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 program = new Command();
+
+program
+  .name("shercheck")
+  .description("A tool to check the integrity of your files")
+  .version("1.0.0")
+  .argument("[path]", "project directory to scan", ".")
+  .option("--json", "output results as JSON instead of colored text")
+  .option(
+    "--fix",
+    "auto-create/update AI-ignore files for unprotected sensitive files",
+  )
+  .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,27 @@
+{
+  "name": "shercheck",
+  "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": {
+    "shercheck": "./bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "keywords": [
+    "security",
+    "secrets",
+    "ai",
+    "cursor",
+    "copilot",
+    "env",
+    "scanner",
+    "cli"
+  ],
+  "license": "MIT",
+  "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("  🔍 SHERCHECK") + 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",
+    }));
+}