userguide: explain rule types and categorization - v9 #12209
Conversation
Add documentation about the rule types introduced by 2696fda. Add doc tags around code definitions that are referenced in the docs. Task #https://redmine.openinfosecfoundation.org/issues/7031
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## master #12209 +/- ##
==========================================
+ Coverage 83.17% 83.18% +0.01%
==========================================
Files 912 912
Lines 257111 257111
==========================================
+ Hits 213856 213885 +29
+ Misses 43255 43226 -29
Flags with carried forward coverage won't be shown. Click here to find out more. |
| * - IP Only | ||
| - Flow | ||
| - Once per direction | ||
| - On IP addresses on the flow | ||
| - Source/ Destination field of a rule | ||
| * - IP Only (contains negated address)(*) | ||
| - Flow | ||
| - Once per direction | ||
| - On IP addresses on the flow | ||
| - Source/ Destination field of a rule, containing negated address |
There was a problem hiding this comment.
Action is flow if flow exists. Packets that are not part of a flow, .... will always be inspected per packet.
| - Source/ Destination field of a rule | ||
| * - IP Only (contains negated address)(*) | ||
| - Flow | ||
| - Once per direction |
There was a problem hiding this comment.
Test this with rule profiling to confirm.
There was a problem hiding this comment.
Maybe we can have a SV test with like-ip-only
- alert rule: several alerts
- drop/pass: should be applied to the flow
| - Packet | ||
| - Per-packet basis | ||
| - Packet-level info (e.g.: header info) | ||
| - ``itype``, ``tcp.hdr``, ``tcp.seq``, ``ttl`` etc. |
There was a problem hiding this comment.
tcp-pkt - add as keyword example here
| - Flow, if stateful (**) | ||
| - Per stream chunk, if stateful, per-packet if not. | ||
| - Against the reassembled stream. If stream unavailable, match per-packet. | ||
| (stream payload or packet payload) |
There was a problem hiding this comment.
move to Inspected, be stream payload AND packet payload
There was a problem hiding this comment.
exposes the stream and/or payload data.
| * - Type | ||
| - Action Scope | ||
| - Inspected | ||
| - Matches |
|
|
||
| * - Type | ||
| - Action Scope | ||
| - Inspected |
There was a problem hiding this comment.
Inspection hook?
| - Keyword Examples (non-exhaustive) | ||
| * - Decoder Events Only | ||
| - Packet | ||
| - Per-packet basis |
There was a problem hiding this comment.
Per-broken/ invalid packet
| * - Decoder Events Only | ||
| - Packet | ||
| - Per-packet basis | ||
| - Packets that are broken on an IP level |
| - ``content`` with ``startswith`` or ``depth`` | ||
| * - Stream | ||
| - Flow, if stateful (**) | ||
| - Per stream chunk, if stateful, per-packet if not. |
There was a problem hiding this comment.
Stream chunks, or just packets (if not accepted by stream engine)
| * - Stream | ||
| - Flow, if stateful (**) | ||
| - Per stream chunk, if stateful, per-packet if not. | ||
| - Against the reassembled stream. If stream unavailable, match per-packet. |
There was a problem hiding this comment.
exposes stream reassembled payload or packet payload data
| - Application Layer (`app_layer`) | ||
| - Protocol Detection Only (`pd_only`) | ||
| - Decoder Events Only (`de_only`) |
| The rule examples provided further cover some such cases, but the table below | ||
| lists those keywords with more details: | ||
|
|
There was a problem hiding this comment.
check detect-flowbits.c:632. some cases will make a packet rule become a stateful / app_tx signature.
|
@njlavigne There will be a new version of this coming out soon to take into account a review done with Victor, but do feel free to add feedback, please, if you see anything weird or missing :) |
| aspects aforementioned. | ||
|
|
||
| .. list-table:: Suricata Rule Types | ||
| :widths: 10, 17, 18, 30, 25 |
There was a problem hiding this comment.
Review width for last 2 columns, especially.
There was a problem hiding this comment.
the rtd theme isn't properly rendering list-table widths properly - it's ignoring this, basically.
The best workaround I've found was using nested paragraphs, as it seems that the width is being based on the column header, and this seems to be working.
|
Given the embedded code, etc. I wonder if this is a little too deep to from the rule chapter. Is it better suited at the end with some "rule internals" or part of a Suricata internals guide? At first I was wondering devguide, but I do realize there is some internals that should be documented with a power user audience, and not necessarily a developer audience. |
|
Information: QA ran without warnings. Pipeline 23656 |
We have Making sense out of alerts, right after the two Rules chapters. Maybe we could have this part about the rule types before or after that one? I understand it has more advanced stuff, but I think semantically it also makes sense that it remains close to the other chapters. imho, the code excerpts that we show aren't mandatory to understand the contents - more to add hooks for those who like to dig... |
Maybe move it to the end of the rules chapter? My thought are:
To be fair, advanced rule writing could be its own book I'm sure! |
Previous PR: #12184
Link to ticket: https://redmine.openinfosecfoundation.org/issues/
https://redmine.openinfosecfoundation.org/issues/7031
Please check the built version: https://suri-rtd-test.readthedocs.io/en/doc-sigtypes-et-properties-v9/rules/rule-types.html
Describe changes:
Many of the examples and conclusions documented here were derived from tests and checks as seen on OISF/suricata-verify#2153