Merge pull request #2 from SytxLabs/add-audio-and-video-support

Add VideoSanitizer and AudioSanitizer for metadata cleanup and embedded payload detection

Author: shaunluedeke

README.md

@@ -2,26 +2,29 @@
 
 [![MIT Licensed](https://img.shields.io/badge/License-MIT-brightgreen.svg?style=flat-square)](LICENSE)
 [![Check code style](https://github.com/SytxLabs/FileSanitizer/actions/workflows/code-style.yml/badge.svg?style=flat-square)](https://github.com/SytxLabs/FileSanitizer/actions/workflows/code-style.yml)
-[![Tests](https://github.com/SytxLabs/FileSanitizer/actions/workflows/tests.yml/badge.svg?style=flat-square)](https://github.com/SytxLabs/FileSanitizer/actions/workflows/code-style.yml)
+[![Tests](https://github.com/SytxLabs/FileSanitizer/actions/workflows/tests.yml/badge.svg?style=flat-square)](https://github.com/SytxLabs/FileSanitizer/actions/workflows/tests.yml)
 [![Latest Version on Packagist](https://poser.pugx.org/sytxlabs/filesanitizer/v/stable?format=flat-square)](https://packagist.org/packages/sytxlabs/filesanitizer)
 [![Total Downloads](https://poser.pugx.org/sytxlabs/filesanitizer/downloads?format=flat-square)](https://packagist.org/packages/sytxlabs/filesanitizer)
 
-
-Pure PHP file sanitizer and scanner for uploaded files. It strips metadata where practical, rewrites selected file types into safer forms, and blocks files that look malicious.
+Pure PHP file sanitizer and scanner for uploaded files. It strips metadata where practical, rewrites selected file types into safer forms, and detects suspicious or malicious content such as XSS-style payloads, risky embedded markup, active PDF content, and dangerous archive entries.
 
 ## Features
 
-- Re-encodes JPEG, PNG, GIF, and WebP images to strip EXIF and ancillary metadata
-- Scans HTML, SVG, PDF, text, Office OOXML, ZIP, and nested ZIP content for risky payloads
-- Recursively scans ZIP archives with depth, entry-count, and expanded-size guards
-- Detects common XSS-style payloads such as `<script>`, inline handlers, `javascript:` URLs, hostile CSS, and dangerous PDF actions
-- Applies strict allowlist-based cleanup for HTML and strict removal rules for SVG
+- Re-encodes supported image formats to remove metadata and ancillary chunks
+- Sanitizes HTML and SVG using strict policy-based cleanup
+- Scans PDFs for active content and applies best-effort cleanup 
+- Scans OOXML documents for risky content such as macros, ActiveX, and external relationships 
+- Recursively scans ZIP archives, including nested archives, with configurable safety limits
+- Scans audio files for suspicious embedded payloads and removes metadata where practical
+- Scans video files for suspicious embedded payloads and applies best-effort metadata cleanup
+- Supports sanitize-always mode for best-effort cleaning even when risky content is detected
+- Pure PHP implementation with no shell access, SSH, or external binaries required
 
-## Install
+## Installation
 
 ```bash
 composer require sytxlabs/filesanitizer
-```
+````
 
 For development and tests:
 
@@ -30,9 +33,7 @@ composer install
 composer test
 ```
 
-PHPUnit is added as a dev dependency
-
-## Usage
+## Quick start
 
 ```php
 <?php
@@ -42,53 +43,194 @@ require __DIR__ . '/vendor/autoload.php';
 use SytxLabs\FileSanitizer\FileSanitizer;
 
 $sanitizer = new FileSanitizer();
+
 $result = $sanitizer->process(__DIR__ . '/upload.svg');
 
 if (!$result['scan']->safe) {
     foreach ($result['scan']->issues as $issue) {
         echo $issue->code . ': ' . $issue->message . PHP_EOL;
     }
+
     exit(1);
 }
 
 echo 'Sanitized file written to: ' . $result['sanitize']->outputPath . PHP_EOL;
 ```
 
-## Archive scanning notes
+## sanitizeAlways mode
 
-The recursive archive scanner uses PHP's `ZipArchive` extension and does not extract archives to a shell. PHP documents `ZipArchive` for reading archive entries and notes extraction and open behavior through the zip extension API.
+When `sanitizeAlways` is enabled, FileSanitizer will attempt best-effort sanitization even if risky content is detected during scanning.
+
+This is useful when you want to:
+
+* always strip metadata where possible
+* always rewrite supported files where possible
+* keep findings for review without immediately rejecting the upload
+
+```php
+<?php
+
+use SytxLabs\FileSanitizer\FileSanitizer;
+
+$sanitizer = new FileSanitizer();
+
+$result = $sanitizer->process(__DIR__ . '/upload.pdf', null, true);
+```
+
+Best-effort sanitization does not guarantee a full structural rebuild for complex formats such as PDF, audio, or video containers.
+
+## Supported file types
+
+FileSanitizer currently supports scanning and/or sanitizing the following file types.
+
+* Images
+  * JPEG
+  * PNG
+  * GIF
+  * WebP
+* Documents and markup
+  * HTML
+  * SVG
+  * PDF
+  * TXT and text-like files
+  * DOCX
+  * XLSX
+  * PPTX
+* Archives
+  * ZIP
+  * Nested ZIP archives
+* Audio
+  * MP3
+  * WAV
+  * OGG
+  * FLAC
+  * M4A
+  * AAC
+* Video
+  * MP4
+  * MOV
+  * WebM
+  * MKV
+  * AVI
+
+## How it works
+
+FileSanitizer combines format-aware scanning with best-effort sanitization.
+
+### Scanning
+
+The scanner looks for suspicious patterns and risky structures such as:
+
+* inline JavaScript-style payloads
+* dangerous HTML or SVG constructs
+* active PDF actions
+* suspicious archive paths and nested archive abuse
+* risky embedded strings in audio and video containers
+* macros, ActiveX, and external relationships in OOXML files
+
+### Sanitizing
+
+Supported sanitizers attempt to reduce risk by:
+
+* re-encoding images
+* removing unsafe HTML and SVG elements and attributes
+* stripping metadata where practical
+* rewriting selected file formats into safer forms
+* applying best-effort cleanup to complex containers
+
+## Archive scanning
+
+ZIP scanning is recursive and designed to detect suspicious content without using shell extraction.
 
 Current guards:
 
-- Maximum nesting depth: 3
-- Maximum scanned entries per archive: 1000
-- Maximum expanded bytes scanned: 25 MB
-- Flags suspicious paths such as `../evil.txt` or absolute-path entries
+* maximum nesting depth: 3
+* maximum scanned entries per archive: 1000
+* maximum expanded bytes scanned: 25 MB
+* suspicious path detection for entries such as `../evil.txt` or absolute paths
 
 ## HTML and SVG policy
 
-HTML cleanup uses PHP's DOM support to parse and rewrite content, removing disallowed tags and risky attributes instead of relying on `strip_tags()`, which PHP user notes caution is not enough for safe attribute handling. PHP's DOM APIs support HTML parsing and tree editing.
+HTML and SVG sanitization is policy-based and removes risky constructs instead of relying on simple tag stripping.
 
 Highlights:
 
-- Removes `script`, `iframe`, `object`, `embed`, `form`, and other non-allowlisted elements
-- Removes all `on*` event handlers
-- Removes `javascript:`, `vbscript:`, `file:`, and unsafe `data:` URLs
-- Drops hostile CSS such as `expression()`, `@import`, `url()`, `behavior:`, and `-moz-binding`
-- Removes SVG active content elements such as `script`, `foreignObject`, animation elements, external media, `image`, and `use`
+* removes `script`, `iframe`, `object`, `embed`, `form`, and other disallowed elements
+* removes all `on*` event handlers
+* removes `javascript:`, `vbscript:`, `file:`, and unsafe `data:` URLs
+* removes hostile CSS such as `expression()`, `@import`, `url()`, `behavior:`, and `-moz-binding`
+* removes SVG active content such as `script`, `foreignObject`, animation elements, external media, `image`, and `use`
+
+## Audio support
+
+FileSanitizer includes best-effort support for common audio formats.
 
-## Tests
+### What it does
+
+* Detects suspicious embedded payloads such as:
+
+    * `<script`
+    * `javascript:`
+    * inline event handler patterns like `onclick=`
+    * `<iframe`
+    * `data:text/html`
+    * embedded PHP tags
+
+* Removes metadata where practical:
+
+    * MP3: ID3v1 and ID3v2 tags
+    * WAV: selected metadata chunks such as `LIST`, `INFO`, and `ID3`
+    * OGG, FLAC, M4A, and AAC: conservative best-effort textual payload cleanup
+
+### Notes
+
+Audio sanitization is best-effort and does not transcode or fully rebuild complex media containers. No shell tools, SSH access, or external binaries are required.
+
+## Video support
+
+FileSanitizer includes best-effort support for common video containers.
+
+### What it does
+
+* Detects suspicious embedded payloads such as:
+
+    * `<script`
+    * `javascript:`
+    * inline event handler patterns like `onload=`
+    * `<iframe`
+    * `data:text/html`
+    * embedded PHP tags
+
+* Applies conservative container cleanup where practical:
+
+    * MP4 and MOV: attempts to remove selected metadata atoms such as `udta`, `meta`, and `ilst`
+    * AVI: removes selected metadata chunks such as `INFO`, `JUNK`, and `IDIT`
+    * WebM and MKV: applies conservative best-effort textual payload cleanup
+
+### Notes
+
+Video sanitization is best-effort and does not transcode or fully rebuild media containers. Without external tools such as FFmpeg, full structural video rewriting is intentionally out of scope.
+
+## Test coverage
 
 Included PHPUnit coverage exercises:
 
-- nested ZIP detection
-- path traversal detection inside ZIPs
-- HTML sanitization rules
-- SVG sanitization rules
-- PDF action detection
+* nested ZIP detection
+* path traversal detection inside ZIPs
+* HTML sanitization rules
+* SVG sanitization rules
+* PDF action detection
+* audio metadata stripping
+* video file scanning for embedded payloads and metadata stripping
 
 ## Limitations
 
-- PDF cleanup is still best-effort rather than a full structural rewrite
-- OOXML files are scanned for risky content and external references but not fully rewritten yet
-- This package is a sanitizer and heuristic scanner, not a substitute for sandboxing or AV scanning
+FileSanitizer is a pure PHP package focused on safe, practical, best-effort sanitization.
+
+### Important limitations
+
+* PDF sanitization is a best-effort and not a full PDF rebuild
+* OOXML files are scanned for risky content but are not fully rewritten
+* audio sanitization removes metadata where practical but does not transcode files
+* video sanitization is best-effort and does not perform full re-encoding or container rebuilding
+* complex media formats may still require deeper inspection in high-security environments

composer.json

@@ -3,7 +3,6 @@
   "description": "A PHP library to sanitize file names and content to prevent security vulnerabilities.",
   "type": "library",
   "license": "MIT",
-  "version": "1.0.2",
   "keywords": ["file sanitization", "security", "PHP library"],
   "authors": [
     {

examples/web.php

@@ -18,7 +18,7 @@
 
 $sanitizer = new FileSanitizer();
 $outputPath = $file . '.sanitized.' . pathinfo($file, PATHINFO_EXTENSION);
-$result = $sanitizer->process($file, $outputPath);
+$result = $sanitizer->process($file, $outputPath, true);
 
 echo '<pre>';
 print_r($result);

src/FileSanitizer.php

@@ -9,11 +9,13 @@
 use SytxLabs\FileSanitizer\Dto\SanitizeReport;
 use SytxLabs\FileSanitizer\Dto\ScanReport;
 use SytxLabs\FileSanitizer\Enums\IssueSeverity;
+use SytxLabs\FileSanitizer\Sanitizer\AudioSanitizer;
 use SytxLabs\FileSanitizer\Sanitizer\HtmlSanitizer;
 use SytxLabs\FileSanitizer\Sanitizer\ImageSanitizer;
 use SytxLabs\FileSanitizer\Sanitizer\PdfSanitizer;
 use SytxLabs\FileSanitizer\Sanitizer\SvgSanitizer;
 use SytxLabs\FileSanitizer\Sanitizer\TextLikeSanitizer;
+use SytxLabs\FileSanitizer\Sanitizer\VideoSanitizer;
 use SytxLabs\FileSanitizer\Scanner\PatternScanner;
 use SytxLabs\FileSanitizer\Support\MimeDetector;
 
@@ -24,13 +26,13 @@ final class FileSanitizer
 
     public function __construct(private readonly ?MimeDetector $mimeDetector = null, private readonly ?ScannerInterface $scanner = null, ?array $sanitizers = null)
     {
-        $this->sanitizers = $sanitizers ?? [new SvgSanitizer(), new HtmlSanitizer(), new ImageSanitizer(), new PdfSanitizer(), new TextLikeSanitizer()];
+        $this->sanitizers = $sanitizers ?? [new SvgSanitizer(), new HtmlSanitizer(), new ImageSanitizer(), new PdfSanitizer(), new TextLikeSanitizer(), new AudioSanitizer(), new VideoSanitizer()];
     }
 
     /**
      * @return array{mimeType:string, scan:ScanReport, sanitize:SanitizeReport}
      */
-    public function process(string $inputPath, bool|string|null $outputPath = null, bool $sanitizeAlways = true): array
+    public function process(string $inputPath, bool|string|null $outputPath = null, bool $sanitizeAlways = false): array
     {
         if (is_bool($outputPath)) {
             $sanitizeAlways = $outputPath;
@@ -44,36 +46,40 @@ public function process(string $inputPath, bool|string|null $outputPath = null,
         $mimeType = ($this->mimeDetector ?? new MimeDetector())->detect($inputPath);
         $scan = ($this->scanner ?? new PatternScanner())->scan($inputPath, $mimeType);
         $outputPath ??= $this->defaultOutputPath($inputPath);
-
-        foreach ($this->sanitizers as $sanitizer) {
-            if (!$sanitizer->supports($mimeType, $inputPath)) {
-                continue;
-            }
-            if (!$scan->safe && !$sanitizeAlways) {
-                return ['mimeType' => $mimeType, 'scan' => $scan, 'sanitize' => new SanitizeReport($outputPath, false, $scan->issues, ['skipped' => true])];
-            }
-            $sanitize = $sanitizer->sanitize($inputPath, $outputPath, $sanitizeAlways);
-            if (!$scan->safe) {
-                $sanitize = new SanitizeReport($sanitize->outputPath, $sanitize->metadataRemoved, [...$scan->issues, ...$sanitize->issues], [...$sanitize->context, 'sanitized_despite_scan_issues' => true]);
+        $sanitizer = $this->resolveSanitizer($mimeType, $inputPath);
+        if ($sanitizer === null) {
+            if (!copy($inputPath, $outputPath)) {
+                throw new RuntimeException('Could not copy unsupported file to output path.');
             }
-            return ['mimeType' => $mimeType, 'scan' => $scan, 'sanitize' => $sanitize];
+            $issues = $scan->issues;
+            $issues[] = new Issue('no_sanitizer', 'No specialized sanitizer exists for this file type; original file was copied after scanning.', IssueSeverity::Warning);
+            return ['mimeType' => $mimeType, 'scan' => $scan, 'sanitize' => new SanitizeReport($outputPath, false, $issues, ['copied_original' => true])];
         }
-
-        if (!copy($inputPath, $outputPath)) {
-            throw new RuntimeException('Could not copy unsupported file to output path.');
+        if (!$scan->safe && !$sanitizeAlways) {
+            return ['mimeType' => $mimeType, 'scan' => $scan, 'sanitize' => new SanitizeReport($outputPath, false, $scan->issues, ['skipped' => true])];
         }
-
-        $issues = $scan->issues;
-        $issues[] = new Issue('no_sanitizer', 'No specialized sanitizer exists for this file type; original file was copied after scanning.', IssueSeverity::Warning);
-
-        return ['mimeType' => $mimeType, 'scan' => $scan, 'sanitize' => new SanitizeReport($outputPath, false, $issues, ['copied_original' => true])];
+        $sanitize = $sanitizer->sanitize($inputPath, $outputPath, $sanitizeAlways);
+        if (!$scan->safe) {
+            $sanitize = new SanitizeReport($sanitize->outputPath, $sanitize->metadataRemoved, [...$scan->issues, ...$sanitize->issues], [...$sanitize->context, 'sanitized_despite_scan_issues' => true]);
+        }
+        return ['mimeType' => $mimeType, 'scan' => $scan, 'sanitize' => $sanitize];
     }
 
     public function sanitizeAlways(string $inputPath, ?string $outputPath = null): array
     {
         return $this->process($inputPath, $outputPath, true);
     }
 
+    private function resolveSanitizer(string $mimeType, string $path): ?SanitizerInterface
+    {
+        foreach ($this->sanitizers as $sanitizer) {
+            if ($sanitizer->supports($mimeType, $path)) {
+                return $sanitizer;
+            }
+        }
+        return null;
+    }
+
     private function defaultOutputPath(string $inputPath): string
     {
         $extension = pathinfo($inputPath, PATHINFO_EXTENSION);