GIPL.FileSecurity 1.1.4

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

• Password-protected files are not supported.

• JavaScript-based files are not supported.

• Macro-enabled Office files are not supported.

---

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

| Parameter | Description |

|---|---|

| `fileStream` | Stream containing the uploaded file |

| `fileName` | Original uploaded file name |

| `fileSize` | Uploaded file size in bytes |

| `MaxFileSize` | Maximum allowed file size in MB/KB |

| `AllowedExtensions` | Array of permitted file extensions |

| `FileNamePattern` | Regular expression used to validate the filename |

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"

};

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"

};

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 / 0.5m 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"

};

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 / 0.5m 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. You can use whole-number or fractional values.

Case 1: Maximum File Size in MB

For example:

| `MaxFileSize` | Maximum File Size |

|---:|---:|

| `1` | 1 MB |

| `2` | 2 MB |

| `3` | 3 MB |

| `5` | 5 MB |

| `10` | 10 MB |

Example — 5 MB limit:

Example:

FileSecurityValidator.Validate(

    fileStream,

    fileName,

    fileSize,

    5, // Maximum file size in 5 MB

    allowedExtensions,

    fileNamePattern);

Case 2: Maximum File Size Using Fractional KB Values

Fractional values let you set limits smaller than 500 KB.

| `MaxFileSize` | Maximum File Size |

|---:|---:|

| `0.5m` | 512 KB |

| `0.1m` | 102.4 KB |

| `0.25m` | 256 KB |

| `0.75m` | 768 KB |

Example — 0.5m MB (512 KB) limit:

FileSecurityValidator.Validate(

    fileStream,

    fileName,

    fileSize,

    0.5m, // Maximum file size: 0.5m MB (512 KB)

    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.