proxywhirl.safe_regex

Safe regex pattern matching with ReDoS protection.

This module provides utilities for safely compiling and matching user-provided regex patterns with timeout protection to prevent Regular Expression Denial of Service (ReDoS) attacks.

Exceptions

RegexComplexityError

Raised when regex pattern is too complex or dangerous.

RegexTimeoutError

Raised when regex compilation or matching exceeds timeout.

Functions

safe_regex_compile(pattern[, flags, timeout, validate])

Safely compile a regex pattern with timeout protection.

safe_regex_findall(pattern, text[, flags, timeout, ...])

Safely find all matches of a regex pattern in text with timeout protection.

safe_regex_match(pattern, text[, flags, timeout, validate])

Safely match a regex pattern against text with timeout protection.

safe_regex_search(pattern, text[, flags, timeout, ...])

Safely search for a regex pattern in text with timeout protection.

validate_regex_pattern(pattern[, max_length])

Validate a regex pattern for safety.

Module Contents

exception proxywhirl.safe_regex.RegexComplexityError[source]

Bases: Exception

Raised when regex pattern is too complex or dangerous.

Initialize self. See help(type(self)) for accurate signature.

exception proxywhirl.safe_regex.RegexTimeoutError[source]

Bases: Exception

Raised when regex compilation or matching exceeds timeout.

Initialize self. See help(type(self)) for accurate signature.

proxywhirl.safe_regex.safe_regex_compile(pattern, flags=0, timeout=DEFAULT_REGEX_TIMEOUT, validate=True)[source]

Safely compile a regex pattern with timeout protection.

Parameters:

  • pattern (str) – Regex pattern string

  • flags (int) – Regex compilation flags (re.IGNORECASE, etc.)

  • timeout (float) – Maximum time allowed for compilation in seconds

  • validate (bool) – Whether to validate pattern complexity first

Returns:

Compiled regex pattern

Raises:

  • RegexTimeoutError – If compilation exceeds timeout

  • typer.Exit – If pattern is rejected during validation

Return type:

re.Pattern[str]

proxywhirl.safe_regex.safe_regex_findall(pattern, text, flags=0, timeout=DEFAULT_REGEX_TIMEOUT, validate=True, max_results=10000)[source]

Safely find all matches of a regex pattern in text with timeout protection.

Parameters:

  • pattern (str | re.Pattern[str]) – Regex pattern (string or compiled pattern)

  • text (str) – Text to search in

  • flags (int) – Regex flags (only used if pattern is a string)

  • timeout (float) – Maximum time allowed for searching in seconds

  • validate (bool) – Whether to validate pattern complexity first (only for string patterns)

  • max_results (int) – Maximum number of results to return (prevents DoS)

Returns:

List of matching strings

Raises:

  • RegexTimeoutError – If searching exceeds timeout

  • typer.Exit – If pattern is rejected during validation

Return type:

list[str]

proxywhirl.safe_regex.safe_regex_match(pattern, text, flags=0, timeout=DEFAULT_REGEX_TIMEOUT, validate=True)[source]

Safely match a regex pattern against text with timeout protection.

Parameters:

  • pattern (str | re.Pattern[str]) – Regex pattern (string or compiled pattern)

  • text (str) – Text to match against

  • flags (int) – Regex flags (only used if pattern is a string)

  • timeout (float) – Maximum time allowed for matching in seconds

  • validate (bool) – Whether to validate pattern complexity first (only for string patterns)

Returns:

Match object if pattern matches, None otherwise

Raises:

  • RegexTimeoutError – If matching exceeds timeout

  • typer.Exit – If pattern is rejected during validation

Return type:

re.Match[str] | None

Safely search for a regex pattern in text with timeout protection.

This is an alias for safe_regex_match for API compatibility.

Parameters:

  • pattern (str | re.Pattern[str]) – Regex pattern (string or compiled pattern)

  • text (str) – Text to search in

  • flags (int) – Regex flags (only used if pattern is a string)

  • timeout (float) – Maximum time allowed for searching in seconds

  • validate (bool) – Whether to validate pattern complexity first (only for string patterns)

Returns:

Match object if pattern found, None otherwise

Raises:

  • RegexTimeoutError – If searching exceeds timeout

  • typer.Exit – If pattern is rejected during validation

Return type:

re.Match[str] | None

proxywhirl.safe_regex.validate_regex_pattern(pattern, max_length=MAX_PATTERN_LENGTH)[source]

Validate a regex pattern for safety.

Parameters:

  • pattern (str) – Regex pattern to validate

  • max_length (int) – Maximum allowed pattern length

Raises:

  • RegexComplexityError – If pattern is too complex or dangerous

  • typer.Exit – If pattern is rejected

Return type:

None