http2: adds documentation

doc/userguide/output/eve/eve-json-format.rst

@@ -1300,7 +1300,6 @@ Example of RFB logging, with full VNC style authentication parameters:
       }
     }
 
-
 Event type: MQTT
 ----------------
 
@@ -1681,5 +1680,106 @@ Example of a truncated MQTT PUBLISH message (with 10000 being the maximum length
         "truncated": true,
         "skipped_length": 100011
       }
+
+Event type: HTTP2
+-----------------
+
+Fields
+~~~~~~
+
+There are the two fields "request" and "response" which can each contain the same set of fields :
+* "settings": a list of settings with "name" and "value"
+* "headers": a list of headers with either "name" and "value", or "table_size_update", or "error" if any
+* "error_code": the error code from GOAWAY or RST_STREAM, which can be "NO_ERROR"
+* "priority": the stream priority.
+
+
+Examples
+~~~~~~~~
+
+Example of HTTP2 logging, of a settings frame:
+
+::
+
+  "http2": {
+    "request": {
+      "settings": [
+        {
+          "settings_id": "SETTINGSMAXCONCURRENTSTREAMS",
+          "settings_value": 100
+        },
+        {
+          "settings_id": "SETTINGSINITIALWINDOWSIZE",
+          "settings_value": 65535
+        }
+      ]
+    },
+    "response": {}
+  }
+
+Example of HTTP2 logging, of a request and response:
+
+::
+
+  "http2": {
+    "request": {
+      "headers": [
+        {
+          "name": ":authority",
+          "value": "localhost:3000"
+        },
+        {
+          "name": ":method",
+          "value": "GET"
+        },
+        {
+          "name": ":path",
+          "value": "/doc/manual/html/index.html"
+        },
+        {
+          "name": ":scheme",
+          "value": "http"
+        },
+        {
+          "name": "accept",
+          "value": "*/*"
+        },
+        {
+          "name": "accept-encoding",
+          "value": "gzip, deflate"
+        },
+        {
+          "name": "user-agent",
+          "value": "nghttp2/0.5.2-DEV"
+        }
+      ]
+    },
+    "response": {
+      "headers": [
+        {
+          "name": ":status",
+          "value": "200"
+        },
+        {
+          "name": "server",
+          "value": "nghttpd nghttp2/0.5.2-DEV"
+        },
+        {
+          "name": "content-length",
+          "value": "22617"
+        },
+        {
+          "name": "cache-control",
+          "value": "max-age=3600"
+        },
+        {
+          "name": "date",
+          "value": "Sat, 02 Aug 2014 10:50:25 GMT"
+        },
+        {
+          "name": "last-modified",
+          "value": "Sat, 02 Aug 2014 07:58:59 GMT"
+        }
+      ]
     }
   }

doc/userguide/rules/http2-keywords.rst

@@ -0,0 +1,134 @@
+HTTP2 Keywords
+==============
+
+HTTP2 frames are grouped into transactions based on the stream identifier it it is not 0.
+For frames with stream identifier 0, whose effects are global for the connection, a transaction is created for each frame.
+
+
+http2.frametype
+---------------
+
+Match on the frame type present in a transaction.
+
+Examples::
+
+  http2.frametype:GOAWAY;
+
+
+http2.errorcode
+---------------
+
+Match on the error code in a GOWAY or RST_STREAM frame
+
+Examples::
+
+  http2.errorcode: NO_ERROR;
+  http2.errorcode: INADEQUATE_SECURITY;
+
+
+http2.priority
+--------------
+
+Match on the value of the HTTP2 priority field present in a PRIORITY or HEADERS frame.
+
+This keyword takes a numeric argument after a colon and supports additional qualifiers, such as:
+
+* ``>`` (greater than)
+* ``<`` (less than)
+* ``x-y`` (range between values x and y)
+
+Examples::
+
+  http2.priority:2;
+  http2.priority:>100;
+  http2.priority:32-64;
+
+
+http2.window
+------------
+
+Match on the value of the HTTP2 value field present in a WINDOWUPDATE frame.
+
+This keyword takes a numeric argument after a colon and supports additional qualifiers, such as:
+
+* ``>`` (greater than)
+* ``<`` (less than)
+* ``x-y`` (range between values x and y)
+
+Examples::
+
+  http2.window:1;
+  http2.window:<100000;
+
+
+http2.size_update
+-----------------
+
+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>`_
+
+This keyword takes a numeric argument after a colon and supports additional qualifiers, such as:
+
+* ``>`` (greater than)
+* ``<`` (less than)
+* ``x-y`` (range between values x and y)
+
+Examples::
+
+  http2.size_update:1234;
+  http2.size_update:>4096;
+
+
+http2.settings
+--------------
+
+Match on the name and value of a HTTP2 setting from a SETTINGS frame.
+
+This keyword takes a numeric argument after a colon and supports additional qualifiers, such as:
+
+* ``>`` (greater than)
+* ``<`` (less than)
+* ``x-y`` (range between values x and y)
+
+Examples::
+
+  http2.settings:SETTINGS_ENABLE_PUSH=0;
+  http2.settings:SETTINGS_HEADER_TABLE_SIZE>4096;
+
+http2.header_name
+-----------------
+
+Match on the name of a HTTP2 header from a HEADER frame (or PUSH_PROMISE or CONTINUATION).
+
+Examples::
+
+  http2.header_name; content:"agent";
+
+``http2.header_name`` is a 'sticky buffer'.
+
+``http2.header_name`` can be used as ``fast_pattern``.
+
+
+http2.header
+-----------------
+
+Match on the name and value of a HTTP2 header from a HEADER frame (or PUSH_PROMISE or CONTINUATION).
+Name and value get concatenated by ": ", colon and space.
+Each colon in the name or the value should be escaped as a double colon "::" for detection
+
+Examples::
+
+  http2.header; content:"agent: nghttp2";
+  http2.header; content:"custom-header: I love::colons";
+
+``http2.header`` is a 'sticky buffer'.
+
+``http2.header`` can be used as ``fast_pattern``.
+
+
+Additional information
+----------------------
+
+More information on the protocol can be found here:
+`<https://tools.ietf.org/html/rfc7540>`_

doc/userguide/rules/index.rst

@@ -27,6 +27,7 @@ Suricata Rules
    sip-keywords
    rfb-keywords
    mqtt-keywords
+   http2-keywords
    app-layer
    xbits
    thresholding

doc/userguide/rules/intro.rst

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