‏BashBox: مفسر bash با PHP خالص برای اسکریپت‌های ایجنت‌ها

BashBox یه مفسر bash هست که Pushpak Chhajed کامل با PHP نوشته. هدفش اجرای اسکریپت‌هاییه که ایجنت‌های هوش مصنوعی می‌سازن، بدون اینکه از proc_open، exec یا shell_exec استفاده کنه. هر دستور یه کلاس PHP هست که روی یه فایل‌سیستم مجازی کار می‌کنه و هر اجرا زیر محدودیت‌هایی هست که خودت تنظیم می‌کنی. یعنی ایجنت هر اسکریپتی بنویسه، به سیستم‌عامل واقعی سرور دسترسی نداره.

کار باهاش ساده‌ست: یه نمونه از Bash می‌سازی و اسکریپت رو به exec() می‌دی. نتیجه شامل خروجی و exit code هست:

$bash = new Bash;

$result = $bash->exec('
    NAME="BashBox"
    echo "Hello, $NAME" | tr a-z A-Z
');

$result->stdout;   // "HELLO, BASHBOX\n"

مفسر از pipe، هدایت خروجی مثل 2>&1، here-doc، آرایه، تابع، کنترل جریان و parameter expansion پشتیبانی می‌کنه. ۵۸ دستور داره، از جمله grep، sed، sort، find و xargs، ولی هیچ باینری sh یا bash واقعی‌ای صدا زده نمی‌شه. اگه اسکریپت خطای syntax داشته باشه، به‌جای exception همون پیام خطای bash با exit code برابر ۲ برمی‌گرده.

فایل‌سیستم پیش‌فرض InMemoryFs هست که اصلاً به دیسک دست نمی‌زنه. سه backend دیگه هم هست: OverlayFs که از یه پوشهٔ واقعی می‌خونه ولی نوشتن‌ها رو تو حافظه نگه می‌داره، ReadWriteFs که داخل یه پوشهٔ ریشهٔ مشخص روی دیسک می‌نویسه، و MountableFs که می‌تونی backendهای مختلف رو روی مسیرهای مختلف mount کنی. هر backend به‌طور پیش‌فرض ۶۴ مگ و ۱۰ هزار فایل سهمیه داره. path traversal و null-byte injection هم مسدودن.

کلاس Limits هجده تنظیم داره، از تعداد دستورها و تکرار حلقه‌ها تا عمق فراخوانی. اگه از یکیشون رد بشی، ExecutionLimitException پرتاب می‌شه:

$bash = new Bash(new BashOptions(
    limits: new Limits(
        maxCommandCount: 100,
        maxLoopIterations: 500,
        maxCallDepth: 10,
    ),
));

شبکه به‌طور پیش‌فرض خاموشه و دستور curl تا وقتی NetworkConfig ندی اصلاً وجود نداره. با allowedUrlPrefixes مشخص می‌کنی کدوم آدرس‌ها مجازن و denyPrivateRanges که پیش‌فرض روشنه، آدرس‌های داخلی و loopback رو رد می‌کنه. هدرهای Authorization و Cookie هم وقتی درخواست به یه دامنهٔ دیگه منتقل بشه حذف می‌شن. برای دستورهای جدید هم کافیه از AbstractCommand ارث‌بری کنی. BashBox به PHP 8.4 یا بالاتر نیاز داره، وابستگی دیگه‌ای نداره و با Laravel AI SDK هم کار می‌کنه.

نکات کلیدی:

• BashBox از proc_open، exec و shell_exec استفاده نمی‌کنه و هر دستور یه کلاس PHP هست.
• ۵۸ دستور داخلی داره و خطای syntax با exit code برابر ۲ برمی‌گرده، نه exception.
• پیش‌فرض‌ها: ۱۰ هزار دستور در هر اسکریپت، ۱۰ هزار تکرار حلقه، ۱۰ مگ خروجی و سهمیهٔ دیسک ۶۴ مگ.
• شبکه پیش‌فرض خاموشه و آدرس‌های خصوصی با denyPrivateRanges رد می‌شن.
• به PHP 8.4 نیاز داره، لایسنسش MIT هست و آخرین نسخه‌ش v0.0.3 هست.