Masquerade

A Rust library, CLI, and Python package for checking that structured files match their declared type by performing bounded signature and structural checks prior to any full loading, decoding, or usage of their contents.

Examples

Rust

use masquerade::inspect;

let result = inspect("upload.jpg")?;
if !result.status().is_valid() {
    if let Some(failure) = result.failure() {
        eprintln!("{}: {}", failure.code(), failure.reason());
    }
}
# Ok::<(), std::io::Error>(())

Python

Use check_file when only boolean outcomes are needed:

from masquerade import check_file

signature, structure = check_file("upload.jpg")

Use inspect_file when the caller needs to decide how to report a failure:

import logging

from masquerade import ValidationStatus, inspect_file

result = inspect_file("upload.jpg")
if result.status is not ValidationStatus.VALID:
    failure = result.structure or result.signature
    logging.getLogger(__name__).info(
        "Rejected upload (%s): %s", failure.code, failure.reason
    )

CLI

$ masquerade upload.jpg
upload.jpg: valid

Use --signature-only to perform only the bounded signature check. Exit status is zero for valid media, one for invalid or unsupported media, and two for usage or I/O errors.

Development

Masquerade uses Cargo for the workspace and uv with Maturin for Python development:

• cargo test --workspace
• cargo clippy --workspace --all-targets -- -D warnings
• cargo fmt --all -- --check
• uv sync --all-groups
• uv run pytest
• uv run pyright
• uv run ruff check .
• uv run ruff format --check .
• uv build
• uv run twine check dist/*