Merge pull request #2993 in SNORT/snort3 from ~OSERHIIE/snort3:doc_js_identifier_norm...

Squashed commit of the following:

commit d90e8b5dd8961a932f872b65a97d99c84b8f3443
Author: Oleksandr Serhiienko <oserhiie@cisco.com>
Date:   Thu Jul 22 15:24:21 2021 +0300

    doc: update user for identifier normalization

diff --git a/doc/user/http_inspect.txt b/doc/user/http_inspect.txt
index 43b60f5656f41737f574328e469319c576e9ae82..4ba703dbffd88654b0e10edaebd26d5dcd7abc81 100755 (executable)
--- a/doc/user/http_inspect.txt
+++ b/doc/user/http_inspect.txt
@@ -162,9 +162,25 @@ normalizer provides more precise whitespace normalization of JavaScript, that
 removes all redundant whitespaces and line terminators from the JavaScript
 syntax point of view (between identifier and punctuator, between identifier and
 operator, etc.) according to ECMAScript 5.1 standard.
+Additionally, it performs normalization of JavaScript identifiers making a
+substitution of unique names with unified names representation: a0 -> z9999.
+The identifiers are variables and function names.
 The normalized data is available through the script_data rule option.
 This is currently experimental and still under development.
 
+===== js_norm_identifier_depth
+
+js_norm_identifier_depth = N {0 : 260000} will set a number of unique
+JavaScript identifiers to normalize. When the depth is reached, a built-in
+alert is generated. It's implemented per HTTP transaction (request/response),
+so the context of identifier substitutions is shared between all the scripts in
+the payload. By default, the value is set to 260000, which is the max allowed
+number of unique identifiers. The generated names are in the range from
+a0 to z9999. Thus, the number of unique identifiers cannot be greater than
+26 * 10000 = 260000. This option takes effect only if js_normalization_depth is
+set to a non-zero value, enabling the enhanced normalizer.
+This is currently experimental and still under development.
+
 ===== xff_headers
 
 This configuration supports defining custom x-forwarded-for type headers. In a