File Keywords
=============

Suricata comes with several rule keywords to match on various file
properties. They depend on properly configured
:doc:`../file-extraction/file-extraction`.

filename
--------

Matches on the file name.

Syntax::

  filename:<string>;

Example::

  filename:"secret";

fileext
-------

Matches on the extension of a file name.

Syntax::

  fileext:<string>;

Example::

  fileext:"jpg";

filemagic
---------

Matches on the information libmagic returns about a file.

Syntax::

  filemagic:<string>;

Example::

  filemagic:"executable for MS Windows";

Note: as libmagic versions differ between installations, the returned
information may also slightly change. See also #437.

filestore
---------

Stores files to disk if the signature matched.

Syntax::

  filestore:<direction>,<scope>;

direction can be:

* request/to_server: store a file in the request / to_server direction
* response/to_client: store a file in the response / to_client direction
* both: store both directions

scope can be:

* file: only store the matching file (for filename,fileext,filemagic matches)
* tx: store all files from the matching HTTP transaction
* ssn/flow: store all files from the TCP session/flow.

If direction and scope are omitted, the direction will be the same as
the rule and the scope will be per file.

filemd5
-------

Match file :ref:`MD5 <md5>` against list of MD5 checksums.

Syntax::

  filemd5:[!]filename;

The filename is expanded to include the rule dir. In the default case
it will become /etc/suricata/rules/filename. Use the exclamation mark
to get a negated match. This allows for white listing.

Examples::

  filemd5:md5-blacklist;
  filemd5:!md5-whitelist;

*File format*

The file format is simple. It's a text file with a single md5 per
line, at the start of the line, in hex notation. If there is extra
info on the line it is ignored.

Output from md5sum is fine::

  2f8d0355f0032c3e6311c6408d7c2dc2  util-path.c
  b9cf5cf347a70e02fde975fc4e117760  util-pidfile.c
  02aaa6c3f4dbae65f5889eeb8f2bbb8d  util-pool.c
  dd5fc1ee7f2f96b5f12d1a854007a818  util-print.c

Just MD5's are good as well::

  2f8d0355f0032c3e6311c6408d7c2dc2
  b9cf5cf347a70e02fde975fc4e117760
  02aaa6c3f4dbae65f5889eeb8f2bbb8d
  dd5fc1ee7f2f96b5f12d1a854007a818

*Memory requirements*

Each MD5 uses 16 bytes of memory. 20 Million MD5's use about 310 MiB of memory.

See also: http://blog.inliniac.net/2012/06/09/suricata-md5-blacklisting/

filesize
--------

Match on the size of the file as it is being transferred.

Syntax::

  filesize:<value>;

Examples::

  filesize:100; # exactly 100 bytes
  filesize:100<>200; # greater than 100 and smaller than 200
  filesize:>100; # greater than 100
  filesize:<100; # smaller than 100

**Note**: For files that are not completely tracked because of packet
loss or stream.depth being reached on the "greater than" is
checked. This is because Suricata can know a file is bigger than a
value (it has seen some of it already), but it can't know if the final
size would have been within a range, an exact value or smaller than a
value.