🛡️ FileTypeChecker

Secure file type validation for .NET applications using magic number detection

✨ Overview

FileTypeChecker is a powerful .NET library that provides reliable file type identification using magic number detection. Unlike traditional filename extension-based validation, this library analyzes the actual file content to determine the true file type, protecting your applications from malicious files and ensuring robust security.

📋 Table of Contents

• 🚀 Quick Start
• 💡 Why Use FileTypeChecker?
• ⚙️ How It Works
• 📦 Installation
• 🔧 Usage Examples
• 📄 Supported File Types
• 🌐 Web Applications
• 🤝 Contributing
• 💖 Support the Project
• 📝 License

🚀 Quick Start

using(varfileStream=File.OpenRead("suspicious-file.exe")){// Check if file type can be identifiedif(FileTypeValidator.IsTypeRecognizable(fileStream)){// Get the actual file typeIFileTypefileType=FileTypeValidator.GetFileType(fileStream);Console.WriteLine($"File type: {fileType.Name} ({fileType.Extension})");// Check specific typeboolisImage=fileStream.IsImage();boolisPdf=fileStream.Is<PortableDocumentFormat>();}}

💡 Why Use FileTypeChecker?

🎯 The Problem

Traditional file validation relies on file extensions, which can be easily manipulated:

• A malicious executable can be renamed to .jpg
• Untrusted files can bypass basic extension checks
• The FileSystemInfo.Extension property only reads the filename

✅ The Solution

FileTypeChecker analyzes the actual file content using magic numbers:

• Reliable: Identifies files by their binary signature, not filename
• Secure: Prevents malicious files from masquerading as safe formats
• Comprehensive: Supports 30+ file types with extensible architecture
• Fast: Minimal performance overhead with efficient binary analysis

⚙️ How It Works

FileTypeChecker uses magic numbers (binary signatures) to identify file types. These are specific byte sequences found at the beginning of files that uniquely identify the format.

🔍 Magic Number Examples

PDF: 25 50 44 46 (%PDF)
PNG: 89 50 4E 47 (‰PNG)
JPEG: FF D8 FF (ÿØÿ)
ZIP: 50 4B 03 04 (PK..)

This method provides reliable identification regardless of file extension, offering better security guarantees than filename-based validation.

📖 Learn more about Magic Numbers on Wikipedia

📦 Installation

Package Manager

Install-Package File.TypeChecker

.NET CLI

dotnet add package File.TypeChecker

PackageReference

<PackageReferenceInclude="File.TypeChecker"Version="4.2.0" />

Requirements: .NET Standard 2.0+

🔧 Usage Examples

Basic File Type Detection

usingFileTypeChecker;using(varfileStream=File.OpenRead("document.pdf")){// Check if file type is recognizableif(FileTypeValidator.IsTypeRecognizable(fileStream)){// Get file type informationIFileTypefileType=FileTypeValidator.GetFileType(fileStream);Console.WriteLine($"Type: {fileType.Name}");Console.WriteLine($"Extension: {fileType.Extension}");}}

Category-Based Validation

using(varfileStream=File.OpenRead("image.jpg")){// Check by categoryboolisImage=fileStream.IsImage();boolisDocument=fileStream.IsDocument();boolisArchive=fileStream.IsArchive();// Check specific typeboolisPng=fileStream.Is<PortableNetworkGraphic>();boolisJpeg=fileStream.Is<JointPhotographicExpertsGroup>();}

File Upload Validation

publicboolValidateUploadedFile(IFormFilefile){using(varstream=file.OpenReadStream()){// Verify file is actually an image (regardless of file extension)if(!stream.IsImage()){thrownewInvalidOperationException("Only image files are allowed");}// Additional validation for specific formatsvarfileType=FileTypeValidator.GetFileType(stream);varallowedTypes=new[]{"PNG","JPEG","BMP"};returnallowedTypes.Contains(fileType.Name);}}

Custom File Type Registration

// Register your own file typepublicclassMyCustomType:FileType{publicoverridestringName=>"My Custom Format";publicoverridestringExtension=>"mycustom";publicoverridestringMimeType=>"application/x-mycustom";publicoverrideboolIsMatch(byte[]signature,Streamstream){returnsignature.Length>=4&&signature[0]==0x4D&&signature[1]==0x59&&signature[2]==0x43&&signature[3]==0x54;}}// Use itFileTypeValidator.RegisterType<MyCustomType>();

📚 More examples available in our Wiki

📄 Supported File Types

FileTypeChecker supports 30+ file formats across multiple categories:

🖼️ Images

• PNG - Portable Network Graphics
• JPEG - Joint Photographic Experts Group
• GIF - Graphics Interchange Format (87a/89a)
• BMP - Bitmap Image File
• TIFF - Tagged Image File Format
• WebP - WebP Image Format
• ICO - Icon File
• PSD - Photoshop Document
• HEIC - High Efficiency Image Container

📄 Documents

• PDF - Portable Document Format
• DOC/DOCX - Microsoft Word Documents
• XLS/XLSX - Microsoft Excel Spreadsheets
• ODT - OpenDocument Text
• ODS - OpenDocument Spreadsheet
• ODP - OpenDocument Presentation
• HTML - HyperText Markup Language
• XML - Extensible Markup Language

🗜️ Archives

• ZIP - ZIP Archive
• RAR - RAR Archive
• 7Z - 7-Zip Archive
• TAR - TAR Archive
• GZIP - GNU Zip
• BZIP2 - BZIP2 Compressed File

🎵 Audio/Video

• MP3 - MPEG Audio Layer 3
• MP4 - MPEG-4 Video
• M4V - iTunes Video
• AVI - Audio Video Interleave
• WAV - Windows Audio

💻 Executables

• EXE - Windows Executable
• ELF - Executable and Linkable Format

➕ Extensible

Add your own custom file types by implementing the IFileType interface.

📋 Complete list available in our Wiki

🌐 Web Applications

For ASP.NET Core applications, check out FileTypeChecker.Web - a companion package with validation attributes for IFormFile:

publicclassUploadModel{[AllowedFileTypes(FileType.Jpeg,FileType.Png)][MaxFileSize(5*1024*1024)]// 5MBpublicIFormFileProfileImage{get;set;}}

Features

• ✅ Pre-built validation attributes
• ✅ Model binding integration
• ✅ Automatic error messages
• ✅ Easy file upload validation

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development

git clone https://github.com/AJMitev/FileTypeChecker.git
cd FileTypeChecker
dotnet restore
dotnet build
dotnet test

💖 Support the Project

If this library helps you, consider supporting its development:

• ⭐ Star the repository and share it with others
• ☕ Buy me a coffee for continued development
• 👥 Become a member for direct access to maintainers

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Credits

• Based on mjolka's Stack Overflow answer: Guessing a file type based on its content
• Inspired by 0xbrock's FileTypeChecker
• Completely rewritten with object-oriented design, fluent API, and extensibility

---

Made with ❤️ by Aleksandar J. Mitev