Safe Regex

Safe Regex is a JavaScript library that detects potentially catastrophic, exponential-time regular expressions that could cause performance issues or denial-of-service vulnerabilities. It analyzes regular expressions by limiting the star height to 1 and provides a simple boolean API to determine if a regex pattern is safe to use.

Package Information

• Package Name: safe-regex
• Package Type: npm
• Language: JavaScript
• Installation: npm install safe-regex

Core Imports

const safeRegex = require('safe-regex');

For ES modules:

import safeRegex from 'safe-regex';

Note: The package uses CommonJS exports (module.exports = safeRegex), so ES module imports require default import syntax.

Basic Usage

const safeRegex = require('safe-regex');

// Check if a regex pattern is safe to use
console.log(safeRegex('(x+x+)+y'));           // false - vulnerable
console.log(safeRegex('(beep|boop)*'));       // true - safe  
console.log(safeRegex('(a+){10}'));           // false - vulnerable
console.log(safeRegex(/\blocation\s*:[^:\n]+\b(Oakland|San Francisco)\b/)); // true - safe

// With custom repetition limit
console.log(safeRegex('a?a?a?a?', { limit: 3 })); // false - exceeds limit
console.log(safeRegex('a?a?a?', { limit: 5 }));   // true - within limit

Architecture

Safe Regex uses a heuristic-based analysis approach to detect potentially dangerous regular expressions:

• Star Height Analysis: Measures the nesting depth of quantifiers (*, +, ?, {n,m}) in the regex AST. Patterns with star height > 1 indicate nested quantifiers that can cause exponential backtracking.
• Repetition Count Heuristic: Counts the total number of quantifier nodes in the regex. Patterns exceeding the limit (default: 25) are flagged as potentially problematic.
• AST Parsing: Uses the regexp-tree library to parse regex patterns into Abstract Syntax Trees for analysis.
• Conservative Approach: Designed to err on the side of caution, which may result in false positives for some safe patterns.

The analyzer framework is extensible but currently implements only heuristic-based detection. For production use cases requiring higher accuracy, consider vuln-regex-detector.

Capabilities

Regex Safety Analysis

Analyzes regular expressions to detect potential ReDoS (Regular expression Denial of Service) vulnerabilities by checking star height and repetition count heuristics.

/**
 * Detect potentially catastrophic regular expressions
 * @param {RegExp|string} re - Regular expression to analyze (RegExp object or string pattern)
 * @param {Object} [opts] - Optional configuration options
 * @param {number} [opts.limit=25] - Maximum number of allowed repetitions in the entire regex
 * @returns {boolean} - true if regex is safe, false if potentially vulnerable
 */
function safeRegex(re, opts);

Parameters:

• re (RegExp | string): The regular expression to analyze. Can be a RegExp object or a string pattern. Invalid regex strings return false.
• opts (Object, optional): Configuration options
  • limit (number, optional): Maximum number of allowed repetitions in the entire regex. Default: 25.

Returns:

• boolean: Returns true if the regex is considered safe, false if it's potentially vulnerable or invalid.

Detection Heuristics:

1. Star Height Analysis: Flags regexes with nested quantifiers (star height > 1) as potentially vulnerable
2. Repetition Count: Flags regexes exceeding the repetition limit as potentially vulnerable
3. Invalid Regex Handling: Returns false for invalid or unparseable regex patterns

Usage Examples:

const safeRegex = require('safe-regex');

// Safe patterns (linear time)
safeRegex(/a*/);                    // true - simple quantifier
safeRegex(/a+/);                    // true - simple quantifier  
safeRegex(/a|b/);                   // true - alternation
safeRegex(/(ab)/);                  // true - grouping
safeRegex(/(beep|boop)*/);          // true - alternation with quantifier
safeRegex(/\bOakland\b/);           // true - word boundaries

// Vulnerable patterns (exponential time)
safeRegex(/(a*)*$/);                // false - nested quantifiers (star height > 1)
safeRegex(/(a+)+$/);                // false - nested quantifiers
safeRegex(/(x+x+)+y/);              // false - catastrophic backtracking
safeRegex('(a+){10}y');             // false - excessive repetition

// String patterns
safeRegex('^foo/bar');              // true - valid string pattern
safeRegex('(a+');                   // false - invalid regex syntax

// Custom limits
safeRegex('a?'.repeat(30), { limit: 25 }); // false - exceeds default limit
safeRegex('a?'.repeat(20), { limit: 25 }); // true - within limit
safeRegex('a?a?a?a?', { limit: 3 });       // false - exceeds custom limit

Important Notes:

• False Positives: Some safe regexes may be flagged as vulnerable (e.g., /(ab*)+$/)
• False Negatives: Some vulnerable regexes may be considered safe (e.g., /(a|a)*$/)
• Accuracy Limitation: For improved accuracy, consider using vuln-regex-detector
• Error Handling: Invalid regex patterns automatically return false
• Type Coercion: Non-string, non-RegExp inputs are converted to strings before parsing

Types

/**
 * Options for configuring regex analysis
 */
interface SafeRegexOptions {
  /** Maximum number of allowed repetitions in the regex (default: 25) */
  limit?: number;
}

/**
 * Main safe-regex function type
 */
type SafeRegexFunction = (re: RegExp | string, opts?: SafeRegexOptions) => boolean;