Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Backports/708/v3 #12267

Closed
wants to merge 3 commits into from
Closed

Backports/708/v3 #12267

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
63033e3
detect: log app-layer metadata in alert with single tx
catenacyber Nov 26, 2024
f5322d2
detect: re-add app-layer to alerts on stream matches
victorjulien Dec 11, 2024
a293a7c
doc: improve documentation about guess-applayer-tx
catenacyber Dec 11, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions doc/userguide/configuration/suricata-yaml.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
10 changes: 5 additions & 5 deletions doc/userguide/output/eve/eve-json-output.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you want to add there that we also log some transaction metadata for rule with stream matches ?
And that the first transaction is logged, like one TCP packet with 3 DNS requests to suricata.io oisf.net and suricon.net and rule alert tcp any any -> any any (content: "suricon"; sid: 1) will log the request to suricata.io

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems all too much of a low level implementation detail to discuss in configuration docs. But these types of issues are making me think we need a know issues and shortcomings chapter.


Metadata::

Expand Down
7 changes: 5 additions & 2 deletions doc/userguide/upgrade.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
--------------------
Expand Down
Loading