Rash - Bidirectional Shell Safety Tool

Rash (v6.34.0) is a bidirectional shell safety tool that purifies legacy bash scripts and lets you write shell scripts in REAL Rust with automatic safety guarantees.

🚀 What's New in v6.34.0+

Latest Updates - 2025-11-12

• Issue #21 FIXED: SC2171 false positive with JSON brackets in heredocs (now correctly handles heredoc contexts)
• Issue #22 FIXED: SC2247 false positive with math operations in awk/bc (context-aware math detection)
• Test Suite: 6,583 tests, 100% pass rate, zero regressions
• Quality: All fixes implemented using EXTREME TDD (unit tests, property tests, mutation tests, integration tests)

v6.34.0 Feature Completions - Released 2025-11-12

• Issue #2 RESOLVED: Makefile multi-line format preservation with --preserve-formatting and --skip-consolidation flags
• Issue #4 RESOLVED: Complete bash parser - all 9 phases including redirection operators, heredocs, pipelines, special variables
• Dockerfile Purification: 6 comprehensive transformations (DOCKER001-006) for production-ready Docker images
• Dogfooding Complete: Fixed all P0 errors in bashrs's own infrastructure (0 errors found by self-analysis)

See CHANGELOG.md for complete release notes.

Why Rash?

• 🛡️ Automatic Safety: Protection against shell injection, word splitting, glob expansion
• 🔍 Beyond Linting: Full AST semantic understanding - transforms code, doesn't just warn
• 📦 Zero Runtime Dependencies: Generated scripts work on any POSIX shell
• 🎯 Deterministic Output: Same input always produces identical scripts
• ✅ ShellCheck Compliant: All output passes strict linting

How Rash Exceeds ShellCheck

Key Difference: ShellCheck tells you what's wrong. Rash understands your code's intent and rewrites it to be safe, deterministic, and idempotent — automatically.

Quick Start

Installation

# From crates.io (recommended)
cargo install bashrs

# Or from source
git clone https://github.com/paiml/bashrs
cd bashrs
cargo install --path rash

Write Rust, Get Safe Shell

// install.rs
#[rash::main]
fn main() {
    let version = env_var_or("VERSION", "1.0.0");
    let prefix = env_var_or("PREFIX", "/usr/local");

    echo("Installing MyApp {version} to {prefix}");

    mkdir_p("{prefix}/bin");
    mkdir_p("{prefix}/share/myapp");

    if exec("cp myapp {prefix}/bin/") {
        echo("✓ Binary installed");
    } else {
        eprint("✗ Failed to install binary");
        exit(1);
    }
}

Transpile to safe POSIX shell:

$ bashrs build install.rs -o install.sh

Or Purify Existing Bash

Before (messy bash):

#!/bin/bash
SESSION_ID=$RANDOM                      # Non-deterministic
mkdir /app/releases/$RELEASE            # Non-idempotent
rm /app/current                         # Fails if doesn't exist

After (purified by Rash):

#!/bin/sh
session_id="session-${version}"         # ✅ Deterministic
mkdir -p "/app/releases/${release}"     # ✅ Idempotent
rm -f "/app/current"                    # ✅ Safe removal

Core Commands

# Transpile Rust to shell
bashrs build input.rs -o output.sh

# Purify legacy bash scripts
bashrs purify messy.sh -o clean.sh

# Interactive REPL with debugging
bashrs repl

# Lint shell scripts
bashrs lint script.sh

# Test bash scripts
bashrs test script.sh

# Quality scoring
bashrs score script.sh

# Comprehensive audit
bashrs audit script.sh

📚 Documentation

The Rash Book is the canonical source for all documentation:

→ Read The Rash Book

Quick links:

• Getting Started
• Quick Start Tutorial
• Linting Rules
• Configuration Management
• API Reference

Why the book?

• ✅ All examples automatically tested
• ✅ Always up-to-date with latest release
• ✅ Comprehensive coverage of all features
• ✅ Real-world examples and tutorials

Quality Metrics (v6.36.0+)

Golden Trace Regression Detection (v6.36.0+)

Rash integrates with renacer to capture and compare syscall patterns for regression detection:

# Capture reference trace
make golden-capture TRACE=version CMD='./target/release/bashrs --version'

# Compare against golden (detect regressions)
make golden-compare TRACE=version CMD='./target/release/bashrs --version'

Use cases:

• Detect unexpected file access patterns
• Prevent security regressions
• Verify performance optimizations reduce syscalls
• Ensure deterministic behavior across builds

See Golden Trace Documentation for complete guide.

Shell Compatibility

Generated scripts are tested on:

Performance

Rash is designed for fast transpilation:

• Rust-to-Shell: 21.1µs transpile time
• Makefile Parsing: 0.034-1.43ms (70-320x faster than targets)
• Memory Usage: <10MB for most scripts

MCP Server

Rash provides a Model Context Protocol (MCP) server for AI-assisted shell script generation:

# Install MCP server
cargo install rash-mcp

# Run server
rash-mcp

Available in the official MCP registry as io.github.paiml/rash.

Contributing

We welcome contributions! See our Contributing Guide for details.

# Clone and test
git clone https://github.com/paiml/bashrs.git
cd bashrs
make test

# Run all quality checks
make validate

License

Rash is licensed under the MIT License. See LICENSE for details.

Acknowledgments

Rash is built with safety principles inspired by:

• ShellCheck for shell script analysis
• Oil Shell for shell language design
• The Rust community for memory safety practices

For comprehensive documentation, tutorials, and examples, visit The Rash Book.