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 8400f92193a5943dbbad41b2edda058b2e9d5c8e..8004ecce9167ed96c9c456c5650f4403dbbaca7c 100644 (file)
--- a/doc/userguide/configuration/suricata-yaml.rst
+++ b/doc/userguide/configuration/suricata-yaml.rst
@@ -660,6 +660,7 @@ The detection-engine builds internal groups of signatures. Suricata loads signat
     sgh-mpm-context: auto
     inspection-recursion-limit: 3000
     stream-tx-log-limit: 4
+    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
@@ -694,11 +695,17 @@ 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 stream-tx-log-limit defines the maximum number of times a
+The ``stream-tx-log-limit`` defines the maximum number of times a
 transaction will get logged for rules without app-layer keywords.
 This is meant to avoid logging the same data an arbitrary number
 of times.
 
+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 da80a3fd196bf1b140896e5d42f4395309f7746e..580504d1f7ea4ad53a6429f7221ebca0af5bfc01 100644 (file)
--- a/doc/userguide/output/eve/eve-json-output.rst
+++ b/doc/userguide/output/eve/eve-json-output.rst
@@ -79,11 +79,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 2b16dd31a35cad648d3260b92a5a19e32524fe05..4bf74b65284dffa858c4ff55243079b9c6c19b23 100644 (file)
--- a/doc/userguide/upgrade.rst
+++ b/doc/userguide/upgrade.rst
@@ -101,8 +101,11 @@ Logging changes
   sometimes logged with a dash instead of an underscore.
 - 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
 --------------------