ByteGuard.FileValidator 1.1.1

ByteGuard File Validator

ByteGuard.FileValidator is a lightweight security-focused library for validating user-supplied files in .NET applications.
It helps you enforce consistent file upload rules by checking:

• Allowed file extensions
• File size limits
• File signatures (magic numbers) to detect spoofed types
• Specification conformance for Office Open XML / Open Document Formats (.docx, .xlsx, .pptx, .odt)
• Malware scan result using a varity of scanners (requires the addition of a specific ByteGuard.FileValidator scanner package)

⚠️ Important: This package is one layer in a defense-in-depth strategy.
It does not replace endpoint protection, sandboxing, input validation, or other security controls.

Features

• ✅ Validate files by extension
• ✅ Validate files by size
• ✅ Validate files by signature (magic-numbers)
• ✅ Validate files by specification conformance for archive-based formats (Open XML and Open Document Formats)
• ✅ Ensure no malware through a variety of antimalware scanners
• ✅ Validate using file path, Stream, or byte[]
• ✅ Configure which file types to support
• ✅ Configure whether to throw exceptions or simply return a boolean
• ✅ Fluent configuration API for easy setup

Getting Started

Installation

This package is published and installed via NuGet.

Reference the package in your project:

dotnet add package ByteGuard.FileValidator

Antimalware scanners

In order to use the antimalware scanning capabilities, ensure you have a ByteGuard.FileValidator antimalware package referenced as well. Youo can find the relevant scanner package on NuGet under the namespace ByteGuard.FileValidator.Scanners.

Usage

Basic validation

// Without antimalware scanner
var configuration = new FileValidatorConfiguration
{
  SupportedFileTypes = [FileExtensions.Pdf, FileExtensions.Jpg, FileExtensions.Png],
  FileSizeLimit = ByteSize.MegaBytes(25),
  ThrowExceptionOnInvalidFile = false
};

var fileValidator = new FileValidator(configuration);
var isValid = fileValidator.IsValidFile("example.pdf", fileStream);

// With antimalware
var antimalwareScanner = AntimalwareScannerImplementation();
var fileValidator = new FileValidator(configuration, antimalwareScanner);
var isValid = fileValidator.IsValidFile("example.pdf", fileStream);

Using the fluent builder

var configuration = new FileValidatorConfigurationBuilder()
  .AllowFileTypes(FileExtensions.Pdf, FileExtensions.Jpg, FileExtensions.Png)
  .SetFileSizeLimit(ByteSize.MegaBytes(25))
  .SetThrowExceptionOnInvalidFile(false)
  .Build();

var fileValidator = new FileValidator(configuration);
var isValid = fileValidator.IsValidFile("example.pdf", fileStream);

Validating specific aspects

The FileValidator class provides methods to validate specific aspects of a file.

⚠️ It’s recommended to use IsValidFile for comprehensive validation.

IsValidFile performs, in order:

1. Extension validation
2. File size validation
3. Signature (magic-number) validation
4. Optional Open XML / Open Document Format specification conformance validation (for supported types)
5. Optional antimalware scanning with a compatible scanning package

bool isExtensionValid = fileValidator.IsValidFileType(fileName);
bool isFileSizeValid = fileValidator.HasValidSize(fileStream);
bool isSignatureValid = fileValidator.HasValidSignature(fileName, fileStream);
bool isOpenXmlValid = fileValidator.IsValidOpenXmlDocument(fileName, fileStream);
bool isOpenDocumentFormatValid = fileValidator.IsValidOpenDocumentFormat(fileName, fileStream);
bool isMalwareClean = fileValidator.IsMalwareClean(fileName, fileStream);

Example

[HttpPost("upload")]
public async Task<IActionResult> Upload(IFormFile file)
{
    using var stream = file.OpenReadStream();

    var antimalwareScanner = AntimalwareScannerImplementation();

    var configuration = new FileValidatorConfiguration
    {
        SupportedFileTypes = [FileExtensions.Pdf, FileExtensions.Docx],
        FileSizeLimit = ByteSize.MegaBytes(10),
        ThrowExceptionOnInvalidFile = false
    };

    var validator = new FileValidator(configuration, antimalwareScanner);

    if (!validator.IsValidFile(file.FileName, stream))
    {
        return BadRequest("Invalid or unsupported file.");
    }

    // Proceed with processing/saving...
    
    return Ok();
}

Supported File Extensions

The following file extensions are supported by the FileValidator:

• .jpeg, .jpg
• .pdf
• .png
• .bmp
• .doc
• .docx
• .odt
• .rtf
• .xls
• .xlsx
• .pptx
• .m4a
• .mov
• .avi
• .mp3
• .mp4
• .wav

Validation coverage per type

IsValidFile always validates:

• File extension (against SupportedFileTypes)
• File size (against FileSizeLimit)
• File signature (magic number)
• Malware scan result (if an antimalware scanner has been configured)

For some formats, additional checks are performed:

• Office Open XML / Open Document Format (.docx, .xlsx, .pptx, .odt):

  • Extension
  • File size
  • Signature
  • Specification conformance
  • Malware scan result

• Other binary formats (e.g. images, audio, video such as .jpg, .png, .mp3, .mp4):

  • Extension
  • File size
  • Signature
  • Malware scan result

Configuration Options

The FileValidatorConfiguration supports:

Exceptions

When ThrowExceptionOnInvalidFile is set to true, validation functions will throw one of the appropriate exceptions defined below. However, when ThrowExceptionOnInvalidFile is set to false, all validation functions will either return true or false.

When to use this package

• ✅ Whenever you need consistent file validation rules across projects
• ✅ When handling user uploads in APIs or web applications
• ✅ When you want defense-in-depth against spoofed or malicious files

License

ByteGuard FileValidator is Copyright © ByteGuard Contributors - Provided under the MIT license.