# Rash - Bidirectional Shell Safety Tool
[](https://crates.io/crates/bashrs)
[](https://docs.rs/bashrs)
[](LICENSE)
[](https://github.com/paiml/bashrs/actions)
[](https://github.com/paiml/bashrs/actions)
[](https://github.com/paiml/bashrs/blob/main/rash/src/testing/)
[](https://github.com/paiml/bashrs/actions)
[](https://github.com/paiml/bashrs)
**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`](examples/PURIFICATION_WORKFLOW.md) for detailed purification examples.
---
## Quick Start (PRIMARY Workflow)
Write Rust:
```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:
```bash
$ 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)
```bash
# 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:
```bash
# 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
### Using cargo-binstall
```bash
cargo binstall bashrs
```
### From Source
```bash
# 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
```bash
# 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
```bash
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
```rust
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
```rust
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
```rust
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
```rust
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
```rust
// 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
```rust
// 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)
```rust
// ✅ 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:
```rust
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:
```bash
# 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:
```bash
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/`](examples/) directory for complete examples:
- **Basic**
- [Hello World](examples/hello.rs) - Simplest example
- [Variables](examples/basic/variables.rs) - Variable usage and escaping
- [Functions](examples/basic/functions.rs) - Built-in functions
- [Standard Library](examples/stdlib_demo.rs) - Stdlib functions demo
- **Control Flow**
- [Conditionals](examples/control_flow/conditionals.rs) - If/else statements
- [Loops](examples/control_flow/loops.rs) - Bounded iteration
- **Safety**
- [Injection Prevention](examples/safety/injection_prevention.rs) - Security examples
- [String Escaping](examples/safety/escaping.rs) - Special character handling
- **Real-World**
- [Node Installer](examples/node-installer.rs) - Node.js bootstrap script
- [Rust Installer](examples/rust-installer.rs) - Rust toolchain installer
## Shell Compatibility
Generated scripts are tested on:
| 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)
| **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](docs/ERROR_GUIDE.md)** for common errors and solutions.
## MCP Server
Rash provides a Model Context Protocol (MCP) server for AI-assisted shell script generation:
```bash
# 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](docs/mcp-registry-publish.md) for details on the automated publishing process.
## Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
### Development Setup
```bash
# 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](docs/mcp-registry-publish.md).
## License
Rash is licensed under the MIT License. See [LICENSE](LICENSE) for details.
## Acknowledgments
Rash is built with safety principles inspired by:
- [ShellCheck](https://www.shellcheck.net/) for shell script analysis
- [Oil Shell](https://www.oilshell.org/) 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):
- [x] Rust-to-Shell transpilation (POSIX, Bash, Dash, Ash)
- [x] Full AST parsing and validation (98.92% coverage)
- [x] IR generation and optimization (87-99% coverage)
- [x] Safety verification and escape handling (95.45% coverage)
- [x] Multi-shell compatibility testing (100% pass rate)
- [x] Property-based testing (114k executions, 0 failures)
- [x] Fuzzing infrastructure (0 failures)
- [x] ShellCheck compliance (24/24 tests pass)
- [x] Arithmetic expressions and comparisons
- [x] User-defined functions
- [x] `println!` macro support
- [x] MCP server (rash-mcp)
**CLI Tools** (Complete):
- [x] `bashrs build` - Transpile Rust to shell
- [x] `bashrs check` - Validate Rust compatibility
- [x] `bashrs init` - Project scaffolding
- [x] `bashrs verify` - Script verification
- [x] `bashrs inspect` - Formal verification reports
**Shipped in v1.0.0-rc1**:
- [x] Control flow (if/else if/else) - STABLE
- [x] For loops (0..n, 0..=n) - STABLE
- [x] While loops (with max_iterations safety) - STABLE
- [x] Match expressions (basic pattern matching) - EXPERIMENTAL
- [x] Logical operators (&&, ||, !) - STABLE
- [x] String and integer comparisons - STABLE
- [x] 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**:
- [x] For loops (`for i in 0..10`) - SHIPPED in v1.0.0-rc1
- [x] Match expressions (pattern matching) - SHIPPED in v1.0.0-rc1
- [x] 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](.quality/v1.0-feature-scope.md) for detailed feature decisions.