fileaudit.gz_check module

License MPL-2.0 (C) 2026 Created by Maikel Mardjan - https://nocomplexity.com/ FileAudit - GZ File Security Checker

exception fileaudit.gz_check.GzValidationError(message)

Bases: Exception

Custom exception for GZip validation failures in FileAudit.

class fileaudit.gz_check.HTTPSOnlyRedirectHandler

Bases: HTTPRedirectHandler

Redirect handler that blocks any redirect to a non-HTTPS URL. Prevents downgrade attacks (e.g. https -> http redirects).

redirect_request(req, fp, code, msg, headers, newurl)

Return a Request or None in response to a redirect.

This is called by the http_error_30x methods when a redirection response is received. If a redirection should take place, return a new Request to allow http_error_30x to perform the redirect. Otherwise, raise HTTPError if no-one else should try to handle this url. Return None if you can’t but another Handler might.

fileaudit.gz_check.validate_gz(func_or_path=None, max_file_size=None, max_uncompressed_ratio=None, max_uncompressed_size=None)

Validate GZip files via decorator or direct invocation.

A GZip file validator that can operate in two modes:

1. Decorator mode — wraps a function to validate a GZip file path passed as an argument before the function body runs.

2. Direct call / CLI mode — validates a file immediately and returns a boolean result.

Security checks performed:

• Compressed file size limits

• GZip decompression ratio limits

• Maximum uncompressed size

• Streaming decompression

• GZip CRC/trailer validation

• GZip concatenated-member validation

• Regular-file validation (local)

• Symlink protection where supported (local)

• Detection of file-size changes during validation (local)

• Remote files restricted to https:// only

Usage:

Bare decorator:

@validate_gz
def process(path):
    ...

Decorator with defaults:

@validate_gz()
def process(path):
    ...

Decorator with custom argument name and options:

@validate_gz("custom_arg_name", max_file_size=5000)
def process(custom_arg_name):
    ...

Direct validation of a local file:

validate_gz("path/to/file.gz", max_uncompressed_size=1000000)

Direct validation of a remote file (HTTPS only):

validate_gz("https://example.com/file.gz")

Parameters:

• func_or_path (callable, str, pathlib.Path, or None) –

  Controls the operating mode:

  • If a callable: the function to decorate

  (bare decorator usage: @validate_gz). - If a str or Path representing a file path or HTTPS URL: direct validation mode. - If a str that is a valid Python identifier and does not look like a file path: treated as the target argument name in decorator mode. - If None: returns a decorator factory.

• max_file_size (int)

• bytes. (- Maximum total uncompressed size in)

• max_uncompressed_ratio (int)

• ratio. (- Maximum GZip decompression)

• max_uncompressed_size (int)

• bytes.

Returns:

• In decorator mode: the wrapped function.

• In direct call mode: True if validation passes, False if validation fails.

Return type:

Union[callable, bool, function]

Raises:

• GzValidationError – If validation fails in decorator mode.

• ValueError – If a security limit is invalid.