doc: integer keywords

Ticket: 6628

Document the generic detection capabilities for integer keywords.
and make every integer keyword pointing to this section.

Author: catenacyber

doc/userguide/rules/dhcp-keywords.rst

@@ -6,6 +6,8 @@ dhcp.leasetime
 
 DHCP lease time (integer).
 
+dhcp.leasetime uses an :ref:`unsigned 64-bits integer <rules-integer-keywords>`.
+
 Syntax::
 
  dhcp.leasetime:[op]<number>
@@ -25,6 +27,8 @@ dhcp.rebinding_time
 
 DHCP rebinding time (integer).
 
+dhcp.rebinding_time uses an :ref:`unsigned 64-bits integer <rules-integer-keywords>`.
+
 Syntax::
 
  dhcp.rebinding_time:[op]<number>
@@ -44,6 +48,8 @@ dhcp.renewal_time
 
 DHCP renewal time (integer).
 
+dhcp.renewal_time uses an :ref:`unsigned 64-bits integer <rules-integer-keywords>`.
+
 Syntax::
 
  dhcp.renewal_time:[op]<number>

doc/userguide/rules/file-keywords.rst

@@ -244,6 +244,8 @@ filesize
 
 Match on the size of the file as it is being transferred.
 
+filesize uses an :ref:`unsigned 64-bits integer <rules-integer-keywords>`.
+
 Syntax::
 
   filesize:<value>;

doc/userguide/rules/flow-keywords.rst

@@ -292,6 +292,8 @@ flow.age
 Flow age in seconds (integer)
 This keyword does not wait for the end of the flow, but will be checked at each packet.
 
+flow.age uses an :ref:`unsigned 32-bits integer <rules-integer-keywords>`.
+
 Syntax::
 
  flow.age: [op]<number>
@@ -314,6 +316,8 @@ flow.pkts_toclient
 Flow number of packets to client (integer)
 This keyword does not wait for the end of the flow, but will be checked at each packet.
 
+flow.pkts_toclient uses an :ref:`unsigned 32-bits integer <rules-integer-keywords>`.
+
 Syntax::
 
  flow.pkts_toclient: [op]<number>
@@ -334,6 +338,8 @@ flow.pkts_toserver
 Flow number of packets to server (integer)
 This keyword does not wait for the end of the flow, but will be checked at each packet.
 
+flow.pkts_toserver uses an :ref:`unsigned 32-bits integer <rules-integer-keywords>`.
+
 Syntax::
 
  flow.pkts_toserver: [op]<number>
@@ -354,6 +360,8 @@ flow.bytes_toclient
 Flow number of bytes to client (integer)
 This keyword does not wait for the end of the flow, but will be checked at each packet.
 
+flow.bytes_toclient uses an :ref:`unsigned 64-bits integer <rules-integer-keywords>`.
+
 Syntax::
 
  flow.bytes_toclient: [op]<number>
@@ -374,6 +382,8 @@ flow.bytes_toserver
 Flow number of bytes to server (integer)
 This keyword does not wait for the end of the flow, but will be checked at each packet.
 
+flow.bytes_toserver uses an :ref:`unsigned 64-bits integer <rules-integer-keywords>`.
+
 Syntax::
 
  flow.bytes_toserver: [op]<number>

doc/userguide/rules/header-keywords.rst

@@ -15,6 +15,8 @@ For example::
 
   ttl:10;
 
+ttl uses an :ref:`unsigned 8-bits integer <rules-integer-keywords>`.
+
 At the end of the ttl keyword you can enter the value on which you
 want to match. The Time-to-live value determines the maximal amount
 of time a packet can be in the Internet-system. If this field is set
@@ -431,6 +433,8 @@ tcp.mss
 Match on the TCP MSS option value. Will not match if the option is not
 present.
 
+tcp.mss uses an :ref:`unsigned 16-bits integer <rules-integer-keywords>`.
+
 The format of the keyword::
 
   tcp.mss:<min>-<max>;
@@ -506,6 +510,8 @@ messages. The different messages are distinct by different names, but
 more important by numeric values. For more information see the table
 with message-types and codes.
 
+itype uses an :ref:`unsigned 8-bits integer <rules-integer-keywords>`.
+
 The format of the itype keyword::
 
   itype:min<>max;
@@ -565,6 +571,8 @@ code of a ICMP message clarifies the message. Together with the
 ICMP-type it indicates with what kind of problem you are dealing with.
 A code has a different purpose with every ICMP-type.
 
+icode uses an :ref:`unsigned 8-bits integer <rules-integer-keywords>`.
+
 The format of the icode keyword::
 
   icode:min<>max;
@@ -719,6 +727,8 @@ icmpv6.mtu
 Match on the ICMPv6 MTU optional value. Will not match if the MTU is not
 present.
 
+icmpv6.mtu uses an :ref:`unsigned 32-bits integer <rules-integer-keywords>`.
+
 The format of the keyword::
 
   icmpv6.mtu:<min>-<max>;

doc/userguide/rules/http-keywords.rst

@@ -237,6 +237,8 @@ The ``urilen`` keyword is used to match on the length of the request
 URI. It is possible to use the ``<`` and ``>`` operators, which
 indicate respectively *smaller than* and *larger than*.
 
+urilen uses an :ref:`unsigned 64-bits integer <rules-integer-keywords>`.
+
 The format of ``urilen`` is::
 
   urilen:3;

doc/userguide/rules/http2-keywords.rst

@@ -31,6 +31,8 @@ http2.priority
 
 Match on the value of the HTTP2 priority field present in a PRIORITY or HEADERS frame.
 
+http2.priority uses an :ref:`unsigned 8-bits integer <rules-integer-keywords>`.
+
 This keyword takes a numeric argument after a colon and supports additional qualifiers, such as:
 
 * ``>`` (greater than)
@@ -49,6 +51,8 @@ http2.window
 
 Match on the value of the HTTP2 value field present in a WINDOWUPDATE frame.
 
+http2.window uses an :ref:`unsigned 32-bits integer <rules-integer-keywords>`.
+
 This keyword takes a numeric argument after a colon and supports additional qualifiers, such as:
 
 * ``>`` (greater than)
@@ -68,6 +72,8 @@ Match on the size of the HTTP2 Dynamic Headers Table.
 More information on the protocol can be found here:
 `<https://tools.ietf.org/html/rfc7541#section-6.3>`_
 
+http2.size_update uses an :ref:`unsigned 64-bits integer <rules-integer-keywords>`.
+
 This keyword takes a numeric argument after a colon and supports additional qualifiers, such as:
 
 * ``>`` (greater than)

doc/userguide/rules/ike-keywords.rst

@@ -61,6 +61,8 @@ ike.exchtype
 
 Match on the value of the Exchange Type.
 
+ike.exchtype uses an :ref:`unsigned 8-bits integer <rules-integer-keywords>`.
+
 This keyword takes a numeric argument after a colon and supports additional qualifiers, such as:
 
 * ``>`` (greater than)
@@ -106,6 +108,8 @@ ike.key_exchange_payload_length
 
 Match against the length of the public key exchange payload (e.g. Diffie-Hellman) of the server or client.
 
+ike.key_exchange_payload_length uses an :ref:`unsigned 32-bits integer <rules-integer-keywords>`.
+
 This keyword takes a numeric argument after a colon and supports additional qualifiers, such as:
 
 * ``>`` (greater than)
@@ -138,6 +142,8 @@ ike.nonce_payload_length
 
 Match against the length of the nonce of the server or client.
 
+ike.nonce_payload_length uses an :ref:`unsigned 32-bits integer <rules-integer-keywords>`.
+
 This keyword takes a numeric argument after a colon and supports additional qualifiers, such as:
 
 * ``>`` (greater than)

doc/userguide/rules/index.rst

@@ -7,6 +7,7 @@ Suricata Rules
    meta
    header-keywords
    payload-keywords
+   integer-keywords
    transforms
    prefilter-keywords
    flow-keywords

doc/userguide/rules/integer-keywords.rst

@@ -0,0 +1,75 @@
+.. _rules-integer-keywords:
+
+Integer Keywords
+================
+
+Many keywords will match on an integer value on the network traffic.
+These are unsigned integers that can be 8, 16, 32 or 64 bits.
+
+Simple example::
+
+    bsize:integer value;
+
+The integer value can be written as base-10 like ``100`` or as 
+an hexadecimal value like ``0x64``.
+
+The most direct exemple is to match for equality, but there are
+different modes.
+
+Comparison modes
+----------------
+
+Integers can be matched for
+* Equality
+* Inequality
+* Greater than
+* Less than
+* Range
+* Negated range
+* Bitmask
+* Negated Bitmask
+
+Comparisons are strict by default. Ranges are thus exclusive.
+That means a range between 1 and 4 will match 2 and 3, but neither 1 nor 4.
+Negated range !1-4 will match for 1 or below and for 4 or above.
+
+Examples::
+
+    bsize:19; # equality
+    bsize:=0x13; # equality
+    bsize:!0x14; # inequality
+    bsize:!=20; # inequality
+    bsize:>21; # greater than
+    bsize:>=21; # greater than or equal
+    bsize:<22; # lesser than
+    bsize:<=22; # lesser than or equal
+    bsize:19-22; # range between value1 and value2
+    bsize:!19-22; # negated range between value1 and value2
+    bsize:&0xc0=0x80; # bitmask mask is compared to value for equality
+    bsize:&0xc0!=0; # bitmask mask is compared to value for inequality
+
+Enumerations
+------------
+
+Some integers on the wire represent an enumeration, that is, some values
+have a string/meaning associated to it.
+Rules can be written using one of these strings to check for equality.
+This is meant to make rules more human-readable and equivalent for matching.
+
+Examples::
+
+    websocket.opcode:text;
+    websocket.opcode:1; # behaves the same
+
+Bitmasks
+--------
+
+Some integers on the wire represent multiple bits.
+Some of these bits have a string/meaning associated to it.
+Rules can be written using a list (comma-separated) of these strings,
+where each item can be negated.
+
+Examples::
+
+    websocket.flags:fin,!comp;
+    websocket.flags:&0xc0=0x80; # behaves the same

doc/userguide/rules/mqtt-keywords.rst

@@ -8,6 +8,8 @@ mqtt.protocol_version
 
 Match on the value of the MQTT protocol version field in the fixed header.
 
+mqtt.protocol_version uses an :ref:`unsigned 8-bits integer <rules-integer-keywords>`.
+
 The format of the keyword::
 
   mqtt.protocol_version:<min>-<max>;