Audit.FileSystem 22.0.1

Audit.FileSystem

File System Extension for Audit.NET library.

Generate Audit Logs by intercepting file system events via FileSystemWatcher.

Audit.FileSystem provides the infrastructure to create audit logs from the file system events, like creating, renaming, modifying or deleting files and directories. It relies on FileSystemWatcher class to intercept the events, so the same limitations applies.

Install

NuGet Package

To install the package run the following command on the Package Manager Console:

PM> Install-Package Audit.FileSystem

Usage

To enable the audit log for a directory, create an instance of FileSystemMonitor clas, and call its Start() method:

var fsMon = new Audit.FileSystem.FileSystemMonitor(@"c:\");
fsMon.Options.IncludeSubdirectories = true;
fsMon.Start();

Or by using the FileSystemMonitorOptions to provide the configuration:

var fsMon = new Audit.FileSystem.FileSystemMonitor(new FileSystemMonitorOptions()
{
    Path = @"c:\",
    IncludeSubdirectories = true,
    Filter = "*.txt",
    IncludeContentPredicate = fi => fi.Length <= 1024 ? FileSystem.ContentType.Text : FileSystem.ContentType.None,
    CustomFilterPredicate = e => !e.FullPath.StartsWith("$RECYCLE.BIN")                    
});

Configuration

Output

The audit events are stored using a Data Provider. You can use one of the available data providers or implement your own. Please refer to the data providers section on Audit.NET documentation.

Settings

The FileSystemMonitorOptions class include the following settings:

Mandatory:

• Path: The path of the directory to monitor.

Optional:

• EventTypeName: A string that identifies the event type. Default is "[{type}] {name}". Can contain the following placeholders:
  • {type}: replaced with the event type (Change, Rename, Create or Delete)
  • {name}: replaced with the file/directory name
  • {path}: replaced with the full file/directory path
• IncludeSubdirectories: To indicate if the subdirectories of the provided Path should be monitored. Default is false.
• IncludedEventTypes: A list indicating the event types (Change, Rename, Create or Delete) that should be included on the audit. Default is NULL meaning all the event types will be logged.
• Filter: The filter string used to determine what files are monitored. Default is "*.*"
• CustomFilterPredicate: Allows to filter events with a custom function that given a file event, returns true if the entry should be logged and false otherwise. Default includes all the files satisfying the provided Filter string.
• IncludeContentPredicate: Allows to determine if the file contents should be included in the log with a custom function that given a file event, returns a ContentType indicating whether the contents should be included as a string (Text), as a byte array (Binary) or not included (None). By default content is not included.
• NotifyFilters: The notify filters. Default is DirectoryName | FileName | LastAccess | LastWrite.
• IgnoreMD5: To indicate if the MD5 computation should be ignored. By default the MD5 hash of the file is included on the log.
• InternalBufferSize: Gets or sets the size (in bytes) of the internal buffer.
• AuditDataProvider: To indicate the Audit Data Provider to use. Default is NULL to use the globally configured data provider.
• CreationPolicy: To indicate the event creation policy to use. Default is NULL to use the globally configured creation policy.
• AuditScopeFactory: Allows to set a specific audit scope factory. By default the general AuditScopeFactory is used.

Output

Audit.FileSystem output includes:

• Execution time.
• Environment information.
• File/Directory name, attributes and properties
• File MD5 hash (optional)
• File contents (optional)

Output Details

The following table describes the Audit.FileSystem output fields:

FileSystemEvent

Describes an event from the file system.

FileContent

Represents the contents of an audited file.

Output Sample

File creation:

{
  "EventType": "[Created] file.txt",
  "Environment": {
    "UserName": "Federico",
    "MachineName": "HP",
    "DomainName": "HP",
    "Culture": "en-US"
  },
  "StartDate": "2017-11-26T23:01:44.5567169-06:00",
  "EndDate": "2017-11-26T23:01:44.5567169-06:00",
  "Duration": 0,
  "FileSystemEvent": {
    "Object": "File",
    "Event": "Create",
    "Attributes": "Archive",
    "Name": "file.txt",
    "Extension": ".txt",
    "FullPath": "c:\\Users\\Federico\\Documents\\file.txt",
    "Length": 694,
    "CreationTime": "2017-11-26T23:01:11.750589-06:00",
    "LastAccessTime": "2017-11-26T23:01:11.750589-06:00",
    "LastWriteTime": "2017-11-26T23:01:11.7515849-06:00",
    "MD5": "ddc032e5fe9bb3aa15144cdc35d959c5"
  }
}

File renaming

{
  "EventType": "[Renamed] renamed.txt",
  "Environment": {
    "UserName": "Federico",
    "MachineName": "HP",
    "DomainName": "HP",
    "Culture": "en-US"
  },
  "StartDate": "2017-11-26T23:01:37.8409103-06:00",
  "EndDate": "2017-11-26T23:01:37.8409103-06:00",
  "Duration": 0,
  "FileSystemEvent": {
    "Object": "File",
    "Event": "Rename",
    "OldName": "file.txt",
    "Name": "renamed.txt",
    "Extension": ".txt",
    "FullPath": "c:\\Users\\Federico\\Documents\\renamed.txt"
  }
}

IO Exception:

{
  "EventType": "[Created] tmpFC2D.tmp",
  "Environment": {
    "UserName": "Federico",
    "MachineName": "HP",
    "DomainName": "HP",
    "Culture": "en-US"
  },
  "StartDate": "2017-11-26T23:01:03.7363727-06:00",
  "EndDate": "2017-11-26T23:01:03.7363727-06:00",
  "Duration": 0,
  "FileSystemEvent": {
    "Object": "File",
    "Event": "Create",
    "Errors": [
      "IOException when getting file attributes: Could not find file 'c:\\Users\\Federico\\AppData\\Local\\Temp\\tmpFC2D.tmp'."
    ],
    "Name": "tmpFC2D.tmp",
    "Extension": ".tmp",
    "FullPath": "c:\\Users\\Federico\\AppData\\Local\\Temp\\tmpFC2D.tmp"
  }
}