Project

General

Profile

Actions

Documentation #5182

open

userguide: better document rule keywords

Added by Juliana Fajardini Reichow 9 months ago. Updated about 1 month ago.

Status:
New
Priority:
High
Target version:
Affected Versions:
Effort:
Difficulty:
Label:

Description

This could probably become more than just one ticket.
The motivation behind it is that there are many rule keywords
that are mentioned but lack proper explanation on what they are/
how they related to what is seen on the wire.
Example: dzise (https://suricata.readthedocs.io/en/latest/rules/payload-keywords.html#dsize)

Improving that would be great.


Subtasks 17 (15 open2 closed)

Documentation #2588: document hostbits keywordNewOISF DevActions
Documentation #3015: Missing documentation for "tag" keywordNewOISF DevActions
Documentation #3018: No documentation for "flowvar" keywordNewOISF DevActions
Documentation #3025: Missing docs for "http." keywordsNewOISF DevActions
Documentation #3028: No documentation for "pkt_data" keywordNewOISF DevActions
Documentation #3030: doc: document for "smb" keywordsClosedEric LeblondActions
Documentation #3031: No documentation for "asn1" keywordNewOISF DevActions
Documentation #3033: No documentation for "stream-event" keywordNewOISF DevActions
Documentation #3034: No documentation for "l3_proto" keywordNewOISF DevActions
Documentation #3036: No documentation for "template2" keywordNewOISF DevActions
Documentation #3748: Add documentation for flags keywordNewActions
Documentation #5068: nfs: document rule keywordNewCommunity TicketActions
Documentation #5088: file.name sticky buffer is not documentedNewOISF DevActions
Documentation #5385: userguide: update rule's format documentClosedJason TaylorActions
Documentation #5485: userguide: explain that the http.header_names buffer is normalizedNewOISF DevActions
Documentation #5519: userguide: update 'dsize' examples and documentationIn ReviewJason TaylorActions
Documentation #5523: userguide: document the tcp-stream keywordNewOISF DevActions
Actions #1

Updated by Juliana Fajardini Reichow 9 months ago

  • Description updated (diff)
Actions #2

Updated by Jason Taylor 7 months ago

I was looking at the http keyword docs at https://suricata.readthedocs.io/en/latest/rules/http-keywords.html and it got me wondering what the best way to display some of the data is?

Some of the pictures in this case, method.png, is being used to illustrate the GET method and keyword usage. In this case the paragraph above the image mentions http.method but the picture references http_method.

I wonder if this sort of scenario is confusing to new rule writers?

Is there an alternative to images that we would want to consider?

I ask because before starting to document new keywords, I am curious if how things are currently layed-out/explained are what we want to continue with?

Thanks in advance!

JT

Actions #3

Updated by Juliana Fajardini Reichow 7 months ago

Jason Taylor wrote in #note-2:

I was looking at the http keyword docs at https://suricata.readthedocs.io/en/latest/rules/http-keywords.html and it got me wondering what the best way to display some of the data is?

Some of the pictures in this case, method.png, is being used to illustrate the GET method and keyword usage. In this case the paragraph above the image mentions http.method but the picture references http_method.

I wonder if this sort of scenario is confusing to new rule writers?

I can see that happening - we do mention that there are newer versions of the keywords in other,
so hopefully although not ideal, not so harmful we'd have to remove them altogether.

Is there an alternative to images that we would want to consider?

I ask because before starting to document new keywords, I am curious if how things are currently layed-out/explained are what we want to continue with?

Thanks in advance!

JT

Hello JT, thanks for your input!

In general, I think we try to avoid adding images and diagrams when we can, for the reason you just pointed out:
they tend to get outdated and are harder to change and maintain than code/text.

From my experience, when we do think diagrams are needed, we have been trying to move towards images or representations
that are easier to maintain and update (for example, diagrams that were generated from a text schema: https://suricata.readthedocs.io/en/latest/devguide/extending/app-layer/transactions.html#sequence-diagrams).

But I understand that is not always feasible, so it's a trade-off between how much effort it would be required to find
a more maintainable solution, and the time you have available for the task.

To summarize:
- images are not mandatory
- we prefer to have alternatives that can be autogenerated and are easier to update and track when we do have images

(I hope this answered your questions!)

Actions #4

Updated by Jason Taylor 7 months ago

Juliana Fajardini Reichow wrote in #note-3:

Jason Taylor wrote in #note-2:

I was looking at the http keyword docs at https://suricata.readthedocs.io/en/latest/rules/http-keywords.html and it got me wondering what the best way to display some of the data is?

Some of the pictures in this case, method.png, is being used to illustrate the GET method and keyword usage. In this case the paragraph above the image mentions http.method but the picture references http_method.

I wonder if this sort of scenario is confusing to new rule writers?

I can see that happening - we do mention that there are newer versions of the keywords in other,
so hopefully although not ideal, not so harmful we'd have to remove them altogether.

Is there an alternative to images that we would want to consider?

I ask because before starting to document new keywords, I am curious if how things are currently layed-out/explained are what we want to continue with?

Thanks in advance!

JT

Hello JT, thanks for your input!

In general, I think we try to avoid adding images and diagrams when we can, for the reason you just pointed out:
they tend to get outdated and are harder to change and maintain than code/text.

From my experience, when we do think diagrams are needed, we have been trying to move towards images or representations
that are easier to maintain and update (for example, diagrams that were generated from a text schema: https://suricata.readthedocs.io/en/latest/devguide/extending/app-layer/transactions.html#sequence-diagrams).

But I understand that is not always feasible, so it's a trade-off between how much effort it would be required to find
a more maintainable solution, and the time you have available for the task.

To summarize:
- images are not mandatory
- we prefer to have alternatives that can be autogenerated and are easier to update and track when we do have images

(I hope this answered your questions!)

It did, I will put together a PR to get your thoughts and we can go from there. Thanks! (Sorry for the delayed response, I didn't get a notification the ticket got updated, I forgot to watch this :)).

Actions #5

Updated by Juliana Fajardini Reichow 4 months ago

  • Subtask #5088 added
Actions #6

Updated by Juliana Fajardini Reichow 4 months ago

  • Subtask #5068 added
Actions #7

Updated by Juliana Fajardini Reichow 4 months ago

  • Subtask #3748 added
Actions #8

Updated by Juliana Fajardini Reichow 4 months ago

  • Subtask #3036 added
Actions #9

Updated by Juliana Fajardini Reichow 4 months ago

  • Subtask #3034 added
Actions #10

Updated by Juliana Fajardini Reichow 4 months ago

  • Subtask #3033 added
Actions #11

Updated by Juliana Fajardini Reichow 4 months ago

  • Subtask #3031 added
Actions #12

Updated by Juliana Fajardini Reichow 4 months ago

  • Subtask #3030 added
Actions #13

Updated by Juliana Fajardini Reichow 4 months ago

  • Subtask #3028 added
Actions #14

Updated by Juliana Fajardini Reichow 4 months ago

  • Subtask #3025 added
Actions #15

Updated by Juliana Fajardini Reichow 4 months ago

  • Subtask #3018 added
Actions #16

Updated by Juliana Fajardini Reichow 4 months ago

  • Subtask #3015 added
Actions #17

Updated by Juliana Fajardini Reichow 4 months ago

  • Subtask #2588 added
Actions #18

Updated by Juliana Fajardini Reichow 4 months ago

  • Subtask #5485 added
Actions #19

Updated by Juliana Fajardini Reichow 4 months ago

  • Subtask #5519 added
Actions #20

Updated by Juliana Fajardini Reichow 3 months ago

  • Subtask #5523 added
Actions

Also available in: Atom PDF