splunkctl 0.5.0__tar.gz → 0.7.0__tar.gz

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

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

{splunkctl-0.5.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.5.0 → splunkctl-0.7.0}/splunkctl/__init__.py

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

{splunkctl-0.5.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.5.0 → splunkctl-0.7.0}/splunkctl/commands/knowledge.py

@@ -17,6 +17,7 @@ uses.
 """
 
 import re
+import urllib.parse
 from typing import Any
 
 import click
@@ -275,9 +276,15 @@ def eventtypes_get(ctx: click.Context, name: str, app: str | None) -> None:
 # each key inside the stanza is a tag name whose value is enabled/disabled.
 # `disabled` itself is the stanza-level flag, not a tag, and eai:* keys are
 # read-only REST metadata — both are excluded from the tag-name views below.
+# REST returns stanza names URL-encoded (`eventtype=cim%3Aauth`); the views
+# decode them, and `tags get` accepts either form.
 _TAG_METADATA_KEYS = {"disabled"}
 
 
+def _decode_stanza(name: str) -> str:
+    return urllib.parse.unquote(name)
+
+
 def _is_tag_key(key: str) -> bool:
     return key not in _TAG_METADATA_KEYS and not key.startswith("eai:")
 
@@ -335,7 +342,7 @@ def tags_list(
     )
     rows: list[dict[str, Any]] = [
         {
-            "field_value": s.name,
+            "field_value": _decode_stanza(s.name),
             "tags": ";".join(_enabled_tag_names(dict(s.content))),
             "app": dict(s.access).get("app", ""),
         }
@@ -359,9 +366,16 @@ def tags_get(ctx: click.Context, field_value: str, app: str | None) -> None:
     try:
         entity = conf_ops.get_stanza(client, "tags", field_value, app=app)
     except KeyError:
-        output.error(
-            f"Stanza '{field_value}' not found in tags.conf.", kind="not_found"
-        )
-        ctx.exit(1)
-        return
-    output.render(ctx, {"name": entity.name, **_tag_states(dict(entity.content))})
+        encoded = urllib.parse.quote(field_value, safe="=")
+        try:
+            entity = conf_ops.get_stanza(client, "tags", encoded, app=app)
+        except KeyError:
+            output.error(
+                f"Stanza '{field_value}' not found in tags.conf.", kind="not_found"
+            )
+            ctx.exit(1)
+            return
+    output.render(
+        ctx,
+        {"name": _decode_stanza(entity.name), **_tag_states(dict(entity.content))},
+    )

splunkctl-0.7.0/splunkctl/commands/server.py

@@ -0,0 +1,179 @@
+"""Server operations — messages, license, KV store, topology health."""
+
+import json
+from datetime import UTC, datetime
+from typing import Any
+
+import click
+
+from splunkctl import guard, output
+from splunkctl.client import get_client
+
+
+def _human_bytes(n: int) -> str:
+    size = float(n)
+    for unit in ("B", "KB", "MB", "GB", "TB"):
+        if abs(size) < 1024 or unit == "TB":
+            return f"{size:.0f} {unit}" if unit == "B" else f"{size:.1f} {unit}"
+        size /= 1024
+    return f"{n} B"
+
+
+@click.group("server")
+def server_group() -> None:
+    """Server operations — messages, license, KV store, topology health."""
+
+
+@server_group.command("messages")
+@guard.guarded
+@click.option("--dismiss", default=None, help="Delete a message by name.")
+@click.pass_context
+def messages(ctx: click.Context, dismiss: str | None) -> None:
+    """List system messages, or dismiss one with --dismiss NAME --yes."""
+    client = get_client(ctx)
+    svc = client.service
+
+    if dismiss is not None:
+        if not guard.check(ctx, f"Dismiss system message '{dismiss}'"):
+            return
+        try:
+            msg = svc.messages[dismiss]
+        except KeyError:
+            output.error(f"Message '{dismiss}' not found.", kind="not_found")
+            ctx.exit(1)
+            return
+        msg.delete()
+        output.info(f"Message '{dismiss}' dismissed.")
+        return
+
+    rows: list[dict[str, Any]] = []
+    for msg in svc.messages.list():
+        c: dict[str, Any] = msg.content
+        rows.append(
+            {
+                "name": msg.name,
+                "severity": c.get("severity", ""),
+                "message": c.get("message", ""),
+                "time_created": c.get("timeCreated_iso", c.get("timeCreated", "")),
+            }
+        )
+    output.render(ctx, rows, empty="No system messages.")
+
+
+# Splunk encodes "never expires" as INT32_MAX seconds.
+_PERPETUAL = 2**31 - 1
+
+
+def _render_license_usage(ctx: click.Context, svc: Any) -> None:
+    """Render today's indexed volume vs quota plus license expiry."""
+    resp = svc.get("/services/licenser/usage", output_mode="json")
+    body: dict[str, Any] = json.loads(resp.body.read())
+    entries: list[dict[str, Any]] = body.get("entry", [])
+    c: dict[str, Any] = entries[0].get("content", {}) if entries else {}
+    used = int(c.get("slaves_usage_bytes", 0))
+    quota = int(c.get("quota", 0))
+    pct = round(used / quota * 100, 1) if quota else 0.0
+
+    resp = svc.get("/services/licenser/licenses", output_mode="json")
+    lic_body: dict[str, Any] = json.loads(resp.body.read())
+    valid = 0
+    expiries: list[int] = []
+    for entry in lic_body.get("entry", []):
+        lc: dict[str, Any] = entry.get("content", {})
+        if lc.get("status") == "VALID":
+            valid += 1
+        exp = int(lc.get("expiration_time", _PERPETUAL))
+        if exp < _PERPETUAL:
+            expiries.append(exp)
+    soonest = (
+        datetime.fromtimestamp(min(expiries), tz=UTC).strftime("%Y-%m-%d")
+        if expiries
+        else "never"
+    )
+
+    output.render(
+        ctx,
+        {
+            "used": _human_bytes(used),
+            "quota": _human_bytes(quota),
+            "pct_used": pct,
+            "licenses_valid": valid,
+            "soonest_expiry": soonest,
+        },
+    )
+
+
+@server_group.command("license")
+@click.option(
+    "--usage",
+    "show_usage",
+    is_flag=True,
+    help="Today's indexed volume vs quota and soonest license expiry.",
+)
+@click.pass_context
+def license_pools(ctx: click.Context, *, show_usage: bool) -> None:
+    """Show license pool usage, or daily volume and expiry with --usage."""
+    client = get_client(ctx)
+    if show_usage:
+        _render_license_usage(ctx, client.service)
+        return
+
+    resp = client.service.get("/services/licenser/pools", output_mode="json")
+    body: dict[str, Any] = json.loads(resp.body.read())
+
+    rows: list[dict[str, Any]] = []
+    for entry in body.get("entry", []):
+        c: dict[str, Any] = entry.get("content", {})
+        used = int(c.get("used_bytes", 0))
+        quota = int(c.get("effective_quota", 0))
+        rows.append(
+            {
+                "title": entry.get("name", ""),
+                "used": _human_bytes(used),
+                "quota": _human_bytes(quota),
+            }
+        )
+    output.render(ctx, rows, empty="No license pools found.")
+
+
+@server_group.command("kvstore")
+@click.pass_context
+def kvstore_status(ctx: click.Context) -> None:
+    """Show KV store status."""
+    client = get_client(ctx)
+    resp = client.service.get("/services/kvstore/status", output_mode="json")
+    body: dict[str, Any] = json.loads(resp.body.read())
+
+    entries: list[dict[str, Any]] = body.get("entry", [])
+    if not entries:
+        output.error("No KV store status available.")
+        ctx.exit(1)
+        return
+
+    c: dict[str, Any] = entries[0].get("content", {})
+    current: dict[str, Any] = c.get("current") or {}
+    status_raw = current.get("status")
+    status = "unknown" if not status_raw else str(status_raw).lower()
+    row: dict[str, Any] = {
+        "status": status,
+        "port": current.get("port", ""),
+        "version": current.get("version", ""),
+        "storage_engine": current.get("storageEngine", ""),
+        "db_path": current.get("dbPath", ""),
+    }
+    output.render(ctx, row)
+
+
+from splunkctl.commands.server_topology import (  # noqa: E402
+    cluster_health,
+    deployment_health,
+    health_report,
+    search_peers,
+    shcluster_health,
+)
+
+server_group.add_command(cluster_health)
+server_group.add_command(shcluster_health)
+server_group.add_command(deployment_health)
+server_group.add_command(health_report)
+server_group.add_command(search_peers)