RFC - WIP - userguide: explain rule types and categorization - v1 #12089
Conversation
Add documentation about the rule types introduced by 2696fda.
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## master #12089 +/- ##
==========================================
- Coverage 83.25% 83.25% -0.01%
==========================================
Files 910 910
Lines 257571 257571
==========================================
- Hits 214450 214437 -13
- Misses 43121 43134 +13
Flags with carried forward coverage won't be shown. Click here to find out more. |
| * - Decode Events Only | ||
| - Packet | ||
| - Per-packet basis | ||
| - Packets that are broken on an IP address level |
| - Packet | ||
| - Per-packet basis | ||
| - Packets that are broken on an IP address level | ||
| - --- |
| - Packet | ||
| - Per-packet basis | ||
| - Packet-level info (e.g.: header info, ttl...) | ||
| - --- |
There was a problem hiding this comment.
Can we move (e.g. ttl) to "Example" column?
| * - IP Only (negated address) | ||
| - Flow | ||
| - Once per direction | ||
| - On the flow, on IP address level (negated addressed) | ||
| - --- |
There was a problem hiding this comment.
My understanding and opinion is that negated address will be resolved internally and have the same properties as above so we can merge these and mention that we could have negated addresses.
There was a problem hiding this comment.
there is special handling for sigs that could be ip-only, but contain address negation. The radix based implementation doesn't support this, so there is a special "like ip-only" logic to make this sigs behave more or less the same as non-negated ip-only
There was a problem hiding this comment.
I see. Need to study the code to understand this properly.
ok so, questions:
- does this information concern the user?
- does it make sense to mention it separately? or rather, can we explain why is it separately mentioned w/o going into the internals somehow?
There was a problem hiding this comment.
it is at least visible to the use in the engine analysis
There was a problem hiding this comment.
I think I would rather do something like 2. I want to offer a good insight on how Suricata actually handles things, because sometimes the low level details will impact difference in behaviors that might otherwise not make sense. (Not sure if my words here make enough sense xD )
| * - IP Only | ||
| - Flow | ||
| - Once per direction | ||
| - On the flow, on IP address level |
There was a problem hiding this comment.
not sure about the language "on IP address level"
There was a problem hiding this comment.
Okie. Do you have a suggestion?
There was a problem hiding this comment.
Maybe "Matches on the IP address on the flow"?
| * - Protocol Detection Only | ||
| - Flow | ||
| - Once per direction, when protocol detection is done | ||
| - app-layer-protocol keyword |
There was a problem hiding this comment.
Suggestion: Matches protocol detected for the flow
Feel free to change the words but this seemed redundant as the keyword is mentioned in the examples
| - Match on payload | ||
| - Match against the reassembled stream. If stream unavailable, match per-packet |
There was a problem hiding this comment.
Q: When do we match against a not reassembled stream? IPS mode?
Comment: These two statements are confusing. Match on payload but also stream?
There was a problem hiding this comment.
Another thing: "Stream" seems to be used on a stream only condition so no pkt match. Someone should verify if this is correct..
There was a problem hiding this comment.
Rules with scope 'flow, if stateful', will apply to the stream if the reassembled stream is available - which may stop being the case if we reach stream-depth, for instance. In that case, the rules will be applied on a packet-level. The difficulty is explaining this on a higher level...
There was a problem hiding this comment.
Q: When do we match against a not reassembled stream? IPS mode?
I guess... when we match against payload keywords, or header keywords, or, say, just the protocol...?
There was a problem hiding this comment.
These two statements are confusing. Match on payload but also stream?
I can see, even based on my previous message, how it is indeed too confusing >__<
There was a problem hiding this comment.
just the protocol...?
Just the protocol, yes indeed. Payload keywords and header keywords not sure as they could be fragmented I suppose.. 🤔
| - Match against the reassembled stream. If stream unavailable, match per-packet | ||
| - Flow, if stateful, per-packet if not | ||
| - 'content' with 'starts with' or 'depth' | ||
| * - Stream |
There was a problem hiding this comment.
Example: flow keywords?
Edit: Nope
|
Followed by: #12105 |
Add documentation about the rule types introduced by commit 2696fda.
Compiled docs: https://suri-rtd-test.readthedocs.io/en/doc-sigtypes-et-properties-v1/rules/intro.html#rule-s-types-and-categorization
This is a WIP, the table needs reviewing and expanding:
TODO:
There are some workflows that I would like to add to the documentation, too, somehow, but must find a good solution for not simply bringing images, but ideally something that can be generated from code description.
The purpose of this documentation is both for better informing our users, and also work as foundational work for the upcoming SuriCon presentation about the same topic.
Examples:
