إشعار
يتطلب الوصول إلى هذه الصفحة تخويلاً. يمكنك محاولة تسجيل الدخول أو تغيير الدلائل.
يتطلب الوصول إلى هذه الصفحة تخويلاً. يمكنك محاولة تغيير الدلائل.
سمحت واجهة برمجة تطبيقات مؤشرات التحميل Microsoft Sentinel الأنظمة الأساسية للتحليل الذكي للمخاطر أو التطبيقات المخصصة باستيراد مؤشرات الاختراق بتنسيق STIX إلى مساحة عمل Microsoft Sentinel. يعمل هذا المستند كمرجع لواجهة برمجة التطبيقات القديمة.
هام
واجهة برمجة التطبيقات هذه قيد المعاينة ولكن لم تعد مستحسنة. استخدم واجهة برمجة تطبيقات كائنات STIX الجديدة في المعاينة لتحميل التحليل الذكي للمخاطر. لمزيد من المعلومات، راجع واجهة برمجة تطبيقات كائنات STIX. تتضمن الشروط التكميلية Azure Preview شروطا قانونية إضافية تنطبق على ميزات Azure الموجودة في الإصدار التجريبي أو المعاينة أو التي لم يتم إصدارها بعد في التوفر العام.
يحتوي استدعاء واجهة برمجة تطبيقات مؤشرات التحميل على خمسة مكونات:
- عنوان URI للطلب
- عنوان رسالة طلب HTTP
- نص رسالة طلب HTTP
- معالجة رأس رسالة استجابة HTTP اختياريا
- معالجة نص رسالة استجابة HTTP اختياريا
تسجيل تطبيق العميل الخاص بك مع Microsoft Entra ID
للمصادقة على Microsoft Sentinel، يتطلب الطلب إلى واجهة برمجة تطبيقات مؤشرات التحميل رمز وصول Microsoft Entra صالحا. لمزيد من المعلومات حول تسجيل التطبيق، راجع تسجيل تطبيق باستخدام النظام الأساسي للهويات في Microsoft أو راجع الخطوات الأساسية كجزء من إعداد موصل بيانات واجهة برمجة التطبيقات لمؤشرات التحميل.
الأذونات
تتطلب واجهة برمجة التطبيقات هذه منح تطبيق Microsoft Entra الاستدعاء دور المساهم Microsoft Sentinel على مستوى مساحة العمل.
إنشاء الطلب
يغطي هذا القسم المكونات الثلاثة الأولى من المكونات الخمسة التي تمت مناقشتها سابقا. تحتاج أولا إلى الحصول على الرمز المميز للوصول من Microsoft Entra ID، والذي تستخدمه لتجميع رأس رسالة الطلب.
الحصول على رمز مميز للوصول
احصل على رمز وصول 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 بالتنسيق التالي:
- وظيفه
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.nethttps://management.azure.com/https://management.azure.com
تجميع رسالة الطلب
كان هناك إصداران من واجهة برمجة التطبيقات القديمة. اعتمادا على نقطة النهاية، كان هناك حاجة إلى اسم صفيف مختلف في نص الطلب. تم تمثيل هذا أيضا بإصدارين من إجراء موصل تطبيق المنطق.
- اسم إجراء الموصل: التحليل الذكي للمخاطر - تحميل مؤشرات التسوية (مهمل)
- نقطه النهايه:
https://sentinelus.azure-api.net/{workspaceId}/threatintelligence:upload-indicators - اسم صفيف المؤشرات:
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 فقط، عندما لا يتم تعيين هذا الحقل، سيتم تعيين واجهة برمجة التطبيقات افتراضيا إلى 2.1 |
type (مطلوب) |
سلسله |
يجب أن تكون indicatorقيمة هذه الخاصية . |
created (مطلوب) |
الطابع الزمني | راجع القسم 3.2 للحصول على مواصفات هذه الخاصية الشائعة. |
modified (مطلوب) |
الطابع الزمني | راجع القسم 3.2 للحصول على مواصفات هذه الخاصية الشائعة. |
name (اختياري) |
سلسله | اسم يستخدم لتعريف المؤشر. يجب على المنتجين توفير هذه الخاصية لمساعدة المنتجات والمحللين على فهم ما يفعله هذا المؤشر بالفعل. |
description (اختياري) |
سلسله | وصف يوفر المزيد من التفاصيل والسياق حول المؤشر، بما في ذلك الغرض منه وخصائصه الرئيسية. يجب على المنتجين توفير هذه الخاصية لمساعدة المنتجات والمحللين على فهم ما يفعله هذا المؤشر بالفعل. |
indicator_types (اختياري) |
قائمة السلاسل | مجموعة من التصنيفات لهذا المؤشر. يجب أن تأتي قيم هذه الخاصية من نوع المؤشر-ov |
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 (اختياري) |
منطقيه | لم يعد منشئ العنصر يعتبر العناصر التي تم إبطالها صالحة. إبطال كائن دائم؛ id إنشاء الإصدارات المستقبلية من الكائن مع هذا.القيمة الافتراضية لهذه الخاصية خاطئة. |
labels (اختياري) |
قائمة السلاسل |
labels تحدد الخاصية مجموعة من المصطلحات المستخدمة لوصف هذا الكائن. يتم تعريف المصطلحات من قبل المستخدم أو مجموعة الثقة. سيتم عرض هذه التسميات كعلامات في Microsoft Sentinel. |
confidence (اختياري) |
صحيح |
confidence تحدد الخاصية الثقة التي يمتلكها المنشئ في صحة بياناته.
يجب أن تكون قيمة الثقة رقما في نطاق 0-100.يحتوي الملحق A على جدول من التعيينات المعيارية لمقاييس الثقة الأخرى التي يجب استخدامها عند تقديم قيمة الثقة في أحد هذه المقاييس. إذا لم تكن خاصية الثقة موجودة، فستكون ثقة المحتوى غير محددة. |
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 | غير المصرح به. |
| 404 | لم يتم العثور على الملف. يحدث هذا الخطأ عادة عندما لا يتم العثور على معرف مساحة العمل. |
| 429 | تم تجاوز عدد الطلبات في دقيقة واحدة. |
| 500 | خطأ في الخادم. عادة ما يكون خطأ في واجهة برمجة التطبيقات أو خدمات Microsoft Sentinel. |
نص الاستجابة عبارة عن صفيف من رسائل الخطأ بتنسيق JSON:
| اسم الحقل | نوع البيانات | الوصف |
|---|---|---|
| اخطاء | صفيف من عناصر الخطأ | قائمة أخطاء التحقق من الصحة |
كائن الخطأ
| اسم الحقل | نوع البيانات | الوصف |
|---|---|---|
| recordIndex | الباحث | فهرس المؤشرات في الطلب |
| errorMessages | صفيف من السلاسل | رسائل الخطأ |
حدود التقييد لواجهة برمجة التطبيقات
يتم تطبيق جميع الحدود لكل مستخدم:
- 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.