From: Travis Green <travis@travisgreen.net>
Date: Thu, 29 Aug 2019 04:16:28 +0000 (-0600)
Subject: doc: add tcp flags documentation
X-Git-Tag: suricata-7.0.2~19
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=96a0e7016fd36458db52b1fca81b9f4a61e24105;p=thirdparty%2Fsuricata.git

doc: add tcp flags documentation

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

diff --git a/doc/userguide/rules/header-keywords.rst b/doc/userguide/rules/header-keywords.rst
index 3b45788e07..36d1437647 100644
--- a/doc/userguide/rules/header-keywords.rst
+++ b/doc/userguide/rules/header-keywords.rst
@@ -293,6 +293,60 @@ Example of tos with a negated value:
 TCP keywords
 ------------
 
+tcp.flags
+^^^^^^^^^
+
+The tcp.flags keyword checks for specific `TCP flag bits
+<https://en.wikipedia.org/wiki/Transmission_Control_Protocol#TCP_segment_structure>`_.
+
+The following flag bits may be checked:
+
+====  ====================================
+Flag  Description
+====  ====================================
+F     FIN - Finish
+S     SYN - Synchronize sequence numbers
+R     RST - Reset
+P     PSH - Push
+A     ACK - Acknowledgment
+U     URG - Urgent
+C     CWR - Congestion Window Reduced
+E     ECE - ECN-Echo
+0     No TCP Flags Set
+====  ====================================
+
+The following modifiers can be set to change the match criteria:
+
+========  ===================================
+Modifier  Description
+========  ===================================
+``+``     match on the bits, plus any others
+``*``     match if any of the bits are set
+``!``     match if the bits are not set
+========  ===================================
+
+To handle writing rules for session initiation packets such as ECN where a SYN
+packet is sent with CWR and ECE flags set, an option mask may be used by
+appending a comma and masked values. For example, a rule that checks for a SYN
+flag, regardless of the values of the reserved bits is ``tcp.flags:S,CE;``
+
+Format of tcp.flags::
+
+    tcp.flags:[modifier]<test flags>[,<ignore flags>];
+    tcp.flags:[!|*|+]<FSRPAUCE0>[,<FSRPAUCE>];
+
+Example::
+
+  alert tcp $EXTERNAL_NET any -> $HOME_NET any (msg:"Example tcp.flags sig"; \
+ :example-rule-emphasis:`tcp.flags:FPU,CE;` classtype:misc-activity; sid:1; rev:1;)
+
+It is also possible to use the `tcp.flags` content as a fast_pattern by using the `prefilter` keyword. For more information on `prefilter` usage see :doc:`prefilter-keywords`
+
+Example::
+
+  alert tcp $EXTERNAL_NET any -> $HOME_NET any (msg:"Example tcp.flags sig"; \
+ :example-rule-emphasis:`tcp.flags:FPU,CE; prefilter;` classtype:misc-activity; sid:1; rev:1;)  
+
 seq
 ^^^
 The seq keyword can be used in a signature to check for a specific TCP