doc: add tcp flags documentation

Signed-off-by: jason taylor <jtfas90@gmail.com>
(cherry picked from commit 96a0e7016fd36458db52b1fca81b9f4a61e24105)

diff --git a/doc/userguide/rules/header-keywords.rst b/doc/userguide/rules/header-keywords.rst
index 5e4e3f994a02031d04cd7663dea7c49664695c23..8bf9838cafee3add7676e1d58ef7635c7247a044 100644 (file)
--- a/doc/userguide/rules/header-keywords.rst
+++ b/doc/userguide/rules/header-keywords.rst
@@ -287,6 +287,60 @@ Example of tos with negated values:
 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