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
```