splunkctl 0.6.0__tar.gz → 0.7.0__tar.gz

{splunkctl-0.6.0 → splunkctl-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: splunkctl
-Version: 0.6.0
+Version: 0.7.0
 Summary: CLI tool for Splunk Enterprise SIEM operations.
 Author: dannyota
 License-Expression: Apache-2.0

{splunkctl-0.6.0 → splunkctl-0.7.0}/pyproject.toml

@@ -52,7 +52,7 @@ Repository = "https://github.com/dannyota/splunkctl"
 Issues = "https://github.com/dannyota/splunkctl/issues"
 
 [tool.setuptools]
-packages = ["splunkctl", "splunkctl.commands", "splunkctl.mcp"]
+packages = ["splunkctl", "splunkctl.commands", "splunkctl.mcp", "splunkctl.soar"]
 
 [tool.setuptools.dynamic]
 version = { attr = "splunkctl.__version__" }

{splunkctl-0.6.0 → splunkctl-0.7.0}/splunkctl/__init__.py

@@ -1,3 +1,3 @@
 """CLI tool for Splunk Enterprise SIEM operations."""
 
-__version__ = "0.6.0"
+__version__ = "0.7.0"

{splunkctl-0.6.0 → splunkctl-0.7.0}/splunkctl/commands/config_cmd.py

@@ -17,17 +17,24 @@ def config_group() -> None:
 
 
 @config_group.command()
-@click.option("--host", prompt=True, default="localhost", help="Splunk host.")
-@click.option("--port", prompt=True, default=8089, type=int, help="Splunk port.")
-@click.option("--username", prompt=True, default="admin", help="Splunk username.")
-@click.option("--password", prompt=True, hide_input=True, help="Splunk password.")
+@click.option("--host", default=None, help="Splunk host.")
+@click.option("--port", default=None, type=int, help="Splunk port.")
+@click.option("--username", default=None, help="Splunk username.")
+@click.option("--password", default=None, help="Splunk password.")
 @click.option(
     "--scheme",
     type=click.Choice(["https", "http"]),
-    default="https",
+    default=None,
     help="Connection scheme.",
 )
-@click.option("--verify/--no-verify", default=False, help="Verify SSL certificate.")
+@click.option("--verify/--no-verify", default=None, help="Verify SSL certificate.")
+@click.option(
+    "--soar",
+    "soar_mode",
+    is_flag=True,
+    default=False,
+    help="Add SOAR connection settings to the profile.",
+)
 @click.option(
     "--profile",
     "profile_name",
@@ -44,13 +51,16 @@ def config_group() -> None:
     default=None,
     help="Config file path (default: ~/.splunkctl/config.yaml).",
 )
+@click.pass_context
 def init(
-    host: str,
-    port: int,
-    username: str,
-    password: str,
-    scheme: str,
-    verify: bool,
+    ctx: click.Context,
+    host: str | None,
+    port: int | None,
+    username: str | None,
+    password: str | None,
+    scheme: str | None,
+    verify: bool | None,
+    soar_mode: bool,
     profile_name: str | None,
     path: str | None,
 ) -> None:
@@ -63,7 +73,28 @@ def init(
     never clobbers an existing multi-profile file.
     ``config init --profile <name>`` targets that named profile instead —
     use ``config use <name>`` afterwards to make it active.
+
+    ``config init --soar`` prompts for SOAR connection settings and saves
+    them as a nested ``soar:`` map within the profile, preserving existing
+    SIEM fields.
     """
+    dest = Path(path) if path else None
+    if soar_mode:
+        _init_soar(profile_name, dest)
+        return
+
+    # Prompt for SIEM fields not supplied via flags.
+    host = host or click.prompt("Host", default="localhost")
+    port = port or click.prompt("Port", default=8089, type=int)
+    username = username or click.prompt("Username", default="admin")
+    password = (
+        password
+        if password is not None
+        else click.prompt("Password", default="", hide_input=True)
+    )
+    scheme = scheme or "https"
+    verify = verify if verify is not None else False
+
     cfg: dict[str, Any] = {
         "host": host,
         "port": port,
@@ -72,7 +103,6 @@ def init(
         "scheme": scheme,
         "verify": verify,
     }
-    dest = Path(path) if path else None
     if profile_name:
         saved = cfg_mod.save_profile(cfg, profile_name, dest)
     elif cfg_mod.is_v2_file(dest):
@@ -82,6 +112,40 @@ def init(
     output.info(f"Config saved to {saved}")
 
 
+def _init_soar(
+    profile_name: str | None,
+    dest: Path | None,
+) -> None:
+    """Prompt for SOAR fields and merge into the target profile."""
+    soar_host = click.prompt("SOAR host", type=str)
+    soar_port = click.prompt("SOAR port", default=8443, type=int)
+    soar_token = click.prompt("SOAR token", default="", type=str)
+    soar_user = click.prompt("SOAR username", default="", type=str)
+    soar_pass = click.prompt("SOAR password", default="", hide_input=True, type=str)
+
+    soar_cfg: dict[str, Any] = {"host": soar_host, "port": soar_port}
+    if soar_token:
+        soar_cfg["token"] = soar_token
+    if soar_user:
+        soar_cfg["username"] = soar_user
+    if soar_pass:
+        soar_cfg["password"] = soar_pass
+
+    # Resolve which profile to update (same precedence as resolve()).
+    config_path = dest or cfg_mod.DEFAULT_PATH
+    raw = cfg_mod._read_raw(config_path)  # noqa: SLF001
+    name = cfg_mod._active_profile_name(raw, profile_name)  # noqa: SLF001
+
+    # Load existing SIEM fields (if any) and attach the new soar: map.
+    try:
+        existing = dict(cfg_mod._profile_config(raw, name))  # noqa: SLF001
+    except cfg_mod.ProfileNotFoundError:
+        existing = {}
+    existing["soar"] = soar_cfg
+    saved = cfg_mod.save_profile(existing, name, dest)
+    output.info(f"SOAR config saved to {saved}")
+
+
 @config_group.command()
 @click.pass_context
 def show(ctx: click.Context) -> None:
@@ -97,7 +161,17 @@ def show(ctx: click.Context) -> None:
     explicit_profile = obj.get("profile")
 
     resolved = cfg_mod.resolve(config_path, profile=explicit_profile)
-    payload = {"profile": resolved["profile"], **cfg_mod.redact(resolved["cfg"])}
+    payload: dict[str, Any] = {
+        "profile": resolved["profile"],
+        **cfg_mod.redact(resolved["cfg"]),
+    }
+
+    # Include redacted SOAR section if the profile has one.
+    soar = cfg_mod.resolve_soar(config_path, profile=explicit_profile)
+    # Only include soar: if the profile actually configured it (has a host).
+    if "host" in soar:
+        payload["soar"] = cfg_mod.redact_soar(soar)
+
     output.render(ctx, payload)
 
     if explicit_profile is None:

{splunkctl-0.6.0 → splunkctl-0.7.0}/splunkctl/config.py

@@ -36,6 +36,17 @@ _ENV_MAP: dict[str, str] = {
     "SPLUNK_VERIFY": "verify",
 }
 
+_SOAR_ENV_MAP: dict[str, str] = {
+    "SOAR_HOST": "host",
+    "SOAR_PORT": "port",
+    "SOAR_TOKEN": "token",
+    "SOAR_USER": "username",
+    "SOAR_PASS": "password",
+    "SOAR_VERIFY": "verify",
+}
+
+_SOAR_SECRETS: frozenset[str] = frozenset({"token", "password"})
+
 type ConfigSource = Literal["profile", "env", "flags"]
 
 
@@ -68,6 +79,11 @@ def defaults() -> dict[str, Any]:
     }
 
 
+def soar_defaults() -> dict[str, Any]:
+    """Return default SOAR configuration values (port and verify only)."""
+    return {"port": 8443, "verify": False}
+
+
 def _read_raw(path: Path) -> dict[str, Any]:
     """Read a config file as a plain dict; {} if missing or empty."""
     if not path.exists():
@@ -94,20 +110,37 @@ def _active_profile_name(raw: dict[str, Any], profile: str | None) -> str:
 
 
 def _profile_config(raw: dict[str, Any], name: str) -> dict[str, Any]:
-    """Return one profile's fields, or raise if ``name`` is unknown.
+    """Return one profile's SIEM fields, or raise if ``name`` is unknown.
 
     A v2 file requires an explicit ``profiles.<name>`` entry. A legacy
     (flat) or missing file only ever has the implicit ``default`` profile.
+    The nested ``soar:`` key is stripped — use ``_soar_profile_config``
+    to read it.
     """
     if _is_v2(raw):
         profiles = raw.get(PROFILES_KEY) or {}
         prof = profiles.get(name)
         if not isinstance(prof, dict):
             raise ProfileNotFoundError(name)
-        return prof
+        return {k: v for k, v in prof.items() if k != "soar"}
+    if name != _DEFAULT_PROFILE:
+        raise ProfileNotFoundError(name)
+    return {k: v for k, v in raw.items() if k != "soar"}
+
+
+def _soar_profile_config(raw: dict[str, Any], name: str) -> dict[str, Any]:
+    """Return the ``soar:`` nested map from a profile, or {} if absent."""
+    if _is_v2(raw):
+        profiles = raw.get(PROFILES_KEY) or {}
+        prof = profiles.get(name)
+        if not isinstance(prof, dict):
+            raise ProfileNotFoundError(name)
+        soar = prof.get("soar")
+        return dict(soar) if isinstance(soar, dict) else {}
     if name != _DEFAULT_PROFILE:
         raise ProfileNotFoundError(name)
-    return raw
+    soar = raw.get("soar")
+    return dict(soar) if isinstance(soar, dict) else {}
 
 
 def is_v2_file(path: Path | None = None) -> bool:
@@ -262,3 +295,57 @@ def use_profile(name: str, path: Path | None = None) -> Path:
 def redact(cfg: dict[str, Any]) -> dict[str, Any]:
     """Return a copy with secret values replaced by '****'."""
     return {k: "****" if k in _SECRETS and v else v for k, v in cfg.items()}
+
+
+# --- SOAR config resolution ---
+
+
+def _apply_soar_env_overlay(cfg: dict[str, Any]) -> bool:
+    """Overlay ``SOAR_*`` env vars onto ``cfg``; True if any applied."""
+    touched = False
+    for env_key, cfg_key in _SOAR_ENV_MAP.items():
+        val = os.environ.get(env_key)
+        if val is None:
+            continue
+        if cfg_key == "port":
+            try:
+                cfg[cfg_key] = int(val)
+            except ValueError:
+                continue
+        elif cfg_key == "verify":
+            cfg[cfg_key] = val.lower() in ("1", "true", "yes")
+        else:
+            cfg[cfg_key] = val
+        touched = True
+    return touched
+
+
+def resolve_soar(
+    path: Path | None = None,
+    *,
+    profile: str | None = None,
+    overrides: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Resolve effective SOAR config for the active profile.
+
+    Precedence: ``overrides`` (CLI flags) > ``SOAR_*`` env vars >
+    profile ``soar:`` section > built-in SOAR defaults (port, verify).
+    Returns a flat dict with only the keys that have values — callers
+    check for ``host`` to decide if SOAR is configured.
+    """
+    cfg = soar_defaults()
+    config_path = path or DEFAULT_PATH
+    raw = _read_raw(config_path)
+    name = _active_profile_name(raw, profile)
+    cfg.update(_soar_profile_config(raw, name))
+    _apply_soar_env_overlay(cfg)
+    if overrides:
+        for key, val in overrides.items():
+            if val is not None:
+                cfg[key] = val
+    return cfg
+
+
+def redact_soar(cfg: dict[str, Any]) -> dict[str, Any]:
+    """Return a copy of SOAR config with secrets replaced by '****'."""
+    return {k: "****" if k in _SOAR_SECRETS and v else v for k, v in cfg.items()}

{splunkctl-0.6.0 → splunkctl-0.7.0}/splunkctl/errors.py

@@ -44,6 +44,12 @@ def classify(exc: Exception) -> Classified | None:
     callers should fall back to their own default handling (e.g. an
     unclassified ``error`` kind, or re-raising).
     """
+    # SOARError carries kind/http_status natively — pass through.
+    from splunkctl.soar.client import SOARError
+
+    if isinstance(exc, SOARError):
+        return Classified(exc.message, exc.kind, exc.http_status)
+
     name = type(exc).__name__
     if name == "HTTPError":
         status: int | None = getattr(exc, "status", None)

{splunkctl-0.6.0 → splunkctl-0.7.0}/splunkctl/guard.py

@@ -8,6 +8,36 @@ import click
 from splunkctl import config as cfg_mod
 
 
+def soar_banner(ctx: click.Context) -> str:
+    """Build ``(SOAR @ host:port)`` guard banner for SOAR mutations.
+
+    Reads SOAR config via :func:`splunkctl.config.resolve_soar` — no
+    network I/O. Safe for dry-run previews and ``--yes`` confirmations.
+    """
+    obj: dict[str, Any] = ctx.obj or {}
+    config_path = Path(obj["config"]) if obj.get("config") else None
+    cfg = cfg_mod.resolve_soar(config_path, profile=obj.get("profile"))
+    host = cfg.get("host", "unknown")
+    port = cfg.get("port", 8443)
+    return f"(SOAR @ {host}:{port})"
+
+
+def soar_check(ctx: click.Context, action: str, *, details: str = "") -> bool:
+    """SOAR mutation guard — same as :func:`check` but with the SOAR banner."""
+    obj: dict[str, Any] = ctx.obj or {}
+    tag = soar_banner(ctx)
+
+    if not obj.get("dry_run", True):
+        click.echo(f"Applying: {action} {tag}", err=True)
+        return True
+
+    click.echo(f"[DRY RUN] {action} {tag}", err=True)
+    if details:
+        click.echo(details, err=True)
+    click.echo("Pass --yes to apply.", err=True)
+    return False
+
+
 def banner(ctx: click.Context, *, overrides: dict[str, Any] | None = None) -> str:
     """Build the ``(source: name @ host:port)`` guard banner.
 

{splunkctl-0.6.0 → splunkctl-0.7.0}/splunkctl/main.py

@@ -30,6 +30,7 @@ from splunkctl.commands.parsers import parsers_group
 from splunkctl.commands.rules import rules_group
 from splunkctl.commands.search import search_group
 from splunkctl.commands.server import server_group
+from splunkctl.commands.soar import soar_group
 from splunkctl.commands.state import state_group
 from splunkctl.commands.users import users_group
 
@@ -199,6 +200,7 @@ cli.add_command(parsers_group)
 cli.add_command(rules_group)
 cli.add_command(search_group)
 cli.add_command(server_group)
+cli.add_command(soar_group)
 cli.add_command(mcp_group)
 cli.add_command(state_group)
 cli.add_command(tags_group)

splunkctl-0.7.0/splunkctl/soar/client.py

@@ -0,0 +1,377 @@
+"""SOAR REST API client — requests-based, lazy, normalizing.
+
+Speaks the Django REST API on Splunk SOAR (on-prem / cloud). All
+response-shape quirks (envelope variants, ``succeeded`` vs ``success``,
+``action_run_id`` vs ``id``, ``failed:true`` on HTTP 200) are
+normalized here so command code never sees them.
+
+Auth: ``ph-auth-token`` header preferred; automatic Basic fallback for
+DELETE (server refuses tokens on DELETE except ``decided_list``). A
+token-only config attempting a non-decided_list DELETE raises
+:class:`SOARError` with kind ``auth``.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator
+from typing import Any
+
+import requests
+
+from splunkctl.errors import kind_for_status
+
+# Endpoints with non-standard envelopes.
+_BARE_ARRAY_ENDPOINTS: frozenset[str] = frozenset({"audit"})
+_RESULTS_ENVELOPE_ENDPOINTS: frozenset[str] = frozenset({"search"})
+
+# DELETE endpoints that accept token auth (exceptions to the Basic rule).
+_TOKEN_DELETE_OK: frozenset[str] = frozenset({"decided_list"})
+
+# Operators where the value is not a string and should not be quoted.
+_UNQUOTED_OPS: frozenset[str] = frozenset({"in", "range"})
+
+
+class SOARError(Exception):
+    """SOAR API error with ``errors.py``-compatible kind and status."""
+
+    def __init__(  # noqa: D107
+        self,
+        message: str,
+        *,
+        kind: str = "error",
+        http_status: int | None = None,
+        data: dict[str, Any] | None = None,
+    ) -> None:
+        self.message = message
+        self.kind = kind
+        self.http_status = http_status
+        self.data = data or {}
+        super().__init__(message)
+
+
+def build_filters(**kwargs: Any) -> dict[str, str]:
+    """Build Django-style query-string filters for a SOAR REST call.
+
+    Rules:
+    - Strings are quoted (``"value"``).
+    - Booleans become Python-style ``True``/``False``.
+    - Integers/floats are unquoted.
+    - ``__in`` lists serialize as ``[1, 2, 3]``.
+    - Keys starting with ``_exclude_`` pass through as-is.
+    - ``None`` values are skipped.
+    """
+    params: dict[str, str] = {}
+    for key, value in kwargs.items():
+        if value is None:
+            continue
+
+        if key.startswith("_exclude_"):
+            params[key] = _format_value(key, value)
+            continue
+
+        # Split off operator suffix (e.g. name__icontains -> name, icontains)
+        params[f"_filter_{key}"] = _format_value(key, value)
+
+    return params
+
+
+def _format_value(key: str, value: Any) -> str:
+    """Format a filter value per SOAR conventions."""
+    if isinstance(value, bool):
+        return "True" if value else "False"
+    if isinstance(value, list):
+        inner = ", ".join(str(v) for v in value)
+        return f"[{inner}]"
+    if isinstance(value, int | float):
+        return str(value)
+    # String values: quote unless it's an __in/__range op
+    parts = key.rsplit("__", maxsplit=1)
+    op = parts[-1] if len(parts) > 1 else None
+    if op in _UNQUOTED_OPS:
+        return str(value)
+    return f'"{value}"'
+
+
+class SOARClient:
+    """Lazy SOAR REST API client.
+
+    No I/O happens until the first ``get``/``post``/``delete`` call.
+    """
+
+    def __init__(  # noqa: D107
+        self,
+        *,
+        host: str,
+        port: int = 8443,
+        token: str | None = None,
+        username: str | None = None,
+        password: str | None = None,
+        verify: bool = False,
+    ) -> None:
+        self._host = host
+        self._port = port
+        self._token = token
+        self._username = username
+        self._password = password
+        self._verify = verify
+        self._session = requests.Session()
+        self._session.verify = verify
+
+    # -- URL helpers --------------------------------------------------------
+
+    @property
+    def _base_url(self) -> str:
+        return f"https://{self._host}:{self._port}/rest"
+
+    def _url(self, path: str) -> str:
+        clean = path.lstrip("/")
+        return f"{self._base_url}/{clean}"
+
+    # -- Auth helpers -------------------------------------------------------
+
+    def _token_headers(self) -> dict[str, str]:
+        return {"ph-auth-token": self._token or ""}
+
+    def _basic_auth(self) -> tuple[str, str]:
+        return (self._username or "", self._password or "")
+
+    def _has_basic(self) -> bool:
+        return bool(self._username and self._password)
+
+    def _auth_kwargs(self, *, method: str, path: str) -> dict[str, Any]:
+        """Build auth kwargs for a request.
+
+        DELETE uses Basic (server refuses tokens) except for decided_list.
+        Everything else prefers token, falls back to Basic.
+        """
+        if method == "DELETE":
+            endpoint_root = path.lstrip("/").split("/")[0]
+            if endpoint_root not in _TOKEN_DELETE_OK:
+                if not self._has_basic():
+                    raise SOARError(
+                        "delete requires username/password credentials "
+                        "(SOAR refuses token auth on DELETE)",
+                        kind="auth",
+                    )
+                return {"auth": self._basic_auth(), "headers": {}}
+            # decided_list DELETE: token OK if available, else Basic
+            if self._token:
+                return {"headers": self._token_headers()}
+            if self._has_basic():
+                return {"auth": self._basic_auth(), "headers": {}}
+            raise SOARError("No credentials configured", kind="auth")
+
+        # Non-DELETE: prefer token, fall back to Basic
+        if self._token:
+            return {"headers": self._token_headers()}
+        if self._has_basic():
+            return {"auth": self._basic_auth(), "headers": {}}
+        raise SOARError("No credentials configured", kind="auth")
+
+    # -- Request helpers ----------------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        data: str | None = None,
+    ) -> Any:
+        """Execute a request and return the parsed, normalized JSON."""
+        auth_kw = self._auth_kwargs(method=method, path=path)
+        headers: dict[str, str] = auth_kw.get("headers", {})
+        if data is not None:
+            headers["Content-Type"] = "application/json"
+
+        kwargs: dict[str, Any] = {
+            "method": method,
+            "url": self._url(path),
+            "headers": headers,
+            "params": params,
+        }
+        if data is not None:
+            kwargs["data"] = data
+        if "auth" in auth_kw:
+            kwargs["auth"] = auth_kw["auth"]
+
+        resp: requests.Response = self._session.request(**kwargs)
+        return self._handle_response(resp, path=path, method=method)
+
+    def _handle_response(
+        self,
+        resp: requests.Response,
+        *,
+        path: str,
+        method: str,
+    ) -> Any:
+        """Parse JSON, check for errors, normalize envelope."""
+        try:
+            body: Any = resp.json()
+        except (ValueError, json.JSONDecodeError):
+            if resp.status_code >= 400:
+                raise SOARError(
+                    f"HTTP {resp.status_code}: {resp.text[:200]}",
+                    kind=kind_for_status(resp.status_code),
+                    http_status=resp.status_code,
+                ) from None
+            return {}
+
+        # Check for failed:true (can appear on any status code)
+        if isinstance(body, dict) and body.get("failed"):
+            msg = body.get("message", f"HTTP {resp.status_code}")
+            if resp.status_code >= 400:
+                kind = kind_for_status(resp.status_code)
+                http_status: int | None = resp.status_code
+            else:
+                # Logical failure on HTTP 200 — not an HTTP error
+                kind = "error"
+                http_status = None
+            raise SOARError(
+                msg,
+                kind=kind,
+                http_status=http_status,
+                data=body,
+            )
+
+        # HTTP errors without failed:true
+        if resp.status_code >= 400:
+            msg = (
+                body.get("message", f"HTTP {resp.status_code}")
+                if isinstance(body, dict)
+                else f"HTTP {resp.status_code}"
+            )
+            raise SOARError(
+                msg,
+                kind=kind_for_status(resp.status_code),
+                http_status=resp.status_code,
+            )
+
+        # Normalize response envelope for GET list endpoints
+        if method == "GET":
+            body = self._normalize_get_envelope(body, path)
+
+        # Normalize POST response keys
+        if method == "POST" and isinstance(body, dict):
+            body = self._normalize_post_keys(body)
+
+        return body
+
+    def _normalize_get_envelope(self, body: Any, path: str) -> Any:
+        """Normalize GET list responses to {count, num_pages, data}."""
+        endpoint_root = path.lstrip("/").split("/")[0]
+
+        # Bare array (audit)
+        if isinstance(body, list):
+            return {"count": len(body), "num_pages": 1, "data": body}
+
+        if not isinstance(body, dict):
+            return body
+
+        # {results} envelope (search)
+        if endpoint_root in _RESULTS_ENVELOPE_ENDPOINTS and "results" in body:
+            results = body["results"]
+            count = body.get("count", len(results))
+            return {"count": count, "num_pages": 1, "data": results}
+
+        return body
+
+    @staticmethod
+    def _normalize_post_keys(body: dict[str, Any]) -> dict[str, Any]:
+        """Normalize ``succeeded`` -> ``success`` and ``action_run_id`` -> ``id``."""
+        if "succeeded" in body and "success" not in body:
+            body["success"] = body.pop("succeeded")
+        if "action_run_id" in body and "id" not in body:
+            body["id"] = body.pop("action_run_id")
+        return body
+
+    # -- Public API ---------------------------------------------------------
+
+    def get(
+        self,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        """GET a SOAR REST endpoint. Returns normalized envelope."""
+        return self._request("GET", path, params=params)
+
+    def post(
+        self,
+        path: str,
+        *,
+        body: Any,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        """POST to a SOAR REST endpoint. Accepts dict or list body."""
+        data = json.dumps(body)
+        return self._request("POST", path, params=params, data=data)
+
+    def delete(
+        self,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        """DELETE a SOAR REST endpoint. Uses Basic auth (except decided_list)."""
+        return self._request("DELETE", path, params=params)
+
+    def get_bytes(
+        self,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+    ) -> bytes:
+        """GET a SOAR REST endpoint and return raw bytes.
+
+        Used for binary downloads (e.g. ``download_attachment``).
+        Raises :class:`SOARError` on non-2xx responses.
+        """
+        auth_kw = self._auth_kwargs(method="GET", path=path)
+        headers: dict[str, str] = auth_kw.get("headers", {})
+
+        kwargs: dict[str, Any] = {
+            "method": "GET",
+            "url": self._url(path),
+            "headers": headers,
+            "params": params,
+        }
+        if "auth" in auth_kw:
+            kwargs["auth"] = auth_kw["auth"]
+
+        resp: requests.Response = self._session.request(**kwargs)
+        if resp.status_code >= 400:
+            raise SOARError(
+                f"HTTP {resp.status_code}: {resp.text[:200]}",
+                kind=kind_for_status(resp.status_code),
+                http_status=resp.status_code,
+            )
+        return resp.content
+
+    def iter_pages(
+        self,
+        path: str,
+        *,
+        page_size: int = 100,
+        params: dict[str, Any] | None = None,
+    ) -> Iterator[dict[str, Any]]:
+        """Iterate all items across paginated results.
+
+        Yields individual items from each page, transparently fetching
+        subsequent pages as needed.
+        """
+        page = 0
+        while True:
+            page_params = dict(params or {})
+            page_params["page"] = page
+            page_params["page_size"] = page_size
+
+            result = self.get(path, params=page_params)
+            data: list[dict[str, Any]] = result.get("data", [])
+            yield from data
+
+            num_pages = result.get("num_pages", 1)
+            page += 1
+            if page >= num_pages or not data:
+                break

{splunkctl-0.6.0 → splunkctl-0.7.0}/splunkctl.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: splunkctl
-Version: 0.6.0
+Version: 0.7.0
 Summary: CLI tool for Splunk Enterprise SIEM operations.
 Author: dannyota
 License-Expression: Apache-2.0

{splunkctl-0.6.0 → splunkctl-0.7.0}/splunkctl.egg-info/SOURCES.txt

@@ -55,6 +55,8 @@ splunkctl/mcp/__init__.py
 splunkctl/mcp/resources.py
 splunkctl/mcp/server.py
 splunkctl/mcp/tools.py
+splunkctl/soar/__init__.py
+splunkctl/soar/client.py
 tests/test_client.py
 tests/test_config.py
 tests/test_guard.py

{splunkctl-0.6.0 → splunkctl-0.7.0}/tests/test_config.py

@@ -281,3 +281,198 @@ def test_use_profile_does_not_test_connectivity(
     config.use_profile("uat", p)
     raw = yaml.safe_load(p.read_text())
     assert raw["current"] == "uat"
+
+
+# --- SOAR profile section (L1) ---
+
+
+def test_soar_defaults() -> None:
+    """soar_defaults returns correct default port and verify."""
+    d = config.soar_defaults()
+    assert d["port"] == 8443
+    assert d["verify"] is False
+    # No host/token/username/password defaults — those must be explicit.
+    assert "host" not in d
+    assert "token" not in d
+    assert "username" not in d
+    assert "password" not in d
+
+
+def test_resolve_soar_from_profile(tmp_path: Path) -> None:
+    """A profile with a soar: section resolves SOAR fields."""
+    p = tmp_path / "config.yaml"
+    _write_v2(
+        p,
+        {"lab": {"host": "siem", "soar": {"host": "soar-host", "token": "tok123"}}},
+        current="lab",
+    )
+    resolved = config.resolve_soar(p)
+    assert resolved["host"] == "soar-host"
+    assert resolved["token"] == "tok123"
+    assert resolved["port"] == 8443  # default
+
+
+def test_resolve_soar_env_overlay(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """SOAR_* env vars override profile soar: values."""
+    p = tmp_path / "config.yaml"
+    _write_v2(
+        p,
+        {"lab": {"host": "siem", "soar": {"host": "profile-soar"}}},
+        current="lab",
+    )
+    monkeypatch.setenv("SOAR_HOST", "env-soar")
+    monkeypatch.setenv("SOAR_PORT", "9443")
+    monkeypatch.setenv("SOAR_TOKEN", "env-token")
+    monkeypatch.setenv("SOAR_VERIFY", "true")
+    resolved = config.resolve_soar(p)
+    assert resolved["host"] == "env-soar"
+    assert resolved["port"] == 9443
+    assert resolved["token"] == "env-token"
+    assert resolved["verify"] is True
+
+
+def test_resolve_soar_env_user_and_pass(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """SOAR_USER and SOAR_PASS map to username and password."""
+    p = tmp_path / "config.yaml"
+    _write_v2(
+        p,
+        {"lab": {"host": "siem", "soar": {"host": "soar-host"}}},
+        current="lab",
+    )
+    monkeypatch.setenv("SOAR_USER", "soar-admin")
+    monkeypatch.setenv("SOAR_PASS", "s3cret")
+    resolved = config.resolve_soar(p)
+    assert resolved["username"] == "soar-admin"
+    assert resolved["password"] == "s3cret"
+
+
+def test_resolve_soar_flags_beat_env(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Explicit overrides (flags) beat env vars."""
+    p = tmp_path / "config.yaml"
+    _write_v2(
+        p,
+        {"lab": {"host": "siem", "soar": {"host": "profile-soar"}}},
+        current="lab",
+    )
+    monkeypatch.setenv("SOAR_HOST", "env-soar")
+    resolved = config.resolve_soar(p, overrides={"host": "flag-soar"})
+    assert resolved["host"] == "flag-soar"
+
+
+def test_resolve_soar_no_soar_section(tmp_path: Path) -> None:
+    """A profile without soar: returns only defaults (port, verify)."""
+    p = tmp_path / "config.yaml"
+    _write_v2(p, {"lab": {"host": "siem"}}, current="lab")
+    resolved = config.resolve_soar(p)
+    assert resolved["port"] == 8443
+    assert resolved["verify"] is False
+    assert "host" not in resolved
+
+
+def test_resolve_soar_respects_profile_flag(tmp_path: Path) -> None:
+    """--profile selects which profile's soar: to read."""
+    p = tmp_path / "config.yaml"
+    _write_v2(
+        p,
+        {
+            "dev": {"host": "dev-siem", "soar": {"host": "dev-soar"}},
+            "prod": {"host": "prod-siem", "soar": {"host": "prod-soar"}},
+        },
+        current="dev",
+    )
+    resolved = config.resolve_soar(p, profile="prod")
+    assert resolved["host"] == "prod-soar"
+
+
+def test_resolve_soar_invalid_port_env_ignored(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Non-numeric SOAR_PORT is silently ignored."""
+    p = tmp_path / "config.yaml"
+    _write_v2(
+        p,
+        {"lab": {"host": "siem", "soar": {"host": "soar-host", "port": 9443}}},
+        current="lab",
+    )
+    monkeypatch.setenv("SOAR_PORT", "not-a-number")
+    resolved = config.resolve_soar(p)
+    assert resolved["port"] == 9443
+
+
+def test_redact_soar_masks_secrets() -> None:
+    """redact_soar masks token and password, keeps others."""
+    soar_cfg: dict[str, Any] = {
+        "host": "soar-host",
+        "port": 8443,
+        "token": "tok123",
+        "username": "admin",
+        "password": "s3cret",
+        "verify": False,
+    }
+    r = config.redact_soar(soar_cfg)
+    assert r["host"] == "soar-host"
+    assert r["token"] == "****"
+    assert r["password"] == "****"
+    assert r["username"] == "admin"
+    assert r["port"] == 8443
+
+
+def test_redact_soar_keeps_empty_secrets() -> None:
+    """Empty token/password stays empty, not redacted."""
+    soar_cfg: dict[str, Any] = {"token": "", "password": ""}
+    r = config.redact_soar(soar_cfg)
+    assert r["token"] == ""
+    assert r["password"] == ""
+
+
+def test_save_profile_with_soar_roundtrips(tmp_path: Path) -> None:
+    """A profile with soar: nested map saves and reloads correctly."""
+    p = tmp_path / "config.yaml"
+    profile_cfg: dict[str, Any] = {
+        "host": "siem-host",
+        "port": 8089,
+        "soar": {"host": "soar-host", "port": 8443, "token": "tok"},
+    }
+    config.save_profile(profile_cfg, "lab", p)
+    raw = yaml.safe_load(p.read_text())
+    assert raw["profiles"]["lab"]["soar"]["host"] == "soar-host"
+    assert raw["profiles"]["lab"]["soar"]["token"] == "tok"
+
+
+def test_resolve_soar_verify_false_string_env(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """SOAR_VERIFY=false resolves as boolean False."""
+    p = tmp_path / "config.yaml"
+    _write_v2(p, {"lab": {"host": "siem", "soar": {"host": "s"}}}, current="lab")
+    monkeypatch.setenv("SOAR_VERIFY", "false")
+    resolved = config.resolve_soar(p)
+    assert resolved["verify"] is False
+
+
+def test_siem_profile_unaffected_by_soar_section(tmp_path: Path) -> None:
+    """Adding soar: to a profile does not pollute SIEM resolve."""
+    p = tmp_path / "config.yaml"
+    _write_v2(
+        p,
+        {
+            "lab": {
+                "host": "siem-host",
+                "port": 8089,
+                "soar": {"host": "soar-host", "token": "tok"},
+            }
+        },
+        current="lab",
+    )
+    siem = config.resolve(p)
+    assert siem["cfg"]["host"] == "siem-host"
+    # SIEM resolve must strip the nested soar: map entirely.
+    assert "soar" not in siem["cfg"]
+    # And SOAR credentials must not leak into the SIEM top-level config.
+    assert "token" not in siem["cfg"]

{splunkctl-0.6.0 → splunkctl-0.7.0}/tests/test_version.py

@@ -4,4 +4,4 @@ from splunkctl import __version__
 
 
 def test_version() -> None:
-    assert __version__ == "0.6.0"
+    assert __version__ == "0.7.0"