splunkctl 0.9.0__tar.gz → 0.10.1__tar.gz

{splunkctl-0.9.0 → splunkctl-0.10.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: splunkctl
-Version: 0.9.0
+Version: 0.10.1
 Summary: CLI tool for Splunk Enterprise SIEM operations.
 Author: dannyota
 License-Expression: Apache-2.0
@@ -101,8 +101,10 @@ ingest. Built for humans and LLM agents alike: deterministic flags,
   envelopes.
 - **Playbooks as code** — `soar playbooks export --unpack` / `import`
   round-trips playbook tgz bundles (the first such tool anywhere);
-  `soar playbooks run --wait` drives and polls runs to completion;
-  `soar actions run --wait` does the same for connector actions.
+  `soar playbooks delete` removes them through the Web UI route (no
+  REST deletion exists); `soar playbooks run --wait` drives and polls
+  runs to completion; `soar actions run --wait` does the same for
+  connector actions.
 - **SIEM-to-SOAR ingest** — `soar ingest --spl` runs a SIEM search and
   creates SOAR containers + typed CEF artifacts using the official CIM-to-CEF
   field map, with SDI dedup, severity mapping, and last-artifact automation
@@ -265,7 +267,7 @@ splunkctl mcp install              # register in .mcp.json
 splunkctl mcp serve                # start stdio MCP server
 ```
 
-The MCP server auto-generates 237 typed tools from the Click command tree
+The MCP server auto-generates 229 typed tools from the Click command tree
 (SIEM + SOAR) with progressive discovery -- agents start with 5 meta-tools
 (`help`, `usage`, `focus`, `unfocus`, `run`) and dynamically load typed
 schemas per command group. Subgroup-granular focus works for nested groups

{splunkctl-0.9.0 → splunkctl-0.10.1}/README.md

@@ -63,8 +63,10 @@ ingest. Built for humans and LLM agents alike: deterministic flags,
   envelopes.
 - **Playbooks as code** — `soar playbooks export --unpack` / `import`
   round-trips playbook tgz bundles (the first such tool anywhere);
-  `soar playbooks run --wait` drives and polls runs to completion;
-  `soar actions run --wait` does the same for connector actions.
+  `soar playbooks delete` removes them through the Web UI route (no
+  REST deletion exists); `soar playbooks run --wait` drives and polls
+  runs to completion; `soar actions run --wait` does the same for
+  connector actions.
 - **SIEM-to-SOAR ingest** — `soar ingest --spl` runs a SIEM search and
   creates SOAR containers + typed CEF artifacts using the official CIM-to-CEF
   field map, with SDI dedup, severity mapping, and last-artifact automation
@@ -227,7 +229,7 @@ splunkctl mcp install              # register in .mcp.json
 splunkctl mcp serve                # start stdio MCP server
 ```
 
-The MCP server auto-generates 237 typed tools from the Click command tree
+The MCP server auto-generates 229 typed tools from the Click command tree
 (SIEM + SOAR) with progressive discovery -- agents start with 5 meta-tools
 (`help`, `usage`, `focus`, `unfocus`, `run`) and dynamically load typed
 schemas per command group. Subgroup-granular focus works for nested groups

{splunkctl-0.9.0 → splunkctl-0.10.1}/pyproject.toml

@@ -51,8 +51,10 @@ Homepage = "https://github.com/dannyota/splunkctl"
 Repository = "https://github.com/dannyota/splunkctl"
 Issues = "https://github.com/dannyota/splunkctl/issues"
 
-[tool.setuptools]
-packages = ["splunkctl", "splunkctl.commands", "splunkctl.mcp", "splunkctl.soar"]
+# Auto-discover subpackages — a hardcoded list silently dropped
+# splunkctl.commands.soar from every wheel (v0.7.0–v0.10.0).
+[tool.setuptools.packages.find]
+include = ["splunkctl*"]
 
 [tool.setuptools.dynamic]
 version = { attr = "splunkctl.__version__" }

{splunkctl-0.9.0 → splunkctl-0.10.1}/splunkctl/__init__.py

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

{splunkctl-0.9.0 → splunkctl-0.10.1}/splunkctl/client.py

@@ -15,6 +15,7 @@ from typing import Any
 import click
 import requests
 import splunklib.client as splunk_client
+import urllib3
 
 from splunkctl import config as cfg_mod
 
@@ -186,6 +187,10 @@ class _WebSession:
         self._timeout = timeout
         self._session = requests.Session()
         self._session.verify = verify
+        if not verify:
+            # verify=false is an explicit config choice (lab/self-signed);
+            # without this every request spams InsecureRequestWarning.
+            urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
         self._csrf_token: str | None = None
         self._logged_in = False
 

{splunkctl-0.9.0 → splunkctl-0.10.1}/splunkctl/commands/es.py

@@ -57,7 +57,7 @@ def _status_to_int(value: str) -> str:
     key = value.strip().lower()
     if key in _STATUS_MAP:
         return _STATUS_MAP[key]
-    if value.isdigit():
+    if value.isascii() and value.isdigit():
         return value
     known = ", ".join(_STATUS_MAP)
     raise click.BadParameter(f"'{value}' is not a known status ({known}, or 0-5)")

splunkctl-0.10.1/splunkctl/commands/soar/__init__.py

@@ -0,0 +1,65 @@
+"""SOAR command group — ``splunkctl soar <subcommand>``."""
+
+import click
+
+from splunkctl.commands.soar import (
+    containers_write as _cw,  # noqa: F401  # register writes
+)
+from splunkctl.commands.soar import (
+    playbook_runs as _pr,  # noqa: F401  # register run/runs
+)
+from splunkctl.commands.soar import (
+    playbooks_delete as _pd,  # noqa: F401  # register delete
+)
+from splunkctl.commands.soar.actions import actions_group
+from splunkctl.commands.soar.admin import audit_cmd, roles_group, users_group
+from splunkctl.commands.soar.admin_views import meta, settings, stats
+from splunkctl.commands.soar.approvals import approvals_group
+from splunkctl.commands.soar.apps import apps_group
+from splunkctl.commands.soar.artifacts import artifacts_group
+from splunkctl.commands.soar.assets import assets_group, ingest_status_cmd
+from splunkctl.commands.soar.cases import cases_group
+from splunkctl.commands.soar.containers import containers_group
+from splunkctl.commands.soar.functions import functions_group
+from splunkctl.commands.soar.indicators import evidence_group, indicators_group
+from splunkctl.commands.soar.ingest import ingest_cmd
+from splunkctl.commands.soar.lists import lists_group
+from splunkctl.commands.soar.notes import notes_group
+from splunkctl.commands.soar.playbooks import playbooks_group
+from splunkctl.commands.soar.search import search
+from splunkctl.commands.soar.system import health, info, license_cmd, test
+from splunkctl.commands.soar.vault import vault_group
+
+
+@click.group("soar")
+def soar_group() -> None:
+    """Splunk SOAR operations — platform reads, containers, playbooks."""
+
+
+soar_group.add_command(test)
+soar_group.add_command(info)
+soar_group.add_command(health)
+soar_group.add_command(license_cmd)
+soar_group.add_command(settings)
+soar_group.add_command(stats)
+soar_group.add_command(meta)
+soar_group.add_command(containers_group)
+soar_group.add_command(cases_group)
+soar_group.add_command(notes_group)
+soar_group.add_command(vault_group)
+soar_group.add_command(artifacts_group)
+soar_group.add_command(apps_group)
+soar_group.add_command(assets_group)
+soar_group.add_command(ingest_status_cmd)
+soar_group.add_command(playbooks_group)
+soar_group.add_command(actions_group)
+soar_group.add_command(functions_group)
+soar_group.add_command(approvals_group)
+soar_group.add_command(lists_group)
+soar_group.add_command(indicators_group)
+soar_group.add_command(evidence_group)
+soar_group.add_command(users_group)
+soar_group.add_command(roles_group)
+soar_group.add_command(audit_cmd)
+soar_group.add_command(search)
+soar_group.add_command(ingest_cmd)

splunkctl-0.10.1/splunkctl/commands/soar/_client.py

@@ -0,0 +1,44 @@
+"""Shared SOAR client construction for command modules."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import click
+
+from splunkctl import config as cfg_mod
+from splunkctl import output
+from splunkctl.soar.client import SOARClient
+
+
+def get_soar_client(ctx: click.Context) -> SOARClient:
+    """Build a SOARClient from the resolved SOAR config.
+
+    Raises ``SystemExit(1)`` with a ``usage`` error envelope when no
+    SOAR host is configured.
+    """
+    obj: dict[str, Any] = ctx.obj or {}
+    cfg_path = obj.get("config")
+    profile = obj.get("profile")
+    config_path = Path(cfg_path) if cfg_path else None
+    cfg = cfg_mod.resolve_soar(config_path, profile=profile)
+
+    host = cfg.get("host")
+    if not host:
+        output.error(
+            "No SOAR host configured. Run 'splunkctl config init --soar' "
+            "or set SOAR_HOST.",
+            kind="usage",
+        )
+        ctx.exit(1)
+        raise SystemExit(1)  # unreachable after ctx.exit in real Click
+
+    return SOARClient(
+        host=host,
+        port=int(cfg.get("port", 8443)),
+        token=cfg.get("token"),
+        username=cfg.get("username"),
+        password=cfg.get("password"),
+        verify=bool(cfg.get("verify", False)),
+    )

splunkctl-0.10.1/splunkctl/commands/soar/_ingest_helpers.py

@@ -0,0 +1,260 @@
+"""Ingest helpers — SIEM search, map-file loading, dedup checks, preview."""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from typing import Any
+
+import click
+import yaml
+from splunklib.results import JSONResultsReader
+
+from splunkctl import output
+from splunkctl.client import get_client
+from splunkctl.soar.cimcef import row_to_cef
+from splunkctl.soar.client import SOARError
+
+_GENERATING = (
+    "abstract",
+    "bucket",
+    "datamodel",
+    "dbinspect",
+    "eventcount",
+    "inputcsv",
+    "inputlookup",
+    "loadjob",
+    "makeresults",
+    "mcollect",
+    "metadata",
+    "metasearch",
+    "mstats",
+    "pivot",
+    "rest",
+    "savedsearch",
+    "tstats",
+    "typeahead",
+)
+
+
+def normalize_spl(spl: str) -> str:
+    """Auto-prepend ``search`` when the query needs it."""
+    stripped = spl.strip()
+    if stripped.startswith("|"):
+        return stripped
+    first_word = stripped.split()[0].lower() if stripped else ""
+    if first_word == "search" or first_word in _GENERATING:
+        return stripped
+    return f"search {stripped}"
+
+
+def read_results(stream: Any) -> list[dict[str, Any]]:
+    """Parse a Splunk results stream into a list of dicts."""
+    reader: Any = JSONResultsReader(stream)
+    rows: list[dict[str, Any]] = []
+    for item in reader:
+        if isinstance(item, dict):
+            rows.append(item)
+    return rows
+
+
+def fetch_spl_results(
+    ctx: click.Context,
+    spl: str,
+    *,
+    earliest: str | None,
+    latest: str | None,
+    app: str | None,
+) -> list[dict[str, Any]]:
+    """Run an SPL search on SIEM and return result rows."""
+    client = get_client(ctx)
+    svc = client.service
+    if app:
+        svc.namespace["app"] = app
+    query = normalize_spl(spl)
+
+    kwargs: dict[str, Any] = {"exec_mode": "normal"}
+    if earliest:
+        kwargs["earliest_time"] = earliest
+    if latest:
+        kwargs["latest_time"] = latest
+
+    output.info(f"Running SIEM search: {query}")
+    job: Any = svc.jobs.create(query, **kwargs)
+
+    timeout: int = ctx.obj.get("timeout", 30)
+    deadline = time.monotonic() + timeout
+    while not job.is_done():
+        if time.monotonic() > deadline:
+            job.cancel()
+            output.error(f"SIEM search timed out after {timeout}s.", kind="timeout")
+            ctx.exit(1)
+            raise SystemExit(1)
+        time.sleep(0.5)
+        job.refresh()
+
+    return read_results(job.results(output_mode="json", count=0))
+
+
+def fetch_sid_results(
+    ctx: click.Context,
+    sid: str,
+) -> list[dict[str, Any]]:
+    """Fetch results from an existing SIEM search job."""
+    client = get_client(ctx)
+    svc = client.service
+    try:
+        job: Any = svc.jobs[sid]
+    except KeyError:
+        output.error(f"Job '{sid}' not found on SIEM.", kind="not_found")
+        ctx.exit(1)
+        raise SystemExit(1) from None
+
+    job.refresh()
+    if not job.is_done():
+        output.error(f"Job '{sid}' is still running.", kind="error")
+        ctx.exit(1)
+        raise SystemExit(1)
+
+    return read_results(job.results(output_mode="json", count=0))
+
+
+def load_map_file(
+    path: str,
+) -> tuple[dict[str, str], dict[str, list[str]], bool]:
+    """Load a YAML map file and return (cim_map, contains_map, include_unmapped).
+
+    Format::
+
+        mappings:
+          src: {cef: sourceAddress, contains: [ip]}
+          custom_score: {cef: riskScore}
+        unmapped: drop   # or "pass"
+    """
+    data = yaml.safe_load(Path(path).read_text())
+    mappings: dict[str, Any] = data.get("mappings", {})
+    cim_map: dict[str, str] = {}
+    contains_map: dict[str, list[str]] = {}
+    for cim_field, spec in mappings.items():
+        if isinstance(spec, dict):
+            cef_key = spec.get("cef", cim_field)
+            cim_map[cim_field] = cef_key
+            contains = spec.get("contains")
+            if isinstance(contains, list) and contains:
+                contains_map[cef_key] = [str(c) for c in contains]
+        else:
+            cim_map[cim_field] = str(spec)
+    unmapped = data.get("unmapped", "drop")
+    return cim_map, contains_map, unmapped == "pass"
+
+
+def validate_label(soar: Any, label: str) -> bool:
+    """Validate that a label exists on the SOAR instance."""
+    try:
+        result = soar.get("container_options", params={})
+        labels: list[str] = []
+        if isinstance(result, dict):
+            for item in result.get("label", []):
+                if isinstance(item, str):
+                    labels.append(item)
+                elif isinstance(item, dict):
+                    labels.append(str(item.get("name", item.get("label", ""))))
+        if labels and label not in labels:
+            output.warning(
+                f"Label '{label}' not found on SOAR "
+                f"(available: {', '.join(labels)}). "
+                f"Container creation may fail."
+            )
+            return False
+    except SOARError:
+        pass
+    return True
+
+
+def dedup_check_container(soar: Any, sdi: str) -> int | None:
+    """Check if a container with this SDI already exists."""
+    try:
+        result = soar.get(
+            "container",
+            params={"_filter_source_data_identifier": json.dumps(sdi)},
+        )
+        data = result.get("data", []) if isinstance(result, dict) else []
+        if data:
+            return int(data[0].get("id", 0))
+    except SOARError:
+        pass
+    return None
+
+
+def dedup_check_artifact(soar: Any, sdi: str, container_id: int) -> int | None:
+    """Check if an artifact with this SDI already exists."""
+    try:
+        result = soar.get(
+            "artifact",
+            params={
+                "_filter_source_data_identifier": json.dumps(sdi),
+                "_filter_container": container_id,
+            },
+        )
+        data = result.get("data", []) if isinstance(result, dict) else []
+        if data:
+            return int(data[0].get("id", 0))
+    except SOARError:
+        pass
+    return None
+
+
+class ContainerGroup:
+    """Accumulator for rows destined for one container."""
+
+    __slots__ = ("name", "rows", "severity", "sdi")
+
+    def __init__(self, name: str, severity: str, sdi: str) -> None:
+        self.name = name
+        self.rows: list[dict[str, Any]] = []
+        self.severity = severity
+        self.sdi = sdi
+
+
+def build_preview(
+    groups: dict[str, ContainerGroup],
+    cim_map: dict[str, str],
+    *,
+    include_unmapped: bool = False,
+) -> str:
+    """Build the dry-run preview string."""
+    lines: list[str] = []
+    lines.append(f"Containers: {len(groups)}")
+    for grp in groups.values():
+        # The dict key is name::sdi (an internal dedup key) — render the
+        # name and SDI separately; SDIs often contain colons themselves.
+        sdi_note = f" (sdi: {grp.sdi})" if grp.sdi else ""
+        lines.append(f"  {grp.name}{sdi_note}: {len(grp.rows)} artifact(s)")
+
+    lines.append("")
+    lines.append("CIM -> CEF mapping (active):")
+    shown = 0
+    for cim, cef in sorted(cim_map.items()):
+        lines.append(f"  {cim} -> {cef}")
+        shown += 1
+        if shown >= 10:
+            remaining = len(cim_map) - shown
+            if remaining > 0:
+                lines.append(f"  ... and {remaining} more")
+            break
+
+    if groups:
+        first_grp = next(iter(groups.values()))
+        if first_grp.rows:
+            sample_cef = row_to_cef(
+                first_grp.rows[0],
+                cim_map=cim_map,
+                include_unmapped=include_unmapped,
+            )
+            if sample_cef:
+                lines.append("")
+                lines.append("Sample CEF payload:")
+                lines.append(json.dumps(sample_cef, indent=2, default=str))
+
+    return "\n".join(lines)