نقاط نهاية REST API

يوفّر AuroraSOC عدد 57 نقطة نهاية REST عبر FastAPI على http://localhost:8000. تتطلب جميع النقاط (باستثناء /health و/api/v1/auth/token) مصادقة JWT.

تدفق المصادقة

عنوان URL الأساسي

http://localhost:8000/api/v1

البدء السريع حسب نوع العميل

cURL

# 1) Authenticate and capture JWT
TOKEN=$(curl -s -X POST http://localhost:8000/api/v1/auth/token \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"admin"}' | jq -r .access_token)

# 2) Query latest alerts
curl -s "http://localhost:8000/api/v1/alerts?limit=20" \
  -H "Authorization: Bearer $TOKEN"

Python (httpx)

import httpx

BASE_URL = "http://localhost:8000/api/v1"

async def list_alerts() -> dict:
    async with httpx.AsyncClient(timeout=20.0) as client:
        # Authenticate once and reuse JWT for all protected endpoints.
        auth_response = await client.post(
            f"{BASE_URL}/auth/token",
            json={"username": "admin", "password": "admin"},
        )
        auth_response.raise_for_status()
        token = auth_response.json()["access_token"]

        alerts_response = await client.get(
            f"{BASE_URL}/alerts",
            params={"limit": 20},
            headers={"Authorization": f"Bearer {token}"},
        )
        alerts_response.raise_for_status()
        return alerts_response.json()

TypeScript (fetch)

const baseUrl = "http://localhost:8000/api/v1";

async function listAlerts() {
  // Get a JWT first.
  const authRes = await fetch(`${baseUrl}/auth/token`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ username: "admin", password: "admin" }),
  });
  if (!authRes.ok) throw new Error(`auth failed: ${authRes.status}`);
  const { access_token } = await authRes.json();

  const alertsRes = await fetch(`${baseUrl}/alerts?limit=20`, {
    headers: { Authorization: `Bearer ${access_token}` },
  });
  if (!alertsRes.ok) throw new Error(`alerts failed: ${alertsRes.status}`);
  return alertsRes.json();
}

نقاط النهاية حسب الفئة

المصادقة

الطريقة	المسار	المصادقة	الصلاحية	الوصف
POST	/api/v1/auth/token	لا يوجد	—	الحصول على رمز وصول JWT

الطلب:

{
  "username": "admin",
  "password": "admin"
}

الاستجابة:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer"
}

المستخدمون

الطريقة	المسار	المصادقة	الصلاحية	الوصف
GET	/api/v1/users/me	JWT	—	ملف المستخدم الحالي
GET	/api/v1/users	JWT	دور admin	عرض جميع المستخدمين
POST	/api/v1/users	JWT	دور admin	إنشاء مستخدم
DELETE	/api/v1/users/{username}	JWT	دور admin	حذف مستخدم

النظام

الطريقة	المسار	المصادقة	الصلاحية	الوصف
GET	/health	لا يوجد	—	فحص سلامة عام

التنبيهات

الطريقة	المسار	المصادقة	الصلاحية	الوصف
GET	/api/v1/alerts	JWT	alerts:read	عرض التنبيهات (بترقيم صفحات)
POST	/api/v1/alerts	JWT	alerts:write	إنشاء تنبيه
GET	/api/v1/alerts/{alert_id}	JWT	alerts:read	جلب تنبيه واحد
PATCH	/api/v1/alerts/{alert_id}	JWT	alerts:write	تحديث حالة التنبيه

معلمات الاستعلام لطلب GET /api/v1/alerts:

المعلمة	النوع	الافتراضي	الوصف
skip	int	0	إزاحة الترقيم
limit	int	50	حجم الصفحة (الحد الأقصى 200)
severity	string	—	تصفية: critical|high|medium|low|info
status	string	—	تصفية: new|triaged|investigating|...
source	string	—	تصفية حسب نظام المصدر

إنشاء التنبيه يتضمن إزالة التكرار:

dedup_hash = SHA256(f"{title}|{source}|{sorted(iocs)}")
# If matching hash exists, returns existing alert instead of creating duplicate

القضايا

الطريقة	المسار	المصادقة	الصلاحية	الوصف
GET	/api/v1/cases	JWT	cases:read	عرض القضايا
POST	/api/v1/cases	JWT	cases:write	إنشاء قضية حادثة
GET	/api/v1/cases/{case_id}	JWT	cases:read	جلب القضية مع المخطط الزمني
PATCH	/api/v1/cases/{case_id}	JWT	cases:write	تحديث القضية

طلب إنشاء قضية:

{
  "title": "Lateral Movement via PsExec",
  "severity": "high",
  "description": "Multiple hosts showing PsExec activity",
  "alert_ids": ["uuid-1", "uuid-2"],
  "assignee": "analyst@example.com"
}

الوكلاء

الطريقة	المسار	المصادقة	الصلاحية	الوصف
GET	/api/v1/agents	JWT	agents:read	عرض جميع الوكلاء الـ16
POST	/api/v1/agents/{id}/enable	JWT	agents:manage	تفعيل الوكيل
POST	/api/v1/agents/{id}/disable	JWT	agents:manage	تعطيل الوكيل
POST	/api/v1/agents/{id}/deploy	JWT	agents:manage	نشر إلى الموقع
PATCH	/api/v1/agents/{id}/scale	JWT	agents:manage	توسيع عدد النسخ (0-10)
POST	/api/v1/agents/investigate	JWT	investigation:trigger	بدء التحقيق

معلمات تصفية الوكلاء:

المعلمة	النوع	الوصف
site	string	تصفية حسب موقع SOC
status	string	active|disabled|error
type	string	تعداد نوع الوكيل

طلب التحقيق (مع حد معدل):

{
  "alert_context": "Suspicious DNS queries to known C2 domain t1.evil.com from 10.0.1.50",
  "has_cps_assets": false,
  "severity": "high"
}

المواقع

الطريقة	المسار	المصادقة	الصلاحية	الوصف
GET	/api/v1/sites	JWT	sites:read	عرض مواقع SOC
POST	/api/v1/sites	JWT	sites:manage	تسجيل موقع
DELETE	/api/v1/sites/{id}	JWT	sites:manage	إزالة موقع

SIEM

الطريقة	المسار	المصادقة	الصلاحية	الوصف
GET	/api/v1/siem/logs	JWT	siem:read	البحث في السجلات
GET	/api/v1/siem/sources	JWT	siem:read	عرض مصادر السجلات
GET	/api/v1/siem/stats	JWT	siem:read	إحصاءات SIEM

EDR

الطريقة	المسار	المصادقة	الصلاحية	الوصف
GET	/api/v1/edr/endpoints	JWT	edr:read	عرض endpoints
GET	/api/v1/edr/endpoints/{id}	JWT	edr:read	تفاصيل endpoint
POST	/api/v1/edr/endpoints/{id}/isolate	JWT	edr:manage	عزل endpoint
POST	/api/v1/edr/endpoints/{id}/unisolate	JWT	edr:manage	إزالة العزل
POST	/api/v1/edr/endpoints/{id}/scan	JWT	edr:manage	تشغيل فحص
GET	/api/v1/edr/stats	JWT	edr:read	إحصاءات EDR

SOAR

الطريقة	المسار	المصادقة	الصلاحية	الوصف
GET	/api/v1/soar/playbooks	JWT	soar:read	عرض Playbooks
GET	/api/v1/soar/playbooks/{id}	JWT	soar:read	تفاصيل Playbook
POST	/api/v1/soar/playbooks/{id}/toggle	JWT	soar:manage	تبديل حالة التفعيل
POST	/api/v1/soar/playbooks/{id}/execute	JWT	soar:execute	تنفيذ Playbook
GET	/api/v1/soar/executions	JWT	soar:read	سجل التنفيذ
GET	/api/v1/soar/rules	JWT	soar:read	قواعد الأتمتة
POST	/api/v1/soar/rules/{id}/toggle	JWT	soar:manage	تبديل القاعدة

Playbooks

الطريقة	المسار	المصادقة	الصلاحية	الوصف
GET	/api/v1/playbooks	JWT	playbooks:read	عرض Playbooks
POST	/api/v1/playbooks/{id}/execute	JWT	playbooks:execute	تنفيذ Playbook
GET	/api/v1/playbooks/executions	JWT	playbooks:read	سجل التنفيذ

CPS / IoT Devices

الطريقة	المسار	المصادقة	الصلاحية	الوصف
GET	/api/v1/cps/devices	JWT	cps:read	عرض أجهزة CPS
GET	/api/v1/cps/devices/{id}	JWT	cps:read	تفاصيل الجهاز
POST	/api/v1/cps/devices/{id}/revoke	JWT	cps:manage	إبطال الشهادة
GET	/api/v1/cps/attestations	JWT	cps:read	نتائج التحقق (Attestation)

الموافقات البشرية

الطريقة	المسار	المصادقة	الصلاحية	الوصف
GET	/api/v1/approvals	JWT	approvals:manage	عرض الموافقات المعلقة
POST	/api/v1/approvals/{id}/decide	JWT	approvals:manage	موافقة/رفض

طلب القرار:

{
  "decision": "approved",
  "reason": "Verified - safe to isolate compromised host"
}

التقارير

الطريقة	المسار	المصادقة	الصلاحية	الوصف
GET	/api/v1/reports	JWT	reports:read	عرض التقارير
GET	/api/v1/reports/{id}	JWT	reports:read	التقرير الكامل

استخبارات التهديدات

الطريقة	المسار	المصادقة	الصلاحية	الوصف
GET	/api/v1/iocs	JWT	iocs:read	عرض IOCs
POST	/api/v1/iocs	JWT	iocs:write	إنشاء IOC

الإحصاءات ولوحة التحكم

الطريقة	المسار	المصادقة	الصلاحية	الوصف
GET	/api/v1/stats/overview	JWT	stats:read	نظرة عامة على لوحة التحكم
GET	/api/v1/dashboard/stats	JWT	stats:read	إحصاءات مسطحة للواجهة الأمامية
GET	/api/v1/correlations	JWT	cps:read	أحداث مترابطة فيزيائيًا-سيبرانيًا
GET	/api/v1/firmware	JWT	cps:read	جرد البرمجيات الثابتة

تحديد معدل الطلبات

فئة نقطة النهاية	حد المعدل	النافذة
API العامة	100 طلب	لكل دقيقة
تشغيل التحقيق	10 طلبات	لكل دقيقة
تنفيذ الـ Playbook	5 طلبات	لكل دقيقة

استجابات الأخطاء

تتبع جميع الأخطاء تنسيقًا موحدًا:

{
  "detail": "Alert not found"
}

رمز الحالة	المعنى
400	طلب غير صالح / خطأ تحقق
401	رمز JWT مفقود أو غير صالح
403	صلاحيات غير كافية
404	المورد غير موجود
429	تم تجاوز حد المعدل
503	قاعدة البيانات غير متاحة (وضع متدهور)

الوضع المتدهور

عند عدم توفر PostgreSQL، تنتقل API تلقائيًا إلى مخازن بيانات داخل الذاكرة مع بيانات تجريبية. يضمن ذلك بقاء لوحة التحكم والمراقبة بحالة تشغيل أثناء صيانة قاعدة البيانات.

@app.exception_handler(DatabaseUnavailable)
async def _handle_db_unavailable(request, exc):
    return JSONResponse(
        status_code=503,
        content={"detail": "Database unavailable — running in degraded mode"},
    )