مرجع واجهة HTTP

يعرض لوحة CVE Intelligence واجهة REST JSON عديمة الحالة على خادم Node/Express. يستخدم الواجهة الأمامية نفس المسارات عبر وكيل Vite أثناء التطوير (/api → localhost:3001) ومسارات نفس المصدر في الإنتاج. يمكن للمُدمِجين استدعاء الواجهة من سكربتات أو بوابات CI أو لوحات داخلية دون تحميل عميل React.

يصف هذا الفصل كل المسار العام، والتحقق من الطلبات، وأشكال الاستجابة، ورموز الأخطاء، والحدود التشغيلية. للتجربة التفاعلية دون خادم حي، استخدم تب API Explorer (محاكاة في المتصفح). للعقود القابلة للقراءة آلياً، اطلب GET /api/openapi.json.

مبادئ تصميم الواجهة

تتبع الواجهة اتفاقيات المنتجات الشائعة: أجسام JSON، UTF-8، بدون ملفات تعريف ارتباط للجلسة (مناسبة للوكيل العكسي وبوابات API)، وأوضاع مسح صريحة (full مقابل watch) تنعكس في meta.mode. كل مسح مستقل؛ لا يخزّن الخادم مكدسك أو النتائج ما لم تحفظ الاستجابات على جانب العميل.

يُدعم بادئتان لعنوان URL:

البادئة	الغرض
/api/*	مسارات متوافقة مع الواجهة الحالية
/api/v1/*	سطح مُنسّخ (نفس المعالجات، مستقر للتكامل)

يُفضَّل للتكاملات الجديدة /api/v1 واعتبار /api alias أثناء الانتقال.

الاكتشاف والبيانات الوصفية

قبل المسح، يستدعي العملاء عادة نقاط اكتشاف لمعرفة الحدود والمصادر المتاحة وتكوين وقت التشغيل.

الصحة — GET /api/health (و /api/v1/health)

تُرجع حالة الحياة مع أعلام غير سرية. استخدمها لفحوصات موازن التحميل ومسبارات بدء التشغيل.

حقول الاستجابة (ملخص):

الحقل	المعنى
ok	دائماً true عندما العملية تعمل
version	إصدار semver للتطبيق من package.json (مثلاً 1.1.0)
sources	معرّفات المصادر المدمجة
nvdApiKey / githubToken	هل بُيِّئت بيانات الاعتماد (وليس القيم)
scanDays	نافذة البحث من SCAN_DAYS (افتراضي 60)
translate	هل الترجمة من جانب الخادم مسموحة
limits	سقوف رقمية (حجم المكدس، أحجام الدفعات)

Detailed probe: GET /api/health?detailed=true — uptime، reachability لكل مصدر، cache، air-gap، translation provider، alerts.webhookConfigured (أي قناة إشعار)، alerts.minSeverity.

Prometheus metrics — GET /metrics

مسار الجذر (ليس تحت /api). METRICS_ENABLED=true افتراضياً؛ METRICS_PROTECT=true يتطلب API_SECRET. راجع Self-hosted metrics.

القدرات — GET /api/capabilities

تُرجع حدود المنتج وأعلام الميزات (أقصى أدوات لكل مسح، لغات الترجمة، أوضاع المسح). يُفضَّل هذا على تحليل health عند بناء النماذج أو مدققات CI.

فهرس المصادر — GET /api/sources

تُرجع سجل المصادر المدمجة (NVD، OSV، GitHub، CISA KEV، خلاصات RSS) مع kind وfullScan وwatchScan، وعناوين RSS الافتراضية. لا تُدرج الخلاصات المخصصة هنا؛ يزوّد العملاء بها في كل طلب عبر customFeeds.

OpenAPI — GET /api/openapi.json

يقدّم مستند OpenAPI 3.1 (server/openapi/spec.json) لتوليد الشيفرة أو استيراد Postman أو اختبارات العقد.

التحقق من الطلبات والأخطاء

يجب أن تكون أجسام POST كائنات JSON. فشل التحقق يُرجع HTTP 400:

{
  "error": "Human-readable message",
  "code": "VALIDATION_ERROR",
  "details": { "max": 50, "received": 72 }
}

فشل المصادر الخارجية (حد NVD، انتهاء RSS) يُرجع 502 أو 429 مع نص error وcode اختياري (SCAN_FAILED، WATCH_FAILED). تعرض الواجهة error كنص؛ قد يقرأ المُدمِجون أيضاً code وdetails.

حد معدل التطبيق (middleware): عند تجاوز العميل حصص scan أو watch لكل IP، يُرجع الخادم HTTP 429:

{
  "error": "Too many scan requests. Try again later.",
  "code": "RATE_LIMITED",
  "retryAfterSec": 42
}

• يستخدم POST /scan وPOST /watch سطلان منفصلان في الدقيقة.
• POST /scan/validate معفى (آمن لـ CI وفحص المكدس).
• اضبط عبر RATE_LIMIT_SCAN_PER_MIN وRATE_LIMIT_WATCH_PER_MIN في .env.

API key / RBAC (v1): مع API_SECRET، المسارات المحمية تتطلب X-Api-Key أو Bearer؛ 401 / 403 عند الفشل. /api/v1/* يطبّق API_ROLE. أرسل X-Tenant-Id مع PostgreSQL.

قواعد المكدس:

• stack — مصفوفة إلزامية غير فارغة من أسماء الأدوات (مُقصّاة)، بحد أقصى 50 أداة.
• customFeeds — اختياري، بحد أقصى 20؛ كل عنصر يحتاج id وurl.
• enabledBuiltin — خريطة اختيارية معرّف مصدر → boolean؛ المفاتيح الغائبة مفعّلة افتراضياً.

التحقق دون مسح — POST /api/scan/validate

يتحقق من stack وenabledBuiltin وcustomFeeds دون استدعاء موفّري CVE خارجيين. استخدمه في المعالجات أو CI لرفض المدخلات قبل مسح مكلف.

مثال طلب:

{
  "stack": ["Redis", "HAProxy"],
  "enabledBuiltin": { "NVD": true, "TuxCare": false },
  "customFeeds": [{ "id": "custom:team-feed", "name": "Team RSS", "url": "https://example.com/cve.rss" }]
}

مثال استجابة:

{
  "valid": true,
  "stack": ["Redis", "HAProxy"],
  "toolCount": 2,
  "customFeedCount": 1,
  "message": "Stack and source options are valid; run POST /api/scan for findings."
}

المسح الكامل — POST /api/scan

ينفّذ مسحاً كاملاً: NVD، OSV، GitHub Advisories، CISA KEV، RSS المدمج، والخلاصات المخصصة المفعّلة. تُدمَج النتائج حسب معرّف CVE، تُغنّى بأعلام KEV، تُترجم اختيارياً، ثم تُعاد في حمولة واحدة.

جسم الطلب:

الحقل	النوع	إلزامي	الوصف
stack	string[]	نعم	أسماء الأدوات للمطابقة
translate	boolean	لا	إذا true، ترجمة العناوين/الأوصاف
locale	fa | ar | ru | zh | fr	لا	اللغة الهدف عند translate: true
enabledBuiltin	object	لا	تبديل لكل مصدر
customFeeds	array	لا	خلاصات RSS/Atom إضافية (معرّفات custom:…)

مثال:

{
  "stack": ["Redis", "HAProxy", "Kubernetes"],
  "translate": true,
  "locale": "ar",
  "enabledBuiltin": { "NVD": true, "TheHackerNews": true }
}

الاستجابة: ScanResponse — vulns[]، summary، search_date، meta (sources_checked، sources_updated_at، duration_ms، mode: "full").

كل ثغرة تتضمن id، tool، title، severity، واختيارياً affected_versions، fixed_version، sources[]، url، patch_available، exploited_in_wild، وعند تفعيل EPSS: epss (0–1) وriskScore (0–10)، وعند تفعيل الامتثال: cwe[] وcompliance_controls[]، وtranslations / title_fa عند الإثراء.

تسلسل المسح (منظور المُدمِج)

sequenceDiagram
  participant Client
  participant API as Express API
  participant Feeds as مصادر خارجية

  Client->>API: POST /api/scan { stack, translate, locale }
  API->>Feeds: NVD/OSV/GitHub/KEV/RSS بالتوازي
  Feeds-->>API: نتائج خام
  API->>API: دمج، إثراء KEV، ترجمة اختيارية
  API-->>Client: 200 { vulns, summary, meta }

شرح المخطط

يرسل العميل حمولة JSON واحدة. يوزّع الخادم على المصادر المُكوَّنة، يُوحّد السجلات إلى شكل ثغرة مشترك، يزيل التكرار حسب معرّف CVE، ويطبّق ترجمة اختيارية على أول N عناصر (يتحكم TRANSLATE_MAX_ITEMS). تتضمن الاستجابة بيانات التوقيت لعرض التقدّم أو تدقيق SLA.

الإجراء خطوة بخطوة

1. استدعِ GET /api/capabilities لقراءة maxStackTools وtranslateLocales.
2. اختيارياً استدعِ POST /api/scan/validate بنفس الجسم المخطط للمسح.
3. نفّذ POST /api/scan مع stack وخيارات المصادر.
4. احفظ vulns وmeta.sources_updated_at إذا احتجت شارات واجهة تزايدية.
5. عند 429، زِد فترة الانتظار وأعد المحاولة بمسحات أقل تكراراً تعتمد على NVD.

المراقبة — POST /api/watch

ينفّذ وضع المراقبة: OSV، GitHub، KEV، وRSS بدون NVD لزمن استجابة أقل. يطابق الجسم المسح مع knownIds اختياري (معرّفات CVE المُشاهدة). تضيف الاستجابة newVulns وhasNew لخطوط التنبيه.

مثال:

{
  "stack": ["Redis"],
  "knownIds": ["CVE-2024-1234", "CVE-2023-9999"],
  "translate": false
}

الاستجابة: كالمسح مع newVulns[]، hasNew: boolean، meta.mode: "watch".

عندما تكون newVulns غير فارغة ومُعدّة متغيرات الإشعار، يرسل الخادم القنوات المُكوَّنة عبر NotificationService (دون التأثير على استجابة JSON).

الترجمة — POST /api/translate

يترجم دفعة حقول title / description الإنجليزية إلى لغة الواجهة عبر MyMemory / LibreTranslate / Ollama (انظر التكوين). يُستخدم عند تغيير لغة الواجهة بعد المسح أو لعناصر تتجاوز حدود ترجمة المسح على الخادم.

طلب:

{
  "locale": "ar",
  "items": [
    {
      "id": "CVE-2024-1",
      "tool": "Redis",
      "title": "Heap buffer overflow",
      "description": "…"
    }
  ]
}

استجابة: { "locale": "ar", "items": [{ "id", "tool", "title", "description" }] }
أقصى عناصر لكل طلب: TRANSLATE_BATCH_MAX (افتراضي 40).

Versioned API (/api/v1 only)

POST /api/v1/scan/stream (SSE)، GET /api/v1/scans/history، GET /api/v1/scans/trends، POST /api/v1/tenants، CRUD /api/v1/tenants/stacks (+ :id)، GET /api/v1/discovery/kubernetes. تتطلب Postgres أو opt-in K8s حيث ينطبق. راجع فصل API بالإنجليزية.

ملخص نقاط النهاية

الطريقة	المسار	الوصف
GET	/api/health	الحياة + الأعلام (?detailed=true)
GET	/metrics	Prometheus
GET	/api/capabilities	الحدود والميزات
GET	/api/sources	فهرس المصادر
GET	/api/openapi.json	مواصفات OpenAPI 3.1
POST	/api/scan/validate	التحقق من المكدس/المصادر فقط
POST	/api/scan	مسح كامل
POST	/api/watch	استطلاع مراقبة + فرق
POST	/api/translate	ترجمة دفعة
POST	/api/v1/scan/stream	SSE scan (v1)
GET	/api/v1/scans/history	تاريخ المستأجر
GET/POST	/api/v1/tenants/stacks	مكدسات محفوظة
GET	/api/v1/discovery/kubernetes	اكتشاف K8s

مسارات /api/* الأساسية لها alias؛ مسارات v1-only ليست تحت /api legacy.

الأمان وملاحظات النشر

الواجهة مخصصة لشبكات موثوقة. مصادقة اختيارية: اضبط API_SECRET على الخادم؛ يرسل العملاء X-Api-Key أو Authorization: Bearer. GET /api/health وGET /api/v1/health بدون مفتاح لمجسات التوازن. لا تعرّض بدون TLS على الإنترنت العام. حدود المعدل موروثة من المصادر؛ اضبط NVD_API_KEY لإنتاجية أعلى.

فصول ذات صلة

• التكوين — متغيرات البيئة
• المعمارية — تخطيط وحدات الخادم
• المسح والمراقبة — دلالات أوضاع المنتج

جرّب الطلبات في تب API Explorer.