From 37d9a5bed688792eec5993d080b793cfebd1303d Mon Sep 17 00:00:00 2001
From: Jeff Lucovsky <jlucovsky@oisf.net>
Date: Wed, 5 Feb 2025 16:03:08 -0500
Subject: [PATCH] doc/entropy: Add documentation for the entropy keyword

This commit updates the
- Upgrade notes for 7 to 8
- Payload keyword section

Both are update to document the new entropy keyword.
---
 doc/userguide/rules/payload-keywords.rst | 62 ++++++++++++++++++++++++
 doc/userguide/upgrade.rst                |  2 +
 2 files changed, 64 insertions(+)

diff --git a/doc/userguide/rules/payload-keywords.rst b/doc/userguide/rules/payload-keywords.rst
index 780ad111f7dc..11dd988f71ab 100644
--- a/doc/userguide/rules/payload-keywords.rst
+++ b/doc/userguide/rules/payload-keywords.rst
@@ -669,6 +669,68 @@ 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 and operator used to determine if the values agree.
+
+The minimum entropy keyword specification is::
+
+    entropy: value <entropy-spec>
+
+This results in the calculated entropy value being compared with
+`entropy-spec` using the (default) equality operator.
+
+Example::
+
+  entropy: 15.01
+
+A match occurs when the calculated entropy and specified entropy values agree.
+This is determined by calculating the entropy value and comparing it with the
+value from the rule using the specified operator.
+
+Example::
+
+  entropy: <15.01
+
+Options have default values:
+- bytes is equal to the current content length
+- offset is 0
+- equality comparison
+
+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>] value <operator><entropy-value>
+
+This example shows all possible options with default values and an entropy value of `4.037`::
+
+	entropy: bytes 0, offset 0,  value = 4.037
+
+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
+ * x-y Match when calculated value is within the exclusive range
+ * !x-y Match when calculated value is not within the exclusive range
+
+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; sid:1;)
+
 rpc
 ---
 
diff --git a/doc/userguide/upgrade.rst b/doc/userguide/upgrade.rst
index f5df98100fba..1a6d07cbe83a 100644
--- a/doc/userguide/upgrade.rst
+++ b/doc/userguide/upgrade.rst
@@ -89,6 +89,8 @@ Major changes
   Suricata 8.0, ``stream.checksum-validation`` no longer affects the checksum rule keywords.
   E.g., ``ipv4-csum: valid`` will only match if the check sum is valid, even when engine
   checksum validations are disabled.
+- New rule keyword ``entropy`` for alerting based on entropy values. See
+  :ref:`keyword_entropy`.
 
 Removals
 ~~~~~~~~