Hooks

regex hook: Detect ReDoS Patterns

Sweep a codebase for ReDoS-prone regex, or score a single pattern, from the command line.

The regex hook is the deterministic regex-safety engine the regex specialization runs, and you can run it yourself. It works in two modes from one command: a scan that sweeps a codebase for ReDoS-prone and runtime-built patterns, and a check that scores a single pattern you hand it.

Scan a codebase​

With no flag it scans the whole project. --dir scopes the scan to a directory, --file to a single file. Both repeat and combine into one report, each file listed once even when more than one target covers it.

npx lagune read regex

The output is raw text whose headers say how to read each section. A section is shown only when it has findings.

Vulnerable regular expressions found:

cmd/server/main.go
([a-z]+)+$ (exponential, search)

Dynamically built regular expressions (review manually by simulating a constructed regex):

app/payments.php
crates/parser/lexer.rs
lib/validate.py

Static regex wrapped in a constructor (use a literal instead):

config/token.rb

When nothing is found, it prints a single line.

npx lagune read regex --dir src/clean
# => no unsafe patterns found

How to read the sections​

SectionMeaning
Vulnerable regular expressions foundReDoS-prone patterns, grouped by file with each pattern indented beneath, followed in parentheses by why it is unsafe and, when it has them, its scope and its flags. Every line is unsafe, so the verdict is not repeated.
Regular expressions the analysis could not settle (review manually)Patterns the analysis could not settle within its work cap, listed the same way.
Strings that would be vulnerable as regular expressions (unconfirmed, review manually)Strings that read as a ReDoS-prone pattern while nothing in the scan proves the code compiles them, listed the same way.
Dynamically built regular expressions (review manually by simulating a constructed regex)Files that build a regex from a variable, a concatenation, or an interpolation.
Static regex wrapped in a constructor (use a literal instead)Files that pass a plain string literal to a regex constructor where a regex literal is simpler and skips a runtime compile.

The first section is a security finding, the only one that fails the run. The second, third, and fourth are not findings on their own: they point to code a static check cannot settle, so they ask for a human read. The fifth is a clarity hint, not a security finding.

What counts as a regular expression​

A quoted string is not a regular expression just because it looks like one: a cron expression, a SQL wildcard, a glob, or a printf precision share the same characters. The scan reports a string as vulnerable only when the code proves it is a pattern:

  • It is a regex literal, or the argument of a regular expression API.
  • It is bound to a name that a regular expression API receives, in the same file or in another one.
  • Its name, or the function it is passed to, says it is a regular expression, such as EMAIL_REGEX or @Pattern(regexp = ...).

A string whose name only suggests a pattern, or whose file builds a regular expression from a value the scan could not trace, is listed as unconfirmed. Every other string is left out, and so is anything written in a comment or in a string that runs across lines, such as a docstring.

CLI options​

OptionValueDescription
--patterna regex sourceCheck one pattern. Repeat to check several, one verdict per pattern, in order.
--flagsregex flagsCheck every --pattern with these flags, such as im. Applies to the check mode only.
--dira directoryScope a scan to a directory. Repeats and combines with --file.
--filea fileScope a scan to a single file. Repeats and combines with --dir.
--limita non-negative integerSet the ReDoS repetition limit (default 25). Applies to both modes. A lower limit is stricter.

With no option it scans the whole project. --pattern is the check mode and cannot be combined with --dir or --file.

Choose what it scans​

It leaves out what Git ignores. To leave out more, or to scan what Git ignores, give regex settings of its own:

npx lagune write add --ignore test/fixtures --checker regex
{
"checkers": {
"regex": { "gitignore": false, "ignore": ["test/fixtures"] }
}
}

Configure the hooks covers every setting.

Supported languages​

The scan reads these languages, keyed by file extension, each by its own rules so a pattern from one is never tested against another. Everything else is skipped rather than scanned with the wrong rules.

#LanguageExtensions
1JavaScript / TypeScript.js, .jsx, .mjs, .cjs, .ts, .tsx, .mts, .cts, .astro, .vue, .svelte, .marko, .riot
2Python.py, .pyi
3Ruby.rb
4Go.go
5PHP.php
6Rust.rs
7Java.java
8C#.cs
9C.c, .h
10C++.cc, .cpp, .cxx, .hpp, .hh, .hxx
11Kotlin.kt, .kts
12Swift.swift
13Scala.scala, .sc
14Dart.dart
15PowerShell.ps1, .psm1, .psd1
16Elixir.ex, .exs
17Objective-C.m, .mm
18R.r
19Julia.jl
20Clojure.clj, .cljs, .cljc, .edn
21Crystal.cr
22Nim.nim, .nims
23V.v
24D.d
25Perl.pl, .pm
Best-effort, not exhaustive

It reads source as text, so it cannot judge a pattern assembled at runtime, and a pattern spread across lines, hidden behind an alias, held in a list, passed through a function's parameter, or written in a form it does not recognize can slip past. Treat the sections as a strong starting point, not a complete inventory, and keep reading the code for what they cannot reach.

Check a single pattern​

Pass --pattern with the pattern's source to score it. The hook prints one word: safe, unsafe, undetermined when the analysis reaches its work cap before settling the pattern, or invalid regex. Repeat --pattern to score several at once, one verdict per pattern, in order.

npx lagune read regex --pattern '(a+)+$'
# => unsafe

npx lagune read regex --pattern '^[a-z0-9_]{3,20}$'
# => safe
Why a quoted argument

Each pattern is passed as a flag value, never interpolated into the command. A value with quotes or backticks stays inert and cannot inject into the shell. Always wrap the pattern in single quotes so your shell does not expand it first.

tip

This is the same engine the regex specialization runs: the scan opens a ReDoS pass, the check confirms a pattern it surfaces.

Frequently Asked Questions

Run npx lagune read regex --pattern '<pattern>'. It returns safe, unsafe, undetermined, or invalid regex.

Run the regex hook in scan mode over the codebase. It reports ReDoS-prone patterns across 25 supported languages.