From 5b1f50ef0de09c11fb9ba513eb47386911f33521 Mon Sep 17 00:00:00 2001
From: Giuseppe Longo <glongo@oisf.net>
Date: Wed, 11 Feb 2026 10:54:45 +0100
Subject: [PATCH] doc: add imap parser and sticky buffers

---
 doc/userguide/output/eve/eve-json-format.rst  | 24 ++++++
 doc/userguide/rules/imap-keywords.rst         | 79 +++++++++++++++++++
 doc/userguide/rules/index.rst                 |  1 +
 doc/userguide/rules/multi-buffer-matching.rst |  2 +
 4 files changed, 106 insertions(+)
 create mode 100644 doc/userguide/rules/imap-keywords.rst

diff --git a/doc/userguide/output/eve/eve-json-format.rst b/doc/userguide/output/eve/eve-json-format.rst
index 0f36559bd7..0a333e4c84 100644
--- a/doc/userguide/output/eve/eve-json-format.rst
+++ b/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"
+    ]
+  }
diff --git a/doc/userguide/rules/imap-keywords.rst b/doc/userguide/rules/imap-keywords.rst
new file mode 100644
index 0000000000..f8b791a80c
--- /dev/null
+++ b/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;)
diff --git a/doc/userguide/rules/index.rst b/doc/userguide/rules/index.rst
index b8d21f0c59..7a2f183487 100644
--- a/doc/userguide/rules/index.rst
+++ b/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
diff --git a/doc/userguide/rules/multi-buffer-matching.rst b/doc/userguide/rules/multi-buffer-matching.rst
index fd54819d87..60f07d602b 100644
--- a/doc/userguide/rules/multi-buffer-matching.rst
+++ b/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``