vmsan

🔥 مجموعة أدوات حماية Firecracker microVM

أنشئ وأدر واتصل بالـ microVMs المعزولة من Firecracker عبر سطر الأوامر. قم بتشغيل VM محمية في ميلي ثانية، نفذ الأوامر، انقل الملفات — لا حاجة لـ SSH.

📚 اقرأ الوثائق الكاملة على vmsan.dev

✨ الميزات

• ⚡ إقلاع بالميلي ثانية — تبدأ microVMs من Firecracker في أقل من 200 مللي ثانية
• 🔒 عزل أمني — jailer, seccomp, cgroups, ومساحات أسماء شبكة لكل VM
• 🖥️ قشرة تفاعلية — PTY عبر WebSocket مع دعم طرفية كامل
• 📂 نقل الملفات — رفع وتنزيل بدون SSH
• 🐳 صور Docker — بناء rootfs من أي صورة OCI باستخدام --from-image
• 🏃 تنفيذ الأوامر — تشغيل الأوامر مع إخراج متدفق، حقن متغيرات البيئة، و sudo
• 🧩 بيئات تشغيل متعددة — base, node22, node24, python3.13
• 📸 لقطات VM — حفظ واستعادة حالة VM
• 📊 مخرجات JSON — علامة --json للبرمجة النصية والأتمتة

📋 المتطلبات الأساسية

• لينكس (x86_64 أو aarch64) مع دعم KVM
• صلاحيات الجذر/sudo (مطلوبة لتوصيل جهاز TAP و jailer)
• Docker (للتثبيت من المصدر، إعادة بناء بيئات التشغيل محلياً، و --from-image)

🚀 التثبيت

curl -fsSL https://vmsan.dev/install | bash

يقوم هذا بتنزيل وتثبيت كل شيء في ~/.vmsan/:

• Firecracker + Jailer (أحدث إصدار)
• نواة لينكس (vmlinux 6.1)
• rootfs لأوبونتو 24.04 (محولة من squashfs إلى ext4)
• CLI لـ vmsan + الوكيل داخل VM
• صور بيئات التشغيل (node22, node24, python3.13) تُنزل كقطع أثرية مبنية مسبقاً

تثبيتات الإصدار القياسي تقوم بتنزيل بيئات التشغيل المضمنة من https://artifacts.vmsan.dev/ ولا تتطلب Docker. تثبيتات المصدر لا تزال تبني بيئات التشغيل محلياً.

curl -fsSL https://vmsan.dev/install | bash -s -- --uninstall

# Install dependencies
bun install

# Build the in-VM agent
cd agent && make install && cd ..

# Build the CLI
bun run build

# Link local build
mkdir -p ~/.vmsan/bin
ln -sf "$(pwd)/dist/bin/cli.mjs" ~/.vmsan/bin/vmsan

📖 الاستخدام

# Create and start a VM
vmsan create --runtime node22 --memory 512 --cpus 2

# Create a VM from a Docker image
vmsan create --from-image node:22-alpine

# List all VMs
vmsan list

# Execute a command inside a VM
vmsan exec <vm-id> ls -la

# Interactive exec with PTY
vmsan exec -i <vm-id> bash

# Connect to a running VM shell
vmsan connect <vm-id>

# Upload a file to a VM
vmsan upload <vm-id> ./local-file.txt /remote/path/file.txt

# Download a file from a VM
vmsan download <vm-id> /remote/path/file.txt ./local-file.txt

# Snapshot a running VM
vmsan snapshot create <vm-id>

# List snapshots
vmsan snapshot list

# Restore a VM from a snapshot
vmsan create --snapshot <snapshot-id>

# Stop a VM
vmsan stop <vm-id>

# Remove a VM
vmsan remove <vm-id>

الأعلام العالمية

الأوامر

⚠️ القيود المعروفة

• لا يوجد شبكات بين VMs (مخطط للإصدار 0.4.0)
• لا يوجد إعداد تصريحي / vmsan.toml (مخطط للإصدار 0.5.0)
• لا دعم لعدة مضيفين (مخطط للإصدار 0.7.0)
• يستخدم nftables مع تطبيق قاعدة ذري لعزل الشبكة (منذ 0.2.0)
• لا يوجد تصفية DNS أو SNI (مخطط للإصدار 0.3.0)
• ICMP محظور افتراضياً من VMs (يمنع نفق ICMP)
• UDP محظور افتراضياً باستثناء DNS (يمنع تسريب UDP؛ لن يعمل QUIC/HTTP3)
• NTP (UDP 123) محظور — يستخدم kvm-clock لمزامنة الوقت، قد تنحرف VMs طويلة التشغيل
• جدار الحماية للمضيف (ufw/firewalld) قد يحتاج إلى قواعد سماح صريحة لحركة مرور vmsan
• لينكس فقط — يتطلب دعم KVM
• المنصة الرئيسية: أوبونتو 24.04 LTS

🛠️ التطوير

# Build
bun run build

# Link local build
ln -sf "$(pwd)/dist/bin/cli.mjs" ~/.vmsan/bin/vmsan

# Dev mode (watch)
bun run dev

# Run tests
bun run test

# Type check
bun run typecheck

# Lint & format
bun run lint
bun run fmt

🏗️ الهندسة المعمارية

bin/            CLI entry point
src/
  commands/     CLI subcommands
  services/     Firecracker client, agent client, VM service
  lib/          Utilities (jailer, networking, shell, logging)
  errors/       Typed error system
  generated/    Firecracker API type definitions
agent/          Go agent that runs inside the VM
docs/           Documentation site (vmsan.dev)

كيف يعمل

1. vmsan يستخدم Firecracker لإنشاء microVMs خفيفة الوزن مع jailer للعزل الأمني
2. كل VM يحصل على جهاز شبكة TAP مع شبكة فرعية /30 خاصة به (198.19.{slot}.0/30)
3. وكيل مبني على Go يعمل داخل VM، ويعرض واجهة HTTP API لتنفيذ الأوامر وعمليات الملفات والوصول إلى القشرة
4. يتواصل CLI مع الوكيل عبر شبكة المضيف-الضيف

يتم تخزين الحالة في ~/.vmsan/:

~/.vmsan/
  vms/          VM state files (JSON)
  jailer/       Chroot directories
  bin/          Agent binary
  kernels/      VM kernel images
  rootfs/       Base root filesystems
  registry/     Docker image rootfs cache
  snapshots/    VM snapshots

⚖️ مقارنة vmsan مع الآخرين

لماذا vmsan؟ Docker يشارك نواة المضيف — الهروب من الحاوية يعني نهاية اللعبة. gVisor يعترض استدعاءات النظام في مساحة المستخدم، مما يقلل من سطح الهجوم لكن لا يلغيه. Kata Containers توفر عزل VM حقيقي لكنها تتطلب تنسيقاً معقداً (containerd, shimv2, K8s). Vagrant يقوم بتشغيل VMs كاملة تستغرق 30+ ثانية ومئات الميغابايت.

vmsan يمنحك عزل على مستوى العتاد مع سطح هجوم ضئيل Firecracker (أقل من 50 ألف سطر من الكود)، يقلع في ميلي ثانية، ولا يتطلب أي تكوين — ثبته وابدأ.

📄 الترخيص

Apache-2.0

نُشر بموجب ترخيص APACHE-2.0. من صنع @angelorc والمجتمع 💛

🤖 تم التحديث تلقائياً باستخدام automd