wgex

wgex is a secure, cache-aware CLI tool for fetching, verifying, and executing scripts from remote URLs. It is designed for safe, repeatable script execution with strong security guarantees, including hash verification, TTL-based caching, and optional sandboxing.

It's intended to add a little more security to installation scripts that tell you to do curl mycommand.net/install | sh

Features

• SHA256 Hash Verification: Ensures downloaded scripts match an expected hash before execution.
• HTTP(S) Download with Conditional Requests: Uses ETag and Last-Modified headers for efficient caching and freshness checks.
• TTL-Based Caching: Scripts are cached locally and revalidated after a configurable time-to-live (TTL).
• Atomic Caching and Metadata Management: Prevents partial or corrupted cache files.
• Optional Sandboxing: Supports chroot-based sandboxing on Unix for isolated script execution.
• Configurable Logging: Simple, colorized logging with multiple log levels.
• Cross-Platform Support: Works on Unix and non-Unix systems, with best-effort emulation of shebang execution on non-Unix.
• CLI Interface: Flexible command-line arguments for specifying script URL, hash, TTL, and execution options.
• Written in Rust: Safety, performance, and reliability.

Security Considerations

wgex is built with security as a top priority:

• Hash Verification: Scripts are only executed if their SHA256 hash matches the expected value, preventing tampering.
• HTTPS Enforcement: Only HTTPS URLs are allowed by default. Use --allow-http to override (not recommended).
• Sandboxing: On Unix, you can use --sandbox chroot to run scripts in a minimal chroot jail (requires root).
• Cache Integrity: Corrupted or mismatched cache files are automatically detected and removed.
• Limited Download Size: The maximum download size is configurable to prevent resource exhaustion attacks.
• Logging: All errors and warnings are clearly logged, with optional debug and trace output for diagnostics.

Installation

cargo install wgex

Usage

# We'll get a warning and exit if the content from the server doesn't match the hash

wgex \
--url https://raw.githubusercontent.com/patbeagan1/dotfiles/refs/heads/master/scripts/documentation/show.py \
--sha256 f52ea09aa5300ecde0bccc76ae5e8ffe961e5b358d7d520de5e71414ef352c7b \
-- \
--magick

# arguments to the script that's being downloaded come after the double dash "--"

Help

A tool to securely fetch, cache, and execute scripts

USAGE:
    wgex [OPTIONS] --url <URL> [SCRIPT_ARGS]...

ARGS:
    <SCRIPT_ARGS>...    Arguments to pass to the script. To pass arguments, use '--' before the
                        script arguments

OPTIONS:
        --allow-http
            Allow plain HTTP (insecure). Defaults to false; only HTTPS is allowed by default

    -h, --help
            Print help information

        --log-level <LOG_LEVEL>
            Log level: off, error, warn, info, debug, trace. Default: off [default: off] [possible
            values: off, error, warn, info, debug, trace]

        --max-bytes <MAX_BYTES>
            Maximum download size in bytes. Default 20 MiB [default: 20971520]

        --sandbox <SANDBOX>
            Sandbox mode: none or chroot. Default: none [default: none] [possible values: none,
            chroot]

        --sha256 <SHA256>
            The expected SHA256 hash of the script

        --timeout-secs <TIMEOUT_SECS>
            HTTP client timeout in seconds [default: 20]

        --ttl <TTL>
            Time-to-live for the cache in seconds. After this time, the URL will be re-checked
            [default: 86400]

        --url <URL>
            The URL of the script to fetch

    -V, --version
            Print version information