doc: add bypass keyword documentation

Signed-off-by: jason taylor <jtfas90@gmail.com>

diff --git a/doc/userguide/performance/ignoring-traffic.rst b/doc/userguide/performance/ignoring-traffic.rst
index cef42e02d177bcd1fd0fcd1b2cc0c2e6e42ed347..cb1930071d33564e92eeba049a7a771118e27172 100644 (file)
--- a/doc/userguide/performance/ignoring-traffic.rst
+++ b/doc/userguide/performance/ignoring-traffic.rst
@@ -4,8 +4,6 @@ Ignoring Traffic
 In some cases there are reasons to ignore certain traffic. Certain hosts
 may be trusted, or perhaps a backup stream should be ignored.
 
-This document lists some strategies for ignoring traffic.
-
 capture filters (BPF)
 ---------------------
 
@@ -66,10 +64,24 @@ Example:
   suppress gen_id 0, sig_id 0, track by_src, ip 1.2.3.4
 
 
-Encrypted traffic
+encrypted traffic
 -----------------
 
 The TLS app layer parser has the ability to stop processing encrypted traffic
 after the initial handshake. By setting the `app-layer.protocols.tls.encryption-handling`
 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.
+
+bypassing traffic
+-----------------
+
+Aside from using the ``bypass`` keyword in rules, there are three other ways to bypass traffic.
+
+- Within suricata (local bypass). Suricata reads a packet, decodes it, checks it in the flow table. If the corresponding flow is local bypassed then it simply skips all streaming, detection and output and the packet goes directly out in IDS mode and to verdict in IPS mode.
+- Within the kernel (capture bypass). When Suricata decides to bypass it calls a function provided by the capture method to declare the bypass in the capture. For NFQ this is a simple mark that will be used by the ruleset. For AF_PACKET this will be a call to add an element in an eBPF hash table stored in kernel.
+- Within the nic driver. This method relies upon XDP, XDP can process the traffic prior to reaching the kernel.
+
+Additional bypass documentation:
+
+https://suricon.net/wp-content/uploads/2017/12/SuriCon17-Manev_Purzynski.pdf
+https://www.stamus-networks.com/2016/09/28/suricata-bypass-feature/

diff --git a/doc/userguide/rules/bypass-keyword.rst b/doc/userguide/rules/bypass-keyword.rst
new file mode 100644 (file)
index 0000000..11b60fb
--- /dev/null
+++ b/doc/userguide/rules/bypass-keyword.rst
@@ -0,0 +1,19 @@
+Bypass Keyword
+==============
+
+Suricata has a ``bypass`` keyword that can be used in signatures to exclude traffic from further evaluation.
+
+The ``bypass`` keyword is useful in cases where there is a large flow expected (e.g. Netflix, Spotify, Youtube).
+
+The ``bypass`` keyword is considered a post-match keyword.
+
+
+bypass
+--------
+
+Bypass a flow on matching http traffic.
+
+Example::
+
+  alert http any any -> any any (content:"suricata-ids.org"; \
+      http_host; bypass; sid:10001; rev:1;)

diff --git a/doc/userguide/rules/index.rst b/doc/userguide/rules/index.rst
index e8b45cf8dda4160cfb2934140228c2f4a719cd02..391d410f5351f61c1b5db63b216c22473bca61b6 100644 (file)
--- a/doc/userguide/rules/index.rst
+++ b/doc/userguide/rules/index.rst
@@ -10,6 +10,7 @@ Suricata Rules
    transforms
    prefilter-keywords
    flow-keywords
+   bypass-keyword
    http-keywords
    file-keywords
    dns-keywords