doc/ftp: Document ftp.completion_code sticky buffer

This commit adds documentation for the ftp.completion_code sticky
buffer. This is a multi-buffer match.

Issue: 7507

diff --git a/doc/userguide/rules/ftp-keywords.rst b/doc/userguide/rules/ftp-keywords.rst
index 93f224e6290f01ed20e608c1a142e4f962efbf10..9c378a482d16c1edfaed03be20eee33ffd3f132d 100644 (file)
--- a/doc/userguide/rules/ftp-keywords.rst
+++ b/doc/userguide/rules/ftp-keywords.rst
@@ -113,6 +113,57 @@ Example rules for each of the preceding FTP commands and command data.
 
   alert ftp any any -> any any (:example-rule-options:`ftp.command_data; content:"192,168,0,13,234,10";` sid: 3;)
 
+ftp.completion_code
+-------------------
+
+This keyword matches on an FTP completion code string. Note that there may be multiple reply strings for
+an FTP command and hence, multiple completion code values to check. ``ftp.completion_code`` is a sticky buffer
+and can be used as a fast pattern. Do not include the response string in the `content` to match upon (see examples).
+
+Syntax::
+
+  ftp.completion_code; content: <quoted-completion-code>;
+
+Signature Example:
+
+.. container:: example-rule
+
+  alert ftp any any -> any any (:example-rule-options:`ftp.completion_code; content:"226";` sid: 1;)
+
+.. note ::
+   FTP commands can return multiple reply strings. Specify a single completion code for each ``ftp.completion_code`` keyword.
+
+
+This example shows an FTP command (``RETR``) followed by an FTP reply with multiple response strings.
+::
+
+    RETR temp.txt
+    150 Opening BINARY mode data connection for temp.txt (1164 bytes).
+    226 Transfer complete.
+
+
+Because there are multiple completion codes and responses, the rule can match on
+``ftp.reply`` and the ``ftp.completion_code``.  Suricata cannot guarantee that
+these come from the `same response`, however.
+
+Signature Examples:
+
+.. container:: example-rule
+
+  alert ftp any any -> any any (ftp.reply; content:"Opening BINARY mode data connection for temp."; \
+  :example-rule-options:`ftp.completion_code; content: "150";` sid: 1;)
+
+.. container:: example-rule
+
+  alert ftp any any -> any any (:example-rule-options:`ftp.completion_code; content: "226";` sid: 2;)
+
+.. container:: example-rule
+
+  alert ftp any any -> any any (
+  ftp.reply; content: "Transfer complete.";
+  :example-rule-options:`ftp.completion_code; content: "226";` sid: 3;)
+
+
 ftp.dynamic_port
 ----------------