The Python ReDoS Vulnerability Scanner β Protect your applications from Regular Expression Denial of Service attacks.
β οΈ License Notice: ReDoctor is licensed under the Business Source License 1.1 (BSL-1.1). Non-commercial use is free. Commercial production use requires a paid license. The code will convert to MIT license on January 9, 2031.
Quick Start β’ Features β’ Installation β’ Usage β’ Documentation β’ Contributing
Regular Expression Denial of Service (ReDoS) is a type of algorithmic complexity attack that exploits the worst-case behavior of regex engines. A vulnerable regex can cause your application to hang for minutes or hours when processing malicious input.
# β οΈ This innocent-looking regex is VULNERABLE! import re pattern = r"^(a+)+$" # This will hang your application: re.match(pattern, "a" * 30 + "!") # Takes exponential time!ReDoctor detects these vulnerabilities before they reach production.
# Install pip install redoctor # Check a pattern from command line redoctor '^(a+)+$' # Output: VULNERABLE: ^(a+)+$ - Complexity: O(2^n) # Use in Python from redoctor import check result = check(r"^(a+)+$") if result.is_vulnerable: print(f"π¨ Vulnerable! Complexity: {result.complexity}") print(f" Attack string: {result.attack}")| Combines static automata-based analysis with intelligent fuzzing for comprehensive detection. Catches vulnerabilities that single-approach tools miss. Pure Python with no external dependencies. Runs in milliseconds for most patterns. Compatible with Python 3.6+. | Generates proof-of-concept attack strings with complexity analysis ( Scan your entire Python codebase for vulnerable regex patterns. Integrates with CI/CD pipelines. |
pip install redoctorRequirements: Python 3.6+ Dependencies: None (pure Python)
# Check a single pattern redoctor '^(a+)+$' # Verbose output with attack details redoctor '(a|a)*$' --verbose # Check with flags redoctor 'pattern' --ignore-case --multiline # Read patterns from stdin echo '^(a+)+$' | redoctor --stdin # Set timeout redoctor 'complex-pattern' --timeout 30Exit codes:
0- Pattern is safe1- Pattern is vulnerable2- Error occurred
from redoctor import check, is_vulnerable, Config # Simple check result = check(r"^(a+)+$") print(result.status) # Status.VULNERABLE print(result.complexity) # O(2^n) print(result.attack) # 'aaaaaaaaaaaaaaaaaaaaa!' # Quick vulnerability check if is_vulnerable(r"(x+x+)+y"): print("Don't use this pattern!") # Access attack pattern details if result.is_vulnerable: attack = result.attack_pattern print(f"Prefix: {attack.prefix!r}") print(f"Pump: {attack.pump!r}") print(f"Suffix: {attack.suffix!r}") # Generate attack strings of different lengths short_attack = attack.build(10) # 10 pump repetitions long_attack = attack.build(100) # 100 pump repetitions # Custom configuration config = Config( timeout=30.0, # Analysis timeout in seconds max_attack_length=4096, # Max attack string length ) result = check(r"complex-pattern", config=config) # Quick mode for CI/CD config = Config.quick() # 1 second timeout result = check(pattern, config=config)Scan your Python codebase for vulnerable regex patterns:
from redoctor.integrations import scan_file, scan_directory # Scan a single file vulnerabilities = scan_file("myapp/validators.py") for vuln in vulnerabilities: print(f"{vuln.file}:{vuln.line} - {vuln.pattern}") print(f" Complexity: {vuln.diagnostics.complexity}") # Scan entire directory for vuln in scan_directory("src/", recursive=True): if vuln.is_vulnerable: print(f"π¨ {vuln}")ReDoctor classifies vulnerabilities by their time complexity:
| Complexity | Description | Risk Level |
|---|---|---|
O(n) | Linear - Safe | β Safe |
O(nΒ²) | Quadratic | |
O(nΒ³) | Cubic | |
O(2βΏ) | Exponential | π¨ Critical |
ReDoctor uses a hybrid approach combining two detection methods:
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β ReDoctor Engine β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€ β β β βββββββββββββββββββ βββββββββββββββββββ β β β Automaton β β Fuzz β β β β Checker β β Checker β β β β β β β β β β β’ NFA analysis β β β’ VM execution β β β β β’ O(n) check β β β’ Step countingβ β β β β’ Witness gen β β β’ Mutation β β β ββββββββββ¬βββββββββ ββββββββββ¬βββββββββ β β β β β β βββββββββββββ¬ββββββββββββββββ β β β β β ββββββββββΌβββββββββ β β β Recall Validatorβ β β β (confirmation) β β β ββββββββββ¬βββββββββ β β β β β ββββββββββΌβββββββββ β β β Diagnostics β β β β β’ Complexity β β β β β’ Attack stringβ β β β β’ Hotspot β β β βββββββββββββββββββ β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ - Automaton Checker: Builds an Ξ΅-NFA from the regex and analyzes for ambiguity patterns that cause backtracking.
- Fuzz Checker: Executes patterns in a step-counting VM with evolved test strings to detect polynomial/exponential growth.
- Recall Validator: Confirms detected vulnerabilities with real execution timing.
Full documentation is available at redoctor.getpagespeed.com
from redoctor import check # Classic nested quantifier - Exponential O(2^n) check(r"^(a+)+$") # VULNERABLE # Overlapping alternatives - Exponential O(2^n) check(r"(a|a)*$") # VULNERABLE # Polynomial O(nΒ²) check(r".*a.*a.*") # VULNERABLE # Email-like pattern - Often vulnerable check(r"^([a-zA-Z0-9]+)*@") # VULNERABLE # Safe patterns check(r"^[a-z]+$") # SAFE check(r"^\d{1,10}$") # SAFE check(r"^[A-Z][a-z]*$") # SAFEContributions are welcome! See our Contributing Guide for details.
# Clone the repo git clone https://github.com/GetPageSpeed/redoctor.git cd redoctor # Install development dependencies pip install -e ".[dev]" # Run tests pytest tests/ -x --tb=short # Run with coverage make testsReDoctor is licensed under the Business Source License 1.1 (BSL-1.1).
- β Free for non-commercial and non-production use
- β Free for personal projects, education, and research
- πΌ Commercial production use requires a paid license
- π Converts to MIT License on January 9, 2031
- Inspired by recheck and academic research on ReDoS detection
- Built with β€οΈ by GetPageSpeed
Protect your applications from ReDoS attacks.
β Star on GitHub β’ π¦ View on PyPI β’ π Read the Docs