Audit.FileSystem

April 9, 2025 · View on GitHub

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

NuGet Status NuGet Count

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 globally configured 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.

Field NameTypeDescription
ObjectFileSystemObjectTypeIndicates the object type: File, Directory or Unknown
EventFileSystemEventTypeThe file system event type: Create, change, Rename or Delete
ErrorsstringAny error encountered when processing the file/directory
AttributesstringThe file/directory attributes
NamestringThe file/directory name
OldNamestringIn case of rename, the old file/directory name
ExtensionstringThe file extension including the point
FullPathstringThe full path to the file/directory
LengthlongThe file length in bytes
CreationTimedatetimeThe file/directory creation date and time
LastAccessTimedatetimeThe file/directory last access date and time
LastWriteTimedatetimeThe file/directory last write date and time
ReadOnlybooleanValue indicating if the file is read only
MD5booleanThe MD5 hash of the file
FileContentFileContentThe file contents when included

FileContent

Represents the contents of an audited file.

Field NameTypeDescription
TypeContentTypeThe content type: Text or Binary
Valuestring/byte arrayThe string (text) or byte array (binary) with the file contents

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"
  }
}

ZZZ Projects - Sponsorship

Entity Framework Extensions and Dapper Plus are major sponsors and are proud to contribute to the development of Audit.NET

Combine the power of auditing with the speed of Bulk Operations to get the best of both worlds — audit and performance.

Entity Framework Extensions - Sponsor

Dapper Plus - Sponsor