Bashrs

🚀 Rash - 双向 shell 安全工具

Rash 是一款双向 shell 安全工具，它可以净化传统的 bash 脚本，还能让你用纯正的 Rust 编写 shell 脚本，并自动提供安全保障。

🚀 快速开始

安装

# 从 crates.io 安装（推荐）
cargo install bashrs

# 或者从源代码安装
git clone https://github.com/paiml/bashrs
cd bashrs
cargo install --path rash

使用 Rust 编写，生成安全的 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);
    }
}

转换为安全的 POSIX shell 脚本：

$ bashrs build install.rs -o install.sh

或者净化现有的 bash 脚本

净化前（杂乱的 bash 脚本）：

#!/bin/bash
SESSION_ID=$RANDOM                      # 非确定性的
mkdir /app/releases/$RELEASE            # 非幂等的
rm /app/current                         # 如果文件不存在会失败

净化后（由 Rash 净化）：

#!/bin/sh
session_id="session-${version}"         # ✅ 确定性的
mkdir -p "/app/releases/${release}"     # ✅ 幂等的
rm -f "/app/current"                    # ✅ 安全的删除操作

✨ 主要特性

• 🛡️ 自动安全防护：防止 shell 注入、单词分割和通配符扩展。
• 🔍 超越代码检查：具备完整的抽象语法树（AST）语义理解能力，不仅能警告，还能转换代码。
• 📦 零运行时依赖：生成的脚本可在任何 POSIX 兼容的 shell 上运行。
• 🎯 确定性输出：相同的输入始终生成相同的脚本。
• ✅ 符合 ShellCheck 标准：所有输出都能通过严格的代码检查。

Rash 超越 ShellCheck 的地方

关键区别：ShellCheck 只会告诉你哪里有问题，而 Rash 能理解你代码的意图，并自动将其重写为安全、确定性和幂等的代码。

📦 安装指南

# 从 crates.io 安装（推荐）
cargo install bashrs

# 或者从源代码安装
git clone https://github.com/paiml/bashrs
cd bashrs
cargo install --path rash

💻 使用示例

基础用法

// 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);
    }
}

转换为安全的 POSIX shell 脚本：

$ bashrs build install.rs -o install.sh

高级用法

# 状态机测试
bashrs playbook install.playbook.yaml --run

# 变异测试（目标：杀死率 >90%）
bashrs mutate script.sh --count 10

# 确定性模拟回放
bashrs simulate script.sh --seed 42 --verify

📚 详细文档

《Rash 手册》 是所有文档的权威来源：

→ 阅读《Rash 手册》

快速链接：

• 入门指南
• 快速入门教程
• 代码检查规则
• 配置管理
• API 参考

为什么选择手册？

• ✅ 所有示例都经过自动测试
• ✅ 始终与最新版本保持同步
• ✅ 全面覆盖所有功能
• ✅ 提供真实世界的示例和教程

🔧 技术细节

核心命令

# 将 Rust 代码转换为 shell 脚本
bashrs build input.rs -o output.sh

# 净化传统的 bash 脚本
bashrs purify messy.sh -o clean.sh

# 交互式 REPL 并支持调试
bashrs repl

# 对 shell 脚本进行代码检查（包括 Dockerfile）
bashrs lint script.sh

# 测试 bash 脚本
bashrs test script.sh

# 质量评分
bashrs score script.sh

# 全面审计
bashrs audit script.sh

高级测试

Rash 集成了 Probar 以进行全面的质量保证：

# 使用剧本进行状态机测试
bashrs playbook install.playbook.yaml --run

# 变异测试（目标：杀死率 >90%）
bashrs mutate script.sh --count 10

# 确定性模拟回放
bashrs simulate script.sh --seed 42 --verify

变异操作符：Rash 应用了 10 种变异操作符，包括字符串变异、命令替换、条件反转和重定向修改，以验证测试质量。

证伪测试（波普尔方法论）

Rash 使用波普尔证伪法 —— 测试尝试证伪功能，而不是证明其有效：

# 运行 130 点的转换器证伪检查清单
cargo test -p bashrs --test transpiler_tcode_tests

# 运行 30 点的 Dockerfile 证伪检查清单
cargo test -p bashrs --test dockerfile_dcode_tests

测试通过意味着证伪尝试失败 —— 该功能正常工作。

性能

Rash 旨在实现快速转换：

• Rust 到 shell：转换时间为 21.1µs
• Makefile 解析：0.034 - 1.43ms（比目标快 70 - 320 倍）
• 内存使用：大多数脚本的内存使用 <10MB

MCP 服务器

Rash 提供了一个模型上下文协议（MCP）服务器，用于 AI 辅助的 shell 脚本生成：

# 安装 MCP 服务器
cargo install rash-mcp

# 运行服务器
rash-mcp

可在官方 MCP 注册表中找到，名称为 io.github.paiml/rash。

📄 许可证

本项目采用 MIT 许可证。详情请见 LICENSE。