مشاركة عبر

الرجوع إلى واجهة برمجة تطبيقات مؤشرات التحميل القديمة

سمحت واجهة برمجة التطبيقات لمؤشرات التحميل من Microsoft Sentinel بأنظمة أساسية للتحليل الذكي للمخاطر أو تطبيقات مخصصة لاستيراد مؤشرات الاختراق بتنسيق STIX إلى مساحة عمل Microsoft Sentinel. يعمل هذا المستند كمرجع لواجهة برمجة التطبيقات القديمة.

هام

واجهة برمجة التطبيقات هذه قيد المعاينة ولكن لم تعد مستحسنة. استخدم واجهة برمجة تطبيقات كائنات STIX الجديدة في المعاينة لتحميل التحليل الذكي للمخاطر. لمزيد من المعلومات، راجع واجهة برمجة تطبيقات كائنات STIX. تتضمن الشروط التكميلية لمعاينة Azure شروطا قانونية إضافية تنطبق على ميزات Azure الموجودة في الإصدار التجريبي أو المعاينة أو التي لم يتم إصدارها بعد في التوفر العام.

يحتوي استدعاء واجهة برمجة التطبيقات لمؤشرات التحميل على خمسة مكونات:

  1. عنوان URI للطلب
  2. رأس رسالة طلب HTTP
  3. نص رسالة طلب HTTP
  4. معالجة رأس رسالة استجابة HTTP اختياريا
  5. معالجة نص رسالة استجابة HTTP اختياريا

تسجيل تطبيق العميل الخاص بك باستخدام معرف Microsoft Entra

من أجل المصادقة على Microsoft Sentinel، يتطلب الطلب إلى مؤشرات التحميل API رمز وصول Microsoft Entra صالحا. لمزيد من المعلومات حول تسجيل التطبيق، راجع تسجيل تطبيق باستخدام النظام الأساسي للهويات في Microsoft أو راجع الخطوات الأساسية كجزء من إعداد موصل بيانات واجهة برمجة التطبيقات لمؤشرات التحميل.

الأذونات

تتطلب واجهة برمجة التطبيقات هذه منح تطبيق Microsoft Entra الاستدعاء دور المساهم في Microsoft Sentinel على مستوى مساحة العمل.

إنشاء الطلب

يغطي هذا القسم المكونات الثلاثة الأولى من المكونات الخمسة التي تمت مناقشتها سابقا. تحتاج أولا إلى الحصول على الرمز المميز للوصول من معرف Microsoft Entra، والذي تستخدمه لتجميع رأس رسالة الطلب.

طلب رمز مميز للوصول

احصل على رمز مميز للوصول إلى Microsoft Entra باستخدام مصادقة OAuth 2.0. V1.0 وV2.0 هي رموز مميزة صالحة مقبولة من قبل واجهة برمجة التطبيقات.

يتم تحديد إصدار الرمز المميز (v1.0 أو v2.0) الذي يتلقاه التطبيق الخاص بك بواسطة الخاصية في بيان التطبيق لواجهة برمجة التطبيقات التي يستدعيها accessTokenAcceptedVersion التطبيق الخاص بك. إذا accessTokenAcceptedVersion تم تعيين إلى 1، فسيتلقى التطبيق الخاص بك رمزا مميزا v1.0.

استخدم مكتبة مصادقة Microsoft MSAL للحصول على رمز وصول v1.0 أو v2.0. أو أرسل طلبات إلى واجهة برمجة تطبيقات REST بالتنسيق التالي:

  • POST https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token
  • عناوين استخدام تطبيق Microsoft Entra:
  • grant_type: "client_credentials"
  • client_id: {Client ID of Microsoft Entra App}
  • client_secret: {secret of Microsoft Entra App}
  • نطاق: "https://management.azure.com/.default"

إذا تم accessTokenAcceptedVersion تعيين في بيان التطبيق إلى 1، فسيتلقى التطبيق الخاص بك رمز وصول v1.0 على الرغم من أنه يستدعي نقطة نهاية الرمز المميز v2.

قيمة المورد/النطاق هي جمهور الرمز المميز. تقبل واجهة برمجة التطبيقات هذه الجماعات المستهدفة التالية فقط:

  • https://management.core.windows.net/
  • https://management.core.windows.net
  • https://management.azure.com/
  • https://management.azure.com

تجميع رسالة الطلب

كان هناك إصداران من واجهة برمجة التطبيقات القديمة. اعتمادا على نقطة النهاية، كان اسم صفيف مختلف مطلوبا في نص الطلب. تم تمثيل هذا أيضا بإصدارين من إجراء موصل تطبيق المنطق.

لقطة شاشة لأسماء إجراءات موصل التطبيق المنطقي لواجهة برمجة تطبيقات مؤشرات تحميل Microsoft Sentinel.

  1. اسم إجراء الموصل: التحليل الذكي للمخاطر - تحميل مؤشرات التسوية (مهمل)
    • نقطه النهايه: https://sentinelus.azure-api.net/{workspaceId}/threatintelligence:upload-indicators
    • اسم صفيف المؤشرات: value
    { "sourcesystem":"TIsource-example", "value":[] }
  • اسم إجراء الموصل: تحليل ذكي للمخاطر - تحميل مؤشرات التسوية (V2) (معاينة)
    • نقطه النهايه: https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload
    • اسم صفيف المؤشرات: indicators 
      {
   "sourcesystem":"TIsource-example",
   "indicators":[]
}

طلب URI

تعيين إصدار واجهة برمجة التطبيقات: api-version=2022-07-01
نقطه النهايه: https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload?api-version=2022-07-01
أسلوب: POST

عنوان الطلب

Authorization: يحتوي على الرمز المميز لحامل OAuth2
Content-Type: application/json

نص الطلب

يحتوي كائن JSON للنص الأساسي على الحقول التالية:

اسم الحقل نوع البيانات ‏‏الوصف
SourceSystem (مطلوب) سلسلة حدد اسم النظام المصدر. القيمة Microsoft Sentinel مقيدة.
المؤشرات (مطلوب) صفيف صفيف من المؤشرات بتنسيق STIX 2.0 أو 2.1

أنشئ مجموعة من المؤشرات باستخدام مواصفات تنسيق مؤشر STIX 2.1، والتي تم تكثيفها هنا لراحتك مع روابط إلى أقسام مهمة. لاحظ أيضا أن بعض الخصائص، على الرغم من أنها صالحة ل STIX 2.1، لا تحتوي على خصائص مؤشر مطابقة في Microsoft Sentinel.

اسم الخاصية كتابة ‏‏الوصف
id (مطلوب) سلسلة معرف يستخدم لتحديد المؤشر. راجع القسم 2.9 للحصول على مواصفات حول كيفية إنشاء id. يبدو التنسيق مشابها indicator--<UUID>
spec_version (اختياري) سلسلة إصدار مؤشر STIX. هذه القيمة مطلوبة في مواصفات STIX، ولكن نظرا لأن واجهة برمجة التطبيقات هذه تدعم STIX 2.0 و2.1 فقط، عندما لا يتم تعيين هذا الحقل، سيتم تعيين API افتراضيا إلى 2.1
type (مطلوب) سلسلة يجب أن تكون indicatorقيمة هذه الخاصية .
created (مطلوب) الطابع الزمني راجع القسم 3.2 للاطلاع على مواصفات هذه الخاصية الشائعة.
modified (مطلوب) الطابع الزمني راجع القسم 3.2 للاطلاع على مواصفات هذه الخاصية الشائعة.
name (اختياري) سلسلة اسم يستخدم لتعريف المؤشر.

يجب على المنتجين توفير هذه الخاصية لمساعدة المنتجات والمحللين على فهم ما يفعله هذا المؤشر في الواقع.
description (اختياري) سلسلة وصف يوفر المزيد من التفاصيل والسياق حول المؤشر، بما في ذلك الغرض منه وخصائصه الرئيسية.

يجب على المنتجين توفير هذه الخاصية لمساعدة المنتجات والمحللين على فهم ما يفعله هذا المؤشر في الواقع.
indicator_types (اختياري) قائمة السلاسل مجموعة من التصنيفات لهذا المؤشر.

يجب أن تأتي قيم هذه الخاصية من نوع المؤشر
pattern (مطلوب) سلسلة يمكن التعبير عن نمط الكشف لهذا المؤشر كنمط STIX أو لغة مناسبة أخرى مثل SNORT وYRA وما إلى ذلك.
pattern_type (مطلوب) سلسلة لغة النمط المستخدمة في هذا المؤشر.

يجب أن تأتي قيمة هذه الخاصية من أنواع الأنماط.

يجب أن تتطابق قيمة هذه الخاصية مع نوع بيانات النمط المضمنة في خاصية النمط.
pattern_version (اختياري) سلسلة إصدار لغة النمط المستخدمة للبيانات في خاصية النمط، والتي يجب أن تتطابق مع نوع بيانات النمط المضمنة في خاصية النمط.

بالنسبة للأنماط التي لا تحتوي على مواصفات رسمية، يجب استخدام إصدار البنية أو التعليمات البرمجية الذي يعرف أن النمط يعمل معه.

بالنسبة للغة نمط STIX، يحدد إصدار المواصفات للكائن القيمة الافتراضية.

بالنسبة للغات الأخرى، يجب أن تكون القيمة الافتراضية أحدث إصدار من لغة الأنماط في وقت إنشاء هذا الكائن.
valid_from (مطلوب) الطابع الزمني الوقت الذي يعتبر فيه هذا المؤشر مؤشرا صالحا للسلوكيات المرتبطة به أو التي يمثلها.
valid_until (اختياري) الطابع الزمني الوقت الذي يجب ألا يعتبر فيه هذا المؤشر مؤشرا صالحا للسلوكيات المرتبطة به أو التي يمثلها.

إذا تم حذف الخاصية valid_until، فلا يوجد قيد على آخر وقت يكون فيه المؤشر صالحا.

يجب أن يكون هذا الطابع الزمني أكبر من الطابع الزمني valid_from.
kill_chain_phases (اختياري) قائمة السلسلة مرحلة (مراحل) سلسلة القتل التي يتوافق مع هذا المؤشر.

يجب أن تأتي قيمة هذه الخاصية من مرحلة Kill Chain.
created_by_ref (اختياري) سلسلة تحدد الخاصية created_by_ref خاصية المعرف للكيان الذي أنشأ هذا الكائن.

إذا تم حذف هذه السمة، فإن مصدر هذه المعلومات غير معرف. بالنسبة لمنشئي الكائنات الذين يرغبون في البقاء مجهولين، احتفظ بهذه القيمة غير محددة.
revoked (اختياري) boolean لم يعد منشئ الكائن يعتبر الكائنات التي تم إبطالها صالحة. إبطال كائن دائم؛ يجب عدم إنشاء الإصدارات المستقبلية من الكائن مع هذا.id

القيمة الافتراضية لهذه الخاصية خاطئة.
labels (اختياري) قائمة السلاسل labels تحدد الخاصية مجموعة من المصطلحات المستخدمة لوصف هذا الكائن. يتم تعريف المصطلحات من قبل المستخدم أو مجموعة الثقة. سيتم عرض هذه التسميات كعلامات في Microsoft Sentinel.
confidence (اختياري) integer confidence تحدد الخاصية الثقة التي يتمتع بها المنشئ في صحة بياناته. يجب أن تكون قيمة الثقة رقما في نطاق 0-100.

يحتوي الملحق أ على جدول تعيينات معيارية لمقاييس الثقة الأخرى التي يجب استخدامها عند تقديم قيمة الثقة في أحد هذه المقاييس.

إذا لم تكن خاصية الثقة موجودة، فستكون ثقة المحتوى غير محددة.
lang (اختياري) سلسلة lang تحدد الخاصية لغة محتوى النص في هذا الكائن. عند وجوده، يجب أن يكون رمز لغة متوافقا مع RFC5646. إذا لم تكن الخاصية موجودة، فإن لغة المحتوى هي en (الإنجليزية).

يجب أن تكون هذه الخاصية موجودة إذا كان نوع الكائن يحتوي على خصائص نص قابلة للترجمة (على سبيل المثال، الاسم والوصف).

قد تتجاوز لغة الحقول الفردية في هذا الكائن الخاصية lang في علامات دقيقة (راجع القسم 7.2.3).
object_marking_refs (اختياري، بما في ذلك TLP) قائمة السلاسل object_marking_refs تحدد الخاصية قائمة بخصائص المعرف لكائنات تعريف العلامات التي تنطبق على هذا الكائن. على سبيل المثال، استخدم معرف تعريف وضع علامة بروتوكول إشارات المرور (TLP) لتعيين حساسية مصدر المؤشر. للحصول على تفاصيل حول معرفات تعريف العلامات التي يجب استخدامها لمحتوى TLP، راجع القسم 7.2.1.4

في بعض الحالات، على الرغم من أنه غير شائع، قد يتم وضع علامة على تعريفات العلامات نفسها مع إرشادات المشاركة أو التعامل معها. في هذه الحالة، يجب ألا تحتوي هذه الخاصية على أي مراجع لنفس كائن تعريف العلامة (أي، لا يمكن أن تحتوي على أي مراجع دائرية).

راجع القسم 7.2.2 للحصول على مزيد من التعريف لعلامات البيانات.
external_references (اختياري) قائمة الكائنات external_references تحدد الخاصية قائمة بالمراجع الخارجية التي تشير إلى معلومات غير STIX. يتم استخدام هذه الخاصية لتوفير واحد أو أكثر من عناوين URL أو الأوصاف أو المعرفات للسجلات في أنظمة أخرى.
granular_markings (اختياري) قائمة العلامات الدقيقة granular_markings تساعد الخاصية على تحديد أجزاء من المؤشر بشكل مختلف. على سبيل المثال، لغة المؤشر هي الإنجليزية، en ولكن الوصف هو الألمانية، de.

في بعض الحالات، على الرغم من أنه غير شائع، قد يتم وضع علامة على تعريفات العلامات نفسها مع إرشادات المشاركة أو التعامل معها. في هذه الحالة، يجب ألا تحتوي هذه الخاصية على أي مراجع لنفس كائن "تعريف العلامة" (على سبيل المثال، لا يمكن أن تحتوي على أي مراجع دائرية).

راجع القسم 7.2.3 لمزيد من التعريف لعلامات البيانات.

معالجة رسالة الاستجابة

يحتوي عنوان الاستجابة على رمز حالة HTTP. راجع هذا الجدول لمزيد من المعلومات حول كيفية تفسير نتيجة استدعاء واجهة برمجة التطبيقات.

كود الحالة ‏‏الوصف
200 تمت بنجاح. ترجع واجهة برمجة التطبيقات 200 عند التحقق من صحة مؤشر واحد أو أكثر ونشره بنجاح.
400 تنسيق غير صحيح. شيء ما في الطلب غير منسق بشكل صحيح.
401 Unauthorized.
404 لم يتم العثور على الملف. يحدث هذا الخطأ عادة عندما لا يتم العثور على معرف مساحة العمل.
429 لقد تجاوز عدد الطلبات في دقيقة واحدة.
500 خطأ في الخادم. عادة ما يكون خطأ في API أو خدمات Microsoft Sentinel.

نص الاستجابة عبارة عن صفيف من رسائل الخطأ بتنسيق JSON:

اسم الحقل نوع البيانات ‏‏الوصف
أخطاء صفيف من كائنات الخطأ قائمة أخطاء التحقق من الصحة

كائن الخطأ

اسم الحقل نوع البيانات ‏‏الوصف
recordIndex العدد الصحيح فهرس المؤشرات في الطلب
رسائل الخطأ مصفوفة السلاسل رسائل خطأ

قيود الخانق لواجهة برمجة التطبيقات

يتم تطبيق جميع الحدود لكل مستخدم:

  • 100 مؤشر لكل طلب.
  • 100 طلب في الدقيقة.

إذا كان هناك طلبات أكثر من الحد الأقصى، 429 يتم إرجاع رمز حالة http في رأس الاستجابة مع نص الاستجابة التالي:

{
    "statusCode": 429,
    "message": "Rate limit is exceeded. Try again in <number of seconds> seconds."
}

حوالي 10,000 مؤشر في الدقيقة هو الحد الأقصى لمعدل النقل قبل تلقي خطأ التقييد.

هيئة طلب العينة

{
    "sourcesystem": "test", 
    "indicators":[
        {
            "type": "indicator",
            "spec_version": "2.1",
            "id": "indicator--10000003-71a2-445c-ab86-927291df48f8", 
            "name": "Test Indicator 1",
            "created": "2010-02-26T18:29:07.778Z", 
            "modified": "2011-02-26T18:29:07.778Z",
            "pattern": "[ipv4-addr:value = '172.29.6.7']", 
            "pattern_type": "stix",
            "valid_from": "2015-02-26T18:29:07.778Z"
        },
        {
            "type": "indicator",
            "spec_version": "2.1",
            "id": "indicator--67e62408-e3de-4783-9480-f595d4fdae52", 
            "created": "2023-01-01T18:29:07.778Z",
            "modified": "2025-02-26T18:29:07.778Z",
            "created_by_ref": "identity--19f33886-d196-468e-a14d-f37ff0658ba7", 
            "revoked": false,
            "labels": [
                "label 1",
                "label 2"
            ],
            "confidence": 55, 
            "lang": "en", 
            "external_references": [
                {
                    "source_name": "External Test Source", 
                    "description": "Test Report",
                    "external_id": "e8085f3f-f2b8-4156-a86d-0918c98c498f", 
                    "url": "https://fabrikam.com//testreport.json",
                    "hashes": {
                        "SHA-256": "6db12788c37247f2316052e142f42f4b259d6561751e5f401a1ae2a6df9c674b"
                    }
                }
            ],
            "object_marking_refs": [
                "marking-definition--613f2e26-407d-48c7-9eca-b8e91df99dc9"
            ],
            "granular_markings": [
                {
                    "marking_ref": "marking-definition--beb3ec79-03aa-4594-ad24-09982d399b80", 
                    "selectors": [ "description", "labels" ],
                    "lang": "en"
                }
            ],
            "name": "Test Indicator 2",
            "description": "This is a test indicator to demo valid fields", 
            "indicator_types": [
                "threatstream-severity-low", "threatstream-confidence-80"
            ],
            "pattern": "[ipv4-addr:value = '192.168.1.1']", 
            "pattern_type": "stix",
            "pattern_version": "2.1",
            "valid_from": "2023-01-01T18:29:07.778Z", 
            "valid_until": "2025-02-26T18:29:07.778Z",
            "kill_chain_phases": [
                {
                    "kill_chain_name": "lockheed-martin-cyber-kill-chain", 
                    "phase_name": "reconnaissance"
                }
            ]
        }
    ]
}

نموذج نص الاستجابة مع خطأ التحقق من الصحة

إذا تم التحقق من صحة جميع المؤشرات بنجاح، يتم إرجاع حالة HTTP 200 مع نص استجابة فارغ.

إذا فشل التحقق من الصحة لمؤشر واحد أو أكثر، يتم إرجاع نص الاستجابة بمزيد من المعلومات. على سبيل المثال، إذا أرسلت صفيفا بأربعة مؤشرات، وكانت المؤشرات الثلاثة الأولى جيدة ولكن الرابع لا يحتوي على id (حقل مطلوب)، إنشاء استجابة رمز حالة HTTP 200 مع النص الأساسي التالي:

{
    "errors": [
        {
            "recordIndex":3, 
            "errorMessages": [
                "Error for Property=id: Required property is missing. Actual value: NULL."
            ]
        }
    ]
}

يتم إرسال المؤشرات كصفيف، لذلك recordIndex يبدأ في 0.

الخطوة التالية

واجهة برمجة التطبيقات هذه قديمة. يرجى الترحيل لاستخدام واجهة برمجة تطبيقات كائنات STIX لتحميل التحليل الذكي للمخاطر. لمزيد من المعلومات، راجع واجهة برمجة تطبيقات كائنات STIX.

  • Last updated on