Documentation

Documentation

• Introduction
• Requirements
• Monitoring
  • Whole system
    • Specified path
    • Include subdirectories
• Matching rules
  • Normal rule (wildcard)
  • Regular expression
• Capturing
  • Copy to location
  • FTP upload
• Advanced
  • Reading
    • Ignore reading errors
    • Buffer size
    • Do not update file access time
  • Writing
    • Filename format
    • Overwrite files with same filename
    • Create directory tree
    • Preserve timestamps

Introduction

You can use FileGrab to capture newly created files in Windows filesystems. Once a file that matches with user specified pattern is created in the monitored location, FileGrab can then copy this file to another location.

This is particularly useful for honeypots, malware analysis, auditing and so on.

Requirements

• .NET Framework 2.0
• Internet connection (for FTP file uploading)

Monitoring

FileGrab uses the FileSystemWatcher .NET class for filesystem monitoring. You may want to check its documentation too.

Whole system

With this option, FileGrab will enumerate all fixed volumes and monitors each of them. Be sure to run FileGrab as an Administrator to have full read access to all mounted filesystems.

Specified path

If you select this option, FileGrab will monitor the specified directory only.

Include subdirectories

If checked, the specified path and all its subdirectories will be monitored. This option is the default when Whole sytem is checked.

Matching rules

Still in Monitor tab, you can specify a file matching rule of two different types (notice that FileGrab is case insenstive, just like Windows filesystems):

Normal rule (wildcard)

The fatest method. Using this option you can specify rules using MS-DOS file matching patterns, like in the following examples:

Matching rule	Matches the following files
*.*	All files (default). An empty string ("") also watches all files.
*.txt	All files with a "txt" extension.
*recipe.doc	All files ending in "recipe" with a "doc" extension.
win*.xml	All files beginning with "win" with an "xml" extension.
Sales*200?.xls	Matches "Sales July 2001.xls", "Sales Aug 2002.xls" and "Sales March 2004.xls" but does not match "Sales Nov 1999.xls"
MyReport.Doc	Matches only "MyReport.doc"

As you may have noticed, you can not negate a normal rule. It is a limitation of FileSystemWatcher class. If you want to set a non-matching rule, please use a regular expression instead.

Regular expression

If you need a more advanced filename matching rule, you can set a regular expression instead. Using it will significantly impact the overall performance as FileGrab will catch all file created in the monitored directory and match it against the regular expression. Examples:

Matching rule	Matching rule
^.*\.(exe|dll)$	All files with a "exe" or "dll" extension.
settings[0-9]\..*$	Files beginning with "settings", followed by a digit, with any extesion.

Optionally, you can check the "Not" checkbox to negate it, so all non-matching filenames.

The matching rule is for filename only. You cannot use it to match directory names because you cannot monitor multiple directories in different trees.

Capturing

Once a file is created, you can choose one of the following capture options, or both:

Copy to location

You can specify a directory where the captured files will be copied to. This directory will not be monitored, even if it is in the same tree of configured monitoring path.

FTP upload

Optionally, you can upload the captured files to a FTP server. Just configure the required settings and click on "Test" button to make sure you have connection there.

Once your settings are done, you can click on "Start" button to being monitoring files. Matched files will be shown in the status bar. The "Hide" checkbox will hide the window (useful for interactive honeypots) but there is no way to unhide the window yet. You shall kill FileGrab process to end the application.

Advanced

Reading

Ignore reading errors

If a file is deleted just after its creation, maybe FileGrab won't be able to read it completely. The volume where the file is saved can be suddenly disconnected, got its filesystem corrupted or throw any other exception. In this option is set, FileGrab will ignore errors and keep monitoring files. Otherwise it will show a message with the error details.

Permissions can also be a problem. Run FileGrab as an Administrator can be a good way for preventing such kind of errors.

Buffer size

You can set the buffer size to 4, 8, 16 (default), 32 or 64 KB. The system notifies the component of file changes, and it stores those changes in a buffer the component creates and passes to the APIs. Each event can use up to 16 bytes of memory, not including the file name. If there are many changes in a short time, the buffer can overflow. This causes the component to lose track of changes in the directory, and it will only provide blanket notification. Increasing the size of the buffer can prevent missing file system change events. However, increasing buffer size is expensive, because it comes from non-paged memory that cannot be swapped out to disk, so keep the buffer as small as possible. To reduce the chances of a buffer overflow, consider set a single monitoring directory, with a good regular (wildcard) filter.

Do not update file access time

This option is not implemented yet.

Writing

Filename format

This option is not implemented yet.

Overwrite files with same filename

If the filename exists in the destiny folder, overwrite it. This option is valid to "Copy to location" mode only. Overwriting in FTP upload is not supported yet.

Create directory tree

This option is not implemented yet.

Preserve timestamps

Read creation, modification and access timestamps from source file and write it to destiny file.