From dd484d9a6de4e4fe5a30da248d4df1803b40728e Mon Sep 17 00:00:00 2001 From: Antoine Ryon Date: Tue, 26 Sep 2023 10:35:09 +0200 Subject: [PATCH 1/8] Add a new XDR use case --- .../playbook/notifications_using_playbooks.md | 41 +++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 42 insertions(+) create mode 100644 docs/xdr/usecases/playbook/notifications_using_playbooks.md diff --git a/docs/xdr/usecases/playbook/notifications_using_playbooks.md b/docs/xdr/usecases/playbook/notifications_using_playbooks.md new file mode 100644 index 0000000000..cfa8e29f5f --- /dev/null +++ b/docs/xdr/usecases/playbook/notifications_using_playbooks.md @@ -0,0 +1,41 @@ +# Send notifications to a Webhook using a playbook + +This use case describes how to send a notification to a third party system like Slack or Microsoft Teams using webhooks and a playbook. + +## Prerequisites + +- A Sekoia.io XDR licence +- The user that configures the Playbook should have a Role that contains: + * The SYMPHONY permissions +- An API Key with a Role that contains at least the following permission: + * SIC_READ_ALERTS + * SIC_READ_INTAKES + +> To create your API Key, follow this [documentation](../../../getting_started/manage_api_keys.md). + +## Create your playbook + +Playbook templates were created to ease the process of setting up the playbooks to send the notifications to Slack or Teams. + +- **Go to** the [Playbook page](https://app.sekoia.io/operations/playbooks) +- **Click** on `+ New Playbook` +- If multi-tenant is available, **select** the Community where the Playbook should be executed +- Choose the `Use a template` option +- Search for `Teams` or `Slack` depending on your needs +- Select the corresponding playbook and click on `Create` + +## Configure your playbook + +Once your playbook is created, the following configuration steps are required: + +- Open each `Sekoia.io` action and select the account that needs to be used to communicate with Sekoia.io APIs. You may have to create an account with the API key you created previously if no account exists. +- Open the `Send to Slack` or `Send to Teams` action and replace the URL with the URL of your webhook + +## Customize your notifications + +The Slack and Teams playbook templates are provided as examples of notifications that can be sent to these solutions, you can customize the playbooks to your needs by adding additionnal actions to retrieve more data from the alerts and events and add them to the payload sent. Keep in mind that the payload must match the format expected by the third parties. + +## External references + +- [Slack Incoming Webhooks](https://api.slack.com/messaging/webhooks) +- [Teams Incoming Webhooks](https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook) \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index bae55e1ed9..ae57a3d078 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -305,6 +305,7 @@ nav: - Palo Alto Cortex XSOAR: xdr/features/integrations/interconnect_sekoia_with_xsoar.md - Usecases: - Synchronize Alerts with an external tool: xdr/usecases/playbook/synchronize_alerts.md + - Send notifications to a Webhook using a playbook: xdr/usecases/playbook/notifications_using_playbooks.md - FAQ: - General: xdr/FAQ.md - Alerts: xdr/FAQ/Alerts_qa.md From ca2fec230a2bba6b799ac01d500acffaecf07f66 Mon Sep 17 00:00:00 2001 From: Antoine Ryon Date: Tue, 26 Sep 2023 10:44:26 +0200 Subject: [PATCH 2/8] Add reference to new page in notifications examples --- docs/getting_started/notifications-Examples.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/getting_started/notifications-Examples.md b/docs/getting_started/notifications-Examples.md index 3a5bdb60b1..4aa71fa46b 100644 --- a/docs/getting_started/notifications-Examples.md +++ b/docs/getting_started/notifications-Examples.md @@ -27,6 +27,7 @@ The “WebHook notification” will let you send message to interact with third !!! info You can’t use the WebHook notification mechanism to push information directly to third parties (such as Slack or Telegram), you have to use an intermediate server. To do so, you can use solutions like IFTTT or a simple HTTP server (see below). + There are also playbook templates that can be used to send notifications to Slack or Microsoft Teams directly using Webhooks, see this documentation for more information [Send notifications to a Webhook using a playbook](../xdr/usecases/playbook/notifications_using_playbooks.md Here’s an example of a posted content to a configured destination via the WebHook mechanism: From e3129d9dba948bbfd5ae4e2621c2cc1a668763a3 Mon Sep 17 00:00:00 2001 From: Antoine Ryon Date: Tue, 26 Sep 2023 10:46:15 +0200 Subject: [PATCH 3/8] Fix missing parenthesis --- docs/getting_started/notifications-Examples.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting_started/notifications-Examples.md b/docs/getting_started/notifications-Examples.md index 4aa71fa46b..9949bef40a 100644 --- a/docs/getting_started/notifications-Examples.md +++ b/docs/getting_started/notifications-Examples.md @@ -27,7 +27,7 @@ The “WebHook notification” will let you send message to interact with third !!! info You can’t use the WebHook notification mechanism to push information directly to third parties (such as Slack or Telegram), you have to use an intermediate server. To do so, you can use solutions like IFTTT or a simple HTTP server (see below). - There are also playbook templates that can be used to send notifications to Slack or Microsoft Teams directly using Webhooks, see this documentation for more information [Send notifications to a Webhook using a playbook](../xdr/usecases/playbook/notifications_using_playbooks.md + There are also playbook templates that can be used to send notifications to Slack or Microsoft Teams directly using Webhooks, see this documentation for more information [Send notifications to a Webhook using a playbook](../xdr/usecases/playbook/notifications_using_playbooks.md) Here’s an example of a posted content to a configured destination via the WebHook mechanism: From c3c2eff6482ce2de7d6464de4feeb8da4c2e3762 Mon Sep 17 00:00:00 2001 From: Antoine Ryon <80452887+TonioRyo@users.noreply.github.com> Date: Tue, 26 Sep 2023 11:15:48 +0200 Subject: [PATCH 4/8] Update docs/xdr/usecases/playbook/notifications_using_playbooks.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sébastien Quioc --- docs/xdr/usecases/playbook/notifications_using_playbooks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/xdr/usecases/playbook/notifications_using_playbooks.md b/docs/xdr/usecases/playbook/notifications_using_playbooks.md index cfa8e29f5f..b8891a2625 100644 --- a/docs/xdr/usecases/playbook/notifications_using_playbooks.md +++ b/docs/xdr/usecases/playbook/notifications_using_playbooks.md @@ -9,7 +9,7 @@ This use case describes how to send a notification to a third party system like * The SYMPHONY permissions - An API Key with a Role that contains at least the following permission: * SIC_READ_ALERTS - * SIC_READ_INTAKES + * SIC_READ_INTAKES > To create your API Key, follow this [documentation](../../../getting_started/manage_api_keys.md). From 8ff2695b68452496a5d86f45299ae5a88b9d9424 Mon Sep 17 00:00:00 2001 From: Antoine Ryon <80452887+TonioRyo@users.noreply.github.com> Date: Tue, 26 Sep 2023 11:15:59 +0200 Subject: [PATCH 5/8] Update docs/getting_started/notifications-Examples.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sébastien Quioc --- docs/getting_started/notifications-Examples.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting_started/notifications-Examples.md b/docs/getting_started/notifications-Examples.md index 9949bef40a..88c96fe2ea 100644 --- a/docs/getting_started/notifications-Examples.md +++ b/docs/getting_started/notifications-Examples.md @@ -27,7 +27,7 @@ The “WebHook notification” will let you send message to interact with third !!! info You can’t use the WebHook notification mechanism to push information directly to third parties (such as Slack or Telegram), you have to use an intermediate server. To do so, you can use solutions like IFTTT or a simple HTTP server (see below). - There are also playbook templates that can be used to send notifications to Slack or Microsoft Teams directly using Webhooks, see this documentation for more information [Send notifications to a Webhook using a playbook](../xdr/usecases/playbook/notifications_using_playbooks.md) + There are also playbook templates that can be used to send notifications to Slack or Microsoft Teams directly using Webhooks; See how to [send notifications to a Webhook using a playbook](../xdr/usecases/playbook/notifications_using_playbooks.md) for more information Here’s an example of a posted content to a configured destination via the WebHook mechanism: From 72995600789941f4cd34c82a9889e5ae5a5e766b Mon Sep 17 00:00:00 2001 From: Antoine Ryon <80452887+TonioRyo@users.noreply.github.com> Date: Tue, 26 Sep 2023 14:24:01 +0200 Subject: [PATCH 6/8] Update docs/getting_started/notifications-Examples.md Co-authored-by: Khaoula Ettaleb <49680698+ka0ula@users.noreply.github.com> --- docs/getting_started/notifications-Examples.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting_started/notifications-Examples.md b/docs/getting_started/notifications-Examples.md index 88c96fe2ea..1d833a9ed7 100644 --- a/docs/getting_started/notifications-Examples.md +++ b/docs/getting_started/notifications-Examples.md @@ -27,7 +27,7 @@ The “WebHook notification” will let you send message to interact with third !!! info You can’t use the WebHook notification mechanism to push information directly to third parties (such as Slack or Telegram), you have to use an intermediate server. To do so, you can use solutions like IFTTT or a simple HTTP server (see below). - There are also playbook templates that can be used to send notifications to Slack or Microsoft Teams directly using Webhooks; See how to [send notifications to a Webhook using a playbook](../xdr/usecases/playbook/notifications_using_playbooks.md) for more information + There are also playbook templates that can be used to send notifications to Slack or Microsoft Teams directly using Webhooks. See how to [send notifications to a Webhook using a playbook](../xdr/usecases/playbook/notifications_using_playbooks.md) for more information. Here’s an example of a posted content to a configured destination via the WebHook mechanism: From 20be52829f8a40195ae99ca4079d37b5ba1553cf Mon Sep 17 00:00:00 2001 From: Antoine Ryon <80452887+TonioRyo@users.noreply.github.com> Date: Tue, 26 Sep 2023 14:24:10 +0200 Subject: [PATCH 7/8] Update docs/xdr/usecases/playbook/notifications_using_playbooks.md Co-authored-by: Khaoula Ettaleb <49680698+ka0ula@users.noreply.github.com> --- docs/xdr/usecases/playbook/notifications_using_playbooks.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/xdr/usecases/playbook/notifications_using_playbooks.md b/docs/xdr/usecases/playbook/notifications_using_playbooks.md index b8891a2625..168dba57d9 100644 --- a/docs/xdr/usecases/playbook/notifications_using_playbooks.md +++ b/docs/xdr/usecases/playbook/notifications_using_playbooks.md @@ -17,6 +17,9 @@ This use case describes how to send a notification to a third party system like Playbook templates were created to ease the process of setting up the playbooks to send the notifications to Slack or Teams. +To create one, follow these steps: + + - **Go to** the [Playbook page](https://app.sekoia.io/operations/playbooks) - **Click** on `+ New Playbook` - If multi-tenant is available, **select** the Community where the Playbook should be executed From 6b152b78a8702508122ab5155fbebd48af6af3da Mon Sep 17 00:00:00 2001 From: Antoine Ryon <80452887+TonioRyo@users.noreply.github.com> Date: Tue, 26 Sep 2023 14:24:32 +0200 Subject: [PATCH 8/8] Update docs/xdr/usecases/playbook/notifications_using_playbooks.md Co-authored-by: Khaoula Ettaleb <49680698+ka0ula@users.noreply.github.com> --- docs/xdr/usecases/playbook/notifications_using_playbooks.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/xdr/usecases/playbook/notifications_using_playbooks.md b/docs/xdr/usecases/playbook/notifications_using_playbooks.md index 168dba57d9..c4abf0088e 100644 --- a/docs/xdr/usecases/playbook/notifications_using_playbooks.md +++ b/docs/xdr/usecases/playbook/notifications_using_playbooks.md @@ -36,7 +36,9 @@ Once your playbook is created, the following configuration steps are required: ## Customize your notifications -The Slack and Teams playbook templates are provided as examples of notifications that can be sent to these solutions, you can customize the playbooks to your needs by adding additionnal actions to retrieve more data from the alerts and events and add them to the payload sent. Keep in mind that the payload must match the format expected by the third parties. +The Slack and Teams playbook templates are provided as examples of notifications that can be sent to these solutions. You can customize the playbooks to suit your needs by adding additional actions to retrieve more data from the alerts and events and add them to the payload sent. + +Keep in mind that the payload must match the format expected by the third parties. ## External references