splunkctl 0.2.0__tar.gz → 0.3.0__tar.gz

{splunkctl-0.2.0 → splunkctl-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: splunkctl
-Version: 0.2.0
+Version: 0.3.0
 Summary: CLI tool for Splunk Enterprise SIEM operations.
 Author: dannyota
 License-Expression: Apache-2.0
@@ -20,9 +20,19 @@ Requires-Python: >=3.13
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: splunk-sdk>=2.0
-Requires-Dist: click>=8.0
+Requires-Dist: click>=8.2
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: tabulate>=0.9
+Requires-Dist: requests>=2.32
+Requires-Dist: defusedxml>=0.7
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
+Requires-Dist: types-requests; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+Requires-Dist: types-tabulate; extra == "dev"
+Requires-Dist: types-defusedxml; extra == "dev"
 Dynamic: license-file
 
 # splunkctl

{splunkctl-0.2.0 → splunkctl-0.3.0}/pyproject.toml

@@ -24,9 +24,22 @@ classifiers = [
 ]
 dependencies = [
     "splunk-sdk>=2.0",
-    "click>=8.0",
+    "click>=8.2",
     "pyyaml>=6.0",
     "tabulate>=0.9",
+    "requests>=2.32",
+    "defusedxml>=0.7",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.6",
+    "mypy>=1.11",
+    "types-requests",
+    "types-PyYAML",
+    "types-tabulate",
+    "types-defusedxml",
 ]
 
 [project.scripts]

{splunkctl-0.2.0 → splunkctl-0.3.0}/splunkctl/__init__.py

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

{splunkctl-0.2.0 → splunkctl-0.3.0}/splunkctl/client.py

@@ -6,17 +6,13 @@ handle remotely (e.g. lookup file upload requires server-side staging).
 
 from __future__ import annotations
 
-import http.cookiejar
-import json
 import re
-import ssl
 import urllib.parse
-import urllib.request
-import uuid
 from pathlib import Path
 from typing import Any
 
 import click
+import requests
 import splunklib.client as splunk_client
 
 from splunkctl import config as cfg_mod
@@ -111,7 +107,10 @@ class SplunkClient:
             cfg = cfg_mod.load(self._config_path)
             cfg.update(self._overrides)
             self._web_session = _WebSession(
-                self.service, verify=bool(cfg.get("verify", False))
+                self.service,
+                verify=bool(cfg.get("verify", False)),
+                debug=self._debug,
+                timeout=self._timeout or 30,
             )
         return self._web_session
 
@@ -137,11 +136,36 @@ class SplunkClient:
         """Install a .spl/.tar.gz app package via the Splunk Web UI."""
         self._ensure_web_session().install_app(file_path, force=force)
 
+    def set_acl(self, entity: Any, *, sharing: str, owner: str | None = None) -> None:
+        """Change an entity's sharing level via its ACL endpoint.
+
+        Args:
+            entity: Any SDK entity (saved search, dashboard, conf stanza...).
+            sharing: One of user, app, global.
+            owner: Defaults to the entity's current owner, else "nobody".
+        """
+        acl: dict[str, Any] = dict(entity.access)
+        entity.acl_update(sharing=sharing, owner=owner or acl.get("owner", "nobody"))
+
 
 class _WebSession:
-    """Manages authentication and uploads via Splunk Web UI."""
+    """Authenticated Splunk Web session for form-handler operations.
+
+    Uses ``requests`` deliberately: the manager form handlers answer a
+    plain urllib POST with a 303 that dead-ends in a 404, while a
+    keep-alive session receives the JSON result directly (verified
+    against Splunk 10.4). TLS verification is on unless the user's
+    config explicitly disables it for self-signed dev instances.
+    """
 
-    def __init__(self, service: Any, *, verify: bool = True) -> None:
+    def __init__(
+        self,
+        service: Any,
+        *,
+        verify: bool = True,
+        debug: bool = False,
+        timeout: int = 30,
+    ) -> None:
         self._host: str = service.host
         self._username: str = service.username
         self._password: str = service.password
@@ -155,15 +179,10 @@ class _WebSession:
         self._web_port = int(web_conf["httpport"])
         self._web_ssl = str(web_conf.content.get("enableSplunkWebSSL", "0")) == "1"
 
-        self._cookies = http.cookiejar.CookieJar()
-        ctx = ssl.create_default_context()
-        if not verify:
-            ctx.check_hostname = False
-            ctx.verify_mode = ssl.CERT_NONE  # noqa: S501
-        self._opener = urllib.request.build_opener(
-            urllib.request.HTTPCookieProcessor(self._cookies),
-            urllib.request.HTTPSHandler(context=ctx),
-        )
+        self._debug = debug
+        self._timeout = timeout
+        self._session = requests.Session()
+        self._session.verify = verify
         self._csrf_token: str | None = None
         self._logged_in = False
 
@@ -172,80 +191,47 @@ class _WebSession:
         scheme = "https" if self._web_ssl else "http"
         return f"{scheme}://{self._host}:{self._web_port}"
 
+    def _request(self, method: str, url: str, **kwargs: Any) -> requests.Response:
+        resp = self._session.request(method, url, timeout=self._timeout, **kwargs)
+        if self._debug:
+            click.echo(f"web {method} {url} -> {resp.status_code}", err=True)
+        return resp
+
     def _login(self) -> None:
         """Authenticate to Splunk Web and obtain session cookies."""
         login_url = f"{self._base_url}/en-US/account/login"
-        resp = self._opener.open(login_url)  # noqa: S310
-        page = resp.read().decode("utf-8")
+        page = self._request("GET", login_url).text
 
         m = re.search(r'"cval"\s*:\s*(\d+)', page)
         cval = m.group(1) if m else "0"
 
-        data = urllib.parse.urlencode(
-            {
+        resp = self._request(
+            "POST",
+            login_url,
+            data={
                 "username": self._username,
                 "password": self._password,
                 "cval": cval,
-            }
-        ).encode()
-        resp = self._opener.open(login_url, data)  # noqa: S310
-        body = json.loads(resp.read().decode("utf-8"))
+            },
+        )
+        try:
+            body: dict[str, Any] = resp.json()
+        except ValueError:
+            raise RuntimeError(
+                f"Splunk Web login failed: HTTP {resp.status_code}"
+            ) from None
         if body.get("status") == "fail":
             msg = body.get("msg", "unknown error")
             raise RuntimeError(f"Splunk Web login failed: {msg}")
 
-        for cookie in self._cookies:
-            if cookie.name.startswith("splunkweb_csrf_token"):
+        for cookie in self._session.cookies:
+            if cookie.name and cookie.name.startswith("splunkweb_csrf_token"):
                 self._csrf_token = cookie.value
                 break
         if not self._csrf_token:
             raise RuntimeError("Could not obtain CSRF token from Splunk Web")
         self._logged_in = True
 
-    def _multipart_post(
-        self,
-        url: str,
-        fields: list[tuple[str, str]],
-        file_field: str,
-        file_name: str,
-        file_data: bytes,
-        content_type: str = "application/octet-stream",
-    ) -> bytes:
-        """Build and send a multipart/form-data POST."""
-        if not self._logged_in:
-            self._login()
-
-        boundary = uuid.uuid4().hex
-        body = b""
-        for field_name, value in fields:
-            body += f"--{boundary}\r\n".encode()
-            body += (
-                f'Content-Disposition: form-data; name="{field_name}"\r\n'
-                f"\r\n"
-                f"{value}\r\n"
-            ).encode()
-
-        body += f"--{boundary}\r\n".encode()
-        body += (
-            f'Content-Disposition: form-data; name="{file_field}";'
-            f' filename="{file_name}"\r\n'
-            f"Content-Type: {content_type}\r\n"
-            f"\r\n"
-        ).encode()
-        body += file_data
-        body += f"\r\n--{boundary}--\r\n".encode()
-
-        req = urllib.request.Request(  # noqa: S310
-            url,
-            data=body,
-            headers={
-                "Content-Type": f"multipart/form-data; boundary={boundary}",
-            },
-            method="POST",
-        )
-        resp = self._opener.open(req)  # noqa: S310
-        return bytes(resp.read())
-
     def upload_lookup(
         self,
         name: str,
@@ -255,6 +241,9 @@ class _WebSession:
         update: bool = False,
     ) -> None:
         """Upload a lookup file via multipart form POST."""
+        if not self._logged_in:
+            self._login()
+
         if update:
             url = (
                 f"{self._base_url}/en-US/manager/{app}"
@@ -265,27 +254,22 @@ class _WebSession:
             url = f"{self._base_url}/en-US/manager/{app}/data/lookup-table-files/_new"
             action = "new"
 
-        fields: list[tuple[str, str]] = [
-            ("__action", action),
-            ("__redirect", ""),
-            ("__ns", app),
-            ("splunk_form_key", self._csrf_token or ""),
-        ]
+        data: dict[str, str] = {
+            "__action": action,
+            "__redirect": "",
+            "__ns": app,
+            "splunk_form_key": self._csrf_token or "",
+        }
         if not update:
-            fields.append(("name", name))
+            data["name"] = name
 
-        resp_body = self._multipart_post(
+        resp = self._request(
+            "POST",
             url,
-            fields,
-            file_field="spl-ctrl_lookupfile",
-            file_name=name,
-            file_data=file_path.read_bytes(),
-            content_type="text/csv",
+            data=data,
+            files={"spl-ctrl_lookupfile": (name, file_path.read_bytes(), "text/csv")},
         )
-        result = json.loads(resp_body.decode("utf-8"))
-        if result.get("status") != "OK":
-            msg = result.get("msg", "unknown error")
-            raise RuntimeError(f"Lookup upload failed: {msg}")
+        _expect_ok(resp, "Lookup upload")
 
     def install_app(
         self,
@@ -298,30 +282,45 @@ class _WebSession:
             self._login()
 
         upload_url = f"{self._base_url}/en-US/manager/appinstall/_upload"
-        resp = self._opener.open(upload_url)  # noqa: S310
-        page = resp.read().decode("utf-8")
+        page = self._request("GET", upload_url).text
 
-        m = re.search(
-            r'name="state"\s+[^>]*value="([^"]*)"',
-            page,
-        )
+        m = re.search(r'name="state"\s+[^>]*value="([^"]*)"', page)
         state = m.group(1) if m else ""
 
-        fields: list[tuple[str, str]] = [
-            ("state", state),
-            ("splunk_form_key", self._csrf_token or ""),
-        ]
+        data: dict[str, str] = {
+            "state": state,
+            "splunk_form_key": self._csrf_token or "",
+        }
         if force:
-            fields.append(("force", "1"))
+            data["force"] = "1"
 
-        self._multipart_post(
+        resp = self._request(
+            "POST",
             upload_url,
-            fields,
-            file_field="appfile",
-            file_name=file_path.name,
-            file_data=file_path.read_bytes(),
-            content_type="application/gzip",
+            data=data,
+            files={
+                "appfile": (
+                    file_path.name,
+                    file_path.read_bytes(),
+                    "application/gzip",
+                )
+            },
         )
+        if resp.status_code >= 400:
+            raise RuntimeError(f"App install failed: HTTP {resp.status_code}")
+
+
+def _expect_ok(resp: requests.Response, what: str) -> None:
+    """Raise unless the form handler answered with JSON status OK."""
+    try:
+        result: dict[str, Any] = resp.json()
+    except ValueError:
+        raise RuntimeError(
+            f"{what} failed: HTTP {resp.status_code} — "
+            f"unexpected response: {resp.text[:200]!r}"
+        ) from None
+    if result.get("status") != "OK":
+        raise RuntimeError(f"{what} failed: {result.get('msg', 'unknown error')}")
 
 
 def get_client(ctx: click.Context) -> SplunkClient:

splunkctl-0.3.0/splunkctl/commands/alerts.py

@@ -0,0 +1,131 @@
+"""Alerts commands — fired alerts, alert actions, suppression."""
+
+from typing import Any
+
+import click
+
+from splunkctl import guard, output
+from splunkctl.client import get_client
+
+
+def _firing_rows(group: Any) -> list[dict[str, Any]]:
+    """One row per triggered alert in a fired-alert group."""
+    rows: list[dict[str, Any]] = []
+    for firing in group.alerts:
+        c: dict[str, Any] = dict(firing.content)
+        rows.append(
+            {
+                "rule": group.name,
+                "triggered": c.get("trigger_time_rendered", c.get("trigger_time", "")),
+                "severity": c.get("severity", ""),
+                "sid": c.get("sid", ""),
+                "actions": c.get("actions", ""),
+            }
+        )
+    return rows
+
+
+@click.group("alerts")
+def alerts_group() -> None:
+    """Manage fired alerts and alert actions."""
+
+
+@alerts_group.command("list")
+@click.pass_context
+def list_alerts(ctx: click.Context) -> None:
+    """List fired alerts (one row per firing, with sid for drill-down)."""
+    client = get_client(ctx)
+    rows: list[dict[str, Any]] = []
+    for group in client.service.fired_alerts:
+        if group.name == "-":
+            continue
+        rows.extend(_firing_rows(group))
+    output.render(ctx, rows, empty="No fired alerts.")
+
+
+@alerts_group.command("get")
+@click.argument("name")
+@click.pass_context
+def get_alert(ctx: click.Context, name: str) -> None:
+    """Get every firing of a fired-alert group."""
+    client = get_client(ctx)
+    for group in client.service.fired_alerts:
+        if group.name == name:
+            rows = _firing_rows(group)
+            output.info(f"{name}: {len(rows)} firing(s)")
+            output.render(ctx, rows)
+            return
+    output.error(f"Fired alert not found: {name}")
+    ctx.exit(1)
+
+
+@alerts_group.command("actions")
+@click.pass_context
+def list_actions(ctx: click.Context) -> None:
+    """List available alert action types."""
+    client = get_client(ctx)
+    rows: list[dict[str, Any]] = []
+    for stanza in client.service.confs["alert_actions"]:
+        content: dict[str, Any] = dict(stanza.content)
+        rows.append(
+            {
+                "name": stanza.name,
+                "label": content.get("label", ""),
+                "description": content.get("description", ""),
+            }
+        )
+    output.render(ctx, rows)
+
+
+@alerts_group.command("suppress")
+@guard.guarded
+@click.argument("name")
+@click.option(
+    "--duration",
+    type=int,
+    default=3600,
+    help="Throttle window in seconds.",
+)
+@click.pass_context
+def suppress_alert(ctx: click.Context, name: str, duration: int) -> None:
+    """Throttle a rule's alerts by setting alert.suppress on its saved search.
+
+    Splunk's fired-alerts endpoint cannot be edited; throttling is a
+    property of the underlying saved search.
+    """
+    details = (
+        f"Set alert.suppress=1, alert.suppress.period={duration}s "
+        f"on saved search '{name}'"
+    )
+    if not guard.check(ctx, "Throttle alerts for rule", details=details):
+        return
+    client = get_client(ctx)
+    try:
+        ss = client.service.saved_searches[name]
+    except KeyError:
+        output.error(f"Saved search not found: {name}")
+        ctx.exit(1)
+        return
+    ss.update(
+        **{"alert.suppress": "1", "alert.suppress.period": f"{duration}s"}
+    ).refresh()
+    output.info(f"Throttled '{name}' for {duration}s.")
+
+
+@alerts_group.command("unsuppress")
+@guard.guarded
+@click.argument("name")
+@click.pass_context
+def unsuppress_alert(ctx: click.Context, name: str) -> None:
+    """Remove alert throttling from a rule's saved search."""
+    if not guard.check(ctx, f"Remove alert throttling from '{name}'"):
+        return
+    client = get_client(ctx)
+    try:
+        ss = client.service.saved_searches[name]
+    except KeyError:
+        output.error(f"Saved search not found: {name}")
+        ctx.exit(1)
+        return
+    ss.update(**{"alert.suppress": "0"}).refresh()
+    output.info(f"Removed throttling from '{name}'.")

{splunkctl-0.2.0 → splunkctl-0.3.0}/splunkctl/commands/apps.py

@@ -67,6 +67,7 @@ def get_app(ctx: click.Context, name: str) -> None:
 
 
 @apps_group.command("install")
+@guard.guarded
 @click.option(
     "--path",
     "file_path",
@@ -100,6 +101,7 @@ def install_app(ctx: click.Context, file_path: str, *, force: bool) -> None:
 
 
 @apps_group.command("uninstall")
+@guard.guarded
 @click.argument("name")
 @click.pass_context
 def uninstall_app(ctx: click.Context, name: str) -> None:
@@ -125,6 +127,7 @@ def uninstall_app(ctx: click.Context, name: str) -> None:
 
 
 @apps_group.command("update")
+@guard.guarded
 @click.argument("name")
 @click.option("--visible/--hidden", default=None, help="Set app visibility.")
 @click.option("--enabled/--disabled", default=None, help="Enable or disable the app.")
@@ -173,6 +176,7 @@ def update_app(
 
 
 @apps_group.command("reload")
+@guard.guarded
 @click.pass_context
 def reload_apps(ctx: click.Context) -> None:
     """Reload all apps."""

{splunkctl-0.2.0 → splunkctl-0.3.0}/splunkctl/commands/commands_meta.py

@@ -6,6 +6,7 @@ from typing import Any
 import click
 
 from splunkctl import __version__, output
+from splunkctl.guard import is_guarded
 
 
 def _param_entry(p: click.Parameter) -> dict[str, Any]:
@@ -45,6 +46,8 @@ def _walk(group: click.Group) -> list[dict[str, Any]]:
         if isinstance(cmd, click.Group):
             node["subcommands"] = _walk(cmd)
         else:
+            if is_guarded(cmd):
+                node["guarded"] = True
             params: list[dict[str, Any]] = []
             for p in cmd.params:
                 if p.name in ("help",):
@@ -65,8 +68,13 @@ def commands_meta(ctx: click.Context) -> None:
         output.error("Cannot resolve CLI root.")
         ctx.exit(1)
         return
+    global_opts = [
+        _param_entry(p) for p in root.command.params if p.name not in ("help",)
+    ]
     result: dict[str, Any] = {
         "version": __version__,
+        "global_options": global_opts,
+        "note": "guarded commands are dry-run by default; pass --yes to apply",
         "commands": _walk(root.command),
     }
     click.echo(json.dumps(result, indent=2))