Skip to content

Real-time network monitor + outbound firewall — see & block every connection. Privacy-first, local-first, Rust fleet agent, SIEM exports, 8 languages. / Moniteur réseau temps réel + pare-feu sortant, agent de flotte Rust, exports SIEM. 100 % local.

9.2 KB
Raw Blame
"""
EN: External alert webhooks — OPT-IN. When the user configures a webhook URL
    (Discord channel webhook, Slack incoming webhook, Telegram bot URL or any
    generic endpoint), warning/critical alerts are POSTed there in real time.
    This is an outbound network call made ONLY when explicitly configured —
    documented in PRIVACY.md.

    Payloads are auto-shaped:
      * Discord/Slack → {"content": "**[warning]** BEACON — …"}
      * Telegram      → {"chat_id": <from `telegram_chat_id` setting>, "text": "…"}
      * generic       → full alert JSON {"alert": {...}, "source": "snitch"}
      * syslog        → `syslog_addr` setting ("host:port" or
                        "tcp://host:port") sends RFC 3164 datagrams —
                        <PRI>TIME HOST TAG: MSG — the SIEM/Wazuh path.

FR: Webhooks d'alerte externes — OPT-IN. Quand l'utilisateur configure une
    URL (webhook de canal Discord, incoming webhook Slack, URL de bot
    Telegram ou endpoint générique), les alertes warning/critical y sont
    POSTées en temps réel. C'est un appel sortant fait UNIQUEMENT si
    explicitement configuré — documenté dans PRIVACY.md.
"""

from __future__ import annotations

import json
import logging
import socket as _socket
import threading
import urllib.parse
import urllib.request
from datetime import datetime

logger = logging.getLogger("snitch.notify")

# EN: Only these severities are forwarded — info alerts would spam channels.
# FR: Seules ces sévérités sont relayées — les infos spammeraient les canaux.
_FORWARD = {"warning", "critical"}
_TIMEOUT_S = 8

# EN: RFC 3164 severity mapping — local4 facility (19) so Snitch alerts can
#     be routed/filtered inside a SIEM: warning→4, critical→2.
# FR: Mapping de sévérité RFC 3164 — facilité local4 (19) pour router les
#     alertes Snitch dans un SIEM : warning→4, critical→2.
_SEV_TO_SYSLOG = {"warning": 4, "critical": 2}

# EN: CEF (ArcSight Common Event Format) 0–10 scale — SIEM connectors
#     (Wazuh, Graylog, Splunk UF, Elastic Agent) parse it natively.
# FR: Échelle CEF 0–10 — les connecteurs SIEM le parsent nativement.
_SEV_TO_CEF = {"warning": 5, "critical": 8}


def _cef_escape(s: str, header: bool = False) -> str:
    """EN: CEF escaping — `\\` everywhere, `|` in header fields,
    `=`+newlines in extension values. / FR: Échappement CEF."""
    s = str(s).replace("\\", "\\\\")
    if header:
        return s.replace("|", "\\|")
    return s.replace("=", "\\=").replace("\n", "\\n").replace("\r", "")


def to_cef(alert: dict, version: str) -> str:
    """EN: One alert as a CEF:0 line — vendor/product/version/signature/
    name/severity then the extension. `details.ip/process` map to the
    standard dst/sproc slots so SIEM correlation works out of the box.
    FR: Une alerte en ligne CEF:0 — `details.ip/process` mappent les
    champs standard dst/sproc pour la corrélation SIEM directe."""
    sev = _SEV_TO_CEF.get(alert.get("severity"), 3)
    det = alert.get("details") or {}
    ext = {
        "rt": alert.get("timestamp") or "",
        "dst": det.get("ip") or alert.get("node_id") or "",
        "sproc": det.get("process") or "",
        "cs1Label": "alertType", "cs1": alert.get("type") or "",
        "cs2Label": "reasons", "cs2": ",".join(det.get("reasons") or []),
    }
    ext_s = " ".join(f"{k}={_cef_escape(v)}" for k, v in ext.items() if v)
    return "CEF:0|Cognition|Snitch|{}|{}|{}|{}|{}".format(
        _cef_escape(version, True), _cef_escape(alert.get("type"), True),
        _cef_escape(alert.get("message"), True), sev, ext_s)


class WebhookNotifier:
    """EN: Holds webhook settings + dispatches alert payloads.
    FR: Définit les réglages webhook + envoie les payloads d'alerte."""

    def __init__(self):
        self._lock = threading.Lock()
        self._url = ""
        self._enabled = False
        self._chat_id = ""
        self._syslog = ""
        self._syslog_format = "rfc3164"
        self._version = "?"

    def configure(self, url: str, enabled: bool, chat_id: str = "",
                  syslog_addr: str = "", syslog_format: str = "rfc3164",
                  version: str = "?") -> None:
        with self._lock:
            self._url = (url or "").strip()
            self._enabled = bool(enabled)
            self._chat_id = (chat_id or "").strip()
            self._syslog = (syslog_addr or "").strip()
            # EN: "cef" wraps the message in ArcSight CEF inside the
            #     syslog envelope — anything else keeps plain RFC 3164.
            # FR: « cef » enveloppe le message en CEF ArcSight dans
            #     l'enveloppe syslog — sinon RFC 3164 brut.
            self._syslog_format = "cef" if syslog_format == "cef" else "rfc3164"
            self._version = version

    def config(self) -> dict:
        with self._lock:
            return {"enabled": self._enabled,
                    "url_set": bool(self._url),
                    "url_masked": (self._url[:32] + "…") if len(self._url) > 32 else self._url,
                    "chat_id_set": bool(self._chat_id),
                    "syslog_set": bool(self._syslog),
                    "syslog_format": self._syslog_format}

    def dispatch(self, alert: dict) -> None:
        """EN: Synchronous POST — must run in an executor, never on the event
        loop. Silent on failure: alerting must never break detection.
        FR: POST synchrone — à lancer dans un executor, jamais sur la boucle.
        Silencieux en échec : l'alerting ne doit jamais casser la détection."""
        with self._lock:
            url, enabled, chat_id = \
                self._url, self._enabled, self._chat_id
            syslog_addr = self._syslog
            syslog_format = self._syslog_format
            version = self._version
        if alert.get("severity") not in _FORWARD:
            return
        text = f"[{alert.get('severity','').upper()}] {alert.get('type')}: {alert.get('message')}"
        # EN: Syslog path is independent of webhook_enabled — a SIEM user
        #     may want ONLY syslog. UDP by default, tcp:// for TCP. The
        #     body is RFC 3164 text or a CEF:0 payload per syslog_format.
        # FR: Le chemin syslog est indépendant du webhook — UDP par
        #     défaut. Le corps est du texte RFC 3164 ou un payload CEF:0
        #     selon syslog_format.
        if syslog_addr:
            body = to_cef(alert, version) if syslog_format == "cef" else text
            self._send_syslog(syslog_addr, alert, body)
        if not enabled or not url:
            return
        # EN: Host-matched provider detection — a substring check would
        #     misclassify `discord.com.evil.example` as Discord. Compare
        #     the parsed hostname (+ subdomain suffix), not the raw URL.
        # FR: Détection du fournisseur par hôte — un test de sous-chaîne
        #     classerait `discord.com.evil.example` comme Discord. On
        #     compare le hostname parsé (+ suffixe de sous-domaine).
        host = (urllib.parse.urlparse(url).hostname or "").lower()
        if host == "discord.com" or host.endswith(".discord.com") \
                or host == "slack.com" or host.endswith(".slack.com"):
            payload = {"content": f"**{text}**"}
        elif host == "api.telegram.org":
            payload = {"text": text}
            if chat_id:
                payload["chat_id"] = chat_id
        else:
            payload = {"alert": alert, "source": "snitch", "text": text}
        try:
            req = urllib.request.Request(
                url, data=json.dumps(payload).encode(),
                headers={"Content-Type": "application/json"},
            )
            urllib.request.urlopen(req, timeout=_TIMEOUT_S).read()
        except Exception as e:                          # noqa: BLE001
            logger.debug("webhook dispatch failed: %s", e)

    @staticmethod
    def _send_syslog(addr: str, alert: dict, text: str) -> None:
        """EN: RFC 3164 datagram — <PRI>Mmm dd HH:MM:SS host tag: msg.
        `addr` is "host:port" (UDP, default) or "tcp://host:port".
        Never raises. / FR: Datagramme RFC 3164 — ne lève jamais."""
        try:
            tcp = addr.startswith("tcp://")
            target = addr[6:] if tcp else addr
            target = target.removeprefix("udp://")
            host, _, port_s = target.rpartition(":")
            port = int(port_s) if port_s.isdigit() else 514
            sev = _SEV_TO_SYSLOG.get(alert.get("severity"), 5)
            pri = 19 * 8 + sev                          # EN: local4.<sev>
            ts = datetime.now().strftime("%b %d %H:%M:%S")
            msg = f"<{pri}>{ts} {_socket.gethostname()} " \
                  f"snitch[{alert.get('type','?')}]: {text}".encode(
                      "utf-8", "replace")
            if tcp:
                with _socket.create_connection(
                        (host, port), timeout=_TIMEOUT_S) as s:
                    s.sendall(msg + b"\n")
            else:
                with _socket.socket(_socket.AF_INET,
                                    _socket.SOCK_DGRAM) as s:
                    s.sendto(msg, (host, port))
        except Exception as e:                          # noqa: BLE001
            logger.debug("syslog dispatch failed: %s", e)


notifier = WebhookNotifier()