[DOCS] Microsoft Defender for Endpoint connector (#219999)

docs/reference/connectors-kibana.md

@@ -1,11 +1,16 @@
 ---
 mapped_pages:
   - https://www.elastic.co/guide/en/kibana/current/action-types.html
+navigation_title: Connectors
+applies_to:
+  serverless: ga
+  stack: ga
 ---
+# Kibana connectors [action-types]
 
-# Connectors (Kibana) [action-types]
-
-Connectors provide a central place to store connection information for services and integrations with Elastic or third party systems. Actions are instantiations of a connector that are linked to rules and run as background tasks on the {{kib}} server when rule conditions are met. {{kib}} provides the following types of connectors:
+Connectors provide a central place to store connection information for services and integrations with Elastic or third party systems.
+Actions are instantiations of a connector that are linked to rules and run as background tasks on the {{kib}} server when rule conditions are met.
+{{kib}} provides the following types of connectors:
 
 * [{{bedrock}}](/reference/connectors-kibana/bedrock-action-type.md): Send a request to {{bedrock}}.
 * [Cases](/reference/connectors-kibana/cases-action-type.md): Add alerts to cases.
@@ -16,6 +21,7 @@ Connectors provide a central place to store connection information for services
 * [{{ibm-r}}](/reference/connectors-kibana/resilient-action-type.md): Create an incident in {{ibm-r}}.
 * [Index](/reference/connectors-kibana/index-action-type.md): Index data into Elasticsearch.
 * [Jira](/reference/connectors-kibana/jira-action-type.md): Create an incident in Jira.
+* [Microsoft Defender for Endpoint](/reference/connectors-kibana/defender-action-type.md): Send requests to  Microsoft Defender-enrolled hosts.
 * [Microsoft Teams](/reference/connectors-kibana/teams-action-type.md): Send a message to a Microsoft Teams channel.
 * [Observability AI Assistant](/reference/connectors-kibana/obs-ai-assistant-action-type.md): Add AI-driven insights and custom actions to your workflow.
 * [OpenAI](/reference/connectors-kibana/openai-action-type.md): Send a request to OpenAI.

docs/reference/connectors-kibana/defender-action-type.md

@@ -0,0 +1,64 @@
+---
+navigation_title: "Microsoft Defender for Endpoint"
+applies_to:
+  stack: ga
+  serverless:
+    observability: ga
+    security: ga
+---
+# Microsoft Defender for Endpoint connector and action
+
+The Microsoft Defender for Endpoint connector enables you to perform actions on Microsoft Defender-enrolled hosts.
+
+## Create connectors in {{kib}}
+
+You can create connectors in **{{stack-manage-app}} > {{connectors-ui}}** or as needed when you're creating a rule. For example:
+
+:::{image} ../images/defender-connector.png
+:alt: Microsoft Defender for Endpoint connector
+:screenshot:
+:::
+
+### Connector configuration
+
+Microsoft Defender for Endpoint connectors have the following configuration properties:
+
+API URL
+:   The URL of the Microsoft Defender for Endpoint API. If you are using the [`xpack.actions.allowedHosts`](/reference/configuration-reference/alerting-settings.md#action-settings) setting, make sure the hostname is added to the allowed hosts.
+
+Application client ID
+:   The application (client) identifier for your app in the Azure portal.
+
+Client secret value
+:   The client secret for your app in the Azure portal.
+
+Name
+:   The name of the connector.
+
+OAuth Scope
+:   The OAuth scopes or permission sets for the Microsoft Defender for Endpoint API.
+
+OAuth Server URL
+:   The OAuth server URL where authentication is sent and received for the Microsoft Defender for Endpoint API.
+
+Tenant ID
+:   The tenant identifier for your app in the Azure portal.
+
+## Test connectors
+
+You can test connectors as you're creating or editing the connector in {{kib}}.
+For example:
+
+:::{image} ../images/defender-connector-test.png
+:alt: Microsoft Defender for Endpoint connector test
+:screenshot:
+:::
+
+## Configure Microsoft Defender for Endpoint
+
+Before you create the connector, you must create a new application on your Azure domain.
+The procedure to create an application is found in the [Microsoft Defender documentation](https://learn.microsoft.com/en-us/defender-endpoint/api/exposed-apis-create-app-webapp).
+
+Make note of the client ID, client secret, and tenant ID, since you must provide this information when you create your connector.
+
+<!-- TBD: Are there minimal API permissions required? -->

docs/reference/toc.yml

@@ -37,6 +37,7 @@ toc:
       - file: connectors-kibana/resilient-action-type.md
       - file: connectors-kibana/index-action-type.md
       - file: connectors-kibana/jira-action-type.md
+      - file: connectors-kibana/defender-action-type.md
       - file: connectors-kibana/teams-action-type.md
       - file: connectors-kibana/obs-ai-assistant-action-type.md
       - file: connectors-kibana/openai-action-type.md

oas_docs/output/kibana.serverless.yaml

@@ -400,6 +400,7 @@ paths:
                     - $ref: '#/components/schemas/gemini_secrets'
                     - $ref: '#/components/schemas/resilient_secrets'
                     - $ref: '#/components/schemas/jira_secrets'
+                    - $ref: '#/components/schemas/defender_secrets'
                     - $ref: '#/components/schemas/teams_secrets'
                     - $ref: '#/components/schemas/genai_secrets'
                     - $ref: '#/components/schemas/opsgenie_secrets'
@@ -517,6 +518,7 @@ paths:
                     - $ref: '#/components/schemas/resilient_config'
                     - $ref: '#/components/schemas/index_config'
                     - $ref: '#/components/schemas/jira_config'
+                    - $ref: '#/components/schemas/defender_config'
                     - $ref: '#/components/schemas/genai_azure_config'
                     - $ref: '#/components/schemas/genai_openai_config'
                     - $ref: '#/components/schemas/opsgenie_config'
@@ -69728,6 +69730,30 @@ components:
         projectKey:
           description: The Jira project key.
           type: string
+    defender_config:
+      title: Connector request properties for a Microsoft Defender for Endpoint connector
+      required:
+        - apiUrl
+        - projectKey
+      description: Defines properties for connectors when type is `.microsoft_defender_endpoint`.
+      type: object
+      properties:
+        apiUrl:
+          type: string
+          description: |
+            The URL of the Microsoft Defender for Endpoint API. If you are using the `xpack.actions.allowedHosts` setting, make sure the hostname is added to the allowed hosts.
+        clientId:
+          type: string
+          description: The application (client) identifier for your app in the Azure portal.
+        oAuthScope:
+          type: string
+          description: The OAuth scopes or permission sets for the Microsoft Defender for Endpoint API.
+        oAuthServerUrl:
+          type: string
+          description: The OAuth server URL where authentication is sent and received for the Microsoft Defender for Endpoint API.
+        tenantId:
+          description: The tenant identifier for your app in the Azure portal.
+          type: string
     genai_azure_config:
       title: Connector request properties for an OpenAI connector that uses Azure OpenAI
       description: |
@@ -70560,6 +70586,16 @@ components:
           description: |
             A password for HTTP basic authentication. It is applicable only when `usesBasic` is `true`.
           type: string
+    defender_secrets:
+      title: Connector secrets properties for a Microsoft Defender for Endpoint connector
+      required:
+        - clientSecret
+      description: Defines secrets for connectors when type is `..microsoft_defender_endpoint`.
+      type: object
+      properties:
+        clientSecret:
+          description: The client secret for your app in the Azure portal.
+          type: string
     run_acknowledge_resolve_pagerduty:
       title: PagerDuty connector parameters
       description: Test an action that acknowledges or resolves a PagerDuty alert.

oas_docs/output/kibana.yaml

@@ -452,6 +452,7 @@ paths:
                     - $ref: '#/components/schemas/gemini_secrets'
                     - $ref: '#/components/schemas/resilient_secrets'
                     - $ref: '#/components/schemas/jira_secrets'
+                    - $ref: '#/components/schemas/defender_secrets'
                     - $ref: '#/components/schemas/teams_secrets'
                     - $ref: '#/components/schemas/genai_secrets'
                     - $ref: '#/components/schemas/opsgenie_secrets'
@@ -569,6 +570,7 @@ paths:
                     - $ref: '#/components/schemas/resilient_config'
                     - $ref: '#/components/schemas/index_config'
                     - $ref: '#/components/schemas/jira_config'
+                    - $ref: '#/components/schemas/defender_config'
                     - $ref: '#/components/schemas/genai_azure_config'
                     - $ref: '#/components/schemas/genai_openai_config'
                     - $ref: '#/components/schemas/opsgenie_config'
@@ -79635,6 +79637,30 @@ components:
         projectKey:
           description: The Jira project key.
           type: string
+    defender_config:
+      title: Connector request properties for a Microsoft Defender for Endpoint connector
+      required:
+        - apiUrl
+        - projectKey
+      description: Defines properties for connectors when type is `.microsoft_defender_endpoint`.
+      type: object
+      properties:
+        apiUrl:
+          type: string
+          description: |
+            The URL of the Microsoft Defender for Endpoint API. If you are using the `xpack.actions.allowedHosts` setting, make sure the hostname is added to the allowed hosts.
+        clientId:
+          type: string
+          description: The application (client) identifier for your app in the Azure portal.
+        oAuthScope:
+          type: string
+          description: The OAuth scopes or permission sets for the Microsoft Defender for Endpoint API.
+        oAuthServerUrl:
+          type: string
+          description: The OAuth server URL where authentication is sent and received for the Microsoft Defender for Endpoint API.
+        tenantId:
+          description: The tenant identifier for your app in the Azure portal.
+          type: string
     genai_azure_config:
       title: Connector request properties for an OpenAI connector that uses Azure OpenAI
       description: |
@@ -80467,6 +80493,16 @@ components:
           description: |
             A password for HTTP basic authentication. It is applicable only when `usesBasic` is `true`.
           type: string
+    defender_secrets:
+      title: Connector secrets properties for a Microsoft Defender for Endpoint connector
+      required:
+        - clientSecret
+      description: Defines secrets for connectors when type is `..microsoft_defender_endpoint`.
+      type: object
+      properties:
+        clientSecret:
+          description: The client secret for your app in the Azure portal.
+          type: string
     run_acknowledge_resolve_pagerduty:
       title: PagerDuty connector parameters
       description: Test an action that acknowledges or resolves a PagerDuty alert.

oas_docs/overlays/connectors.overlays.yaml

@@ -213,6 +213,8 @@ actions:
                     # Index (.index) N/A
                     # Jira (.jira)
                     - $ref: '../../x-pack/platform/plugins/shared/actions/docs/openapi/components/schemas/jira_secrets.yaml'
+                    # Microsoft Defender for Endpoint (.microsoft_defender_endpoint)
+                    - $ref: '../../x-pack/platform/plugins/shared/actions/docs/openapi/components/schemas/defender_secrets.yaml'
                     # Microsoft Teams (.teams)
                     - $ref: '../../x-pack/platform/plugins/shared/actions/docs/openapi/components/schemas/teams_secrets.yaml'
                     # Observability AI Assistant (.observability-ai-assistant) TBD
@@ -275,6 +277,8 @@ actions:
                     - $ref: '../../x-pack/platform/plugins/shared/actions/docs/openapi/components/schemas/index_config.yaml'
                     # Jira (.jira)
                     - $ref: '../../x-pack/platform/plugins/shared/actions/docs/openapi/components/schemas/jira_config.yaml'
+                    # Microsoft Defender for Endpoint (.microsoft_defender_endpoint)
+                    - $ref: '../../x-pack/platform/plugins/shared/actions/docs/openapi/components/schemas/defender_config.yaml'
                     # Microsoft Teams (.teams) N/A
                     # Observability AI Assistant (.observability-ai-assistant) TBD
                     # Azue OpenAI (.gen-ai)

x-pack/platform/plugins/shared/actions/docs/openapi/components/schemas/defender_config.yaml

@@ -0,0 +1,23 @@
+title: Connector request properties for a Microsoft Defender for Endpoint connector
+required:
+  - apiUrl
+  - projectKey
+description: Defines properties for connectors when type is `.microsoft_defender_endpoint`.
+type: object
+properties:
+  apiUrl:
+    type: string
+    description: >
+      The URL of the Microsoft Defender for Endpoint API. If you are using the `xpack.actions.allowedHosts` setting, make sure the hostname is added to the allowed hosts.
+  clientId:
+    type: string
+    description: The application (client) identifier for your app in the Azure portal.
+  oAuthScope:
+    type: string
+    description: The OAuth scopes or permission sets for the Microsoft Defender for Endpoint API.
+  oAuthServerUrl:
+    type: string
+    description: The OAuth server URL where authentication is sent and received for the Microsoft Defender for Endpoint API.
+  tenantId:
+    description: The tenant identifier for your app in the Azure portal.
+    type: string

x-pack/platform/plugins/shared/actions/docs/openapi/components/schemas/defender_secrets.yaml

@@ -0,0 +1,9 @@
+title: Connector secrets properties for a Microsoft Defender for Endpoint connector
+required:
+  - clientSecret
+description: Defines secrets for connectors when type is `..microsoft_defender_endpoint`.
+type: object
+properties:
+  clientSecret:
+    description: The client secret for your app in the Azure portal.
+    type: string