splunkctl 0.3.0__tar.gz → 0.4.0__tar.gz

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

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

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

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

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

@@ -6,6 +6,7 @@ handle remotely (e.g. lookup file upload requires server-side staging).
 
 from __future__ import annotations
 
+import json
 import re
 import urllib.parse
 from pathlib import Path
@@ -29,6 +30,7 @@ class SplunkClient:
         self,
         *,
         config_path: Path | None = None,
+        profile: str | None = None,
         host: str | None = None,
         port: int | None = None,
         username: str | None = None,
@@ -42,6 +44,7 @@ class SplunkClient:
         debug: bool = False,
     ) -> None:
         self._config_path = config_path
+        self._profile = profile
         self._overrides: dict[str, Any] = {
             k: v
             for k, v in {
@@ -72,7 +75,7 @@ class SplunkClient:
                 logging.basicConfig(level=logging.DEBUG)
                 logging.getLogger("splunklib").setLevel(logging.DEBUG)
 
-            cfg = cfg_mod.load(self._config_path)
+            cfg = cfg_mod.load(self._config_path, profile=self._profile)
             cfg.update(self._overrides)
 
             connect_args: dict[str, Any] = {
@@ -104,7 +107,7 @@ class SplunkClient:
 
     def _ensure_web_session(self) -> _WebSession:
         if self._web_session is None:
-            cfg = cfg_mod.load(self._config_path)
+            cfg = cfg_mod.load(self._config_path, profile=self._profile)
             cfg.update(self._overrides)
             self._web_session = _WebSession(
                 self.service,
@@ -323,11 +326,60 @@ def _expect_ok(resp: requests.Response, what: str) -> None:
         raise RuntimeError(f"{what} failed: {result.get('msg', 'unknown error')}")
 
 
+def rest_get_json(
+    svc: Any,
+    path: str,
+    *,
+    owner: str | None = None,
+    app: str | None = None,
+    **query: Any,
+) -> Any:
+    """GET a REST path via the SDK's authenticated session and parse JSON.
+
+    Always passes ``output_mode=json`` so endpoints that default to Atom
+    XML (e.g. ``storage/collections/config``) come back as JSON just like
+    the KV store data endpoints already do. Any raised ``HTTPError`` (or
+    connection failure) is left to propagate — callers rely on
+    ``splunkctl.errors.classify`` at the top level to turn it into a
+    clean error envelope.
+    """
+    resp = svc.get(path, owner=owner, app=app, output_mode="json", **query)
+    return json.loads(resp.body.read())
+
+
+def rest_post_json(
+    svc: Any,
+    path: str,
+    body: Any,
+    *,
+    owner: str | None = None,
+    app: str | None = None,
+) -> Any:
+    """POST a JSON-encoded body to a REST path and parse the JSON response.
+
+    The KV store data API (``storage/collections/data/...``) requires
+    ``Content-Type: application/json`` on the request body and always
+    responds with JSON — unlike most Splunk config endpoints, which use
+    ``x-www-form-urlencoded`` params via plain keyword arguments. Returns
+    ``None`` for an empty response body (e.g. some KV store writes).
+    """
+    resp = svc.post(
+        path,
+        owner=owner,
+        app=app,
+        headers=[("Content-Type", "application/json")],
+        body=json.dumps(body),
+    )
+    raw = resp.body.read()
+    return json.loads(raw) if raw else None
+
+
 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,
+        profile=obj.get("profile"),
         timeout=obj.get("timeout", 30),
         debug=obj.get("debug", False),
     )

{splunkctl-0.3.0 → splunkctl-0.4.0}/splunkctl/commands/alerts.py

@@ -6,6 +6,7 @@ import click
 
 from splunkctl import guard, output
 from splunkctl.client import get_client
+from splunkctl.commands.common import filter_by_name, list_options, page_slice
 
 
 def _firing_rows(group: Any) -> list[dict[str, Any]]:
@@ -31,15 +32,28 @@ def alerts_group() -> None:
 
 
 @alerts_group.command("list")
+@list_options
 @click.pass_context
-def list_alerts(ctx: click.Context) -> None:
-    """List fired alerts (one row per firing, with sid for drill-down)."""
+def list_alerts(
+    ctx: click.Context,
+    *,
+    limit: int | None,
+    offset: int,
+    name_filter: str | None,
+) -> None:
+    """List fired alerts (one row per firing, with sid for drill-down).
+
+    --filter matches the rule name; --limit/--offset page the firing rows
+    client-side (a row is one firing, not one rule).
+    """
     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))
+    rows = filter_by_name(rows, name_filter, name_of=lambda r: str(r["rule"]))
+    rows = page_slice(rows, limit=limit, offset=offset)
     output.render(ctx, rows, empty="No fired alerts.")
 
 
@@ -55,7 +69,7 @@ def get_alert(ctx: click.Context, name: str) -> None:
             output.info(f"{name}: {len(rows)} firing(s)")
             output.render(ctx, rows)
             return
-    output.error(f"Fired alert not found: {name}")
+    output.error(f"Fired alert not found: {name}", kind="not_found")
     ctx.exit(1)
 
 
@@ -103,7 +117,7 @@ def suppress_alert(ctx: click.Context, name: str, duration: int) -> None:
     try:
         ss = client.service.saved_searches[name]
     except KeyError:
-        output.error(f"Saved search not found: {name}")
+        output.error(f"Saved search not found: {name}", kind="not_found")
         ctx.exit(1)
         return
     ss.update(
@@ -124,7 +138,7 @@ def unsuppress_alert(ctx: click.Context, name: str) -> None:
     try:
         ss = client.service.saved_searches[name]
     except KeyError:
-        output.error(f"Saved search not found: {name}")
+        output.error(f"Saved search not found: {name}", kind="not_found")
         ctx.exit(1)
         return
     ss.update(**{"alert.suppress": "0"}).refresh()

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

@@ -7,6 +7,7 @@ import click
 
 from splunkctl import guard, output
 from splunkctl.client import get_client
+from splunkctl.commands.common import fetch_page, list_options
 
 _APP_FIELDS = ("label", "version", "visible", "disabled", "author", "description")
 
@@ -37,12 +38,21 @@ def apps_group() -> None:
 
 
 @apps_group.command("list")
+@list_options
 @click.pass_context
-def list_apps(ctx: click.Context) -> None:
+def list_apps(
+    ctx: click.Context,
+    *,
+    limit: int | None,
+    offset: int,
+    name_filter: str | None,
+) -> None:
     """List installed apps."""
     client = get_client(ctx)
     svc = client.service
-    apps = svc.apps.list()
+    apps = fetch_page(
+        svc.apps.list, limit=limit, offset=offset, name_filter=name_filter
+    )
     if not apps:
         output.info("No apps found.")
         return
@@ -60,7 +70,7 @@ def get_app(ctx: click.Context, name: str) -> None:
     try:
         app = svc.apps[name]
     except KeyError:
-        output.error(f"App '{name}' not found.")
+        output.error(f"App '{name}' not found.", kind="not_found")
         ctx.exit(1)
         return
     output.render(ctx, _app_row(app))
@@ -116,7 +126,7 @@ def uninstall_app(ctx: click.Context, name: str) -> None:
         app = svc.apps[name]
         app.delete()
     except KeyError:
-        output.error(f"App '{name}' not found.")
+        output.error(f"App '{name}' not found.", kind="not_found")
         ctx.exit(1)
         return
     except Exception as exc:
@@ -165,7 +175,7 @@ def update_app(
         app = svc.apps[name]
         app.update(**kwargs)
     except KeyError:
-        output.error(f"App '{name}' not found.")
+        output.error(f"App '{name}' not found.", kind="not_found")
         ctx.exit(1)
         return
     except Exception as exc:

splunkctl-0.4.0/splunkctl/commands/audit.py

@@ -0,0 +1,196 @@
+"""``audit`` group — change audit and RBAC attestation, for regulator evidence.
+
+Both subcommands are read-only (no ``guard``).
+
+``changes`` wraps ``index=_audit`` without ever composing user input into
+SPL: the dispatched search is always the constant ``search index=_audit``.
+Time bounds go through the oneshot job's ``earliest_time``/``latest_time``
+kwargs, and ``--user``/``--action``/``--object-type`` filter the
+already-normalized rows client-side, after the fetch.
+
+``rbac`` joins users/roles/capabilities/index-restrictions via SDK reads
+only, for periodic access recertification evidence.
+"""
+
+from typing import Any
+
+import click
+
+from splunkctl import output
+from splunkctl.client import get_client
+from splunkctl.commands.audit_parse import parse_event
+from splunkctl.commands.common import read_results
+
+_AUDIT_SPL = "search index=_audit"
+
+
+def _as_list(value: Any) -> list[str]:
+    """Normalize a Splunk multi-value field that may come back as a bare string.
+
+    The REST API returns a plain string instead of a one-item list when a
+    multi-value field has exactly one value.
+    """
+    if isinstance(value, list):
+        return [str(v) for v in value]
+    if isinstance(value, str) and value:
+        return [value]
+    return []
+
+
+def _transitive_roles(
+    direct: list[str], role_map: dict[str, dict[str, Any]]
+) -> list[str]:
+    """Full ``imported_roles`` closure of ``direct`` (self included, cycle-safe)."""
+    seen: set[str] = set()
+    stack = list(direct)
+    while stack:
+        name = stack.pop()
+        if name in seen or name not in role_map:
+            continue
+        seen.add(name)
+        stack.extend(_as_list(role_map[name].get("imported_roles", [])))
+    return sorted(seen)
+
+
+def _aggregate(
+    names: list[str], role_map: dict[str, dict[str, Any]], field: str
+) -> str:
+    r"""Union ``field`` across ``names``, deduplicated, sorted, semicolon-joined.
+
+    ``;`` (never ``\n``) so aggregated multi-value cells stay one CSV field.
+    """
+    values: set[str] = set()
+    for name in names:
+        content = role_map.get(name)
+        if content is not None:
+            values.update(_as_list(content.get(field, [])))
+    return ";".join(sorted(values))
+
+
+def _user_row(user: Any, role_map: dict[str, dict[str, Any]]) -> dict[str, Any]:
+    content: dict[str, Any] = user.content
+    direct = _as_list(content.get("roles", []))
+    effective = _transitive_roles(direct, role_map)
+    return {
+        "user": user.name,
+        "email": str(content.get("email") or ""),
+        "roles": ";".join(sorted(direct)),
+        "capabilities": _aggregate(effective, role_map, "capabilities"),
+        "srch_indexes_allowed": _aggregate(effective, role_map, "srchIndexesAllowed"),
+    }
+
+
+def _role_row(name: str, role_map: dict[str, dict[str, Any]]) -> dict[str, Any]:
+    imported = _as_list(role_map[name].get("imported_roles", []))
+    effective = _transitive_roles([name], role_map)
+    return {
+        "role": name,
+        "imported_roles": ";".join(sorted(imported)),
+        "capabilities": _aggregate(effective, role_map, "capabilities"),
+        "srch_indexes_allowed": _aggregate(effective, role_map, "srchIndexesAllowed"),
+    }
+
+
+@click.group("audit")
+def audit_group() -> None:
+    """Change audit and RBAC attestation — regulator evidence, read-only."""
+
+
+@audit_group.command("changes")
+@click.option("--since", default="-24h", help="Earliest time (default -24h).")
+@click.option("--until", default="now", help="Latest time (default now).")
+@click.option(
+    "--user",
+    "user_filter",
+    default=None,
+    help="Filter by user (case-insensitive).",
+)
+@click.option(
+    "--action",
+    "action_filter",
+    default=None,
+    help="Filter by action, substring (case-insensitive).",
+)
+@click.option(
+    "--object-type",
+    "object_type_filter",
+    default=None,
+    help="Filter by object type (case-insensitive).",
+)
+@click.option(
+    "--limit",
+    type=click.IntRange(min=1),
+    default=500,
+    help="Max results after client-side filtering (default 500).",
+)
+@click.pass_context
+def changes(
+    ctx: click.Context,
+    since: str,
+    until: str,
+    user_filter: str | None,
+    action_filter: str | None,
+    object_type_filter: str | None,
+    limit: int,
+) -> None:
+    """Normalized index=_audit change events (both legacy and JSON shapes).
+
+    SECURITY: the dispatched SPL is always the constant
+    ``search index=_audit``. --since/--until go through the search job's
+    time-range kwargs; --user/--action/--object-type filter the
+    normalized rows client-side. No flag value is ever composed into the
+    SPL string.
+    """
+    client = get_client(ctx)
+    svc = client.service
+
+    output.info(f"Searching: {_AUDIT_SPL}")
+    stream: Any = svc.jobs.oneshot(
+        _AUDIT_SPL,
+        output_mode="json",
+        count=0,
+        earliest_time=since,
+        latest_time=until,
+    )
+    rows = [parse_event(r) for r in read_results(stream)]
+
+    if user_filter is not None:
+        rows = [r for r in rows if r["user"].lower() == user_filter.lower()]
+    if action_filter is not None:
+        needle = action_filter.lower()
+        rows = [r for r in rows if needle in r["action"].lower()]
+    if object_type_filter is not None:
+        obj_type_lower = object_type_filter.lower()
+        rows = [r for r in rows if r["object_type"].lower() == obj_type_lower]
+
+    rows.sort(key=lambda r: r["time"], reverse=True)
+    output.render(ctx, rows[:limit], empty="No audit events found.")
+
+
+@audit_group.command("rbac")
+@click.option(
+    "--roles-only",
+    is_flag=True,
+    help="One row per role instead of per user (role-centric attestation view).",
+)
+@click.pass_context
+def rbac(ctx: click.Context, *, roles_only: bool) -> None:
+    """Users x roles x capabilities x index-restrictions — recertification evidence.
+
+    Capabilities and srch_indexes_allowed are aggregated across each
+    principal's direct roles AND the full transitive closure of their
+    imported roles, deduplicated and sorted.
+    """
+    client = get_client(ctx)
+    svc = client.service
+
+    role_map: dict[str, dict[str, Any]] = {r.name: dict(r.content) for r in svc.roles}
+
+    if roles_only:
+        rows = [_role_row(name, role_map) for name in sorted(role_map)]
+        output.render(ctx, rows, empty="No roles found.")
+        return
+
+    users = sorted(svc.users, key=lambda u: str(u.name))
+    user_rows = [_user_row(u, role_map) for u in users]
+    output.render(ctx, user_rows, empty="No users found.")

splunkctl-0.4.0/splunkctl/commands/audit_parse.py

@@ -0,0 +1,151 @@
+"""Normalize both index=_audit event shapes into one six-key schema.
+
+Splunk ships two incompatible shapes in the same ``_audit`` index, mixed
+in one stream:
+
+- ``audittrail`` (legacy): a plain-text line,
+  ``Audit:[timestamp=..., user=..., action=..., <tail>]`` where
+  ``<tail>`` is an action-specific, comma-separated list of extra fields
+  (e.g. ``info=granted, cap=1`` for capability checks,
+  ``modified_settings=[...]`` for ``edit_index``, or no ``info=`` at all
+  for some system actions like ``artifact_deleted``/file-integrity
+  ``update`` — confirmed live). Only ``timestamp``/``user``/``action``
+  are structurally guaranteed; there is no field that consistently
+  identifies "the object" across every action. Many admin-capability
+  checks (``edit_user``, ``edit_roles``, ...) do carry a literal
+  ``object="..."`` marker, so that's used when present.
+- ``audittrailv2`` (structured): one JSON object per line, with
+  ``actor.name``, a top-level ``action``, and a ``data`` object shaped
+  ``{name, type, ownership: {app, owner}, attributes}`` for
+  object/system-category events (config changes), or just
+  ``{type, attributes}`` / ``{attributes}`` for action/authn/check
+  events (searches, logins, capability checks). There is no literal
+  ``data.object``/``data.object_type`` key on real events — ``data.name``
+  and ``data.type`` are the nearest equivalents and are used here.
+
+Both are normalized into the same six-key schema so callers never
+hand-write shape-specific parsing. An event matching neither shape is
+never dropped — it comes back with ``action: "unparsed"`` and the raw
+line preserved in ``object``, so audit evidence stays complete.
+"""
+
+import json
+import re
+from typing import Any
+
+SCHEMA_KEYS: tuple[str, ...] = (
+    "time",
+    "user",
+    "action",
+    "object",
+    "object_type",
+    "app",
+)
+
+_LEGACY_RE = re.compile(
+    r"^Audit:\[timestamp=(?P<timestamp>[^,]*),\s*"
+    r"user=(?P<user>[^,]*),\s*"
+    r"action=(?P<action>[^,\]]*)"
+)
+_OBJECT_RE = re.compile(r'object="(?P<value>[^"]*)"')
+_APP_RE = re.compile(r'app=(?:"(?P<quoted>[^"]*)"|(?P<bare>[^,\]]+))')
+
+
+def _as_str(value: Any) -> str:
+    """Coerce a JSON scalar (or ``None``) to ``str`` for the output schema."""
+    return "" if value is None else str(value)
+
+
+def _event_time(row: dict[str, Any]) -> str:
+    """Splunk's own indexed ``_time`` — present on every event regardless of shape.
+
+    Used instead of re-parsing the two different embedded timestamp
+    formats: it's always populated (Splunk's own ``TIME_FORMAT``
+    extraction already did that work at index time) and gives one
+    consistent, sortable representation across both shapes.
+    """
+    return _as_str(row.get("_time"))
+
+
+def _parse_json_shape(raw: str) -> dict[str, str] | None:
+    """Parse the structured JSON shape (sourcetype ``audittrailv2``).
+
+    Returns ``None`` when ``raw`` isn't valid JSON or doesn't look like an
+    audittrailv2 event (missing ``actor``/``action``), so the caller can
+    fall back to the legacy parser.
+    """
+    try:
+        obj: Any = json.loads(raw)
+    except (json.JSONDecodeError, TypeError, ValueError):
+        return None
+    if not isinstance(obj, dict) or "action" not in obj or "actor" not in obj:
+        return None
+
+    actor = obj.get("actor")
+    user = actor.get("name") if isinstance(actor, dict) else None
+
+    data = obj.get("data")
+    data = data if isinstance(data, dict) else {}
+    ownership = data.get("ownership")
+    ownership = ownership if isinstance(ownership, dict) else {}
+    attributes = data.get("attributes")
+    attributes = attributes if isinstance(attributes, dict) else {}
+    app = ownership.get("app") or attributes.get("app")
+
+    return {
+        "user": _as_str(user),
+        "action": _as_str(obj.get("action")),
+        "object": _as_str(data.get("name")),
+        "object_type": _as_str(data.get("type")),
+        "app": _as_str(app),
+    }
+
+
+def _parse_legacy_shape(raw: str) -> dict[str, str] | None:
+    """Parse the legacy plain-text shape (sourcetype ``audittrail``).
+
+    Returns ``None`` when ``raw`` doesn't match the
+    ``Audit:[timestamp=..., user=..., action=...`` prefix, so the caller
+    can fall back to the unparsed case.
+    """
+    m = _LEGACY_RE.match(raw)
+    if m is None:
+        return None
+
+    obj_m = _OBJECT_RE.search(raw)
+    app_m = _APP_RE.search(raw)
+    app = ""
+    if app_m is not None:
+        app = (
+            app_m.group("quoted")
+            if app_m.group("quoted") is not None
+            else app_m.group("bare")
+        )
+
+    return {
+        "user": m.group("user").strip(),
+        "action": m.group("action").strip(),
+        "object": obj_m.group("value") if obj_m is not None else "",
+        "object_type": "",
+        "app": app.strip(),
+    }
+
+
+def parse_event(row: dict[str, Any]) -> dict[str, str]:
+    """Normalize one raw ``_audit`` result row into the six-key schema.
+
+    Tries the JSON shape, then the legacy text shape; anything matching
+    neither becomes an ``action: "unparsed"`` row with the full raw line
+    in ``object`` — never silently dropped.
+    """
+    raw = _as_str(row.get("_raw"))
+    parsed = _parse_json_shape(raw) or _parse_legacy_shape(raw)
+    if parsed is None:
+        parsed = {
+            "user": "",
+            "action": "unparsed",
+            "object": raw,
+            "object_type": "",
+            "app": "",
+        }
+    return {"time": _event_time(row), **parsed}