Download the PHP package hassan-lateef/guardian without Composer

Guardian

Guardian is a Laravel package for validating uploaded files before you store them.

It is designed to catch common upload abuse cases such as:

• blocked executable extensions like .php, .sh, .exe
• double extensions like avatar.php.png
• MIME spoofing where the file contents do not match the extension
• suspicious payloads embedded inside text files, images, PDFs, or SVGs
• malformed or fake image/PDF/ZIP-based documents
• dangerous SVG elements, attributes, and javascript: links

What Guardian Currently Does

The active scan pipeline in the package is:

1. ExtensionScanner
2. MimeScanner
3. ContentScanner
4. SvgScanner
5. StructuralScanner

Guardian fails fast. The first scanner that rejects the file stops the pipeline.

Installation

Publish the config:

Usage

Middleware

Guardian registers the guardian middleware alias automatically through the package service provider.

The middleware scans every uploaded file in the request, including nested file arrays.

Validation Rule

You can also use the facade helper:

Manual Inspection

If you want a result object instead of an exception:

Multiple Files

Scanner Details

1. Extension Scanner

Checks the original filename and:

• rejects files with no extension
• rejects any extension in guardian.blocked_extensions
• rejects multi-part extensions when guardian.reject_double_extensions is true

Example rejected names:

• shell.php
• avatar.php.png
• backup.tar.php

2. MIME Scanner

Uses PHP fileinfo to detect the file's real MIME type from the file bytes, then verifies:

• the MIME exists in guardian.allowed_mimes
• the uploaded extension matches the configured extensions for that MIME

This catches renamed files whose contents do not match their extension.

3. Content Scanner

Reads up to the first 1 MB of the file and scans based on extension group:

• full: runs all configured dangerous patterns
• light: runs a smaller high-confidence rule set
• skip: does not content-scan the file

Current default groups:

• full: svg, txt, csv, rtf, html, htm, xml
• light: jpg, jpeg, png, gif, webp, bmp, tif, tiff, ico, pdf
• skip: office docs, archives, audio, and video formats listed in config

Examples of patterns checked include:

• PHP opening tags
• eval(), exec(), system(), shell_exec()
• common obfuscation patterns
• web shell signatures
• <script> tags and javascript: payloads
• null byte injection

4. SVG Scanner

Runs only for .svg files when guardian.svg_deep_scan is enabled.

It parses the SVG as XML and rejects configured dangerous elements and attributes.

Default forbidden elements include:

• script
• foreignObject
• feImage
• iframe
• embed
• object
• animate
• animateMotion
• set
• link

Default forbidden attributes include a long list of event handlers such as:

• onclick
• onload
• onerror
• onbegin
• onanimationstart

It also blocks:

• javascript: inside href or xlink:href
• dangerous CSS inside style
• xml:base

Important: the current config intentionally allows some SVG features that older docs often block, such as legitimate <use> references and harmless visual elements, while still blocking dangerous URI and style payloads.

5. Structural Scanner

Performs format-specific validation when guardian.structural_validation is enabled.

Current behavior:

• images: validates parseability with GD, or Imagick if GD is unavailable
• SVG: validates that the file is parseable XML
• PDF: checks for the %PDF- header
• ZIP, DOCX, XLSX: checks for the PK ZIP header

If guardian.re_encode_images is true, supported images are re-encoded through GD to strip embedded payloads and metadata from the temporary uploaded file before you store it.

Structural validation currently applies to:

• jpg, jpeg, png, gif, webp
• svg
• pdf
• zip, docx, xlsx

Other allowed file types still pass through the earlier scanners, but do not currently receive extra structural validation.

Configuration

After publishing the config, you can tune Guardian through config/guardian.php.

Allowed MIME Map

Guardian only accepts MIME types defined in allowed_mimes.

The shipped config includes support for:

• images
• PDF and common office documents
• text files such as txt, csv, rtf
• archives such as zip, rar, 7z, gz, tar
• common audio and video formats

Blocked Extensions

The default blocked list includes executable and server-side formats such as:

• php, phtml, phar
• shell script extensions
• Windows executable/script extensions
• Python, Ruby, Perl, CGI
• Java archive/class formats
• ASP, ASPX, JSP
• .htaccess, .htpasswd

Useful Config Flags

Content Scan Map

Optional Size Limit

The core Guardian class also checks guardian.max_file_size if you define it in your config. The published config does not currently include this key by default, but the runtime supports it.

Example:

Rejections and Responses

Guardian::inspect() throws Hassan\Guardian\Exceptions\MaliciousFileException when a file is rejected.

The exception renders a 422 JSON response automatically:

You can also catch it manually:

Logging

When log_rejections is enabled, Guardian logs rejected uploads with:

• original filename
• file size
• client MIME type
• rejection reason
• scanner class
• request IP
• request URL

ClamAV Status

The repository contains a ClamAvScanner class and related config keys under guardian.clamav.

Current package state:

• the class exists
• config exists
• it is not part of the default Guardian pipeline

That means enabling guardian.clamav.enabled in config alone does not currently add ClamAV scanning to normal Guardian::inspect() or Guardian::check() calls.

If you want to experiment with a custom pipeline, you can override the scanner list:

Requirements

From composer.json, the package currently requires:

• PHP ^8.1
• ext-gd
• ext-libxml
• ext-dom
• ext-fileinfo

Notes

• Guardian validates uploads before storage. It does not replace secure storage, safe file serving, or authorization checks.
• Browser-reported MIME types are not trusted.
• For image re-encoding to happen, GD support for the image format must be available.
• If neither GD nor Imagick is available at runtime, image structural validation is skipped with a warning log.