Хук regex є детермінованим рушієм безпеки регулярних виразів, який запускає спеціалізація regex, і ви можете запускати його самі. Він працює у двох режимах однієї команди: scan, що перевіряє кодову базу на шаблони, схильні до ReDoS або побудовані під час виконання, і check, що оцінює окремий шаблон, який ви йому передаєте.

Перевірка кодової бази

Без прапорців хук перевіряє весь проєкт. --dir обмежує перевірку каталогом, --file одним файлом. Обидва можна повторювати й поєднувати в один звіт, і кожен файл з'являється в ньому один раз, навіть якщо його охоплює більше ніж одна ціль.

Увесь проєкт

npx lagune read regex

Каталог

npx lagune read regex --dir src/services

Один файл

npx lagune read regex --file bin/import.pl

Кілька цілей

npx lagune read regex --dir core --dir workers --file Sources/App/Router.swift

З лімітом

--limit задає поріг ReDoS для перевірки (за замовчуванням 25), той самий ліміт, що приймає режим check. Нижчий ліміт суворіший.

npx lagune read regex --dir src/services --limit 15

Вивід є звичайним текстом, заголовки якого пояснюють, як читати кожен розділ. Розділ показується лише тоді, коли в ньому є знахідки.

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

Якщо нічого не знайдено, хук виводить один рядок.

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

Як читати розділи

Розділ	Значення
Vulnerable regular expressions found	Шаблони, схильні до ReDoS, згруповані за файлами, кожен шаблон з відступом під файлом, а в дужках пояснено, чому він небезпечний, і, якщо є, його область і прапорці. Кожен рядок небезпечний, тож вердикт не повторюється.
Regular expressions the analysis could not settle (review manually)	Шаблони, щодо яких аналіз не зміг дійти висновку в межах свого ліміту роботи, перелічені так само.
Dynamically built regular expressions (review manually by simulating a constructed regex)	Файли, що будують регулярний вираз зі змінної, конкатенації чи інтерполяції.
Static regex wrapped in a constructor (use a literal instead)	Файли, що передають звичайний рядковий літерал у конструктор регулярного виразу там, де літерал регулярного виразу простіший і не потребує компіляції під час виконання.

Перший розділ є знахідкою безпеки. Другий і третій самі по собі не є знахідками: вони вказують на код, щодо якого статична перевірка не може дійти висновку, тож потребують, щоб його прочитала людина. Четвертий є підказкою для зрозумілості коду, а не знахідкою безпеки.

Параметри CLI

Параметр	Значення	Опис
--pattern	джерело регулярного виразу	Перевірити один шаблон. Повторіть, щоб перевірити кілька, по вердикту на шаблон, у тому самому порядку.
--flags	прапорці регулярного виразу	Перевірити кожен --pattern з цими прапорцями, як-от im. Діє лише в режимі check.
--dir	каталог	Обмежити перевірку каталогом. Повторюється й поєднується з --file.
--file	файл	Обмежити перевірку одним файлом. Повторюється й поєднується з --dir.
--limit	невід'ємне ціле число	Задати ліміт повторень ReDoS (за замовчуванням 25). Діє в обох режимах. Нижчий ліміт суворіший.

Без параметрів хук перевіряє весь проєкт. --pattern вмикає режим check і не поєднується з --dir чи --file.

Підтримувані мови

Перевірка читає ці мови, визначаючи їх за розширенням файлу, кожну за її власними правилами, тож шаблон з однієї мови ніколи не перевіряється за правилами іншої. Усе інше пропускається, а не перевіряється за хибними правилами.

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

Найкраще з можливого, але не вичерпно

Хук читає вихідний код як текст, тож не може оцінити шаблон, зібраний під час виконання, а шаблон, розкиданий на кілька рядків, прихований за псевдонімом або записаний у формі, яку хук не розпізнає, може прослизнути. Сприймайте розділи як надійну відправну точку, а не як повний перелік, і читайте код далі, щоб охопити те, до чого вони не дістаються.

Перевірка окремого шаблону

Передайте --pattern із джерелом шаблону, щоб оцінити його. Хук виводить одне слово: safe, unsafe, undetermined, коли аналіз досягає свого ліміту роботи, не дійшовши висновку, або invalid regex. Повторіть --pattern, щоб оцінити кілька шаблонів одразу, по вердикту на шаблон, у тому самому порядку.

Один шаблон

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

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

Кілька шаблонів

npx lagune read regex --pattern '(a+)+$' --pattern '^[a-z]+$'
# => unsafe
# => safe

З прапорцями

--flags перевіряє кожен --pattern у виклику з прапорцями, з якими він виконується, бо прапорець змінює, яким символам відповідає шаблон.

npx lagune read regex --pattern '^(?:a|A)+$'
# => safe

npx lagune read regex --pattern '^(?:a|A)+$' --flags 'i'
# => unsafe

З лімітом

--limit задає ліміт повторень (за замовчуванням 25) і діє для кожного --pattern у виклику. Нижчий ліміт суворіший.

npx lagune read regex --pattern 'a?a?a?' --limit 2
# => unsafe

Чому аргумент у лапках

Кожен шаблон передається як значення прапорця й ніколи не підставляється в команду. Значення з лапками чи зворотними апострофами залишається інертним і не може здійснити ін'єкцію в оболонку. Завжди беріть шаблон в одинарні лапки, щоб ваша оболонка не розгорнула його першою.

порада

Це той самий рушій, який запускає спеціалізація regex: перевірка scan відкриває прохід ReDoS, а check підтверджує шаблон, який вона виявляє.

Часті запитання

Виконайте npx lagune read regex --pattern '<pattern>'. Хук повертає safe, unsafe, undetermined або invalid regex.

Запустіть хук regex у режимі scan над кодовою базою. Він повідомляє про шаблони, схильні до ReDoS, у 25 підтримуваних мовах.