TAR Validations

Contents

TAR Validations#

Why Security Validation is Critical for Tar Files#

Processing untrusted TAR archives poses significant security risks:

Path Traversal: Malicious TAR entries with ../ paths can overwrite sensitive system files
Resource Exhaustion: Archive bombs with excessive members or inflated sizes can cause denial of service
System Resource Abuse: Extreme total extraction sizes or individual file sizes can exhaust memory/disk
Symlink/Hardlink Attacks: Links can point to sensitive files outside the extraction target
Device/FIFO Exploitation: Device nodes or named pipes can cause system instability

Capabilities#

The validate_tar function performs comprehensive security checks:

Check	Description
File Size	Enforces maximum allowed archive file size
Member Count	Limits number of files/directories inside archive
Total Extraction Size	Prevents archive bombs through total extracted size limits
Individual File Size	Caps size per extracted file
Path Traversal	Prevents `../` and absolute path escapes
Link Rejection	Blocks symlinks, hardlinks, devices, and FIFOs
Filename Length	Limits path length to prevent buffer overflows
Directory Depth	Prevents excessive nesting that could exhaust inodes
Remote File Restriction	Only accepts `https://` URIs (strictly no `http://`, `ftp://`, `file://`)

Usage Options#

Parameters#

Parameter	Description
`func_or_path`	Path or callable for the tar archive.
`max_file_size`	Max size of the archive file.
`max_tar_members`	Max number of members in the archive.
`max_total_extracted_size`	Max total size of extracted content.
`max_individual_file_size`	Max size of any single file.
`max_filename_length`	Max length of filenames.
`max_directory_depth`	Max directory nesting depth.

Defaults#

Global default fallbacks:

DEFAULT_MAX_FILE_SIZE = 10 * 1024 * 1024  # 10 MB
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

And note:

HEAD_TIMEOUT = 10
DOWNLOAD_TIMEOUT = 30

Usage Modes#

1. Direct Call / CLI Validation#

# Local file validation
valid = validate_tar("path/to/archive.tar", max_tar_members=100)

# Remote HTTPS validation
valid = validate_tar("https://example.com/archive.tar", max_file_size=10*1024*1024)

# Returns bool: True if valid, False if invalid (errors printed to stdout)

2. Decorator Mode#

from pathlib import Path

# Bare decorator (uses default limits)
@validate_tar
def process_archive(path: Path):
    # Archive already validated before function body executes
    return extract_content(path)

# Decorator with custom limits
@validate_tar(max_file_size=5_000_000, max_tar_members=50)
def process_secure_archive(file_path: str):
    # Secure validation with custom thresholds
    return handle_archive(file_path)

# Argument name targeting
@validate_tar("input_path", max_directory_depth=5)
def process_with_named_arg(input_path: str):
    # Validates the argument named 'input_path'
    return process(input_path)

3. Factory Mode#

# Create a preconfigured validator
validator = validate_tar(max_tar_members=10, max_individual_file_size=1024*1024)

@validator
def process_small_archive(tar_path: str):
    # Uses preconfigured limits
    return handle(tar_path)

API Reference#

validate_tar(
    func_or_path=None,           # Callable (decorator), str/Path (direct), or None (factory)
    max_file_size=None,          # Max archive file size (bytes)
    max_tar_members=None,        # Max number of entries in archive
    max_total_extracted_size=None, # Max total extracted bytes
    max_individual_file_size=None, # Max per-file extracted size
    max_filename_length=None,    # Max path length
    max_directory_depth=None     # Max directory nesting level
)