توثيق API

المصادقة

أرسل مفتاح API الخاص بك كرمز bearer أو في ترويسة X-API-Key:

curl https://vulny.app/api/v1/targets \
  -H "Authorization: Bearer vlny_your_key"

حدود المعدل

120 طلبًا في الدقيقة لكل مفتاح. تتضمن كل استجابة ترويسات X-RateLimit-Limit و X-RateLimit-Remaining و X-RateLimit-Reset. يؤدي تجاوز الحد إلى إرجاع 429 مع ترويسة Retry-After.

بدء فحص

POST /api/v1/scans — ابدأ فحصًا عند الطلب على هدف (يُضاف إلى حسابك إذا كان جديدًا). يُرجع id الفحص لاستطلاعه.

curl -X POST https://vulny.app/api/v1/scans \
  -H "Authorization: Bearer vlny_your_key" \
  -H "Content-Type: application/json" \
  -d '{"target":"example.com"}'

# → { "id": "...", "target": "example.com", "status": "queued" }

حالة الفحص والنتائج

GET /api/v1/scans/{id} — استطلِع حتى تصبح done صحيحة. يُرجع ملخص درجة الخطورة summary وقائمة findings — استخدمها لتمرير أو إفشال خط أنابيب CI.

curl https://vulny.app/api/v1/scans/SCAN_ID \
  -H "Authorization: Bearer vlny_your_key"

# → { "status": "finished", "done": true, "progress": 100,
#     "summary": { "critical": 1, "high": 2, "medium": 0, "low": 3, "total": 6 },
#     "findings": [ { "severity": "critical", "title": "CVE-2024-...", "cvss_score": 9.8, "port": "443/tcp" } ] }

راجع خط أنابيب DevSecOps للحصول على أمثلة كاملة لـ GitLab CI و GitHub Actions تنتظر اكتمال الفحص وتُفشل البناء عند النتائج الحرجة.

إضافة أهداف (بالجملة، حتى 1000)

POST /api/v1/targets/bulk — يقبل النطاقات أو عناوين IP، اختياريًا مع وسوم. يحترم حد الأهداف في خطتك.

curl -X POST https://vulny.app/api/v1/targets/bulk \
  -H "Authorization: Bearer vlny_your_key" \
  -H "Content-Type: application/json" \
  -d '{"targets":["example.com","203.0.113.10",{"value":"api.example.com","tags":["prod"]}]}'

حذف الأهداف (بالجملة)

DELETE /api/v1/targets/bulk — بواسطة المعرّفات أو بواسطة القيم (عناوين IP / أسماء المضيفين).

curl -X DELETE https://vulny.app/api/v1/targets/bulk \
  -H "Authorization: Bearer vlny_your_key" \
  -H "Content-Type: application/json" \
  -d '{"values":["example.com","203.0.113.10"]}'

تحديث الوسوم (بالجملة)

PATCH /api/v1/targets/tags — تعيين أو إضافة أو إزالة الوسوم على عدة أهداف دفعة واحدة (mode: set | add | remove).

curl -X PATCH https://vulny.app/api/v1/targets/tags \
  -H "Authorization: Bearer vlny_your_key" \
  -H "Content-Type: application/json" \
  -d '{"values":["example.com"],"tags":["pci","prod"],"mode":"add"}'

مواصفات OpenAPI

المواصفات الكاملة القابلة للقراءة آليًا متوفرة على /api/v1/openapi.json — استوردها إلى Postman أو Insomnia أو مولّد الشيفرة الخاص بك.