From e62eb004599ec500aeacfa7150b0dbca19f0a0fb Mon Sep 17 00:00:00 2001 From: Victor Julien Date: Thu, 3 Jul 2025 15:31:51 +0200 Subject: [PATCH] doc/userguide: add ips chapter; add concept Move setup guides into the new chapter as well. Explain `stream.inline` logic. Ticket: #5513. Ticket: #6284. --- doc/userguide/Makefile.am | 4 +- doc/userguide/firewall/firewall-design.rst | 2 + doc/userguide/index.rst | 3 +- doc/userguide/ips/index.rst | 9 ++ doc/userguide/ips/ips-concept.rst | 92 ++++++++++++++++++ .../setting-up-ipsinline-for-linux.rst | 0 .../IPtables.png | Bin .../IPtables3.png | Bin .../iptables1.png | Bin .../iptables2.png | Bin .../iptables4.png | Bin .../iptables_vnL.png | Bin .../setting-up-ipsinline-for-windows.rst | 0 13 files changed, 105 insertions(+), 5 deletions(-) create mode 100644 doc/userguide/ips/index.rst create mode 100644 doc/userguide/ips/ips-concept.rst rename doc/userguide/{ => ips}/setting-up-ipsinline-for-linux.rst (100%) rename doc/userguide/{ => ips}/setting-up-ipsinline-for-linux/IPtables.png (100%) rename doc/userguide/{ => ips}/setting-up-ipsinline-for-linux/IPtables3.png (100%) rename doc/userguide/{ => ips}/setting-up-ipsinline-for-linux/iptables1.png (100%) rename doc/userguide/{ => ips}/setting-up-ipsinline-for-linux/iptables2.png (100%) rename doc/userguide/{ => ips}/setting-up-ipsinline-for-linux/iptables4.png (100%) rename doc/userguide/{ => ips}/setting-up-ipsinline-for-linux/iptables_vnL.png (100%) rename doc/userguide/{ => ips}/setting-up-ipsinline-for-windows.rst (100%) diff --git a/doc/userguide/Makefile.am b/doc/userguide/Makefile.am index dea2298959..052c6c5204 100644 --- a/doc/userguide/Makefile.am +++ b/doc/userguide/Makefile.am @@ -18,6 +18,7 @@ EXTRA_DIST = \ initscripts.rst \ install.rst \ install \ + ips \ licenses \ lua \ make-sense-alerts.rst \ @@ -32,9 +33,6 @@ EXTRA_DIST = \ rule-management \ rules \ security.rst \ - setting-up-ipsinline-for-linux \ - setting-up-ipsinline-for-linux.rst \ - setting-up-ipsinline-for-windows.rst \ support-status.rst \ unix-socket.rst \ what-is-suricata.rst \ diff --git a/doc/userguide/firewall/firewall-design.rst b/doc/userguide/firewall/firewall-design.rst index bee7f4760d..228e13b7da 100644 --- a/doc/userguide/firewall/firewall-design.rst +++ b/doc/userguide/firewall/firewall-design.rst @@ -1,3 +1,5 @@ +.. _firewall mode design: + Firewall Mode Design ******************** diff --git a/doc/userguide/index.rst b/doc/userguide/index.rst index 01d47bc7c9..9ca58f56e2 100644 --- a/doc/userguide/index.rst +++ b/doc/userguide/index.rst @@ -21,8 +21,6 @@ This is the documentation for Suricata |version|. configuration/index.rst reputation/index.rst initscripts - setting-up-ipsinline-for-linux - setting-up-ipsinline-for-windows output/index.rst lua/index.rst file-extraction/file-extraction.rst @@ -30,6 +28,7 @@ This is the documentation for Suricata |version|. capture-hardware/index.rst unix-socket.rst plugins/index.rst + ips/index.rst firewall/index.rst 3rd-party-integration/index.rst manpages/index.rst diff --git a/doc/userguide/ips/index.rst b/doc/userguide/ips/index.rst new file mode 100644 index 0000000000..18062ad3ef --- /dev/null +++ b/doc/userguide/ips/index.rst @@ -0,0 +1,9 @@ +IPS Mode +======== + +.. toctree:: + + ips-concept + setting-up-ipsinline-for-linux + setting-up-ipsinline-for-windows + diff --git a/doc/userguide/ips/ips-concept.rst b/doc/userguide/ips/ips-concept.rst new file mode 100644 index 0000000000..863314340d --- /dev/null +++ b/doc/userguide/ips/ips-concept.rst @@ -0,0 +1,92 @@ +IPS Concept +=========== + +Intrusion Prevention System mode, or IPS mode, is the Suricata mode that makes it act as a +traffic filter. + +By default it will allow all traffic, and will use ``drop`` or ``reject`` rules to block +unwanted traffic. + +It is generally used ``inline``, where threat detection rules are used to drop known bad traffic. + +The ``inline`` operations are either on layer 2 (bridge, for example using AF_PACKET or DPDK) +or on layer 3 (routing, for example in NFQueue or IPFW). + + +Differences from the passive IDS mode +------------------------------------- + +TCP stream engine +^^^^^^^^^^^^^^^^^ + +Where in IDS mode TCP traffic is only inspected after the acknowledgement (ACK) for it has +been received, in IPS mode the default behavior is different: new data is inspected +immediately, together with previous data where possible. +The inspection happens in a sliding window. This behavior is controlled by the +``stream.inline`` setting. + +In case of overlapping data, the first data Suricata receives is accepted. Follow-up data +that overlaps with this is then checked against the first data. If it is different, the +traffic on the wire is rewritten to match the first data. + +The sliding window inspection can be visualized as such:: + + Packet 1: [hdr][segment data 1 ] + Segments: [segment data 1 ] + Window: [ inspection window ] + + Packet 2: [hdr][segment data 2] + Segments: [segment data 1 ][segment data 2] + Window: [ inspection window ] + + Packet 3: [hdr][segment data 3] + Segments: [segment data 1 ][segment data 2][segment data 3] + Window: [ inspection window ] + + Packet 4: [hdr][segment data 4] + Segments: [segment data 2][segment data 3][segment data 4] + Window: [ inspection window ] + +Each segment's data is inspected together with the other available data. One consequence +of this is that there can be significant rescanning of data, which has a performance impact. + +http body inspection +^^^^^^^^^^^^^^^^^^^^ + +Similar to the sliding window approach in the TCP stream engine, the HTTP body +inspection will happen in a sliding manner by default. In IDS mode body data is +buffered to the configured settings before inspection. + +:: + + app-layer: + protocols: + http: + libhtp: + default-config: + # auto will use http-body-inline mode in IPS mode, yes or no set it statically + http-body-inline: auto + + +file.data +^^^^^^^^^ + +For HTTP, the ``file.data`` logic is the same as the body inspection above. + +Exception Policies +------------------ + +By default, when IPS mode is enabled, the exception policies are set to block (``drop``). +This is to make sure rules cannot be bypassed due to Suricata reaching an error state in +parsing, reaching internal resource limits and other exception conditions. + +See :ref:`Exception Policies documentation `. + +Differences from Firewall Mode +------------------------------ + +The main difference is that unlike IPS mode, Firewall Mode has a default ``drop`` policy. +This means that a ruleset must be created to allow traffic to be accepted, instead of +accepting traffic by default and filtering out unwanted traffic. + +See :ref:`Firewall Mode Design `. diff --git a/doc/userguide/setting-up-ipsinline-for-linux.rst b/doc/userguide/ips/setting-up-ipsinline-for-linux.rst similarity index 100% rename from doc/userguide/setting-up-ipsinline-for-linux.rst rename to doc/userguide/ips/setting-up-ipsinline-for-linux.rst diff --git a/doc/userguide/setting-up-ipsinline-for-linux/IPtables.png b/doc/userguide/ips/setting-up-ipsinline-for-linux/IPtables.png similarity index 100% rename from doc/userguide/setting-up-ipsinline-for-linux/IPtables.png rename to doc/userguide/ips/setting-up-ipsinline-for-linux/IPtables.png diff --git a/doc/userguide/setting-up-ipsinline-for-linux/IPtables3.png b/doc/userguide/ips/setting-up-ipsinline-for-linux/IPtables3.png similarity index 100% rename from doc/userguide/setting-up-ipsinline-for-linux/IPtables3.png rename to doc/userguide/ips/setting-up-ipsinline-for-linux/IPtables3.png diff --git a/doc/userguide/setting-up-ipsinline-for-linux/iptables1.png b/doc/userguide/ips/setting-up-ipsinline-for-linux/iptables1.png similarity index 100% rename from doc/userguide/setting-up-ipsinline-for-linux/iptables1.png rename to doc/userguide/ips/setting-up-ipsinline-for-linux/iptables1.png diff --git a/doc/userguide/setting-up-ipsinline-for-linux/iptables2.png b/doc/userguide/ips/setting-up-ipsinline-for-linux/iptables2.png similarity index 100% rename from doc/userguide/setting-up-ipsinline-for-linux/iptables2.png rename to doc/userguide/ips/setting-up-ipsinline-for-linux/iptables2.png diff --git a/doc/userguide/setting-up-ipsinline-for-linux/iptables4.png b/doc/userguide/ips/setting-up-ipsinline-for-linux/iptables4.png similarity index 100% rename from doc/userguide/setting-up-ipsinline-for-linux/iptables4.png rename to doc/userguide/ips/setting-up-ipsinline-for-linux/iptables4.png diff --git a/doc/userguide/setting-up-ipsinline-for-linux/iptables_vnL.png b/doc/userguide/ips/setting-up-ipsinline-for-linux/iptables_vnL.png similarity index 100% rename from doc/userguide/setting-up-ipsinline-for-linux/iptables_vnL.png rename to doc/userguide/ips/setting-up-ipsinline-for-linux/iptables_vnL.png diff --git a/doc/userguide/setting-up-ipsinline-for-windows.rst b/doc/userguide/ips/setting-up-ipsinline-for-windows.rst similarity index 100% rename from doc/userguide/setting-up-ipsinline-for-windows.rst rename to doc/userguide/ips/setting-up-ipsinline-for-windows.rst -- 2.47.3