0
# Safe Regex
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: safe-regex
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install safe-regex`
10

11
## Core Imports
12

13
```javascript
14
const safeRegex = require('safe-regex');
15
```
16

17
For ES modules:
18

19
```javascript
20
import safeRegex from 'safe-regex';
21
```
22

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

25
## Basic Usage
26

27
```javascript
28
const safeRegex = require('safe-regex');
29

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

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

41
## Architecture
42

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

45
- **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.
46
- **Repetition Count Heuristic**: Counts the total number of quantifier nodes in the regex. Patterns exceeding the limit (default: 25) are flagged as potentially problematic.
47
- **AST Parsing**: Uses the `regexp-tree` library to parse regex patterns into Abstract Syntax Trees for analysis.
48
- **Conservative Approach**: Designed to err on the side of caution, which may result in false positives for some safe patterns.
49

50
The analyzer framework is extensible but currently implements only heuristic-based detection. For production use cases requiring higher accuracy, consider [vuln-regex-detector](https://github.com/davisjam/vuln-regex-detector).
51

52
## Capabilities
53

54
### Regex Safety Analysis
55

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

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

69
**Parameters:**
70

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

75
**Returns:**
76

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

79
**Detection Heuristics:**
80

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

85
**Usage Examples:**
86

87
```javascript
88
const safeRegex = require('safe-regex');
89

90
// Safe patterns (linear time)
91
safeRegex(/a*/);                    // true - simple quantifier
92
safeRegex(/a+/);                    // true - simple quantifier  
93
safeRegex(/a|b/);                   // true - alternation
94
safeRegex(/(ab)/);                  // true - grouping
95
safeRegex(/(beep|boop)*/);          // true - alternation with quantifier
96
safeRegex(/\bOakland\b/);           // true - word boundaries
97

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

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

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

114
**Important Notes:**
115

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

122
## Types
123

124
```javascript { .api }
125
/**
126
 * Options for configuring regex analysis
127
 */
128
interface SafeRegexOptions {
129
  /** Maximum number of allowed repetitions in the regex (default: 25) */
130
  limit?: number;
131
}
132

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