From: Victor Julien <vjulien@oisf.net>
Date: Tue, 4 Jun 2024 10:30:12 +0000 (+0200)
Subject: doc/userguide: add documentation for SMTP frames
X-Git-Tag: suricata-8.0.0-beta1~1197
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F11236%2Fhead;p=thirdparty%2Fsuricata.git

doc/userguide: add documentation for SMTP frames
---

diff --git a/doc/userguide/rules/smtp-keywords.rst b/doc/userguide/rules/smtp-keywords.rst
index ec91f6fc0c..8369856b9f 100644
--- a/doc/userguide/rules/smtp-keywords.rst
+++ b/doc/userguide/rules/smtp-keywords.rst
@@ -16,4 +16,59 @@ Signature Example:
   :example-rule-options:`file.name; content:"winmail.dat";` \
   classtype:bad-unknown; sid:1; rev:1;)
 
-For additional information on the ``file.name`` keyword, see :doc:`file-keywords`.
\ No newline at end of file
+For additional information on the ``file.name`` keyword, see :doc:`file-keywords`.
+
+Frames
+------
+
+The SMTP parser supports the following frames:
+
+* smtp.command_line
+* smtp.response_line
+* smtp.data
+* smtp.stream
+
+smtp.command_line
+~~~~~~~~~~~~~~~~~
+
+A single line from the client to the server. Multi-line commands will have a frame per
+line. Lines part of the SMTP DATA transfer are excluded.
+
+.. container:: example fule
+
+  alert smtp any any -> any any ( \
+  :example-rule-options:`frame:smtp.command_line; content:"MAIL|20|FROM:"; startswith;` \
+  sid:1;)
+
+smtp.response_line
+~~~~~~~~~~~~~~~~~~
+
+A single line from the server to the client. Multi-line commands will have a frame per line.
+
+.. container:: example fule
+
+  alert smtp any any -> any any ( \
+  :example-rule-options:`frame:smtp.response_line; content:"354 go ahead"; startswith;` \
+  sid:1;)
+
+smtp.data
+~~~~~~~~~
+
+A streaming buffer containing the DATA bytes sent from client to server.
+
+.. container:: example fule
+
+  alert smtp any any -> any any ( \
+  :example-rule-options:`frame:smtp.data; content:"Reply-To:"; startswith; content:"Subject"; distance:0;` \
+  sid:1;)
+
+smtp.stream
+~~~~~~~~~~~
+
+Streaming buffer of the entire TCP data for the SMTP session.
+
+.. container:: example fule
+
+  alert smtp any any -> any any (flow:to_client; \
+  :example-rule-options:`frame:smtp.stream; content:"250 ok|0d 0a|354 go ahead";` \
+  sid:1;)