From 03aac436f0faf22202b9f835a2c029889e227a2e Mon Sep 17 00:00:00 2001
From: Jeff Lucovsky <jlucovsky@oisf.net>
Date: Mon, 13 Jan 2025 08:33:14 -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 | 51 ++++++++++++++++++++++++
 doc/userguide/upgrade.rst                |  2 +
 2 files changed, 53 insertions(+)

diff --git a/doc/userguide/rules/payload-keywords.rst b/doc/userguide/rules/payload-keywords.rst
index 780ad111f7dc..16466cbc08e2 100644
--- a/doc/userguide/rules/payload-keywords.rst
+++ b/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
 ---
 
diff --git a/doc/userguide/upgrade.rst b/doc/userguide/upgrade.rst
index 4bf74b65284d..cb5d3dec5bb8 100644
--- a/doc/userguide/upgrade.rst
+++ b/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
 ~~~~~~~~