Getting Started¶

This guide will get you up and running with ReDoctor in under 5 minutes.

Installation¶

pippipx (isolated)From source

pip install redoctor

pipx install redoctor

git clone https://github.com/GetPageSpeed/redoctor.git cd redoctor pip install -e .

Requirements

Python 3.6 or higher
No external dependencies required

Your First Check¶

Command Line¶

The quickest way to check a regex pattern:

redoctor '^(a+)+$'

Output:

VULNERABLE: ^(a+)+$  Complexity: O(2^n)  Attack: 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa!'

Python API¶

from redoctor import check  # Check a regex pattern result = check(r"^(a+)+$")  # Check the result print(f"Status: {result.status}") # Status.VULNERABLE print(f"Complexity: {result.complexity}") # O(2^n) print(f"Is vulnerable: {result.is_vulnerable}") # True  # Get the attack string if result.is_vulnerable:  print(f"Attack: {result.attack}")   # Get detailed attack pattern  attack = result.attack_pattern  print(f"Prefix: {attack.prefix!r}")  print(f"Pump: {attack.pump!r}")  print(f"Suffix: {attack.suffix!r}")

Understanding the Results¶

ReDoctor returns a Diagnostics object with the following key properties:

Property	Type	Description
`status`	`Status`	`SAFE`, `VULNERABLE`, `UNKNOWN`, or `ERROR`
`is_vulnerable`	`bool`	Quick check if pattern is vulnerable
`is_safe`	`bool`	Quick check if pattern is safe
`complexity`	`Complexity`	Time complexity (`O(n)`, `O(n²)`, `O(2ⁿ)`)
`attack`	`str`	Generated attack string
`attack_pattern`	`AttackPattern`	Detailed attack structure
`hotspot`	`Hotspot`	The vulnerable part of the regex

Quick Checks¶

For simple boolean checks:

from redoctor import is_vulnerable, is_safe  # Check if vulnerable if is_vulnerable(r"(a|a)*$"):  print("Don't use this pattern!")  # Check if safe if is_safe(r"^[a-z]+$"):  print("This pattern is safe to use")

Checking with Flags¶

Support for regex flags:

CLIPython

# Ignore case redoctor 'pattern' --ignore-case  # Multiline redoctor 'pattern' --multiline  # Dotall redoctor 'pattern' --dotall  # Combined redoctor 'pattern' -i -m -s

from redoctor import check from redoctor.parser.flags import Flags  flags = Flags(  ignore_case=True,  multiline=True,  dotall=False )  result = check(r"^hello.*world$", flags=flags)

Configuration¶

Customize the analysis behavior:

from redoctor import check, Config  # Default configuration config = Config.default()  # Quick mode (faster, less thorough) config = Config.quick()  # Thorough mode (slower, more comprehensive) config = Config.thorough()  # Custom configuration config = Config(  timeout=30.0, # Analysis timeout (seconds)  max_attack_length=4096, # Maximum attack string length  max_iterations=100000, # Maximum fuzz iterations )  result = check(r"pattern", config=config)

See the Configuration Guide for all options.

Scanning Source Code¶

Find vulnerable patterns in your Python codebase:

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}")  # Scan entire project for vuln in scan_directory("src/", recursive=True):  if vuln.is_vulnerable:  print(f"🚨 {vuln}")