GIPL.FileSecurity 1.0.8

GIPL.FileSecurity

GIPL.FileSecurity is a .NET library for secure file-upload validation. It validates uploaded files using extension, filename, MIME type, file signatures (magic bytes), file structure, size limits, and stream-based inspection.

The library is designed to help prevent common file-upload security issues such as extension spoofing, MIME-type mismatches, invalid file structures, and unsafe filenames.

Features

• File extension validation
• File name validation
• MIME type validation
• File signature / magic-byte validation
• PDF validation
• DOC / DOCX validation
• XLS / XLSX validation
• PPT / PPTX validation
• Image validation
• ZIP-based document validation
• File size validation
• Stream-based validation
• Safe file name generation
• Validation result with error code and message
• No requirement to save the uploaded file to disk before validation

Supported Frameworks

The package supports:

.NET Framework

• .NET Framework 4.6.1 and above

.NET

• .NET 5.0 and above

Installation

Install the NuGet package using Package Manager Console:

Install-Package GIPL.FileSecurity

Or using the .NET CLI:

dotnet add package GIPL.FileSecurity

Required Parameters

The main validation method requires the following parameters:

fileStream
fileName
fileSize
MaxFileSize
AllowedExtensions
FileNamePattern

Parameter Description

The validation method is:

FileSecurityValidator.Validate(
    fileStream,
    fileName,
    fileSize,
    MaxFileSize,
    AllowedExtensions,
    FileNamePattern);

Allowed Extensions

Example allowed extensions:

string[] allowedExtensions =
{
    ".pdf",
    ".doc",
    ".docx",
    ".odt",
    ".rtf",
    ".txt",

    ".xls",
    ".xlsx",
    ".ods",
    ".csv",

    ".ppt",
    ".pptx",
    ".odp",

    ".jpg",
    ".jpeg",
    ".png",
    ".gif",
    ".bmp",
    ".tiff",

    ".zip",
    ".rar"
};

Extensions should be provided with the leading . character.

File Name Pattern

Recommended filename validation pattern:

string fileNamePattern =
    @"^[A-Za-z0-9][A-Za-z0-9 _-]*\.[A-Za-z0-9]+$";

This pattern allows filenames such as:

document.pdf
My Document.pdf
invoice_2026.pdf
report-01.xlsx
photo_01.jpg

It rejects filenames containing unsupported characters such as:

../../file.pdf
<script>.pdf
file|name.pdf
file:name.pdf

.NET Framework Example

The following example can be used with .NET Framework 4.6.1 and above, including ASP.NET applications using HttpPostedFile.

using System;
using GIPL.FileSecurity;

string[] allowedExtensions =
{
    ".pdf",
    ".doc",
    ".docx",
    ".odt",
    ".rtf",
    ".txt",

    ".xls",
    ".xlsx",
    ".ods",
    ".csv",

    ".ppt",
    ".pptx",
    ".odp",

    ".jpg",
    ".jpeg",
    ".png",
    ".gif",
    ".bmp",
    ".tiff",

    ".zip",
    ".rar"
};

string fileNamePattern =
    @"^[A-Za-z0-9][A-Za-z0-9 _-]*\.[A-Za-z0-9]+$";

FileValidationResult result = FileSecurityValidator.Validate(
    FileUpload.PostedFile.InputStream,
    FileUpload.FileName,
    FileUpload.PostedFile.ContentLength,
    5,
    allowedExtensions,
    fileNamePattern);

if (!result.IsValid)
{
    string msg = result.Message;
    string errorCode = result.ErrorCode;
    string name = result.FileName;

    return;
}

In this example:

Maximum file size = 5 MB

The uploaded file is validated directly from:

FileUpload.PostedFile.InputStream

The file does not need to be saved to disk before validation.

Create a Safe File Name

After successful validation, generate a safe filename using:

string newFileName =
    FileSecurityValidator.GenerateSafeFileName(result.FileName);

Example:

if (result.IsValid)
{
    string newFileName =
        FileSecurityValidator.GenerateSafeFileName(result.FileName);

    // Use newFileName when storing the uploaded file.
}

It is recommended to use the generated safe filename instead of trusting the original client-provided filename for storage.

ASP.NET Core / .NET Example

The following example can be used with .NET 5.0 and above and IFormFile.

using System.IO;
using GIPL.FileSecurity;

string[] allowedExtensions =
{
    ".pdf",
    ".doc",
    ".docx",
    ".odt",
    ".rtf",
    ".txt",

    ".xls",
    ".xlsx",
    ".ods",
    ".csv",

    ".ppt",
    ".pptx",
    ".odp",

    ".jpg",
    ".jpeg",
    ".png",
    ".gif",
    ".bmp",
    ".tiff",

    ".zip",
    ".rar"
};

string fileNamePattern =
    @"^[A-Za-z0-9][A-Za-z0-9 _-]*\.[A-Za-z0-9]+$";

FileValidationResult result;

using (Stream stream = model.File.OpenReadStream())
{
    result = FileSecurityValidator.Validate(
        stream,
        model.File.FileName,
        model.File.Length,
        5,
        allowedExtensions,
        fileNamePattern);
}

if (!result.IsValid)
{
    string msg = result.Message;
    string errorCode = result.ErrorCode;
    string name = result.FileName;

    return;
}

The maximum allowed file size in this example is:

5 MB

ASP.NET Core Safe File Name

After successful validation:

string newFileName =
    FileSecurityValidator.GenerateSafeFileName(result.FileName);

Example:

if (result.IsValid)
{
    string newFileName =
        FileSecurityValidator.GenerateSafeFileName(result.FileName);

    // Save the file using newFileName.
}

Complete ASP.NET Core Example

using System.IO;
using GIPL.FileSecurity;

public IActionResult Upload(IFormFile file)
{
    string[] allowedExtensions =
    {
        ".pdf",
        ".doc",
        ".docx",
        ".odt",
        ".rtf",
        ".txt",

        ".xls",
        ".xlsx",
        ".ods",
        ".csv",

        ".ppt",
        ".pptx",
        ".odp",

        ".jpg",
        ".jpeg",
        ".png",
        ".gif",
        ".bmp",
        ".tiff",

        ".zip",
        ".rar"
    };

    string fileNamePattern =
        @"^[A-Za-z0-9][A-Za-z0-9 _-]*\.[A-Za-z0-9]+$";

    FileValidationResult result;

    using (Stream stream = file.OpenReadStream())
    {
        result = FileSecurityValidator.Validate(
            stream,
            file.FileName,
            file.Length,
            5,
            allowedExtensions,
            fileNamePattern);
    }

    if (!result.IsValid)
    {
        string message = result.Message;
        string errorCode = result.ErrorCode;
        string fileName = result.FileName;

        return BadRequest(new
        {
            IsValid = false,
            Message = message,
            ErrorCode = errorCode,
            FileName = fileName
        });
    }

    string newFileName =
        FileSecurityValidator.GenerateSafeFileName(result.FileName);

    return Ok(new
    {
        IsValid = true,
        OriginalFileName = result.FileName,
        SafeFileName = newFileName
    });
}

Validation Flow

The recommended upload flow is:

User selects file
       ↓
Open uploaded file stream
       ↓
File size validation
       ↓
File name validation
       ↓
Extension validation
       ↓
MIME type validation
       ↓
File signature / magic-byte validation
       ↓
File-content validation
       ↓
PDF / Office / Image validation
       ↓
Validation successful
       ↓
Generate safe file name
       ↓
Store the file

If any validation step fails, the upload should be rejected.

FileValidationResult

The validation method returns:

FileValidationResult

Example:

FileValidationResult result =
    FileSecurityValidator.Validate(
        fileStream,
        fileName,
        fileSize,
        maxFileSize,
        allowedExtensions,
        fileNamePattern);

You can check the validation status:

if (!result.IsValid)
{
    // File validation failed.
}

Available result information can be used as:

string message = result.Message;
string errorCode = result.ErrorCode;
string fileName = result.FileName;

Example:

if (!result.IsValid)
{
    string msg = result.Message;
    string errorCode = result.ErrorCode;
    string name = result.FileName;

    // Reject upload.
    return;
}

Maximum File Size

The MaxFileSize parameter is specified in MB.

For example:

5

means:

Maximum file size = 5 MB

Example:

FileSecurityValidator.Validate(
    fileStream,
    fileName,
    fileSize,
    5,
    allowedExtensions,
    fileNamePattern);

For a 10 MB limit:

FileSecurityValidator.Validate(
    fileStream,
    fileName,
    fileSize,
    10,
    allowedExtensions,
    fileNamePattern);

Stream-Based Validation

The library is designed to validate uploaded files directly from a stream.

.NET Framework

FileUpload.PostedFile.InputStream

ASP.NET Core

model.File.OpenReadStream()

This allows validation before the uploaded content is stored permanently.

Security Recommendation

Do not rely only on the file extension or MIME type supplied by the client.

For secure file uploads, validate multiple properties:

1. File size
2. Filename
3. Extension
4. MIME type
5. File signature / magic bytes
6. Actual file structure
7. Format-specific content
8. Malware scanning where required
9. Generate a safe server-side filename
10. Store uploaded files using controlled server-side paths

Client-provided values such as:

FileName
Content-Type
Extension

should not be treated as proof of the actual file type.

Basic Usage Summary

.NET Framework

FileValidationResult result = FileSecurityValidator.Validate(
    FileUpload.PostedFile.InputStream,
    FileUpload.FileName,
    FileUpload.PostedFile.ContentLength,
    5,
    allowedExtensions,
    fileNamePattern);

if (!result.IsValid)
{
    string msg = result.Message;
    string errorCode = result.ErrorCode;
    string name = result.FileName;

    return;
}

string newFileName =
    FileSecurityValidator.GenerateSafeFileName(result.FileName);

.NET Core / .NET 5+

FileValidationResult result;

using (Stream stream = model.File.OpenReadStream())
{
    result = FileSecurityValidator.Validate(
        stream,
        model.File.FileName,
        model.File.Length,
        5,
        allowedExtensions,
        fileNamePattern);
}

if (!result.IsValid)
{
    string msg = result.Message;
    string errorCode = result.ErrorCode;
    string name = result.FileName;

    return;
}

string newFileName =
    FileSecurityValidator.GenerateSafeFileName(result.FileName);

License

Copyright © GIPL.

Use of this package is subject to the license terms distributed with the package.