ecdsa-scan 0.1.0

package/src/lib/mask.js

@@ -0,0 +1,199 @@
+// Comment masking.
+//
+// Rules match against a copy of the source in which every comment character is
+// replaced by a space. Offsets and line numbers stay identical to the original
+// file, so a match index in the masked text always points at the same place in
+// the real file — but documentation, disabled code and prose examples never
+// produce findings. String literals are left intact: many rules legitimately
+// look inside them (PEM blocks, `createSign("sha1")`, curve names).
+
+const QUOTES = new Set(['"', "'", "`"]);
+
+/** Index of the closing quote of the string starting at `i` (or end of text). */
+function skipString(text, i, { rawBacktick = false } = {}) {
+  const quote = text[i];
+  const raw = rawBacktick && quote === "`";
+  for (let j = i + 1; j < text.length; j++) {
+    const ch = text[j];
+    if (!raw && ch === "\\") {
+      j++;
+      continue;
+    }
+    if (ch === quote) return j;
+    // Unterminated single-quoted strings are a lexing dead end; stop at the
+    // newline so one stray apostrophe cannot swallow the rest of the file.
+    if (!raw && ch === "\n" && quote !== "`") return j - 1;
+  }
+  return text.length - 1;
+}
+
+// A `/` starts a regular expression (rather than division) when the previous
+// significant token cannot end an expression. Standard heuristic — good enough
+// to keep `/https:\/\//` from being mistaken for a line comment.
+const REGEX_PRECEDERS = new Set("(,=:[!&|?{};+-*%^~<>".split(""));
+const REGEX_KEYWORDS = /\b(?:return|typeof|instanceof|in|of|new|delete|void|case|do|else|yield|await)$/;
+
+function regexLiteralAllowed(text, slashIndex) {
+  let k = slashIndex - 1;
+  while (k >= 0 && /\s/.test(text[k])) k--;
+  if (k < 0) return true;
+  const prev = text[k];
+  if (REGEX_PRECEDERS.has(prev)) return true;
+  return REGEX_KEYWORDS.test(text.slice(Math.max(0, k - 12), k + 1));
+}
+
+/** Index of the closing `/` of the regex literal starting at `i`. */
+function skipRegex(text, i) {
+  let inClass = false;
+  for (let j = i + 1; j < text.length; j++) {
+    const ch = text[j];
+    if (ch === "\\") {
+      j++;
+      continue;
+    }
+    if (ch === "\n") return j - 1; // not a regex after all; bail out safely
+    if (ch === "[") inClass = true;
+    else if (ch === "]") inClass = false;
+    else if (ch === "/" && !inClass) return j;
+  }
+  return text.length - 1;
+}
+
+function blank(out, from, to) {
+  for (let i = from; i <= to && i < out.length; i++) {
+    if (out[i] !== "\n") out[i] = " ";
+  }
+}
+
+function maskCLike(text, { regexLiterals, rawBacktick }) {
+  const out = text.split("");
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (QUOTES.has(ch)) {
+      i = skipString(text, i, { rawBacktick });
+      continue;
+    }
+    if (ch === "/" && text[i + 1] === "/") {
+      let end = text.indexOf("\n", i);
+      if (end === -1) end = text.length;
+      blank(out, i, end - 1);
+      i = end;
+      continue;
+    }
+    if (ch === "/" && text[i + 1] === "*") {
+      let end = text.indexOf("*/", i + 2);
+      end = end === -1 ? text.length - 1 : end + 1;
+      blank(out, i, end);
+      i = end;
+      continue;
+    }
+    if (ch === "/" && regexLiterals && regexLiteralAllowed(text, i)) {
+      i = skipRegex(text, i);
+      continue;
+    }
+  }
+  return out.join("");
+}
+
+function maskPython(text) {
+  const out = text.split("");
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if ((ch === '"' || ch === "'") && text.slice(i, i + 3) === ch.repeat(3)) {
+      const close = text.indexOf(ch.repeat(3), i + 3);
+      i = close === -1 ? text.length : close + 2;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      i = skipString(text, i);
+      continue;
+    }
+    if (ch === "#") {
+      let end = text.indexOf("\n", i);
+      if (end === -1) end = text.length;
+      blank(out, i, end - 1);
+      i = end;
+      continue;
+    }
+  }
+  return out.join("");
+}
+
+/**
+ * Blank the *contents* of string, template and regex literals, keeping the
+ * delimiters and every offset. Rules that look for code structure (a call, a
+ * comparison, an assignment) use this view so that documentation strings, code
+ * samples and a scanner's own patterns never look like real code.
+ *
+ * Expects text whose comments are already masked.
+ */
+export function maskLiterals(code, lang) {
+  const cLike = lang === "js" || lang === "ts" || lang === "go";
+  if (!cLike && lang !== "python") return code;
+  const out = code.split("");
+  for (let i = 0; i < code.length; i++) {
+    const ch = code[i];
+    if (lang === "python" && (ch === '"' || ch === "'") && code.slice(i, i + 3) === ch.repeat(3)) {
+      const close = code.indexOf(ch.repeat(3), i + 3);
+      const end = close === -1 ? code.length - 1 : close - 1;
+      blank(out, i + 3, end);
+      i = close === -1 ? code.length : close + 2;
+      continue;
+    }
+    if (QUOTES.has(ch)) {
+      const end = skipString(code, i, { rawBacktick: lang === "go" });
+      blank(out, i + 1, end - 1);
+      i = end;
+      continue;
+    }
+    if (cLike && lang !== "go" && ch === "/" && regexLiteralAllowed(code, i)) {
+      const end = skipRegex(code, i);
+      blank(out, i + 1, end - 1);
+      i = end;
+      continue;
+    }
+  }
+  const masked = out.join("");
+  return lang === "js" || lang === "ts" ? maskJsxText(masked) : masked;
+}
+
+// Prose written as JSX children — "…the curve is P-256 or secp256k1…" — is text,
+// not code, but it carries no quotes to give it away. A run between a closing
+// `>` and the next opening `<` is treated as prose when it reads like a
+// sentence and contains nothing that could be an expression.
+const NOT_PROSE = /[=;{}]|&&|\|\||==|!=|<=|>=/;
+
+function maskJsxText(code) {
+  if (!code.includes("</")) return code;
+  const out = code.split("");
+  let i = code.indexOf(">");
+  while (i !== -1) {
+    const next = code.indexOf("<", i + 1);
+    if (next === -1) break;
+    const run = code.slice(i + 1, next);
+    const spaces = (run.match(/ /g) ?? []).length;
+    if (run.length >= 12 && spaces >= 4 && !NOT_PROSE.test(run)) {
+      blank(out, i + 1, next - 1);
+    }
+    i = code.indexOf(">", next + 1);
+  }
+  return out.join("");
+}
+
+/**
+ * Return `text` with comments blanked out. Length, newlines and every byte
+ * offset are preserved.
+ */
+export function maskComments(text, lang) {
+  switch (lang) {
+    case "js":
+    case "ts":
+      return maskCLike(text, { regexLiterals: true, rawBacktick: false });
+    case "go":
+      return maskCLike(text, { regexLiterals: false, rawBacktick: true });
+    case "python":
+      return maskPython(text);
+    default:
+      return text;
+  }
+}

package/src/lib/text.js

@@ -0,0 +1,86 @@
+// Small text helpers shared by rules: regex iteration with offsets, balanced
+// bracket scanning (so a rule can look at the whole argument list of a call,
+// even across newlines) and line windows for context checks.
+
+const CLOSERS = { "(": ")", "[": "]", "{": "}" };
+
+function skipStringFrom(text, i) {
+  const quote = text[i];
+  for (let j = i + 1; j < text.length; j++) {
+    const ch = text[j];
+    if (ch === "\\") {
+      j++;
+      continue;
+    }
+    if (ch === quote) return j;
+    if (ch === "\n" && quote !== "`") return j - 1;
+  }
+  return text.length - 1;
+}
+
+/**
+ * Scan from an opening bracket to its match, ignoring brackets inside string
+ * literals. Returns `{ start, end, inner, truncated }`.
+ */
+export function balancedSpan(text, openIndex, limit = 20000) {
+  const open = text[openIndex];
+  const close = CLOSERS[open];
+  if (!close) return { start: openIndex, end: openIndex, inner: "", truncated: true };
+  const hardEnd = Math.min(text.length, openIndex + limit);
+  let depth = 0;
+  for (let i = openIndex; i < hardEnd; i++) {
+    const ch = text[i];
+    if (ch === '"' || ch === "'" || ch === "`") {
+      i = skipStringFrom(text, i);
+      continue;
+    }
+    if (ch === open) depth++;
+    else if (ch === close) {
+      depth--;
+      if (depth === 0) {
+        return { start: openIndex, end: i, inner: text.slice(openIndex + 1, i), truncated: false };
+      }
+    }
+  }
+  return { start: openIndex, end: hardEnd - 1, inner: text.slice(openIndex + 1, hardEnd), truncated: true };
+}
+
+/** Iterate regex matches, always in global mode, yielding the match objects. */
+export function* matchAll(text, re) {
+  const rx = re.global ? new RegExp(re.source, re.flags) : new RegExp(re.source, re.flags + "g");
+  let m;
+  while ((m = rx.exec(text)) !== null) {
+    if (m[0] === "") rx.lastIndex++;
+    else yield m;
+  }
+}
+
+/** `function foo(`, `def foo(`, `func Foo(` — a definition, not a call site. */
+const DECLARATION_BEFORE = /\b(?:function|def|func|class|interface|type)\s+$/;
+
+/**
+ * Find calls whose callee matches `calleeRe`. Yields
+ * `{ index, callee, args, end }` where `args` is the raw argument text.
+ * Function declarations are skipped: defining `decodeJwt(...)` is not calling it.
+ */
+export function* findCalls(text, calleeRe) {
+  for (const m of matchAll(text, calleeRe)) {
+    let i = m.index + m[0].length;
+    while (i < text.length && /\s/.test(text[i])) i++;
+    if (text[i] !== "(") continue;
+    if (DECLARATION_BEFORE.test(text.slice(Math.max(0, m.index - 12), m.index))) continue;
+    const span = balancedSpan(text, i);
+    yield { index: m.index, callee: m[0], match: m, args: span.inner, end: span.end };
+  }
+}
+
+/** True when `re` matches anywhere in `text`. */
+export function has(text, re) {
+  return typeof re === "string" ? text.includes(re) : re.test(text);
+}
+
+/** Longest common trimmed line, used for readable snippets. */
+export function snippetAt(lines, lineNumber, maxLen = 160) {
+  const raw = (lines[lineNumber - 1] ?? "").trim();
+  return raw.length > maxLen ? `${raw.slice(0, maxLen - 1)}…` : raw;
+}

package/src/report.js

@@ -0,0 +1,298 @@
+// Output formats: human-readable terminal text, JSON, and SARIF 2.1.0 for
+// GitHub Code Scanning. No dependencies — ANSI codes are written directly.
+
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { rules as allRules } from "./rules/index.js";
+
+export const TOOL_NAME = "ecdsa-scan";
+export const TOOL_VERSION = "0.1.0";
+export const TOOL_URI = "https://ecdsa.com/scanner";
+
+const ANSI = {
+  reset: "\u001b[0m",
+  bold: "\u001b[1m",
+  dim: "\u001b[2m",
+  red: "\u001b[31m",
+  yellow: "\u001b[33m",
+  blue: "\u001b[34m",
+  cyan: "\u001b[36m",
+  green: "\u001b[32m",
+  gray: "\u001b[90m",
+};
+
+export function makeColors(enabled) {
+  const wrap = (code) => (text) => (enabled ? `${code}${text}${ANSI.reset}` : String(text));
+  return {
+    bold: wrap(ANSI.bold),
+    dim: wrap(ANSI.dim),
+    red: wrap(ANSI.red),
+    yellow: wrap(ANSI.yellow),
+    blue: wrap(ANSI.blue),
+    cyan: wrap(ANSI.cyan),
+    green: wrap(ANSI.green),
+    gray: wrap(ANSI.gray),
+  };
+}
+
+const CONFIDENCE_STYLE = {
+  confirmed: (c) => c.red("confirmed"),
+  suspected: (c) => c.yellow("suspected"),
+  advisory: (c) => c.cyan("advisory "),
+};
+
+/** Wrap `text` to `width`, indenting every line with `indent`. */
+export function wrapText(text, width, indent = "") {
+  const words = String(text).split(/\s+/).filter(Boolean);
+  const lines = [];
+  let current = "";
+  for (const word of words) {
+    if (current && current.length + 1 + word.length > width) {
+      lines.push(current);
+      current = word;
+    } else {
+      current = current ? `${current} ${word}` : word;
+    }
+  }
+  if (current) lines.push(current);
+  return lines.map((line) => indent + line).join("\n");
+}
+
+export function countBy(items, key) {
+  const out = {};
+  for (const item of items) out[item[key]] = (out[item[key]] ?? 0) + 1;
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Terminal
+// ---------------------------------------------------------------------------
+
+/**
+ * Human-readable report. The full explanation of a rule (why / fix / docs) is
+ * printed once, with the first finding it produced; later findings show only
+ * the location and the message so long scans stay readable.
+ */
+export function formatText(result, options = {}) {
+  const c = makeColors(options.color ?? false);
+  const width = Math.min(Math.max(options.width ?? 100, 60), 120);
+  const findings = result.findings;
+  const out = [];
+
+  out.push(`${c.bold("ecdsa scan")} ${c.dim("·")} ${result.root}`);
+
+  if (findings.length === 0) {
+    out.push("");
+    out.push(c.green("No findings at the requested confidence level."));
+  }
+
+  const explained = new Set();
+  let currentFile = null;
+  for (const f of findings) {
+    if (f.relPath !== currentFile) {
+      currentFile = f.relPath;
+      out.push("");
+      out.push(c.bold(currentFile));
+    }
+    const badge = (CONFIDENCE_STYLE[f.confidence] ?? ((x) => x.dim(f.confidence)))(c);
+    out.push(`  ${c.dim(`${f.line}:${f.column}`)}  ${badge}  ${c.blue(f.ruleId)}  ${f.title}`);
+    if (f.snippet) out.push(c.gray(`      │ ${f.snippet}`));
+    out.push(wrapText(f.message, width - 6, "      "));
+    if (!explained.has(f.ruleId)) {
+      explained.add(f.ruleId);
+      if (f.why) {
+        out.push(c.dim(wrapText(`Why it matters: ${f.why}`, width - 6, "      ")));
+      }
+      if (f.fix) {
+        out.push(c.dim("      Fix:"));
+        for (const line of String(f.fix).split("\n")) out.push(c.dim(`        ${line}`));
+      }
+      if (f.docs) out.push(c.dim(`      Reference: ${f.docs}`));
+    }
+    out.push("");
+  }
+
+  // Inventory
+  if (options.inventory !== false && result.inventory.length > 0) {
+    out.push(c.bold("Inventory"));
+    const groups = new Map();
+    for (const item of result.inventory) {
+      if (!groups.has(item.kind)) groups.set(item.kind, []);
+      groups.get(item.kind).push(item);
+    }
+    for (const [kind, items] of groups) {
+      const names = items.map((i) => `${i.name} ${c.dim(`(${i.files.length})`)}`).join(", ");
+      out.push(wrapText(`${kind}: ${names}`, width - 2, "  "));
+    }
+    out.push("");
+  }
+
+  const byConfidence = countBy(findings, "confidence");
+  const summary = ["confirmed", "suspected", "advisory"]
+    .filter((level) => byConfidence[level])
+    .map((level) => `${byConfidence[level]} ${level}`)
+    .join(", ");
+  out.push(
+    `${c.bold("Summary")} ${result.stats.scannedFiles} file${result.stats.scannedFiles === 1 ? "" : "s"} scanned, ${findings.length} finding${findings.length === 1 ? "" : "s"}${summary ? ` (${summary})` : ""}`
+  );
+  if (byConfidence.confirmed) {
+    out.push(c.red(`Exit code 1: ${byConfidence.confirmed} confirmed finding${byConfidence.confirmed === 1 ? "" : "s"}.`));
+  }
+  if (result.errors.length > 0) {
+    out.push(c.dim(`${result.errors.length} path(s) could not be read; run with --json to see them.`));
+  }
+  out.push(
+    c.dim("Static pattern analysis: it can miss defects and can flag correct code. Treat advisory findings as questions, not verdicts.")
+  );
+  return out.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// JSON
+// ---------------------------------------------------------------------------
+
+export function formatJson(result, options = {}) {
+  const ruleMeta = {};
+  for (const f of result.findings) {
+    if (ruleMeta[f.ruleId]) continue;
+    const rule = allRules.find((r) => r.id === f.ruleId);
+    ruleMeta[f.ruleId] = {
+      title: rule?.title ?? f.title,
+      severity: rule?.severity ?? f.severity,
+      defaultConfidence: rule?.confidence ?? f.confidence,
+      why: rule?.why,
+      fix: rule?.fix,
+      docs: rule?.docs,
+    };
+  }
+
+  const INVENTORY_SECTION = {
+    library: "libraries",
+    algorithm: "algorithms",
+    curve: "curves",
+    operation: "operations",
+  };
+  const grouped = { libraries: [], algorithms: [], curves: [], operations: [] };
+  for (const item of result.inventory) {
+    const key = INVENTORY_SECTION[item.kind] ?? `${item.kind}s`;
+    (grouped[key] ??= []).push({ name: item.name, detail: item.detail, files: item.files });
+  }
+
+  return JSON.stringify(
+    {
+      tool: { name: TOOL_NAME, version: TOOL_VERSION, informationUri: TOOL_URI },
+      scannedAt: options.now ?? new Date().toISOString(),
+      root: result.root,
+      summary: {
+        filesScanned: result.stats.scannedFiles,
+        filesSkipped: result.stats.skippedFiles,
+        findings: result.findings.length,
+        byConfidence: countBy(result.findings, "confidence"),
+        bySeverity: countBy(result.findings, "severity"),
+        byRule: countBy(result.findings, "ruleId"),
+      },
+      rules: ruleMeta,
+      findings: result.findings.map((f) => ({
+        ruleId: f.ruleId,
+        title: f.title,
+        severity: f.severity,
+        confidence: f.confidence,
+        message: f.message,
+        path: f.relPath,
+        absolutePath: f.file,
+        line: f.line,
+        column: f.column,
+        snippet: f.snippet,
+        docs: f.docs,
+      })),
+      inventory: grouped,
+      errors: result.errors,
+    },
+    null,
+    2
+  );
+}
+
+// ---------------------------------------------------------------------------
+// SARIF 2.1.0
+// ---------------------------------------------------------------------------
+
+const SARIF_LEVEL = { confirmed: "error", suspected: "warning", advisory: "note" };
+const SECURITY_SEVERITY = { high: "7.5", medium: "5.0", low: "3.0" };
+
+export function formatSarif(result) {
+  const usedRuleIds = [...new Set(result.findings.map((f) => f.ruleId))];
+  const sarifRules = usedRuleIds.map((id) => {
+    const rule = allRules.find((r) => r.id === id) ?? {};
+    return {
+      id,
+      name: id
+        .split("-")
+        .map((part) => part[0].toUpperCase() + part.slice(1))
+        .join(""),
+      shortDescription: { text: rule.title ?? id },
+      fullDescription: { text: rule.why ?? rule.title ?? id },
+      help: {
+        text: [rule.why, rule.fix ? `Fix:\n${rule.fix}` : null, rule.docs].filter(Boolean).join("\n\n"),
+        markdown: [rule.why, rule.fix ? `**Fix**\n\n\`\`\`\n${rule.fix}\n\`\`\`` : null, rule.docs ? `[Reference](${rule.docs})` : null]
+          .filter(Boolean)
+          .join("\n\n"),
+      },
+      helpUri: rule.docs ?? TOOL_URI,
+      defaultConfiguration: { level: SARIF_LEVEL[rule.confidence] ?? "warning" },
+      properties: {
+        tags: ["security", "cryptography", "signatures"],
+        precision: rule.confidence === "confirmed" ? "high" : rule.confidence === "suspected" ? "medium" : "low",
+        "security-severity": SECURITY_SEVERITY[rule.severity] ?? "5.0",
+      },
+    };
+  });
+
+  const results = result.findings.map((f) => ({
+    ruleId: f.ruleId,
+    ruleIndex: usedRuleIds.indexOf(f.ruleId),
+    level: SARIF_LEVEL[f.confidence] ?? "warning",
+    message: { text: `${f.title}: ${f.message}` },
+    locations: [
+      {
+        physicalLocation: {
+          artifactLocation: { uri: f.relPath, uriBaseId: "%SRCROOT%" },
+          region: {
+            startLine: f.line,
+            startColumn: f.column,
+            snippet: { text: f.snippet ?? "" },
+          },
+        },
+      },
+    ],
+    partialFingerprints: {
+      primaryLocationLineHash: createHash("sha256").update(`${f.ruleId}|${f.relPath}|${f.snippet}`).digest("hex").slice(0, 32),
+    },
+    properties: { confidence: f.confidence, severity: f.severity },
+  }));
+
+  const rootUri = `file://${path.resolve(result.root).split(path.sep).join("/")}/`;
+  return JSON.stringify(
+    {
+      $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+      version: "2.1.0",
+      runs: [
+        {
+          tool: {
+            driver: {
+              name: "ecdsa scan",
+              version: TOOL_VERSION,
+              informationUri: TOOL_URI,
+              rules: sarifRules,
+            },
+          },
+          originalUriBaseIds: { "%SRCROOT%": { uri: rootUri } },
+          invocations: [{ executionSuccessful: true }],
+          results,
+        },
+      ],
+    },
+    null,
+    2
+  );
+}