redosray 1.0.0

package/src/cli.js

@@ -0,0 +1,228 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { scanPaths } = require('./scanFiles');
+const { scanRegex } = require('./scan');
+
+const VERSION = require('../package.json').version;
+
+const HELP = `redosray — find ReDoS-vulnerable regexes and prove them, offline.
+
+USAGE
+  redosray [paths...]            scan files/directories for vulnerable regexes
+  redosray -e '<regex>'          test a single regex pattern
+  cat file | redosray -e -       read the regex from stdin
+
+OPTIONS
+  -e, --regex <pat>   test one regex instead of scanning paths ('-' = stdin)
+  -f, --flags <fl>    regex flags for -e mode (e.g. i, gm)
+      --json          machine-readable JSON output
+      --ci            exit non-zero (2) if any vulnerability is confirmed
+      --timeout <ms>  per-match hang threshold (default 1000)
+      --no-color      disable ANSI colors
+  -h, --help          show this help
+  -v, --version       show version
+
+Every reported vulnerability is a REAL measured hang: redosray finds candidate
+patterns statically, then confirms each by timing a match against a growing
+input inside an isolated worker. The smallest input that crosses the timeout is
+printed as shareable proof — no false-positive claims.
+
+Maintained by the AI agent "Aurelio Nakamura". MIT licensed.
+`;
+
+function parseArgs(argv) {
+  const opts = {
+    paths: [], regex: null, flags: '', json: false, ci: false,
+    timeoutMs: 1000, color: true, help: false, version: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    switch (a) {
+      case '-h': case '--help': opts.help = true; break;
+      case '-v': case '--version': opts.version = true; break;
+      case '--json': opts.json = true; break;
+      case '--ci': opts.ci = true; break;
+      case '--no-color': opts.color = false; break;
+      case '-e': case '--regex': opts.regex = argv[++i]; break;
+      case '-f': case '--flags': opts.flags = argv[++i] || ''; break;
+      case '--timeout': opts.timeoutMs = parseInt(argv[++i], 10) || 1000; break;
+      default:
+        if (a.startsWith('-') && a !== '-') {
+          process.stderr.write(`redosray: unknown option ${a}\n`);
+          process.exitCode = 2;
+          opts._error = true;
+        } else {
+          opts.paths.push(a);
+        }
+    }
+  }
+  return opts;
+}
+
+// --- minimal ANSI helpers ---
+function mkColor(enabled) {
+  const wrap = (code) => (s) => (enabled ? `\u001b[${code}m${s}\u001b[0m` : String(s));
+  return {
+    red: wrap('31'), yellow: wrap('33'), green: wrap('32'),
+    cyan: wrap('36'), gray: wrap('90'), bold: wrap('1'), magenta: wrap('35'),
+  };
+}
+
+function fmtMs(ms) {
+  if (ms >= 1000) return `${(ms / 1000).toFixed(2)}s`;
+  return `${Math.round(ms)}ms`;
+}
+
+function truncate(s, n) {
+  if (s.length <= n) return s;
+  return s.slice(0, n - 1) + '…';
+}
+
+// A tiny sparkline of the timing curve (samples: [{length, ms, timedOut}]).
+function sparkline(samples) {
+  const bars = '▁▂▃▄▅▆▇█';
+  const vals = samples.map((s) => s.timedOut ? Infinity : s.ms);
+  const finite = vals.filter((v) => Number.isFinite(v));
+  const max = finite.length ? Math.max(...finite, 1) : 1;
+  return vals.map((v) => (v === Infinity ? '█' : bars[Math.min(bars.length - 1, Math.floor((v / max) * (bars.length - 1)))])).join('');
+}
+
+function describeInput(proof) {
+  // Show the proof input compactly: collapse long runs.
+  const input = proof.input;
+  if (input.length <= 60) return JSON.stringify(input);
+  return `${JSON.stringify(input.slice(0, 40))} … (${input.length} chars)`;
+}
+
+function printFinding(c, f, index) {
+  const tag = f.complexity === 'exponential'
+    ? c.red(c.bold(' EXPONENTIAL '))
+    : c.yellow(c.bold(' POLYNOMIAL '));
+  const kind = c.gray(`(${f.kind})`);
+  const out = [];
+  out.push(`${c.bold(`#${index}`)} ${tag} ${kind}`);
+  out.push(`  ${c.cyan('/' + f.source + '/' + f.flags)}`);
+  if (f.locations && f.locations.length) {
+    const shown = f.locations.slice(0, 5);
+    for (const loc of shown) {
+      out.push(`  ${c.gray('at')} ${loc.file}:${loc.line}:${loc.column}`);
+    }
+    if (f.locations.length > shown.length) {
+      out.push(c.gray(`  … +${f.locations.length - shown.length} more location(s)`));
+    }
+  }
+  if (f.proof) {
+    const last = f.samples && f.samples.length ? f.samples[f.samples.length - 1] : null;
+    out.push(`  ${c.magenta('proof')} input ${describeInput(f.proof)}`);
+    out.push(`        ${f.proof.length} chars → hung past ${f.proof.timeoutMs}ms` +
+      (last && last.timedOut ? c.gray(` (${last.ms >= f.proof.timeoutMs ? '≥' : ''}${fmtMs(last.ms)})`) : ''));
+    if (f.samples && f.samples.length > 1) {
+      out.push(`  ${c.gray('curve')} ${sparkline(f.samples)} ${c.gray(`${f.samples[0].length}→${f.samples[f.samples.length - 1].length} chars`)}`);
+    }
+  }
+  return out.join('\n');
+}
+
+async function runSingle(opts, c) {
+  let source = opts.regex;
+  if (source === '-') {
+    source = fs.readFileSync(0, 'utf8').trim();
+  }
+  // Allow the user to paste /pattern/flags form too.
+  let flags = opts.flags;
+  const m = /^\/(.*)\/([a-z]*)$/s.exec(source);
+  if (m) { source = m[1]; if (!flags) flags = m[2]; }
+
+  let res;
+  try {
+    res = await scanRegex(source, flags, { timeoutMs: opts.timeoutMs });
+  } catch (e) {
+    if (opts.json) { process.stdout.write(JSON.stringify({ error: String(e.message || e) }) + '\n'); }
+    else process.stderr.write(c.red(`redosray: could not analyze regex: ${e.message || e}\n`));
+    return 2;
+  }
+
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(res, null, 2) + '\n');
+    return res.vulnerable && opts.ci ? 2 : 0;
+  }
+
+  if (!res.vulnerable) {
+    process.stdout.write(`${c.green('✓ safe')} ${c.cyan('/' + source + '/' + flags)} ${c.gray(`— ${res.candidates} candidate(s), no hang up to the tested bound`)}\n`);
+    return 0;
+  }
+  const finding = {
+    source, flags, complexity: res.complexity, kind: res.kind,
+    proof: res.proof, samples: res.samples, locations: [],
+  };
+  process.stdout.write(printFinding(c, finding, 1) + '\n');
+  return opts.ci ? 2 : 0;
+}
+
+async function runScan(opts, c) {
+  const roots = opts.paths.length ? opts.paths : ['.'];
+  for (const r of roots) {
+    if (!fs.existsSync(r)) {
+      process.stderr.write(c.red(`redosray: path not found: ${r}\n`));
+      return 2;
+    }
+  }
+
+  const isTTY = process.stderr.isTTY;
+  const report = await scanPaths(roots, {
+    timeoutMs: opts.timeoutMs,
+    onProgress: opts.json ? undefined : ({ index, total }) => {
+      if (isTTY) process.stderr.write(`\r${c.gray(`scanning regex ${index}/${total}…`)}\u001b[K`);
+    },
+  });
+  if (!opts.json && isTTY) process.stderr.write('\r\u001b[K');
+
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+    return report.vulnerable && opts.ci ? 2 : 0;
+  }
+
+  const head = `${c.gray('scanned')} ${report.filesScanned} file(s), ` +
+    `${report.distinctRegexes} distinct regex(es)`;
+  process.stdout.write(head + '\n');
+
+  if (report.vulnerable === 0) {
+    process.stdout.write(c.green('✓ no ReDoS-vulnerable regexes confirmed\n'));
+    return 0;
+  }
+
+  process.stdout.write('\n');
+  report.findings.forEach((f, i) => {
+    process.stdout.write(printFinding(c, f, i + 1) + '\n\n');
+  });
+
+  const exp = report.findings.filter((f) => f.complexity === 'exponential').length;
+  const poly = report.findings.length - exp;
+  process.stdout.write(
+    c.bold(`${report.vulnerable} vulnerable regex(es): `) +
+    `${c.red(`${exp} exponential`)}, ${c.yellow(`${poly} polynomial`)}\n`,
+  );
+  return opts.ci ? 2 : 0;
+}
+
+async function main(argv) {
+  const opts = parseArgs(argv);
+  const c = mkColor(opts.color && process.stdout.isTTY && !process.env.NO_COLOR);
+  if (opts._error) return 2;
+  if (opts.help) { process.stdout.write(HELP); return 0; }
+  if (opts.version) { process.stdout.write(`redosray ${VERSION}\n`); return 0; }
+
+  if (opts.regex !== null) return runSingle(opts, c);
+  return runScan(opts, c);
+}
+
+module.exports = { main, parseArgs, sparkline };
+
+if (require.main === module) {
+  main(process.argv.slice(2)).then((code) => { process.exit(code || 0); }).catch((e) => {
+    process.stderr.write(`redosray: ${e && e.stack || e}\n`);
+    process.exit(1);
+  });
+}

package/src/confirm.js

@@ -0,0 +1,64 @@
+'use strict';
+const path = require('node:path');
+const { Worker } = require('node:worker_threads');
+
+const WORKER = path.join(__dirname, 'worker.js');
+
+/**
+ * Run one regex match against `input` in an isolated worker, timing it and
+ * killing it if it exceeds `timeoutMs`. A timeout is itself the signal that the
+ * regex catastrophically backtracks on that input.
+ * @returns {Promise<{timedOut:boolean, ms:number, matched:boolean}>}
+ */
+function timeMatch(source, flags, input, timeoutMs) {
+  return new Promise((resolve) => {
+    const w = new Worker(WORKER, { workerData: { source, flags, input } });
+    const start = Date.now();
+    const timer = setTimeout(() => {
+      w.terminate();
+      resolve({ timedOut: true, ms: Date.now() - start, matched: false });
+    }, timeoutMs);
+    w.once('message', (m) => {
+      clearTimeout(timer);
+      w.terminate();
+      resolve({ timedOut: false, ms: m.ns / 1e6, matched: m.matched });
+    });
+    w.once('error', () => {
+      clearTimeout(timer);
+      resolve({ timedOut: false, ms: Date.now() - start, matched: false, error: true });
+    });
+  });
+}
+
+/**
+ * Dynamically CONFIRM a ReDoS by feeding the regex an attack string of growing
+ * size and watching for super-linear blow-up. Returns the smallest input that
+ * pushed match time past `timeoutMs` (the shareable "proof"), or null if the
+ * regex stayed fast at every size (no confirmed vulnerability).
+ *
+ * @param attack {{prefix?:string, pump:string, suffix?:string}}
+ */
+async function confirm(source, flags, attack, opts = {}) {
+  const timeoutMs = opts.timeoutMs ?? 1000;
+  const maxPumps = opts.maxPumps ?? 100000;
+  const prefix = attack.prefix ?? '';
+  const suffix = attack.suffix ?? '';
+  const samples = [];
+  // Grow geometrically so exponential blow-up is caught in a handful of steps
+  // and polynomial blow-up within a few dozen.
+  for (let n = 10; n <= maxPumps; n = Math.ceil(n * 1.6)) {
+    const input = prefix + attack.pump.repeat(n) + suffix;
+    const r = await timeMatch(source, flags, input, timeoutMs);
+    samples.push({ pumps: n, length: input.length, ms: r.ms, timedOut: r.timedOut });
+    if (r.timedOut) {
+      return {
+        vulnerable: true,
+        proof: { input, pumps: n, length: input.length, timeoutMs },
+        samples,
+      };
+    }
+  }
+  return { vulnerable: false, samples };
+}
+
+module.exports = { timeMatch, confirm };

package/src/extract.js

@@ -0,0 +1,228 @@
+'use strict';
+
+/**
+ * Extract regex literals from source code, dependency-free, language-aware.
+ *
+ * The goal is NOT a full parser: it is to reliably find regex *sources* to feed
+ * the analyzer, with file:line:column, while avoiding obvious false extractions
+ * (division operators, comments, strings). We keep this conservative: it is fine
+ * to miss an odd construction (false negative) but we must not mis-slice code
+ * into a bogus "regex" that then wastes a dynamic confirmation.
+ *
+ * Supported:
+ *   - JS/TS/JSX/TSX: `/pattern/flags` literals + `new RegExp("...", "flags")`
+ *   - Python:        `re.compile("...")`, `re.match/search/fullmatch/... ("...")`
+ * Returns array of { source, flags, line, column, raw, kind } (kind = 'literal'|'ctor').
+ */
+
+const JS_EXT = new Set(['.js', '.mjs', '.cjs', '.jsx', '.ts', '.tsx', '.mts', '.cts']);
+const PY_EXT = new Set(['.py', '.pyi']);
+
+function extForPath(p) {
+  const m = /(\.[^.\/\\]+)$/.exec(p);
+  return m ? m[1].toLowerCase() : '';
+}
+
+function languageForPath(p) {
+  const ext = extForPath(p);
+  if (JS_EXT.has(ext)) return 'js';
+  if (PY_EXT.has(ext)) return 'py';
+  return null;
+}
+
+// Precompute line-start offsets so we can map an index -> {line, column}.
+function lineIndexer(text) {
+  const starts = [0];
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] === '\n') starts.push(i + 1);
+  }
+  return function at(index) {
+    // binary search for the greatest start <= index
+    let lo = 0, hi = starts.length - 1;
+    while (lo < hi) {
+      const mid = (lo + hi + 1) >> 1;
+      if (starts[mid] <= index) lo = mid; else hi = mid - 1;
+    }
+    return { line: lo + 1, column: index - starts[lo] + 1 };
+  };
+}
+
+/**
+ * A tiny JS tokenizing scanner that walks the source char-by-char, tracking
+ * whether we are inside a string / template / comment, so that a `/` is only
+ * treated as a regex start when the previous significant token allows it.
+ */
+function scanJs(text) {
+  const out = [];
+  const n = text.length;
+  let i = 0;
+  // Track the last significant (non-space, non-comment) character to decide if
+  // a `/` begins a regex (after operators, `(`, `,`, `=`, `:`, `[`, `!`, `&`,
+  // `|`, `?`, `{`, `;`, `return`, etc.) versus division (after value/ident/`)`).
+  let prevSig = '';
+  let prevWord = '';
+
+  const regexAllowedAfter = new Set([
+    '', '(', ',', '=', ':', '[', '!', '&', '|', '?', '{', ';', '+', '-', '*',
+    '%', '<', '>', '^', '~', '}', 'return',
+  ]);
+
+  function isRegexStart() {
+    if (regexAllowedAfter.has(prevSig)) return true;
+    if (/^(return|typeof|instanceof|in|of|new|do|else|yield|await|case|void|delete)$/.test(prevWord)) return true;
+    return false;
+  }
+
+  while (i < n) {
+    const c = text[i];
+    // line comment
+    if (c === '/' && text[i + 1] === '/') {
+      i += 2;
+      while (i < n && text[i] !== '\n') i++;
+      continue;
+    }
+    // block comment
+    if (c === '/' && text[i + 1] === '*') {
+      i += 2;
+      while (i < n && !(text[i] === '*' && text[i + 1] === '/')) i++;
+      i += 2;
+      continue;
+    }
+    // strings
+    if (c === '"' || c === "'" || c === '`') {
+      const quote = c;
+      i++;
+      while (i < n) {
+        if (text[i] === '\\') { i += 2; continue; }
+        if (text[i] === quote) { i++; break; }
+        // naive template handling: skip ${...} not needed for our purpose
+        i++;
+      }
+      prevSig = 'str'; prevWord = '';
+      continue;
+    }
+    // regex literal
+    if (c === '/' && isRegexStart()) {
+      const start = i;
+      i++;
+      let inClass = false;
+      let ok = false;
+      let body = '';
+      while (i < n) {
+        const d = text[i];
+        if (d === '\\') { body += d + (text[i + 1] || ''); i += 2; continue; }
+        if (d === '\n') break; // unterminated -> not a regex
+        if (d === '[') inClass = true;
+        else if (d === ']') inClass = false;
+        else if (d === '/' && !inClass) { ok = true; break; }
+        body += d;
+        i++;
+      }
+      if (ok) {
+        i++; // consume closing /
+        let flags = '';
+        while (i < n && /[a-z]/i.test(text[i])) { flags += text[i]; i++; }
+        // ignore trivially-empty or clearly-not-regex bodies
+        if (body.length > 0) {
+          out.push({ index: start, source: body, flags, raw: '/' + body + '/' + flags, kind: 'literal' });
+        }
+        prevSig = 'regex'; prevWord = '';
+        continue;
+      } else {
+        // treat as division
+        i = start + 1;
+        prevSig = '/'; prevWord = '';
+        continue;
+      }
+    }
+    // new RegExp("...", "flags")  /  RegExp('...')
+    if ((c === 'R') && /RegExp/.test(text.slice(i, i + 6)) && /\bRegExp$/.test(text.slice(0, i + 6))) {
+      // fallthrough to word handling below; ctor handled by regex on whole text later
+    }
+    // identifiers / words
+    if (/[A-Za-z_$]/.test(c)) {
+      let w = '';
+      const s = i;
+      while (i < n && /[A-Za-z0-9_$]/.test(text[i])) { w += text[i]; i++; }
+      prevWord = w; prevSig = 'ident';
+      continue;
+    }
+    // whitespace
+    if (/\s/.test(c)) { i++; continue; }
+    // any other single significant char
+    prevSig = c; prevWord = '';
+    i++;
+  }
+  return out;
+}
+
+// new RegExp("src" [, "flags"]) — string-literal args only (dynamic args are
+// out of scope; we cannot statically know their value).
+function scanCtorArgs(text, ctorRe) {
+  const out = [];
+  let m;
+  const re = new RegExp(ctorRe.source, 'g');
+  while ((m = re.exec(text)) !== null) {
+    const quote = m[1];
+    let raw = m[2];
+    const flags = m[4] || '';
+    // Unescape the string-literal one level so it becomes a real regex source.
+    let source;
+    try {
+      source = quote === '`'
+        ? raw
+        : JSON.parse('"' + raw.replace(/\\'/g, "'").replace(/"/g, '\\"') + '"');
+    } catch {
+      source = raw.replace(/\\(.)/g, '$1');
+    }
+    if (source && source.length > 0) {
+      out.push({ index: m.index, source, flags, raw: m[0], kind: 'ctor' });
+    }
+  }
+  return out;
+}
+
+function extractJs(text) {
+  const found = scanJs(text);
+  // new RegExp("...", "...") — allow single/double/backtick quotes
+  const ctorRe = /\bRegExp\s*\(\s*(["'`])((?:\\.|(?!\1).)*)\1\s*(?:,\s*(["'`])([a-z]*)\3\s*)?\)/;
+  return found.concat(scanCtorArgs(text, ctorRe));
+}
+
+function extractPy(text) {
+  // re.compile(r"...") / re.match(r'...') / re.search("...") etc.
+  const reCall = /\bre\.(?:compile|match|search|fullmatch|findall|finditer|sub|subn|split)\s*\(\s*(r?)(["'])((?:\\.|(?!\2).)*)\2/g;
+  const out = [];
+  let m;
+  while ((m = reCall.exec(text)) !== null) {
+    const rawFlag = m[1];
+    const body = m[3];
+    let source = body;
+    if (!rawFlag) {
+      // non-raw string: collapse one level of Python escapes for regex meaning
+      source = body.replace(/\\(.)/g, (mm, ch) => (ch === '\\' ? '\\\\' : '\\' + ch));
+    }
+    if (source && source.length > 0) {
+      out.push({ index: m.index, source, flags: '', raw: m[0], kind: 'ctor' });
+    }
+  }
+  return out;
+}
+
+/**
+ * Extract regex sources from a file's text.
+ * @param {string} text  file contents
+ * @param {string} path  file path (used for language detection)
+ * @returns {Array<{source,flags,line,column,raw,kind}>}
+ */
+function extractFromText(text, path) {
+  const lang = languageForPath(path) || 'js';
+  const raw = lang === 'py' ? extractPy(text) : extractJs(text);
+  const at = lineIndexer(text);
+  return raw.map((r) => {
+    const pos = at(r.index);
+    return { source: r.source, flags: r.flags, line: pos.line, column: pos.column, raw: r.raw, kind: r.kind };
+  });
+}
+
+module.exports = { extractFromText, languageForPath, JS_EXT, PY_EXT };

package/src/index.js

@@ -0,0 +1,20 @@
+'use strict';
+// Public library API for redosray.
+const { scanRegex } = require('./scan');
+const { findCandidates, shapeOf } = require('./analyze');
+const { parse } = require('./parser');
+const { confirm, timeMatch } = require('./confirm');
+const { scanPaths, collectFiles } = require('./scanFiles');
+const { extractFromText } = require('./extract');
+
+module.exports = {
+  scanRegex,      // async: static candidates + dynamic confirmation -> proof
+  scanPaths,      // async: scan files/dirs for vulnerable regexes -> report
+  collectFiles,   // list scannable source files under roots
+  extractFromText,// pull regex literals (+file position) from source text
+  findCandidates, // static only: list attack candidates
+  parse,          // regex -> AST
+  shapeOf,        // AST -> source-ish string
+  confirm,        // dynamic confirmation of one attack
+  timeMatch,      // time a single regex match in an isolated worker
+};