spanforge 1.0.0__py3-none-any.whl

spanforge/export/siem_splunk.py

@@ -0,0 +1,264 @@
+"""spanforge.export.siem_splunk — Splunk HTTP Event Collector (HEC) exporter.
+
+Forwards spanforge events to a Splunk HTTP Event Collector endpoint.
+
+Configuration
+-------------
+``SPANFORGE_SPLUNK_HEC_URL``
+    Required.  Full URL of the Splunk HEC endpoint, e.g.
+    ``https://splunk.example.com:8088/services/collector/event``.
+
+``SPANFORGE_SPLUNK_HEC_TOKEN``
+    Required.  Splunk HEC authentication token (``Splunk <token>``).
+
+``SPANFORGE_SPLUNK_INDEX``
+    Optional.  Splunk index to route events to.  Default: ``"main"``.
+
+``SPANFORGE_SPLUNK_SOURCE``
+    Optional.  Splunk ``source`` field.  Default: ``"spanforge"``.
+
+``SPANFORGE_SPLUNK_SOURCETYPE``
+    Optional.  Splunk ``sourcetype`` field.  Default: ``"spanforge:event"``.
+
+``SPANFORGE_SPLUNK_BATCH_SIZE``
+    Optional integer.  Events per HEC request.  Default: ``50``.
+
+``SPANFORGE_SPLUNK_TIMEOUT``
+    Optional float (seconds).  HTTP request timeout.  Default: ``10.0``.
+
+Example::
+
+    import os
+    os.environ["SPANFORGE_SPLUNK_HEC_URL"] = "https://splunk:8088/services/collector/event"
+    os.environ["SPANFORGE_SPLUNK_HEC_TOKEN"] = "your-token-here"
+
+    from spanforge.export.siem_splunk import SplunkHECExporter
+    exporter = SplunkHECExporter()
+    exporter.export(event)
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import ssl
+import threading
+import time
+import urllib.error
+import urllib.request
+from typing import TYPE_CHECKING, Any
+
+from spanforge.export.siem_schema import event_to_siem_record
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from spanforge.event import Event
+
+__all__ = ["SplunkHECError", "SplunkHECExporter"]
+
+_log = logging.getLogger("spanforge.export.siem_splunk")
+
+_DEFAULT_BATCH_SIZE = 50
+_DEFAULT_TIMEOUT = 10.0
+_DEFAULT_INDEX = "main"
+_DEFAULT_SOURCE = "spanforge"
+_DEFAULT_SOURCETYPE = "spanforge:event"
+
+
+class SplunkHECError(RuntimeError):
+    """Raised when a Splunk HEC delivery attempt fails permanently."""
+
+
+class SplunkHECExporter:
+    """Export spanforge events to a Splunk HTTP Event Collector endpoint.
+
+    Args:
+        hec_url:    Splunk HEC URL.  Falls back to ``SPANFORGE_SPLUNK_HEC_URL``.
+        token:      HEC authentication token.  Falls back to
+                    ``SPANFORGE_SPLUNK_HEC_TOKEN``.
+        index:      Splunk index.  Falls back to ``SPANFORGE_SPLUNK_INDEX``.
+        source:     Splunk source field.  Falls back to ``SPANFORGE_SPLUNK_SOURCE``.
+        sourcetype: Splunk sourcetype field.  Falls back to
+                    ``SPANFORGE_SPLUNK_SOURCETYPE``.
+        batch_size: Events per HTTP request.  Falls back to
+                    ``SPANFORGE_SPLUNK_BATCH_SIZE`` (default 50).
+        timeout:    HTTP request timeout in seconds.  Falls back to
+                    ``SPANFORGE_SPLUNK_TIMEOUT`` (default 10.0).
+        verify_ssl: Whether to verify the server TLS certificate.  Default
+                    ``True``; set to ``False`` only in controlled lab
+                    environments.
+    """
+
+    def __init__(
+        self,
+        *,
+        hec_url: str = "",
+        token: str = "",
+        index: str = "",
+        source: str = "",
+        sourcetype: str = "",
+        batch_size: int = 0,
+        timeout: float = 0.0,
+        verify_ssl: bool = True,
+    ) -> None:
+        self._hec_url: str = hec_url or os.environ.get("SPANFORGE_SPLUNK_HEC_URL", "")
+        self._token: str = token or os.environ.get("SPANFORGE_SPLUNK_HEC_TOKEN", "")
+        self._index: str = index or os.environ.get("SPANFORGE_SPLUNK_INDEX", _DEFAULT_INDEX)
+        self._source: str = source or os.environ.get("SPANFORGE_SPLUNK_SOURCE", _DEFAULT_SOURCE)
+        self._sourcetype: str = sourcetype or os.environ.get(
+            "SPANFORGE_SPLUNK_SOURCETYPE", _DEFAULT_SOURCETYPE
+        )
+        self._batch_size: int = batch_size or int(
+            os.environ.get("SPANFORGE_SPLUNK_BATCH_SIZE", _DEFAULT_BATCH_SIZE)
+        )
+        self._timeout: float = timeout or float(
+            os.environ.get("SPANFORGE_SPLUNK_TIMEOUT", _DEFAULT_TIMEOUT)
+        )
+        self._verify_ssl: bool = verify_ssl
+        self._lock: threading.Lock = threading.Lock()
+        self._pending: list[dict[str, Any]] = []
+        self._sent_count: int = 0
+        self._error_count: int = 0
+
+        if not self._hec_url:
+            raise ValueError(
+                "Splunk HEC URL must be provided via hec_url argument or "
+                "SPANFORGE_SPLUNK_HEC_URL environment variable"
+            )
+        # Enforce HTTP/HTTPS-only — prevents file:// or custom-scheme injection (B310)
+        parsed_scheme = self._hec_url.split("://", 1)[0].lower() if "://" in self._hec_url else ""
+        if parsed_scheme not in ("http", "https"):
+            raise ValueError(
+                f"Splunk HEC URL must use http:// or https:// scheme, got: {self._hec_url!r}"
+            )
+        if not self._token:
+            raise ValueError(
+                "Splunk HEC token must be provided via token argument or "
+                "SPANFORGE_SPLUNK_HEC_TOKEN environment variable"
+            )
+        # Reject plaintext HTTP in non-test environments
+        if (
+            self._hec_url.startswith("http://")
+            and not self._hec_url.startswith("http://localhost")
+            and not self._hec_url.startswith("http://127.")
+        ):
+            _log.warning(
+                "Splunk HEC URL uses plaintext HTTP — use HTTPS in production: %s",
+                self._hec_url,
+            )
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def export(self, event: Event) -> None:
+        """Buffer *event* and flush when batch_size is reached."""
+        payload = self._build_hec_payload(event)
+        with self._lock:
+            self._pending.append(payload)
+            if len(self._pending) >= self._batch_size:
+                self._flush_locked()
+
+    def export_batch(self, events: Sequence[Event]) -> int:
+        """Export a batch of events.  Returns the number of events sent."""
+        for event in events:
+            self.export(event)
+        self.flush()
+        return len(events)
+
+    def flush(self) -> None:
+        """Force-flush any buffered events to Splunk HEC."""
+        with self._lock:
+            self._flush_locked()
+
+    def close(self) -> None:
+        """Flush and release resources."""
+        self.flush()
+
+    @property
+    def sent_count(self) -> int:
+        """Total number of events successfully sent to Splunk."""
+        return self._sent_count
+
+    @property
+    def error_count(self) -> int:
+        """Total number of delivery failures."""
+        return self._error_count
+
+    # ------------------------------------------------------------------
+    # Context manager support
+    # ------------------------------------------------------------------
+
+    def __enter__(self) -> SplunkHECExporter:
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _build_hec_payload(self, event: Event) -> dict[str, Any]:
+        """Convert a spanforge Event to a Splunk HEC event dict."""
+        return {
+            "time": event.timestamp if hasattr(event, "timestamp") else time.time(),
+            "index": self._index,
+            "source": self._source,
+            "sourcetype": self._sourcetype,
+            "event": event_to_siem_record(event),
+        }
+
+    def _flush_locked(self) -> None:
+        """Send all pending payloads.  Must be called with ``_lock`` held."""
+        if not self._pending:
+            return
+        batch = self._pending[:]
+        self._pending.clear()
+        try:
+            self._send(batch)
+            self._sent_count += len(batch)
+        except Exception as exc:
+            self._error_count += len(batch)
+            _log.error("SplunkHECExporter: failed to send %d events — %s", len(batch), exc)
+
+    def _send(self, payloads: list[dict[str, Any]]) -> None:
+        """POST *payloads* to the Splunk HEC endpoint.
+
+        Multiple events are encoded as newline-delimited JSON (Splunk's
+        raw HEC format).
+
+        Raises:
+            SplunkHECError: On a permanent 4xx / 5xx response.
+        """
+        body = "\n".join(json.dumps(p) for p in payloads).encode()
+        headers = {
+            "Authorization": f"Splunk {self._token}",
+            "Content-Type": "application/json",
+        }
+        req = urllib.request.Request(self._hec_url, data=body, headers=headers, method="POST")
+        ctx: ssl.SSLContext | None = None
+        if not self._verify_ssl:
+            ctx = ssl.create_default_context()
+            ctx.check_hostname = False
+            ctx.verify_mode = ssl.CERT_NONE
+
+        try:
+            with urllib.request.urlopen(req, timeout=self._timeout, context=ctx) as resp:  # nosec B310 — scheme validated to http/https in __init__
+                if resp.status >= 400:
+                    raise SplunkHECError(
+                        f"Splunk HEC returned HTTP {resp.status} for {len(payloads)} events"
+                    )
+        except urllib.error.HTTPError as exc:
+            raise SplunkHECError(f"Splunk HEC HTTP error {exc.code}: {exc.reason}") from exc
+        except urllib.error.URLError as exc:
+            raise SplunkHECError(f"Splunk HEC connection error: {exc.reason}") from exc
+
+    def __repr__(self) -> str:
+        return (
+            f"SplunkHECExporter(hec_url={self._hec_url!r}, "
+            f"index={self._index!r}, "
+            f"sent={self._sent_count}, errors={self._error_count})"
+        )

spanforge/export/siem_syslog.py

@@ -0,0 +1,212 @@
+"""spanforge.export.siem_syslog - Syslog / CEF exporter.
+
+Forwards spanforge events to a remote syslog receiver (RFC 5424) optionally
+encoded as ArcSight Common Event Format (CEF).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+import socket
+import threading
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Any
+
+from spanforge.export.siem_schema import event_to_siem_record, severity_from_event
+
+if TYPE_CHECKING:
+    from spanforge.event import Event
+
+__all__ = ["SyslogExporter", "SyslogExporterError"]
+
+_log = logging.getLogger("spanforge.export.siem_syslog")
+
+_DEFAULT_PORT = 514
+_DEFAULT_TRANSPORT = "udp"
+_DEFAULT_FORMAT = "rfc5424"
+_DEFAULT_APP_NAME = "spanforge"
+_DEFAULT_FACILITY = 16  # local0
+_SEVERITY_MAP: dict[str, int] = {
+    "alert": 1,
+    "error": 3,
+    "warn": 4,
+    "warning": 4,
+    "info": 6,
+    "debug": 7,
+    "trace": 7,
+}
+
+_CEF_VENDOR = "SpanForge"
+_CEF_PRODUCT = "SpanForge"
+_CEF_VERSION = "1.0"
+_CEF_ESCAPE_RE = re.compile(r"([\\|=])")
+
+
+class SyslogExporterError(RuntimeError):
+    """Raised when a syslog delivery attempt fails permanently."""
+
+
+class SyslogExporter:
+    """Export spanforge events to a remote syslog receiver."""
+
+    def __init__(
+        self,
+        *,
+        host: str = "",
+        port: int = 0,
+        transport: str = "",
+        format: str = "",
+        app_name: str = "",
+        facility: int = -1,
+    ) -> None:
+        self._host: str = host or os.environ.get("SPANFORGE_SYSLOG_HOST", "")
+        self._port: int = port or int(os.environ.get("SPANFORGE_SYSLOG_PORT", _DEFAULT_PORT))
+        self._transport: str = (
+            transport or os.environ.get("SPANFORGE_SYSLOG_TRANSPORT", _DEFAULT_TRANSPORT)
+        ).lower()
+        self._format: str = (
+            format or os.environ.get("SPANFORGE_SYSLOG_FORMAT", _DEFAULT_FORMAT)
+        ).lower()
+        self._app_name: str = app_name or os.environ.get(
+            "SPANFORGE_SYSLOG_APP_NAME", _DEFAULT_APP_NAME
+        )
+        self._facility: int = (
+            facility
+            if facility >= 0
+            else int(os.environ.get("SPANFORGE_SYSLOG_FACILITY", _DEFAULT_FACILITY))
+        )
+        self._lock: threading.Lock = threading.Lock()
+        self._sent_count: int = 0
+        self._error_count: int = 0
+
+        if not self._host:
+            raise ValueError(
+                "Syslog host must be provided via host argument or "
+                "SPANFORGE_SYSLOG_HOST environment variable"
+            )
+        if self._transport not in ("udp", "tcp"):
+            raise ValueError(f"transport must be 'udp' or 'tcp', got {self._transport!r}")
+        if self._format not in ("rfc5424", "cef"):
+            raise ValueError(f"format must be 'rfc5424' or 'cef', got {self._format!r}")
+        if not (0 <= self._facility <= 23):
+            raise ValueError(f"facility must be in range 0-23, got {self._facility}")
+
+    def export(self, event: Event) -> None:
+        """Encode *event* and send it to the syslog receiver."""
+        message = self._format_cef(event) if self._format == "cef" else self._format_rfc5424(event)
+        try:
+            self._send(message)
+            with self._lock:
+                self._sent_count += 1
+        except Exception as exc:
+            with self._lock:
+                self._error_count += 1
+            _log.error("SyslogExporter: failed to send event - %s", exc)
+
+    def close(self) -> None:
+        """No persistent connection; this is a no-op for UDP mode."""
+
+    @property
+    def sent_count(self) -> int:
+        """Total events successfully delivered."""
+        return self._sent_count
+
+    @property
+    def error_count(self) -> int:
+        """Total delivery failures."""
+        return self._error_count
+
+    def __enter__(self) -> SyslogExporter:
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+    def _severity_from_event(self, event: Event) -> int:
+        """Map event_type prefix to a syslog severity (0-7)."""
+        return severity_from_event(event)
+
+    def _priority(self, severity: int) -> int:
+        """Compute syslog PRI value from facility and severity."""
+        return self._facility * 8 + severity
+
+    def _format_rfc5424(self, event: Event) -> str:
+        """Format event as an RFC 5424 syslog message."""
+        severity = self._severity_from_event(event)
+        pri = self._priority(severity)
+        timestamp = (
+            datetime.now(tz=timezone.utc).isoformat(timespec="seconds").replace("+00:00", "Z")
+        )
+        hostname = socket.gethostname()
+        proc_id = "-"
+        msg_id = event.event_type.replace(" ", "_")
+        structured_data = "-"
+        record_json = json.dumps(event_to_siem_record(event), sort_keys=True)
+        msg = f"spanforge event_id={event.event_id} payload={record_json}"
+        return (
+            f"<{pri}>1 {timestamp} {hostname} {self._app_name} "
+            f"{proc_id} {msg_id} {structured_data} {msg}"
+        )
+
+    def _format_cef(self, event: Event) -> str:
+        """Format event as a CEF (ArcSight Common Event Format) message."""
+        severity = self._severity_from_event(event)
+        pri = self._priority(severity)
+        timestamp = (
+            datetime.now(tz=timezone.utc).isoformat(timespec="seconds").replace("+00:00", "Z")
+        )
+        hostname = socket.gethostname()
+        event_type_escaped = _CEF_ESCAPE_RE.sub(r"\\\1", event.event_type)
+        cef_header = (
+            f"CEF:0|{_CEF_VENDOR}|{_CEF_PRODUCT}|{_CEF_VERSION}|"
+            f"{event_type_escaped}|{event_type_escaped}|{severity}|"
+        )
+        extensions: dict[str, str] = {
+            "rt": timestamp,
+            "deviceExternalId": event.event_id,
+            "app": self._app_name,
+            "event_type": event.event_type,
+        }
+        siem_record = event_to_siem_record(event)
+        for key, value in siem_record.items():
+            if key == "payload":
+                continue
+            safe_key = re.sub(r"[^A-Za-z0-9_]", "_", str(key))
+            safe_value = (
+                json.dumps(value, sort_keys=True) if isinstance(value, (dict, list)) else str(value)
+            )
+            extensions[safe_key] = _CEF_ESCAPE_RE.sub(r"\\\1", safe_value)
+        payload = getattr(event, "payload", {}) or {}
+        if isinstance(payload, dict):
+            for key, value in payload.items():
+                safe_key = re.sub(r"[^A-Za-z0-9_]", "_", str(key))
+                safe_value = _CEF_ESCAPE_RE.sub(r"\\\1", str(value))
+                extensions[safe_key] = safe_value
+        ext_str = " ".join(f"{key}={value}" for key, value in extensions.items())
+        syslog_prefix = f"<{pri}>1 {timestamp} {hostname} {self._app_name} - - - "
+        return syslog_prefix + cef_header + ext_str
+
+    def _send(self, message: str) -> None:
+        """Deliver *message* via UDP or TCP syslog."""
+        data = (message + "\n").encode("utf-8", errors="replace")
+        try:
+            if self._transport == "udp":
+                with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as sock:
+                    sock.sendto(data, (self._host, self._port))
+            else:
+                with socket.create_connection((self._host, self._port), timeout=5.0) as sock:
+                    sock.sendall(data)
+        except OSError as exc:
+            raise SyslogExporterError(
+                f"Syslog delivery failed to {self._host}:{self._port} ({self._transport}): {exc}"
+            ) from exc
+
+    def __repr__(self) -> str:
+        return (
+            f"SyslogExporter(host={self._host!r}, port={self._port}, "
+            f"transport={self._transport!r}, format={self._format!r}, "
+            f"sent={self._sent_count}, errors={self._error_count})"
+        )