DOCUMENTATION: Improve documentation for configuring Playbook alerts and custom filters

[thedeadliestcatch]

I'm reproducing the original description prior to its conversion into a discussion (#12705) which is unfitting and dismissive, considering that it pertains to 1) a clear issue that can be addressed and tracked as such 2) a general user-base issue/improvement

The documentation for configuring Playbook -alert- filters is sorely lacking.

For instance, valuable documentation missing includes:

Compound filters depending on multiple conditionals (ex. host, process executable, parent process executable).
Compound filters using hosts lists.
How to use any context variables in the filter.

There are many playbook rules that remain inactive by default that are quite useful in real-world setups, but need fine tuning due to false positives, for example in container environments. The documentation currently has no real content about configuration of said filters, and the publicly available information is also deficient. This most likely results in people just deactivating the problematic rules.... a zero-sum game.

Please do not frivolously convert issues into "discussions" as it makes them impossible to track, and more often than not, they are never seen again. It also inflates the apparent number of closed issues versus open ones, which is not a good measure of effective QA, even if it makes it more satisfying for the team to wake up to an (artificially) short list of problems.

Case in point, the present situation with #12653 originated from several (not just one) messages after the original issue was dismissed here. I'm sure we can do better.

[thedeadliestcatch]

A follow-up:

The current documentation is limited to https://docs.securityonion.net/en/2.3/playbook.html#tuning-plays

The sofilter syntax is important - add as many top-level filter clauses as you need, but they should all start with sofilter - for example sofilter1, sofilter2

The examples should include multiple cases, the existent one is also potentially meaningless to most users, since we are not explaining where User comes from:

sofilter:
  User: SA_ITOPS

There should be proper clarification to what is permitted or supported, where to find the key names (users, process name, etc), and if these can be applied in a conditional way, etc.

Amusingly enough, this has become the first search engine hit for documentation on filtering Playbook alerts :-)

[thedeadliestcatch]

Let's take the following rule/play:

https://github.com/SigmaHQ/sigma/blob/master/rules/linux/file_event/file_event_lnx_wget_download_file_in_tmp_dir.yml

Tentatively, an user might find that a legitimate script generates a false positive while downloading to the /tmp directory (say, in a LXC container), and the existent documentation will provide no useful information as to how he can adapt the play/rule to his environment.

Given the following:

detection:
    selection:
        Image|endswith: '/wget'
        TargetFilename|startswith:
            - '/tmp/'
            - '/var/tmp/'
    condition: selection

The documentation ideally should answer:

• How can the user configure a conditional mutual exclusion case where TargetFilename and Image match but another context variable does not (ex. Match against a parent process image, or the running user, or the host itself).
• What context variables are available and how he can use them to produce a "discard" path for the alert without an overly inclusive set of conditionals.