Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

doc: update file keywords v1 #9245

Closed
wants to merge 2 commits into from
Closed

doc: update file keywords v1 #9245

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1c500f3
doc: update file.name keyword information
jmtaylor90 Jul 17, 2023
537d7dd
doc: update file.magic keyword information
jmtaylor90 Jul 17, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
33 changes: 23 additions & 10 deletions doc/userguide/rules/file-keywords.rst
View file
Open in desktop
Expand Up @@ -5,21 +5,25 @@ 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.

Syntax::

filename:<string>;
file.name:<string>;

Example::

filename:"secret";
file.name:"secret";

``file.name`` supports multiple buffer matching, see :doc:`multi-buffer-matching`.

**Note** The ``filename`` keyword is still supported but the
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is no longer true:

filename:"secret"; is now equivalent to file.name; content:"secret"; nocase;

Similarly, fileext:
fileext:pdf; is equivalent to file.name; content:".pdf"; nocase; endswith;. Note the dot that is prepended to pdf.

This is handled at parsing, so at runtime this is identical in behavior and performance.

btw we're looking at backporting this optimization to 6: https://redmine.openinfosecfoundation.org/issues/6203

``file.name`` convention is preferred due to better performance
in signature evaluation.

fileext
-------

Expand All @@ -33,24 +37,33 @@ Example::

fileext:"jpg";

filemagic
---------
file.magic
----------

Matches on the information libmagic returns about a file.

Syntax::

filemagic:<string>;
file.magic:<string>;
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This incorrect. filemagic is the legacy notation, that uses:
filemagic:"Windows";
file.magic is the new implementation:
file.magic; content:"Windows"; nocase;

Note that like with filename above, the difference exists only during parsing in 7.


Example::

filemagic:"executable for MS Windows";
file.magic:"executable for MS Windows";

Note: as libmagic versions differ between installations, the returned
information may also slightly change. See also #437.
**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`.

**Note** The ``filemagic`` keyword is still supported but the
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

perf should now be identical

``file.magic`` convention is preferred due to better performance
in signature evaluation.

filestore
---------

Expand Down