Notification examples
Examples
When your conditions are configured, you'll have to choose which actions should be triggered by the notification mechanism. You can enable one or more actions for each notification rule.
For instance, you can decide to send an e-mail AND send a message on a Mattermost channel.
SEKOIA.IO Notification
The “Notification” action allows you to send an in-app notification that will be made available across SEKOIA.IO. All notifications can be accessed from the bell icon
on the top right. By clicking there, the notification panel with all notifications will be displayed.
Email Notification
The “Email notification” will let you send an e-mail to an arbitrary address with the two different options:
- By default, simple notification content will be sent with a link to SEKOIA.IO page corresponding of the Condition(s) set up
- If you enable the
Enrich email with contextual infos
toggle, more contextual information related to your alert will be communicated.
Mattermost Notification
Mattermost is a popular professional chat service. The “Mattermost notification” will send messages to any Mattermost instance. To do so, you’ll have to configure a new Incoming Webhook
on your Mattermost instance and choose to which Mattermost channel the message should be sent to.
You can refer to the Mattermost documentation on how to create a new Mattermost “incoming webhook”.
WebHook Notification
The “WebHook notification” will let you send message to interact with third party softwares. Technical informations related to the event will be pushed to an HTTP server. That latter will be able to understand the received payload and act (for example, retrieve more information about the event itself via SEKOIA.IO APIs and then push notification to an internal messaging service).
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).
Here’s an example of a posted content to a configured destination via the WebHook mechanism:
{
"type": "alert",
"action": "created",
"attributes": {
"uuid": "5696845f-9ecf-4431-9f0f-48ee0ee2eff1",
"short_id": "ALEY4fqz8moo"
},
"metadata": {
"version": 2,
"created_at": "2022-01-14T15:06:57.398005+00:00",
"community_uuid": "d6cea089-0f36-46c4-a10a-0e4c2e20fb10",
"avatar_uuid": null,
"user_uuid": null,
"permissions": []
}
}
This payload is about a newly _created_ _alert_
which concerns the d6cea089-0f36-46c4-a10a-0e4c2e20fb10
community and which identifier is ALEY4fqz8moo
(or 5696845f-9ecf-4431-9f0f-48ee0ee2eff1
if you prefer the UUID form).
Here's the description of the payload fields description:
Payload title | Availability | Description |
---|---|---|
type |
Always | Event type, can be alert or content-proposal (for reports). More types will be added in the future |
action |
Always | Action that took place, can be created , updated , deleted . |
metadata |
Always | This object contains information around the event itself |
metadata.version |
Always | Version of the event, WebHook events are currently at version 2. |
metadata.created |
Always | Date of creation of the event. |
metadata.community_uuid |
Always | Community concerned by the event. |
metadata.avatar_uuid |
Always | Event that concerns only a single member of a community (not used for alerts or reports). |
metadata.user_uuid |
Always | Event that concerns only a single user of SEKOIA.IO. |
metadata.permissions |
Always | Unused. |
attributes.uuid |
Alert specific | Unique identifier of the alert (UUID). Can be used to talk to the Alert API. |
attributes.short_id |
Alert specific | Human readable alert unique identifer. |
Now, let’s say that you want to post a notification to your internal Microsoft Teams messaging system when a new alert is raised. To do so, you have to:
- Configure a small HTTP server that will receive the payload
- It will then talk to SEKOIA.IO’s Alert API to retrieve more information about the alert itself (its title, its urgency, etc.)
- The final message is computed and pushed to Microsoft Teams via their incoming WebHook system
Here’s an example of an HTTP server written in Python and FastAPI:
"""Sample notification handler for SEKOIA.IO WebHook Notifications.
Sample FastAPI application that is in charge of receiving WebHook events from SEKOIA.IO’s Notification mechanism, enrich event by talking to SEKOIA.IO’s Alert API and then to push a notification to Microsoft Teams, via an incoming WebHook.
"""
from datetime import datetime
from typing import Literal, Optional
import httpx
from fastapi import BackgroundTasks, FastAPI
from pydantic import BaseModel, BaseSettings
class WebHookSettings(BaseSettings): # (4)
apikey: str
teams_webhook_url: Optional[str] = None
class SEKOIAIOWebHookAlertAttributes(BaseModel):
uuid: str
short_id: str
class SEKOIAIOWebHookMetadata(BaseModel):
version: int = 2
created_at: datetime
community_uuid: str
avatar_uuid: Optional[str] = None
user_uuid: Optional[str] = None
permissions: Optional[list[str]] = None
class SEKOIAIOWebHookEvent(BaseModel): # (5)
type: Literal["alert"]
action: str
attributes: SEKOIAIOWebHookAlertAttributes
metadata: SEKOIAIOWebHookMetadata
app = FastAPI()
settings = WebHookSettings()
async def push_notification_to_teams(event: SEKOIAIOWebHookEvent):
"""Simple task that will extract the retrieve the full alert via
SEKOIA.IO API and then creates a message that will be posted on
Microsoft Teams via a predefined incoming WebHook.
"""
async with httpx.AsyncClient() as client:
response = await client.get( # (2)
f"https://api.sekoia.io/v1/sic/alerts/{event.attributes.uuid}",
params={"stix": False},
headers={"Authorization": f"Bearer {settings.apikey}"},
)
if response.status_code == 200:
alert = response.json()
message = (
f"A new alert “{alert['title']}” was created on SEKOIA.IO with "
"status “{alert['status']['name']}” and “{alert['urgency']['display']}” severity."
)
if settings.teams_webhook_url:
client.post(settings.teams_webhook_url, json={"text": message}) # (3)
@app.post("/hooks/67a7472b-b43c-415d-b1ce-c135fb1dfb0e") # (1)
async def handle_new_alert(
event: SEKOIAIOWebHookEvent, background_tasks: BackgroundTasks
):
background_tasks.add_task(push_notification_to_teams, event)
- Entrypoint of our HTTP server that receives SEKOIA.IO WebHook notifications. Please define a unique URL, using and UUID for example.
- Code in charge of collecting more information on the alert itself by talking to SEKOIA.IO APIs.
- Send the final text message to Microsoft Teams.
- Environment variables that needs to be defined to let the server work.
- Base model that will be used to parse incoming events (this version only handles alerts).
Now, you have to create a new API Key in SEKOIA.IO’s User Center. That one should have at least the right to read alerts (SIC_READ_ALERT
permissions).
Then you have to install requirements and start the HTTP server with the appropriate environment variables:
python -m venv venv
source venv/bin/activate # (1)
pip install "fastapi[uvicorn]" "uvicorn[classic]" "httpx" # (2)
export APIKEY="eyJ0eXAiOiJ…" # (3)
export TEAMS_WEBHOOK_URL="https://…"
poetry run uvicorn main:app # (4)
ngrok http 8000 # (5)
- Create a Python virtual environment to install our code
- Install requirements
- Export environment variables
- Start the server
- Use ngrok to provide access to your local code (development only)
Finally, you can configure SEKOIA.IO’s WebHook notification to push events to your HTTP server on the following URL: https://ad76-2a01-cb08-8b87-5600-777f-e748-9e82-49c2.ngrok.io/hooks/67a7472b-b43c-415d-b1ce-c135fb1dfb0e
.