splunkctl 0.3.0__tar.gz → 0.3.1__tar.gz

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

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

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

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

{splunkctl-0.3.0 → splunkctl-0.3.1}/splunkctl/commands/common.py

@@ -5,6 +5,8 @@ from typing import Any
 
 import click
 
+from splunkctl import output
+
 _ALERT_TYPES = (
     "custom",
     "number of events",
@@ -159,3 +161,36 @@ def alert_kwargs(
     if schedule_window is not None:
         kwargs["schedule_window"] = schedule_window
     return kwargs
+
+
+# Known alert actions and the companion field Splunk rejects --yes without.
+# One-line adds only — this is advisory, not exhaustive.
+_REQUIRED_ACTION_FIELDS: dict[str, str] = {
+    "email": "action.email.to",
+    "webhook": "action.webhook.param.url",
+}
+
+
+def warn_missing_action_fields(
+    actions: str,
+    kwargs: dict[str, Any],
+    existing: dict[str, Any] | None = None,
+) -> None:
+    """Warn on stderr for enabled actions missing a known-required field.
+
+    Advisory only — the server remains the authority. Checks ``kwargs``
+    (explicit flags plus ``--set`` pairs) for the companion field; for
+    updates, ``existing`` (the saved search's current server-side content)
+    also satisfies the check. Actions outside ``_REQUIRED_ACTION_FIELDS``
+    are silently skipped.
+    """
+    for act in (a.strip() for a in actions.split(",") if a.strip()):
+        field = _REQUIRED_ACTION_FIELDS.get(act)
+        if field is None or kwargs.get(field):
+            continue
+        if existing is not None and existing.get(field):
+            continue
+        output.warning(
+            f"action '{act}' requires {field} — the server will reject "
+            "--yes without it."
+        )

{splunkctl-0.3.0 → splunkctl-0.3.1}/splunkctl/commands/rules.py

@@ -12,21 +12,41 @@ from splunkctl.commands.common import read_results
 from splunkctl.commands.rules_io import export_rules, import_rules
 
 
-def _resolve_rule(ctx: click.Context, client: Any, name: str, app: str | None) -> Any:
-    """Fetch a saved search, optionally within a specific app namespace."""
+def _quoted(value: str) -> str:
+    """Quote a value for an SPL ``field=value`` search filter."""
+    return '"' + value.replace('"', '\\"') + '"'
+
+
+def _resolve_rule(
+    ctx: click.Context,
+    client: Any,
+    name: str,
+    app: str | None,
+    owner: str | None = None,
+) -> Any:
+    """Fetch a saved search, optionally scoped to an app/owner namespace."""
     svc = client.service
-    if app is None:
+    if app is None and owner is None:
         try:
             return svc.saved_searches[name]
         except KeyError:
             output.error(f"Saved search not found: {name}")
             ctx.exit(1)
             raise
-    matches = svc.saved_searches.list(search=f"name={name}", app=app, count=10)
+    scope_kwargs: dict[str, str] = {}
+    if app is not None:
+        scope_kwargs["app"] = app
+        scope_kwargs["owner"] = owner if owner is not None else "-"
+    elif owner is not None:
+        scope_kwargs["owner"] = owner
+    matches = svc.saved_searches.list(
+        search=f"name={_quoted(name)}", count=10, **scope_kwargs
+    )
     for m in matches:
         if m.name == name:
             return m
-    output.error(f"Saved search not found in app '{app}': {name}")
+    scope = ", ".join(f"{k}={v}" for k, v in scope_kwargs.items())
+    output.error(f"Saved search not found ({scope}): {name}")
     ctx.exit(1)
     raise KeyError(name)
 
@@ -71,6 +91,18 @@ _DETAIL_FIELDS = (
 )
 
 
+def _action_params(c: dict[str, Any]) -> dict[str, Any]:
+    """Non-empty ``action.<name>.*`` content keys for each enabled action."""
+    actions = str(c.get("actions", "") or "")
+    params: dict[str, Any] = {}
+    for act in (a.strip() for a in actions.split(",") if a.strip()):
+        prefix = f"action.{act}."
+        for key, val in c.items():
+            if key.startswith(prefix) and val not in ("", None):
+                params[key] = val
+    return params
+
+
 def _detail(ss: Any) -> dict[str, Any]:
     c: dict[str, Any] = ss.content
     acl: dict[str, Any] = ss.access
@@ -81,6 +113,7 @@ def _detail(ss: Any) -> dict[str, Any]:
         "sharing": acl.get("sharing", ""),
     }
     row.update({f: c.get(f, "") for f in _DETAIL_FIELDS})
+    row.update(_action_params(c))
     return row
 
 
@@ -100,11 +133,34 @@ rules_group.add_command(import_rules)
     default=None,
     help="Case-insensitive name substring filter.",
 )
+@click.option(
+    "--app",
+    default=None,
+    help="Only saved searches in this app (default: current namespace, which "
+    "may miss app-private rules — pass --app to see them).",
+)
+@click.option(
+    "--owner",
+    default=None,
+    help="Only saved searches owned by this user (default: current namespace).",
+)
 @click.pass_context
-def list_rules(ctx: click.Context, name_filter: str | None) -> None:
+def list_rules(
+    ctx: click.Context,
+    name_filter: str | None,
+    *,
+    app: str | None,
+    owner: str | None,
+) -> None:
     """List all saved searches."""
     client = get_client(ctx)
-    items = client.service.saved_searches.list()
+    kwargs: dict[str, str] = {}
+    if app is not None:
+        kwargs["app"] = app
+        kwargs["owner"] = owner if owner is not None else "-"
+    elif owner is not None:
+        kwargs["owner"] = owner
+    items = client.service.saved_searches.list(**kwargs)
     if name_filter:
         needle = name_filter.lower()
         items = [ss for ss in items if needle in ss.name.lower()]
@@ -114,16 +170,17 @@ def list_rules(ctx: click.Context, name_filter: str | None) -> None:
 
 @rules_group.command()
 @click.argument("name")
+@click.option(
+    "--app",
+    default=None,
+    help="Splunk app context (needed to resolve app-private saved searches).",
+)
+@click.option("--owner", default=None, help="Splunk owner context.")
 @click.pass_context
-def get(ctx: click.Context, name: str) -> None:
+def get(ctx: click.Context, name: str, *, app: str | None, owner: str | None) -> None:
     """Get a saved search by name."""
     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 = _resolve_rule(ctx, client, name, app, owner)
     output.render(ctx, _detail(ss))
 
 
@@ -160,6 +217,7 @@ def create(
         kwargs["description"] = description
     if actions is not None:
         kwargs["actions"] = actions
+        common.warn_missing_action_fields(actions, kwargs)
     if disabled:
         kwargs["disabled"] = "1"
     if app is not None:
@@ -225,12 +283,22 @@ def update(
         ctx.exit(1)
         return
 
+    # Only fetch the existing rule up front when a required-field check
+    # against server-side state is needed — keeps other dry-runs offline.
+    client: Any = None
+    ss: Any = None
+    if actions is not None:
+        client = get_client(ctx)
+        ss = _resolve_rule(ctx, client, name, app)
+        common.warn_missing_action_fields(actions, kwargs, ss.content)
+
     detail = "\n".join(f"  {k}: {v}" for k, v in kwargs.items())
     if not guard.check(ctx, f"Update saved search '{name}'", details=detail):
         return
 
-    client = get_client(ctx)
-    ss = _resolve_rule(ctx, client, name, app)
+    if ss is None:
+        client = get_client(ctx)
+        ss = _resolve_rule(ctx, client, name, app)
     ss.update(**kwargs).refresh()
     output.info(f"Updated saved search '{name}'.")
 

{splunkctl-0.3.0 → splunkctl-0.3.1}/splunkctl/commands/rules_io.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Any
+from typing import Any, NotRequired, TypedDict
 
 import click
 import yaml
@@ -51,7 +51,38 @@ _TRUNC = 60
 
 
 def _trunc(val: str) -> str:
-    return val if len(val) <= _TRUNC else val[: _TRUNC - 1] + "…"
+    """Truncate for the text preview, with an explicit hidden-length marker.
+
+    Never emits a bare ``…`` — a truncated value always says how many
+    characters were hidden, e.g. ``foo… [+57 chars]``.
+    """
+    if len(val) <= _TRUNC:
+        return val
+    kept = val[: _TRUNC - 1]
+    hidden = len(val) - len(kept)
+    return f"{kept}… [+{hidden} chars]"
+
+
+class FieldChange(TypedDict):
+    """One field's before/after value in a rule diff."""
+
+    field: str
+    old: str | None
+    new: str
+
+
+class RuleDiff(TypedDict):
+    """Full, untruncated diff classification for one YAML rule doc.
+
+    ``kind`` is the granular text-preview classification (create / update /
+    unchanged / exists / skip). JSON output collapses ``exists`` into
+    ``unchanged`` — see ``_json_row``.
+    """
+
+    name: str | None
+    kind: str
+    changes: list[FieldChange]
+    reason: NotRequired[str]
 
 
 def _rule_to_dict(ss: Any) -> dict[str, Any]:
@@ -154,6 +185,94 @@ def _changes(ss: Any, spl: str, kwargs: dict[str, Any]) -> dict[str, tuple[str,
     return diff
 
 
+def _field_changes(diff: dict[str, tuple[str, str]]) -> list[FieldChange]:
+    return [{"field": k, "old": old, "new": new} for k, (old, new) in diff.items()]
+
+
+def _create_changes(spl: str, kwargs: dict[str, Any]) -> list[FieldChange]:
+    """Full set of fields a new rule would be created with (old is None)."""
+    changes: list[FieldChange] = [{"field": "search", "old": None, "new": str(spl)}]
+    changes.extend({"field": k, "old": None, "new": str(v)} for k, v in kwargs.items())
+    return changes
+
+
+def _rule_diff(svc: Any, rule: Any, *, update: bool) -> RuleDiff:
+    """Classify one YAML doc and compute its full, untruncated field diff.
+
+    This is the dry-run-only counterpart to ``_plan_rule`` (which drives
+    the ``--yes`` apply path and is left untouched): a single pass that
+    feeds both the text preview and the structured JSON diff.
+    """
+    if not isinstance(rule, dict) or "name" not in rule:
+        return {
+            "name": None,
+            "kind": "skip",
+            "changes": [],
+            "reason": "invalid entry: no name",
+        }
+    name = rule["name"]
+    spl = rule.get("search", "")
+    if not spl:
+        return {
+            "name": name,
+            "kind": "skip",
+            "changes": [],
+            "reason": "no search field",
+        }
+    kwargs = _import_kwargs(rule)
+    try:
+        ss = svc.saved_searches[name]
+    except KeyError:
+        return {"name": name, "kind": "create", "changes": _create_changes(spl, kwargs)}
+    if not update:
+        return {"name": name, "kind": "exists", "changes": []}
+    diff = _changes(ss, spl, kwargs)
+    if not diff:
+        return {"name": name, "kind": "unchanged", "changes": []}
+    return {"name": name, "kind": "update", "changes": _field_changes(diff)}
+
+
+def _preview_lines(d: RuleDiff) -> list[str]:
+    """Render one rule's diff as the human-readable text preview lines."""
+    name = d["name"] or ""
+    kind = d["kind"]
+    if kind == "skip":
+        reason = d.get("reason", "")
+        label = f"{name}: {reason}" if name else reason
+        return [f"  skip: {label}"]
+    if kind == "update":
+        lines = [f"  update: {name}"]
+        lines.extend(
+            f"    {c['field']}: {_trunc(str(c['old']))} -> {_trunc(c['new'])}"
+            for c in d["changes"]
+        )
+        return lines
+    return [f"  {kind}: {name}"]
+
+
+# no-update-mode "exists" is reported to JSON consumers as "unchanged" — it
+# matches the CLI's own summary counts, which already fold the two together.
+_JSON_ACTIONS = {
+    "create": "create",
+    "update": "update",
+    "unchanged": "unchanged",
+    "exists": "unchanged",
+    "skip": "skip",
+}
+
+
+def _json_row(d: RuleDiff) -> dict[str, Any]:
+    """Build one rule's JSON diff row: ``{name, action, changes[, reason]}``."""
+    row: dict[str, Any] = {
+        "name": d["name"],
+        "action": _JSON_ACTIONS[d["kind"]],
+        "changes": d["changes"],
+    }
+    if d["kind"] == "skip":
+        row["reason"] = d.get("reason", "")
+    return row
+
+
 def _plan_rule(svc: Any, rule: Any, *, update: bool) -> tuple[str, list[str]]:
     """Classify one YAML doc: (status line, per-field diff lines)."""
     if not isinstance(rule, dict) or "name" not in rule:
@@ -222,8 +341,13 @@ def import_rules(
     """Import saved searches from a YAML file.
 
     Dry-run previews create/update/unchanged per rule with field-level
-    diffs. Exits non-zero when any rule is skipped or fails, so CI
-    pipelines cannot silently pass a broken detections file.
+    diffs on stderr. Pass ``--json``/``--format json`` to also get a
+    full, untruncated JSON diff array on stdout: one object per rule,
+    ``{"name", "action", "changes": [{"field", "old", "new"}], "reason"}``
+    (on skip only). Action is one of ``create`` | ``update`` | ``unchanged``
+    | ``skip``; ``old`` is null for ``create``, ``changes`` is empty for
+    ``unchanged`` and ``skip``. Exits non-zero when any rule is skipped or
+    fails, so CI pipelines cannot silently pass a broken detections file.
     """
     p = Path(file_path)
     try:
@@ -241,15 +365,10 @@ def import_rules(
     client = get_client(ctx)
     svc = client.service
 
+    diffs = [_rule_diff(svc, rule, update=update) for rule in docs]
     plan_lines: list[str] = []
-    planned_skips = 0
-    for rule in docs:
-        status, diff_lines = _plan_rule(svc, rule, update=update)
-        kind, _, label = status.partition(":")
-        plan_lines.append(f"  {kind}: {label}")
-        plan_lines.extend(f"  {line}" for line in diff_lines)
-        if kind == "skip":
-            planned_skips += 1
+    for d in diffs:
+        plan_lines.extend(_preview_lines(d))
     detail = f"  update existing: {update}\n" + "\n".join(plan_lines)
 
     if not guard.check(
@@ -257,6 +376,9 @@ def import_rules(
         f"Import {len(docs)} rule(s) from {p.name}",
         details=detail,
     ):
+        obj: dict[str, Any] = ctx.obj or {}
+        if obj.get("json") or obj.get("format") == "json":
+            output.render(ctx, [_json_row(d) for d in diffs])
         return
 
     results: list[str] = []

{splunkctl-0.3.0 → splunkctl-0.3.1}/splunkctl/commands/search.py

@@ -204,6 +204,7 @@ def list_jobs(ctx: click.Context) -> None:
     rows: list[dict[str, Any]] = []
     for job in svc.jobs:
         content: dict[str, Any] = dict(job.content)
+        acl: dict[str, Any] = job.access
         dur = content.get("runDuration", "")
         if isinstance(dur, (float, str)):
             try:
@@ -215,7 +216,7 @@ def list_jobs(ctx: click.Context) -> None:
             {
                 "sid": job.sid,
                 "status": content.get("dispatchState", ""),
-                "owner": content.get("author", ""),
+                "owner": acl.get("owner", ""),
                 "spl": spl[:60] + ("…" if len(spl) > 60 else ""),
                 "event_count": content.get("eventCount", 0),
                 "run_duration": dur,

{splunkctl-0.3.0 → splunkctl-0.3.1}/splunkctl/commands/server.py

@@ -97,11 +97,14 @@ def kvstore_status(ctx: click.Context) -> None:
         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": c.get("current.status", ""),
-        "port": c.get("current.port", ""),
-        "version": c.get("current.version", ""),
-        "storage_engine": c.get("current.storageEngine", ""),
-        "db_path": c.get("current.dbPath", ""),
+        "status": status,
+        "port": current.get("port", ""),
+        "version": current.get("version", ""),
+        "storage_engine": current.get("storageEngine", ""),
+        "db_path": current.get("dbPath", ""),
     }
     output.render(ctx, row)

{splunkctl-0.3.0 → splunkctl-0.3.1}/splunkctl/output.py

@@ -103,6 +103,11 @@ def info(msg: str) -> None:
     click.echo(msg, err=True)
 
 
+def warning(msg: str) -> None:
+    """Print an advisory warning to stderr. Does not affect exit code."""
+    click.echo(f"Warning: {msg}", err=True)
+
+
 def _csv(rows: Rows) -> str:
     if not rows:
         return ""

{splunkctl-0.3.0 → splunkctl-0.3.1}/splunkctl/skill/SKILL.md

@@ -3,6 +3,15 @@
 You are operating a Splunk Enterprise instance via `splunkctl`. This guide
 tells you how to authenticate, run commands, and handle common workflows.
 
+## Scope
+
+`splunkctl` targets Splunk Enterprise core over the REST API. There is no
+dedicated `es` command group yet (planned for a later phase). Enterprise
+Security capabilities — notables, risk, correlation-search actions,
+asset/identity lookups — are reachable today through the generic search,
+rules, and lookups commands documented below; see **ES recipes** under
+Workflow patterns.
+
 ## Auth
 
 Set up credentials once — all commands inherit them automatically.
@@ -47,7 +56,9 @@ Token auth: set `SPLUNK_TOKEN` for service-account access without a password.
 - **stdout**: data payload only (table, JSON, CSV, JSONL)
 - **stderr**: info messages, errors, dry-run previews
 - **JSON format**: always a JSON array of objects, even for single items
-- **Exit codes**: 0 = success, 1 = error. Dry-run exits 0.
+- **Exit codes**: 0 = success, 1 = application error (not found, server
+  rejected the request, etc.), 2 = usage error (missing/invalid flags or
+  arguments — Click rejects before any request is made). Dry-run exits 0.
 
 ## Commands
 
@@ -79,12 +90,16 @@ splunkctl search upload --path threats.csv --index threat_intel --yes
 SPL is auto-normalized: bare keywords get `search` prepended; pipe-leading
 and generating commands (`makeresults`, `inputlookup`, `tstats`, etc.) are
 passed through unchanged. Use `--app` to scope searches to a specific app.
+The `owner` column in `search jobs` is the real submitting user (job ACL,
+not the job's internal `author` field, which is always blank).
 
 ### Rules (saved searches)
 
 ```bash
 splunkctl rules list
+splunkctl rules list --app Splunk_Security_Essentials  # include app-private rules
 splunkctl rules get 'My Rule'
+splunkctl rules get 'My Rule' --app Splunk_Security_Essentials --owner nobody
 splunkctl rules create --name 'New Rule' --search 'index=main error' \
     --cron '*/5 * * * *' --actions email --description 'Alert on errors' --yes
 splunkctl rules update 'My Rule' --search 'index=main fail' --yes
@@ -101,6 +116,41 @@ splunkctl rules import --path detections.yml --yes
 splunkctl rules import --path detections.yml --no-update --yes
 ```
 
+`list`/`get` default to the current namespace, which misses saved
+searches private to another app — e.g. detections shipped inside
+Splunk_Security_Essentials are invisible to a plain `rules list`. Always
+pass `--app` when auditing detection coverage: it automatically
+wildcards the owner (`owner="-"`) so app-private rules owned by any user
+are included, not just the caller's own. Add `--owner` only to narrow
+the audit to a single user's rules — omitting `--app` entirely still
+leaves a blind spot. `get` also surfaces every enabled action's
+non-empty `action.<name>.*` params (e.g. `action.notable.param.severity`,
+`action.risk.param._risk_score`) inline — no export needed just to see
+what a correlation search's actions are configured to do.
+
+`create`/`update --actions email` or `--actions webhook` warn on stderr
+during dry-run if the action's required companion field is missing
+(`action.email.to` for email, `action.webhook.param.url` for webhook) —
+the server otherwise 400s on `--yes`. Supply it with `--set`:
+
+```bash
+splunkctl rules create --name 'New Rule' --search 'index=main error' \
+    --actions email --set action.email.to=soc@bank.example --yes
+```
+
+`--set KEY=VALUE` (repeatable, `create`/`update` only) sets any raw
+saved-search REST field — the generic escape hatch for anything without
+a first-class flag, including ES action params:
+
+```bash
+splunkctl rules update 'ES Correlation Search' \
+    --set action.notable.param.severity=high \
+    --set action.notable.param.security_domain=access \
+    --set action.risk.param._risk_score=80 \
+    --set action.risk.param._risk_object_type=user \
+    --yes
+```
+
 ### Alerts
 
 ```bash
@@ -248,6 +298,10 @@ splunkctl server license                # license pool usage
 splunkctl server kvstore                # KV store status
 ```
 
+`kvstore` always reports an explicit status word (`ready`, `failed`,
+`starting`, `unknown`, ...) — never a blank field, so a down KV store
+can't be mistaken for a healthy empty result.
+
 ### Config
 
 ```bash
@@ -276,10 +330,25 @@ splunkctl skill install                 # install to ~/.claude/skills/
 
 ### Investigate an alert
 
+Pivot on the firing's `sid` to pull the exact triggering events — don't
+re-run the detection's SPL broadly, that returns whatever matches now,
+not what actually fired.
+
 ```bash
-splunkctl alerts list
-splunkctl rules get 'Alert Rule Name'
-splunkctl search run 'index=main error' --earliest -7d --limit 1000
+splunkctl alerts list                    # each firing has a sid
+splunkctl alerts get 'Alert Rule Name'    # all firings for one rule, with sid
+splunkctl search job <sid>                # the exact triggering results
+splunkctl search job <sid> --events       # raw events instead of stats/table rows
+```
+
+Fallback only: if the job's TTL has expired (`search job <sid>` errors
+not-found), recover the SPL from the rule and re-run it over the firing's
+time window instead:
+
+```bash
+splunkctl rules get 'Alert Rule Name'                # recover the SPL
+splunkctl search run '<SPL from rules get>' \
+    --earliest -7d --latest now --limit 1000
 ```
 
 ### Audit detection coverage
@@ -287,6 +356,43 @@ splunkctl search run 'index=main error' --earliest -7d --limit 1000
 ```bash
 splunkctl rules list --json | jq '[.[] | select(.is_scheduled == "1")]'
 splunkctl rules list --json | jq '[.[] | select(.disabled == "1")]'
+# Repeat with --app for every app that ships detections, or app-private
+# rules (e.g. Splunk_Security_Essentials) are silently excluded:
+splunkctl rules list --app Splunk_Security_Essentials --json | jq '[.[] | select(.disabled == "1")]'
+```
+
+### ES recipes
+
+No dedicated `es` command group yet (see Scope) — these generic
+recipes cover the common Enterprise Security workflows in the meantime.
+
+```bash
+# Read notables
+splunkctl search run 'index=notable' --earliest -24h --latest now --limit 100
+splunkctl search run 'index=notable status_label!=Closed' --earliest -7d --limit 200
+
+# Read risk — aggregate risk score per object
+splunkctl search run 'index=risk | stats sum(risk_score) by risk_object' \
+    --earliest -24h --latest now
+
+# Author/tune a correlation search's notable + risk actions via --set
+splunkctl rules update 'ES Correlation Search Name' \
+    --set action.notable.param.severity=high \
+    --set action.notable.param.security_domain=access \
+    --set action.risk.param._risk_score=80 \
+    --set action.risk.param._risk_object=user \
+    --set action.risk.param._risk_object_type=user \
+    --yes
+# Audit what a correlation search's actions are already set to:
+splunkctl rules get 'ES Correlation Search Name'   # inlines action.notable.*/action.risk.* params
+
+# Asset/identity CSVs — managed like any other lookup table (exact
+# filename/app vary by ES version, e.g. assets_by_str.csv /
+# identities_lookup_by_str.csv under SplunkEnterpriseSecuritySuite):
+splunkctl lookups list --app SplunkEnterpriseSecuritySuite
+splunkctl lookups download assets_by_str.csv --app SplunkEnterpriseSecuritySuite
+splunkctl lookups update assets_by_str.csv --file assets.csv \
+    --app SplunkEnterpriseSecuritySuite --yes
 ```
 
 ### Detection rule lifecycle
@@ -319,8 +425,17 @@ splunkctl rules import --path detections.yml
 splunkctl rules import --path detections.yml --yes
 # Import without updating existing rules
 splunkctl rules import --path detections.yml --no-update --yes
+# Machine-readable dry-run diff, to verify programmatically before --yes
+splunkctl rules import --path detections.yml --json
 ```
 
+`import --json` (dry-run only, apply path is unaffected) emits a full,
+untruncated diff array on stdout instead of applying anything: one
+object per rule, `{"name", "action", "changes": [{"field", "old",
+"new"}], "reason"}`. `action` is `create` | `update` | `unchanged` |
+`skip`; `reason` is present only when `action` is `skip`; `old` is
+`null` for `create`; `changes` is `[]` for `unchanged` and `skip`.
+
 ### Parsers-as-code
 
 ```bash

{splunkctl-0.3.0 → splunkctl-0.3.1}/splunkctl.egg-info/PKG-INFO

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

{splunkctl-0.3.0 → splunkctl-0.3.1}/tests/test_version.py

@@ -4,4 +4,4 @@ from splunkctl import __version__
 
 
 def test_version() -> None:
-    assert __version__ == "0.3.0"
+    assert __version__ == "0.3.1"