]> git.ipfire.org Git - thirdparty/suricata.git/commitdiff
doc: add byte_* documentation to the userguide 3703/head
authorBryant Smith <bhsmith27+git@gmail.com>
Sat, 2 Mar 2019 17:07:25 +0000 (10:07 -0700)
committerBryant Smith <bhsmith27+git@gmail.com>
Mon, 4 Mar 2019 21:15:55 +0000 (14:15 -0700)
Added byte_test, byte_jump and byte_extract description and example rules

doc/userguide/rules/payload-keywords.rst

index 8ea6ae28195b67759cba941ed617ab2b142e8f74..bea7e92187d2228343ccc2a380c50a0679777ce6 100644 (file)
@@ -264,6 +264,169 @@ example of dsize in a rule:
 
     alert udp $EXTERNAL_NET any -> $HOME_NET 65535 (msg:"GPL DELETED EXPLOIT LANDesk Management Suite Alerting Service buffer overflow"; :example-rule-emphasis:`dsize:>268;` reference: bugtraq,23483; reference: cve,2007-1674; classtype: attempted-admin; sid:100000928; rev:1;)
 
+byte_test
+---------
+The ``byte_test`` keyword extracts ``<num of bytes>`` and performs an operation selected with ``<operator>`` against the value in ``<test value>`` at a particular ``<offset>``.
+
+Format::
+  
+  byte_test:<num of bytes>, [!]<operator>, <test value>, <offset> [,relative] \
+  [,<endian>][, string, <num type>][, dce][, bitmask <bitmask value>]; 
+
+
++----------------+------------------------------------------------------------------------------+
+| <num of bytes> | The number of bytes selected from the packet to be converted                        |
++----------------+------------------------------------------------------------------------------+
+| <operator>    |                                                                              |
+|               | - [!] Negation can prefix other operators                                    |
+|               | - < less than                                                                |
+|                       | - > greater than                                                             |
+|               | - = equal                                                                    |
+|               | - <= less than or equal                                                      |
+|               | - >= greater than or equal                                                   |
+|               | - & bitwise AND                                                              |
+|               | - ^ bitwise OR                                                               |
++----------------+------------------------------------------------------------------------------+
+| <value>       | Value to test the converted value against [hex or decimal accepted]          |
++----------------+------------------------------------------------------------------------------+
+| <offset>      | Number of bytes into the payload                                             |
++----------------+------------------------------------------------------------------------------+
+| [relative]    | Offset relative to last content match                                        |
++----------------+------------------------------------------------------------------------------+
+| [endian]      | Type of number being read:                                                   |       
+|               | - big (Most significant byte at lowest address)                              |
+|               | - little (Most significant byte at the highest address)                      |
++----------------+------------------------------------------------------------------------------+
+| [string] <num> |                                                                             |
+|               | - hex - Converted string represented in hex                                  |
+|               | - dec - Converted string represented in dedimal                              |
+|               | - oct - Converted string represented in octal                                |
++----------------+------------------------------------------------------------------------------+
+| [dce]                 | Allow the DCE module determine the byte order                                |
++----------------+------------------------------------------------------------------------------+
+| [bitmask]     | Applies the AND operator on the bytes converted                              |
++----------------+------------------------------------------------------------------------------+
+
+
+Example::
+
+  alert tcp any any -> any any \
+        (msg:"Byte_Test Example - Num = Value"; \
+        content:"|00 01 00 02|"; byte_test:2,=,0x01;)
+
+  alert tcp any any -> any any \
+        (msg:"Byte_Test Example - Num = Value relative to content"; \
+        content:"|00 01 00 02|"; byte_test:2,=,0x03,relative;)
+
+  alert tcp any any -> any any \
+        (msg:"Byte_Test Example - Num != Value"; content:"|00 01 00 02|"; \
+        byte_test:2,!=,0x06;)
+
+  alert tcp any any -> any any \ 
+         (msg:"Byte_Test Example - Detect Large Values"; content:"|00 01 00 02|"; \
+         byte_test:2,>,1000,relavtive;)
+
+  alert tcp any any -> any any \
+        (msg:"Byte_Test Example - Lowest bit is set"; \
+        content:"|00 01 00 02|"; byte_test:2,&,0x01,relative;)
+
+  alert tcp any any -> any any (msg:"Byte_Test Example - Compare to String"; \
+        content:"foobar"; byte_test:4,=,1337,1,relative,string,dec;)
+
+
+byte_jump
+---------
+
+The ``byte_jump`` keyword allows for the ability to select a ``<num of bytes>`` from an ``<offset>`` and moves the detection pointer to that position.  Content matches will then be based off the new position.
+
+Format::
+
+  byte_jump:<num of bytes>, <offset> [, relative][, multiplier <mult_value>] \
+       [, <endian>][, string, <num_type>][, align][, from_beginning][, from_end] \ 
+        [, post_offset <value>][, dce][, bitmask <value>];
+
++-----------------------+-----------------------------------------------------------------------+
+| <num of bytes>       | The number of bytes selected from the packet to be converted          |
++-----------------------+-----------------------------------------------------------------------+
+| <offset>             | Number of bytes into the payload                                      |
++-----------------------+-----------------------------------------------------------------------+
+| [relative]           | Offset relative to last content match                                 |
++-----------------------+-----------------------------------------------------------------------+
+| [multiplier] <value>  | Multiple the converted byte by the <value>                           |
++-----------------------+-----------------------------------------------------------------------+
+| [endian]             | - big (Most significant byte at lowest address)                       |
+|                      | - little (Most significant byte at the highest address)               |
++-----------------------+-----------------------------------------------------------------------+
+| [string] <num_type>          |                                                                       |
+|                      | - hex Converted data is represented in hex                            |
+|                      | - dec Converted data is represented in decimal                        |
+|                      | - oct Converted data is represented as octal                          |
++-----------------------+-----------------------------------------------------------------------+
+| [align]              | Rounds the number up to the next 32bit boundary                       |
++-----------------------+-----------------------------------------------------------------------+
+| [from_beginning]     | Jumps forward from the beginning of the packet, instead of            |
+|                      | where the detection pointer is set                                    |
++-----------------------+-----------------------------------------------------------------------+
+| [from_end]           | Jump will begin at the end of the payload, instead of                 |
+|                      | where the detection point is set                                      |
++-----------------------+-----------------------------------------------------------------------+
+| [post_offset] <value>        | After the jump operation has been performed, it will                  |
+|                      | jump an additional number of bytes specified by <value>               |
++-----------------------+-----------------------------------------------------------------------+
+| [dce]                        | Allow the DCE module determine the byte order                         |
++-----------------------+-----------------------------------------------------------------------+
+| [bitmask] <value>    | The AND operator will be applied by <value> and the                   |
+|                      | converted bytes, then jump operation is performed                     |
++-----------------------+-----------------------------------------------------------------------+
+
+Example::
+
+  alert tcp any any -> any any \
+       (msg:"Byte_Jump Example"; \
+       content:"Alice"; byte_jump:2,0; content:"Bob";)
+
+  alert tcp any any -> any any \
+       (msg:"Byte_Jump Multiple Jumps"; \
+       byte_jump:2,0; byte_jump:2,0,relative; content:"foobar"; distance:0; within:6;)
+
+  alert tcp any any -> any any \
+       (msg:"Byte_Jump From the End -8 Bytes"; \
+       byte_jump:0,0, from_end, post_offset -8; \
+       content:"|6c 33 33 74|"; distance:0 within:4;)
+
+
+byte_extract
+------------
+
+The ``byte_extract`` keyword extracts ``<num of bytes>`` at a particular ``<offset>`` and stores it in ``<var_name>``. The value in ``<var_name>`` can be used in any modifier that takes a number as an option and in the case of ``byte_test`` it can be used as a value.
+
+Format::
+
+  byte_extract:<num of bytes>, <offset>, <var_name>, [, relative];
+
+============== ==================================
+ Keyword       Modifier 
+==============         ==================================
+ content       offset,depth,distance,within    
+ byte_test     offset,value                    
+ byte_jump     offset                          
+ isdataat      offset                          
+============== ==================================
+
+Example::
+
+  alert tcp any any -> any any \
+        (msg:"Byte_Extract Example Using distance"; \
+        content:"Alice"; byte_extract:2,0,size; content:"Bob"; distance:size; within:3; sid:1;)
+  alert tcp any any -> any any \
+        (msg:"Byte_Extract Example Using within"; \
+        flow:established,to_server; content:"|00 FF|"; \
+        byte_extract:1,0,len,relative; content:"|5c 00|"; distance:2; within:len; sid:2;)
+  alert tcp any any -> any any \
+        (msg:"Byte_Extract Example Comparing Bytes"; \
+        flow:established,to_server; content:"|00 FF|"; \
+        byte_extract:2,0,cmp_ver,relative; content:"FooBar"; distance:0; byte_test:2,=,cmp_ver,0; sid:3;)
+
 rpc
 ---
 
@@ -447,3 +610,4 @@ Suricata has its own specific pcre modifiers. These are:
   buffer as http_host.  W can be combined with /R. Note that R is
   relative to the previous match so both matches have to be in the
   HTTP-Host buffer.
+