From 35b275654f763dd5909c712774282f23d798cfc8 Mon Sep 17 00:00:00 2001 From: Juliana Fajardini Date: Wed, 22 Mar 2023 16:05:40 -0300 Subject: [PATCH] docs: clarify exception policy's supported values As flow.memcap-policy and defrag.memcap-policy do not support flow actions, clarify that in the documentation. Also fix some typos, and add missing values in some places where the exception policies were explained. Related to Bug #5940 (cherry picked from commit 31066c7c3b54e5a7144b68ef10b3352929a29166) --- .../configuration/exception-policies.rst | 10 ++++++---- doc/userguide/configuration/suricata-yaml.rst | 20 ++++++++++--------- suricata.yaml.in | 8 ++++---- 3 files changed, 21 insertions(+), 17 deletions(-) diff --git a/doc/userguide/configuration/exception-policies.rst b/doc/userguide/configuration/exception-policies.rst index 0d82b33210..2d394d0df9 100644 --- a/doc/userguide/configuration/exception-policies.rst +++ b/doc/userguide/configuration/exception-policies.rst @@ -40,14 +40,15 @@ Exception policies are implemented for: * - flow.memcap - memcap-policy - Apply policy when the memcap limit for flows is reached and no flow could - be freed up. + be freed up. Apply policy to the packet. * - defrag.memcap - memcap-policy - Apply policy when the memcap limit for defrag is reached and no tracker - could be picked up. + could be picked up. Apply policy to the packet. * - app-layer - error-policy - - Apply policy if a parser reaches an error state. + - Apply policy if a parser reaches an error state. Apply policy to the + packet and flow. To change any of these, go to the specific section in the suricata.yaml file (for more configuration details, check the :doc:`suricata.yaml's` @@ -60,7 +61,8 @@ are: application layer protocol), drop the packet and all future packets in the flow. - ``drop-packet``: drop the packet. -- ``reject``: same as ``drop-flow``, but reject the current packet as well. +- ``reject``: same as ``drop-flow``, but reject the current packet as well (see + ``reject`` action in Rule's :ref:`actions`). - ``bypass``: bypass the flow. No further inspection is done. :ref:`Bypass ` may be offloaded. - ``pass-flow``: disable payload and packet detection; stream reassembly, diff --git a/doc/userguide/configuration/suricata-yaml.rst b/doc/userguide/configuration/suricata-yaml.rst index 32272981ec..62fd27ece1 100644 --- a/doc/userguide/configuration/suricata-yaml.rst +++ b/doc/userguide/configuration/suricata-yaml.rst @@ -937,8 +937,8 @@ Suricata discards the fragments (timeout). This occurs by default after 60 seconds. In IPS mode, it is possible to tell the engine what to do in case the memcap for -the defrag engine is reached: "drop-flow", "pass-flow", "bypass", "drop-packet", -"pass-packet", or "ignore" (default behavior). +the defrag engine is reached: "drop-packet", "pass-packet", or "ignore" (default +behavior). :: @@ -1000,7 +1000,7 @@ thread ensures that wherever possible and within the memcap. There will be 10000 flows prepared. In IPS mode, a memcap-policy exception policy can be set, telling Suricata -what to do in case memcap is hit: 'drop-flow', 'pass-flow', 'bypass', 'reject', +what to do in case memcap is hit: 'drop-packet', 'pass-packet', 'reject', or 'ignore'. :: @@ -1102,8 +1102,8 @@ be recognized by Suricata. The stream-engine has two memcaps that can be set. One for the stream-tracking-engine and one for the reassembly-engine. For both cases, in IPS mode, an exception policy (memcap-policy) can be set, telling Suricata -what to do in case memcap is hit: 'drop-flow', 'pass-flow', 'bypass', 'reject', -'ignore'. +what to do in case memcap is hit: 'drop-flow', 'drop-packet', 'pass-flow', +'pass-packet', 'bypass', 'reject', or 'ignore'. The stream-tracking-engine keeps information of the flow in memory. Information about the state, TCP-sequence-numbers and the TCP @@ -1134,7 +1134,8 @@ sessions. This setup always includes a lot of information. If you want Suricata to check the stream from that time on, you can do so by setting the option 'midstream' to 'true'. The default setting is 'false'. In IPS mode, it is possible to define a 'midstream-policy', -indicating whether Suricata should drop, pass or bypass a midstream flow. +indicating whether Suricata should drop-flow, drop-packet, pass-flow, +pass-packet, reject, or bypass a midstream flow. The default is ignore. Normally Suricata is able to see all packets of a connection. Some networks make it more complicated though. Some of the network-traffic follows a different route than the other part, in other words: the traffic goes @@ -1194,7 +1195,8 @@ The reassembly-engine has to keep data segments in memory in order to be able to reconstruct a stream. To avoid resource starvation a memcap is used to limit the memory used. In IPS mode, an exception policy (memcap-policy) can be set, telling Suricata what to do in case memcap -is hit: 'drop-flow', 'pass-flow', 'bypass', 'reject', 'ignore'. +is hit: 'drop-flow', 'drop-packet', 'pass-flow', 'pass-packet', 'bypass', +'reject', or 'ignore'. Reassembling a stream is an expensive operation. With the option depth you can control how far into a stream reassembly is done. By default @@ -1210,7 +1212,7 @@ adding in a random factor. reassembly: memcap: 256mb # Memory reserved for stream data reconstruction (in bytes) - memcap-policy: ignore # What to do when a midstream session is seen + memcap-policy: ignore # What to do when memcap for reassembly is hit depth: 1mb # The depth of the reassembling. toserver_chunk_size: 2560 # inspect raw stream in chunks of at least this size toclient_chunk_size: 2560 # inspect raw stream in chunks of at least @@ -1255,7 +1257,7 @@ Application Layer Parsers The ``app-layer`` section holds application layer specific configurations. In IPS mode, a global exception policy accessed via the ``error-policy`` -setting can be defined to indicate what the engine should do in case if +setting can be defined to indicate what the engine should do in case it encounters an app-layer error. Possible values are "drop-flow", "pass-flow", "bypass", "drop-packet", "pass-packet", "reject" or "ignore" (which maintains the default behavior). diff --git a/suricata.yaml.in b/suricata.yaml.in index 42ba0576d3..78c4b1a0e7 100644 --- a/suricata.yaml.in +++ b/suricata.yaml.in @@ -1160,8 +1160,8 @@ host-os-policy: # Defrag settings: -# The memcap-policy value can be "drop-flow", "pass-flow", "bypass", -# "drop-packet", "pass-packet", "reject" or "ignore" (which is the default). +# The memcap-policy value can be "drop-packet", "pass-packet", "reject" or +# "ignore" (which is the default). defrag: memcap: 32mb # memcap-policy: ignore @@ -1204,8 +1204,8 @@ defrag: # last time seen flows. # The memcap can be specified in kb, mb, gb. Just a number indicates it's # in bytes. -# The memcap-policy can be "drop-flow", "pass-flow", "bypass", "drop-packet", -# "pass-packet", "reject" or "ignore" (which is the default). +# The memcap-policy can be "drop-packet", "pass-packet", "reject" or "ignore" +# (which is the default). flow: memcap: 128mb -- 2.47.2