splunkctl 0.1.0__py3-none-any.whl

splunkctl/__init__.py

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

splunkctl/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as `python -m splunkctl`."""
+
+from splunkctl.main import cli
+
+cli()

splunkctl/client.py

@@ -0,0 +1,103 @@
+"""SDK wrapper — lazy connection and auth resolution."""
+
+from pathlib import Path
+from typing import Any
+
+import click
+import splunklib.client as splunk_client
+
+from splunkctl import config as cfg_mod
+
+
+class SplunkClient:
+    """Lazy-initializing Splunk SDK client.
+
+    Connection is established on first access to ``.service``.
+    Help, config, and offline commands never trigger auth.
+    """
+
+    def __init__(  # noqa: D107
+        self,
+        *,
+        config_path: Path | None = None,
+        host: str | None = None,
+        port: int | None = None,
+        username: str | None = None,
+        password: str | None = None,
+        token: str | None = None,
+        scheme: str | None = None,
+        app: str | None = None,
+        owner: str | None = None,
+        verify: bool | None = None,
+        timeout: int = 30,
+        debug: bool = False,
+    ) -> None:
+        self._config_path = config_path
+        self._overrides: dict[str, Any] = {
+            k: v
+            for k, v in {
+                "host": host,
+                "port": port,
+                "username": username,
+                "password": password,
+                "token": token,
+                "scheme": scheme,
+                "app": app,
+                "owner": owner,
+                "verify": verify,
+            }.items()
+            if v is not None
+        }
+        self._timeout = timeout
+        self._debug = debug
+        self._service: Any = None
+
+    @property
+    def service(self) -> Any:
+        """Connect on first access."""
+        if self._service is None:
+            if self._debug:
+                import logging
+
+                logging.basicConfig(level=logging.DEBUG)
+                logging.getLogger("splunklib").setLevel(logging.DEBUG)
+
+            cfg = cfg_mod.load(self._config_path)
+            cfg.update(self._overrides)
+
+            connect_args: dict[str, Any] = {
+                "host": cfg.get("host", "localhost"),
+                "port": int(cfg.get("port", 8089)),
+                "scheme": cfg.get("scheme", "https"),
+            }
+
+            if cfg.get("token"):
+                connect_args["splunkToken"] = cfg["token"]
+            else:
+                connect_args["username"] = cfg.get("username", "")
+                connect_args["password"] = cfg.get("password", "")
+
+            if cfg.get("app"):
+                connect_args["app"] = cfg["app"]
+            if cfg.get("owner"):
+                connect_args["owner"] = cfg["owner"]
+
+            if not cfg.get("verify", False):
+                connect_args["verify"] = False
+
+            if self._timeout:
+                connect_args["timeout"] = self._timeout
+
+            self._service = splunk_client.connect(**connect_args)
+
+        return self._service
+
+
+def get_client(ctx: click.Context) -> SplunkClient:
+    """Build a SplunkClient from Click context. Does not connect."""
+    obj: dict[str, Any] = ctx.ensure_object(dict)
+    return SplunkClient(
+        config_path=Path(obj["config"]) if obj.get("config") else None,
+        timeout=obj.get("timeout", 30),
+        debug=obj.get("debug", False),
+    )

splunkctl/commands/alerts.py

@@ -0,0 +1,94 @@
+"""Alerts commands — fired alerts, alert actions, suppression."""
+
+from typing import Any
+from urllib.parse import quote
+
+import click
+
+from splunkctl import output
+from splunkctl.client import get_client
+from splunkctl.guard import check
+
+
+@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."""
+    client = get_client(ctx)
+    rows: list[dict[str, Any]] = []
+    for alert in client.service.fired_alerts:
+        if alert.name == "-":
+            continue
+        content: dict[str, Any] = dict(alert.content)
+        rows.append(
+            {
+                "name": alert.name,
+                "count": alert.count,
+                "triggered_time": content.get("triggered_time", ""),
+                "severity": content.get("severity", ""),
+            }
+        )
+    if not rows:
+        output.info("No fired alerts.")
+        return
+    output.render(ctx, rows)
+
+
+@alerts_group.command("get")
+@click.argument("name")
+@click.pass_context
+def get_alert(ctx: click.Context, name: str) -> None:
+    """Get details of a specific fired alert group."""
+    client = get_client(ctx)
+    try:
+        alert = client.service.fired_alerts[name]
+    except KeyError:
+        output.error(f"Fired alert not found: {name}")
+        ctx.exit(1)
+        return
+    row: dict[str, Any] = {"name": alert.name, "count": alert.count}
+    row.update(dict(alert.content))
+    output.render(ctx, row)
+
+
+@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")
+@click.argument("name")
+@click.option(
+    "--duration",
+    type=int,
+    default=3600,
+    help="Suppression duration in seconds.",
+)
+@click.pass_context
+def suppress_alert(ctx: click.Context, name: str, duration: int) -> None:
+    """Suppress a fired alert (guarded)."""
+    details = f"Suppress '{name}' for {duration}s"
+    if not check(ctx, "suppress fired alert", details=details):
+        return
+    client = get_client(ctx)
+    path = f"/services/alerts/fired_alerts/{quote(name, safe='')}"
+    client.service.post(path, suppress="1", expiration=str(duration))
+    output.info(f"Suppressed: {name} for {duration}s")

splunkctl/commands/apps.py

@@ -0,0 +1,189 @@
+"""App management commands — list, get, install, uninstall, update, reload."""
+
+from typing import Any
+
+import click
+
+from splunkctl import guard, output
+from splunkctl.client import get_client
+
+_APP_FIELDS = ("label", "version", "visible", "disabled", "author", "description")
+
+
+def _app_row(app: Any) -> dict[str, Any]:
+    content: dict[str, Any] = dict(app.content)
+    return {
+        "name": app.name,
+        **{f: content.get(f, "") for f in _APP_FIELDS},
+    }
+
+
+def _list_fields(app: Any) -> dict[str, Any]:
+    content: dict[str, Any] = dict(app.content)
+    return {
+        "name": app.name,
+        "label": content.get("label", ""),
+        "version": content.get("version", ""),
+        "visible": content.get("visible", ""),
+        "disabled": content.get("disabled", ""),
+        "author": content.get("author", ""),
+    }
+
+
+@click.group("apps")
+def apps_group() -> None:
+    """Manage Splunk apps."""
+
+
+@apps_group.command("list")
+@click.pass_context
+def list_apps(ctx: click.Context) -> None:
+    """List installed apps."""
+    client = get_client(ctx)
+    svc = client.service
+    apps = svc.apps.list()
+    if not apps:
+        output.info("No apps found.")
+        return
+    rows = [_list_fields(a) for a in apps]
+    output.render(ctx, rows)
+
+
+@apps_group.command("get")
+@click.argument("name")
+@click.pass_context
+def get_app(ctx: click.Context, name: str) -> None:
+    """Get app details."""
+    client = get_client(ctx)
+    svc = client.service
+    try:
+        app = svc.apps[name]
+    except KeyError:
+        output.error(f"App '{name}' not found.")
+        ctx.exit(1)
+        return
+    output.render(ctx, _app_row(app))
+
+
+@apps_group.command("install")
+@click.option("--name", required=True, help="App name.")
+@click.option(
+    "--path",
+    "file_path",
+    required=True,
+    type=click.Path(exists=True),
+    help="Path to .tar.gz or .spl package.",
+)
+@click.pass_context
+def install_app(ctx: click.Context, name: str, file_path: str) -> None:
+    """Install an app from a .tar.gz or .spl file."""
+    details = f"Install app '{name}' from '{file_path}'"
+    if not guard.check(ctx, details):
+        return
+
+    client = get_client(ctx)
+    svc = client.service
+    try:
+        svc.post(
+            "/services/apps/local",
+            name=name,
+            update=True,
+            filename=True,
+            **{"appfile": file_path},
+        )
+    except Exception as exc:
+        output.error(f"Install failed: {exc}")
+        ctx.exit(1)
+        return
+    output.info(f"Installed app '{name}'.")
+
+
+@apps_group.command("uninstall")
+@click.argument("name")
+@click.pass_context
+def uninstall_app(ctx: click.Context, name: str) -> None:
+    """Uninstall an app."""
+    details = f"Uninstall app '{name}'"
+    if not guard.check(ctx, details):
+        return
+
+    client = get_client(ctx)
+    svc = client.service
+    try:
+        app = svc.apps[name]
+        app.delete()
+    except KeyError:
+        output.error(f"App '{name}' not found.")
+        ctx.exit(1)
+        return
+    except Exception as exc:
+        output.error(f"Uninstall failed: {exc}")
+        ctx.exit(1)
+        return
+    output.info(f"Uninstalled app '{name}'.")
+
+
+@apps_group.command("update")
+@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.")
+@click.pass_context
+def update_app(
+    ctx: click.Context,
+    name: str,
+    visible: bool | None,
+    enabled: bool | None,
+) -> None:
+    """Update app settings."""
+    kwargs: dict[str, Any] = {}
+    if visible is not None:
+        kwargs["visible"] = visible
+    if enabled is not None:
+        kwargs["disabled"] = not enabled
+    if not kwargs:
+        msg = "No settings specified. Use --visible/--hidden or --enabled/--disabled."
+        output.error(msg)
+        ctx.exit(1)
+        return
+
+    parts: list[str] = []
+    if visible is not None:
+        parts.append(f"visible={'true' if visible else 'false'}")
+    if enabled is not None:
+        parts.append(f"disabled={'false' if enabled else 'true'}")
+    details = f"Update app '{name}': {', '.join(parts)}"
+    if not guard.check(ctx, details):
+        return
+
+    client = get_client(ctx)
+    svc = client.service
+    try:
+        app = svc.apps[name]
+        app.update(**kwargs)
+    except KeyError:
+        output.error(f"App '{name}' not found.")
+        ctx.exit(1)
+        return
+    except Exception as exc:
+        output.error(f"Update failed: {exc}")
+        ctx.exit(1)
+        return
+    output.info(f"Updated app '{name}'.")
+
+
+@apps_group.command("reload")
+@click.pass_context
+def reload_apps(ctx: click.Context) -> None:
+    """Reload all apps."""
+    if not guard.check(ctx, "Reload all apps"):
+        return
+
+    client = get_client(ctx)
+    svc = client.service
+    try:
+        svc.get("/services/apps/local/_reload")
+    except Exception as exc:
+        output.error(f"Reload failed: {exc}")
+        ctx.exit(1)
+        return
+    output.info("Apps reloaded.")

splunkctl/commands/commands_meta.py

@@ -0,0 +1,72 @@
+"""Self-discovery — machine-readable command tree for agents."""
+
+import json
+from typing import Any
+
+import click
+
+from splunkctl import __version__, output
+
+
+def _param_entry(p: click.Parameter) -> dict[str, Any]:
+    """Build a single parameter descriptor."""
+    entry: dict[str, Any] = {
+        "name": p.name or "",
+        "type": p.type.name if hasattr(p.type, "name") else str(p.type),
+    }
+    if isinstance(p, click.Argument):
+        entry["kind"] = "argument"
+    elif isinstance(p, click.Option):
+        entry["kind"] = "option"
+        if p.opts:
+            entry["flags"] = p.opts
+        if p.is_flag:
+            entry["type"] = "flag"
+        if p.required:
+            entry["required"] = True
+        if p.help:
+            entry["help"] = p.help
+    if isinstance(p.type, click.Choice):
+        entry["choices"] = list(p.type.choices)
+    if not (isinstance(p, click.Option) and p.is_flag):
+        if isinstance(p.default, (str, int, float)) and p.default is not None:
+            entry["default"] = p.default
+    return entry
+
+
+def _walk(group: click.Group) -> list[dict[str, Any]]:
+    """Recursively build the command tree."""
+    nodes: list[dict[str, Any]] = []
+    for name, cmd in sorted(group.commands.items()):
+        node: dict[str, Any] = {
+            "name": name,
+            "help": (cmd.help or "").split("\n")[0],
+        }
+        if isinstance(cmd, click.Group):
+            node["subcommands"] = _walk(cmd)
+        else:
+            params: list[dict[str, Any]] = []
+            for p in cmd.params:
+                if p.name in ("help",):
+                    continue
+                params.append(_param_entry(p))
+            if params:
+                node["params"] = params
+        nodes.append(node)
+    return nodes
+
+
+@click.command("commands")
+@click.pass_context
+def commands_meta(ctx: click.Context) -> None:
+    """Print the command tree as JSON (for agent discovery)."""
+    root = ctx.parent
+    if root is None or not isinstance(root.command, click.Group):
+        output.error("Cannot resolve CLI root.")
+        ctx.exit(1)
+        return
+    result: dict[str, Any] = {
+        "version": __version__,
+        "commands": _walk(root.command),
+    }
+    click.echo(json.dumps(result, indent=2))

splunkctl/commands/config_cmd.py

@@ -0,0 +1,87 @@
+"""Config commands — init, show, test."""
+
+from pathlib import Path
+from typing import Any
+
+import click
+
+from splunkctl import config as cfg_mod
+from splunkctl import output
+from splunkctl.client import SplunkClient
+
+
+@click.group("config")
+def config_group() -> None:
+    """Manage splunkctl configuration."""
+
+
+@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(
+    "--scheme",
+    type=click.Choice(["https", "http"]),
+    default="https",
+    help="Connection scheme.",
+)
+@click.option("--verify/--no-verify", default=False, help="Verify SSL certificate.")
+@click.option(
+    "--path",
+    type=click.Path(),
+    default=None,
+    help="Config file path (default: ~/.splunkctl/config.yaml).",
+)
+def init(
+    host: str,
+    port: int,
+    username: str,
+    password: str,
+    scheme: str,
+    verify: bool,
+    path: str | None,
+) -> None:
+    """Interactive setup — create or overwrite config."""
+    cfg: dict[str, Any] = {
+        "host": host,
+        "port": port,
+        "username": username,
+        "password": password,
+        "scheme": scheme,
+        "verify": verify,
+    }
+    dest = Path(path) if path else None
+    saved = cfg_mod.save(cfg, dest)
+    output.info(f"Config saved to {saved}")
+
+
+@config_group.command()
+@click.pass_context
+def show(ctx: click.Context) -> None:
+    """Display current config (secrets redacted)."""
+    cfg_path = ctx.obj.get("config")
+    cfg = cfg_mod.load(Path(cfg_path) if cfg_path else None)
+    output.render(ctx, cfg_mod.redact(cfg))
+
+
+@config_group.command()
+@click.pass_context
+def test(ctx: click.Context) -> None:
+    """Verify connectivity and auth against the Splunk instance."""
+    cfg_path = ctx.obj.get("config")
+    config_path = Path(cfg_path) if cfg_path else None
+    cfg = cfg_mod.load(config_path)
+
+    output.info(
+        f"Connecting to {cfg.get('scheme', 'https')}://"
+        f"{cfg.get('host', 'localhost')}:{cfg.get('port', 8089)} ..."
+    )
+
+    try:
+        client = SplunkClient(config_path=config_path)
+        svc_info = client.service.info
+        output.info(f"OK — {svc_info['serverName']} (Splunk {svc_info['version']})")
+    except Exception as exc:
+        output.error(str(exc))
+        ctx.exit(1)