مرجع APIٔ HTTP

پنل CVE Intelligence یک REST API مبتنی بر JSON روی سرور Node/Express ارائه می‌دهد. رابط کاربری در توسعه از پراکسی Vite (/api → پورت ۳۰۰۱) و در production از همان مبدأ درخواست می‌زند. یکپارچه‌سازی‌ها می‌توانند بدون بارگذاری کلاینت React، از اسکریپت، CI یا داشبورد داخلی به API متصل شوند.

این فصل همهٔ مسیرهای عمومی، اعتبارسنجی درخواست، شکل پاسخ‌ها، کدهای خطا و سقف‌های عملیاتی را شرح می‌دهد. برای آزمایش بدون سرور زنده از تب API Explorer (شبیه‌ساز مرورگر) استفاده کنید. برای قرارداد ماشینی: GET /api/openapi.json.

اصول طراحی API

قراردادها مطابق محصول‌های استاندارد است: بدنهٔ JSON، UTF-8، بدون کوکی نشست (مناسب پروکسی معکوس و API Gateway)، و تفکیک صریح اسکن کامل و نظارت در meta.mode. هر اسکن مستقل است؛ سرور پشته یا یافته‌ها را ذخیره نمی‌کند مگر شما پاسخ را سمت کلاینت نگه دارید.

دو پیشوند URL پشتیبانی می‌شود:

پیشوند	کاربرد
/api/*	مسیرهای سازگار با UI فعلی
/api/v1/*	سطح نسخه‌دار برای یکپارچه‌سازی پایدار

یکپارچه‌سازی‌های جدید ترجیحاً /api/v1 را انتخاب کنند.

کشف قابلیت‌ها و فراداده

قبل از اسکن، کلاینت‌ها معمولاً endpointهای کشف را می‌خوانند تا سقف‌ها، منابع و پیکربندی زمان اجرا را بدانند.

سلامت — GET /api/health (و /api/v1/health)

زنده بودن سرویس و پرچم‌های غیرمحرمانه. برای health check لودبالانسر مناسب است.

فیلدهای پاسخ (خلاصه):

فیلد	معنی
ok	وقتی فرایند بالا است همیشه true
version	نسخهٔ semver اپ از package.json (مثلاً 1.1.0)
sources	شناسه‌های فیدهای داخلی
nvdApiKey / githubToken	آیا اعتبار env تنظیم شده (نه خود مقادیر)
scanDays	پنجرهٔ look-back از SCAN_DAYS (پیش‌فرض ۶۰)
translate	آیا ترجمهٔ سمت سرور مجاز است
limits	سقف‌های عددی (اندازهٔ پشته، اندازهٔ batch)

پروب تفصیلی: GET /api/health?detailed=true (همان روی /api/v1/health) uptime، دسترس‌پذیری هر منبع، اندازه/بک‌اند cache، پرچم‌های mirror در air-gap، ارائه‌دهندهٔ ترجمه و پیکربندی اعلان را برمی‌گرداند:

فیلد	معنی
uptime	uptime فرایند به ثانیه
sources	نگاشت شناسهٔ منبع → { reachable, lastOkAt, … }
cache	{ size, backend } — حافظه یا Redis
airgap	وقتی AIRGAPPED=true — سلامت mirror
translation.activeProvider	DeepL، LibreTranslate یا GoogleGTX
alerts.webhookConfigured	true وقتی هر کانال اعلان در env تنظیم شده (Slack، Discord، Telegram، email، webhook عمومی یا ALERT_WEBHOOK_URL قدیمی)
alerts.minSeverity	NOTIFICATION_MIN_SEVERITY یا ALERT_MIN_SEVERITY (پیش‌فرض HIGH)

متریک Prometheus — GET /metrics

مسیر ریشه (نه زیر /api). وقتی METRICS_ENABLED=true (پیش‌فرض) متن Prometheus برمی‌گرداند. با METRICS_PROTECT=true همان API_SECRET مسیرهای API لازم است. متریک self-hosted و docs/self-hosted/METRICS.md.

قابلیت‌ها — GET /api/capabilities

سقف‌های محصول (حداکثر ابزار در اسکن، اندازهٔ دستهٔ ترجمه، حالت‌های اسکن) و پرچم‌های feature. برای فرم‌ها و اعتبارسنج CI بهتر از پارس دستی health است.

فهرست منابع — GET /api/sources

رجیستری منابع داخلی (NVD، OSV، GitHub، KEV، RSS) همراه kind و اینکه در full یا watch شرکت می‌کنند. فیدهای سفارشی در هر درخواست با customFeeds ارسال می‌شوند.

OpenAPI — GET /api/openapi.json

سند OpenAPI 3.1 برای codegen و Postman.

اعتبارسنجی و خطا

بدنهٔ POST باید شیء JSON باشد. خطای اعتبارسنجی: HTTP 400 با error، اختیاری code (مثلاً VALIDATION_ERROR) و details.

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

خطاهای upstream (محدودیت NVD، timeout RSS) معمولاً 502 یا 429 با codeهای SCAN_FAILED یا WATCH_FAILED هستند. UI مقدار 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 (اختیاری): با تنظیم API_SECRET، مسیرهای محافظت‌شده به X-Api-Key یا Authorization: Bearer نیاز دارند. نبود یا اشتباه بودن → 401 با { "code": "AUTH_REQUIRED" }. GET /api/health و /api/v1/health برای load balancer بدون کلید باز می‌مانند.

RBAC (v1، وقتی API_SECRET فعال است): مسیرهای /api/v1/* نقش سرور API_ROLE (پیش‌فرض admin) را اعمال می‌کنند. نقش ناکافی → 403 با { "code": "FORBIDDEN" }. نقش‌ها: admin، scanner، viewer، auditor. مسیرهای legacy /api/* فعلاً RBAC ندارند — برای استقرار احراز هویت‌شده /api/v1 را ترجیح دهید.

سربرگ multi-tenant (v1): با PostgreSQL (DATABASE_URL)، X-Tenant-Id: <slug> روی فراخوانی‌های نسخه‌دار بفرستید؛ حذف = tenant default.

قوانین پشته:

• stack — آرایهٔ اجباری نام ابزار (حداکثر ۵۰ مورد)
• customFeeds — اختیاری، حداکثر ۲۰؛ هر مورد id و url
• enabledBuiltin — اختیاری؛ غایب = فعال

اعتبارسنجی بدون اسکن — POST /api/scan/validate

فقط stack و گزینه‌های منبع را می‌سنجد بدون تماس با NVD/OSV. برای ویزارد پشته یا 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، KEV، RSS و فیدهای سفارشی فعال. ادغام بر اساس شناسهٔ CVE، غنی‌سازی KEV، ترجمهٔ اختیاری.

فیلد	نوع	اجباری	توضیح
stack	string[]	بله	نام ابزارها
translate	boolean	خیر	ترجمهٔ عنوان/توضیح
locale	fa…fr	خیر	زبان هدف
enabledBuiltin	object	خیر	خاموش/روشن منابع
customFeeds	array	خیر	RSS دلخواه

پاسخ: vulns[]، summary، search_date، meta با mode: "full" و sources_updated_at.

هر آسیب‌پذیری شامل id، tool، title، severity، sources[]، url، exploited_in_wild است؛ با EPSS فعال فیلدهای اختیاری epss (۰–۱) و riskScore (۰–۱۰)، با نگاشت انطباق فعال cwe[] و compliance_controls[]، و در صورت غنی‌سازی translations / title_fa اضافه می‌شوند.

نمونه درخواست:

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

sequenceDiagram
  participant Client
  participant API as Express API
  participant Feeds as منابع خارجی

  Client->>API: POST /api/scan
  API->>Feeds: NVD/OSV/GitHub/KEV/RSS
  Feeds-->>API: یافته‌های خام
  API->>API: ادغام و ترجمهٔ اختیاری
  API-->>Client: 200 JSON

شرح نمودار

کلاینت یک JSON می‌فرستد؛ سرور به‌صورت موازی منابع فعال را می‌خواند، رکوردها را یکسان‌سازی می‌کند و در صورت translate: true بخشی از موارد را به locale ترجمه می‌کند (محدودیت TRANSLATE_MAX_ITEMS).

روال گام‌به‌گام

1. GET /api/capabilities برای سقف ابزار و زبان‌های ترجمه
2. در صورت نیاز POST /api/scan/validate
3. POST /api/scan
4. در 429 (NVD) فاصلهٔ retry را زیاد کنید

نظارت — POST /api/watch

نظارت: بدون NVD، سریع‌تر. فیلد knownIds برای محاسبهٔ 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

ترجمهٔ دسته‌ای عنوان/توضیح انگلیسی به fa، ar، ru، zh، fr (حداکثر TRANSLATE_BATCH_MAX، پیش‌فرض ۴۰).

نمونه درخواست:

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

پاسخ: { "locale": "ru", "items": [{ "id", "tool", "title", "description" }] }

API نسخه‌دار (/api/v1 فقط)

این مسیرها فقط زیر /api/v1 هستند. aliasهای legacy /api/* فقط scan، watch، validate، translate و metadata را پوشش می‌دهند.

جریان اسکن (SSE) — POST /api/v1/scan/stream

همان بدنهٔ JSON اسکن کامل. پاسخ Server-Sent Events است: رویداد پیشرفت، سپس complete یا error. نقش‌ها: admin، scanner.

تاریخچهٔ اسکن — GET /api/v1/scans/history

Query limit (۱–۲۰۰، پیش‌فرض ۵۰). { enabled, tenant, items[] } از متادیتای PostgreSQL. 503 DATABASE_DISABLED بدون DATABASE_URL. نقش‌ها: admin، scanner، viewer، auditor.

روند اسکن — GET /api/v1/scans/trends

Query days (۱–۳۶۵، پیش‌فرض ۳۰). { enabled, tenant, days, points[] }. همان نیاز DB و نقش‌های history.

tenant و پشتهٔ ذخیره‌شده

متد	مسیر	نقش	شرح
POST	/api/v1/tenants	admin	ایجاد tenant { slug, name }
GET	/api/v1/tenants/stacks	read	فهرست پشته برای X-Tenant-Id
POST	/api/v1/tenants/stacks	admin	ایجاد { name, tools, settings? }
GET	/api/v1/tenants/stacks/:id	read	دریافت با UUID
PUT	/api/v1/tenants/stacks/:id	admin	به‌روزرسانی
DELETE	/api/v1/tenants/stacks/:id	admin	حذف

بدون PostgreSQL همهٔ مسیرهای tenant/stack 503 برمی‌گردانند.

کشف Kubernetes — GET /api/v1/discovery/kubernetes

نیاز K8S_DISCOVERY_ENABLED=true. نقش‌ها: admin، scanner. 503 K8S_DISCOVERY_DISABLED وقتی opt-in خاموش است.

جدول endpointها

متد	مسیر	شرح
GET	/api/health	سلامت (?detailed=true برای ops)
GET	/metrics	متریک Prometheus
GET	/api/capabilities	سقف‌ها
GET	/api/sources	کاتالوگ منابع
GET	/api/openapi.json	OpenAPI
POST	/api/scan/validate	اعتبارسنجی
POST	/api/scan	اسکن کامل
POST	/api/watch	نظارت
POST	/api/translate	ترجمه
POST	/api/v1/scan/stream	اسکن کامل روی SSE (فقط v1)
GET	/api/v1/scans/history	تاریخچه tenant (Postgres)
GET	/api/v1/scans/trends	روند tenant (Postgres)
POST	/api/v1/tenants	ایجاد tenant
GET/POST	/api/v1/tenants/stacks	فهرست / ایجاد پشته
GET/PUT/DELETE	/api/v1/tenants/stacks/:id	CRUD پشته
GET	/api/v1/discovery/kubernetes	کشف K8s

aliasهای legacy /api/* برای ردیف‌های scan/metadata اصلی (نه مسیرهای فقط-v1).

امنیت و استقرار

API برای شبکهٔ مورد اعتماد است. احراز هویت اختیاری: API_SECRET روی سرور؛ کلاینت‌ها X-Api-Key یا Authorization: Bearer می‌فرستند. GET /api/health و GET /api/v1/health بدون کلید برای load balancer باز می‌مانند. برای اینترنت عمومی Gateway با TLS لازم است. محدودیت نرخ از ارائه‌دهندگان upstream (به‌ویژه NVD) به‌ارث می‌رسد؛ برای throughput بالاتر NVD_API_KEY را تنظیم کنید.

فصل‌های مرتبط

• پیکربندی — متغیرهای محیط
• معماری — چیدمان ماژول سرور
• اسکن و نظارت — معنای محصولی modeها

تب API Explorer را امتحان کنید.