@@ -7,6 +7,43 @@ This is the matching library used internally by npm.
77It works by converting glob expressions into JavaScript ` RegExp `
88objects.
99
10+ ## Important Security Consideration!
11+
12+ > [ !WARNING]
13+ > This library uses JavaScript regular expressions. Please read
14+ > the following warning carefully, and be thoughtful about what
15+ > you provide to this library in production systems.
16+
17+ _ Any_ library in JavaScript that deals with matching string
18+ patterns using regular expressions will be subject to
19+ [ ReDoS] ( https://owasp.org/www-community/attacks/Regular_expression_Denial_of_Service_-_ReDoS )
20+ if the pattern is generated using untrusted input.
21+
22+ Efforts have been made to mitigate risk as much as is feasible in
23+ such a library, providing maximum recursion depths and so forth,
24+ but these measures can only ultimately protect against accidents,
25+ not malice. A dedicated attacker can _ always_ find patterns that
26+ cannot be defended against by a bash-compatible glob pattern
27+ matching system that uses JavaScript regular expressions.
28+
29+ To be extremely clear:
30+
31+ > [ !WARNING]
32+ > ** If you create a system where you take user input, and use
33+ > that input as the source of a Regular Expression pattern, in
34+ > this or any extant glob matcher in JavaScript, you will be
35+ > pwned.**
36+
37+ A future version of this library _ may_ use a different matching
38+ algorithm which does not exhibit backtracking problems. If and
39+ when that happens, it will likely be a sweeping change, and those
40+ improvements will ** not** be backported to legacy versions.
41+
42+ In the near term, it is not reasonable to continue to play
43+ whack-a-mole with security advisories, and so any future ReDoS
44+ reports will be considered "working as intended", and resolved
45+ entirely by this warning.
46+
1047## Usage
1148
1249``` js
@@ -396,6 +433,42 @@ separators in file paths for comparison.)
396433
397434Defaults to the value of ` process.platform ` .
398435
436+ ### maxGlobstarRecursion
437+
438+ Max number of non-adjacent ` ** ` patterns to recursively walk
439+ down.
440+
441+ The default of ` 200 ` is almost certainly high enough for most
442+ purposes, and can handle absurdly excessive patterns.
443+
444+ If the limit is exceeded (which would require very excessively
445+ long patterns and paths containing lots of ` ** ` patterns!), then
446+ it is treated as non-matching, even if the path would normally
447+ match the pattern provided.
448+
449+ That is, this is an intentional false negative, deemed an
450+ acceptable break in correctness for security and performance.
451+
452+ ### maxExtglobRecursion
453+
454+ Max depth to traverse for nested extglobs like ` *(a|b|c) `
455+
456+ Default is 2, which is quite low, but any higher value swiftly
457+ results in punishing performance impacts. Note that this is _ not_
458+ relevant when the globstar types can be safely coalesced into a
459+ single set.
460+
461+ For example, ` *(a|@(b|c)|d) ` would be flattened into
462+ ` *(a|b|c|d) ` . Thus, many common extglobs will retain good
463+ performance and never hit this limit, even if they are
464+ excessively deep and complicated.
465+
466+ If the limit is hit, then the extglob characters are simply not
467+ parsed, and the pattern effectively switches into `noextglob:
468+ true` mode for the contents of that nested sub-pattern. This will
469+ typically _ not_ result in a match, but is considered a valid
470+ trade-off for security and performance.
471+
399472## Comparisons to other fnmatch/glob implementations
400473
401474While strict compliance with the existing standards is a
0 commit comments