Project

General

Profile

Actions

Documentation #5182

open

userguide: better document rule keywords

Added by Juliana Fajardini Reichow about 2 years ago. Updated about 17 hours ago.

Status:
New
Priority:
Normal
Assignee:
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 19 (13 open6 closed)

Documentation #2588: document hostbits keywordNewOISF DevActions
Documentation #3015: userguide: document "tag" keywordResolvedVictor JulienActions
Documentation #6511: userguide: document "tag" keyword (7.0.x backport)ClosedVictor JulienActions
Documentation #3018: No documentation for "flowvar" keywordNewOISF DevActions
Documentation #3025: Missing docs for "http." keywordsIn ProgressJason TaylorActions
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 keywordNewCommunity TicketActions
Documentation #5068: nfs: document rule keywordNewCommunity TicketActions
Documentation #5088: file.name sticky buffer is not documentedClosedJason TaylorActions
Documentation #5385: userguide: update rule's format documentClosedJason TaylorActions
Documentation #5485: userguide: explain that the http.header_names buffer is normalizedNewJason TaylorActions
Documentation #5519: userguide: update 'dsize' examples and documentationClosedJason TaylorActions
Documentation #5523: userguide: document the tcp-stream keywordNewOISF DevActions
Documentation #6386: Add tls.cert_chain_len DocumentationClosedJason TaylorActions

Related issues 1 (0 open1 closed)

Related to Suricata - Task #5626: doc: document file.dataClosedJason TaylorActions
Actions #1

Updated by Juliana Fajardini Reichow about 2 years ago

  • Description updated (diff)
Actions #2

Updated by Jason Taylor almost 2 years 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 almost 2 years 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 almost 2 years 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 over 1 year ago

  • Subtask #5088 added
Actions #6

Updated by Juliana Fajardini Reichow over 1 year ago

  • Subtask #5068 added
Actions #7

Updated by Juliana Fajardini Reichow over 1 year ago

  • Subtask #3748 added
Actions #8

Updated by Juliana Fajardini Reichow over 1 year ago

  • Subtask #3036 added
Actions #9

Updated by Juliana Fajardini Reichow over 1 year ago

  • Subtask #3034 added
Actions #10

Updated by Juliana Fajardini Reichow over 1 year ago

  • Subtask #3033 added
Actions #11

Updated by Juliana Fajardini Reichow over 1 year ago

  • Subtask #3031 added
Actions #12

Updated by Juliana Fajardini Reichow over 1 year ago

  • Subtask #3030 added
Actions #13

Updated by Juliana Fajardini Reichow over 1 year ago

  • Subtask #3028 added
Actions #14

Updated by Juliana Fajardini Reichow over 1 year ago

  • Subtask #3025 added
Actions #15

Updated by Juliana Fajardini Reichow over 1 year ago

  • Subtask #3018 added
Actions #16

Updated by Juliana Fajardini Reichow over 1 year ago

  • Subtask #3015 added
Actions #17

Updated by Juliana Fajardini Reichow over 1 year ago

  • Subtask #2588 added
Actions #18

Updated by Juliana Fajardini Reichow over 1 year ago

  • Subtask #5485 added
Actions #19

Updated by Juliana Fajardini Reichow over 1 year ago

  • Subtask #5519 added
Actions #20

Updated by Juliana Fajardini Reichow over 1 year ago

  • Subtask #5523 added
Actions #21

Updated by Jason Taylor 6 months ago

Actions #22

Updated by Shivani Bhardwaj 6 months ago

Actions #23

Updated by Shivani Bhardwaj 6 months ago

  • Subtask #6386 added
Actions #24

Updated by Juliana Fajardini Reichow 5 months ago

  • Related to Task #5626: doc: document file.data added
Actions #25

Updated by Victor Julien 3 months ago

  • Assignee changed from Juliana Fajardini Reichow to OISF Dev
Actions

Also available in: Atom PDF