TarGz Validations

TarGz Validations#

Why security checks are needed#

TAR.GZ archives can embed zip bombs, path-traversal payloads (../), oversized members, symlinks, device nodes, or excessively deep directory trees. Validating an archive before extraction or further processing prevents resource exhaustion, arbitrary file writes, and other attacks that would otherwise occur only at extraction time.

Capabilities#

The validator enforces configurable limits on:

compressed file size
GZip decompression ratio (zip-bomb protection)
number of TAR members
total extracted size
individual file size
filename / path length
directory nesting depth

The validator also has the capabilities to reject or protect:

Path Traversal Protection
The function validates member names against a temporary base path to ensure nothing escapes the intended extraction directory. So it prevents extracting outside target directory.
Special Files Rejected
The function also rejects symlinks/hardlinks/devices/FIFOs” in tar.gz files.

Usage Options#

Parameters#

Parameter	Description
`path`	path (local or remote) to the `.tar.gz` archive.
`max_file_size`	Maximum size (in bytes) of the compressed `.tar.gz` archive.
`max_uncompressed_ratio`	Maximum compression ratio (uncompressed / compressed size). Protects against bombs.
`max_tar_members`	Maximum number of members (files + directories) in the archive.
`max_total_extracted_size`	Maximum total size (in bytes) of all extracted content.
`max_individual_file_size`	Maximum size (in bytes) of any single file inside the archive.
`max_filename_length`	Maximum length of any filename or path component.
`max_directory_depth`	Maximum nesting depth of directories inside the archive.

Defaults#

Global default fallbacks:

DEFAULT_MAX_FILE_SIZE = 10 * 1024 * 1024  # 10 MB
DEFAULT_MAX_UNCOMPRESSED_RATIO = 100  # 100:1 ratio
DEFAULT_MAX_TAR_MEMBERS = 1000
DEFAULT_MAX_TOTAL_EXTRACTED_SIZE = 100 * 1024 * 1024  # 100 MB
DEFAULT_MAX_INDIVIDUAL_FILE_SIZE = 10 * 1024 * 1024  # 10 MB
DEFAULT_MAX_FILENAME_LENGTH = 255
DEFAULT_MAX_DIRECTORY_DEPTH = 50

How to use the checks#

Decorator mode – validate the path argument of a function before it runs:

@validate_tar_gz
def process(archive_path):
    ...

@validate_tar_gz(max_tar_members=50, max_file_size=10_000_000)
def process(archive_path):
    ...

Direct / CLI mode – validate immediately and obtain a boolean result:

ok = validate_tar_gz("data.tar.gz", max_uncompressed_ratio=20)

Failures raise TarValidationError in decorator mode and return False (with a printed message) in direct mode.