detect/entropy: Add entropy keyword

doc/userguide/rules/meta.rst

@@ -225,7 +225,7 @@ errors.
 
 Requirements that follow the valid format of ``<keyword>
 <expression>`` but are not known to Suricata are allowed for future
-compatiblity, however unknown requirement expressions will lead to the
+compatibility, however unknown requirement expressions will lead to the
 requirement not being met, skipping the rule.
 
 When parsing rules, the parser attempts to process the ``requires``

doc/userguide/rules/payload-keywords.rst

@@ -669,6 +669,57 @@ Example::
 	 flow:established,to_server; content:"|00 FF|"; \
 	 byte_extract:2,0,cmp_ver,relative; content:"FooBar"; distance:0; byte_test:2,=,cmp_ver,0; sid:3;)
 
+.. _keyword_entropy:
+
+entropy
+-------
+
+The ``entropy`` keyword calculates the Shannon entropy value for content and compares it with
+an entropy value. When there is a match, rule processing will continue.
+
+The ``entropy`` keyword syntax is the keyword entropy followed by options
+and the entropy value for comparison.
+
+The minimum entropy keyword specification is::
+
+    entropy: value <entropy-val>
+
+This results in the calculated entropy value being compared with
+`entropy-val` using the equality operator.
+
+A match occurs when the values and operator agree. This example matches
+if the calculated and entropy value are the same.
+
+Options have default values:
+- bytes is equal to the current content length
+- offset is 0
+- oper is the equality operator: "=="
+
+When entropy keyword options are specified, all options and "value" must
+be comma-separated. Options and value may be specified in any order.
+
+The complete format for the ``entropy`` keyword is::
+
+	entropy: [bytes <byteval>] [offset <offsetval>] [oper <operval>] value <entropy-val>
+
+This example shows all possible options with default values::
+
+	entropy: bytes 0, offset 0, oper ==, value <entropy-val>
+
+The following operators are available::
+
+ * == (default): Match when calculated value equals entropy value
+ * < Match when calculated value is strictly less than entropy value
+ * <=  Match when calculated value is less than or equal to entropy value
+ * > Match when calculated value is strictly greater than entropy value
+ * >= Match when calculated value is greater than or equal to entropy value
+ * !=  Match when calculated value is not equal to entropy value
+
+This example matches if the `file.data` content for an HTTP transaction has
+a Shannon entropy value of 4 or higher::
+
+	alert http any any -> any any (msg:"entropy simple test"; file.data; entropy: value 4, oper >=; sid:1;)
+
 rpc
 ---
 

doc/userguide/upgrade.rst

@@ -82,6 +82,8 @@ Major changes
 - Unknown requirements in the ``requires`` keyword will now be treated
   as unmet requirements, causing the rule to not be loaded. See
   :ref:`keyword_requires`.
+- New rule keyword ``entropy`` for alerting based on entropy values. See
+  :ref:`keyword_entropy`.
 
 Removals
 ~~~~~~~~