thodoristsampouris/agentguardصندوق رمل (sandbox) بثقة صفرية لوكلاء الذكاء الاصطناعي مع عزل نظام الملفات على مستوى النواة، ووكيل شبكة شفاف، ومحرك سياسات قائم على YAML لاعتراض والتحكم في أوامر الصدفة وعمليات الملفات وطلبات الشبكة.
صندوق رمل (sandbox) بدون ثقة للوكلاء الذكيين المستقلين.
يقوم AgentGuard بتطويق أي وكيل ذكي (LangChain، CrewAI، AutoGen، نصوص خاصة) بحواجز أمان. تغيير بأمر واحد:
# قبل (خطير - الوكيل لديه وصول كامل للنظام)
python my_agent.py
# بعد (داخل صندوق الرمل)
agentguard run -- python my_agent.py
يعترض AgentGuard كل أمر شل، وتعديل ملف، وطلب شبكة يقوم به الوكيل. يتم السماح تلقائياً بالإجراءات الآمنة، وحظر الإجراءات الخطيرة تلقائياً، ويتم عرض باقي الإجراءات على المستخدم للموافقة.
يمتلك AgentGuard أربع طبقات دفاعية تعمل معاً:
┌─────────────────────────────────────────────────────────────┐
│ Layer 0: سجن نظام الملفات (sandbox-exec على macOS) │
│ تطبيق على مستوى النواة. يقيد كتابات الملفات والشبكة │
│ على مستوى استدعاءات النظام. لا يمكن للوكيل تجاوزه من │
│ مساحة المستخدم. يمنع Python's open(), requests.post(), إلخ.│
├─────────────────────────────────────────────────────────────┤
│ Layer 1: وكيل الشبكة │
│ وكيل HTTP/HTTPS شفاف. يتم فحص كل استدعاء شبكي يقوم به │
│ الوكيل مقابل السياسة. السماح/المنع لكل وجهة مع رؤية كاملة │
│ في واجهة المستخدم النصية (TUI). │
├─────────────────────────────────────────────────────────────┤
│ Layer 2: واجهات PATH الوهمية │
│ نصوص شل وهمية تعترض الأوامر مثل git, pip, curl, rm. │
│ كل وهمية تطلب الإذن من الخفي (daemon) قبل تشغيل │
│ الثنائي الحقيقي. │
├─────────────────────────────────────────────────────────────┤
│ Layer 3: محرك السياسات + خفي الموافقة │
│ قواعد مبنية على YAML تقيم كل إجراء معترض. │
│ السماح تلقائياً بالأوامر الآمنة، حظر الخطيرة تلقائياً، │
│ وعرض الباقي على المستخدم للموافقة. │
└─────────────────────────────────────────────────────────────┘
لا توجد طبقة واحدة هي الحدود الأمنية. تعمل معاً - دفاع متعمق.
go build -o agentguard ./cmd/agentguard/
go build -o agentguard-check ./cmd/agentguard-check/
يجب أن يكون كلا الثنائيين في نفس المجلد.
agentguard init
ينشئ هذا ملف .agentguard/policy.yaml في المجلد الحالي. قم بتعديله ليناسب احتياجاتك.
agentguard run -- python my_agent.py
تتولى واجهة TUI شاشة الطرفية وتعرض:
للأدوات التفاعلية مثل Claude Code التي تحتاج الطرفية:
agentguard run --headless -- claude
يحصل الوكيل على الطرفية مباشرة. يعمل AgentGuard بصمت في الخلفية. يتم تسجيل جميع الأحداث في ~/.agentguard/logs/headless.log. راقب في طرفية أخرى:
tail -f ~/.agentguard/logs/headless.log
agentguard run [flags] -- <command> [args...]
--policy <path> استخدام ملف سياسة محدد
--headless لا TUI - الوكيل يحصل على الطرفية
--default-allow السماح تلقائياً بقرارات PROMPT في الوضع بدون رأس (افتراضياً: منع تلقائي)
--no-sandbox تعطيل sandbox-exec (الوهميات والوكيل لا يزالان نشطين)
agentguard init إنشاء ملف سياسة افتراضي
agentguard version طباعة الإصدار
السياسات هي ملفات YAML تحدد ما يمكن للوكيل فعله وما لا يمكنه فعله. يتحقق AgentGuard من ثلاثة مواقع (بالترتيب):
./.agentguard/policy.yaml (محلي للمشروع)~/.agentguard/policy.yaml (عام للمستخدم)version: 1
deny:
# منع الأوامر الخطيرة
- command: "rm"
args: "-rf *"
reason: "الحذف المتكرر القسري خطير جداً"
- command: "sudo"
args: "*"
reason: "رفع الصلاحيات غير مسموح به"
- command: "chmod"
args: "777 *"
reason: "الأذونات القابلة للكتابة عالمياً خطيرة"
# منع قراءة الملفات الحساسة (يتم تطبيقه بواسطة sandbox-exec)
- file:
path: "*.env"
action: "read"
reason: "لا تدع الوكيل يقرأ ملفات .env"
- file:
path: "*.pem"
action: "read"
reason: "لا تدع الوكيل يقرأ المفاتيح الخاصة"
allow:
# أوامر آمنة للقراءة فقط
- command: "ls"
- command: "cat"
- command: "pwd"
- command: "echo"
- command: "grep"
- command: "head"
- command: "tail"
- command: "wc"
# git للقراءة فقط
- command: "git"
args: "status"
- command: "git"
args: "log *"
- command: "git"
args: "diff *"
# السماح بالكتابة إلى مساحة العمل
- file:
path: "/tmp/workspace/**"
action: "write"
# السماح بنقاط نهاية API محددة
- network:
destination: "api.anthropic.com:443"
- network:
destination: "api.github.com:443"
deny network *) - يتم فحصها ثالثاً. تعمل كمنع افتراضي.قواعد الأوامر - تطابق أوامر الشل بالاسم ونمط الوسيطات:
- command: "git"
args: "push *"
reason: "الدفع يتطلب موافقة"
قواعد الملفات - تطابق عمليات الملفات (يتم تطبيقها بواسطة sandbox-exec):
- file:
path: "*.env"
action: "read" # "read" أو "write"
reason: "حماية الأسرار"
قواعد الشبكة - تطابق وجهات الشبكة (يتم تطبيقها بواسطة الوكيل + sandbox-exec):
- network:
destination: "api.anthropic.com:443"
استخدم * كحرف بدل في وسيطات الأوامر ومسارات الملفات ووجهات الشبكة.
| المفتاح | الإجراء | متى |
|---|---|---|
Y | السماح بالطلب المعلق | طلب الموافقة مرئي |
N | رفض الطلب المعلق | طلب الموافقة مرئي |
A | السماح + التذكر لهذه الجلسة ("السماح دائماً") | طلب الموافقة مرئي |
B | الرفض + التذكر لهذه الجلسة ("الحظر للأبد") | طلب الموافقة مرئي |
Tab | تبديل لوحة الإخراج القياسي/الخطأ للوكيل | دائماً |
Up/Down | التمرير في تيار النشاط | دائماً |
Q | الخروج (يقتل الوكيل) | دائماً |
| إجراء الوكيل | الوهميات | الوكيل | sandbox-exec |
|---|---|---|---|
subprocess.run(["rm", "-rf", "/"]) | نعم | - | - |
subprocess.run(["git", "push"]) | نعم | - | - |
requests.post("https://evil.com") | - | نعم | نعم |
urllib.request.urlopen("https://api.com") | - | نعم | نعم |
open(".env", "r") | - | - | نعم |
open("/etc/shadow", "w") | - | - | نعم |
/usr/bin/curl https://evil.com (مسار مطلق) | - | نعم | نعم |
agentguard/
├── cmd/
│ ├── agentguard/ # الثنائي الرئيسي لواجهة CLI
│ └── agentguard-check/ # الثنائي المساعد للوهميات
├── internal/
│ ├── policy/ # محرك السياسات (تحليل YAML، تقييم القواعد)
│ ├── events/ # نظام الأحداث (سجل تدقيق JSONL، نشر/اشتراك)
│ ├── daemon/ # خفي مركزي (مقبس Unix، قائمة انتظار الموافقة)
│ │ └── client/ # مكتبة العميل للوهميات
│ ├── shim/ # مولد الوهميات (اعتراض قائم على PATH)
│ ├── proxy/ # وكيل شبكة شفاف
│ ├── spawner/ # التنسيق + تكامل صندوق رمل macOS
│ └── ui/tui/ # واجهة المستخدم النصية (Bubble Tea)
├── configs/
│ └── default_policy.yaml # ملف سياسة مرجعي
├── .gitignore
├── go.mod
├── LICENSE
└── README.md