splunkctl 0.12.0__tar.gz → 0.13.0__tar.gz

{splunkctl-0.12.0/splunkctl.egg-info → splunkctl-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: splunkctl
-Version: 0.12.0
+Version: 0.13.0
 Summary: Open-source MCP server and CLI for Splunk Enterprise SIEM and Splunk SOAR.
 Author: dannyota
 License-Expression: Apache-2.0
@@ -36,6 +36,8 @@ Requires-Dist: types-requests; extra == "dev"
 Requires-Dist: types-PyYAML; extra == "dev"
 Requires-Dist: types-tabulate; extra == "dev"
 Requires-Dist: types-defusedxml; extra == "dev"
+Provides-Extra: browser
+Requires-Dist: playwright>=1.45; extra == "browser"
 Dynamic: license-file
 
 <div align="center">
@@ -114,6 +116,7 @@ splunkctl rules disable 'My Rule'
 # Add and verify Splunk SOAR when needed
 splunkctl config init --soar
 splunkctl soar test
+splunkctl auth login --target siem             # browser SAML/MFA login
 splunkctl soar containers list
 ```
 
@@ -192,6 +195,7 @@ streamable HTTP configuration.
 |---|---|
 | `doctor` | Check connection, authentication, health, and permissions |
 | `config` | Configure profiles and test connectivity |
+| `auth` | Browser SAML login, session status, and logout |
 | `info` | Show server version, operating system, and license details |
 | `search` | Run, export, upload, and manage search jobs |
 | `rules` | Manage detection rules and YAML import/export |

{splunkctl-0.12.0 → splunkctl-0.13.0}/README.md

@@ -74,6 +74,7 @@ splunkctl rules disable 'My Rule'
 # Add and verify Splunk SOAR when needed
 splunkctl config init --soar
 splunkctl soar test
+splunkctl auth login --target siem             # browser SAML/MFA login
 splunkctl soar containers list
 ```
 
@@ -152,6 +153,7 @@ streamable HTTP configuration.
 |---|---|
 | `doctor` | Check connection, authentication, health, and permissions |
 | `config` | Configure profiles and test connectivity |
+| `auth` | Browser SAML login, session status, and logout |
 | `info` | Show server version, operating system, and license details |
 | `search` | Run, export, upload, and manage search jobs |
 | `rules` | Manage detection rules and YAML import/export |

splunkctl-0.13.0/docs/guides/auth.md

@@ -0,0 +1,61 @@
+# Browser SAML authentication
+
+splunkctl can complete Splunk SAML single sign-on (including a second factor)
+in a headed Chromium window and then reuse the resulting product session until
+it expires. The browser handles the identity provider; splunkctl never reads or
+stores TOTP secrets or codes.
+
+## How it works
+
+1. `splunkctl config init` probes the public login route. When it sees a
+   redirect to an external identity provider, it records `auth_mode: browser`
+   and stores the product `web_url`.
+2. `splunkctl auth login --target <siem|soar>` opens Chromium at the product
+   login route. You complete the IdP prompts, including any TOTP code.
+3. splunkctl extracts only the product session (Splunk `splunkd_<port>` cookie,
+   or SOAR `sessionid` + `csrftoken`) and proves it against the product API.
+4. Normal commands reuse the cached session whenever the active profile selects
+   browser mode. A missing or expired session never opens a browser; the command
+   prints the exact login instruction instead.
+
+## Commands
+
+```text
+splunkctl auth login --target siem
+splunkctl auth login --target soar
+splunkctl auth status [--target siem|soar|both]
+splunkctl auth logout [--target siem|soar|both]
+```
+
+`login` requires exactly one target; two back-to-back browser flows are easy to
+confuse. `status` reports `missing`, `valid`, `expired`, or `unreachable`.
+`logout` always removes the local session, even if the remote endpoint refuses.
+
+## Optional dependency
+
+Browser login needs Playwright and Chromium:
+
+```bash
+pip install 'splunkctl[browser]'
+python -m playwright install chromium
+```
+
+Configuration still succeeds without them. `splunkctl auth login` prints the
+exact commands when they are missing.
+
+## Session storage and security
+
+Sessions are stored under `~/.splunkctl/sessions/<profile>/<target>.json` with
+directory mode `0700` and file mode `0600`. A record holds only the target,
+profile, product origin, product session values, and validation timestamps. It
+never stores passwords, Playwright storage state, identity-provider cookies, or
+TOTP secrets. Session values are redacted from all output.
+
+## What is and is not supported
+
+Supported: SAML browser login for SIEM and SOAR, one target per login, session
+status and logout, automatic SAML detection, and a reusable Keycloak lab.
+
+Not supported in this release: reading or storing TOTP secrets, native Splunk
+Duo or RSA flows, OpenID Connect or OAuth, logging in to both products in one
+command, and a local splunkctl callback redirect.

splunkctl-0.13.0/docs/guides/keycloak-lab.md

@@ -0,0 +1,20 @@
+# Keycloak SAML lab
+
+The lab runs Keycloak in rootless Podman as an external identity provider for
+the Splunk SIEM and SOAR VMs. It lets you exercise the browser SAML flow,
+including manual TOTP entry, without giving splunkctl access to the TOTP secret.
+
+See `lab/keycloak/README.md` in the source tree for topology, setup, reset, and
+recovery. The short version:
+
+```bash
+cd lab/keycloak
+cp .env.example .env      # set the two *_PASSWORD secrets
+./labctl.sh start
+./labctl.sh configure
+./labctl.sh verify
+```
+
+Then run `splunkctl config init` against a product that uses SAML, or configure
+the products to point at `http://100.65.1.1:8080` as their IdP, and log in with
+`splunkctl auth login --target siem`.

{splunkctl-0.12.0 → splunkctl-0.13.0}/docs/guides/mcp.md

@@ -5,7 +5,7 @@ server to give AI agents — Claude Code, Claude Desktop, Cursor, Windsurf, or
 any MCP client — direct access to your Splunk Enterprise SIEM and Splunk SOAR
 instances.
 
-The server uses **dynamic tool loading**: instead of exposing all 259 tools
+The server uses **dynamic tool loading**: instead of exposing all 262 tools
 upfront, it starts with 5 meta-tools and loads group-specific typed tools on
 demand. This keeps the agent's context window small while covering every
 command. Version 0.12 uses MCP Python SDK 2 and publishes tool-list changes

{splunkctl-0.12.0 → splunkctl-0.13.0}/pyproject.toml

@@ -42,6 +42,9 @@ dev = [
     "types-tabulate",
     "types-defusedxml",
 ]
+browser = [
+    "playwright>=1.45",
+]
 
 [project.scripts]
 splunkctl = "splunkctl.main:cli"

{splunkctl-0.12.0 → splunkctl-0.13.0}/splunkctl/__init__.py

@@ -1,3 +1,3 @@
 """CLI tool for Splunk Enterprise and Splunk SOAR operations."""
 
-__version__ = "0.12.0"
+__version__ = "0.13.0"

splunkctl-0.13.0/splunkctl/auth/__init__.py

@@ -0,0 +1 @@
+"""Browser SAML authentication — session store, detector, adapters, broker."""

splunkctl-0.13.0/splunkctl/auth/adapters.py

@@ -0,0 +1,151 @@
+"""Product session adapters — convert browser cookies into API sessions.
+
+SIEM extracts the Splunk Web ``splunkd_<port>`` session value and validates it
+against the management API. SOAR keeps the Django ``sessionid`` and
+``csrftoken`` cookies and validates against ``/rest/version``. Logout is
+best-effort: the local session is always removed even if the remote endpoint
+rejects the request.
+"""
+
+from __future__ import annotations
+
+from typing import Literal, Protocol
+
+import requests
+
+from splunkctl.auth.session import Target
+
+type ValidationStatus = Literal["valid", "expired", "unreachable"]
+
+
+class ExtractError(RuntimeError):
+    """Browser cookies did not contain the expected product session values."""
+
+
+class SessionAdapter(Protocol):
+    """A product's cookie->session mapping plus validation and logout."""
+
+    target: Target
+
+    def extract(self, cookies: dict[str, str]) -> dict[str, str]:
+        """Map browser cookies to the product's API session values."""
+        ...
+
+    def validate(
+        self, values: dict[str, str], *, api_base: str, verify: bool, timeout: int
+    ) -> ValidationStatus:
+        """Check ``values`` and return their current validation status."""
+        ...
+
+    def logout(
+        self, values: dict[str, str], *, web_url: str, verify: bool, timeout: int
+    ) -> None:
+        """Best-effort remote logout for the given session values."""
+        ...
+
+
+class SIEMAdapter:
+    """Splunk Enterprise SIEM adapter."""
+
+    target: Target = "siem"
+
+    def extract(self, cookies: dict[str, str]) -> dict[str, str]:
+        """Extract the Splunk session key from the ``splunkd_*`` cookie."""
+        for name, value in cookies.items():
+            if name.startswith("splunkd_"):
+                return {"session_key": value, "cookie": name}
+        raise ExtractError(
+            "SIEM browser login did not produce a Splunk session cookie "
+            "(splunkd_<port>). The identity-provider flow may not have "
+            "completed."
+        )
+
+    def validate(
+        self, values: dict[str, str], *, api_base: str, verify: bool, timeout: int
+    ) -> ValidationStatus:
+        """Validate the session key against the management API."""
+        try:
+            resp = requests.get(
+                f"{api_base.rstrip('/')}/services/server/info",
+                params={"output_mode": "json"},
+                headers={"Authorization": f"Splunk {values['session_key']}"},
+                verify=verify,
+                timeout=timeout,
+            )
+        except (requests.RequestException, OSError):
+            return "unreachable"
+        if resp.status_code == 200:
+            return "valid"
+        if resp.status_code in (401, 403):
+            return "expired"
+        return "unreachable"
+
+    def logout(
+        self, values: dict[str, str], *, web_url: str, verify: bool, timeout: int
+    ) -> None:
+        """GET the Splunk Web logout route to end the session."""
+        requests.get(
+            f"{web_url.rstrip('/')}/en-US/account/logout",
+            cookies={values["cookie"]: values["session_key"]},
+            verify=verify,
+            timeout=timeout,
+        )
+
+
+class SOARAdapter:
+    """Splunk SOAR adapter."""
+
+    target: Target = "soar"
+
+    def extract(self, cookies: dict[str, str]) -> dict[str, str]:
+        """Extract the Django ``sessionid`` and ``csrftoken`` cookies."""
+        session_id = cookies.get("sessionid")
+        csrf = cookies.get("csrftoken")
+        if not session_id or not csrf:
+            raise ExtractError(
+                "SOAR browser login did not produce sessionid and csrftoken "
+                "cookies. The identity-provider flow may not have completed."
+            )
+        return {"sessionid": session_id, "csrftoken": csrf}
+
+    def validate(
+        self, values: dict[str, str], *, api_base: str, verify: bool, timeout: int
+    ) -> ValidationStatus:
+        """Validate the cookies against ``/rest/version``."""
+        try:
+            resp = requests.get(
+                f"{api_base.rstrip('/')}/rest/version",
+                cookies=values,
+                verify=verify,
+                timeout=timeout,
+            )
+        except (requests.RequestException, OSError):
+            return "unreachable"
+        if resp.status_code == 200:
+            return "valid"
+        if resp.status_code in (401, 403):
+            return "expired"
+        return "unreachable"
+
+    def logout(
+        self, values: dict[str, str], *, web_url: str, verify: bool, timeout: int
+    ) -> None:
+        """POST the SOAR logout route to end the session."""
+        requests.post(
+            f"{web_url.rstrip('/')}/logout",
+            cookies=values,
+            headers={"X-CSRFToken": values["csrftoken"]},
+            verify=verify,
+            timeout=timeout,
+        )
+
+
+_ADAPTERS: dict[Target, SessionAdapter] = {
+    "siem": SIEMAdapter(),
+    "soar": SOARAdapter(),
+}
+
+
+def get_adapter(target: Target) -> SessionAdapter:
+    """Return the session adapter for a product target."""
+    return _ADAPTERS[target]

splunkctl-0.13.0/splunkctl/auth/broker.py

@@ -0,0 +1,115 @@
+"""Headed-Chromium SAML login via Playwright (lazy import).
+
+Playwright and its Chromium build are optional and only imported here. The
+browser context is temporary and isolated: identity-provider cookies are
+discarded when the context closes, and only the final product-origin cookies
+are returned.
+"""
+
+from __future__ import annotations
+
+import importlib
+import time
+from typing import Any
+from urllib.parse import urlsplit
+
+
+class BrokerError(RuntimeError):
+    """A browser-login failure with an ``errors.py``-compatible kind."""
+
+    def __init__(self, message: str, *, kind: str = "auth") -> None:  # noqa: D107
+        super().__init__(message)
+        self.message = message
+        self.kind = kind
+
+
+def _sync_playwright() -> Any:
+    """Import the sync Playwright API lazily; raises ImportError when absent."""
+    return importlib.import_module("playwright.sync_api").sync_playwright()
+
+
+def browser_available() -> bool:
+    """True when the Playwright package imports."""
+    try:
+        _sync_playwright()
+        return True
+    except ImportError:
+        return False
+
+
+def install_hint() -> str:
+    """The exact optional install commands, shown when the browser is missing."""
+    return (
+        "Install the optional browser support with: "
+        "pip install 'splunkctl[browser]' && python -m playwright install chromium"
+    )
+
+
+def _origin_of(url: str) -> tuple[str, str, int | None]:
+    parts = urlsplit(url)
+    port = parts.port
+    if port is None:
+        port = 443 if parts.scheme == "https" else 80
+    return parts.scheme, parts.hostname or "", port
+
+
+def run_login(
+    *,
+    login_url: str,
+    expected_origin: str,
+    verify: bool,
+    timeout: int,
+) -> dict[str, str]:
+    """Open headed Chromium, follow SAML to ``expected_origin``, return cookies.
+
+    Raises :class:`BrokerError` on timeout, wrong final origin, or early close.
+    """
+    if not browser_available():
+        raise BrokerError(
+            "Playwright or Chromium is not installed. " + install_hint(),
+            kind="usage",
+        )
+    with _sync_playwright() as playwright:
+        browser = playwright.chromium.launch(headless=False)
+        context = browser.new_context(ignore_https_errors=not verify)
+        page = context.new_page()
+        deadline = time.monotonic() + timeout
+        try:
+            page.goto(login_url)
+            expected = _origin_of(expected_origin)
+            # The login route is often on the product origin and only bounces to
+            # the IdP after a JS auto-submit or server redirect. Wait for the
+            # browser to leave the product origin first, then wait for it to
+            # return once the user completes the identity-provider flow.
+            while _origin_of(page.url) == expected:
+                if page.is_closed():
+                    raise BrokerError(
+                        "The browser was closed before login finished.", kind="auth"
+                    )
+                if time.monotonic() > deadline:
+                    raise BrokerError(
+                        f"Timed out waiting for the identity provider to take over "
+                        f"from {login_url}.",
+                        kind="timeout",
+                    )
+                page.wait_for_timeout(500)
+            while _origin_of(page.url) != expected:
+                if page.is_closed():
+                    raise BrokerError(
+                        "The browser was closed before login finished.", kind="auth"
+                    )
+                if time.monotonic() > deadline:
+                    raise BrokerError(
+                        f"Timed out waiting for login to reach the expected origin "
+                        f"({expected_origin}).",
+                        kind="timeout",
+                    )
+                page.wait_for_timeout(500)
+            cookies = {}
+            for cookie in context.cookies(urls=[expected_origin]):
+                if cookie.get("name") and cookie.get("value"):
+                    cookies[cookie["name"]] = cookie["value"]
+            return cookies
+        finally:
+            context.close()
+            browser.close()

splunkctl-0.13.0/splunkctl/auth/detector.py

@@ -0,0 +1,120 @@
+"""Public login-route classification for SAML vs password authentication.
+
+The detector only reads public login pages; it never uses stored credentials
+and never treats an ordinary HTTP 401 or a local login form as MFA. A 3xx to a
+different host is the reliable SAML signal (the identity provider is external);
+SAML/SSO text markers are a fallback for providers that serve a local
+interstitial before redirecting.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from typing import Literal
+from urllib.parse import urlsplit
+
+import requests
+
+type AuthMode = Literal["password", "browser", "unknown"]
+
+_REDIRECT = (301, 302, 303, 307, 308)
+
+
+def _different_host(location: str, login_url: str) -> bool:
+    """True when a redirect Location targets a different host than login_url.
+
+    A relative or protocol-relative Location stays on the login host and is
+    not an external-IdP signal; a scheme/port change on the same host is
+    likewise not a different host.
+    """
+    host = urlsplit(location).hostname
+    if host is None:
+        return False
+    return host != urlsplit(login_url).hostname
+
+
+def classify(
+    *,
+    login_url: str,
+    status: int,
+    headers: Mapping[str, str],
+    body: str,
+) -> AuthMode:
+    """Classify a login-route response without credentials."""
+    if status in _REDIRECT:
+        location = headers.get("Location", headers.get("location", ""))
+        return (
+            "browser"
+            if location and _different_host(location, login_url)
+            else "password"
+        )
+    if status == 401:
+        return "password"
+    lowered = body.lower()
+    if any(
+        marker in lowered for marker in ("saml", "single sign-on", "sign in with sso")
+    ):
+        return "browser"
+    if (
+        'type="password"' in lowered
+        or 'name="password"' in lowered
+        or "name='password'" in lowered
+    ):
+        return "password"
+    return "unknown"
+
+
+def probe(login_url: str, *, verify: bool, timeout: int) -> AuthMode:
+    """GET the login route without following redirects and classify it."""
+    try:
+        resp = requests.get(
+            login_url, allow_redirects=False, verify=verify, timeout=timeout
+        )
+    except requests.RequestException:
+        return "unknown"
+    return classify(
+        login_url=login_url,
+        status=resp.status_code,
+        headers=dict(resp.headers),
+        body=resp.text,
+    )
+
+
+def siem_login_url(web_url: str) -> str:
+    """Splunk Web login route (SAML auto-redirects when configured)."""
+    return f"{web_url.rstrip('/')}/en-US/account/login"
+
+
+def soar_login_url(web_url: str) -> str:
+    """SOAR Django login route (SAML auto-redirects when configured)."""
+    return f"{web_url.rstrip('/')}/login"
+
+
+_SAML_SSO_SUFFIX = "/protocol/saml"
+
+
+def siem_idp_issuer(web_url: str, *, verify: bool, timeout: int) -> str | None:
+    """Return the SAML IdP issuer the SIEM is configured against, or ``None``.
+
+    Splunk's SAML login route renders a form that auto-submits to the IdP (its
+    ``action`` is the IdP SSO URL); strip the ``/protocol/saml`` suffix to get
+    the issuer. Used to derive another product's SSO URL from the same IdP.
+    Returns ``None`` when the login route is unreachable, not SAML, or does not
+    reveal an issuer.
+    """
+    login_url = siem_login_url(web_url)
+    try:
+        resp = requests.get(
+            login_url, allow_redirects=False, verify=verify, timeout=timeout
+        )
+    except requests.RequestException:
+        return None
+    if resp.status_code in _REDIRECT:
+        target = resp.headers.get("Location", "")
+    else:
+        match = re.search(r'action="([^"]*)"', resp.text)
+        target = match.group(1) if match else ""
+    if _SAML_SSO_SUFFIX not in target:
+        return None
+    return target.split(_SAML_SSO_SUFFIX, 1)[0]