@getfootgun/footgun 0.0.0-stage → 0.2.0

package/lib/pack.mjs

@@ -0,0 +1,127 @@
+// Downloads, caches and validates the Footgun rule pack. Only the pack request leaves the machine.
+import { createHash, randomBytes } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { ruleProblems } from "./rules.mjs";
+
+export class NoRulesError extends Error {
+  constructor() { super("Could not download Footgun rules and no cached copy exists."); this.name = "NoRulesError"; }
+}
+
+export function defaultCacheDir() { return join(homedir(), ".footgun"); }
+
+// The key itself never reaches disk: a keyed pack is cached under a short hash of it.
+function cacheFile(cacheDir, key) {
+  return join(cacheDir, key ? `rules-${createHash("sha256").update(key).digest("hex").slice(0, 12)}.json` : "rules.json");
+}
+
+function isPack(p) {
+  return !!p && typeof p === "object" && typeof p.version === "string" && Array.isArray(p.rules);
+}
+
+function readCache(file) {
+  try {
+    const c = JSON.parse(readFileSync(file, "utf8"));
+    return c && typeof c.fetchedAt === "string" && isPack(c.pack) ? c : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(cacheDir, file, pack) {
+  try {
+    mkdirSync(cacheDir, { recursive: true, mode: 0o700 });
+    const tmp = `${file}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+    try {
+      writeFileSync(tmp, JSON.stringify({ fetchedAt: new Date().toISOString(), pack }), { mode: 0o600 });
+      renameSync(tmp, file);
+    } catch (e) {
+      rmSync(tmp, { force: true });
+      throw e;
+    }
+  } catch {
+    // a cache we cannot write only costs the offline fallback next time
+  }
+}
+
+// Drops rules whose detect patterns are unsafe or malformed. scanProject checks the rest of the shape.
+function validate(raw) {
+  const rules = [];
+  const skippedRules = [];
+  for (const rule of raw.rules) {
+    const id = rule && typeof rule.id === "string" && rule.id ? rule.id : "(unknown)";
+    let why = null;
+    try {
+      if (!rule || typeof rule !== "object" || Array.isArray(rule)) why = "rule must be an object";
+      else if (!Array.isArray(rule.detect)) why = "detect must be a list";
+      else {
+        const problems = [...new Set(rule.detect.flatMap((d) => ruleProblems(d)))];
+        if (problems.length) why = problems.join("; ");
+      }
+    } catch {
+      why = "rule could not be read";
+    }
+    if (why) skippedRules.push({ id, why });
+    else rules.push(rule);
+  }
+  return { version: raw.version, generatedAt: typeof raw.generatedAt === "string" ? raw.generatedAt : null, rules, skippedRules };
+}
+
+/**
+ * Returns { pack: { version, generatedAt, rules, skippedRules, cachedAt }, fromCache }.
+ * fromCache is true only when the download failed and the last cached pack was used.
+ */
+export async function loadPack({ url, key, cacheDir = defaultCacheDir(), timeoutMs = 5000 }) {
+  const file = cacheFile(cacheDir, key);
+  const cached = readCache(file);
+  const headers = { accept: "application/json" };
+  if (key) headers.authorization = `Bearer ${key}`;
+  if (cached) headers["if-none-match"] = `"${cached.pack.version}"`;
+  try {
+    const signal = AbortSignal.timeout(timeoutMs);
+    const r = await fetch(`${url.replace(/\/+$/, "")}/api/v1/rules`, { headers, signal });
+    if (r.status === 304 && cached) {
+      writeCache(cacheDir, file, cached.pack);
+      return { pack: { ...validate(cached.pack), cachedAt: null }, fromCache: false };
+    }
+    if (!r.ok) throw new Error(`rule pack request failed: ${r.status}`);
+    const body = await r.json();
+    if (!isPack(body)) throw new Error("rule pack has the wrong shape");
+    writeCache(cacheDir, file, body);
+    return { pack: { ...validate(body), cachedAt: null }, fromCache: false };
+  } catch {
+    if (!cached) throw new NoRulesError();
+    return { pack: { ...validate(cached.pack), cachedAt: cached.fetchedAt }, fromCache: true };
+  }
+}
+
+const SEVERITY_KEY = { breaks: "breaks", "will-break": "willBreak", silent: "silent", cost: "cost" };
+
+/** Finding counts by severity for the usage ping. Manual "check yourself" findings count under their severity. */
+export function pingCounts(findings) {
+  const counts = { breaks: 0, willBreak: 0, silent: 0, cost: 0 };
+  for (const f of findings) {
+    const k = SEVERITY_KEY[f?.severity];
+    if (k) counts[k] = Math.min(counts[k] + 1, 10000);
+  }
+  return counts;
+}
+
+/**
+ * Anonymous usage ping: the kind of run, whether Node was found and finding counts by severity. Nothing else.
+ * Skipped when FOOTGUN_SHARE is "false". Never throws, never prints, and gives up after timeoutMs.
+ */
+export async function sendPing({ url, kind, counts, nodeFound = true, timeoutMs = 2000 }) {
+  if (process.env.FOOTGUN_SHARE === "false") return;
+  try {
+    await fetch(`${url.replace(/\/+$/, "")}/api/v1/ping`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ kind, nodeFound, counts }),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch {
+    // a ping that fails costs nothing
+  }
+}

package/lib/report.mjs

@@ -0,0 +1,49 @@
+// Text and JSON output for `footgun scan`. Every server-supplied string goes through clean().
+import { clean } from "./clean.mjs";
+
+const GROUPS = [
+  ["breaks", "Breaks now"],
+  ["will-break", "Will break"],
+  ["silent", "Wrong results with no error"],
+  ["cost", "Costs money"],
+];
+
+/** Severities that trip `--fail-on`. Check-yourself items never do. */
+export const FAIL_ON = { breaks: ["breaks"], "will-break": ["breaks", "will-break"] };
+
+export function failed(findings, failOn) {
+  if (!failOn) return false;
+  return findings.some((f) => !f.manual && FAIL_ON[failOn].includes(f.severity));
+}
+
+function details(f) {
+  const out = [`  Fix: ${clean(f.fix)}`];
+  if (f.deadline) out.push(`  Deadline: ${clean(f.deadline)}`);
+  if (f.url) out.push(`  ${clean(f.url)}`);
+  return out;
+}
+
+export function textReport(findings) {
+  if (!findings.length) return "No known traps found.";
+  const found = findings.filter((f) => !f.manual);
+  const manual = findings.filter((f) => f.manual);
+  const out = [];
+  for (const [sev, heading] of GROUPS) {
+    const group = found.filter((f) => f.severity === sev);
+    if (!group.length) continue;
+    out.push(`${heading}:`, "");
+    for (const f of group) out.push(`${clean(f.file)}:${f.line}  ${clean(f.title)}`, ...details(f), "");
+  }
+  if (manual.length) {
+    out.push("Check these yourself:", "");
+    for (const f of manual) out.push(clean(f.title), ...details(f), "");
+  }
+  const now = found.filter((f) => f.severity === "breaks").length;
+  const dated = found.filter((f) => f.deadline).length;
+  out.push(`${found.length} ${found.length === 1 ? "problem" : "problems"} (${now} break now, ${dated} with a deadline)`);
+  return out.join("\n");
+}
+
+export function jsonReport({ findings, skippedRules, fromCache, version }) {
+  return JSON.stringify({ version, fromCache, findings, skippedRules }, null, 2);
+}

package/lib/rules.d.ts

@@ -0,0 +1,18 @@
+export type PackageRef = {
+  ecosystem: "npm" | "pypi" | "github-action" | "service";
+  name: string;
+  range: string;
+};
+
+export type DetectRule = {
+  files: string[];
+  pattern: string;
+  unless?: string;
+};
+
+/** Empty array means the rule is safe to run. */
+export function ruleProblems(rule: DetectRule): string[];
+/** Paths are forward-slash and relative. Supports **, *, ? and {a,b}. */
+export function globMatch(glob: string, relPath: string): boolean;
+/** 1-based line numbers of matches; [] when not applicable. */
+export function matchRule(rule: DetectRule, relPath: string, text: string): number[];

package/lib/rules.mjs

@@ -0,0 +1,149 @@
+// Shared trap-rule matcher. Dependency-free; used by the scanner and the rule gate.
+// Rules must stay RE2-compatible: no backreferences, no lookarounds, no nested quantifiers.
+
+const MAX_PATTERN = 300;
+const MAX_LINE = 2000;
+const MAX_GLOB = 200;
+const MAX_GLOB_STARS = 6;
+
+function scanPattern(src) {
+  const problems = [];
+  const groups = []; // each entry: { quant: has an unbounded/ranged quantifier inside, alt: has a top-level | }
+  const rangeAt = (i) => /^\{\d+,\d*\}/.exec(src.slice(i));
+  let inClass = false;
+  for (let i = 0; i < src.length; i++) {
+    const c = src[i];
+    if (c === "\\") {
+      const n = src[i + 1];
+      if (!inClass && n && ((n >= "1" && n <= "9") || (n === "k" && src[i + 2] === "<"))) {
+        problems.push("backreferences are not allowed");
+      }
+      i++;
+      continue;
+    }
+    if (inClass) {
+      if (c === "]") inClass = false;
+      continue;
+    }
+    if (c === "[") { inClass = true; continue; }
+    if (c === "(") {
+      if (src[i + 1] === "?" && (src[i + 2] === "=" || src[i + 2] === "!" ||
+          (src[i + 2] === "<" && (src[i + 3] === "=" || src[i + 3] === "!")))) {
+        problems.push("lookarounds are not allowed");
+      }
+      groups.push({ quant: false, alt: false });
+      continue;
+    }
+    if (c === "*" || c === "+") {
+      if (groups.length) groups[groups.length - 1].quant = true;
+      continue;
+    }
+    if (c === "{") {
+      const m = rangeAt(i);
+      if (m) {
+        if (groups.length) groups[groups.length - 1].quant = true;
+        i += m[0].length - 1;
+      }
+      continue;
+    }
+    if (c === "|") {
+      if (groups.length) groups[groups.length - 1].alt = true;
+      continue;
+    }
+    if (c === ")") {
+      const g = groups.pop();
+      const next = src[i + 1];
+      const quantified = next === "*" || next === "+" || (next === "{" && rangeAt(i + 1));
+      if (g && quantified && g.quant) problems.push("nested quantifiers are not allowed");
+      if (g && quantified && g.alt) problems.push("quantified alternation is not allowed");
+      if (g && groups.length) {
+        if (g.quant) groups[groups.length - 1].quant = true;
+        if (g.alt) groups[groups.length - 1].alt = true;
+      }
+    }
+  }
+  return [...new Set(problems)];
+}
+
+export function ruleProblems(rule) {
+  const problems = [];
+  if (!rule || typeof rule !== "object") return ["rule must be an object"];
+  if (!Array.isArray(rule.files) || rule.files.length === 0 || !rule.files.every((f) => typeof f === "string" && f)) {
+    problems.push("files must be a non-empty list of globs");
+  } else if (rule.files.some((g) => g.length > MAX_GLOB || g.split("*").length - 1 > MAX_GLOB_STARS)) {
+    // glob matching runs outside the matcher's time cap, so its size is capped here
+    problems.push(`files: a glob is longer than ${MAX_GLOB} characters or has more than ${MAX_GLOB_STARS} *`);
+  }
+  for (const key of ["pattern", "unless"]) {
+    const src = rule[key];
+    if (key === "unless" && src === undefined) continue;
+    if (typeof src !== "string" || src === "") {
+      problems.push(`${key} must be a non-empty string`);
+      continue;
+    }
+    if (src.length > MAX_PATTERN) problems.push(`${key} is longer than ${MAX_PATTERN} characters`);
+    problems.push(...scanPattern(src).map((p) => `${key}: ${p}`));
+    try { new RegExp(src, "m"); } catch { problems.push(`${key} does not compile`); }
+  }
+  return problems;
+}
+
+const globCache = new Map();
+
+function globToRegExp(glob) {
+  glob = glob.replace(/(?:\*\*\/)+/g, "**/"); // **/**/ matches what **/ matches
+  let out = "";
+  let braces = 0;
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === "*") {
+      if (glob[i + 1] === "*") {
+        if (glob[i + 2] === "/") { out += "(?:.*/)?"; i += 2; } else { out += ".*"; i++; }
+      } else out += "[^/]*";
+    } else if (c === "?") out += "[^/]";
+    else if (c === "{") { out += "(?:"; braces++; }
+    else if (c === "}" && braces) { out += ")"; braces--; }
+    else if (c === "," && braces) out += "|";
+    else out += c.replace(/[.+^$()|[\]\\{}]/g, "\\$&");
+  }
+  while (braces--) out += ")";
+  return new RegExp(`^${out}$`);
+}
+
+export function globMatch(glob, relPath) {
+  let re = globCache.get(glob);
+  if (!re) { re = globToRegExp(glob); globCache.set(glob, re); }
+  return re.test(relPath);
+}
+
+const verdicts = new WeakMap();
+
+function isSafe(rule) {
+  if (!rule || typeof rule !== "object") return false;
+  let v = verdicts.get(rule);
+  if (v === undefined) {
+    try { v = ruleProblems(rule).length === 0; } catch { v = false; }
+    verdicts.set(rule, v);
+  }
+  return v;
+}
+
+export function matchRule(rule, relPath, text) {
+  if (!isSafe(rule)) return [];
+  if (!rule.files.some((g) => globMatch(g, relPath))) return [];
+  let re, unless;
+  try {
+    re = new RegExp(rule.pattern, "m");
+    unless = rule.unless ? new RegExp(rule.unless, "m") : null;
+  } catch {
+    return [];
+  }
+  if (unless && unless.test(text)) return [];
+  const hits = [];
+  const lines = text.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].length > MAX_LINE) continue;
+    if (re.test(lines[i])) hits.push(i + 1);
+  }
+  return hits;
+}

package/lib/scan-worker.mjs

@@ -0,0 +1,24 @@
+// Runs detect patterns off the main thread so a runaway regex can be stopped.
+// Before each (file, detect) pair it records the detect index and bumps a counter
+// in shared memory; the main thread watches the counter and terminates on a stall.
+
+import { parentPort, workerData } from "node:worker_threads";
+import { matchRule } from "./rules.mjs";
+
+const { detects } = workerData;
+const progress = new Int32Array(workerData.progress);
+
+parentPort.on("message", (batch) => {
+  batch.forEach((file, i) => {
+    const hits = [];
+    for (const d of file.ds) {
+      Atomics.store(progress, 1, d);
+      Atomics.add(progress, 0, 1);
+      const lines = matchRule(detects[d], file.rel, file.text);
+      if (lines.length) hits.push([d, lines]);
+    }
+    parentPort.postMessage({ i, hits });
+  });
+});
+
+parentPort.postMessage("ready");

package/lib/scan.d.ts

@@ -0,0 +1,55 @@
+import type { PackageRef, DetectRule } from "./rules.mjs";
+
+export type Severity = "breaks" | "will-break" | "silent" | "cost";
+
+export type PackRule = {
+  id: string;
+  title: string;
+  provider: string;
+  severity: Severity;
+  deadline: string | null;
+  packages: PackageRef[];
+  detect: DetectRule[];
+  checkManually: boolean;
+  fix: string;
+  url: string | null;
+  private?: boolean;
+};
+
+/** dir is relative to the scan root ("" for the root); values are resolved versions. */
+export type Manifest = {
+  dir: string;
+  npm: Record<string, string>;
+  pypi: Record<string, string>;
+  actions: Record<string, string>;
+};
+
+export type Finding = {
+  trapId: string;
+  title: string;
+  provider: string;
+  severity: Severity;
+  deadline: string | null;
+  file: string | null;
+  line: number | null;
+  fix: string;
+  url: string | null;
+  private: boolean;
+  manual: boolean;
+};
+
+export type SkippedRule = { id: string; why: string };
+
+/**
+ * A rule whose package ref the manifest at dir satisfies, hit or not. Rules with no npm, pypi or github-action refs,
+ * rules satisfied only through a broad range ("*", "", "x", "X", or any range that 0.0.0 and 999999.0.0 both satisfy) and rules skipped at run time never appear.
+ */
+export type Applicable = {
+  trapId: string;
+  package: { ecosystem: "npm" | "pypi" | "github-action"; name: string; version: string };
+  dir: string;
+};
+
+export function readManifests(root: string): Manifest[];
+/** Never rejects for a bad rule: unsafe, malformed or runaway rules land in skippedRules. */
+export function scanProject(root: string, rules: PackRule[]): Promise<{ findings: Finding[]; skippedRules: SkippedRule[]; applicable: Applicable[] }>;