diff --git a/docs/management/action-types.asciidoc b/docs/management/action-types.asciidoc index e3b01ba0afcf7..868f235bcf3e1 100644 --- a/docs/management/action-types.asciidoc +++ b/docs/management/action-types.asciidoc @@ -50,6 +50,10 @@ a| <> | Create an incident in Jira. +a| <> + +| Send requests to Microsoft Defender-enrolled hosts. + a| <> | Send a message to a Microsoft Teams channel. diff --git a/docs/management/connectors/action-types/defender.asciidoc b/docs/management/connectors/action-types/defender.asciidoc new file mode 100644 index 0000000000000..ddeb46c0d85eb --- /dev/null +++ b/docs/management/connectors/action-types/defender.asciidoc @@ -0,0 +1,62 @@ +[[defender-action-type]] +== Microsoft Defender for Endpoint connector and action +++++ +Microsoft Defender for Endpoint +++++ + +The Microsoft Defender for Endpoint connector enables you to perform actions on Microsoft Defender-enrolled hosts. + +[float] +[[define-defender-ui]] +=== 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: + +[role="screenshot"] +image::management/connectors/images/defender-connector.png[Microsoft Defender for Endpoint connector] + +[float] +[[defender-connector-configuration]] +==== 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 <> 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. + +[float] +[[defender-action-configuration]] +=== Test connectors + +You can test connectors as you're creating or editing the connector in {kib}. For example: + +[role="screenshot"] +image::management/connectors/images/defender-connector-test.png[Microsoft Defender for Endpoint connector test] + +[float] +[[configuring-defender]] +=== 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 https://learn.microsoft.com/en-us/defender-endpoint/api/exposed-apis-create-app-webapp[Microsoft Defender documentation]. + +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/management/connectors/images/defender-connector-test.png b/docs/management/connectors/images/defender-connector-test.png new file mode 100644 index 0000000000000..d4842a89e9881 Binary files /dev/null and b/docs/management/connectors/images/defender-connector-test.png differ diff --git a/docs/management/connectors/images/defender-connector.png b/docs/management/connectors/images/defender-connector.png new file mode 100644 index 0000000000000..ea51bd0ef143a Binary files /dev/null and b/docs/management/connectors/images/defender-connector.png differ diff --git a/docs/management/connectors/index.asciidoc b/docs/management/connectors/index.asciidoc index c5c1ce4600c5d..10fd41b4326a6 100644 --- a/docs/management/connectors/index.asciidoc +++ b/docs/management/connectors/index.asciidoc @@ -10,6 +10,7 @@ include::action-types/gemini.asciidoc[leveloffset=+1] include::action-types/resilient.asciidoc[leveloffset=+1] include::action-types/index.asciidoc[leveloffset=+1] include::action-types/jira.asciidoc[leveloffset=+1] +include::action-types/defender.asciidoc[leveloffset=+1] include::action-types/teams.asciidoc[leveloffset=+1] include::action-types/obs-ai-assistant.asciidoc[leveloffset=+1] include::action-types/openai.asciidoc[leveloffset=+1] 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/oas_docs/output/kibana.serverless.yaml b/oas_docs/output/kibana.serverless.yaml index e059af49ad90b..05200f79154d8 100644 --- a/oas_docs/output/kibana.serverless.yaml +++ b/oas_docs/output/kibana.serverless.yaml @@ -354,6 +354,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' @@ -479,6 +480,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' @@ -60779,6 +60781,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: | @@ -61611,6 +61637,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 067ca0b77479e..268efb3e5087e 100644 --- a/oas_docs/output/kibana.yaml +++ b/oas_docs/output/kibana.yaml @@ -741,6 +741,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' @@ -858,6 +859,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' @@ -49876,6 +49878,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: | @@ -50708,6 +50734,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