From: Juliana Fajardini Date: Thu, 15 Sep 2022 23:07:54 +0000 (-0300) Subject: userguide: add section about exception policies X-Git-Tag: suricata-7.0.0-beta1~171 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=7b0008d4f09d9cb0bdafb30dc0fdc9d8ecd183b3;p=thirdparty%2Fsuricata.git userguide: add section about exception policies This describes briefly what the exception policies are, what is the engine's behavior, what options are available and to which parts are they implemented. Task #5475 Task #5515 --- diff --git a/doc/userguide/configuration/exception-policies.rst b/doc/userguide/configuration/exception-policies.rst new file mode 100644 index 0000000000..0d82b33210 --- /dev/null +++ b/doc/userguide/configuration/exception-policies.rst @@ -0,0 +1,105 @@ +.. _exception policies: + +Exception Policies +================== + +Suricata has a set of configuration variables to indicate what should the engine +do when certain exception conditions, such as hitting a memcap, are reached. + +They are called Exception Policies and are configurable via suricata.yaml. If +enabled, the engine will call them when it reaches exception states. + +For developers or for researching purposes, there are also simulation options +exposed in debug mode and passed via command-line. These exist to force or +simulate failures or errors and understand Suricata behavior under such conditions. + +Exception Policies +------------------ + +Exception policies are implemented for: + +.. list-table:: Exception Policy configuration variables + :widths: 20, 18, 62 + :header-rows: 1 + + * - Config setting + - Policy variable + - Expected behavior + * - stream.memcap + - memcap-policy + - If a stream memcap limit is reached, call the memcap policy on the packet + and flow. + * - stream.midstream + - midstream-policy + - If a session is picked up midstream, call the memcap policy on the packet + and flow. + * - stream.reassembly.memcap + - memcap-policy + - If stream reassembly reaches memcap limit, call the memcap policy on the + packet and flow. + * - flow.memcap + - memcap-policy + - Apply policy when the memcap limit for flows is reached and no flow could + be freed up. + * - defrag.memcap + - memcap-policy + - Apply policy when the memcap limit for defrag is reached and no tracker + could be picked up. + * - app-layer + - error-policy + - Apply policy if a parser reaches an error state. + +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` +documentation). + +The possible values for the exception policies, and the resulting behaviors, +are: + +- ``drop-flow``: disable inspection for the whole flow (packets, payload, + 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. +- ``bypass``: bypass the flow. No further inspection is done. :ref:`Bypass + ` may be offloaded. +- ``pass-flow``: disable payload and packet detection; stream reassembly, + app-layer parsing and logging still happen. +- ``pass-packet``: disable detection, still does stream updates and app-layer + parsing (depeding on which policy triggered it). +- ``ignore``: do not apply exception policies (default behavior). + +The *Drop*, *pass* and *reject* are similar to the rule actions described in :ref:`rule +actions`. + +Command-line Options for Simulating Exceptions +---------------------------------------------- + +It is also possible to force specific exception scenarios, to check engine +behavior under failure or error conditions. + +The available command-line options are: + +- ``simulate-applayer-error-at-offset-ts``: force an applayer error in the to + server direction at the given offset. +- ``simulate-applayer-error-at-offset-tc``: force an applayer error in the to + client direction at the given offset. +- ``simulate-packet-loss``: simulate that the packet with the given number + (``pcap_cnt``) from the session was lost. +- ``simulate-packet-tcp-reassembly-memcap``: simulate that the TCP stream + reassembly reached memcap for the specified packet. +- ``simulate-packet-tcp-ssn-memcap``: simulate that the TCP session hit the + memcap for the specified packet. +- ``simulate-packet-flow-memcap``: force the engine to assume that flow memcap is + hit at the given packet. +- ``simulate-packet-defrag-memcap``: force Suricata to assume memcap is hit when + defragmenting specified packet. +- ``simulate-alert-queue-realloc-failure``: prevent the engine from dynamically + growing the temporary alert queue, during alerts processing. + +Common abbreviations +-------------------- + +- applayer: application layer protocol +- memcap: (maximum) memory capacity available +- defrag: defragmentation diff --git a/doc/userguide/configuration/index.rst b/doc/userguide/configuration/index.rst index 5467d8a3fb..d4891c1132 100644 --- a/doc/userguide/configuration/index.rst +++ b/doc/userguide/configuration/index.rst @@ -5,6 +5,7 @@ Configuration suricata-yaml global-thresholds + exception-policies snort-to-suricata multi-tenant dropping-privileges diff --git a/doc/userguide/performance/ignoring-traffic.rst b/doc/userguide/performance/ignoring-traffic.rst index 2b1ecdb4c7..0ce36d6d07 100644 --- a/doc/userguide/performance/ignoring-traffic.rst +++ b/doc/userguide/performance/ignoring-traffic.rst @@ -78,6 +78,8 @@ after the initial handshake. By setting the `app-layer.protocols.tls.encryption- option to `bypass` the rest of this flow is ignored. If flow bypass is enabled, the bypass is done in the kernel or in hardware. +.. _bypass: + bypassing traffic ----------------- diff --git a/doc/userguide/rules/intro.rst b/doc/userguide/rules/intro.rst index d3e3321b54..8db7174543 100644 --- a/doc/userguide/rules/intro.rst +++ b/doc/userguide/rules/intro.rst @@ -39,6 +39,8 @@ are the options. We will be using the above signature as an example throughout this section, highlighting the different parts of the signature. +.. _actions: + Action ------ .. container:: example-rule