agentsh

ملاحظة لنظام macOS: تطبيق الإجراءات الأمنية الأصلي عبر ESF (إطار الأمان للنقاط الطرفية) + NE (توسعة الشبكة) هو في مرحلة ألفا. يعمل بشكل متكامل - تتدفق أحداث الملفات والعمليات والشبكة من توسعة النظام إلى محرك سياسات Go - ولكن توقع حواف خشنة وتغييرات متقطعة بين الإصدارات. للاستخدام الإنتاجي اليوم، نوصي بنظام Linux.

ملاحظة لنظام Windows: نعمل على توقيع برامج تشغيل minifilter. حتى ذلك الحين، فقط وضع Windows WSL2 مدعوم بالكامل للاستخدام الإنتاجي.

بوابة تنفيذ آمنة ومدعومة بالسياسات لعملاء الذكاء الاصطناعي.

يجلس agentsh تحت وكيلك/أدواتك - معترضًا أنشطة الملفات والشبكة والعمليات والإشارات (بما في ذلك أشجار العمليات الفرعية)، مفعلًا السياسات التي تحددها، وباعثًا أحداث تدقيق مهيكلة.

ملاحظة حول المنصات: يوفر Linux تطبيقًا كاملاً (درجة أمان 100%). نظام macOS ESF+NE (درجة 90%) في مرحلة ألفا - فعال لكنه غير جاهز للإنتاج. نظام Windows WSL2 يوفر تطبيقًا مكافئًا كاملاً لنظام Linux (درجة 100%)؛ التطبيق الأصلي لنظام Windows عبر برنامج تشغيل minifilter + AppContainer (درجة 85%) في انتظار توقيع برنامج التشغيل. راجع مصفوفة مقارنة المنصات للحصول على التفاصيل.

---

ما هو agentsh؟

• نقطة نهاية شيل/تنفيذ قابلة للتضمين تحول كل أمر (وعملياته الفرعية) إلى أحداث قابلة للتدقيق.
• محرك سياسات لكل عملية: allow، deny، approve (موافقة بشرية)، soft_delete، أو redirect.
• رؤية كاملة للإدخال/الإخراج:
  • فتح/قراءة/كتابة/حذف الملفات
  • اتصال الشبكة + DNS
  • بدء/إنهاء العمليات
  • نشاط PTY
  • طلبات واجهة برمجة تطبيقات LLM مع تتبع DLP والاستخدام
  • حركة مرور قاعدة بيانات من عائلة Postgres عبر db_services المعلنة
  • إرسال/حظر الإشارات (مطبقة في Linux، تدقيق في macOS/Windows)
  • استعلامات قاعدة البيانات عبر وكيل PostgreSQL المدمج — تصنيف وسياسة لكل عبارة
  • توجيه مكالمات واجهة برمجة تطبيقات HTTP الصادرة عبر الخدمات المعلنة (http_services) بقواعد لكل طريقة، لكل مسار، وتحكم بالمراجعة، وتطبيق مضيف مغلق عند الفشل
• وضعان للإخراج:
  • إخراج شيل صديق للإنسان
  • استجابات JSON مضغوطة للوكلاء/الأدوات

---

لماذا agentsh؟

سير عمل الوكيل ينفذ في النهاية كودًا عشوائيًا (pip install، make test، python script.py). ضوابط "طلب الموافقة قبل تشغيل أمر" التقليدية تتوقف عند حدود الأداة ولا تستطيع رؤية ما يحدث داخل ذلك الأمر.

يفرض agentsh السياسة في وقت التشغيل، لذا فإن العمل المخفي الذي تقوم به العمليات الفرعية يظل محكومًا ومسجلًا، وعند الحاجة، مرخصًا.

---

الحجب الهادف: deny ← redirect (القوة الفائقة للتوجيه)

معظم الأنظمة يمكنها منع (deny) إجراء. يمكن لـ agentsh أيضًا توجيهه (redirect).

هذا يعني أنه عندما يحاول الوكيل النهج الخاطئ (أو حلول بديلة بقوة غاشمة)، يمكن للسياسة توجيهه إلى المسار الصحيح عن طريق تبديل الأمر وإرجاع إرشادات - مما يبقي الوكيل على الطريق المعبد ويقلل من إعادة المحاولات المهدرة.

مثال: توجيه curl إلى غلاف خاضع للتدقيق```yaml command_rules:

• name: redirect-curl commands: [curl, wget] decision: redirect message: "Downloads routed through audited fetch" redirect_to: command: agentsh-fetch args: ["--audit"]

**مثال: إعادة توجيه الكتابات خارج مساحة العمل إلى الداخل**```yaml
file_rules:
  - name: redirect-outside-writes
    paths: ["/home/**", "/tmp/**"]
    operations: [write, create]
    decision: redirect
    redirect_to: "/workspace/.scratch"
    message: "Writes outside workspace redirected to /workspace/.scratch"

يرى الوكيل عملية ناجحة (وليس خطأ)، لكنك تتحكم في أين تهبط الأشياء بالفعل.

---

الحاويات + agentsh: أفضل معًا

الحاويات تعزل سطح المضيف؛ agentsh يضيف رؤية وسياسة في وقت التشغيل داخل الحاوية.

• تدقيق لكل عملية (ملفات، شبكة، أوامر) يظهر ما حدث أثناء التثبيت/البناء/الاختبارات.
• الموافقات والقواعد تستمر عبر الأصداف طويلة العمر وأشجار العمليات الفرعية—وليس فقط الأمر الأول.
• تحكم على مستوى المسار في مساحات العمل/الذاكرة المؤقتة/بيانات الاعتماد المثبتة؛ الحاويات لا توفر هذه الدقة بشكل أصلي.
• نفس السلوك على المضيف وداخل الحاويات، لذلك يرى CI والتطوير المحلي نفس نتائج السياسة.

---

بداية سريعة

التثبيت

macOS (Homebrew)```bash brew tap canyonroad/tap brew install --cask agentsh

يقوم هذا بتثبيت حزمة تطبيق AgentSH مع امتداد النظام ESF+NE. بعد التثبيت، ستُطلب منك الموافقة على امتداد النظام في **System Settings > General > Login Items & Extensions**.

**Linux (من إصدار GitHub)**

قم بتنزيل ملف `.deb` أو `.rpm` أو `.apk` الخاص بمنصتك من [صفحة الإصدارات](https://github.com/erans/agentsh/releases).```bash
# Example for Debian/Ubuntu
sudo dpkg -i agentsh_<VERSION>_linux_amd64.deb

من المصدر (Linux)```bash make build sudo install -m 0755 bin/agentsh bin/agentsh-shell-shim /usr/local/bin

**من المصدر (macOS)**```bash
# ESF+NE mode (full enforcement — Alpha, requires Xcode 15+)
make build-macos-enterprise

راجع دليل بناء macOS للحصول على تعليمات مفصلة لبناء macOS.

---

التشغيل محلياً```bash

Start the server (optional if using autostart)

./bin/agentsh server --config configs/server-config.yaml

Create a session and run a command (shell output)

SID=$(./bin/agentsh session create --workspace . --json | jq -r .id) ./bin/agentsh exec "$SID" -- ls -la

Structured output for agents

./bin/agentsh exec --output json --events summary "$SID" -- curl https://example.com

---

### التحقق من ما يتم فرضه

يقوم `agentsh detect` بفحص المضيف والإبلاغ عن بدائل الفرض المتاحة فعليًا — seccomp، Landlock، FUSE، eBPF، ptrace، cgroups — مجمعة في درجات حماية لكل مجال بالإضافة إلى وضع الأمان المحدد. على المضيفين المقيدين (فئة Daytona، E2B، Firecracker) حيث لا يمكن تثبيت مستمع إشعار المستخدم الخاص بـ seccomp، فإنه يبلغ عن الوضع الذي سيتم فرضه *فعليًا* بدلاً من ما يدعمه النواة فقط.```bash
agentsh detect              # human-readable protection report
agentsh detect config       # emit a config tuned for this host

انظر أوضاع الأمان للحصول على مصفوفة الأوضاع وعناصر الضبط.

---

أخبر وكيلك باستخدامه (مقتطف AGENTS.md / CLAUDE.md)```md

Shell access

• Run commands via agentsh, not directly in bash/zsh.
• Use: agentsh exec $SID -- <your-command-here>
• For structured output: agentsh exec --output json --events summary $SID -- <your-command-here>
• Get session ID first: SID=$(agentsh session create --workspace . --json | jq -r .id)

---

### التشغيل التلقائي (بدون خطوة الخادم اليدوية)

أنت **لا** تحتاج إلى تشغيل `agentsh server` بنفسك.

* أول أمر `agentsh exec` (أو أي `/bin/sh`/`/bin/bash` مُحاكى) سيقوم تلقائيًا بتشغيل خادم محلي باستخدام `configs/server-config.yaml` (أو `AGENTSH_CONFIG` إذا تم تعيينه).
* هذا الخادم يحافظ على طبقة FUSE ومحرك السياسات طوال عمر الجلسة؛ الأوامر اللاحقة تعيد استخدامه.
* قم بتعيين `AGENTSH_NO_AUTO=1` إذا كنت ترغب في إدارة دورة حياة الخادم يدويًا.

---

## الاستخدام في Docker (مع محاكي الصدفة)

انظر إلى `Dockerfile.example` للحصول على صورة مبنية على دبيان بسيطة.

داخل الصورة، قم بتثبيت حزمة إصدار (أو انسخ بنيتك)، ثم فعّل المحاكي:```bash
agentsh shim install-shell \
  --root / \
  --shim /usr/bin/agentsh-shell-shim \
  --bash \
  --i-understand-this-modifies-the-host

وجه الشيم إلى الخادم الخاص بك (السايدكار أو المضيف):```dockerfile ENV AGENTSH_SERVER=http://127.0.0.1:18080

### فرض عدم التفاعل

بشكل افتراضي، يتجاوز shim السياسة عندما لا يكون stdin طرفية (TTY) (مع الحفاظ على البيانات الثنائية للأوامر المنقولة عبر الأنابيب). على المنصات التي تكون فيها الأوامر دائمًا غير تفاعلية ولكنها لا تزال بحاجة إلى فرض السياسة (مثل exe.dev، واجهات برمجة تطبيقات الحماية sandbox APIs)، أضف `--force`:```bash
agentsh shim install-shell \
  --root / \
  --shim /usr/bin/agentsh-shell-shim \
  --bash \
  --force \
  --i-understand-this-modifies-the-host

يقوم هذا بكتابة ملف /etc/agentsh/shim.conf مع force=true، والذي يقرأه الشيم (shim) عند بدء التشغيل. يعمل ملف التهيئة بغض النظر عن كيفية استدعاء الصدفة (على عكس متغيرات البيئة أو نصوص الإعدادات). يحقق AGENTSH_SHIM_FORCE=1 في بيئة العملية نفس التأثير لكل عملية.