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。