From 5f898cb50f3607df5c6cc896cdf7550990ad7caf Mon Sep 17 00:00:00 2001 From: jason taylor Date: Mon, 17 Jul 2023 16:36:58 +0000 Subject: [PATCH 1/3] doc: update file.name keyword information Signed-off-by: jason taylor --- doc/userguide/rules/file-keywords.rst | 24 +++++++++++++++++------- 1 file changed, 17 insertions(+), 7 deletions(-) diff --git a/doc/userguide/rules/file-keywords.rst b/doc/userguide/rules/file-keywords.rst index 199bf5f6411c..9f2ce750a991 100644 --- a/doc/userguide/rules/file-keywords.rst +++ b/doc/userguide/rules/file-keywords.rst @@ -5,20 +5,30 @@ Suricata comes with several rule keywords to match on various file properties. They depend on properly configured :doc:`../file-extraction/file-extraction`. -filename --------- +file.name +--------- -Matches on the file name. +``file.name`` is a sticky buffer that is used to look at filenames +that are seen in flows that Suricata evaluates. The various payload +keywords can be used (e.g. ``startswith``, ``nocase`` and ``bsize``) +with ``file.name``. -Syntax:: +Example:: - filename:; + file.name; content:"examplefilename"; + +``file.name`` supports multiple buffer matching, see :doc:`multi-buffer-matching`. + +**Note** ``filename`` can still be used. A notable difference between +``file.name`` and ``filename`` is that ``filename`` assumes ``nocase`` +by default. In the example below the two signatures are considered +the same. Example:: - filename:"secret"; + filename:"examplefilename"; -``file.name`` supports multiple buffer matching, see :doc:`multi-buffer-matching`. + file.name; content:"examplefilename"; nocase; fileext ------- From 6814d82c228f3e7f20e24dc7b661ab384be6464b Mon Sep 17 00:00:00 2001 From: jason taylor Date: Tue, 18 Jul 2023 21:17:31 +0000 Subject: [PATCH 2/3] doc: update fileext keyword information Signed-off-by: jason taylor --- doc/userguide/rules/file-keywords.rst | 34 +++++++++++++++++++++++---- 1 file changed, 29 insertions(+), 5 deletions(-) diff --git a/doc/userguide/rules/file-keywords.rst b/doc/userguide/rules/file-keywords.rst index 9f2ce750a991..ec7fd1ab6a6c 100644 --- a/doc/userguide/rules/file-keywords.rst +++ b/doc/userguide/rules/file-keywords.rst @@ -31,17 +31,41 @@ Example:: file.name; content:"examplefilename"; nocase; fileext -------- +-------- -Matches on the extension of a file name. +``fileext`` is used to look at individual file extensions that are +seen in flows that Suricata evaluates. -Syntax:: +Example:: + + fileext:"pdf"; + +**Note:** ``fileext`` does not allow partial matches. For example, if +a PDF file (.pdf) is seen by a Suricata signature with +fileext:"pd"; the signature will not produce an alert. + +**Note:** ``fileext`` assumes ``nocase`` by default. This means +that a file with the extension .PDF will be seen the same as if +the file had an extension of .pdf. + +**Note:** ``fileext`` and ``file.name`` can both be used to match on +file extensions. In the example below the two signatures are +considered the same. + +Example:: + + fileext:"pdf"; + + file.name; content:".pdf"; nocase; endswith; - fileext:; +**Note**: While``fileeext`` and ``file.name`` can both be used +to match on file extensions, ``file.name`` allows for partial +matching on file extensions. The following would match on a file +with the extension of .pd as well as .pdf. Example:: - fileext:"jpg"; + file.name; content:".pd"; filemagic --------- From 12d608fab1949174d92c3b33679d34527d9bfba6 Mon Sep 17 00:00:00 2001 From: jason taylor Date: Tue, 1 Aug 2023 15:34:08 +0000 Subject: [PATCH 3/3] doc: update file.magic information Signed-off-by: jason taylor --- doc/userguide/rules/file-keywords.rst | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/doc/userguide/rules/file-keywords.rst b/doc/userguide/rules/file-keywords.rst index ec7fd1ab6a6c..a9b24deafe07 100644 --- a/doc/userguide/rules/file-keywords.rst +++ b/doc/userguide/rules/file-keywords.rst @@ -67,21 +67,33 @@ Example:: file.name; content:".pd"; -filemagic ---------- +file.magic +---------- Matches on the information libmagic returns about a file. -Syntax:: +Example:: - filemagic:; + file.magic; content:"executable for MS Windows"; + +**Note** ``filemagic`` can still be used. The only difference between +``file.magic`` and ``file.magic`` is that ``filemagic`` assumes ``nocase`` +by default. In the example below the two signatures are considered +the same. Example:: filemagic:"executable for MS Windows"; -Note: as libmagic versions differ between installations, the returned -information may also slightly change. See also #437. + file.magic; content:"executable for MS Windows"; nocase; + +Note: Suricata currently uses its underlying operating systems +version/implementation of libmagic. Different versions and +implementations of libmagic do not return the same information. +Additionally there are varying Suricata performance impacts +based on the version and implementation of libmagic. +Additional information about Suricata and libmagic can be found +here: https://redmine.openinfosecfoundation.org/issues/437 ``file.magic`` supports multiple buffer matching, see :doc:`multi-buffer-matching`.