renweimeng/vlun-agent-xVulnAgent-X: إطار وكيل متعدد الطبقات لكشف الثغرات على مستوى المستودع
VulnAgent-X هو نموذج أولي متعدد الوكلاء لاكتشاف الثغرات/العيوب موجه لإعادة إنتاج الأوراق البحثية. يستقبل مستودعًا محليًا أو فرقًا (diff)، ويخرج استنتاجات منظمة، وسلسلة أدلة، ونتائج توطين، وثقة، وسجلات تجريبية.
repo path أو unified diffscreening -> context expansion -> scheduler -> router -> experts -> sceptic -> verification(stub) -> evidence fusionissue_typelocation(file + line range)evidence_summaryconfidenceseverityoptional_cwefix_hintevidence_chaincounter_evidencescreening: فحص سريع للمناطق المشبوهة (قواعد + إشارات بيانات وصفية)context_expansion: جلب "أقل سياق كافٍ" (استخراج نافذة حسب الموقع المشبوه)scheduler: استراتيجية ترقية تعتمد على الثقة والمخاطر (early_exit / expert_review / verification)router_agent: اختيار وكيل خبير لكل منطقة مشبوهةsemantic/security/logic: تقديم ادعاءات وأدلة منظمة من زوايا مختلفةsceptic_agent: توليد أدلة مضادة وإشارات عقابيةverification: تحقق ديناميكي اختياري (حاليًا تنفيذ آمن مؤقت)evidence_fusion: دمج موحد وإخراج الاستنتاجات النهائيةالمتطلبات: Python 3.11+ (يمكن تشغيلها أيضًا على إصدارات أحدث)
cd /Users/xiaolu/Documents/Python_code/vulnAgentX
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'
تحليل المستودع بالكامل:
.venv/bin/vulnagentx analyze --repo /path/to/repo --output json
تحليل ملف فرق:
.venv/bin/vulnagentx analyze --diff-file /path/to/patch.diff --output json
إخراج موجز:
.venv/bin/vulnagentx analyze --repo /path/to/repo --output summary
تشغيل الخدمة:
.venv/bin/uvicorn vulnagentx.app.api:app --reload
فحص الصحة:
curl http://127.0.0.1:8000/health
بدء التحليل:
curl -X POST http://127.0.0.1:8000/analyze \
-H "Content-Type: application/json" \
-d '{"repo_path":"/path/to/repo"}'
docker compose -f docker/docker-compose.yml up --build
.venv/bin/ruff check src tests
.venv/bin/mypy src
.venv/bin/pytest
{
"run_id": "...",
"findings": [
{
"issue_type": "command_injection",
"location": {"file_path": "app.py", "start_line": 42, "end_line": 42},
"evidence_summary": "تم اكتشاف سطح تنفيذ الأوامر...",
"confidence": 0.87,
"severity": "critical",
"optional_cwe": "CWE-78",
"fix_hint": "تجنب تركيب أوامر الصدفة...",
"source_agents": ["security_agent", "semantic_agent"],
"evidence_chain": [],
"counter_evidence": []
}
],
"metrics": {
"runtime_seconds": 0.07
},
"logs": []
}
| الملف | الاستخدام |
|---|---|
.env.example | قالب متغيرات البيئة (إعدادات اختيارية مثل مستوى السجل). |
pyproject.toml | بناء المشروع، التبعيات، نقاط دخول البرامج النصية، إعداد pytest/ruff/mypy. |
README.md | ملف README الرئيسي (مع زر تبديل اللغة، الافتراضي الصينية). |
README.zh.md | الوثائق الكاملة بالصينية. |
README.en.md | الوثائق الكاملة بالإنجليزية. |
docker/Dockerfile | ملف بناء حاوية خدمة API. |
docker/docker-compose.yml | تشغيل خدمة الحاوية بنقرة واحدة محليًا. |
rules/semgrep/vulnagentx-rules.yml | مجموعة قواعد Semgrep المدمجة (حقن أوامر/حقن SQL/إلغاء التسلسل/استدعاءات C غير آمنة). |
scripts/run_experiment.py | برنامج تنفيذ تجارب مجمعة على مجموعة البيانات، إخراج تنبؤات بصيغة JSONL. |
scripts/evaluate.py | قراءة مخرجات التجارب وحساب مقاييس الكشف/التوطين/الكفاءة. |
scripts/run_ablation.py | برنامج تجارب الحذف (no_semgrep/no_treesitter/no_sceptic/no_verification). |
src/vulnagentx)| الملف | الاستخدام |
|---|---|
src/vulnagentx/__init__.py | تعريف إصدار الحزمة وتصديرها. |
src/vulnagentx/app/__init__.py | تهيئة الحزمة الفرعية app. |
src/vulnagentx/app/cli.py | نقطة دخول CLI (vulnagentx analyze). |
src/vulnagentx/app/api.py | نقطة دخول خدمة FastAPI (/health، /analyze). |
src/vulnagentx/app/schemas.py | مخططات Pydantic لطلبات/ردود API. |
src/vulnagentx/core/__init__.py | تهيئة الحزمة الفرعية core. |
src/vulnagentx/core/state.py | نموذج الحالة العالمية: المناطق، الأدلة، مخرجات الوكلاء، الاستنتاجات، السجلات، المقاييس. |
src/vulnagentx/core/screening.py | المرحلة الأولى من الفحص السريع، استخراج المناطق المشبوهة. |
src/vulnagentx/core/context_expansion.py | توسيع السياق: استخراج نافذة الكود الأدنى حسب الموقع. |
src/vulnagentx/core/scheduler.py | استراتيجية ترقية حساسة للثقة (early_exit/expert_review/verification). |
src/vulnagentx/core/verification.py | وحدة تحقق ديناميكي اختيارية (حاليًا إصدار آمن مؤقت). |
src/vulnagentx/core/evidence_fusion.py | دمج أدلة متعددة الوكلاء، إخراج الاستنتاجات النهائية. |
src/vulnagentx/core/workflow.py | نقطة دخول التنسيق من البداية إلى النهاية VulnAgentWorkflow. |
src/vulnagentx/agents/__init__.py | تجميع تصدير الوكلاء. |
src/vulnagentx/agents/base.py | فئة أساسية مجردة للوكيل وأداة الحصول على السياق. |
src/vulnagentx/agents/router_agent.py | وكيل التوجيه: تعيين وكيل خبير لكل منطقة مشبوهة. |
src/vulnagentx/agents/semantic_agent.py | الوكيل الدلالي: مخاطر الطبقة الدلالية (مثل المؤشر الفارغ، إلغاء التسلسل، ابتلاع الاستثناءات). |
tests)| الملف | الاستخدام |
|---|---|
tests/test_agents.py | اختبارات وحدة: مخرجات منظمة لكل وكيل ومنطق الأدلة المضادة. |
tests/test_end_to_end.py | اختبار شامل: من إدخال المستودع إلى الاستنتاجات النهائية. |
tests/test_research_modules.py | اختبارات الوحدات الجديدة: بناء رسم بياني Tree-sitter، سلسلة تنفيذ التحقق، مقاييس التقييم. |
OpenAI + Ollama محلي + تبديل تلقائي عبر المصنعsrc/vulnagentx/agents/security_agent.py |
| وكيل الأمان: قواعد الثغرات الأمنية (حقن الأوامر، حقن SQL، تجاوز الحدود، إلخ). |
src/vulnagentx/agents/logic_bug_agent.py | وكيل المنطق: عيوب الأعمال/تدفق التحكم (حدود، قسمة على صفر، نقص التفويض، إلخ). |
src/vulnagentx/agents/sceptic_agent.py | وكيل الشك: توليد أدلة مضادة، عقوبات تعارض، تقليل الثقة. |
src/vulnagentx/adapters/__init__.py | تهيئة الحزمة الفرعية للمهايئات. |
src/vulnagentx/adapters/sandbox_adapter.py | منفذ صندوق رمل مقيد بعمليات فرعية (مهلة، بدون شل) للتحقق. |
src/vulnagentx/adapters/semgrep_adapter.py | مهايئ واجهة سطر أوامر Semgrep (اختياري التمكين). |
src/vulnagentx/adapters/treesitter_adapter.py | مهايئ Tree-sitter حقيقي (يحلل AST وعلاقات الاستدعاء/الاستيراد عند التوفر، يتدهور عند عدم التوفر). |
src/vulnagentx/adapters/llm/__init__.py | تجميع تصدير مهايئات LLM. |
src/vulnagentx/adapters/llm/base.py | واجهة بروتوكول مهايئ LLM. |
src/vulnagentx/adapters/llm/mock_adapter.py | LLM وهمي قابل للاختبار دون اتصال. |
src/vulnagentx/adapters/llm/openai_adapter.py | مهايئ SDK الرسمي لـ OpenAI. |
src/vulnagentx/adapters/llm/local_adapter.py | مهايئ النموذج المحلي (Ollama HTTP API). |
src/vulnagentx/adapters/llm/factory.py | تحديد مهايئ LLM تلقائيًا حسب التكوين والرجوع إلى Mock. |
src/vulnagentx/retrieval/repo_graph.py | فهرس الرسم البياني للكود واسترجاع الملفات المجاورة (بناءً على تداخل رموز AST). |
src/vulnagentx/datasets/base.py | هيكل عينة مجموعة البيانات العامة وقراءة JSONL/CSV. |
src/vulnagentx/datasets/devign.py | نقطة دخول تحميل بيانات Devign. |
src/vulnagentx/datasets/bigvul.py | نقطة دخول تحميل بيانات Big-Vul. |
src/vulnagentx/datasets/primevul.py | نقطة دخول تحميل بيانات PrimeVul. |
src/vulnagentx/datasets/jit.py | نقطة دخول تحميل بيانات JIT. |
src/vulnagentx/eval/detection_metrics.py | مقاييس الكشف (Precision/Recall/F1/Accuracy). |
src/vulnagentx/eval/localization_metrics.py | مقاييس التوطين (Top-1/Top-3/MRR). |
src/vulnagentx/eval/efficiency_metrics.py | مقاييس الكفاءة (متوسط الوقت، P95، متوسط الاستنتاجات). |
src/vulnagentx/eval/ablations.py | منطق تنفيذ تجارب الحذف. |
src/vulnagentx/utils/config.py | مركز تكوين سير العمل (مفاتيح env/CLI/API). |