From c3e203c2696e42ec107fe6a5a659fca54b2e4993 Mon Sep 17 00:00:00 2001
From: Efe Barlas <43009963+efebarlas@users.noreply.github.com>
Date: Wed, 15 Dec 2021 01:56:58 -0500
Subject: [PATCH] Update ReDoS section of security.md to accommodate #1683
 (#1828)

* Update ReDoS section of security.md

* Update docs/security.md

* Update docs/security.md

* Update docs/security.md

Co-authored-by: Evgeny Poberezkin <2769109+epoberezkin@users.noreply.github.com>
---
 docs/security.md | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/docs/security.md b/docs/security.md
index fcbfa7032..f4818b5b0 100644
--- a/docs/security.md
+++ b/docs/security.md
@@ -65,6 +65,26 @@ Certain regular expressions can lead to the exponential evaluation time even wit
 
 Please assess the regular expressions you use in the schemas on their vulnerability to this attack - see [safe-regex](https://github.com/substack/safe-regex), for example.
 
+By default, Ajv uses the regex engine built into Node.js. This engine has exponential worst-case performance. This performance (and ReDoS attacks) can be mitigated by using a linear-time regex engine. Ajv supports the use of a third-party regex engine for this purpose. 
+
+To use a third-party regex engine in Ajv, set the ajv.opts.code.regExp property to that regex engine during instantiation. Here we use Google’s RE2 engine as an example. 
+
+``` 
+const Ajv = require("ajv") 
+const RE2 = require("re2") 
+const ajv = new Ajv({regExp: RE2}) 
+``` 
+
+For details about the interface of the `regexp` option, see options.md under the docs folder. 
+
+Although linear-time regex engines eliminate ReDoS vulnerabilities, changing a regex engine carries some risk, including:  
+
+ - Minor changes in regex syntax. 
+ - Minor changes in regex semantics. For example, RE2 always interprets regexes in Unicode, and disagrees with JavaScript in its definition of whitespace. To avoid regressions, develop and test your regexes in the same regex engine that you use in production. 
+ - May not support some advanced features, such as look-aheads or back-references. 
+ - May have (minor) common-case performance degradation. 
+ - Increases size of distributable (e.g. RE2 includes a non-trivial C component). 
+
 ::: warning ReDoS attack
 Some formats that [ajv-formats](https://github.com/ajv-validator/ajv-formats) package implements use [regular expressions](https://github.com/ajv-validator/ajv-formats/blob/master/src/formats.ts) that can be vulnerable to ReDoS attack.
 :::