From: Jeff Lucovsky <jlucovsky@oisf.net>
Date: Sat, 29 Mar 2025 17:48:38 +0000 (-0400)
Subject: doc/ftp: Document ftp.completion_code sticky buffer
X-Git-Tag: suricata-8.0.0-rc1~252
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F13262%2Fhead;p=thirdparty%2Fsuricata.git

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 93f224e629..9c378a482d 100644
--- 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
 ----------------