doc: improve documentation about guess-applayer-tx

Ticket: 7199

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

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
+**WARNING: If there are multiple live transactions, none will get
-picked up.
+picked up.** This is to reduce the chances of logging unrelated data, and may
-The alert event will have ``"tx_guessed": true`` to recognize
+lead to alerts being logged without metadata, in some cases.
-these alerts.
+The alert event will have ``tx_guessed: true`` to recognize
-
+such alerts.
 
 Metadata::
 

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
+  ``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.
+  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
 --------------------