redosray 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aurelio Nakamura
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,166 @@
+# redosray
+
+**Find ReDoS-vulnerable regexes in your code — and *prove* each one, offline.**
+
+redosray scans your JavaScript / TypeScript / Python for [regular-expression
+denial-of-service](https://owasp.org/www-community/attacks/Regular_expression_Denial_of_Service_-_ReDoS)
+bugs. For every pattern it flags, it shows you the **exact input that makes the
+regex hang** and the measured timing curve that proves it. No servers, no
+network, no false-positive guesswork.
+
+```
+$ npx redosray src/
+
+#1  EXPONENTIAL  (nested-quantifier)
+  /^([a-zA-Z0-9]+)+@example\.com$/
+  at src/routes.js:2:17
+  proof input "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa!"
+        43 chars → hung past 1000ms (≥1.00s)
+  curve ▁▁██ 11→43 chars
+
+1 vulnerable regex(es): 1 exponential, 0 polynomial
+```
+
+> **Built and maintained by an AI agent.** redosray is written and maintained
+> autonomously by **Aurelio Nakamura**, an AI software agent. Issues and PRs are
+> read and acted on. The code is MIT-licensed and yours to audit.
+
+**▶ Try it in your browser — no install:** paste a regex into the
+[**redosray playground**](https://aurelio-nakamura.github.io/redosray/) and it
+runs the same dynamic confirmation client-side, showing you the exact input that
+hangs the pattern and the measured blow-up curve. Nothing leaves the page.
+
+---
+
+## Why redosray
+
+Most ReDoS tools reason about your regex *statically* — they build an automaton
+and warn you about shapes that *could* backtrack. That produces false alarms
+(patterns that are technically ambiguous but never actually blow up on real
+input) and gives you no evidence to act on.
+
+redosray does both halves:
+
+1. **Static candidate finding.** A dependency-free regex parser builds an AST
+   and looks for the three shapes that cause catastrophic backtracking:
+   nested quantifiers (`(a+)+`), ambiguous alternation (`(a|a)+`), and
+   sequential/overlapping quantifiers (`.*.*=.*`).
+2. **Dynamic confirmation.** Each candidate is *actually run* against a growing
+   attack string inside an isolated worker thread, timed, and killed if it
+   exceeds a threshold. The smallest input that crosses the timeout is reported
+   as **proof**.
+
+**If redosray flags it, it hangs — measured, not theorized.** A pattern that
+looks scary but stays fast on every input is reported as safe, so you don't
+waste time chasing phantoms.
+
+## Install
+
+```bash
+# one-off, no install
+npx redosray path/to/src
+
+# or globally
+npm install -g redosray
+```
+
+Requires Node.js ≥ 16. Zero runtime dependencies.
+
+## Usage
+
+Scan files or directories (defaults to the current directory):
+
+```bash
+redosray                 # scan .
+redosray src/ lib/       # scan multiple paths
+redosray app.py          # a single file
+```
+
+Test a single pattern:
+
+```bash
+redosray -e '(a+)+$'
+redosray -e '/^(\d+)+$/i'          # /pattern/flags form works too
+echo '(x+x+)+y' | redosray -e -    # from stdin
+```
+
+### Options
+
+| Flag | Meaning |
+|------|---------|
+| `-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 (code `2`) if any vulnerability is confirmed |
+| `--timeout <ms>` | Per-match hang threshold (default `1000`) |
+| `--no-color` | Disable ANSI colors |
+| `-h, --help` / `-v, --version` | — |
+
+### Use it in CI
+
+Fail the build if a ReDoS regex sneaks in:
+
+```yaml
+# .github/workflows/redos.yml
+- run: npx redosray --ci src/
+```
+
+### JSON for tooling
+
+```bash
+redosray --json src/ | jq '.findings[] | {source, complexity, proof: .proof.input}'
+```
+
+Each finding includes the pattern, its complexity class (`exponential` /
+`polynomial`), the vuln family, every source location, the proof input, and the
+full timing sample curve.
+
+## What it detects
+
+| Family | Example | Class |
+|--------|---------|-------|
+| Nested quantifier | `(a+)+`, `([a-z]+)*`, `(\d+)+` | exponential |
+| Ambiguous alternation | `(a\|a)+`, `(\w\|\d)+` | exponential |
+| Sequential / overlapping | `.*.*=.*`, `a.*.*b` | polynomial |
+
+Supported sources: `.js` `.jsx` `.ts` `.tsx` `.mjs` `.cjs` (regex literals and
+`new RegExp(...)`) and `.py` (`re.compile` / `re.match` / `re.search` / …).
+Minified files, `node_modules`, `.git`, `dist`, and other build dirs are skipped
+automatically.
+
+## How the proof works
+
+For a confirmed finding, redosray grows the attack input geometrically and times
+each match in a worker it can kill:
+
+```
+curve ▁▁██ 11→43 chars
+```
+
+Each block is a match time; `█` means it blew past the timeout. Exponential bugs
+cross in a handful of steps; polynomial ones take a few dozen. The reported
+`proof.input` is the smallest string that crossed the line — paste it into a REPL
+and watch your own regex hang.
+
+## Limitations (honest ones)
+
+- It confirms by **measurement**, so it can't prove a pattern is *safe* for all
+  possible inputs — only that it stayed fast up to the tested bound. It's a
+  finder of real bugs, not a formal verifier.
+- Dynamic analysis extracts regex *literals*; regexes built from runtime string
+  concatenation aren't evaluated.
+- Timing thresholds are machine-relative; tune `--timeout` for your CI hardware.
+
+## Comparison
+
+| | redosray | static-only detectors |
+|---|---|---|
+| Reports a real hang | ✅ measured proof | ❌ theoretical |
+| False positives | none (confirmed) | common |
+| Shows the attack input | ✅ | ❌ |
+| Offline / no deps | ✅ | varies |
+| Scans a whole repo | ✅ JS/TS/Py | varies |
+
+## License
+
+[MIT](./LICENSE) © Aurelio Nakamura. Contributions welcome.

package/bin/redosray.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+'use strict';
+require('../src/cli').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/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "redosray",
+  "version": "1.0.0",
+  "description": "Find ReDoS-vulnerable regexes in your code and prove them — offline. Shows the exact input that hangs each pattern.",
+  "type": "commonjs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aurelio-nakamura/redosray.git"
+  },
+  "homepage": "https://aurelio-nakamura.github.io/redosray/",
+  "bugs": {
+    "url": "https://github.com/aurelio-nakamura/redosray/issues"
+  },
+  "author": "Aurelio Nakamura",
+  "bin": {
+    "redosray": "bin/redosray.js"
+  },
+  "main": "src/index.js",
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/**/*.test.js",
+    "start": "node bin/redosray.js",
+    "build:browser": "node scripts/build-browser.js"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "license": "MIT",
+  "keywords": ["redos", "regex", "security", "backtracking", "dos", "regexp", "sast", "static-analysis"]
+}

package/src/analyze.js

@@ -0,0 +1,163 @@
+'use strict';
+// AST-based candidate finder for catastrophic / super-linear backtracking.
+//
+// Philosophy: STATIC finds *candidates*; DYNAMIC confirmation (confirm.js)
+// decides. So this file is deliberately liberal — it flags shapes that *might*
+// blow up and derives a concrete attack string for each. Because every reported
+// vulnerability is later proven by a measured hang, over-flagging here only
+// costs a few extra confirmation runs; it never produces a false claim.
+
+const { parse } = require('./parser');
+const { canStart, isNullable, sampleChar, overlapChar, failChar } = require('./charset');
+
+// Unwrap transparent wrappers (single-item seq, non-capturing/capturing groups)
+// to reach the "meat" of a sub-expression.
+function unwrap(node) {
+  let cur = node;
+  for (;;) {
+    if (cur.type === 'group') { cur = cur.body; continue; }
+    if (cur.type === 'seq' && cur.items.length === 1) { cur = cur.items[0]; continue; }
+    return cur;
+  }
+}
+
+function isUnbounded(node) {
+  return node.type === 'repeat' && node.max === Infinity;
+}
+
+// Collect every descendant repeat node (with a path for context).
+function walk(node, visit) {
+  visit(node);
+  switch (node.type) {
+    case 'alt': node.options.forEach((o) => walk(o, visit)); break;
+    case 'seq': node.items.forEach((it) => walk(it, visit)); break;
+    case 'repeat': walk(node.body, visit); break;
+    case 'group': case 'look': walk(node.body, visit); break;
+    default: break;
+  }
+}
+
+// Find, inside `node`, a descendant unbounded repeat over an atom-ish body.
+function findInnerRepeat(node) {
+  let found = null;
+  walk(node, (n) => {
+    if (found) return;
+    if (isUnbounded(n)) {
+      const b = unwrap(n.body);
+      if (['char', 'class', 'any', 'esc'].includes(b.type)) found = { rep: n, atom: b };
+    }
+  });
+  return found;
+}
+
+// Gather the alternation options at the top of a (possibly wrapped) node.
+function altOptions(node) {
+  const u = unwrap(node);
+  if (u.type === 'alt') return u.options;
+  return null;
+}
+
+function makeAttack(kind, matchedShape, pump, suffix, prefix = '') {
+  return { kind, matchedShape, prefix, pump, suffix };
+}
+
+// Produce a stable-ish shape string for dedup/reporting.
+function shapeOf(node) {
+  switch (node.type) {
+    case 'char': return node.value;
+    case 'any': return '.';
+    case 'esc': return '\\' + node.kind;
+    case 'class': return '[' + (node.negated ? '^' : '') + node.set + ']';
+    case 'anchor': return node.kind;
+    case 'backref': return '\\' + node.ref;
+    case 'group': return '(' + (node.capturing ? '' : '?:') + shapeOf(node.body) + ')';
+    case 'look': return '(?' + (node.behind ? '<' : '') + (node.negative ? '!' : '=') + shapeOf(node.body) + ')';
+    case 'alt': return node.options.map(shapeOf).join('|');
+    case 'seq': return node.items.map(shapeOf).join('');
+    case 'repeat': {
+      const q = node.max === Infinity ? (node.min === 0 ? '*' : (node.min === 1 ? '+' : `{${node.min},}`))
+        : (node.min === 0 && node.max === 1 ? '?' : `{${node.min},${node.max}}`);
+      return shapeOf(node.body) + q + (node.greedy ? '' : '?');
+    }
+    default: return '?';
+  }
+}
+
+/**
+ * Return a de-duplicated list of attack candidates for a parsed regex source.
+ * Each candidate: { kind, matchedShape, prefix, pump, suffix }.
+ */
+function findCandidates(source) {
+  let ast;
+  try { ast = parse(source); } catch { return []; }
+  const out = [];
+  const seen = new Set();
+  const push = (c) => {
+    if (!c || !c.pump) return;
+    const key = c.kind + '|' + c.matchedShape + '|' + c.pump + '|' + c.suffix;
+    if (seen.has(key)) return;
+    seen.add(key);
+    out.push(c);
+  };
+
+  walk(ast, (node) => {
+    // ---- Family A: nested quantifier  (X+)+ , (X*)* , ((\d+))+ ...
+    if (isUnbounded(node)) {
+      const inner = findInnerRepeat(node.body);
+      if (inner) {
+        const pump = sampleChar(inner.atom);
+        // Require the outer body to also start with pump, so consecutive outer
+        // iterations overlap (this is what makes it ambiguous / exponential).
+        if (pump && canStart(node.body, pump)) {
+          const suffix = failChar(inner.atom);
+          push(makeAttack('nested-quantifier', shapeOf(node), pump, suffix));
+        }
+      }
+
+      // ---- Family B: ambiguous alternation under a quantifier  (a|a)+ (a|ab)+
+      const opts = altOptions(node.body);
+      if (opts && opts.length >= 2) {
+        for (let x = 0; x < opts.length; x++) {
+          for (let y = x + 1; y < opts.length; y++) {
+            const pump = overlapChar(opts[x], opts[y]);
+            if (pump) {
+              const suffix = failChar(node.body);
+              push(makeAttack('ambiguous-alternation', shapeOf(node), pump, suffix));
+            }
+          }
+        }
+      }
+    }
+
+    // ---- Family C: adjacent unbounded quantifiers with overlapping first sets
+    //      \d+\d+ , a+a* , .*.*  -> polynomial (usually quadratic) backtracking.
+    if (node.type === 'seq') {
+      const reps = [];
+      for (let k = 0; k < node.items.length; k++) {
+        const it = node.items[k];
+        if (isUnbounded(it)) reps.push({ idx: k, rep: it });
+      }
+      for (let a = 0; a < reps.length; a++) {
+        for (let b = a + 1; b < reps.length; b++) {
+          // only pair them if everything strictly between is nullable (so both
+          // quantifiers actually compete over the same run of characters)
+          let between = true;
+          for (let m = reps[a].idx + 1; m < reps[b].idx; m++) {
+            if (!isNullable(node.items[m])) { between = false; break; }
+          }
+          if (!between) continue;
+          const pump = overlapChar(reps[a].rep.body, reps[b].rep.body);
+          if (pump) {
+            const suffix = failChar(reps[a].rep.body);
+            const shape = shapeOf({ type: 'seq', items: node.items.slice(reps[a].idx, reps[b].idx + 1) });
+            push(makeAttack('sequential-quantifier', shape, pump, suffix));
+          }
+        }
+      }
+    }
+  });
+
+  return out;
+}
+
+module.exports = { findCandidates, parse, shapeOf };

package/src/charset.js

@@ -0,0 +1,87 @@
+'use strict';
+// Small character-set reasoning over AST atoms. Used to (a) pick a concrete
+// "pump" character an ambiguous sub-expression matches, and (b) pick a "fail"
+// character that forces the engine to backtrack. These only need to be good
+// enough to build an attack candidate — the dynamic confirmation step is the
+// source of truth, so an imperfect guess yields a false-negative, never a
+// false-positive.
+
+const ASCII = [];
+for (let c = 0x20; c < 0x7f; c++) ASCII.push(String.fromCharCode(c));
+const PROBE = ['a', 'A', '1', '0', '_', ' ', '!', '@', '-', '\t'].concat(ASCII);
+
+function classMatches(set, negated, ch) {
+  try {
+    const re = new RegExp('^[' + (negated ? '^' : '') + set + ']$');
+    return re.test(ch);
+  } catch {
+    return false;
+  }
+}
+
+// Can `node` begin a match with character `ch`?
+function canStart(node, ch) {
+  switch (node.type) {
+    case 'char': return node.value === ch;
+    case 'any': return ch !== '\n';
+    case 'esc': {
+      const k = node.kind;
+      if (k === 'd') return /[0-9]/.test(ch);
+      if (k === 'D') return !/[0-9]/.test(ch);
+      if (k === 'w') return /[A-Za-z0-9_]/.test(ch);
+      if (k === 'W') return !/[A-Za-z0-9_]/.test(ch);
+      if (k === 's') return /\s/.test(ch);
+      if (k === 'S') return !/\s/.test(ch);
+      return false;
+    }
+    case 'class': return classMatches(node.set, node.negated, ch);
+    case 'group': return canStart(node.body, ch);
+    case 'look': return false; // zero-width; handled by nullability elsewhere
+    case 'repeat': return canStart(node.body, ch);
+    case 'alt': return node.options.some((o) => canStart(o, ch));
+    case 'anchor': return false;
+    case 'backref': return false;
+    case 'seq': {
+      for (const it of node.items) {
+        if (isNullable(it)) { if (canStart(it, ch)) return true; continue; }
+        return canStart(it, ch);
+      }
+      return false;
+    }
+    default: return false;
+  }
+}
+
+function isNullable(node) {
+  switch (node.type) {
+    case 'repeat': return node.min === 0 || isNullable(node.body);
+    case 'anchor': case 'look': return true;
+    case 'group': return isNullable(node.body);
+    case 'alt': return node.options.some(isNullable);
+    case 'seq': return node.items.every(isNullable);
+    default: return false;
+  }
+}
+
+// A representative character the (atom-ish) node matches, or null.
+function sampleChar(node) {
+  for (const ch of PROBE) if (canStart(node, ch)) return ch;
+  return null;
+}
+
+// A character both nodes can start with (their overlap), or null.
+function overlapChar(a, b) {
+  for (const ch of PROBE) if (canStart(a, ch) && canStart(b, ch)) return ch;
+  return null;
+}
+
+// A character that the node does NOT match — used as the failing suffix that
+// forces exhaustive backtracking. Prefer visible, benign chars.
+function failChar(node) {
+  const prefer = ['!', 'x', 'Z', '0', ' ', '\uffff', '\n', '\x00'];
+  for (const ch of prefer) if (!canStart(node, ch)) return ch;
+  for (const ch of PROBE) if (!canStart(node, ch)) return ch;
+  return '\x00';
+}
+
+module.exports = { canStart, isNullable, sampleChar, overlapChar, failChar };