detect/entropy: Unique flowvar names

doc/userguide/configuration/suricata-yaml.rst

@@ -538,13 +538,13 @@ In multi mode the filename takes a few special variables:
   - %n representing the thread number
   - %i representing the thread id
   - %t representing the timestamp (secs or secs.usecs based on 'ts-format')
-  
+
   Example: filename: pcap.%n.%t
 
 .. note:: It is possible to use directories but the directories are not
   created by Suricata. For example ``filename: pcaps/%n/log.%s`` will log into
   the pre-existing ``pcaps`` directory and per thread sub directories.
-  
+
 .. note:: that the limit and max-files settings are enforced per thread. So the
   size limit using 8 threads with 1000mb files and 2000 files is about 16TiB.
 
@@ -2145,8 +2145,8 @@ A logging line exists of two parts. First it displays meta information
 
   i: suricata: This is Suricata version 7.0.2 RELEASE running in USER mode
 
-(Here the part until the second `:` is the meta info, 
-"This is Suricata version 7.0.2 RELEASE running in USER mode" is the actual 
+(Here the part until the second `:` is the meta info,
+"This is Suricata version 7.0.2 RELEASE running in USER mode" is the actual
 message.)
 
 It is possible to determine which information will be displayed in
@@ -3028,6 +3028,25 @@ headers are encapsulated in the same number of headers.
 Advanced Options
 ----------------
 
+entropy
+~~~~~~~
+
+When a rule causes an entropy value to be calculated for a flow, output for the flow will include
+the calculated entropy value. The log output contains the sticky buffer name for which the
+entropy was calculated. Often, more context is needed and the configuration setting shown
+below will amend the sticky buffer name with the signature id and instance number from the rule
+that caused the entropy value calculation. The instance number changes for each ``entropy``
+keyword usage within a rule.  The default value is ``off``. We strongly recommend changing
+the value to ``on``.
+
+::
+
+    logging:
+        # Ensure that logged entropy values have unique names by appending the signature_id
+        # of the rule and other values where used
+        #entropy:
+            #make-unique: off
+
 stacktrace
 ~~~~~~~~~~
 Display diagnostic stacktraces when a signal unexpectedly terminates Suricata, e.g., such as
@@ -3086,7 +3105,7 @@ Suricata 7.0 default:
        #allow-rules: true
 
        # Upper bound of allocations by a Lua rule before it will fail
-       #max-bytes: 500000 
+       #max-bytes: 500000
 
        # Upper bound of lua instructions by a Lua rule before it will fail
        #max-instructions: 500000

doc/userguide/rules/payload-keywords.rst

@@ -749,6 +749,16 @@ the calculated entropy value with the buffer on which the value was computed::
         }
       }
 
+When ``logging.entropy.make-unique`` is enabled, the format is modified such
+that the signature id of the rule producing the entropy value and the occurrence
+value is included::
+
+     "metadata": {
+        "entropy": {
+          "file_data_391933_1": 4.265743301617466
+        }
+      }
+
 The events where entropy is logged will depend largely on how it's used within a
 rule and the rule's protocol.
 

src/detect-entropy.c

@@ -28,8 +28,39 @@
 
 #include "rust.h"
 
+/*
+ * Base size required for the entropy var name:
+ * - 17 (tags)
+ *   10 (max sid)
+ *   5 (separators)
+ *   2 (entropy instance cnt)
+ */
+#define ENTROPY_VAR_NAME_BASE_LEN (17 + 10 + 5 + 2)
+#define ENTROPY_VAR_NAME_FORMAT   "sid:%d;buffer:%s;instance:%d"
+
+static int DetectEntropyRuleInstanceCount(Signature *s)
+{
+    int entropy_cnt = 1;
+    for (uint32_t x = 0; x < s->init_data->buffer_index; x++) {
+        for (SigMatch *sm = s->init_data->buffers[x].head; sm != NULL; sm = sm->next) {
+            if (sm->type == DETECT_ENTROPY) {
+                ++entropy_cnt;
+            }
+        }
+    }
+
+    return entropy_cnt;
+}
+
 static int DetectEntropySetup(DetectEngineCtx *de_ctx, Signature *s, const char *arg)
 {
+
+    int unique_name;
+    SCConfGetBool("logging.entropy.make-unique", &unique_name);
+    if (unique_name) {
+        SCLogConfig("entropy values are marked with signature_id");
+    }
+
     DetectEntropyData *ded = SCDetectEntropyParse(arg);
     if (ded == NULL) {
         goto error;
@@ -41,8 +72,19 @@ static int DetectEntropySetup(DetectEngineCtx *de_ctx, Signature *s, const char
             goto error;
 
         sm_list = s->init_data->list;
-        ded->fv_idx = VarNameStoreRegister(
-                DetectEngineBufferTypeGetNameById(de_ctx, sm_list), VAR_TYPE_FLOW_FLOAT);
+        const char *var_name_ptr = DetectEngineBufferTypeGetNameById(de_ctx, sm_list);
+        if (unique_name) {
+            int entropy_cnt = DetectEntropyRuleInstanceCount(s);
+            SCLogDebug("There are a total of %d entropy usages in this rule", entropy_cnt);
+
+            char name_buf[ENTROPY_VAR_NAME_BASE_LEN + strlen(var_name_ptr)];
+            snprintf(name_buf, sizeof(name_buf), ENTROPY_VAR_NAME_FORMAT, s->id, var_name_ptr,
+                    entropy_cnt);
+
+            ded->fv_idx = VarNameStoreRegister(name_buf, VAR_TYPE_FLOW_FLOAT);
+        } else {
+            ded->fv_idx = VarNameStoreRegister(var_name_ptr, VAR_TYPE_FLOW_FLOAT);
+        }
     }
 
     if (SCSigMatchAppendSMToList(de_ctx, s, DETECT_ENTROPY, (SigMatchCtx *)ded, sm_list) != NULL) {

suricata.yaml.in

@@ -608,6 +608,15 @@ logging:
   # This value is overridden by the SC_LOG_LEVEL env var.
   default-log-level: notice
 
+  # Ensure that logged entropy values have unique names by including additional
+  # information in the logged output name: signature id, instance
+  # When off: file_data
+  # When on: sid:nnn;buffer:file_data:instance:1
+  # The default value is off; it is strongly recommended to change this
+  # value to on
+  #entropy:
+    #make-unique: off
+
   # The default output format.  Optional parameter, should default to
   # something reasonable if not provided.  Can be overridden in an
   # output section.  You can leave this out to get the default.