From 31066c7c3b54e5a7144b68ef10b3352929a29166 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 --- .../configuration/exception-policies.rst | 31 ++++++++++--------- doc/userguide/configuration/suricata-yaml.rst | 20 ++++++------ suricata.yaml.in | 21 ++++++------- 3 files changed, 38 insertions(+), 34 deletions(-) diff --git a/doc/userguide/configuration/exception-policies.rst b/doc/userguide/configuration/exception-policies.rst index cfa81c9bd2..21c50eaed1 100644 --- a/doc/userguide/configuration/exception-policies.rst +++ b/doc/userguide/configuration/exception-policies.rst @@ -29,14 +29,14 @@ have the need to. :: - # In IPS mode, the default is drop-packet/drop-flow. To fallback to old - # behavior (setting each of them individually, or ignoring all), set this - # to ignore. + # Define a common behavior for all exception policies. + # In IPS mode, the default is drop-flow. For cases when that's not possible, the + # engine will fall to drop-packet. To fallback to old behavior (setting each of + # them individually, or ignoring all), set this to ignore. # All values available for exception policies can be used, and there is one - # extra option: auto - which means drop-packet/drop-flow in IPS mode and - # ignore in IDS mode). - # Exception policy values are: drop-packet, drop-flow, reject, bypass, - # pass-packet, pass-flow, ignore (disable). + # extra option: auto - which means drop-flow or drop-packet (as explained above) + # in IPS mode, and ignore in IDS mode. Exception policy values are: drop-packet, + # drop-flow, reject, bypass, pass-packet, pass-flow, ignore (disable). exception-policy: auto This value will be overwritten by specific exception policies whose settings are @@ -46,10 +46,11 @@ Auto '''' **In IPS mode**, the default behavior for all exception policies is to drop -packets and/or flows. It is possible to disable this default, by setting the -exception policies "master switch" yaml config option to ``ignore``. +the flow, or the packet, when the flow action is not supported. It is possible +to disable this default, by setting the exception policies' "master switch" yaml +config option to ``ignore``. -**In IDS mode**, setting auto mode actually means disabling the +**In IDS mode**, setting ``auto`` mode actually means disabling the ``master-swtich``, or ignoring the exception policies. Specific settings @@ -79,14 +80,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` @@ -99,7 +101,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 fa96d04b54..04d5e75b7d 100644 --- a/doc/userguide/configuration/suricata-yaml.rst +++ b/doc/userguide/configuration/suricata-yaml.rst @@ -936,8 +936,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). :: @@ -999,7 +999,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'. :: @@ -1101,8 +1101,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 @@ -1133,7 +1133,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 @@ -1193,7 +1194,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 @@ -1209,7 +1211,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 @@ -1254,7 +1256,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 e80e8a0d72..da13df91a7 100644 --- a/suricata.yaml.in +++ b/suricata.yaml.in @@ -1295,14 +1295,13 @@ legacy: # Exception Policies # # Define a common behavior for all exception policies. -# In IPS mode, the default is drop-packet/drop-flow. To fallback to old -# behavior (setting each of them individually, or ignoring all), set this -# to ignore. +# In IPS mode, the default is drop-flow. For cases when that's not possible, the +# engine will fall to drop-packet. To fallback to old behavior (setting each of +# them individually, or ignoring all), set this to ignore. # All values available for exception policies can be used, and there is one -# extra option: auto - which means drop-packet/drop-flow in IPS mode and -# ignore in IDS mode). -# Exception policy values are: drop-packet, drop-flow, reject, bypass, -# pass-packet, pass-flow, ignore (disable). +# extra option: auto - which means drop-flow or drop-packet (as explained above) +# in IPS mode, and ignore in IDS mode. Exception policy values are: drop-packet, +# drop-flow, reject, bypass, pass-packet, pass-flow, ignore (disable). exception-policy: auto # IP Reputation @@ -1352,8 +1351,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 @@ -1396,8 +1395,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