Websockets 2695 v12

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
@@ -35,6 +36,7 @@ Suricata Rules
    quic-keywords
    nfs-keywords
    smtp-keywords
+   websocket-keywords
    app-layer
    xbits
    thresholding

doc/userguide/rules/integer-keywords.rst

@@ -0,0 +1,74 @@
+.. _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
+* Lesser than
+* Range
+* Negated range
+* Bitmask
+* Negated Bitmask
+
+Comparison are strict by default.
+That means range between 1 and 4, will match 2 and 3, but not 1 neither 4.
+
+Examples::
+
+    bsize:integer value; # equality
+    bsize:=integer value; # equality
+    bsize:!integer value; # inequality
+    bsize:!=integer value; # inequality
+    bsize:>integer value; # greater than
+    bsize:>=integer value; # greater than or equal
+    bsize:<integer value; # lesser than
+    bsize:<=integer value; # lesser than or equal
+    bsize:integer value1-integer value2; # range between value1 and value2
+    bsize:!integer value1-integer value2; # negated range between value1 and value2
+    bsize:&mask=value; # bitmask mask is compared to value for equality
+    bsize:&mask!=value; # 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::
+
+    websocker.opcode:text;
+    websocker.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-seperated) of these strings,
+where each item can be negated.
+
+Examples::
+
+    websocket.flags:fin,!comp;
+    websocker.flags:&0xc0=0x80; # behaves the same

doc/userguide/rules/intro.rst

@@ -110,6 +110,7 @@ you can pick from. These are:
 * snmp
 * tftp
 * sip
+* websocket
 
 The availability of these protocols depends on whether the protocol
 is enabled in the configuration file, suricata.yaml.

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>;

doc/userguide/rules/payload-keywords.rst

@@ -280,6 +280,8 @@ bsize
 With the ``bsize`` keyword, you can match on the length of the buffer. This adds
 precision to the content match, previously this could have been done with ``isdataat``.
 
+bsize uses an, :ref:` unsigned 64-bits integer <rules-integer-keywords>`.
+
 An optional operator can be specified; if no operator is present, the operator will
 default to '='. When a relational operator is used, e.g., '<', '>' or '<>' (range),
 the bsize value will be compared using the relational operator. Ranges are inclusive.
@@ -336,6 +338,8 @@ This may be convenient in detecting buffer overflows.
 
 dsize cannot be used when using app/streamlayer protocol keywords (i.e. http.uri)
 
+dsize uses an, :ref:` unsigned 16-bits integer <rules-integer-keywords>`.
+
 Format::
 
   dsize:[<>!]number; || dsize:min<>max;

doc/userguide/rules/rfb-keywords.rst

@@ -36,6 +36,8 @@ rfb.sectype
 
 Match on the value of the RFB security type field, e.g. ``2`` for VNC challenge-response authentication, ``0`` for no authentication, and ``30`` for Apple's custom Remote Desktop authentication.
 
+rfb.sectype 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/tls-keywords.rst

@@ -284,6 +284,8 @@ tls.cert_chain_len
 
 Matches on the TLS certificate chain length.
 
+tls.cert_chain_len uses an, :ref:` unsigned 32-bits integer <rules-integer-keywords>`.
+
 tls.cert_chain_len supports `<, >, <>, !` and using an exact value.
 
 Example::

doc/userguide/rules/websocket-keywords.rst

@@ -0,0 +1,57 @@
+WebSocket Keywords
+==================
+
+websocket.payload
+-----------------
+
+A sticky buffer on the unmasked payload,
+limited by suricata.yaml config value ``websocket.max-payload-size``.
+
+Examples::
+
+  websocket.payload; pcre:"/^123[0-9]*/";
+  websocket.payload content:"swordfish";
+
+``websocket.payload`` is a 'sticky buffer' and can be used as ``fast_pattern``.
+
+websocket.flags
+---------------
+
+Matches on the websocket flags.
+It uses a 8-bit unsigned integer as value.
+Only the four upper bits are used.
+
+The value can also be a list of strings (comma-separated),
+where each string is the name of a specific bit like `fin` and `comp`,
+and can be prefixed by `!` for negation.
+
+Examples::
+
+  websocket.flags:128;
+  websocket.flags:&0x40=0x40;
+  websocket.flags:fin,!comp;
+
+websocket.mask
+--------------
+
+Matches on the websocket mask if any.
+It uses a 32-bit unsigned integer as value (big-endian).
+
+Examples::
+
+  websocket.mask:123456;
+  websocket.mask:>0;
+
+websocket.opcode
+----------------
+
+Matches on the websocket opcode.
+It uses a 8-bit unsigned integer as value.
+Only 16 values are relevant.
+It can also be specified by text from the enumeration
+
+Examples::
+
+  websocket.opcode:1;
+  websocket.opcode:>8;
+  websocket.opcode:ping;