ecdsa-scan 0.1.0

package/src/scan.js

@@ -0,0 +1,308 @@
+// Scan engine: walk a directory, build a FileContext per source file, run every
+// rule against it and collect findings plus the crypto inventory.
+//
+// Everything here is read-only. The scanner opens files, never writes them.
+
+import { readFile, readdir, stat } from "node:fs/promises";
+import path from "node:path";
+import { maskComments, maskLiterals } from "./lib/mask.js";
+import { compileIgnore } from "./lib/glob.js";
+import { balancedSpan, findCalls, matchAll, snippetAt } from "./lib/text.js";
+import { rules as allRules } from "./rules/index.js";
+
+export const CONFIDENCE_ORDER = { advisory: 0, suspected: 1, confirmed: 2 };
+export const CONFIDENCE_LEVELS = Object.keys(CONFIDENCE_ORDER);
+
+/** Directories that never contain first-party source worth scanning. */
+export const DEFAULT_SKIP_DIRS = new Set([
+  "node_modules",
+  ".git",
+  ".hg",
+  ".svn",
+  "dist",
+  "build",
+  "out",
+  "vendor",
+  ".next",
+  ".nuxt",
+  ".turbo",
+  ".cache",
+  "coverage",
+  "__pycache__",
+  ".venv",
+  "venv",
+  ".tox",
+  ".mypy_cache",
+  ".pytest_cache",
+  "target",
+  ".gradle",
+  ".idea",
+  ".vscode",
+]);
+
+const LANG_BY_EXT = {
+  ".js": "js",
+  ".mjs": "js",
+  ".cjs": "js",
+  ".jsx": "js",
+  ".ts": "ts",
+  ".tsx": "ts",
+  ".mts": "ts",
+  ".cts": "ts",
+  ".py": "python",
+  ".go": "go",
+  ".pem": "keyfile",
+  ".key": "keyfile",
+  ".p8": "keyfile",
+  ".pk8": "keyfile",
+  ".p12": "keyfile",
+  ".pfx": "keyfile",
+  ".jks": "keyfile",
+  ".asc": "keyfile",
+};
+
+const KEY_FILENAMES = new Set(["id_rsa", "id_dsa", "id_ecdsa", "id_ed25519", "server.key", "privkey.pem"]);
+
+const MAX_FILE_BYTES = 2 * 1024 * 1024;
+
+export function languageOf(filePath) {
+  const base = path.basename(filePath);
+  if (KEY_FILENAMES.has(base)) return "keyfile";
+  return LANG_BY_EXT[path.extname(filePath).toLowerCase()] ?? null;
+}
+
+const TEST_DIR_RE = /(^|\/)(tests?|__tests__|spec|specs|fixtures?|testdata|examples?|samples?|mocks?|__mocks__|e2e|demo|demos|docs)(\/|$)/i;
+const TEST_FILE_RE = /(\.(test|spec)\.[jt]sx?$|_test\.go$|(^|\/)test_[^/]+\.py$|[^/]+_test\.py$|\.fixture\.)/i;
+
+export function looksLikeTestPath(relPath) {
+  return TEST_DIR_RE.test(relPath) || TEST_FILE_RE.test(relPath);
+}
+
+/**
+ * Everything a rule gets to look at. `code` is the comment-masked copy — use it
+ * for almost everything; `text` is the raw file, for the few rules where a hit
+ * inside a comment still matters (a pasted private key, for example).
+ */
+export function createFileContext({ filePath, relPath, text, lang }) {
+  const code = maskComments(text, lang);
+  const structure = maskLiterals(code, lang);
+  const lines = text.split("\n");
+  const lineStarts = [0];
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] === "\n") lineStarts.push(i + 1);
+  }
+
+  function positionAt(index) {
+    let low = 0;
+    let high = lineStarts.length - 1;
+    while (low < high) {
+      const mid = (low + high + 1) >> 1;
+      if (lineStarts[mid] <= index) low = mid;
+      else high = mid - 1;
+    }
+    return { line: low + 1, column: index - lineStarts[low] + 1 };
+  }
+
+  return {
+    path: filePath,
+    relPath,
+    lang,
+    family: lang === "js" || lang === "ts" ? "jsts" : lang,
+    text,
+    code,
+    // Same as `code`, but with the contents of strings, template literals and
+    // regular expressions blanked out. Rules looking for real code structure
+    // use this so documentation and code samples do not become findings.
+    structure,
+    lines,
+    isTestPath: looksLikeTestPath(relPath),
+    positionAt,
+    lineAt: (index) => positionAt(index).line,
+    snippet: (line) => snippetAt(lines, line),
+    /** Text of the lines around `index`, for cheap context checks. */
+    window(index, before = 4, after = 4) {
+      const { line } = positionAt(index);
+      return lines.slice(Math.max(0, line - 1 - before), line + after).join("\n");
+    },
+    /** Text of the statement `index` sits in (bounded by line breaks/semicolons). */
+    lineOf(index) {
+      const { line } = positionAt(index);
+      return lines[line - 1] ?? "";
+    },
+    /**
+     * True when the character at `index` sits inside a string, template or
+     * regex literal — i.e. the match is documentation or a code sample rather
+     * than executable code. Rules use this to stay quiet on their own examples.
+     */
+    isMasked: (index) => code[index] !== " " && structure[index] === " ",
+    has: (re, source = code) => (typeof re === "string" ? source.includes(re) : re.test(source)),
+    matchAll: (re, source = code) => matchAll(source, re),
+    findCalls: (re, source = code) => findCalls(source, re),
+    balancedSpan: (index, source = code) => balancedSpan(source, index),
+  };
+}
+
+function isBinary(buffer) {
+  const limit = Math.min(buffer.length, 4096);
+  for (let i = 0; i < limit; i++) {
+    if (buffer[i] === 0) return true;
+  }
+  return false;
+}
+
+/** Recursively collect scannable files under `root`. */
+export async function collectFiles(root, { ignore, skipDirs = DEFAULT_SKIP_DIRS, followSymlinks = false } = {}) {
+  const isIgnored = ignore ?? (() => false);
+  const files = [];
+  const errors = [];
+
+  async function walk(dir) {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch (err) {
+      errors.push({ path: dir, message: err.message });
+      return;
+    }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      const rel = path.relative(root, full).split(path.sep).join("/");
+      if (isIgnored(rel)) continue;
+      if (entry.isSymbolicLink() && !followSymlinks) continue;
+      if (entry.isDirectory()) {
+        if (skipDirs.has(entry.name)) continue;
+        await walk(full);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      const lang = languageOf(full);
+      if (!lang) continue;
+      files.push({ path: full, relPath: rel, lang });
+    }
+  }
+
+  const info = await stat(root);
+  if (info.isFile()) {
+    const rel = path.basename(root);
+    const lang = languageOf(root);
+    if (lang && !isIgnored(rel)) files.push({ path: root, relPath: rel, lang });
+  } else {
+    await walk(root);
+  }
+  files.sort((a, b) => a.relPath.localeCompare(b.relPath));
+  return { files, errors };
+}
+
+function ruleAppliesTo(rule, lang) {
+  if (!rule.languages || rule.languages === "any") return true;
+  return rule.languages.includes(lang);
+}
+
+/**
+ * Run the rule set over a directory (or a single file).
+ * Returns findings sorted by file/line plus the crypto inventory.
+ */
+export async function scan(root, options = {}) {
+  const rules = options.rules ?? allRules;
+  const isIgnored = compileIgnore(options.ignore);
+  const { files, errors } = await collectFiles(root, { ignore: isIgnored });
+
+  const findings = [];
+  const inventory = new Map();
+  let scannedFiles = 0;
+  let skippedFiles = 0;
+
+  for (const file of files) {
+    let buffer;
+    try {
+      buffer = await readFile(file.path);
+    } catch (err) {
+      errors.push({ path: file.path, message: err.message });
+      continue;
+    }
+    // Key stores (.p12/.pfx) are binary but still worth reporting on, so the
+    // binary guard applies to source files only.
+    if (buffer.length > MAX_FILE_BYTES || (isBinary(buffer) && file.lang !== "keyfile")) {
+      skippedFiles++;
+      continue;
+    }
+    const ctx = createFileContext({
+      filePath: file.path,
+      relPath: file.relPath,
+      text: isBinary(buffer) ? "" : buffer.toString("utf8"),
+      lang: file.lang,
+    });
+    scannedFiles++;
+
+    for (const rule of rules) {
+      if (!ruleAppliesTo(rule, ctx.lang)) continue;
+      let produced;
+      try {
+        produced = rule.kind === "inventory" ? rule.collect(ctx) : rule.match(ctx);
+      } catch (err) {
+        errors.push({ path: file.path, message: `rule ${rule.id} failed: ${err.message}` });
+        continue;
+      }
+      if (!produced) continue;
+      if (rule.kind === "inventory") {
+        for (const item of produced) {
+          const key = `${item.kind}:${item.name}`;
+          const existing = inventory.get(key) ?? { ...item, files: new Set() };
+          existing.files.add(ctx.relPath);
+          if (item.detail && !existing.detail) existing.detail = item.detail;
+          inventory.set(key, existing);
+        }
+        continue;
+      }
+      for (const raw of produced) {
+        const position = raw.index !== undefined ? ctx.positionAt(raw.index) : { line: raw.line, column: raw.column ?? 1 };
+        findings.push({
+          ruleId: rule.id,
+          title: rule.title,
+          severity: raw.severity ?? rule.severity,
+          confidence: raw.confidence ?? rule.confidence,
+          message: raw.message,
+          note: raw.note ?? rule.note,
+          why: rule.why,
+          fix: rule.fix,
+          docs: rule.docs,
+          file: ctx.path,
+          relPath: ctx.relPath,
+          line: position.line,
+          column: position.column,
+          snippet: raw.snippet ?? ctx.snippet(position.line),
+        });
+      }
+    }
+  }
+
+  // One finding per rule/file/line/column — rules that scan both raw and masked
+  // text can otherwise report the same spot twice.
+  const seen = new Set();
+  const deduped = findings.filter((f) => {
+    const key = `${f.ruleId}|${f.relPath}|${f.line}|${f.column}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+
+  deduped.sort(
+    (a, b) => a.relPath.localeCompare(b.relPath) || a.line - b.line || a.column - b.column || a.ruleId.localeCompare(b.ruleId)
+  );
+
+  return {
+    root,
+    findings: deduped,
+    inventory: [...inventory.values()]
+      .map((item) => ({ kind: item.kind, name: item.name, detail: item.detail, files: [...item.files].sort() }))
+      .sort((a, b) => a.kind.localeCompare(b.kind) || a.name.localeCompare(b.name)),
+    stats: { scannedFiles, skippedFiles, totalCandidates: files.length },
+    errors,
+  };
+}
+
+/** Keep only findings at or above `min` confidence. */
+export function filterByConfidence(findings, min) {
+  const floor = CONFIDENCE_ORDER[min] ?? 0;
+  return findings.filter((f) => (CONFIDENCE_ORDER[f.confidence] ?? 0) >= floor);
+}