نموذج أولي لـ VulnAgent-X للبحث

VulnAgent-X هو نموذج أولي متعدد الوكلاء لاكتشاف الثغرات/العيوب موجه لإعادة إنتاج الأوراق البحثية. يستقبل مستودعًا محليًا أو فرقًا (diff)، ويخرج استنتاجات منظمة، وسلسلة أدلة، ونتائج توطين، وثقة، وسجلات تجريبية.

القدرات الأساسية

• صيغة الإدخال: repo path أو unified diff
• سير العمل: screening -> context expansion -> scheduler -> router -> experts -> sceptic -> verification(stub) -> evidence fusion
• حقول الإخراج:
  • issue_type
  • location(file + line range)
  • evidence_summary
  • confidence
  • severity
  • optional_cwe
  • fix_hint
  • evidence_chain
  • counter_evidence
• الواجهة: CLI + FastAPI
• تجارب قابلة للتكرار: pytest / mypy / ruff + دعم تشغيل Docker

نظرة عامة على سير العمل

1. screening: فحص سريع للمناطق المشبوهة (قواعد + إشارات بيانات وصفية)
2. context_expansion: جلب "أقل سياق كافٍ" (استخراج نافذة حسب الموقع المشبوه)
3. scheduler: استراتيجية ترقية تعتمد على الثقة والمخاطر (early_exit / expert_review / verification)
4. router_agent: اختيار وكيل خبير لكل منطقة مشبوهة
5. semantic/security/logic: تقديم ادعاءات وأدلة منظمة من زوايا مختلفة
6. sceptic_agent: توليد أدلة مضادة وإشارات عقابية
7. verification: تحقق ديناميكي اختياري (حاليًا تنفيذ آمن مؤقت)
8. evidence_fusion: دمج موحد وإخراج الاستنتاجات النهائية

دليل التثبيت والتشغيل

1) إعداد البيئة

المتطلبات: Python 3.11+ (يمكن تشغيلها أيضًا على إصدارات أحدث)

cd /Users/xiaolu/Documents/Python_code/vulnAgentX
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'

2) استخدام CLI

تحليل المستودع بالكامل:

.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

3) استخدام API

تشغيل الخدمة:

.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"}'

4) تشغيل عبر Docker

docker compose -f docker/docker-compose.yml up --build

5) فحص الجودة والاختبارات

.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)