Storage Validators
API reference for file upload security validators including Magic Byte inspection, DoS size limits, and extension whitelisting.
This module provides validation controls to protect server integrity during file uploads. It includes file extension checks, file size limit enforcement to defend against Denial of Service (DoS) attacks, and MIME-type verification using binary Magic Bytes.
Base Class
BaseStorageValidator
Base interface protocol defining standard storage validators. All custom validators must inherit from this class and implement __call__.
from fastapi import UploadFile
from zcore.storage import BaseStorageValidator
class BaseStorageValidator:
def __call__(self, file: UploadFile) -> None:
raise NotImplementedErrorValidators are callables. When invoked, they inspect the UploadFile instance and raise a ValidationError with descriptive metadata if validation fails.
Built-in Security Validators
FileExtensionValidator
Enforces extension whitelist checks on incoming file names.
from zcore.storage import FileExtensionValidator
validator = FileExtensionValidator(
allowed_extensions=[".png", ".jpg", ".pdf"],
message="Custom invalid extension message"
)Prop
Type
MaxFileSizeValidator
Enforces file size thresholds to prevent Denial of Service (DoS) and disk space exhaustion.
from zcore.storage import MaxFileSizeValidator
validator = MaxFileSizeValidator(
max_size_mb=10.0,
message="File size exceeds limit"
)Prop
Type
Chunked Stream Support: If the Starlette file.size attribute is unavailable, MaxFileSizeValidator safely seeks to the end of the byte stream (file.file.seek(0, 2)), measures the stream position (tell()), and rewinds to the beginning (seek(0)) without buffering payloads into RAM.
SafeMimeTypeValidator
MIME-type validator utilizing binary Magic Byte verification. Reads the first 8192 header bytes of the file to verify that the file's raw binary signature matches its declared format.
from zcore.storage import SafeMimeTypeValidator
validator = SafeMimeTypeValidator(
allowed_mimes=["image/png", "image/jpeg", "application/pdf"]
)Prop
Type
Executable & Injection Firewall:
Before validating formats, SafeMimeTypeValidator inspects header bytes for high-risk binary headers and script patterns:
- Executable Headers (
BLOCKED_HEADER_PREFIXES): Windows PE (MZ), Unix Shebang scripts (#!/), Linux ELF binaries (\x7fELF). - Malicious Content Patterns (
MALICIOUS_CONTENT_PATTERNS): Active scripts and XSS vectors including<?php,<script,javascript:,vbscript:,data:text/html,<!doctype html,<html,<iframe>,<object>,<embed>, DOM event attributes (onload=,onerror=,onclick=), and SVG xlink JavaScript links.
Any file containing these execution signatures is immediately rejected with a critical security alert, regardless of its extension.
Default Supported Binary Signatures (SIGNATURES)
SafeMimeTypeValidator validates against the following built-in magic byte headers:
| Format | Magic Byte Signature | MIME Type |
|---|---|---|
| PNG | b"\x89PNG\r\n\x1a\n" | image/png |
| JPEG | b"\xff\xd8\xff" | image/jpeg |
| GIF | b"GIF87a" / b"GIF89a" | image/gif |
b"%PDF" | application/pdf | |
| WebP | b"RIFF" | image/webp |