diff --git a/docs/reference/connectors-kibana.md b/docs/reference/connectors-kibana.md index 4de8a0fa4cbc7..e5aa417925876 100644 --- a/docs/reference/connectors-kibana.md +++ b/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. diff --git a/docs/reference/connectors-kibana/defender-action-type.md b/docs/reference/connectors-kibana/defender-action-type.md new file mode 100644 index 0000000000000..5d17fa553d696 --- /dev/null +++ b/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. + + \ No newline at end of file diff --git a/docs/reference/images/defender-connector-test.png b/docs/reference/images/defender-connector-test.png new file mode 100644 index 0000000000000..d4842a89e9881 Binary files /dev/null and b/docs/reference/images/defender-connector-test.png differ diff --git a/docs/reference/images/defender-connector.png b/docs/reference/images/defender-connector.png new file mode 100644 index 0000000000000..ea51bd0ef143a Binary files /dev/null and b/docs/reference/images/defender-connector.png differ diff --git a/docs/reference/toc.yml b/docs/reference/toc.yml index 6baffa2a51243..8c87e826b6b5c 100644 --- a/docs/reference/toc.yml +++ b/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 diff --git a/oas_docs/output/kibana.serverless.yaml b/oas_docs/output/kibana.serverless.yaml index b590e2605402d..2e55f9a79fe45 100644 --- a/oas_docs/output/kibana.serverless.yaml +++ b/oas_docs/output/kibana.serverless.yaml @@ -401,6 +401,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' @@ -518,6 +519,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' @@ -63277,6 +63279,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: | @@ -64109,6 +64135,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. diff --git a/oas_docs/output/kibana.yaml b/oas_docs/output/kibana.yaml index 7766cf57cb6c8..0d77ab36b4eba 100644 --- a/oas_docs/output/kibana.yaml +++ b/oas_docs/output/kibana.yaml @@ -447,6 +447,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' @@ -564,6 +565,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' @@ -69749,6 +69751,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: | @@ -70581,6 +70607,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. diff --git a/oas_docs/overlays/connectors.overlays.yaml b/oas_docs/overlays/connectors.overlays.yaml index 5622973106152..5252ff666355d 100644 --- a/oas_docs/overlays/connectors.overlays.yaml +++ b/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) diff --git a/x-pack/platform/plugins/shared/actions/docs/openapi/components/schemas/defender_config.yaml b/x-pack/platform/plugins/shared/actions/docs/openapi/components/schemas/defender_config.yaml new file mode 100644 index 0000000000000..faa96668bb24f --- /dev/null +++ b/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 \ No newline at end of file diff --git a/x-pack/platform/plugins/shared/actions/docs/openapi/components/schemas/defender_secrets.yaml b/x-pack/platform/plugins/shared/actions/docs/openapi/components/schemas/defender_secrets.yaml new file mode 100644 index 0000000000000..efb972208e7fb --- /dev/null +++ b/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