doc: improve documentation about guess-applayer-tx

Ticket: 7199

diff --git a/doc/userguide/configuration/suricata-yaml.rst b/doc/userguide/configuration/suricata-yaml.rst
index 7bcabdb77fedde6a1fb4d217294dd20bff8ce9e9..6956af8364377efc4f56889cd108cd5bbd207c35 100644 (file)
--- a/doc/userguide/configuration/suricata-yaml.rst
+++ b/doc/userguide/configuration/suricata-yaml.rst
@@ -632,6 +632,7 @@ The detection-engine builds internal groups of signatures. Suricata loads signat
       toserver-groups: 25
     sgh-mpm-context: auto
     inspection-recursion-limit: 3000
+    guess-applayer-tx: no
 
 At all of these options, you can add (or change) a value. Most
 signatures have the adjustment to focus on one direction, meaning
@@ -666,6 +667,12 @@ complicated issues. It could end up in an 'endless loop' due to a bug,
 meaning it will repeat its actions over and over again. With the
 option inspection-recursion-limit you can limit this action.
 
+The ``guess-applayer-tx`` option controls whether the engine will try to guess
+and tie a transaction to a given alert if the matching signature doesn't have
+app-layer keywords. If enabled, AND ONLY ONE LIVE TRANSACTION EXISTS, that
+transaction's data will be added to the alert metadata. Note that this may not
+be the expected data, from an analyst's perspective.
+
 *Example 4     Detection-engine grouping tree*
 
 .. image:: suricata-yaml/grouping_tree.png

diff --git a/doc/userguide/output/eve/eve-json-output.rst b/doc/userguide/output/eve/eve-json-output.rst
index f6ff28c8ae463f308878986638b9daa5018e032e..d9462952e1bf15fa7866f5ea56e4cc8913359bf9 100644 (file)
--- a/doc/userguide/output/eve/eve-json-output.rst
+++ b/doc/userguide/output/eve/eve-json-output.rst
@@ -71,11 +71,11 @@ can be used to force the detect engine to tie a transaction
 to an alert.
 This transaction is not guaranteed to be the relevant one,
 depending on your use case and how you define relevant here.
-If there are multiple live transactions, none will get
-picked up.
-The alert event will have ``"tx_guessed": true`` to recognize
-these alerts.
-
+**WARNING: If there are multiple live transactions, none will get
+picked up.** This is to reduce the chances of logging unrelated data, and may
+lead to alerts being logged without metadata, in some cases.
+The alert event will have ``tx_guessed: true`` to recognize
+such alerts.
 
 Metadata::
 

diff --git a/doc/userguide/upgrade.rst b/doc/userguide/upgrade.rst
index 816d7e22db2158e9586f5a0eb4dcaddc692fd068..6da52adb1f8862eb9698dea9394195530e8573a2 100644 (file)
--- a/doc/userguide/upgrade.rst
+++ b/doc/userguide/upgrade.rst
@@ -61,8 +61,11 @@ Upgrading to 7.0.8
             behavior.
 - Application layer metadata is logged with alerts by default **only for rules that
   use application layer keywords**. For other rules, the configuration parameter
-  ``detect.guess-applayer-tx`` can be used to force the detect engine to find a
-  transaction, which is not guaranteed to be the one you expect.
+  ``detect.guess-applayer-tx`` can be used to force the detect engine to guess a
+  transaction, which is not guaranteed to be the one you expect. **In this case,
+  the engine will NOT log any transaction metadata if there is more than one
+  live transaction, to reduce the chances of logging unrelated data.** This may
+  lead to what looks like a regression in behavior, but it is a considered choice.
 
 Upgrading 6.0 to 7.0
 --------------------