doc: add imap parser and sticky buffers

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

@@ -3388,3 +3388,27 @@ Example ::
     "min_ttl": 1,
     "max_ttl": 1
   }
+
+Event type: IMAP
+----------------
+
+Fields
+~~~~~~
+
+* "requests": Array of IMAP request lines sent by the client. Each entry is
+  formatted as "tag command arguments". ``LOGIN`` arguments and SASL initial
+  responses on ``AUTHENTICATE`` commands are replaced with ``<redacted>``.
+  Client responses to SASL continuation requests are not logged.
+* "responses": Array of IMAP response lines from the server.
+
+Example ::
+
+  "imap": {
+    "requests": [
+      "8 UID fetch 1 (UID RFC822.SIZE BODY.PEEK[])"
+    ],
+    "responses": [
+      "* 1 FETCH (UID 1 RFC822.SIZE 452 BODY[] {452})",
+      "8 OK UID FETCH completed"
+    ]
+  }

doc/userguide/rules/imap-keywords.rst

@@ -0,0 +1,79 @@
+IMAP Keywords
+=============
+
+.. role:: example-rule-action
+.. role:: example-rule-header
+.. role:: example-rule-options
+.. role:: example-rule-emphasis
+
+imap.request
+------------
+
+Matches on IMAP request lines sent from the client to the server.
+
+Each buffer is a request line as sent by the client, without the trailing
+CRLF. Literal data is not part of the buffer. Unlike the EVE
+``imap.requests`` field, ``LOGIN`` and ``AUTHENTICATE`` arguments are not
+redacted.
+
+Syntax::
+
+ imap.request; content:"<content to match against>";
+
+``imap.request`` is a 'sticky buffer' and can be used as a ``fast_pattern``.
+
+``imap.request`` supports multiple buffer matching, see :doc:`multi-buffer-matching`.
+
+This keyword maps to the EVE field ``imap.requests[]``
+
+Examples
+^^^^^^^^
+
+Example of a signature that would alert if an IMAP request contains a LOGIN command:
+
+.. container:: example-rule
+
+  alert imap any any -> any any (msg:"IMAP LOGIN request"; :example-rule-emphasis:`imap.request; content:"LOGIN";` sid:1;)
+
+imap.response
+-------------
+
+Matches on IMAP response lines sent from the server to the client.
+
+Syntax::
+
+ imap.response; content:"<content to match against>";
+
+``imap.response`` is a 'sticky buffer' and can be used as a ``fast_pattern``.
+
+``imap.response`` supports multiple buffer matching, see :doc:`multi-buffer-matching`.
+
+This keyword maps to the EVE field ``imap.responses[]``
+
+Examples
+^^^^^^^^
+
+Example of a signature that would alert if an IMAP response contains "OK":
+
+.. container:: example-rule
+
+  alert imap any any -> any any (msg:"IMAP OK response"; :example-rule-emphasis:`imap.response; content:"OK";` sid:1;)
+
+Frames
+------
+
+The IMAP parser supports the following frames:
+
+* imap.pdu
+
+imap.pdu
+^^^^^^^^
+
+A single IMAP request or response PDU. Each command from the client or
+response line from the server creates a separate frame.
+
+.. container:: example-rule
+
+  alert imap any any -> any any (\
+  :example-rule-options:`frame:imap.pdu; content:"LOGIN"; startswith;` \
+  sid:1;)

doc/userguide/rules/index.rst

@@ -41,6 +41,7 @@ Suricata Rules
    quic-keywords
    nfs-keywords
    smtp-keywords
+   imap-keywords
    websocket-keywords
    app-layer
    decode-layer

doc/userguide/rules/multi-buffer-matching.rst

@@ -94,6 +94,8 @@ following keywords:
 * ``http.response_header``
 * ``http2.header_name``
 * ``ike.vendor``
+* ``imap.request``
+* ``imap.response``
 * ``krb5.cname``
 * ``krb5.sname``
 * ``ldap.request.attribute_type``