splunkctl 0.1.0__py3-none-any.whl

splunkctl/commands/search.py

@@ -0,0 +1,270 @@
+"""Search commands — run, export, oneshot, jobs, job, cancel."""
+
+import time
+from typing import Any
+
+import click
+from splunklib.results import JSONResultsReader
+
+from splunkctl import guard, output
+from splunkctl.client import get_client
+
+_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 _time_kwargs(
+    earliest: str | None,
+    latest: str | None,
+) -> dict[str, str]:
+    """Build SDK time-range kwargs."""
+    kw: dict[str, str] = {}
+    if earliest:
+        kw["earliest_time"] = earliest
+    if latest:
+        kw["latest_time"] = latest
+    return kw
+
+
+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
+
+
+@click.group("search")
+def search_group() -> None:
+    """Search and job management."""
+
+
+@search_group.command("run")
+@click.argument("spl")
+@click.option("--earliest", default=None, help="Earliest time (e.g. -24h, -7d).")
+@click.option("--latest", default=None, help="Latest time (e.g. now).")
+@click.option("--limit", default=100, type=int, help="Max results (default 100).")
+@click.option("--app", default=None, help="Splunk app context.")
+@click.pass_context
+def run_search(
+    ctx: click.Context,
+    spl: str,
+    earliest: str | None,
+    latest: str | None,
+    limit: int,
+    app: str | None,
+) -> None:
+    """Run a search synchronously and print results."""
+    client = get_client(ctx)
+    svc = client.service
+    if app:
+        svc.namespace["app"] = app
+    query = _normalize_spl(spl)
+
+    timeout: int = ctx.obj.get("timeout", 30)
+    kwargs: dict[str, Any] = {
+        "exec_mode": "normal",
+        **_time_kwargs(earliest, latest),
+    }
+
+    output.info(f"Running: {query}")
+    job: Any = svc.jobs.create(query, **kwargs)
+
+    deadline = time.monotonic() + timeout
+    while not job.is_done():
+        if time.monotonic() > deadline:
+            job.cancel()
+            output.error(f"Search timed out after {timeout}s.")
+            ctx.exit(1)
+            return
+        time.sleep(0.5)
+        job.refresh()
+
+    rows = _read_results(job.results(output_mode="json", count=limit))
+    output.render(ctx, rows)
+
+
+@search_group.command("export")
+@click.argument("spl")
+@click.option("--earliest", default=None, help="Earliest time.")
+@click.option("--latest", default=None, help="Latest time.")
+@click.option("--app", default=None, help="Splunk app context.")
+@click.pass_context
+def export_search(
+    ctx: click.Context,
+    spl: str,
+    earliest: str | None,
+    latest: str | None,
+    app: str | None,
+) -> None:
+    """Streaming export for large result sets."""
+    client = get_client(ctx)
+    svc = client.service
+    if app:
+        svc.namespace["app"] = app
+    query = _normalize_spl(spl)
+
+    kwargs: dict[str, Any] = {
+        "output_mode": "json",
+        **_time_kwargs(earliest, latest),
+    }
+
+    output.info(f"Exporting: {query}")
+    stream: Any = svc.jobs.export(query, **kwargs)
+    rows = _read_results(stream)
+    output.render(ctx, rows)
+
+
+@search_group.command("oneshot")
+@click.argument("spl")
+@click.option("--earliest", default=None, help="Earliest time.")
+@click.option("--latest", default=None, help="Latest time.")
+@click.option("--limit", default=100, type=int, help="Max results (default 100).")
+@click.option("--app", default=None, help="Splunk app context.")
+@click.pass_context
+def oneshot_search(
+    ctx: click.Context,
+    spl: str,
+    earliest: str | None,
+    latest: str | None,
+    limit: int,
+    app: str | None,
+) -> None:
+    """Quick one-off search."""
+    client = get_client(ctx)
+    svc = client.service
+    if app:
+        svc.namespace["app"] = app
+    query = _normalize_spl(spl)
+
+    kwargs: dict[str, Any] = {
+        "output_mode": "json",
+        "count": limit,
+        **_time_kwargs(earliest, latest),
+    }
+
+    output.info(f"Oneshot: {query}")
+    stream: Any = svc.jobs.oneshot(query, **kwargs)
+    rows = _read_results(stream)
+    output.render(ctx, rows)
+
+
+@search_group.command("jobs")
+@click.pass_context
+def list_jobs(ctx: click.Context) -> None:
+    """List running and recent search jobs."""
+    client = get_client(ctx)
+    svc = client.service
+
+    rows: list[dict[str, Any]] = []
+    for job in svc.jobs:
+        content: dict[str, Any] = dict(job.content)
+        dur = content.get("runDuration", "")
+        if isinstance(dur, (float, str)):
+            try:
+                dur = f"{float(dur):.3f}"
+            except (ValueError, TypeError):
+                pass
+        rows.append(
+            {
+                "sid": job.sid,
+                "status": content.get("dispatchState", ""),
+                "earliest": content.get("earliestTime", ""),
+                "latest": content.get("latestTime", ""),
+                "event_count": content.get("eventCount", 0),
+                "run_duration": dur,
+            }
+        )
+    output.render(ctx, rows)
+
+
+@search_group.command("job")
+@click.argument("sid")
+@click.pass_context
+def get_job(ctx: click.Context, sid: str) -> None:
+    """Get status and results for a specific job."""
+    client = get_client(ctx)
+    svc = client.service
+
+    try:
+        job: Any = svc.jobs[sid]
+    except KeyError:
+        output.error(f"Job '{sid}' not found.")
+        ctx.exit(1)
+        return
+
+    job.refresh()
+    content: dict[str, Any] = dict(job.content)
+    done: bool = job.is_done()
+
+    status: dict[str, Any] = {
+        "sid": job.sid,
+        "status": content.get("dispatchState", ""),
+        "earliest": content.get("earliestTime", ""),
+        "latest": content.get("latestTime", ""),
+        "event_count": content.get("eventCount", 0),
+        "result_count": content.get("resultCount", 0),
+        "run_duration": content.get("runDuration", ""),
+        "is_done": done,
+    }
+
+    if done:
+        rows = _read_results(job.results(output_mode="json"))
+        if rows:
+            output.info(f"Job {sid}: DONE - {len(rows)} result(s)")
+            output.render(ctx, rows)
+            return
+    output.render(ctx, status)
+
+
+@search_group.command("cancel")
+@click.argument("sid")
+@click.pass_context
+def cancel_job(ctx: click.Context, sid: str) -> None:
+    """Cancel a running search job."""
+    if not guard.check(ctx, f"Cancel job '{sid}'"):
+        return
+
+    client = get_client(ctx)
+    svc = client.service
+
+    try:
+        job: Any = svc.jobs[sid]
+    except KeyError:
+        output.error(f"Job '{sid}' not found.")
+        ctx.exit(1)
+        return
+
+    job.cancel()
+    output.info(f"Job '{sid}' cancelled.")

splunkctl/commands/skill_cmd.py

@@ -0,0 +1,43 @@
+"""Skill commands — print or install the embedded SKILL.md."""
+
+import importlib.resources
+from pathlib import Path
+
+import click
+
+from splunkctl import output
+
+_INSTALL_DIR = Path.home() / ".claude" / "skills" / "splunkctl"
+
+
+def _load_skill() -> str:
+    """Read SKILL.md from the installed package."""
+    try:
+        ref = importlib.resources.files("splunkctl.skill").joinpath("SKILL.md")
+        return ref.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        output.error("SKILL.md not found in package. Reinstall splunkctl.")
+        raise SystemExit(1) from None
+
+
+@click.group("skill", invoke_without_command=True)
+@click.pass_context
+def skill_group(ctx: click.Context) -> None:
+    """Print or install the embedded agent skill guide."""
+    if ctx.invoked_subcommand is None:
+        click.echo(_load_skill(), nl=False)
+
+
+@skill_group.command("print")
+def skill_print() -> None:
+    """Print SKILL.md to stdout."""
+    click.echo(_load_skill(), nl=False)
+
+
+@skill_group.command("install")
+def skill_install() -> None:
+    """Install SKILL.md to ~/.claude/skills/splunkctl/."""
+    _INSTALL_DIR.mkdir(parents=True, exist_ok=True)
+    dest = _INSTALL_DIR / "SKILL.md"
+    dest.write_text(_load_skill(), encoding="utf-8")
+    output.info(f"Installed to {dest}")

splunkctl/commands/users.py

@@ -0,0 +1,211 @@
+"""User and role management commands."""
+
+from typing import Any
+
+import click
+
+from splunkctl import guard, output
+from splunkctl.client import get_client
+
+_MAX_CAPS = 5
+
+
+def _user_row(user: Any) -> dict[str, Any]:
+    c: dict[str, Any] = user.content
+    roles = c.get("roles", [])
+    if isinstance(roles, str):
+        roles = [roles]
+    return {
+        "name": user.name,
+        "realname": c.get("realname", ""),
+        "email": c.get("email", ""),
+        "roles": ", ".join(roles),
+        "defaultApp": c.get("defaultApp", ""),
+        "type": c.get("type", ""),
+    }
+
+
+def _role_row(role: Any) -> dict[str, Any]:
+    c: dict[str, Any] = role.content
+    imported = c.get("imported_roles", [])
+    if isinstance(imported, str):
+        imported = [imported]
+    caps = c.get("capabilities", [])
+    if isinstance(caps, str):
+        caps = [caps]
+    truncated = ", ".join(caps[:_MAX_CAPS])
+    if len(caps) > _MAX_CAPS:
+        truncated += f" (+{len(caps) - _MAX_CAPS} more)"
+    return {
+        "name": role.name,
+        "imported_roles": ", ".join(imported),
+        "capabilities": truncated,
+        "defaultApp": c.get("defaultApp", ""),
+    }
+
+
+@click.group("users")
+def users_group() -> None:
+    """Manage users and roles."""
+
+
+@users_group.command("list")
+@click.pass_context
+def list_users(ctx: click.Context) -> None:
+    """List all users."""
+    client = get_client(ctx)
+    users = client.service.users.list()
+    if not users:
+        output.info("No users found.")
+        return
+    rows = [_user_row(u) for u in users]
+    output.render(ctx, rows)
+
+
+@users_group.command("get")
+@click.argument("name")
+@click.pass_context
+def get_user(ctx: click.Context, name: str) -> None:
+    """Get details for a single user."""
+    client = get_client(ctx)
+    try:
+        user = client.service.users[name]
+    except KeyError:
+        output.error(f"User '{name}' not found.")
+        ctx.exit(1)
+        return
+    output.render(ctx, _user_row(user))
+
+
+@users_group.command("roles")
+@click.pass_context
+def list_roles(ctx: click.Context) -> None:
+    """List all roles."""
+    client = get_client(ctx)
+    roles = client.service.roles.list()
+    if not roles:
+        output.info("No roles found.")
+        return
+    rows = [_role_row(r) for r in roles]
+    output.render(ctx, rows)
+
+
+@users_group.command("create")
+@click.option("--name", "username", required=True, help="Username.")
+@click.option("--password", required=True, help="Password.")
+@click.option(
+    "--roles",
+    required=True,
+    help="Comma-separated role names.",
+)
+@click.option("--email", default=None, help="Email address.")
+@click.option("--realname", default=None, help="Display name.")
+@click.pass_context
+def create_user(
+    ctx: click.Context,
+    username: str,
+    password: str,
+    roles: str,
+    *,
+    email: str | None,
+    realname: str | None,
+) -> None:
+    """Create a new user."""
+    roles_list = [r.strip() for r in roles.split(",")]
+    details = f"Create user '{username}' with roles: {', '.join(roles_list)}"
+    if not guard.check(ctx, details):
+        return
+
+    client = get_client(ctx)
+    kwargs: dict[str, Any] = {"password": password, "roles": roles_list}
+    if email:
+        kwargs["email"] = email
+    if realname:
+        kwargs["realname"] = realname
+
+    try:
+        client.service.users.create(username, **kwargs)
+    except Exception as exc:
+        output.error(f"Create failed: {exc}")
+        ctx.exit(1)
+        return
+    output.info(f"Created user '{username}'.")
+
+
+@users_group.command("update")
+@click.argument("name")
+@click.option("--roles", default=None, help="Comma-separated role names.")
+@click.option("--email", default=None, help="Email address.")
+@click.option("--realname", default=None, help="Display name.")
+@click.option("--default-app", default=None, help="Default app.")
+@click.pass_context
+def update_user(
+    ctx: click.Context,
+    name: str,
+    *,
+    roles: str | None,
+    email: str | None,
+    realname: str | None,
+    default_app: str | None,
+) -> None:
+    """Update an existing user."""
+    kwargs: dict[str, Any] = {}
+    if roles is not None:
+        kwargs["roles"] = [r.strip() for r in roles.split(",")]
+    if email is not None:
+        kwargs["email"] = email
+    if realname is not None:
+        kwargs["realname"] = realname
+    if default_app is not None:
+        kwargs["defaultApp"] = default_app
+
+    if not kwargs:
+        output.error("No update fields specified.")
+        ctx.exit(1)
+        return
+
+    changes = ", ".join(f"{k}={v}" for k, v in kwargs.items())
+    if not guard.check(ctx, f"Update user '{name}'", details=changes):
+        return
+
+    client = get_client(ctx)
+    try:
+        user = client.service.users[name]
+    except KeyError:
+        output.error(f"User '{name}' not found.")
+        ctx.exit(1)
+        return
+
+    try:
+        user.update(**kwargs)
+        user.refresh()
+    except Exception as exc:
+        output.error(f"Update failed: {exc}")
+        ctx.exit(1)
+        return
+    output.info(f"Updated user '{name}'.")
+
+
+@users_group.command("delete")
+@click.argument("name")
+@click.pass_context
+def delete_user(ctx: click.Context, name: str) -> None:
+    """Delete a user."""
+    if not guard.check(ctx, f"Delete user '{name}'"):
+        return
+
+    client = get_client(ctx)
+    try:
+        user = client.service.users[name]
+    except KeyError:
+        output.error(f"User '{name}' not found.")
+        ctx.exit(1)
+        return
+
+    try:
+        user.delete()
+    except Exception as exc:
+        output.error(f"Delete failed: {exc}")
+        ctx.exit(1)
+        return
+    output.info(f"Deleted user '{name}'.")

splunkctl/config.py

@@ -0,0 +1,82 @@
+"""Config file management — load, save, redact."""
+
+import os
+import stat
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+DEFAULT_DIR: Path = Path.home() / ".splunkctl"
+DEFAULT_PATH: Path = DEFAULT_DIR / "config.yaml"
+
+_SECRETS: frozenset[str] = frozenset({"password", "token", "secret"})
+
+_ENV_MAP: dict[str, str] = {
+    "SPLUNK_HOST": "host",
+    "SPLUNK_PORT": "port",
+    "SPLUNK_USER": "username",
+    "SPLUNK_PASS": "password",
+    "SPLUNK_SCHEME": "scheme",
+    "SPLUNK_TOKEN": "token",
+    "SPLUNK_APP": "app",
+    "SPLUNK_OWNER": "owner",
+    "SPLUNK_VERIFY": "verify",
+}
+
+
+def defaults() -> dict[str, Any]:
+    """Return default configuration values."""
+    return {
+        "host": "localhost",
+        "port": 8089,
+        "username": "admin",
+        "password": "",
+        "scheme": "https",
+        "verify": False,
+    }
+
+
+def load(path: Path | None = None) -> dict[str, Any]:
+    """Load config with resolution: defaults -> file -> env vars."""
+    cfg = defaults()
+    config_path = path or DEFAULT_PATH
+
+    if config_path.exists():
+        with open(config_path) as f:
+            file_cfg = yaml.safe_load(f)
+        if isinstance(file_cfg, dict):
+            cfg.update(file_cfg)
+
+    for env_key, cfg_key in _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
+
+    return cfg
+
+
+def save(cfg: dict[str, Any], path: Path | None = None) -> Path:
+    """Save config to YAML with 0600 permissions."""
+    config_path = path or DEFAULT_PATH
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+
+    with open(config_path, "w") as f:
+        yaml.dump(dict(cfg), f, default_flow_style=False, sort_keys=False)
+
+    config_path.chmod(stat.S_IRUSR | stat.S_IWUSR)
+    return config_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()}

splunkctl/guard.py

@@ -0,0 +1,22 @@
+"""Mutation guard — dry-run preview, --yes to apply."""
+
+from typing import Any
+
+import click
+
+
+def check(ctx: click.Context, action: str, *, details: str = "") -> bool:
+    """Return True if the mutation should proceed.
+
+    Dry-run (default) prints a preview to stderr and returns False.
+    Pass ``--yes`` to apply.
+    """
+    obj: dict[str, Any] = ctx.obj or {}
+    if not obj.get("dry_run", True):
+        return True
+
+    click.echo(f"[DRY RUN] {action}", err=True)
+    if details:
+        click.echo(details, err=True)
+    click.echo("Pass --yes to apply.", err=True)
+    return False