Rash - Bidirectional Shell Safety Tool

Rash is a bidirectional shell safety tool that lets you write shell scripts in REAL Rust and automatically purify legacy bash scripts.

Why Rash?

🛡️ Safety First: Automatic protection against shell injection attacks
🔍 Compile-Time Verification: Catch errors before deployment
📦 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 Works: Two Workflows

Rash operates in two directions to maximize shell script safety:

🚀 PRIMARY: Rust → Safe Shell (Production-Ready)

Write new scripts in REAL Rust, transpile to provably safe shell.

Rust Code (.rs) → cargo test → Transpile → Safe POSIX Shell
                   ↑ Test FIRST with Rust tooling

Use cases:

Bootstrap installers (Node.js, Rust toolchain, etc.)
CI/CD deployment scripts
System configuration tools
Any new shell automation

Benefits:

Full Rust std library support
Test with cargo test, lint with cargo clippy
Property-based testing with proptest
100% deterministic, idempotent output

🔄 SECONDARY: Bash → Rust → Purified Bash (Legacy Cleanup)

Ingest messy bash, convert to Rust with tests, output purified shell.

Messy Bash → Parser → Rust + Tests → Transpile → Purified Bash
                       ↑ Tests auto-generated

Use cases:

Clean up legacy bash scripts
Remove non-deterministic constructs ($RANDOM, timestamps, $$)
Enforce idempotency (mkdir -p, rm -f)
Generate comprehensive test suites

Benefits:

Automatic test generation
Remove unsafe patterns
Maintain shell compatibility
Preserve functionality while improving safety

See examples/PURIFICATION_WORKFLOW.md for detailed purification examples.

Quick Start (PRIMARY Workflow)

Write Rust:

// 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}");
    
    // Create installation directories
    mkdir_p("{prefix}/bin");
    mkdir_p("{prefix}/share/myapp");
    
    // Copy files (with automatic quoting)
    if exec("cp myapp {prefix}/bin/") {
        echo("✓ Binary installed");
    } else {
        echo("✗ Failed to install binary");
        exit(1);
    }
}

Get POSIX shell:

$ bashrs build install.rs -o install.sh
$ cat install.sh
#!/bin/sh
# Generated by Rash v0.4.0
# POSIX-compliant shell script

set -euf
IFS=' 	
'
export LC_ALL=C

# Rash runtime functions
rash_require() {
    if ! "$@"; then
        echo "FATAL: Requirement failed: $*" >&2
        exit 1
    fi
}

# Main script begins
main() {
    VERSION="${VERSION:-1.0.0}"
    PREFIX="${PREFIX:-/usr/local}"
    
    echo "Installing MyApp $VERSION to $PREFIX"
    
    mkdir -p "$PREFIX/bin"
    mkdir -p "$PREFIX/share/myapp"
    
    if cp myapp "$PREFIX/bin/"; then
        echo "✓ Binary installed"
    else
        echo "✗ Failed to install binary"
        exit 1
    fi
}

# Execute main function
main "$@"

Installation

From crates.io (Recommended)

# Install latest release candidate
cargo install bashrs --version 1.0.0-rc1

# Or install latest stable
cargo install bashrs

Binary Releases

Pre-built binaries are available for Linux and macOS:

# Linux x86_64
curl -L https://github.com/paiml/bashrs/releases/latest/download/bashrs-x86_64-unknown-linux-musl.tar.gz | tar xz

# macOS x86_64
curl -L https://github.com/paiml/bashrs/releases/latest/download/bashrs-x86_64-apple-darwin.tar.gz | tar xz

# macOS ARM64
curl -L https://github.com/paiml/bashrs/releases/latest/download/bashrs-aarch64-apple-darwin.tar.gz | tar xz

Using cargo-binstall

cargo binstall bashrs

From Source

# Full build with all features
cargo install --git https://github.com/paiml/bashrs

# Minimal build (smaller binary, ~2MB)
cargo install --git https://github.com/paiml/bashrs --no-default-features --features minimal

Usage

Basic Commands

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

# Check if a file is valid Rash
bashrs check input.rs

# Initialize a new Rash project
bashrs init my-project

# Verify safety properties
bashrs verify input.rs output.sh

# Inspect AST and safety properties
bashrs inspect input.rs

# Compile to self-extracting script (BETA)
bashrs compile input.rs -o install --self-extracting

CLI Options

USAGE:
    bashrs [OPTIONS] <COMMAND>

COMMANDS:
    build       Transpile Rust to shell script
    check       Validate Rust source without transpiling
    init        Initialize a new Rash project
    verify      Verify shell script matches source
    inspect     Analyze AST and safety properties
    compile     Compile to standalone binary (BETA - experimental)

OPTIONS:
    -v, --verbose            Enable verbose output
    -V, --version            Print version information
    -h, --help               Print help information
    --target <SHELL>         Target shell: posix, bash, ash (default: posix)
    --verify <LEVEL>         Verification level: none, basic, strict, paranoid
    --validation <LEVEL>     Validation level: none, minimal, strict, paranoid

BUILD OPTIONS:
    -o, --output <FILE>      Output file (default: stdout)
    --optimize               Enable optimization passes
    --strict                 Enable strict mode checks
    --emit-proof             Emit verification proof alongside output

Language Features

Supported Rust Subset

Rash supports a carefully chosen subset of Rust that maps cleanly to shell:

Variables and Types

let name = "Alice";              // String literals
let count = 42;                  // Integers (including negatives: -42)
let flag = true;                 // Booleans
let user = env("USER");          // Environment variables
let result = capture("date");    // Command output

Arithmetic Operations

let x = 1 + 2;                   // Addition → $((1 + 2))
let y = 10 - 3;                  // Subtraction → $((10 - 3))
let z = 4 * 5;                   // Multiplication → $((4 * 5))
let w = 20 / 4;                  // Division → $((20 / 4))

Comparison Operators

if x > 0 {                       // Greater than → [ "$x" -gt 0 ]
    println!("Positive");        // println! macro supported
}
if y == 5 { ... }                // Equal → [ "$y" -eq 5 ]
if z < 10 { ... }                // Less than → [ "$z" -lt 10 ]

User-Defined Functions

fn add(a: i32, b: i32) -> i32 {
    a + b                        // Return value via echo
}

fn main() {
    let sum = add(1, 2);         // Captured with $(add 1 2)
    println!("Sum: {}", sum);
}

Built-in Functions

// I/O operations
echo("Hello, World!");           // Print to stdout
println!("Hello, World!");       // println! macro (Sprint 10)
eprint("Error!");                // Print to stderr

// File system
mkdir_p("/tmp/myapp");           // Create directory recursively
write_file("config.txt", data);  // Write file
let content = read_file("config.txt");  // Read file
if path_exists("/etc/config") { ... }   // Check path

// Process management  
exec("ls -la");                  // Run command
let output = capture("date");    // Capture command output
exit(0);                         // Exit with code

// Environment
set_env("KEY", "value");         // Set environment variable
let val = env("KEY");            // Get environment variable
let val = env_var_or("KEY", "default"); // With default

Control Flow

// Conditionals
if condition {
    // ...
} else if other {
    // ...
} else {
    // ...
}

// ✅ Pattern matching - SUPPORTED (experimental in v1.0.0-rc1)
match value {
    "linux" => echo("Linux detected"),
    "darwin" => echo("macOS detected"),
    _ => echo("Unknown OS"),
}

Loops ✅ (Supported in v1.0.0-rc1)

// ✅ For loops - FULLY SUPPORTED
for i in 0..10 {
    echo("Iteration: {i}");
}

// ✅ While loops - FULLY SUPPORTED
let mut count = 0;
while count < 10 {
    count = count + 1;
    echo("Count: {count}");
}

Safety Features

All generated scripts are protected against:

Command Injection: All variables are properly quoted
Path Traversal: Paths are validated and escaped
Glob Expansion: Glob patterns are quoted when needed
Word Splitting: IFS is set to safe value
Undefined Variables: set -u catches undefined vars

Example of automatic safety:

let user_input = env("UNTRUSTED");
exec("echo {user_input}");  // Safe: becomes echo "$user_input"

Beta Features ⚗️

The following features are available but marked as experimental in v1.0:

Binary Compilation (BETA)

Compile Rust to self-extracting shell scripts or container images:

# Self-extracting script (includes runtime)
bashrs compile install.rs -o install --self-extracting

# Container image (OCI format)
bashrs compile app.rs -o app --container --format oci

Status:

✅ Self-extracting scripts work and are tested
⚠️ Container packaging is experimental
⚠️ Binary optimization is in progress

Limitations:

Container formats are not fully implemented
Advanced runtime optimizations pending
Limited to dash/bash/busybox runtimes

Recommendation: Use bashrs build for production deployments. Use compile for quick testing or when you need a single-file installer.

Proof Generation (BETA)

Generate formal verification proofs alongside transpiled scripts:

bashrs build input.rs -o output.sh --emit-proof

This creates output.proof with formal correctness guarantees.

Status: ⚠️ Proof format is experimental and may change

Examples

See the examples/ directory for complete examples:

Basic
- Hello World - Simplest example
- Variables - Variable usage and escaping
- Functions - Built-in functions
- Standard Library - Stdlib functions demo
Control Flow
- Conditionals - If/else statements
- Loops - Bounded iteration
Safety
- Injection Prevention - Security examples
- String Escaping - Special character handling
Real-World
- Node Installer - Node.js bootstrap script
- Rust Installer - Rust toolchain installer

Shell Compatibility

Generated scripts are tested on:

Shell	Version	Status
POSIX sh	-	✅ Full support
dash	0.5.11+	✅ Full support
bash	3.2+	✅ Full support
ash (BusyBox)	1.30+	✅ Full support
zsh	5.0+	✅ Full support
mksh	R59+	✅ Full support

Performance

Rash is designed for fast transpilation:

21.1µs transpile time for simple scripts (100x better than target!)
Memory usage <10MB for most scripts
Generated scripts add minimal overhead (~20 lines boilerplate)

Quality Metrics (v1.0.0)

Metric	Status	Notes
Tests	756/756 ✅	100% pass rate (752 unit + 4 integration)
Property Tests	52 properties ✅	~26,000+ test cases, 0 failures
Core Coverage	85.36% ✅	Parser, IR, Emitter, Verifier
Total Coverage	82.18% ✅	All modules including CLI
Mutation Kill Rate	~83% (baseline) 🟡	Target: ≥90% (Sprint 26 in progress)
Multi-Shell	100% pass ✅	sh, dash, bash, ash, zsh, mksh
ShellCheck	24/24 pass ✅	All generated scripts POSIX-compliant
Performance	19.1µs ✅	Simple transpile (523x better than target!)
Complexity	Median 1.0 ✅	All core functions <10
Edge Cases	11/11 fixed ✅	100% completion

v1.0.0 Status: ✅ STABLE - Production-ready with A+ quality grade

Troubleshooting

Having issues? Check our Error Guide for common errors and solutions.

MCP Server

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

# Install from crates.io
cargo install rash-mcp

# Run MCP server
rash-mcp

The MCP server is available in the official registry as io.github.paiml/rash.

For developers: See MCP Registry Publishing Guide for details on the automated publishing process.

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/paiml/rash.git
cd rash

# Run tests
make test

# Run with all checks
make validate

# Build release binary
make release

Publishing to MCP Registry

For maintainers publishing new MCP server versions, see the MCP Registry Publishing Guide.

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

Roadmap

v1.0.0-rc1 (Current Release) 🧪

Status: Release Candidate - Ready for Testing Released: 2025-10-04 Quality Metrics:

667 tests passing (100% pass rate)
97.7% mutation kill rate (42/43 mutants caught)
83.07% code coverage (88.74% core transpiler)
0 shellcheck warnings
37/37 book examples passing

Core Features (Complete):

Rust-to-Shell transpilation (POSIX, Bash, Dash, Ash)
Full AST parsing and validation (98.92% coverage)
IR generation and optimization (87-99% coverage)
Safety verification and escape handling (95.45% coverage)
Multi-shell compatibility testing (100% pass rate)
Property-based testing (114k executions, 0 failures)
Fuzzing infrastructure (0 failures)
ShellCheck compliance (24/24 tests pass)
Arithmetic expressions and comparisons
User-defined functions
println! macro support
MCP server (rash-mcp)

CLI Tools (Complete):

bashrs build - Transpile Rust to shell
bashrs check - Validate Rust compatibility
bashrs init - Project scaffolding
bashrs verify - Script verification
bashrs inspect - Formal verification reports

Shipped in v1.0.0-rc1:

Control flow (if/else if/else) - STABLE
For loops (0..n, 0..=n) - STABLE
While loops (with max_iterations safety) - STABLE
Match expressions (basic pattern matching) - EXPERIMENTAL
Logical operators (&&, ||, !) - STABLE
String and integer comparisons - STABLE
Self-extracting scripts - STABLE
Container packaging (in progress)
Proof generation (experimental format)

v1.1 (Planned)

Interactive Features:

Playground/REPL (separate rash-playground crate)
Web-based transpiler
Live syntax highlighting

Language Features:

For loops (for i in 0..10) - SHIPPED in v1.0.0-rc1
Match expressions (pattern matching) - SHIPPED in v1.0.0-rc1
While loops - SHIPPED in v1.0.0-rc1
Arrays and collections (advanced operations)
Enhanced pattern matching guards

Tooling:

Language server protocol (LSP)
IDE integration examples
Better error diagnostics

v1.2+ (Future)

Advanced Features:

Incremental compilation
More shell targets (fish, PowerShell, nushell)
Package manager integration
Advanced optimizations (constant folding, DCE)
Formal verification with SMT solvers

Documentation:

Video tutorials
Interactive examples
Best practices guide

See v1.0-feature-scope.md for detailed feature decisions.

bashrs 1.0.0