Project

General

Profile

Actions
Copy link

Documentation #3751

open

Alert metadata JSON configs in suricata.yaml.in should match the RTD documentation

Added by Sascha Steinbiss over 4 years ago. Updated about 2 months ago.

Status:
New
Priority:
Low
Assignee:
Community Ticket
Target version:
TBD
Affected Versions:
Effort:
Difficulty:
Label:

Description

It would be nice if the suricata.yaml.in file -- and hence the default configuration file -- contained at least a commented out version of the detailed alert metadata configuration, i.e. the

- alert:
    #payload: yes             # enable dumping payload in Base64
    #payload-buffer-size: 4kb # max size of payload buffer to output in eve-log
    #payload-printable: yes   # enable dumping payload in printable (lossy) format
    #packet: yes              # enable dumping of packet (without stream segments)
    #http-body: yes           # Requires metadata; enable dumping of http body in Base64
    #http-body-printable: yes # Requires metadata; enable dumping of http body in printable format

    # metadata:

      # Include the decoded application layer (ie. http, dns)
      #app-layer: true

      # Log the the current state of the flow record.
      #flow: true

      #rule:
        # Log the metadata field from the rule in a structured
        # format.
        #metadata: true

        # Log the raw rule text.
        #raw: false

The ReadtheDocs documentation shows it (https://suricata.readthedocs.io/en/latest/output/eve/eve-json-output.html#alerts) but the suricata.yaml.in only shows the metadata: yes/no switch (https://github.com/OISF/suricata/blob/master/suricata.yaml.in#L152). For someone who uses the example fileand its comments as option documentation (such as me) that's a bit inconvenient.
------------

Edit: this task will be considered completed when both the documentation and the suricata.yaml.in explanation comment clearly indicate what enabling or disabling metadata means to the EVE output, and the metadata options. The documentation should ideally include one or more examples.

Actions
Copy link
 #1

Updated by Sascha Steinbiss over 4 years ago

  • Priority changed from Normal to Low
Actions
Copy link
 #2

Updated by Jason Ish over 4 years ago

How about a link to the documentation? I think the idea here, and in other parts of the configuration is that the documentation should be the reference, while we try to keep the default configuration a little smaller. But I do struggle a bit with this myself. I often want to log the full rule and get it wrong the first time.

Actions
Copy link
 #3

Updated by Sascha Steinbiss over 4 years ago

A link to the documentation is the minimum, I think. I always considered the suricata.yaml as a snapshot of what the complete configuration would look like in the default state (which is also helpful to diff between versions to find out what to update). Only having a subset of the possible configuration items in there would hide good functionality from users. Just my 2 cents :)

Actions
Copy link
 #4

Updated by Jason Ish over 4 years ago

Sascha Steinbiss wrote in #note-3:

Only having a subset of the possible configuration items in there would hide good functionality from users. Just my 2 cents :)

Yeah, its an active area of discussion. A complete suricata.yaml is pretty daunting for new users, given most of it doesn't need to be touched. I think Andreas is actively looking into better ways here.

Actions
Copy link
 #5

Updated by Andreas Herz over 4 years ago

I would go with the doc link as a first quick win and include the other issue within the whole discussion. We still struggle to find the best solution to that.

Actions
Copy link
 #6

Updated by Philippe Antoine over 1 year ago

  • Assignee set to Community Ticket
  • Target version set to TBD
Actions
Copy link
 #7

Updated by Juliana Fajardini Reichow about 2 months ago

  • Status changed from New to In Review
Actions
Copy link
 #8

Updated by Sascha Steinbiss about 2 months ago ยท Edited

Juliana Fajardini Reichow wrote in #note-7:

It looks like https://github.com/OISF/suricata/pull/11767/commits/0db6d9606e3588d46d5e21b7101e67d01a42b44e fixed this. Is that right?

Better! But it still looks (from https://github.com/OISF/suricata/pull/11767/files#diff-6edad567c7414ca3b78009e7d315547542cbb77455e7a223c11719d2734fd3db) like metadata can be either no or a sub-object with additional options -- however, the comment still mentions Default yes. So is metadata: yes a proper configuration, and what would that imply for the additional options?

Sure, one can take a look at the code to see how it is evaluated but I think it should also be clear from the example configuration.

Actions
Copy link
 #9

Updated by Juliana Fajardini Reichow about 2 months ago

  • Description updated (diff)
  • Status changed from In Review to New

Sascha Steinbiss wrote in #note-8:

Juliana Fajardini Reichow wrote in #note-7:

It looks like https://github.com/OISF/suricata/pull/11767/commits/0db6d9606e3588d46d5e21b7101e67d01a42b44e fixed this. Is that right?

Better! But it still looks (from https://github.com/OISF/suricata/pull/11767/files#diff-6edad567c7414ca3b78009e7d315547542cbb77455e7a223c11719d2734fd3db) like metadata can be either no or a sub-object with additional options -- however, the comment still mentions Default yes. So is metadata: yes a proper configuration, and what would that imply for the additional options?

Sure, one can take a look at the code to see how it is evaluated but I think it should also be clear from the example configuration.

Can't disagree with that! Thanks for you feedback, this remains open, then. I've also added a bit in terms of expectations for completion.

Actions
Copy link

Also available in: Atom PDF