Documentation #3751
openAlert metadata JSON configs in suricata.yaml.in should match the RTD documentation
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.
Updated by Sascha Steinbiss over 4 years ago
- Priority changed from Normal to Low
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.
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 :)
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.
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.
Updated by Philippe Antoine over 1 year ago
- Assignee set to Community Ticket
- Target version set to TBD
Updated by Juliana Fajardini Reichow 2 months ago
- Status changed from New to In Review
It looks like https://github.com/OISF/suricata/pull/11767/commits/0db6d9606e3588d46d5e21b7101e67d01a42b44e fixed this. Is that right?
Updated by Sascha Steinbiss 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.
Updated by Juliana Fajardini Reichow 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 eitherno
or a sub-object with additional options -- however, the comment still mentionsDefault yes
. So ismetadata: 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.