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 في بيئة العملية نفس التأثير لكل عملية.

النمط الموصى به: تشغيل agentsh كـ sidecar (أو PID 1) في نفس الـ pod/service ومشاركة مساحة عمل حجمية؛ يضمن الشيم أن كل قفزة صدفة تبقى تحت السياسة.

نموذج السياسة

القرارات

allow (السماح)
deny (الرفض)
approve (موافقة بشرية)
redirect (استبدال أمر)
audit (سماح + تسجيل)
soft_delete (حذف مشروط مع إمكانية الاسترجاع)

النطاقات

عمليات الملفات
الأوامر
متغيرات البيئة
الشبكة (DNS/اتصال)
قاعدة البيانات (جمل SQL عبر وكيل PostgreSQL)
إعدادات PTY/الجلسة
خدمات HTTP المُعلنة

التقييم

القاعدة المطابقة الأولى هي الفائزة

القواعد موجودة في سياسة مسماة؛ تختار الجلسات سياسة.

القيم الافتراضية:

نموذج التهيئة: configs/server-config.yaml
السياسة الافتراضية: configs/policies/default.yaml
تجاوز عبر متغير البيئة: تعيين AGENTSH_POLICY_NAME إلى اسم سياسة مسموح بها (بدون لاحقة). إذا كان غير مضبوط/غير صالح/غير مسموح، يتم استخدام الافتراضي.
سياسة البيئة: قم بتكوين policies.env_policy (السماح/الرفض، max_bytes، max_keys، block_iteration) وتجاوزات env_* لكل أمر في ملفات السياسة. قائمة السماح الفارغة تضع افتراضيًا PATH/LANG/TERM/HOME مع قائمة منع مدمجة للأسرار؛ قم بتعيين block_iteration لإخفاء تعداد البيئة (يتطلب env shim).
قائمة السماح: قم بتكوين policies.allowed في config.yml؛ الفارغ يعني أن الافتراضي فقط مسموح به.
التكامل الاختياري: قم بتعيين policies.manifest_path إلى بيان SHA256 للتحقق من ملفات السياسة عند التحميل.

مرجع سريع لسياسة البيئة

الإعدادات الافتراضية: في حالة عدم وجود env_allow، يقوم agentsh ببناء بيئة مصغرة (PATH/LANG/TERM/HOME) ويجرد المفاتيح السرية المضمنة.
التجاوزات: env_allow/env_deny لكل أمر بالإضافة إلى env_max_keys/env_max_bytes للحد من بيئة الطفل وتصفيتها عند وقت التنفيذ.
حظر التعداد: env_block_iteration: true (عالمي أو لكل قاعدة) يخفي تعداد البيئة؛ قم بتعيين policies.env_shim_path إلى libenvshim.so لكي يقوم agentsh بحقن LD_PRELOAD + AGENTSH_ENV_BLOCK_ITERATION=1.
الحدود: أخطاء إذا تم تجاوز الحدود; يتم تطبيق منشئ البيئة قبل التنفيذ لكل أمر.
env_inject: متغيرات بيئة موثوقة من المشغل يتم حقنها في جميع الأوامر، متجاوزة تصفية السياسة. الاستخدام الأساسي: BASH_ENV لتعطيل أوامر الصدفة المضمنة التي تتجاوز seccomp. قم بتكوينها في sandbox.env_inject (عالمي) أو على مستوى السياسة (يتجاوز العالمي).

أمثلة على القواعد (مختصرة)```yaml

version: 1 name: default

file_rules:

name: allow-workspace paths: ["/workspace", "/workspace/**"] operations: [read, open, stat, list, write, create, mkdir, chmod, rename] decision: allow
name: approve-workspace-delete paths: ["/workspace", "/workspace/**"] operations: [delete, rmdir] decision: approve message: "Delete {{.Path}}?" timeout: 5m
name: deny-ssh-keys paths: ["/home//.ssh/", "/root/.ssh/**"] operations: ["*"] decision: deny

network_rules:

name: allow-api domains: ["api.example.com"] ports: [443] decision: allow

command_rules:

name: block-dangerous commands: ["rm", "shutdown", "reboot"] decision: deny

---

### استخدام سياسة```bash
# Start the server with your policy
./bin/agentsh server --config configs/server-config.yaml

# Create a session pinned to a policy
SID=$(./bin/agentsh session create --workspace /workspace --policy default --json | jq -r .id)

# Exec commands; responses include decision + guidance when blocked/approved
./bin/agentsh exec "$SID" -- rm -rf /workspace/tmp

المصادقة

يدعم agentsh عدة طرق للمصادقة:

النوع	حالة الاستخدام
`api_key`	نشر بسيط بمفاتيح ثابتة
`oidc`	SSO للمؤسسات (Okta، Azure AD، إلخ)
`hybrid`	قبول كلتا الطريقتين

أوضاع الموافقة للتحقق البشري في الحلقة:

local_tty - مطالبة المحطة الطرفية (افتراضي)
totp - رموز تطبيق المصادقة
webauthn - مفاتيح أمان الأجهزة (YubiKey)
api - موافقة عن بعد عبر REST

انظر SECURITY.md لتفاصيل التكوين.

أمان MCP

القائمة البيضاء للأدوات: التحكم في أدوات MCP التي يمكن استدعاؤها عبر سياسات القائمة المسموح بها/المحظورة
تثبيت الإصدار: اكتشاف تغييرات تعريف الأداة (حماية السحب المفاجئ) مع استجابات قابلة للتكوين
الكشف عبر الخوادم: منع أنماط تسرب البيانات (قراءة من الخادم A ← إرسال عبر الخادم B)
تحديد المعدل: تحديد معدل سعة الرمز المميز لخوادم MCP ونطاقات الشبكة

انظر SECURITY.md لخيارات التكوين الكاملة، أو قم بتشغيل MCP Protection Demo لرؤية هذه الاكتشافات قيد التنفيذ.

عرض توضيحي لـ 60 ثانية

أسرع طريقة "لفهم الأمر" هي تشغيل شيء يقوم بتوليد عمليات فرعية ويلمس نظام الملفات/الشبكة.```bash

1) Create a session in your repo/workspace

SID=$(agentsh session create --workspace . --json | jq -r .id)

2) Run something simple (human-friendly output)

agentsh exec "$SID" -- uname -a

→ prints system info, just like normal

3) Run something that hits the network (JSON output + event summary)

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

→ JSON response includes: exit_code, stdout, and events[] showing dns_query + net_connect

4) Trigger a policy decision - try to delete something

agentsh exec "$SID" -- rm -rf ./tmp

→ With default policy: prompts for approval or denies based on your rules

5) See what happened (structured audit trail)

agentsh exec --output json --events all "$SID" -- ls

→ events[] shows every file operation, even from subprocesses

**ما ستراه في مخرجات JSON:**
- `exit_code`: حالة الخروج من الأمر
- `stdout` / `stderr`: المخرجات الملتقطة
- `events[]`: كل عملية ملف/شبكة/معالجة مع قرارات السياسة
- `policy.decision`: `allow`، `deny`، `approve`، أو `redirect`

نصيحة: احتفظ بمحطة طرفية مع `--output json` مفتوحة عند اختبار السياسات—فذلك يوضح ما يتم لمسه.

---

### تقارير الجلسة

إنشاء تقارير ماركدون تلخص نشاط الجلسة:```bash
# Quick summary
agentsh report latest --level=summary

# Detailed investigation
agentsh report <session-id> --level=detailed --output=report.md

التقارير تتضمن:

ملخص القرار (مسموح، محظور، معاد توجيهه)
كشف النتائج التلقائي (انتهاكات، حالات شاذة)
تحليل النشاط حسب الفئة
الجدول الزمني الكامل للأحداث (الوضع المفصل)

انظر دليل التكامل CI/CD للحصول على أمثلة خطوط الأنابيب.

نقاط تفتيش مساحة العمل

إنشاء لقطات لحالة مساحة العمل للاستعادة من العمليات التدميرية:```bash

Create a checkpoint before risky operations

agentsh checkpoint create --session $SID --workspace /workspace --reason "before cleanup"

List checkpoints for a session

agentsh checkpoint list --session $SID

Show what changed since a checkpoint

agentsh checkpoint show --session $SID --workspace /workspace --diff

Preview what rollback would restore (dry-run)

agentsh checkpoint rollback --session $SID --workspace /workspace --dry-run

Restore workspace to checkpoint state

agentsh checkpoint rollback --session $SID --workspace /workspace

Clean up old checkpoints

agentsh checkpoint purge --session $SID --older-than 24h --keep 5

**نقطة التحقق التلقائي:** عند التمكين، يقوم agentsh بإنشاء نقاط تحقق تلقائيًا قبل الأوامر الخطرة (`rm`, `mv`, `git reset`, `git checkout`, إلخ). قم بالتكوين في `sessions.checkpoints.auto_checkpoint`.

راجع [SECURITY.md](https://github.com/canyonroad/agentsh/blob/main/SECURITY.md#checkpoint-and-rollback) للحصول على خيارات التكوين الكاملة.

---

### وكيل LLM وDLP

يتضمن agentsh وكيلًا مضمنًا يعترض جميع طلبات واجهة برمجة تطبيقات LLM من الوكلاء:```bash
# Check proxy status for a session
agentsh proxy status <session-id>

# View LLM-specific events
agentsh session logs <session-id> --type=llm

الميزات:

التوجيه التلقائي: يضبط ANTHROPIC_BASE_URL و OPENAI_BASE_URL بحيث يتم توجيه وكلاء SDK عبر الوكيل
مزودون مخصصون: التوجيه إلى LiteLLM، Azure OpenAI، vLLM، أو بوابات الشركات
تنقيح DLP: يتم تنقيح المعلومات الشخصية (البريد الإلكتروني، أرقام الهواتف، مفاتيح API، إلخ) قبل الوصول إلى مزودي LLM
أنماط مخصصة: تحديد أنماط خاصة بالمؤسسة للبيانات الحساسة
تتبع الاستخدام: استخراج عدد الرموز وتسجيلها لإسناد التكلفة
مسار التدقيق: تسجيل جميع الطلبات/الاستجابات في تخزين الجلسة

تكوين المزود:```yaml proxy: mode: embedded providers: anthropic: https://api.anthropic.com # Default Anthropic API openai: https://api.openai.com # Default OpenAI API

# Or use alternative providers:
# openai: http://localhost:8000         # LiteLLM / vLLM
# openai: https://your-resource.openai.azure.com  # Azure OpenAI
# anthropic: https://llm.corp.example.com         # Corporate gateway

**تكوين DLP:**```yaml
dlp:
  mode: redact
  patterns:
    email: true
    api_keys: true
  custom_patterns:
    - name: customer_id
      display: identifier
      regex: "CUST-[0-9]{8}"

انظر وثائق وكيل LLM للحصول على خيارات التكوين الكاملة.

يقوم نفس الوكيل أيضًا بتوزيع إدخالات http_services المُصرَّح بها — واجهات API المُسماة مع قواعد لكل طريقة ولكل مسار. انظر خدمات HTTP المُصرَّح بها وكتاب طبخ خدمات HTTP لمزيد من التفاصيل.

التحكم في الوصول إلى قاعدة البيانات (Postgres فقط حاليًا)

يمكن لـ agentsh تطبيق السياسات على خدمات قاعدة البيانات المُصرَّح بها من خلال db_services وdatabase_connection_rules وdatabase_rules. التنفيذ الحالي مخصص لعائلة Postgres فقط: PostgreSQL هو الهدف المدعوم، مع استخدام Aurora Postgres لنفس المسار، ومعاملة Redshift/CockroachDB كلهجات متوافقة مع Postgres بتغطية تجريبية. MySQL وMongoDB وSnowflake وBigQuery وDatabricks وClickHouse وMSSQL وCassandra وRedis وOracle هي بنود في خارطة الطريق، وليست دعمًا جاريًا في وقت التشغيل.

يتضمن دعم Postgres الحالي ما يلي:

قرارات السماح/الرفض/الموافقة/التدقيق للاتصالات.
تصنيف العبارات لبروتوكول PostgreSQL السلكي v3، بما في ذلك Simple Query وExtended Query وعبارات SQL المُعدَّة وCOPY ومنع FunctionCall وحالة المعاملة ورسم خرائط CancelRequest.
تغطية سياسة صارمة لكل كائن مع أولوية الرفض.
محددات علاقة/دالة مدعومة بالفهرس للسياسات ذات الكائنات المُحَلَّلة.
إعادة توجيه آمنة في وقت التشغيل عبر redirect لاستبدال علاقة Postgres للقراءة فقط.
كشف الالتفاف وتغطية اختبارات E2E Docker الحقيقية لـ Postgres في CI.

زمن تشغيل وكيل Postgres هو كود داخلي حاليًا يعمل على Linux فقط. استخدم Linux الأصلي أو WSL2 أو بيئة VM Linux لفرض قاعدة البيانات.

انظر التحكم في الوصول إلى قاعدة البيانات ووثائق السياسات.

توليد السياسات

توليد سياسات مقيدة من سلوك الجلسة الملاحظ (سير عمل "profile-then-lock"):```bash

Generate policy from latest session

agentsh policy generate latest --output=ci-policy.yaml

Generate with custom name and threshold

agentsh policy generate abc123 --name=production-build --threshold=10

Quick preview to stdout

agentsh policy generate latest

السياسة المُنشأة:
- تسمح فقط بالعمليات التي تمت ملاحظتها خلال الجلسة
- تجمع المسارات في أنماط glob عندما يكون هناك العديد من الملفات في نفس الدليل
- تقلص المجالات الفرعية إلى أحرف بدل (مثل `*.github.com`)
- تضع علامات على الأوامر الخطرة (curl, wget, rm) بأنماط الوسائط
- تتضمن العمليات المحظورة كقواعد معلقة للمراجعة

**حالات الاستخدام:**
- **تقييد CI/CD**: إنشاء ملف تعريف لتشغيل بناء/اختبار، وقفل التشغيلات المستقبلية على هذا السلوك
- **صندوق حماية الوكيل**: السماح لوكيل ذكاء اصطناعي بتشغيل مهمة، وإنشاء سياسة للتشغيلات المستقبلية
- **توصيف الحاويات**: إنشاء ملف تعريف لعبء العمل، وإنشاء سياسة دنيا للإنتاج

---

## الوصول إلى قاعدة البيانات (PostgreSQL)

يتضمن agentsh **وكيل PostgreSQL** مضمنًا يجعل الوصول إلى قاعدة البيانات مدركًا للوكيل وخاضعًا للسياسة. يتحدث بروتوكول سلك Postgres، ويصنف كل عبارة إلى قائمة من *التأثيرات* (قراءات، كتابات، DDL، DCL، التحكم في المعاملات/الجلسات، `COPY`/تصدير جماعي، …)، ويقيم كل تأثير مقابل `database_rules` قبل إعادة التوجيه إلى الأعلى — لذلك يتم التعامل مع `UPDATE` أو `DROP` أو `DELETE` غير المحدد بنفس طريقة كتابة ملف أو اتصال شبكة.

- **تقييم لكل تأثير وكائنات متعددة** — القواعد هي جمع الكل / **أي رفض يفوز** (الفعل الأكثر تقييدًا هو الذي يقرر)، وليس أول تطابق.
- **القرارات:** `allow`, `deny`, `approve` (موافقة بشرية), `audit`, و `redirect` على مستوى العبارة.
- **حارس `require_where`** — رفض `UPDATE`/`DELETE` على المستوى الأعلى التي تفتقر إلى شرط `WHERE`.
- **قواعد مستوى الاتصال** (`database_connection_rules`) تتحكم في الجلسات التي قد تصل إلى `db_service` المعلن.
- **أحداث تدقيق المصادقة + العبارات** لكل اتصال واستعلام؛ تسجيل نص العبارة قابل للتكوين (`policies.db.log_statements: none | parameters_redacted | full`).

تغطي المرحلة 1 بروتوكول سلك PostgreSQL v3 (لهجات: `postgres`, `aurora_postgres`; `redshift` / `cockroachdb` في مرحلة تجريبية). اتصالات النسخ المتماثل والمشفر بـ GSSAPI تكون مرفوضة افتراضيًا.```yaml
database_rules:
  # normal reads + updates on the declared service
  - name: app-read-and-update
    db_service: appdb
    operations: [READ, UPDATE]
    decision: allow

  # allow UPDATE/DELETE only when scoped by a WHERE clause
  - name: app-guard-unscoped-dml
    db_service: appdb
    operations: [UPDATE, DELETE]
    require_where: true
    decision: allow

  # block schema/DDL mutations; terminate the transaction on violation
  - name: app-deny-ddl
    db_service: appdb
    operations: [CREATE, DROP, ALTER, EXPORT]
    decision: deny
    deny_mode_in_tx: terminate
    message: "appdb is read+update only. Requested: {{.Operation}}"

انظر إلى مواصفات التحكم في الوصول إلى قاعدة البيانات للحصول على تصنيف العمليات الكامل، ونموذج التأثيرات، وقواعد الاتصال، ونموذج التهديدات التي لا يمكن تجنبها.

إعادة توجيه الشبكة

يمكن لـ agentsh إعادة توجيه اتصالات DNS و TCP بشفافية، مما يتيح حالات استخدام مثل توجيه استدعاءات API عبر بروكسيات الشركات أو تبديل مزودي الذكاء الاصطناعي دون تغييرات في الكود.

إعادة توجيه DNS

اعتراض حل DNS وإرجاع عناوين IP المهيأة:```yaml dns_redirect:

match: "api.anthropic.com" redirect_ip: "10.0.0.50" visibility: audit_only on_failure: fail_closed
match: ".*\.openai\.com" # Regex pattern redirect_ip: "10.0.0.51" visibility: warn

### إعادة توجيه الاتصال

إعادة توجيه اتصالات TCP إلى وجهات مختلفة مع معالجة TLS اختيارية:```yaml
connect_redirect:
  - match: "api.anthropic.com:443"
    redirect_to: "vertex-proxy.internal:8443"
    tls_mode: passthrough          # Forward encrypted traffic unchanged
    visibility: silent

  - match: "api.openai.com:443"
    redirect_to: "azure-proxy.internal:443"
    tls_mode: rewrite_sni          # Modify SNI in TLS ClientHello
    rewrite_sni: "azure-openai.example.com"
    visibility: audit_only

الخيارات

دعم المنصة

حالات الاستخدام

توجيه بوابة API: توجيه استدعاءات Anthropic/OpenAI عبر بوابة LLM الخاصة بالشركة
تبديل المزود: إعادة توجيه Claude API إلى GCP Vertex AI أو Azure OpenAI
الاختبار: إعادة توجيه واجهات برمجة التطبيقات الإنتاجية إلى خوادم وهمية
الامتثال: فرض جميع حركة مرور LLM عبر وكلاء التدقيق

تصفية الإشارات

تعترض agentsh الإشارات (kill، SIGTERM، إلخ) المرسلة بين العمليات، مما يوفر تحكمًا قائمًا على السياسة في الإشارات التي يمكن أن تصل إلى أي أهداف.

دعم المنصة

أمثلة على قواعد الإشارات```yaml

signal_rules:

Allow signals to self and children

name: allow-self signals: ["@all"] target: type: self decision: allow
name: allow-children signals: ["@all"] target: type: children decision: allow

Redirect SIGKILL to graceful SIGTERM

name: graceful-kill signals: ["SIGKILL"] target: type: children decision: redirect redirect_to: SIGTERM

Block fatal signals to external processes

name: deny-external-fatal signals: ["@fatal"] target: type: external decision: deny

### مجموعات الإشارات

- `@all` - جميع الإشارات (1-31)
- `@fatal` - SIGKILL, SIGTERM, SIGQUIT, SIGABRT
- `@job` - SIGSTOP, SIGCONT, SIGTSTP, SIGTTIN, SIGTTOU
- `@reload` - SIGHUP, SIGUSR1, SIGUSR2

### أنواع الهدف

- `self` - العملية التي ترسل إشارة لنفسها
- `children` - العمليات الفرعية المباشرة
- `descendants` - جميع العمليات المنحدرة
- `session` - أي عملية في جلسة agentsh
- `external` - معرفات العمليات خارج الجلسة
- `system` - PID 1 وخيوط النواة

انظر [وثائق السياسة](https://github.com/canyonroad/agentsh/blob/main/docs/operations/policies.md#signal-rules) للحصول على خيارات التكوين الكاملة.

---

## مراقبة الإدخال/الإخراج للملفات في macOS

في macOS، يراقب agentsh إدخال/إخراج الملفات باستخدام إطار أمان نقطة النهاية (ESF)، ويشترك في أحداث AUTH و NOTIFY. تشمل العمليات المتتبعة فتح الملف، إنشاؤه، حذفه، إعادة تسميته، كتابته (يتم اكتشافها عبر حدث close-modified)، وفي macOS 26+، chmod و chown عبر أحداث تغيير السمة. يُنسب كل حدث ملف إلى الجلسة والأمر الأصليين من خلال تحليل PID، مما يوفر سجلات تدقيق كاملة عبر أشجار العمليات الفرعية.

يوفر ESF تطبيق السماح/الرفع على مستوى النواة ولكنه لا يدعم اعتراض الملفات الشفاف مثل FUSE في Linux. إجراءات السياسة التي تتطلب اعتراضًا - مثل `redirect` (إعادة كتابة المسار) و `soft_delete` (الحجر الصحي) - يتم تنفيذها على أنها رفض + توجيه: يتم حظر العملية على مستوى ESF ويتلقى الوكيل تعليمات لإعادة المحاولة بالمسار الصحيح أو للتأكيد على أن الملف محمي. انظر [وثائق بنية ESF+NE لنظام macOS](https://github.com/canyonroad/agentsh/blob/main/docs/macos-esf-ne-architecture.md) للحصول على تفاصيل تدفق الأحداث و [وثائق السياسة](https://github.com/canyonroad/agentsh/blob/main/docs/operations/policies.md#file-rule-actions-on-macos-esf) لسلوك كل إجراء.

---

## حزم السياسات الابتدائية

لديك بالفعل سياسة افتراضية (`configs/policies/default.yaml`). حزم المبادئ هذه متاحة كملفات منفصلة حتى تتمكن الفرق من اختيار واحدة:

* **[`policies/dev-safe.yaml`](https://github.com/canyonroad/agentsh/blob/main/configs/policies/dev-safe.yaml)**: آمن للتطوير المحلي
  * السماح بالقراءة/الكتابة في مساحة العمل
  * الموافقة على الحذف في مساحة العمل
  * رفض `~/.ssh/**`, `/root/.ssh/**`
  * تقييد الشبكة بالنطاقات/المنافذ المسموح بها

* **[`policies/ci-strict.yaml`](https://github.com/canyonroad/agentsh/blob/main/configs/policies/ci-strict.yaml)**: آمن لعدّاءات CI
  * رفض أي شيء خارج مساحة العمل
  * رفض الشبكة الصادرة باستثناء سجلات القطع الأثرية
  * رفض الصدف التفاعلية إلا إذا كان مسموحًا بها صراحةً
  * تدقيق كل شيء (أحداث ملخصة)

* **[`policies/agent-sandbox.yaml`](https://github.com/canyonroad/agentsh/blob/main/configs/policies/agent-sandbox.yaml)**: وضع "تشغيل كود غير معروف من قبل الوكيل"
  * رفض افتراضي + قائمة مسموح بها صريحة
  * الموافقة على أي وصول لبيانات الاعتماد/المسار
  * إعادة توجيه استخدام أداة الشبكة إلى الوكلاء/المرايا الداخلية
  * حذف ناعم للعمليات التدميرية لسهولة الاسترداد

---

## أمثلة تكامل مساعد الذكاء الاصطناعي

مقتطفات جاهزة للاستخدام لتكوين مساعدي البرمجة بالذكاء الاصطناعي لاستخدام agentsh:

* **[Claude Code](https://github.com/canyonroad/agentsh/blob/main/examples/claude)** - مقتطف CLAUDE.md لتكامل Claude Code
* **[Cursor](https://github.com/canyonroad/agentsh/blob/main/examples/cursor)** - قواعد Cursor لتكامل agentsh
* **[AGENTS.md](https://github.com/canyonroad/agentsh/blob/main/examples/agents)** - مقتطف AGENTS.md عام (يعمل مع أدوات ذكاء اصطناعي متعددة)

> **ملاحظة:** هذه الأمثلة مخصصة لسيناريوهات التطوير المحلي حيث لا يكون تشغيل وكيل الذكاء الاصطناعي داخل حاوية عمليًا. بالنسبة لبيئات الإنتاج أو CI/CD، يُفضل تشغيل الوكلاء في حاويات مع تثبيت شل شيم - راجع [الاستخدام في Docker](#use-in-docker-with-the-shell-shim).

---

## المراجع

* **عرض توضيحي لحماية MCP:** [`agentsh-mcp-protection-demo`](https://github.com/canyonroad/agentsh-mcp-protection-demo) - عرض توضيحي مباشر لاكتشاف التسرب عبر الخوادم، ومنع سحب السجادة، وتوليد السياسات
* **نموذج الأمان والتهديدات:** [`SECURITY.md`](https://github.com/canyonroad/agentsh/blob/main/SECURITY.md) - ما يحمي منه agentsh، القيود المعروفة، قائمة مراجعة المشغل
* **KMS خارجي:** [`SECURITY.md#external-kms-integration`](https://github.com/canyonroad/agentsh/blob/main/SECURITY.md#external-kms-integration) - AWS KMS, Azure Key Vault, HashiCorp Vault, GCP Cloud KMS لمفاتيح سلامة التدقيق
* قالب التكوين: [`configs/server-config.yaml`](https://github.com/canyonroad/agentsh/blob/main/configs/server-config.yaml)
* السياسة الافتراضية: [`configs/policies/default.yaml`](https://github.com/canyonroad/agentsh/blob/main/configs/policies/default.yaml)
* مثال Dockerfile (مع shim): [`Dockerfile.example`](https://github.com/canyonroad/agentsh/blob/main/Dockerfile.example)
* **وثائق السياسة:** [`docs/operations/policies.md`](https://github.com/canyonroad/agentsh/blob/main/docs/operations/policies.md) - متغيرات السياسة، قواعد الإشارات، إعادة توجيه الشبكة
* **التحكم في الوصول إلى قاعدة البيانات:** [`docs/agentsh-db-access-spec.md`](https://github.com/canyonroad/agentsh/blob/main/docs/agentsh-db-access-spec.md) - نطاق تطبيق قاعدة البيانات Postgres فقط، دلالات السياسة، سلوك إعادة التوجيه، وخارطة الطريق
* **دليل سياسات الأوامر:** [`docs/cookbook/command-policies.md`](https://github.com/canyonroad/agentsh/blob/main/docs/cookbook/command-policies.md) - كيفية السماح بملف ثنائي جديد، ومتى تستخدم `wrap` بدلاً من `exec`، وكيفية تصحيح أخطاء الرفض
* **دليل خدمات HTTP:** [`docs/cookbook/http-services.md`](https://github.com/canyonroad/agentsh/blob/main/docs/cookbook/http-services.md) - وصفات لتوجيه مكالمات API HTTP الصادرة عبر الخدمات المعلنة مع القواعد و بوابات الموافقة
* **دليل تكاملات Sandbox SDK:** [`docs/cookbook/sandbox-sdk-integrations.md`](https://github.com/canyonroad/agentsh/blob/main/docs/cookbook/sandbox-sdk-integrations.md) - تكوين `shim_install` لـ Tensorlake / E2B / Modal / Daytona حيث يتم تشغيل الأوامر كأشقاء لخادم agentsh
* **مهارات تأليف السياسات:** [`skills/`](https://github.com/canyonroad/agentsh/blob/main/skills) - مهارات مساعد الذكاء الاصطناعي لإنشاء وتحرير السياسات في Claude Code و NanoClaw وغيرها.
* **مقارنة المنصات:** [`docs/platform-comparison.md`](https://github.com/canyonroad/agentsh/blob/main/docs/platform-comparison.md) - دعم الميزات، درجات الأمان، الأداء حسب المنصة
* **Bubblewrap مقابل agentsh:** [`docs/bubblewrap-vs-agentsh-comparison.md`](https://github.com/canyonroad/agentsh/blob/main/docs/bubblewrap-vs-agentsh-comparison.md) - مقارنة مع Bubblewrap لعزل حاويات Linux
* **التحكم في الوصول إلى قاعدة البيانات:** [`docs/agentsh-db-access-spec.md`](https://github.com/canyonroad/agentsh/blob/main/docs/agentsh-db-access-spec.md) - تصنيف وكيل PostgreSQL، نموذج التأثيرات، `database_rules`، قواعد الاتصال، نموذج التهديد
* **أنماط الأمان و `detect`:** [`docs/security-modes.md`](https://github.com/canyonroad/agentsh/blob/main/docs/security-modes.md) - أنماط التطبيق، درجة الحماية، وما يبلغ عنه `agentsh detect`
* **seccomp:** [`docs/seccomp.md`](https://github.com/canyonroad/agentsh/blob/main/docs/seccomp.md) - تصفية استدعاءات النظام، اعتراض execve، وحجب عائلة المقبس
* **وضع ptrace:** [`docs/ptrace-support.md`](https://github.com/canyonroad/agentsh/blob/main/docs/ptrace-support.md) - تطبيق PTRACE_SEIZE للحاويات المقيدة (`attach_mode`, مرشح مسبق seccomp)
* **eBPF:** [`docs/ebpf.md`](https://github.com/canyonroad/agentsh/blob/main/docs/ebpf.md) - تتبع شبكة eBPF وتطبيق السياسات
* **وكيل LLM و DLP:** [`docs/llm-proxy.md`](https://github.com/canyonroad/agentsh/blob/main/docs/llm-proxy.md) - تكوين وكيل مضمن، أنماط DLP، تتبع الاستخدام
* **دليل بناء macOS:** [`docs/macos-build.md`](https://github.com/canyonroad/agentsh/blob/main/docs/macos-build.md) - تعليمات بناء ESF+NE
* **بنية macOS ESF+NE:** [`docs/macos-esf-ne-architecture.md`](https://github.com/canyonroad/agentsh/blob/main/docs/macos-esf-ne-architecture.md) - تفاصيل امتداد النظام و XPC والنشر
* **صندوق رمل XPC لـ macOS:** [`docs/macos-xpc-sandbox.md`](https://github.com/canyonroad/agentsh/blob/main/docs/macos-xpc-sandbox.md) - التحكم في XPC/Mach IPC للعمليات المعزولة
* متغيرات البيئة (جميع تجاوزات `AGENTSH_*`، مفاتيح التشغيل التلقائي، اختيار النقل): [`docs/spec.md` §15.3 "Environment Variables"](https://github.com/canyonroad/agentsh/blob/main/docs/spec.md#153-environment-variables)
* البنية وتدفق البيانات (FUSE + محرك السياسات + API): تعليقات مضمنة في [`configs/server-config.yaml`](https://github.com/canyonroad/agentsh/blob/main/configs/server-config.yaml) و [`internal/netmonitor`](https://github.com/canyonroad/agentsh/blob/main/internal/netmonitor)
* مساعدة CLI: `agentsh --help`, `agentsh exec --help`, `agentsh shim --help`

---

تم إنشاؤه بمساعدة وكلاء من أجل وكلاء.

`visibility`	`silent`, `audit_only`, `warn`	كيفية تسجيل/عرض عمليات إعادة التوجيه
`on_failure`	`fail_closed`, `fail_open`, `retry_original`	ما يحدث إذا فشلت إعادة التوجيه
`tls_mode`	`passthrough`, `rewrite_sni`	معالجة TLS لإعادة توجيه الاتصال

إعادة توجيه DNS	✅ eBPF	✅ pf/proxy	✅ WinDivert
إعادة توجيه الاتصال	✅ eBPF	✅ pf/proxy	✅ WinDivert
إعادة كتابة SNI	✅	✅	✅

Linux	نعم (seccomp user-notify)	نعم	نعم
macOS	لا	لا	نعم (ES)
Windows	جزئي	لا	نعم (ETW)

agentsh

الأكثر شعبية

agentsh

ما هو agentsh؟

لماذا agentsh؟

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

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

بداية سريعة

التثبيت

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

Start the server (optional if using autostart)

Create a session and run a command (shell output)

Structured output for agents

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

Shell access

نموذج السياسة

القرارات

النطاقات

التقييم

مرجع سريع لسياسة البيئة

أمثلة على القواعد (مختصرة)```yaml

المصادقة

أمان MCP

عرض توضيحي لـ 60 ثانية

1) Create a session in your repo/workspace

2) Run something simple (human-friendly output)

→ prints system info, just like normal

3) Run something that hits the network (JSON output + event summary)

→ JSON response includes: exit_code, stdout, and events[] showing dns_query + net_connect

4) Trigger a policy decision - try to delete something

→ With default policy: prompts for approval or denies based on your rules

5) See what happened (structured audit trail)

→ events[] shows every file operation, even from subprocesses

نقاط تفتيش مساحة العمل

Create a checkpoint before risky operations

List checkpoints for a session

Show what changed since a checkpoint

Preview what rollback would restore (dry-run)

Restore workspace to checkpoint state

Clean up old checkpoints

التحكم في الوصول إلى قاعدة البيانات (Postgres فقط حاليًا)

توليد السياسات

Generate policy from latest session

Generate with custom name and threshold

Quick preview to stdout

إعادة توجيه الشبكة

إعادة توجيه DNS

الخيارات

دعم المنصة

حالات الاستخدام

تصفية الإشارات

دعم المنصة

أمثلة على قواعد الإشارات```yaml

Allow signals to self and children

Redirect SIGKILL to graceful SIGTERM

Block fatal signals to external processes