Microsoft Sentinel موصلات دفع CCF (معاينة) - دليل بدء الاستخدام

يساعدك هذا الدليل على فهم وإنشاء وتوزيع الموصلات بدون تعليمات برمجية المستندة إلى الدفع Microsoft Sentinel باستخدام دفع إطار عمل الموصل بدون تعليمات برمجية (CCF) (معاينة).

ما هو دفع CCF؟

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

يوفر CCF Push العديد من الفوائد الرئيسية:

• تدفق البيانات التي يتحكم فيها التطبيق: يتحكم تطبيقك في وقت وكيفية إرسال البيانات، ما يتيح استراتيجيات تجميع ذكية واستخدام محسن للشبكة.
• الاستيعاب في الوقت الحقيقي: إرسال البيانات على الفور عند حدوث الأحداث، دون انتظار فواصل الاستقصاء.
• بنية مبسطة: لا حاجة للحفاظ على نقاط نهاية واجهة برمجة التطبيقات Sentinel للاستقصاء.
• التزويد المستند إلى القالب: ينشئ التوزيع قوالب ARM ل DCRs والجداول المخصصة وتسجيل التطبيق Entra وأسرار العميل - تتلقى تفاصيل الاتصال للتكوين في تطبيق الإرسال الخاص بك.
• المصادقة الآمنة: يستخدم تطبيقات Microsoft Entra مع OAuth 2.0 لتقديم البيانات الآمنة.

المتطلبات المسبقه

• قبل البدء، يجب أن يكون لديك حق الوصول إلى مستودع GitHub Azure-Sentinel لأدوات التعبئة والتغليف.
• أذونات Microsoft Entra:
  • إذن لإنشاء تسجيل تطبيق في Microsoft Entra ID. يتطلب عادة Entra دور مطور تطبيق معرف أو أعلى.
  • إذن لإنشاء تطبيق مع أسرار. إذا لم تمنح هذا الإذن، يفشل الموصل لأسباب أمنية.
  • يجب أن يكون للناشر الدور المناسب لاسترداد الرموز المميزة من تطبيق Microsoft Entra. هذه الرموز المميزة مطلوبة لمصادقة الطلبات إلى نقطة نهاية تجميع البيانات (DCE)، وهي نقطة النهاية حيث يدفع الموصل بياناته في نهاية المطاف. إذا لم يتمكن الموفر من استرداد الرموز المميزة، فلا يمكن إرسال البيانات إلى DCE.
• أذونات Microsoft Azure:
  • إذن لتعيين دور Monitoring Metrics Publisher على قاعدة جمع البيانات (DCR). يتطلب عادة Azure دور مالك RBAC أو مسؤول وصول المستخدم.

كيفية عمل دفع CCF

نموذج الدفع مقابل نموذج السحب

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

موصلات سحب CCF - مستندة إلى الاستقصاء:

في نموذج السحب، يستقصي Microsoft Sentinel بشكل دوري واجهة برمجة التطبيقات لاسترداد البيانات:

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

موصلات دفع CCF - تستند إلى الحدث:

في نموذج الدفع، يرسل تطبيقك البيانات مباشرة إلى Microsoft Sentinel:

• يبدأ التطبيق الخاص بك إرسال البيانات عند حدوث الأحداث.
• تصل البيانات في الوقت الفعلي تقريبا مع إنشاء الأحداث.
• لا تحتاج إلى الاحتفاظ بنقطة نهاية واجهة برمجة التطبيقات.
• يتحكم تطبيقك في التجميع والتوقيت وتحسين تدفق البيانات.

تدفق بيانات الدفع

يتكون تدفق بيانات دفع CCF من خمس خطوات رئيسية:

1. يمكنك نشر الموصل في Microsoft Sentinel.

2. Azure تلقائيا بإنشاء الموارد التالية:

   • تطبيق Microsoft Entra مع بيانات اعتماد
   • قاعدة جمع البيانات (DCR) - تحدد كيفية معالجة بياناتك
   • نقطة نهاية تجميع البيانات (DCE) - عنوان URL حيث ترسل البيانات
   • جدول سجل مخصص - حيث يتم تخزين بياناتك
   • تعيينات الأدوار - أذونات لتطبيق Entra

3. تتلقى تفاصيل الاتصال التالية:

   • معرف المستأجر
   • معرف التطبيق (العميل)
   • سر العميل
   • DCE URI (عنوان URL لنقطة النهاية)
   • معرف DCR غير قابل للتغيير
   • اسم Stream

4. يرسل تطبيقك البيانات التالية:

   • يحصل على رمز OAuth 2.0 المميز باستخدام CCF الذي تم إنشاؤه Entra بيانات اعتماد التطبيق. لمزيد من المعلومات، راجع تدفق بيانات اعتماد عميل OAuth 2.0
   • تنسيق الأحداث ك JSON مطابق لمخطط الجدول
   • بيانات POSTs إلى نقطة نهاية DCE

5. Azure معالجة البيانات وتخزينها:

   • يقوم DCRs بتحويل البيانات (تحويلات KQL الاختيارية)
   • تتم كتابة البيانات إلى الجدول المخصص في Log Analytics
   • تتوفر البيانات للاستعلامات والتحليلات والتنبيهات في Sentinel

البيانات الاصطناعية لدفع CCF

يتكون حل موصل CCF Push من أربعة مكونات رئيسية:

• تعريف الجدول المخصص
• قاعدة جمع البيانات (DCR)
• تعريف الموصل (UI)
• دفع تكوين الموصل

تعريف الجدول المخصص

ما هو: المخطط الذي يحدد بنية بياناتك في Log Analytics.

المتطلبات الرئيسية:

• يجب أن ينتهي اسم الجدول ب _CL (لاحقة السجل المخصصة).
• يجب أن يتضمن عمودا TimeGenerated (نوع التاريخ والوقت).
• أنواع الأعمدة: سلسلة، int، طويل، حقيقي، منطقي، التاريخ والوقت، ديناميكي، GUID.
• استخدم إصدار 2025-07-01 واجهة برمجة التطبيقات أو أحدث.
• لمزيد من المعلومات، راجع إنشاء جدول مخصص في Azure سجلات المراقبة.

مثال:

{
  "name": "ContosoSecurityAlerts_CL",
  "type": "Microsoft.OperationalInsights/workspaces/tables",
  "apiVersion": "2025-07-01",
  "properties": {
     "schema": {
        "name": "ContosoSecurityAlerts_CL",
        "columns": [
          {
             "name": "TimeGenerated",
             "type": "datetime"
          },
          {
             "name": "EventSeverity",
             "type": "string"
          },
          {
             "name": "EventType",
             "type": "string"
          },
          {
             "name": "UserName",
             "type": "string"
          },
          {
             "name": "SourceIP",
             "type": "string"
          },
          {
             "name": "DeviceId",
             "type": "string"
          },
          {
             "name": "AlertMessage",
             "type": "string"
          }
        ]
     }
  }
}

قاعدة جمع البيانات (DCR)

ما هو: يحدد كيفية استيعاب Azure Monitor لبياناتك ومعالجتها. لمزيد من المعلومات، راجع قواعد جمع البيانات في Azure Monitor.

ما يفعله:

• تحديد اسم دفق الإدخال (ما يستخدمه تطبيقك عند إرسال البيانات)
• تحديد تحويلات KQL الاختيارية لتشكيل البيانات وإثراءها
• توجيه البيانات إلى الجدول الوجهة
• ارتباطات إلى نقطة نهاية تجميع البيانات (DCE)

المكونات الرئيسية:

• streamDeclarations: يحدد بنية البيانات الواردة (يجب أن تتطابق مع ما يرسله تطبيقك)
• destinations: أين تذهب البيانات (مساحة عمل Log Analytics)
• dataFlows: مسار التحويل من دفق الإدخال إلى جدول الإخراج
• dataCollectionEndpointId: ارتباطات إلى DCE لاستيعاب البيانات

مثال:

{
  "name": "ContosoSecurityAlertsPushDCR",
  "apiVersion": "2021-09-01-preview",
  "type": "Microsoft.Insights/dataCollectionRules",
  "location": "[parameters('workspace-location')]",
  "properties": {
     "streamDeclarations": {
        "Custom-ContosoSecurityAlerts": {
          "columns": [
             {
                "name": "EventSeverity",
                "type": "string"
             },
             {
                "name": "EventType",
                "type": "string"
             },
             {
                "name": "UserName",
                "type": "string"
             },
             {
                "name": "SourceIP",
                "type": "string"
             },
             {
                "name": "DeviceId",
                "type": "string"
             },
             {
                "name": "AlertMessage",
                "type": "string"
             }
          ]
        }
     },
     "destinations": {
        "logAnalytics": [
          {
             "workspaceResourceId": "[variables('workspaceResourceId')]",
             "name": "clv2ws1"
          }
        ]
     },
     "dataFlows": [
        {
          "streams": [
             "Custom-ContosoSecurityAlerts"
          ],
          "destinations": [
             "clv2ws1"
          ],
          "transformKql": "source | extend TimeGenerated = now()",
          "outputStream": "Custom-ContosoSecurityAlerts_CL"
        }
     ],
     "dataCollectionEndpointId": "[concat('/subscriptions/',parameters('subscription'),'/resourceGroups/',parameters('resourceGroupName'),'/providers/Microsoft.Insights/dataCollectionEndpoints/',parameters('workspace'))]"
  }
}

مهم

• يجب أن يبدأ اسم Stream بالبادئةCustom-.
• transformKql يمكن أن يكون ببساطة "source" للتمرير، أو تضمين منطق KQL لتحويل البيانات.
• outputStream يجب أن يتطابق مع اسم الجدول الخاص بك مع Custom- البادئة واللاحقة _CL .

تعريف الموصل (UI)

يتحكم تعريف الموصل في كيفية ظهور الموصل في معرض موصل البيانات Microsoft Sentinel. لمزيد من المعلومات، راجع مرجع واجهة برمجة تطبيقات تعريفات موصل البيانات.

يتضمن تعريف الموصل ما يلي:

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

عناصر واجهة المستخدم الرئيسية:

• DeployPushConnectorButton: تشغيل التوزيع التلقائي للموارد
• CopyableLabel: يعرض تفاصيل الاتصال بعد التوزيع (يستخدم fillWith المعلمة)
• Markdown: يوفر إرشادات وسياقا منسقين
• IsConnectedQuery: التحقق من اتصال الموصل استنادا إلى البيانات الأخيرة

مثال على البنية (مختصر للوضوح):

{
    "name": "ContosoSecurityAlertsPush",
    "apiVersion": "2022-09-01-preview",
    "type": "Microsoft.SecurityInsights/dataConnectorDefinitions",
    "location": "[parameters('workspace-location')]",
    "kind": "Customizable",
    "properties": {
        "connectorUiConfig": {
            "id": "ContosoSecurityAlertsPush",
            "title": "Contoso Security Alerts (Push)",
            "publisher": "Contoso Corporation",
            "descriptionMarkdown": "The [Contoso Security Alerts](https://www.contoso.com/) connector provides the capability to push real-time security alerts from your Contoso application directly into Microsoft Sentinel using the Codeless Connector Framework (CCF) Push pattern. This connector ingests alert severity, event types, user information, and network details into a custom Log Analytics table for analysis, alerting, and visualization.",
            "graphQueries": [
                {
                    "metricName": "Security Alerts",
                    "legend": "ContosoSecurityAlerts_CL",
                    "baseQuery": "ContosoSecurityAlerts_CL"
                }
            ],
            "sampleQueries": [
                {
                    "description": "All security alerts",
                    "query": "ContosoSecurityAlerts_CL\n | sort by TimeGenerated desc"
                },
                {
                    "description": "Critical and High severity alerts",
                    "query": "ContosoSecurityAlerts_CL\n | where EventSeverity in ('Critical', 'High')\n | sort by TimeGenerated desc"
                }
            ],
            "dataTypes": [
                {
                    "name": "ContosoSecurityAlerts_CL",
                    "lastDataReceivedQuery": "ContosoSecurityAlerts_CL\n| summarize Time = max(TimeGenerated)\n| where isnotempty(Time)"
                }
            ],
            "connectivityCriteria": [
                {
                    "type": "IsConnectedQuery",
                    "value": [
                        "ContosoSecurityAlerts_CL\n| summarize LastLogReceived = max(TimeGenerated)\n| project IsConnected = LastLogReceived > ago(7d)"
                    ]
                }
            ],
            "availability": {
                "status": 1
            },
            "permissions": {
                "resourceProvider": [
                    {
                        "provider": "Microsoft.OperationalInsights/workspaces",
                        "permissionsDisplayText": "read and write permissions are required.",
                        "providerDisplayName": "Workspace",
                        "scope": "Workspace",
                        "requiredPermissions": {
                            "write": true,
                            "read": true,
                            "delete": true
                        }
                    }
                ],
                "customs": [
                    {
                        "name": "Microsoft Entra",
                        "description": "Permission to create an app registration in Microsoft Entra ID. Typically requires Entra ID Application Developer role or higher."
                    },
                    {
                        "name": "Microsoft Azure",
                        "description": "Permission to assign Monitoring Metrics Publisher role on data collection rule (DCR). Typically requires Azure RBAC Owner or User Access Administrator role."
                    }
                ]
            },
            "instructionSteps": [
                {
                    "title": "1. Create ARM Resources and Provide the Required Permissions",
                    "description": "This connector enables your Contoso application to push security alerts directly to Microsoft Sentinel via the Azure Monitor Ingestion API.",
                    "instructions": [
                        {
                            "type": "Markdown",
                            "parameters": {
                                "content": "#### Automated Configuration and Secure Data Ingestion with Entra Application \nClicking on \"Deploy\" will trigger the creation of a Log Analytics table and a Data Collection Rule (DCR). \nIt will then create an Entra application, link the DCR to it, and set the entered secret in the application. This setup enables data to be sent securely to the DCR using an Entra token."
                            }
                        },
                        {
                            "type": "DeployPushConnectorButton",
                            "parameters": {
                                "label": "Deploy Contoso Push connector resources",
                                "applicationDisplayName": "Contoso Security Alerts Push Connector Application"
                            }
                        }
                    ]
                },
                {
                    "title": "2. Configure Your Contoso Application",
                    "description": "Use the following parameters to configure your Contoso application to push security alerts to the workspace.",
                    "instructions": [
                        {
                            "type": "CopyableLabel",
                            "parameters": {
                                "label": "Tenant ID (Directory ID)",
                                "fillWith": [
                                    "TenantId"
                                ]
                            }
                        },
                        {
                            "type": "CopyableLabel",
                            "parameters": {
                                "label": "Entra App Registration Application ID",
                                "fillWith": [
                                    "ApplicationId"
                                ],
                                "placeholder": "Deploy push connector to get the App Registration Application ID"
                            }
                        },
                        {
                            "type": "CopyableLabel",
                            "parameters": {
                                "label": "Entra App Registration Secret",
                                "fillWith": [
                                    "ApplicationSecret"
                                ],
                                "placeholder": "Deploy push connector to get the App Registration Secret"
                            }
                        },
                        {
                            "type": "CopyableLabel",
                            "parameters": {
                                "label": "Data Collection Endpoint Uri",
                                "fillWith": [
                                    "DataCollectionEndpoint"
                                ],
                                "placeholder": "Deploy push connector to get the Data Collection Endpoint Uri"
                            }
                        },
                        {
                            "type": "CopyableLabel",
                            "parameters": {
                                "label": "Data Collection Rule Immutable ID",
                                "fillWith": [
                                    "DataCollectionRuleId"
                                ],
                                "placeholder": "Deploy push connector to get the Data Collection Rule Immutable ID"
                            }
                        },
                        {
                            "type": "CopyableLabel",
                            "parameters": {
                                "label": "Stream Name",
                                "value": "Custom-ContosoSecurityAlerts"
                            }
                        },
                        {
                            "type": "Markdown",
                            "parameters": {
                                "content": "#### Configure Contoso Application\nUpdate your Contoso application configuration with the above credentials to enable security alert push to Microsoft Sentinel.\n\nExample configuration:\njson\n{\n \"azure\": {\n \"tenant_id\": \"<Tenant ID>\",\n \"client_id\": \"<Application ID>\",\n \"client_secret\": \"<Application Secret>\",\n \"dce_endpoint\": \"<Data Collection Endpoint Uri>\",\n \"dcr_immutable_id\": \"<Data Collection Rule Immutable ID>\",\n \"stream_name\": \"Custom-ContosoSecurityAlerts\"\n }\n}\n"
                            }
                        }
                    ]
                }
            ]
        }
    }
}

مهم

• id يجب أن يكون in connectorUiConfig فريدا ومطابقا للمراجع في تكوين موصل البيانات.
• استخدم IsConnectedQuery لموصلات الإنتاج (يتحقق من صحة البيانات الأخيرة)، أو hasDataConnectors للتحقق من الصحة أبسط.
• fillWith يتم ملء المعلمات في CopyableLabel تلقائيا بعد التوزيع.
• تستخدم القيم الثابتة، مثل اسم الدفق، المعلمة value بدلا من fillWith.

دفع تكوين الموصل

تكوين موصل الدفع هو مثيل موصل البيانات الذي يربط تعريف الموصل بالموارد المنشورة.

تكوين موصل الدفع

• ربط تعريف الموصل (UI) بتطبيق DCR Entra المنشور
• يخزن تفاصيل المصادقة (معرف التطبيق، معرف كيان الخدمة)
• تكوين DCR السجلات (نقطة النهاية، المعرف غير القابل للتغيير، اسم الدفق)
• تمكين واجهة المستخدم من استرداد تفاصيل الاتصال وعرضها للمستخدمين

الخصائص الرئيسية:

• connectorDefinitionName: يجب أن يتطابق مع id في تعريف الموصل الخاص بك
• dcrConfig: يحتوي على نقطة نهاية DCR ومعرف القاعدة واسم الدفق
• auth: يحتوي على معرف التطبيق Entra ومعرف كيان الخدمة
• kind: يجب أن يكون "Push" لموصلات الدفع

مثل:

{
  "name": "ContosoSecurityAlertsPushDCR",
  "apiVersion": "2021-09-01-preview",
  "type": "Microsoft.Insights/dataCollectionRules",
  "location": "[parameters('workspace-location')]",
  "properties": {
    "streamDeclarations": {
      "Custom-ContosoSecurityAlerts": {
        "columns": [
          {
            "name": "EventSeverity",
            "type": "string"
          },
          {
            "name": "EventType",
            "type": "string"
          },
          {
            "name": "UserName",
            "type": "string"
          },
          {
            "name": "SourceIP",
            "type": "string"
          },
          {
            "name": "DeviceId",
            "type": "string"
          },
          {
            "name": "AlertMessage",
            "type": "string"
          }
        ]
      }
    },
    "destinations": {
      "logAnalytics": [
        {
          "workspaceResourceId": "[variables('workspaceResourceId')]",
          "name": "clv2ws1"
        }
      ]
    },
    "dataFlows": [
      {
        "streams": [
          "Custom-ContosoSecurityAlerts"
        ],
        "destinations": [
          "clv2ws1"
        ],
        "transformKql": "source | extend TimeGenerated = now()",
        "outputStream": "Custom-ContosoSecurityAlerts_CL"
      }
    ],
    "dataCollectionEndpointId": "[concat('/subscriptions/',parameters('subscription'),'/resourceGroups/',parameters('resourceGroupName'),'/providers/Microsoft.Insights/dataCollectionEndpoints/',parameters('workspace'))]"
  }
}

مهم

• يجب أن يتطابق connectorDefinitionName تماما مع تعريف idالموصل.
• يجب أن يتطابق streamName مع الدفق المعلن في DCR الخاص بك.
• يتم إنشاء هذا المورد تلقائيا أثناء النشر عندما يحدد المستخدمون الزر DeployPushConnector .

إنشاء موصل الدفع الأول

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

الهدف: إرسال تنبيهات الأمان من التطبيق الخاص بك إلى Sentinel في الوقت الحقيقي

يرسل تطبيقك بنية الحدث:

{
  "TimeGenerated": "2025-11-21T10:30:00Z",
  "EventSeverity": "Medium",
  "EventType": "LoginAlert",
  "UserName": "alice@contoso.com",
  "SourceIP": "192.168.1.100",
  "DeviceId": "device-12345",
  "AlertMessage": "Multiple failed login attempts detected"
}

دليل خطوة بخطوة لإنشاء موصل الدفع

1. استنساخ مستودع Azure-Sentinel

   ثم قم بنسخ مستودع Azure-Sentinel الرسمي إلى جهازك المحلي. يحتوي هذا المستودع على أدوات التعبئة ويوفر بنية الحل القياسية.

   1. نسخ المستودع
      git clone https://github.com/<YOUR_FORK>/Azure-Sentinel.git

   2. انتقل إلى دليل الحلول cd Azure-Sentinel/Solutions
      تتضمن بنية المستودع ما يلي:

   • Tools/Create-Azure-Sentinel-Solution/V3/
   • يحتوي على البرنامج النصي للتغليف createSolutionV3.ps1
   • الحلول/ المكان الذي ستقوم فيه بإنشاء حل الموصل

2. إنشاء بنية مجلد الحل الخاص بك إنشاء دليل حل جديد داخل المجلد الحلول/ باتباع اصطلاح التسمية القياسي. إنشاء دلائل الحلول (من Azure-Sentinel/الحلول/)

   mkdir ContosoSecurityAlerts
   cd ContosoSecurityAlerts
   mkdir Data
   mkdir "Data Connectors"
   mkdir "Data Connectors/ContosoSecurityAlerts_ccf"
   

   تبدو بنية المجلد كما يلي:

   Sentinel Azure/
    └── الحلول/
       └── ContosoSecurityAlerts/
           ├── البيانات/
           └── موصلات البيانات/
               └── ContosoSecurityAlerts_ccf/

3. تعريف الجدول

   في المجلد ContosoSecurityAlerts_ccf، أنشئ ملفا باسم table.json باستخدام تعريف الجدول المخصص:

   {
     "name": "ContosoSecurityAlerts_CL",
     "type": "Microsoft.OperationalInsights/workspaces/tables",
     "apiVersion": "2025-07-01",
     "properties": {
       "schema": {
         "name": "ContosoSecurityAlerts_CL",
         "columns": [
           {
             "name": "TimeGenerated",
             "type": "datetime"
           },
           {
             "name": "EventSeverity",
             "type": "string"
           },
           {
             "name": "EventType",
             "type": "string"
           },
           {
             "name": "UserName",
             "type": "string"
           },
           {
             "name": "SourceIP",
             "type": "string"
           },
           {
             "name": "DeviceId",
             "type": "string"
           },
           {
             "name": "AlertMessage",
             "type": "string"
           }
         ]
       }
     }
   }
   

4. إنشاء DCR

   في المجلد ContosoSecurityAlerts_ccf، أنشئ ملفا باسم DCR.json يحدد دفق الإدخال ويوجه البيانات إلى الجدول الخاص بك:

   {
     "name": "ContosoSecurityAlertsPushDCR",
     "apiVersion": "2021-09-01-preview",
     "type": "Microsoft.Insights/dataCollectionRules",
     "location": "[parameters('workspace-location')]",
     "properties": {
       "streamDeclarations": {
         "Custom-ContosoSecurityAlerts": {
           "columns": [
             {
               "name": "EventSeverity",
               "type": "string"
             },
             {
               "name": "EventType",
               "type": "string"
             },
             {
               "name": "UserName",
               "type": "string"
             },
             {
               "name": "SourceIP",
               "type": "string"
             },
             {
               "name": "DeviceId",
               "type": "string"
             },
             {
               "name": "AlertMessage",
               "type": "string"
             }
           ]
         }
       },
       "destinations": {
         "logAnalytics": [
           {
             "workspaceResourceId": "[variables('workspaceResourceId')]",
             "name": "clv2ws1"
           }
         ]
       },
       "dataFlows": [
         {
           "streams": [
             "Custom-ContosoSecurityAlerts"
           ],
           "destinations": [
             "clv2ws1"
           ],
           "transformKql": "source | extend TimeGenerated = now()",
           "outputStream": "Custom-ContosoSecurityAlerts_CL"
         }
       ],
       "dataCollectionEndpointId": "[concat('/subscriptions/',parameters('subscription'),'/resourceGroups/',parameters('resourceGroupName'),'/providers/Microsoft.Insights/    dataCollectionEndpoints/',parameters('workspace'))]"
     }
   }
   

5. إنشاء تعريف الموصل

   في المجلد ContosoSecurityAlerts_ccf أنشئ ملفا باسم connectorDefinition.json يحدد كيفية تفاعل المستخدمين مع الموصل في Sentinel:

   {
       "name": "ContosoSecurityAlertsPush",
       "apiVersion": "2022-09-01-preview",
       "type": "Microsoft.SecurityInsights/dataConnectorDefinitions",
       "location": "[parameters('workspace-location')]",
       "kind": "Customizable",
       "properties": {
           "connectorUiConfig": {
               "id": "ContosoSecurityAlertsPush",
               "title": "Contoso Security Alerts (Push)",
               "publisher": "Contoso Corporation",
               "descriptionMarkdown": "The [Contoso Security Alerts](https://www.contoso.com/) connector provides the capability to push real-time security alerts from your   Contoso application directly into Microsoft Sentinel using the Codeless Connector Framework (CCF) Push pattern. This connector ingests alert severity, event  types, user information, and network details into a custom Log Analytics table for analysis, alerting, and visualization.",
               "graphQueries": [
                   {
                       "metricName": "Security Alerts",
                       "legend": "ContosoSecurityAlerts_CL",
                       "baseQuery": "ContosoSecurityAlerts_CL"
                   }
               ],
               "sampleQueries": [
                   {
                       "description": "All security alerts",
                       "query": "ContosoSecurityAlerts_CL\n | sort by TimeGenerated desc"
                   },
                   {
                       "description": "Critical and High severity alerts",
                       "query": "ContosoSecurityAlerts_CL\n | where EventSeverity in ('Critical', 'High')\n | sort by TimeGenerated desc"
                   }
               ],
               "dataTypes": [
                   {
                       "name": "ContosoSecurityAlerts_CL",
                       "lastDataReceivedQuery": "ContosoSecurityAlerts_CL\n| summarize Time = max(TimeGenerated)\n| where isnotempty(Time)"
                   }
               ],
               "connectivityCriteria": [
                   {
                       "type": "IsConnectedQuery",
                       "value": [
                           "ContosoSecurityAlerts_CL\n| summarize LastLogReceived = max(TimeGenerated)\n| project IsConnected = LastLogReceived > ago(7d)"
                       ]
                   }
               ],
               "availability": {
                   "status": 1
               },
               "permissions": {
                   "resourceProvider": [
                       {
                           "provider": "Microsoft.OperationalInsights/workspaces",
                           "permissionsDisplayText": "read and write permissions are required.",
                           "providerDisplayName": "Workspace",
                           "scope": "Workspace",
                           "requiredPermissions": {
                               "write": true,
                               "read": true,
                               "delete": true
                           }
                       }
                   ],
                   "customs": [
                       {
                           "name": "Microsoft Entra",
                           "description": "Permission to create an app registration in Microsoft Entra ID. Typically requires Entra ID Application Developer role or higher."
                       },
                       {
                           "name": "Microsoft Azure",
                           "description": "Permission to assign Monitoring Metrics Publisher role on data collection rule (DCR). Typically requires Azure RBAC Owner or User   Access Administrator role."
                       }
                   ]
               },
               "instructionSteps": [
                   {
                       "title": "1. Create ARM Resources and Provide the Required Permissions",
                       "description": "This connector enables your Contoso application to push security alerts directly to Microsoft Sentinel via the Azure Monitor Ingestion  API.",
                       "instructions": [
                           {
                               "type": "Markdown",
                               "parameters": {
                                   "content": "#### Automated Configuration and Secure Data Ingestion with Entra Application \nClicking on \"Deploy\" will trigger the creation    of a Log Analytics table and a Data Collection Rule (DCR). \nIt will then create an Entra application, link the DCR to it, and set the     entered secret in the application. This setup enables data to be sent securely to the DCR using an Entra token."
                               }
                           },
                           {
                               "type": "DeployPushConnectorButton",
                               "parameters": {
                                   "label": "Deploy Contoso Push connector resources",
                                   "applicationDisplayName": "Contoso Security Alerts Push Connector Application"
                               }
                           }
                       ]
                   },
                   {
                       "title": "2. Configure Your Contoso Application",
                       "description": "Use the following parameters to configure your Contoso application to push security alerts to the workspace.",
                       "instructions": [
                           {
                               "type": "CopyableLabel",
                               "parameters": {
                                   "label": "Tenant ID (Directory ID)",
                                   "fillWith": [
                                       "TenantId"
                                   ]
                               }
                           },
                           {
                               "type": "CopyableLabel",
                               "parameters": {
                                   "label": "Entra App Registration Application ID",
                                   "fillWith": [
                                       "ApplicationId"
                                   ],
                                   "placeholder": "Deploy push connector to get the App Registration Application ID"
                               }
                           },
                           {
                               "type": "CopyableLabel",
                               "parameters": {
                                   "label": "Entra App Registration Secret",
                                   "fillWith": [
                                       "ApplicationSecret"
                                   ],
                                   "placeholder": "Deploy push connector to get the App Registration Secret"
                               }
                           },
                           {
                               "type": "CopyableLabel",
                               "parameters": {
                                   "label": "Data Collection Endpoint Uri",
                                   "fillWith": [
                                       "DataCollectionEndpoint"
                                   ],
                                   "placeholder": "Deploy push connector to get the Data Collection Endpoint Uri"
                               }
                           },
                           {
                               "type": "CopyableLabel",
                               "parameters": {
                                   "label": "Data Collection Rule Immutable ID",
                                   "fillWith": [
                                       "DataCollectionRuleId"
                                   ],
                                   "placeholder": "Deploy push connector to get the Data Collection Rule Immutable ID"
                               }
                           },
                           {
                               "type": "CopyableLabel",
                               "parameters": {
                                   "label": "Stream Name",
                                   "value": "Custom-ContosoSecurityAlerts"
                               }
                           },
                           {
                               "type": "Markdown",
                               "parameters": {
                                   "content": "#### Configure Contoso Application\nUpdate your Contoso application configuration with the above credentials to enable security     alert push to Microsoft Sentinel.\n\nExample configuration:\njson\n{\n \"azure\": {\n \"tenant_id\": \"<Tenant ID>\",\n \"client_id\":  \"<Application ID>\",\n \"client_secret\": \"<Application Secret>\",\n \"dce_endpoint\": \"<Data Collection Endpoint Uri>\",\n   \"dcr_immutable_id\": \"<Data Collection Rule Immutable ID>\",\n \"stream_name\": \"Custom-ContosoSecurityAlerts\"\n }\n}\n"
                               }
                           }
                       ]
                   }
               ]
           }
       }
   }
   

6. إنشاء تكوين موصل البيانات

   في المجلد ContosoSecurityAlerts_ccf، أنشئ ملفا باسم dataConnector.json يربط تعريف الموصل بالموارد المنشورة:

   {
     "name": "ContosoSecurityAlertsPushConnectorPolling",
     "apiVersion": "2024-09-01",
     "type": "Microsoft.SecurityInsights/dataConnectors",
     "kind": "Push",
     "properties": {
       "connectorDefinitionName": "ContosoSecurityAlertsPush",
       "dcrConfig": {
         "streamName": "Custom-ContosoSecurityAlerts",
         "dataCollectionEndpoint": "[[parameters('dcrConfig').dataCollectionEndpoint]",
         "dataCollectionRuleImmutableId": "[[parameters('dcrConfig').dataCollectionRuleImmutableId]"
       },
       "auth": {
         "type": "Push",
         "AppId": "[[parameters('auth').appId]",
         "ServicePrincipalId": "[[parameters('auth').servicePrincipalId]"
       },
       "request": {
         "RetryCount": 1
       },
       "response": {
         "eventsJsonPaths": [
           "$"
         ]
       }
     }
   }
   

7. إنشاء بيانات تعريف الحل Files

   1. Solution_ContosoSecurityAlerts.json في مجلد البيانات، أنشئ Solution_ContosoSecurityAlerts.json بتفاصيل الحل:

      {
           "Name": "ContosoSecurityAlerts",
           "Author": "Contoso Corporation - support@contoso.com",
           "Logo": "<svg width=\"75px\" height=\"75px\" viewBox=\"0 0 75 75\" xmlns=\"http://www.w3.org/2000/svg\"><rect width=\"75\" height=\"75\" fill=\"#FF6B35\"/><text   x=\"37.   5\" y=\"45\" font-family=\"Arial\" font-size=\"18\" fill=\"white\" text-anchor=\"middle\" font-weight=\"bold\">CONTOSO</text></svg>",
           "Description": "The Contoso Security Alerts solution provides real-time security alert ingestion from your Contoso application into Microsoft Sentinel using the       Codeless Connector Framework (CCF) Push pattern. Your application pushes alert severity, event types, user information, and network details directly to Azure   Monitor     for analysis, alerting, and visualization.",
           "Data Connectors": [
                "Data Connectors/ContosoSecurityAlerts_ccf/connectorDefinition.json"
           ],
           "BasePath": "C:\\GitHub\\Azure-Sentinel\\Solutions\\ContosoSecurityAlerts",
           "Version": "1.0.0",
           "Metadata": "SolutionMetadata.json",
           "TemplateSpec": true,
           "Is1PConnector": false
      }
      

      مهم

      متطلبات الحقل الهامة:

      • BasePath: تحديث إلى المسار المحلي الفعلي إلى مستودع Azure-Sentinel
      • Metadata: يجب أن يكون مرجعا SolutionMetadata.json (تم إنشاؤه في الخطوة 6B)
      • Version: تعيين الإصدار الدلالي، على سبيل المثال، 3.0.0
      • TemplateSpec: دائما true لحلول مركز المحتوى
      • Is1Pconnector: تعيين إلى false للموصلات الشريكة/المخصصة

   2. إنشاء SolutionMetadata.json في جذر الحل

      في المجلد ContosoSecurityAlerts، قم بإنشاء SolutionMetadata.json في دليل جذر الحل (نفس مستوى مجلد البيانات):

      {
        "publisherId": "contoso",
        "offerId": "contoso-security-alerts",
        "firstPublishDate": "2025-01-01",
        "lastPublishDate": "2025-01-01",
        "providers": [
           "Contoso"
        ],
        "categories": {
           "domains": [
              "Security - Threat Protection",
              "Security - Cloud Security"
           ]
        },
        "support": {
           "name": "Contoso Corporation",
           "tier": "Partner",
           "link": "https://www.contoso.com/support"
        }
      }
      

      تحتاج إلى ملف SolutionMetadata.json لتغليف مركز المحتوى:

      • تتوقع أداة التعبئة والتغليف هذا الملف في جذر الحل
      • يحتوي على بيانات تعريف السوق لتوزيع مركز المحتوى

   3. إنشاء ReleaseNotes.md في جذر الحل

      الإصدار	تاريخ التعديل (DD-MM-YYYY)	تغيير السجل
      3.0.0	DD-MM-YYYYY	مثال على الحل

   قائمة التحقق من الصحة

   قبل المتابعة إلى الخطوة التالية، تحقق مما يلي:

   • لا يحتوي اسم المجلد على مسافات، على سبيل المثال ContosoSecurityAlerts
   • Name يتطابق الحقل في Solution_ContosoSecurityAlerts.json مع اسم المجلد تماما
   • SolutionMetadata.json موجود في جذر الحل (وليس في مجلد البيانات)
   • BasePath يشير إلى مسار مستودع Azure-Sentinel المحلي الفعلي
   • Metadata مراجع الحقول "SolutionMetadata.json"
   • publisherId ومطابقة offerId بين كلا الملفين

8. التحقق من بنية الحل

   تأكد من تطابق بنية المجلد مع التخطيط المطلوب مع جميع الملفات الموجودة:

   Azure-Sentinel/
   └── Solutions/
        └── ContosoSecurityAlerts/                         Folder name (no spaces)
             ├── Data/
             │   └── Solution_ContosoSecurityAlerts.json    From Step 7A
             ├── SolutionMetadata.json                      From Step 7B (at root)
             ├── ReleaseNotes.md                            From Step 7C
             └── Data Connectors/
                   └── ContosoSecurityAlerts_ccf/
                        ├── table.json                         From Step 3
                        ├── DCR.json                           From Step 4
                        ├── connectorDefinition.json           From Step 5
                        └── dataConnector.json                 From Step 6
   

9. حزم الحل الخاص بك

   استخدم أداة التعبئة والتغليف createSolutionV3.ps1 لإنشاء قالب توزيع ARM.

   # Navigate to the packaging tools directory (from Azure-Sentinel repository root)
   cd Tools/Create-Azure-Sentinel-Solution/V3
   
   # Run the packaging tool
   # When prompted for "Enter solution data folder path:", provide:
   # <REPO_ROOT>Solutions/ContosoSecurityAlerts/Data (Note! This path is absolute)
   .\createSolutionV3.ps1
   

   البرنامج النصي تلقائيا:

   • التحقق من صحة بنية البيانات/ المجلد
   • معالجة البيانات الاصطناعية للموصل

   الإخراج المتوقع:

   يعرض البرنامج النصي للتغليف التحقق من صحة arm-ttk (Azure Resource Manager Template Toolkit) الفاشلة. هذا الفشل متوقع وطبيعي لموصلات CCF Push:

   Failed arm-ttk (Test-AzTemplate): Package
   Failed arm-ttk (Test-AzTemplate) on solutions: Package
   ************Validating if Package Json files are valid or not***************
   File Solutions\ContosoSecurityAlerts\Package\createUiDefinition.json is a valid Json file!
   File Solutions\ContosoSecurityAlerts\Package\mainTemplate.json is a valid Json file!
   File Solutions\ContosoSecurityAlerts\Package\testParameters.json is a valid Json file!
   

   نجحت الحزمة إذا رأيت رسائل التحقق من صحة JSON الثلاث التي تؤكد الملفات الصالحة. يمكنك تجاهل arm-ttk فشل موصلات CCF Push.

   لمزيد من المعلومات، راجع وثائق أدوات حلول Azure-Sentinel.

10. نشر حزمة الحل

    انشر قالب ARM الذي تم إنشاؤه (حزمة/mainTemplate.json) إلى اشتراكك في Azure.

    1. في مدخل Azure، ابحث عن Deploy a custom template
    2. حدد إنشاء القالب الخاص بك في المحرر
    3. حدد تحميل الملف وحدد Package/mainTemplate.json من مجلد الإخراج
    4. حدد حفظ
    5. املأ معلمات التوزيع:
       • الاشتراك: اشتراكك في Azure
       • مجموعة الموارد: مجموعة الموارد التي تحتوي على مساحة عمل Sentinel
       • المنطقه: نفس المنطقة التي توجد بها مساحة عمل Sentinel
       • مساحه عمل: اسم مساحة عمل Log Analytics
    6. حدد Review + create، ثم Create

    يجعل هذا التوزيع الموصل متاحا في معرض موصلات البيانات Microsoft Sentinel.

    للحصول على خطوات مفصلة، راجع [التشغيل السريع: إنشاء وتوزيع قوالب ARM باستخدام مدخل Azure](/azure/azure-resource-manager/templates/ quickstart-create-templates-use-the-portal).

11. تمكين موصل البيانات

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

    1. في مدخل Azure، انتقل إلى مساحة عمل Microsoft Sentinel
    2. انتقل إلىموصلات بيانات>
    3. ابحث عن تنبيهات أمان Contoso وحددها (دفع)
    4. حدد فتح صفحة الموصل
    5. حدد الزر Deploy Contoso Security Alerts connector
    6. انتظر حتى يكتمل التوزيع (ينشئ جدولا مخصصا، DCR، DCE، Entra التطبيق مع بيانات الاعتماد)
    7. انسخ تفاصيل الاتصال التي تظهر:
       • معرف المستأجر
       • معرف التطبيق (العميل)
       • سر العميل
       • URI لنقطة نهاية تجميع البيانات
       • معرف قاعدة تجميع البيانات غير القابل للتغيير
       • اسم Stream:Custom-ContosoSecurityAlerts

12. تكوين التطبيق الخاص بك

    قم بتحديث التعليمات البرمجية للتطبيق الخاص بك باستخدام بيانات الاعتماد وتفاصيل الموارد من الخطوة 10. تستخدم التعليمات البرمجية تدفق بيانات اعتماد عميل OAuth 2.0 للمصادقة باستخدام Azure Monitor.

    تنبيه

    حماية بيانات الاعتماد الخاصة بك: لا تقم أبدا بتكوين بيانات اعتماد الرمز الثابت (معرف المستأجر، معرف التطبيق، سر العميل) مباشرة في التعليمات البرمجية للتطبيق الخاص بك أو تثبيتها في التحكم بالمصادر. استخدم حلول تخزين بيانات الاعتماد الآمنة مثل:

    • Azure Key Vault لتطبيقات الإنتاج
    • متغيرات البيئة أو ملفات التكوين (مستبعدة من التحكم بالمصادر)
    • الهويات المدارة عند الاقتضاء
    • أدوات إدارة البيانات السرية التي تشفر بيانات الاعتماد الثابتة

    التعليمات البرمجية لتطبيق Python المثال:

    يستخدم المثال التالي قيم العنصر النائب مثل <Your-Tenant-ID>. استبدل هذه القيم بمراجع آمنة لبيانات الاعتماد الفعلية.

    import requests
    import json
    from datetime import datetime, timezone
    
    # Connection details from Step 11
    
    tenant_id = "<Your-Tenant-ID>"
    app_id = "<Your-Application-ID>"
    app_secret = "<Your-Client-Secret>"
    dce_uri = "<Your-DCE-URI>"
    dcr_immutable_id = "<Your-DCR-Immutable-ID>"
    stream_name = "Custom-ContosoSecurityAlerts"
    
    
    **Get OAuth token**
    
    token_url = f"https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token"
    token_data = {
         "client_id": app_id,
         "scope": "https://monitor.azure.com//.default",
         "client_secret": app_secret,
         "grant_type": "client_credentials"
    }
    token_response = requests.post(token_url, data=token_data)
    access_token = token_response.json()["access_token"]
    
    
    # Create event matching your table schema
    
    event = [{
         "TimeGenerated": datetime.now(timezone.utc).isoformat(),
         "EventSeverity": "Medium",
         "EventType": "LoginAlert",
         "UserName": "alice@contoso.com",
         "SourceIP": "192.168.1.100",
         "DeviceId": "device-12345",
         "AlertMessage": "Multiple failed login attempts detected"
    }]
    
    
    # Send to Sentinel
    
    headers = {
         "Authorization": f"Bearer {access_token}",
         "Content-Type": "application/json"
    }
    upload_url = f"{dce_uri}/dataCollectionRules/{dcr_immutable_id}/streams/{stream_name}?api-version=2023-01-01"
    response = requests.post(upload_url, headers=headers, json=event)
    
    print(f"Status: {response.status_code}")
    print("Security alert sent to Sentinel!")
    

13. الاستعلام عن بياناتك

    بعد إرسال التنبيهات، استعلم في Sentinel. السماح من 5 إلى 10 دقائق للاستيعاب الأول.

    // View all recent alerts
    ContosoSecurityAlerts_CL
    | where TimeGenerated > ago(1h)
    | order by TimeGenerated desc
    
    // High severity alerts
    ContosoSecurityAlerts_CL
    | where EventSeverity == "High"
    | project TimeGenerated, EventType, UserName, SourceIP, AlertMessage
    
    // Alert summary by severity
    ContosoSecurityAlerts_CL
    | where TimeGenerated > ago(7d)
    | summarize Count=count() by EventSeverity
    

المحتوى ذو الصلة

الآن بعد أن فهمت موصلات CCF Push، اتبع الخطوات التالية:

1. تصميم مخطط البيانات - حدد الأحداث التي تريد إرسالها وحقولها.
2. إنشاء بيانات اصطناعية للموصل - إنشاء ملفات JSON الأربعة (الجدول، DCR، تعريف الموصل، موصل البيانات).
3. تنظيم بنية الحل - إعداد البيانات/ وموصلات البيانات/ المجلدات ذات التسمية المناسبة.
4. حزم الحل الخاص بك - استخدم createSolutionV3.ps1 لإنشاء قوالب التوزيع.
5. التوزيع والاختبار - التوزيع إلى مساحة عمل Sentinel والتحقق من صحة تدفق البيانات.
6. التكامل مع التطبيق الخاص بك - إضافة تعليمة برمجية لإرسال الأحداث في الوقت الحقيقي.
7. إنشاء تنبيهات ومصنفات - استخدم بياناتك لمراقبة الأمان.

موارد إضافية

وثائق CCF

• إنشاء موصل بدون تعليمات برمجية (CCF Pull) - موصلات مستندة إلى الاستقصاء.
• مرجع واجهة برمجة تطبيقات تعريفات موصل البيانات - دليل تكوين واجهة المستخدم.
• مرجع قواعد اتصال موصل البيانات - قواعد الاتصال لموصلات الاستقصاء.

Azure Monitor وجمع البيانات

• Azure Monitor Logs Ingestion API - Core API لإرسال البيانات.
• قواعد جمع البيانات في Azure Monitor - فهم DCRs.
• بنية قاعدة جمع البيانات - تفاصيل بنية DCR.
• نقاط نهاية جمع البيانات في Azure Monitor - تكوين DCE.
• البرنامج التعليمي: إرسال البيانات إلى Azure Monitor Logs باستخدام واجهة برمجة تطبيقات استيعاب السجلات - البرنامج التعليمي خطوة بخطوة.
• إنشاء جدول مخصص - دليل إنشاء جدول مخصص.

المصادقة والأمان

• تدفق بيانات اعتماد عميل OAuth 2.0 - كيفية عمل مصادقة التطبيق إلى الخدمة.
• النظام الأساسي للهويات في Microsoft رموز الوصول المميزة - فهم رموز OAuth المميزة.
• تسجيل تطبيق في Microsoft Entra ID - كيفية تسجيل تطبيق في Microsoft Entra ID.
• أفضل الممارسات لتسجيل التطبيق Azure AD - Entra أمان التطبيق.
• تعيين أدوار Azure باستخدام قوالب Azure Resource Manager (ARM) - تعيين الأدوار باستخدام القوالب.
• توصيات أمان قالب ARM - تأمين قوالب التوزيع.
• Azure مراقبة حدود الخدمة - حدود المعدل والحصص النسبية.

Microsoft Sentinel

• حول حلول Microsoft Sentinel - تغليف الموصلات كحلول.
• مراقبة صحة موصلات البيانات - مراقبة السلامة.
• مرجع قالب ARM لموصلات البيانات - مرجع واجهة برمجة التطبيقات الكامل.

الحصول على المساعدة

• بالنسبة لشركاء ISV الذين يبنون عمليات التكامل، اتصل بما يلي: azuresentinelpartner@microsoft.com
• للأسئلة التقنية، استخدم Microsoft Q&A مع العلامة "azure-sentinel".