chore: import upstream snapshot with attribution

integrations/splunk/__init__.py

@@ -0,0 +1,33 @@
+"""Splunk integration classifier."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from integrations._validation_helpers import report_classify_failure
+from integrations.config_models import SplunkIntegrationConfig
+
+logger = logging.getLogger(__name__)
+
+
+def classify(
+    credentials: dict[str, Any], record_id: str
+) -> tuple[SplunkIntegrationConfig | None, str | None]:
+    try:
+        cfg = SplunkIntegrationConfig.model_validate(
+            {
+                "base_url": credentials.get("base_url", ""),
+                "token": credentials.get("token", ""),
+                "index": credentials.get("index", "main"),
+                "verify_ssl": credentials.get("verify_ssl", True),
+                "ca_bundle": credentials.get("ca_bundle", ""),
+                "integration_id": record_id,
+            }
+        )
+    except Exception as exc:
+        report_classify_failure(exc, logger=logger, integration="splunk", record_id=record_id)
+        return None, None
+    if cfg.base_url and cfg.token:
+        return cfg, "splunk"
+    return None, None

integrations/splunk/_client.py

@@ -0,0 +1,32 @@
+"""Splunk client factory for the SplunkSearchTool."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from integrations.splunk.client import SplunkClient, SplunkConfig
+
+
+def make_client(
+    base_url: str | None,
+    token: str | None = None,
+    index: str = "main",
+    verify_ssl: bool = True,
+    ca_bundle: str = "",
+) -> SplunkClient | None:
+    if not base_url or not token:
+        return None
+    return SplunkClient(
+        SplunkConfig(
+            base_url=base_url,
+            token=token,
+            index=index,
+            verify_ssl=verify_ssl,
+            ca_bundle=ca_bundle,
+        )
+    )
+
+
+def unavailable(source: str, empty_key: str, error: str, **extra: Any) -> dict[str, Any]:
+    """Standardised unavailable response."""
+    return {"source": source, "available": False, "error": error, empty_key: [], **extra}

integrations/splunk/client.py

@@ -0,0 +1,203 @@
+"""Splunk REST API client for RCA log searches."""
+
+from __future__ import annotations
+
+import json
+import logging
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+import httpx
+
+from integrations.config_models import SplunkIntegrationConfig
+from integrations.probes import ProbeResult
+from platform.observability.errors.service import capture_service_error
+from platform.observability.streaming import StreamingParseStats
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_TIMEOUT_SECONDS = 30.0
+
+
+def build_splunk_spl_query(
+    *,
+    raw_query: str = "",
+    index: str = "main",
+    error_message: str = "",
+    alert_name: str = "",
+    trace_id: str = "",
+    limit: int = 50,
+) -> str:
+    """Build an SPL query for RCA investigation.
+
+    Priority:
+      1. raw_query — operator supplied a verbatim SPL (from annotations.query)
+      2. Construct from available signals (index + keyword filters)
+    """
+    if raw_query.strip():
+        # Ensure a head clause to prevent runaway queries
+        spl = raw_query.strip()
+        if "| head " not in spl.lower():
+            spl = f"{spl} | head {limit}"
+        return spl
+
+    # Build keyword filter from alert signals
+    keyword = (error_message or alert_name or "").strip()
+    if trace_id:
+        keyword_clause = f'index={index} trace_id="{trace_id}"'
+    elif keyword:
+        # Escape double-quotes inside keyword
+        safe_keyword = keyword.replace('"', '\\"')
+        keyword_clause = f'index={index} "{safe_keyword}"'
+    else:
+        keyword_clause = f"index={index}"
+
+    return f"search {keyword_clause} | head {limit}"
+
+
+SplunkConfig = SplunkIntegrationConfig
+
+
+class SplunkClient:
+    """Synchronous Splunk REST API client using the export (streaming) endpoint."""
+
+    def __init__(self, config: SplunkConfig) -> None:
+        self.config = config
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.config.token}",
+            "Content-Type": "application/x-www-form-urlencoded",
+        }
+
+    def _export_url(self) -> str:
+        return f"{self.config.base_url}/services/search/jobs/export"
+
+    def search_logs(
+        self,
+        query: str,
+        *,
+        time_range_minutes: int = 60,
+        limit: int = 50,
+    ) -> dict[str, Any]:
+        """Run a blocking SPL search via the export endpoint.
+
+        Returns normalized log rows. The export endpoint streams results
+        immediately — no job polling needed, making it ideal for RCA.
+        """
+        now = datetime.now(UTC)
+        earliest = now - timedelta(minutes=max(int(time_range_minutes), 1))
+
+        params = {
+            "search": query if query.startswith("search ") else f"search {query}",
+            "earliest_time": earliest.strftime("%Y-%m-%dT%H:%M:%S"),
+            "latest_time": now.strftime("%Y-%m-%dT%H:%M:%S"),
+            "output_mode": "json",
+            "count": str(limit),
+        }
+
+        try:
+            response = httpx.post(
+                self._export_url(),
+                headers=self._headers(),
+                data=params,
+                timeout=_DEFAULT_TIMEOUT_SECONDS,
+                verify=self.config.ssl_verify,
+            )
+            response.raise_for_status()
+        except httpx.HTTPStatusError as exc:
+            capture_service_error(exc, logger=logger, integration="splunk", method="search_logs")
+            return {
+                "success": False,
+                "error": f"HTTP {exc.response.status_code}: {exc.response.text[:200]}",
+            }
+        except Exception as exc:
+            capture_service_error(exc, logger=logger, integration="splunk", method="search_logs")
+            return {"success": False, "error": str(exc)}
+
+        logs = self._parse_export_response(response.text)
+        return {
+            "success": True,
+            "logs": logs,
+            "total": len(logs),
+            "query": query,
+        }
+
+    def _parse_export_response(self, response_text: str) -> list[dict[str, Any]]:
+        """Parse the NDJSON export stream into normalized log dicts."""
+        logs: list[dict[str, Any]] = []
+        stats = StreamingParseStats()
+        for line in response_text.splitlines():
+            stripped = line.strip()
+            if not stripped:
+                continue
+            try:
+                payload = json.loads(stripped)
+            except json.JSONDecodeError as exc:
+                stats.record_error(exc)
+                continue
+            stats.record_parsed()
+            if not isinstance(payload, dict):
+                continue
+            result_type = payload.get("result")
+            if isinstance(result_type, dict):
+                logs.append(self._normalize_row(result_type))
+        stats.report_if_unhealthy(logger=logger, integration="splunk", source="search/jobs/export")
+        return logs
+
+    def _normalize_row(self, row: dict[str, Any]) -> dict[str, Any]:
+        """Normalize a Splunk result row to a common log shape."""
+        return {
+            "timestamp": str(row.get("_time", "")),
+            "message": str(row.get("_raw", row.get("message", ""))),
+            "level": str(row.get("log_level", row.get("severity", ""))),
+            "source": str(row.get("source", "")),
+            "host": str(row.get("host", "")),
+            "sourcetype": str(row.get("sourcetype", "")),
+            "index": str(row.get("index", "")),
+            "raw": row,
+        }
+
+    def validate_access(self) -> dict[str, Any]:
+        """Validate Splunk credentials by hitting the server info endpoint."""
+        info_url = f"{self.config.base_url}/services/server/info"
+        try:
+            response = httpx.get(
+                info_url,
+                headers={"Authorization": f"Bearer {self.config.token}"},
+                params={"output_mode": "json"},
+                timeout=10.0,
+                verify=self.config.ssl_verify,
+            )
+            response.raise_for_status()
+            data = response.json()
+            version = data.get("entry", [{}])[0].get("content", {}).get("version", "unknown")
+            return {
+                "success": True,
+                "detail": f"Connected to Splunk {version}",
+            }
+        except httpx.HTTPStatusError as exc:
+            capture_service_error(
+                exc, logger=logger, integration="splunk", method="validate_access"
+            )
+            return {
+                "success": False,
+                "error": f"HTTP {exc.response.status_code}: {exc.response.text[:200]}",
+            }
+        except Exception as exc:
+            capture_service_error(
+                exc, logger=logger, integration="splunk", method="validate_access"
+            )
+            return {"success": False, "error": str(exc)}
+
+    def probe_access(self) -> ProbeResult:
+        """Validate Splunk connectivity by calling the server info endpoint."""
+        if not (self.config.base_url and self.config.token):
+            return ProbeResult.missing("Missing base_url or token.")
+
+        result = self.validate_access()
+        if not result.get("success"):
+            return ProbeResult.failed(
+                f"Server info check failed: {result.get('error', 'unknown error')}"
+            )
+        return ProbeResult.passed(result.get("detail", "Connected."))

integrations/splunk/tools/__init__.py

@@ -0,0 +1,145 @@
+# ======== from tools/splunk_search_tool/ ========
+
+"""Splunk log search tool for RCA investigation."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from core.tool_framework.base import BaseTool
+from integrations.splunk._client import make_client, unavailable
+from platform.common.evidence_compaction import compact_logs, summarize_counts
+
+_ERROR_KEYWORDS = (
+    "error",
+    "fail",
+    "exception",
+    "traceback",
+    "critical",
+    "killed",
+    "crash",
+    "panic",
+    "timeout",
+)
+
+
+class SplunkSearchTool(BaseTool):
+    """Search Splunk logs using SPL for errors, exceptions, and application events."""
+
+    name = "query_splunk_logs"
+    source = "splunk"
+    description = (
+        "Search Splunk using SPL (Search Processing Language) for application errors, "
+        "exceptions, and operational events. Returns time-bounded log evidence."
+    )
+    use_cases = [
+        "Investigating application errors stored in Splunk",
+        "Searching Splunk indexes for error patterns during incident window",
+        "Fetching recent error logs for a service identified in an alert",
+        "Correlating trace IDs with Splunk log entries",
+    ]
+    surfaces = ("investigation", "chat")
+    requires = []  # connection_verified check is in is_available()
+    outputs = {
+        "splunk_logs": "All log events returned from Splunk search",
+        "splunk_error_logs": "Subset of logs matching error/exception keywords",
+    }
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "query": {
+                "type": "string",
+                "description": (
+                    "SPL search string (e.g. 'index=main error | head 50'). "
+                    "Do not include the leading 'search' keyword."
+                ),
+            },
+            "time_range_minutes": {
+                "type": "integer",
+                "default": 60,
+                "description": "Look-back window in minutes from now.",
+            },
+            "limit": {
+                "type": "integer",
+                "default": 50,
+                "description": "Maximum number of events to return.",
+            },
+            "index": {
+                "type": "string",
+                "description": "Splunk index to search (overrides integration default).",
+            },
+        },
+        "required": ["query"],
+    }
+
+    def is_available(self, sources: dict) -> bool:
+        return bool(sources.get("splunk", {}).get("connection_verified"))
+
+    def extract_params(self, sources: dict) -> dict:
+        splunk = sources.get("splunk", {})
+        return {
+            "query": splunk.get("default_query", f"index={splunk.get('index', 'main')} | head 50"),
+            "time_range_minutes": splunk.get("time_range_minutes", 60),
+            "limit": 50,
+            "index": splunk.get("index", "main"),
+            "base_url": splunk.get("base_url"),
+            "token": splunk.get("token"),
+            "verify_ssl": splunk.get("verify_ssl", True),
+            "ca_bundle": splunk.get("ca_bundle", ""),
+        }
+
+    def run(
+        self,
+        query: str,
+        time_range_minutes: int = 60,
+        limit: int = 50,
+        index: str = "main",
+        base_url: str | None = None,
+        token: str | None = None,
+        verify_ssl: bool = True,
+        ca_bundle: str = "",
+        **_kwargs: Any,
+    ) -> dict:
+        client = make_client(base_url, token, index, verify_ssl, ca_bundle)
+        if client is None:
+            return unavailable(
+                "splunk_logs",
+                "logs",
+                "Splunk integration not configured (missing base_url or token)",
+            )
+
+        result = client.search_logs(
+            query=query,
+            time_range_minutes=time_range_minutes,
+            limit=limit,
+        )
+
+        if not result.get("success"):
+            return unavailable("splunk_logs", "logs", result.get("error", "Unknown error"))
+
+        logs = result.get("logs", [])
+        error_logs = [
+            log
+            for log in logs
+            if any(kw in log.get("message", "").lower() for kw in _ERROR_KEYWORDS)
+        ]
+
+        compacted_logs = compact_logs(logs, limit=limit)
+        compacted_error_logs = compact_logs(error_logs, limit=limit)
+
+        result_data: dict[str, Any] = {
+            "source": "splunk_logs",
+            "available": True,
+            "logs": compacted_logs,
+            "error_logs": compacted_error_logs,
+            "total": result.get("total", 0),
+            "query": query,
+        }
+        summary = summarize_counts(result.get("total", 0), len(compacted_logs), "logs")
+        if summary:
+            result_data["truncation_note"] = summary
+        return result_data
+
+
+# Module-level alias for direct invocation
+query_splunk_logs = SplunkSearchTool()

integrations/splunk/verifier.py

@@ -0,0 +1,12 @@
+"""Splunk integration verifier."""
+
+from __future__ import annotations
+
+from integrations.splunk.client import SplunkClient, SplunkConfig
+from integrations.verification import register_probe_verifier
+
+verify_splunk = register_probe_verifier(
+    "splunk",
+    config=SplunkConfig.model_validate,
+    client=SplunkClient,
+)