From d11e8a8ee7fb2cb2da0567de16bde344e1313f36 Mon Sep 17 00:00:00 2001 From: Victor Julien Date: Wed, 11 Dec 2024 10:09:19 +0100 Subject: [PATCH] doc/userguide: document TCP urgent policy --- doc/userguide/configuration/suricata-yaml.rst | 52 +++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/doc/userguide/configuration/suricata-yaml.rst b/doc/userguide/configuration/suricata-yaml.rst index c68d14f401a6..8400f92193a5 100644 --- a/doc/userguide/configuration/suricata-yaml.rst +++ b/doc/userguide/configuration/suricata-yaml.rst @@ -1305,6 +1305,58 @@ network inspection. .. image:: suricata-yaml/IDS_chunk_size.png +TCP Urgent Handling +^^^^^^^^^^^^^^^^^^^ + +TCP Urgent pointer support is a complicated topic, where it is essentially impossible +for a network device to know with certainty what the behavior of the receiving host is. + +For this reason, many middleboxes strip the URG flag and reset the urgent pointer (see +for example RFC 6093, 3.4). + +Several options are provided to control how to deal with the urgent pointer. + +:: + + stream: + reassembly: + urgent: + policy: oob # drop, inline, oob (1 byte, see RFC 6093, 3.1), gap + oob-limit-policy: drop + +`stream.reassembly.urgent.policy`: + - `drop`: drop URG packets before they affect the stream engine + - `inline`: ignore the urgent pointer and process all data inline + - `oob` (out of band): treat the last byte as out of band + - `gap`: skip the last byte, but do no adjust sequence offsets, leading to + gaps in the data + +If the urgent policy is set to `oob`, there is an additional setting. Since OOB data does +advance the TCP sequence number, the stream engine tracks the number of bytes to make sure +no GAPs in the non-OOB data are seen by the app-layer parsers and detection engine. This +is currently limited to 64k per direction. If the number of OOB bytes exceeds that 64k, an +additional policy is triggered: `stream.reassembly.urgent.oob-limit-policy`. + +`stream.reassembly.urgent.oob-limit-policy`: +- `drop`: drop URG packets before they affect the stream engine +- `inline`: ignore the urgent pointer and process all data inline +- `gap`: skip the last byte, but do no adjust sequence offsets, leading to gaps in the data + +Observables +""""""""""" + +Each packet with the URG flag set, will increment the `tcp.urg` counter. + +When dropping the URG packets, the packets will have the drop reason +`ips.drop_reason.stream_urgent`, which is also a counter in the stats logging. + +The stream event `stream-event:reassembly_urgent_oob_limit_reached` allows matching on the +packet that reaches the OOB limit. Stream rule `2210066` matches on this. + +If `stats.stream-events` are enabled the counter `stream.reassembly_urgent_oob_limit_reached` +will be incremented if the OOB limit is reached. + + Host Tracking -------------