Notifikace a alerting¶

Notifikační integrace, pravidla alertů a konfigurace incident response

Verze dokumentu: 1.1.0
Poslední aktualizace: 2026-04-19

1. Přehled¶

MazeVault poskytuje komplexní notifikační systém, který upozorňuje operátory na kritické události jako expirace certifikátů, selhání rotace secrets a bezpečnostní incidenty. Notifikace mohou být doručovány současně přes více kanálů.

Týdenní reporty exspirací (v1.0.38+)

MazeVault může generovat automatické týdenní reporty se seznamem všech certifikátů a secrets exspirujících do 60 dnů. Reporty jsou doručovány na všechny povolené notifikační kanály současně. Konfigurujte příjemce a spouštějte reporty ručně z Systémové výstupy → Reporty. Viz Poznámky k verzím pro detaily.

Podporované notifikační kanály¶

Kanál	Popis	Autentizace
Email (Office365 OAuth2)	Email přes Microsoft Graph API — doporučeno pro Office365 prostředí	Azure AD App Registration (OAuth2 client credentials)
Email (SMTP)	Legacy SMTP notifikace s podporou HTML	SMTP credentials (env proměnné)
Microsoft Teams	Zprávy přes Incoming Webhook konektor	Webhook URL
Slack	Zprávy přes Incoming Webhook s Markdown formátováním	Webhook URL
JIRA	Automatické vytváření issues v JIRA projektech	Email + API Token (Basic Auth)
Generic Webhook	HTTP POST na libovolnou URL s JSON payloadem	URL

2. Konfigurace¶

2.1 Konfigurace emailu¶

MazeVault podporuje dva způsoby odesílání emailů. Office365 OAuth2 je doporučený pro organizace používající Microsoft 365. Pokud je zapnutý, má přednost před SMTP.

Varianta A: Office365 OAuth2 (doporučeno)¶

Odesílá emaily přes Microsoft Graph API pomocí OAuth2 client credentials flow. Žádná SMTP hesla nejsou potřeba.

Předpoklady:

Azure AD App Registration s oprávněním Mail.Send (Application permission)
Udělený admin consent pro toto oprávnění
(Doporučeno) Application Access Policy v Exchange Online pro omezení odesílatele

Proměnná	Povinná	Popis	Příklad
`O365_EMAIL_ENABLED`	Ano	Nastavte na `true` pro zapnutí	`true`
`O365_TENANT_ID`	Ano	Azure AD tenant ID	`12345678-abcd-...`
`O365_CLIENT_ID`	Ano	Client ID app registrace	`87654321-dcba-...`
`O365_CLIENT_SECRET`	Ano*	Client secret	`***`
`O365_SENDER_EMAIL`	Ano	Email odesílatele (uživatel nebo sdílená schránka)	`noreply@firma.cz`
`O365_AUTH_METHOD`	Ne	Metoda autentizace (výchozí: `client_secret`)	`client_secret`

* Povinné pro client_secret auth. Pro Azure AKS použijte managed_identity.

Status emailového transportu

Po konfiguraci zkontrolujte System Outputs → Notifications záložku — status indikátor zobrazí "📧 Email Transport: Office365 OAuth2 ✅".

Varianta B: SMTP (legacy)¶

Proměnná	Povinná	Popis	Příklad
`SMTP_HOST`	Ano	Hostname SMTP serveru	`smtp.office365.com`
`SMTP_PORT`	Ano	Port SMTP serveru	`587`
`SMTP_USERNAME`	Ano	Uživatelské jméno pro SMTP autentizaci	`noreply@firma.cz`
`SMTP_PASSWORD`	Ano	Heslo pro SMTP autentizaci	`***`
`SMTP_FROM`	Ano	Adresa odesílatele	`noreply@firma.cz`

Priorita transportu¶

1. O365_EMAIL_ENABLED=true → Office365 přes Microsoft Graph API
2. SMTP_HOST nakonfigurován → Legacy SMTP
3. Nic nakonfigurováno      → Emailové notifikace vypnuty

Testování emailové konfigurace

Po nastavení environment proměnných restartujte MazeVault backend a použijte tlačítko Test v System Outputs → Notifications pro ověření doručení.

2.2 Notifikační integrace (UI)¶

Přejděte na System Outputs → Notifications pro konfiguraci notifikačních kanálů.

Přidání nové integrace¶

Klikněte na Add Integration
Vyberte typ integrace (Slack, Teams, JIRA, Webhook, Email)
Zadejte popisný název
Vyplňte požadovaná konfigurační pole
Volitelně zaškrtněte Enable Weekly Expiry Report
Klikněte na Save Integration

Konfigurace JIRA¶

Pole	Popis	Příklad
Jira Base URL	URL vaší Atlassian instance	`https://firma.atlassian.net`
Email	Email Atlassian účtu	`operator@firma.cz`
API Token	Atlassian API token (vygenerovat zde)	`ATATT3x...`
Project Key	Klíč JIRA projektu pro vytváření issues	`SEC`

Test JIRA vytváří reálné issues

Tlačítko Test vytvoří skutečný JIRA issue v nakonfigurovaném projektu. Při počátečním nastavení použijte testovací projekt.

Konfigurace Slack¶

Pole	Popis	Příklad
Webhook URL	Slack Incoming Webhook URL	`https://hooks.slack.com/services/T.../B.../xxx`
Channel (volitelné)	Přepsat výchozí kanál	`#security-alerts`

Konfigurace Microsoft Teams¶

Pole	Popis	Příklad
Webhook URL	Teams Incoming Webhook URL	`https://outlook.office.com/webhook/...`

Konfigurace Generic Webhook¶

Pole	Popis	Příklad
URL	Cílový endpoint URL	`https://api.pagerduty.com/events`

Formát webhook payloadu:

{
  "subject": "Předmět alertu",
  "message": "Text alertu"
}

3. Pravidla alertů a triggery¶

3.1 Automatické alerty (denní kontrola)¶

MazeVault provádí denní kontrolu (každých 24 hodin) následujících podmínek:

Alerty expirace certifikátů¶

Podmínka	Alert spuštěn?
Certifikát expiruje do 30 dnů, auto-renewal vypnutý	✅ Ano
Certifikát expiruje do 30 dnů, auto-renewal zapnutý ale selhal	✅ Ano
Certifikát expiruje do 30 dnů, auto-renewal zapnutý a úspěšný	❌ Ne
Certifikát již expiroval	❌ Ne (pouze pre-expiry alerty)

Příjemci alertů:

Legacy environment proměnné (ADMIN_EMAIL, TEAMS_WEBHOOK_URL)
Incident kontakty organizace
Všechny aktivní notifikační integrace (kategorie: notification)

Alerty selhání rotace secrets¶

Podmínka	Alert spuštěn?
Stav rotace = `failed` a enabled = `true`	✅ Ano
Stav rotace = `success`	❌ Ne
Rotace enabled = `false`	❌ Ne

3.2 Notifikace incidentů (v reálném čase)¶

Při detekci a vytvoření bezpečnostního incidentu jsou notifikace odeslány okamžitě:

Audit log — zaznamenán event INCIDENT_DETECTED
Incident kontakty — email odeslán všem nakonfigurovaným kontaktům
Notifikační integrace — všechny aktivní integrace obdrží alert

Notifikace incidentu obsahuje: - Typ a závažnost incidentu - Název postiženého zdroje - Čas detekce - Detaily změny

3.3 Notifikace selhání rotace (per-secret)¶

Individuální konfigurace rotace secrets mohou mít dedikované notifikační emaily:

Konfigurovány per rotace v nastavení rotace secretu
Odesílány pouze emailem při selhání rotace
Nezávislé na notifikačních integracích na úrovni organizace

3.4 Týdenní report expirace (plánovaný)¶

Komplexní report je generován a odesílán každé pondělí v 7:00 CET:

Obsah reportu:

Certifikáty expirující v příštích 60 dnech
Secrets s rotací splatnou v příštích 60 dnech
Celkové počty certifikátů a secrets

Kanály doručení:

Kanál	Formát	Konfigurace
Email	HTML (formátovaná tabulka)	System Outputs → Weekly Expiry Report → Recipients
Slack/Teams/Webhook/JIRA	Textový souhrn	Integrace se zaškrtnutým "Enable Weekly Expiry Report"

4. Konfigurace incident response¶

4.1 Incident kontakty¶

Přejděte na System Outputs → Incident Response pro správu kontaktů.

Incident kontakty dostávají emailové notifikace pro: - Alerty expirace certifikátů - Alerty selhání rotace - Bezpečnostní incidenty

Každý kontakt má: - Name — Jméno kontaktní osoby - Email — Notifikační emailová adresa - Role — Organizační role (např. Security Lead, DevOps) - Priority — Pořadí priority kontaktu

4.2 Legacy environment proměnné¶

Pro zpětnou kompatibilitu jsou kontrolovány i tyto environment proměnné:

Proměnná	Popis
`ADMIN_EMAIL`	Záložní admin email pro všechny alerty
`TEAMS_WEBHOOK_URL`	Záložní Teams webhook pro všechny alerty

Tyto jsou kontrolovány navíc k nakonfigurovaným integracím a incident kontaktům.

5. Pořadí doručení notifikací¶

Při spuštění alertu jsou notifikace odesílány v tomto pořadí:

1. Legacy environment proměnné (ADMIN_EMAIL, TEAMS_WEBHOOK_URL)
2. Incident kontakty organizace (pouze email)
3. Aktivní notifikační integrace:
   a. JIRA → Vytvoří issue
   b. Teams → Odešle webhook zprávu
   c. Slack → Odešle webhook zprávu
   d. Webhook → Odešle HTTP POST
   e. Email → Odešle nakonfigurovaným příjemcům

Best-effort doručení

Každý kanál je nezávislý. Pokud jeden kanál selže (např. JIRA API je nedostupné), ostatní kanály stále obdrží notifikaci. Selhání jsou logována v backend logech.

6. Testování integrací¶

Použití tlačítka Test¶

Přejděte na System Outputs → Notifications
Najděte kartu integrace
Klikněte na Test
Počkejte na výsledek (tlačítko zobrazuje "Testing..." během požadavku)
Toast notifikace zobrazí úspěch nebo konkrétní chybovou zprávu

Co test provádí¶

Integrace	Testovací akce
JIRA	Vytvoří reálný "Task" issue s názvem "Test Notification from MazeVault"
Teams	Odešle testovací zprávu na webhook
Slack	Odešle testovací zprávu na webhook
Webhook	Odešle testovací JSON payload na URL
Email	Odešle testovací email každému nakonfigurovanému příjemci

7. Řešení problémů¶

Časté problémy¶

Příznak	Příčina	Řešení
"Test notification failed"	Neplatné credentials nebo URL	Zkontrolujte konfiguraci integrace, ověřte API tokeny
Nevytvářejí se JIRA issues	Špatný project key nebo oprávnění	Ověřte, že project key existuje a API token má oprávnění vytvářet issues
Teams/Slack zprávy nedorazí	Webhook URL expirovala nebo je deaktivovaná	Vygenerujte novou webhook URL v Teams/Slack administraci
Emaily se nedoručují	Nesprávná SMTP konfigurace	Ověřte `SMTP_*` environment proměnné, zkontrolujte firewall pravidla
Týdenní report se neodesílá	Nejsou nakonfigurováni příjemci	Přidejte příjemce v System Outputs → Weekly Expiry Report

Kontrola notifikačních logů¶

Backend logy obsahují detailní informace o doručení notifikací:

[NotificationScheduler] Certificate CN=example.com expiring on 2026-04-15
[NotificationScheduler] Failed to send JIRA notification (integration=abc123): jira api error: 401
[IncidentService] Failed to send Teams notification (integration=def456): teams webhook failed with status: 410
[WeeklyReportService] Failed to send report to channel slack: no webhook_url in Slack integration xyz789

Filtrujte logy podle těchto prefixů pro diagnostiku problémů s notifikacemi: - [NotificationScheduler] — Denní kontroly expirace a rotace - [IncidentService] — Notifikace incidentů - [WeeklyReportService] — Doručení týdenního reportu