Merge pull request #10 from ByteGuard-HQ/dev

Release v1.1.0

Author: detilium

Directory.Version.props

@@ -1,5 +1,5 @@
 <Project>
   <PropertyGroup>
-    <VersionPrefix>1.0.1</VersionPrefix>
+    <VersionPrefix>1.1.0</VersionPrefix>
   </PropertyGroup>
 </Project>

README.md

@@ -7,16 +7,18 @@ It helps you enforce consistent file upload rules by checking:
 -   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 library should be part of a **defense-in-depth** strategy.  
-It does not replace antivirus scanning, sandboxing, or other security controls.
+> ⚠️ **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
@@ -25,37 +27,45 @@ It does not replace antivirus scanning, sandboxing, or other security controls.
 ## Getting Started
 
 ### Installation
-This package is published and installed via NuGet.
+This package is published and installed via [NuGet](https://www.nuget.org/packages/ByteGuard.FileValidator).
 
 Reference the package in your project:
 ```bash
 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
 
 ```csharp
+// Without antimalware scanner
 var configuration = new FileValidatorConfiguration
 {
-	SupportedFileTypes = [FileExtensions.Pdf, FileExtensions.Jpg, FileExtensions.Png],
-	FileSizeLimit = ByteSize.MegaBytes(25),
-	ThrowExceptionOnInvalidFile = false
+  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
 
 ```csharp
 var configuration = new FileValidatorConfigurationBuilder()
-	.AllowFileTypes(FileExtensions.Pdf, FileExtensions.Jpg, FileExtensions.Png)
-	.SetFileSizeLimit(ByteSize.MegaBytes(25))
-	.SetThrowExceptionOnInvalidFile(false)
-	.Build();
+  .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);
@@ -72,13 +82,15 @@ The `FileValidator` class provides methods to validate specific aspects of a fil
 > 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
 
 ```csharp
 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
@@ -88,14 +100,16 @@ 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);
+    var validator = new FileValidator(configuration, antimalwareScanner);
 
     if (!validator.IsValidFile(file.FileName, stream))
     {
@@ -132,9 +146,10 @@ The following file extensions are supported by the `FileValidator`:
 
 `IsValidFile` always validates:
 
-- File extension (against `SupportedFileTypes`)
-- File size (against `FileSizeLimit`)
-- File signature (magic number)
+- 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:
 
@@ -143,11 +158,13 @@ For some formats, additional checks are performed:
   - 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
 
@@ -171,6 +188,7 @@ When `ThrowExceptionOnInvalidFile` is set to `true`, validation functions will t
 | `InvalidSignatureException` | Thrown when the file's signature does not match the expected signature for its type. |
 | `InvalidOpenXmlFormatException` | Thrown when the internal structure of an Open XML file is invalid (`.docx`, `.xlsx`, `.pptx`, etc.). |
 | `InvalidOpenDocumentFormatException` | Thrown when the specification conformance of an Open Document Format file is invalid (`.odt`, etc.). |
+| `MalwareDetectedException` | Thrown when the configured antimalware scanner detected malware in the file from a scan result. |
 
 ## When to use this package
 

assets/icon.png

@@ -1,14 +1,15 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
     <PropertyGroup>
-        <TargetFrameworks>netstandard2.0;net48;net8.0;net9.0;net10.0</TargetFrameworks>
+        <TargetFrameworks>netstandard2.0;net8.0;net9.0;net10.0</TargetFrameworks>
         <Authors>ByteGuard Contributors, detilium</Authors>
         <Description>ByteGuard File Validator is a security-focused .NET library for validating user-supplied files, providing a configurable API to help you enforce safe and consistent file handling across your applications.</Description>
         <PackageProjectUrl>https://github.com/ByteGuard-HQ/byteguard-file-validator-net</PackageProjectUrl>
         <RepositoryUrl>https://github.com/ByteGuard-HQ/byteguard-file-validator-net</RepositoryUrl>
         <RepositoryType>git</RepositoryType>
         <PackageTags>byteguard file-validator file-validation file-upload upload-validation security application-security appsec</PackageTags>
         <PackageReadmeFile>README.md</PackageReadmeFile>
+        <PackageIcon>icon.png</PackageIcon>
         <Copyright>Copyright © ByteGuard Contributors</Copyright>
         <PackageLicenseExpression>MIT</PackageLicenseExpression>
     </PropertyGroup>
@@ -19,6 +20,7 @@
 
     <ItemGroup>
         <None Include="..\..\README.md" Pack="true" PackagePath="\" />
+        <None Include="..\..\assets\icon.png" Pack="true" PackagePath="\" />
     </ItemGroup>
 
     <ItemGroup>

src/ByteGuard.FileValidator/ByteGuard.FileValidator.csproj

@@ -1,5 +1,4 @@
-using System;
-using System.Globalization;
+using System.Globalization;
 
 namespace ByteGuard.FileValidator
 {

src/ByteGuard.FileValidator/ByteSize.cs

@@ -1,6 +1,4 @@
-using System;
-using System.Linq;
-using ByteGuard.FileValidator.Exceptions;
+using ByteGuard.FileValidator.Exceptions;
 
 namespace ByteGuard.FileValidator.Configuration
 {
@@ -49,4 +47,4 @@ public static void ThrowIfInvalid(FileValidatorConfiguration configuration)
             }
         }
     }
-}
+}

src/ByteGuard.FileValidator/Configuration/ConfigurationValidator.cs

@@ -1,5 +1,4 @@
-using System.Collections.Generic;
-using ByteGuard.FileValidator.Exceptions;
+using ByteGuard.FileValidator.Scanners;
 
 namespace ByteGuard.FileValidator.Configuration
 {
@@ -26,34 +25,9 @@ public class FileValidatorConfiguration
         /// </remarks>
         public long FileSizeLimit { get; set; } = -1;
 
-        /// <summary>
-        /// Maximum file size limit in string representation (e.g. "25MB", "2 GB", etc.).
-        /// </summary>
-        /// <remarks>
-        /// Defines the file size limit of files. See <see cref="ByteSize"/> for conversion help.
-        /// Will be ignored if <see cref="FileSizeLimit"/> is defined.
-        /// Spacing (<c>"25 MB"</c> vs. <c>"25MB"</c>) is irrelevant.
-        /// <para>Supported string representation are:
-        /// <ul>
-        /// <li><c>B</c>: Bytes</li>
-        /// <li><c>KB</c>: Kilobytes</li>
-        /// <li><c>MB</c>: Megabytes</li>
-        /// <li><c>GB</c>: Gigabytes</li>
-        /// </ul>
-        /// </para>
-        /// </remarks>
-        public string FriendlyFileSizeLimit { get; set; }
-
         /// <summary>
         /// Whether to throw an exception if an unsupported/invalid file is encountered. Defaults to <c>true</c>.
         /// </summary>
-        /// <remarks>
-        /// Will throw the following exceptions:
-        /// <ul>
-        ///     <li><see cref="UnsupportedFileException"/> if the given file type is not supported according to the <see cref="SupportedFileTypes"/>.</li>
-        ///     <li><see cref="InvalidSignatureException"/> if the file signature does not match the valid signatures for the given file type.</li>
-        /// </ul>
-        /// </remarks>
         public bool ThrowExceptionOnInvalidFile { get; set; } = true;
     }
-}
+}

src/ByteGuard.FileValidator/Configuration/FileValidatorConfiguration.cs

@@ -1,4 +1,4 @@
-using System.Collections.Generic;
+using ByteGuard.FileValidator.Scanners;
 
 namespace ByteGuard.FileValidator.Configuration
 {
@@ -61,4 +61,4 @@ public FileValidatorConfiguration Build()
             return configuration;
         }
     }
-}
+}

src/ByteGuard.FileValidator/Configuration/FileValidatorConfigurationBuilder.cs

@@ -0,0 +1,46 @@
+namespace ByteGuard.FileValidator.Exceptions
+{
+    /// <summary>
+    /// Exception type used specifically when a an antimalware scanner failed to scane the file.
+    /// </summary>
+    public class AntimalwareScannerException : Exception
+    {
+        /// <summary>
+        /// Default expcetion message for this expection type, if no custom message is provided.
+        /// </summary>
+        private const string defaultMessage = "An error occurred while scanning the file with the antimalware scanner.";
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="AntimalwareScannerException"/> class indicating that an error occured during the scan.
+        /// </summary>
+        public AntimalwareScannerException()
+            : this(defaultMessage)
+        {
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="AntimalwareScannerException"/> class indicating that an error occured during the scan.
+        /// </summary>
+        /// <param name="message">Custom exception message.</param>
+        public AntimalwareScannerException(string message) : base(message)
+        {
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="AntimalwareScannerException"/> class indicating that an error occured during the scan.
+        /// </summary>
+        /// <param name="message">Custom exception message.</param>
+        /// <param name="innerException">Inner exception.</param>
+        public AntimalwareScannerException(string message, Exception innerException) : base(message, innerException)
+        {
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="AntimalwareScannerException"/> class indicating that an error occured during the scan.
+        /// </summary>
+        /// <param name="innerException">Inner exception.</param>
+        public AntimalwareScannerException(Exception innerException) : base(defaultMessage, innerException)
+        {
+        }
+    }
+}

src/ByteGuard.FileValidator/Exceptions/AntimalwareScannerException.cs

@@ -1,23 +1,33 @@
-using System;
-
-namespace ByteGuard.FileValidator.Exceptions
+namespace ByteGuard.FileValidator.Exceptions
 {
     /// <summary>
     /// Exception type used specifically when a given file does not contain any content.
     /// </summary>
     public class EmptyFileException : Exception
     {
+        /// <summary>
+        /// Construct a new <see cref="EmptyFileException"/> to indicate that the provided file does not have any content.
+        /// </summary>
         public EmptyFileException()
             : this("The provided file does not have any content.")
         {
         }
 
+        /// <summary>
+        /// Construct a new <see cref="EmptyFileException"/> to indicate that the provided file does not have any content.
+        /// </summary>
+        /// <param name="message">Custom exception message.</param>
         public EmptyFileException(string message) : base(message)
         {
         }
 
+        /// <summary>
+        /// Construct a new <see cref="EmptyFileException"/> to indicate that the provided file does not have any content.
+        /// </summary>
+        /// <param name="message">Custom exception message.</param>
+        /// <param name="innerException">Inner exception.</param>
         public EmptyFileException(string message, Exception innerException) : base(message, innerException)
         {
         }
     }
-}
+}