splunkctl 0.8.0__tar.gz → 0.10.0__tar.gz

{splunkctl-0.8.0 → splunkctl-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: splunkctl
-Version: 0.8.0
+Version: 0.10.0
 Summary: CLI tool for Splunk Enterprise SIEM operations.
 Author: dannyota
 License-Expression: Apache-2.0
@@ -38,11 +38,11 @@ Dynamic: license-file
 
 <div align="center">
 
-<a href="https://splunk.danny.vn"><img src="docs/assets/banner.svg" alt="splunkctl — operate Splunk Enterprise as code" width="600"></a>
+<a href="https://splunk.danny.vn"><img src="docs/assets/banner.svg" alt="splunkctl — operate Splunk Enterprise and Splunk SOAR as code" width="600"></a>
 
 # splunkctl
 
-**Operate Splunk Enterprise as code — for SOC teams, detection engineers, and AI agents.**
+**Operate Splunk Enterprise and Splunk SOAR as code — for SOC teams, detection engineers, and AI agents.**
 
 [Docs](https://splunk.danny.vn) · [Catalog](docs/design/catalog.md) · [Releases](https://github.com/dannyota/splunkctl/releases)
 
@@ -50,15 +50,19 @@ Dynamic: license-file
 
 ---
 
-A Python CLI that queries, inspects, and manages a **remote** Splunk
-Enterprise instance over the REST API. Built on the
+A Python CLI that queries, inspects, and manages **remote** Splunk
+Enterprise and Splunk SOAR instances over their REST APIs. SIEM commands
+are built on the
 [splunk-sdk-python](https://github.com/dannyota/splunk-sdk-python/tree/splunkctl)
-fork with [Click](https://click.palletsprojects.com/). The core loop is
-**pull live state → review the diff → push it back** — one `state` engine
-covering rules, parsers, macros, lookups, and dashboards, with a
-change-evidence report artifact for bank change tickets. It's built for
-humans and LLM agents alike: deterministic flags, `--json` everywhere,
-structured error envelopes, and a built-in MCP server
+fork with [Click](https://click.palletsprojects.com/); SOAR commands use
+`SOARClient`, a requests-based Django REST client with dual auth (token +
+Basic fallback). The SIEM core loop is **pull live state, review the diff,
+push it back** -- one `state` engine covering rules, parsers, macros,
+lookups, and dashboards, with a change-evidence report artifact for change
+tickets. The SOAR surface covers ops visibility, container/artifact
+lifecycle, the first playbooks-as-code loop anywhere, and SIEM-to-SOAR
+ingest. Built for humans and LLM agents alike: deterministic flags,
+`--json` everywhere, structured error envelopes, and a built-in MCP server
 (`splunkctl mcp serve`) with progressive tool discovery.
 
 > **Every mutation is dry-run by default.** Nothing changes until you pass
@@ -90,8 +94,23 @@ structured error envelopes, and a built-in MCP server
   `--limit`/`--offset`/`--filter` on every list surface, multi-instance
   profiles with a bank-safety guard banner
   (`(profile: uat @ host:port)`).
-- **Built for agents** — built-in MCP server with 129 auto-generated tools,
-  progressive discovery (5 meta-tools + focus/unfocus), 22 guide resources,
+- **SOAR ops** — `soar` command tree: containers, artifacts, vault, notes,
+  cases/workbooks, approvals, custom lists, indicators, evidence, users,
+  roles, audit, and cross-object search. Full lifecycle: create, update,
+  close, assign, delete -- with the same dry-run guard and typed error
+  envelopes.
+- **Playbooks as code** — `soar playbooks export --unpack` / `import`
+  round-trips playbook tgz bundles (the first such tool anywhere);
+  `soar playbooks delete` removes them through the Web UI route (no
+  REST deletion exists); `soar playbooks run --wait` drives and polls
+  runs to completion; `soar actions run --wait` does the same for
+  connector actions.
+- **SIEM-to-SOAR ingest** — `soar ingest --spl` runs a SIEM search and
+  creates SOAR containers + typed CEF artifacts using the official CIM-to-CEF
+  field map, with SDI dedup, severity mapping, and last-artifact automation
+  batching.
+- **Built for agents** — built-in MCP server with 237 auto-generated tools,
+  progressive discovery (5 meta-tools + focus/unfocus), 33 guide resources,
   guard markers on every mutation, dual output (TTY = table, pipe = JSON).
 
 ## Install
@@ -119,10 +138,12 @@ splunkctl --version
 ## Quickstart
 
 ```bash
-splunkctl config init                         # interactive setup
-splunkctl doctor                              # check connection, auth, permissions
-splunkctl search run 'index=main | head 10'   # run a search
-splunkctl rules list                          # list detection rules
+splunkctl config init                         # interactive SIEM setup
+splunkctl config init --soar                  # add SOAR credentials
+splunkctl doctor                              # check SIEM connection
+splunkctl soar test                           # check SOAR connection
+splunkctl search run 'index=main | head 10'   # run a SIEM search
+splunkctl soar containers list                # list SOAR containers
 splunkctl commands --json                     # discover every verb
 ```
 
@@ -174,6 +195,7 @@ splunkctl state push --dir config/ --report r.json --yes  # deploy + evidence
 | `tags` | Tags — list, get |
 | `datamodels` | Data model definitions + acceleration health |
 | `state` | Config-as-code pull/diff/push with change-evidence reports |
+| `soar` | SOAR: containers, artifacts, vault, playbooks, actions, cases, ingest |
 | `commands` | Machine-readable command tree (JSON) |
 | `mcp` | Built-in MCP server for AI agent integration |
 
@@ -245,11 +267,12 @@ splunkctl mcp install              # register in .mcp.json
 splunkctl mcp serve                # start stdio MCP server
 ```
 
-The MCP server auto-generates 129 typed tools from the Click command tree
-with progressive discovery — agents start with 5 meta-tools (`help`,
-`usage`, `focus`, `unfocus`, `run`) and dynamically load typed schemas per
-command group. 22 guide resources are served as `guide://` URIs. Mutations
-are guarded: `yes=true` to apply (dry-run by default).
+The MCP server auto-generates 229 typed tools from the Click command tree
+(SIEM + SOAR) with progressive discovery -- agents start with 5 meta-tools
+(`help`, `usage`, `focus`, `unfocus`, `run`) and dynamically load typed
+schemas per command group. Subgroup-granular focus works for nested groups
+like `soar containers`. 33 guide resources are served as `guide://` URIs.
+Mutations are guarded: `yes=true` to apply (dry-run by default).
 
 ## License
 

{splunkctl-0.8.0 → splunkctl-0.10.0}/README.md

@@ -1,10 +1,10 @@
 <div align="center">
 
-<a href="https://splunk.danny.vn"><img src="docs/assets/banner.svg" alt="splunkctl — operate Splunk Enterprise as code" width="600"></a>
+<a href="https://splunk.danny.vn"><img src="docs/assets/banner.svg" alt="splunkctl — operate Splunk Enterprise and Splunk SOAR as code" width="600"></a>
 
 # splunkctl
 
-**Operate Splunk Enterprise as code — for SOC teams, detection engineers, and AI agents.**
+**Operate Splunk Enterprise and Splunk SOAR as code — for SOC teams, detection engineers, and AI agents.**
 
 [Docs](https://splunk.danny.vn) · [Catalog](docs/design/catalog.md) · [Releases](https://github.com/dannyota/splunkctl/releases)
 
@@ -12,15 +12,19 @@
 
 ---
 
-A Python CLI that queries, inspects, and manages a **remote** Splunk
-Enterprise instance over the REST API. Built on the
+A Python CLI that queries, inspects, and manages **remote** Splunk
+Enterprise and Splunk SOAR instances over their REST APIs. SIEM commands
+are built on the
 [splunk-sdk-python](https://github.com/dannyota/splunk-sdk-python/tree/splunkctl)
-fork with [Click](https://click.palletsprojects.com/). The core loop is
-**pull live state → review the diff → push it back** — one `state` engine
-covering rules, parsers, macros, lookups, and dashboards, with a
-change-evidence report artifact for bank change tickets. It's built for
-humans and LLM agents alike: deterministic flags, `--json` everywhere,
-structured error envelopes, and a built-in MCP server
+fork with [Click](https://click.palletsprojects.com/); SOAR commands use
+`SOARClient`, a requests-based Django REST client with dual auth (token +
+Basic fallback). The SIEM core loop is **pull live state, review the diff,
+push it back** -- one `state` engine covering rules, parsers, macros,
+lookups, and dashboards, with a change-evidence report artifact for change
+tickets. The SOAR surface covers ops visibility, container/artifact
+lifecycle, the first playbooks-as-code loop anywhere, and SIEM-to-SOAR
+ingest. Built for humans and LLM agents alike: deterministic flags,
+`--json` everywhere, structured error envelopes, and a built-in MCP server
 (`splunkctl mcp serve`) with progressive tool discovery.
 
 > **Every mutation is dry-run by default.** Nothing changes until you pass
@@ -52,8 +56,23 @@ structured error envelopes, and a built-in MCP server
   `--limit`/`--offset`/`--filter` on every list surface, multi-instance
   profiles with a bank-safety guard banner
   (`(profile: uat @ host:port)`).
-- **Built for agents** — built-in MCP server with 129 auto-generated tools,
-  progressive discovery (5 meta-tools + focus/unfocus), 22 guide resources,
+- **SOAR ops** — `soar` command tree: containers, artifacts, vault, notes,
+  cases/workbooks, approvals, custom lists, indicators, evidence, users,
+  roles, audit, and cross-object search. Full lifecycle: create, update,
+  close, assign, delete -- with the same dry-run guard and typed error
+  envelopes.
+- **Playbooks as code** — `soar playbooks export --unpack` / `import`
+  round-trips playbook tgz bundles (the first such tool anywhere);
+  `soar playbooks delete` removes them through the Web UI route (no
+  REST deletion exists); `soar playbooks run --wait` drives and polls
+  runs to completion; `soar actions run --wait` does the same for
+  connector actions.
+- **SIEM-to-SOAR ingest** — `soar ingest --spl` runs a SIEM search and
+  creates SOAR containers + typed CEF artifacts using the official CIM-to-CEF
+  field map, with SDI dedup, severity mapping, and last-artifact automation
+  batching.
+- **Built for agents** — built-in MCP server with 237 auto-generated tools,
+  progressive discovery (5 meta-tools + focus/unfocus), 33 guide resources,
   guard markers on every mutation, dual output (TTY = table, pipe = JSON).
 
 ## Install
@@ -81,10 +100,12 @@ splunkctl --version
 ## Quickstart
 
 ```bash
-splunkctl config init                         # interactive setup
-splunkctl doctor                              # check connection, auth, permissions
-splunkctl search run 'index=main | head 10'   # run a search
-splunkctl rules list                          # list detection rules
+splunkctl config init                         # interactive SIEM setup
+splunkctl config init --soar                  # add SOAR credentials
+splunkctl doctor                              # check SIEM connection
+splunkctl soar test                           # check SOAR connection
+splunkctl search run 'index=main | head 10'   # run a SIEM search
+splunkctl soar containers list                # list SOAR containers
 splunkctl commands --json                     # discover every verb
 ```
 
@@ -136,6 +157,7 @@ splunkctl state push --dir config/ --report r.json --yes  # deploy + evidence
 | `tags` | Tags — list, get |
 | `datamodels` | Data model definitions + acceleration health |
 | `state` | Config-as-code pull/diff/push with change-evidence reports |
+| `soar` | SOAR: containers, artifacts, vault, playbooks, actions, cases, ingest |
 | `commands` | Machine-readable command tree (JSON) |
 | `mcp` | Built-in MCP server for AI agent integration |
 
@@ -207,11 +229,12 @@ splunkctl mcp install              # register in .mcp.json
 splunkctl mcp serve                # start stdio MCP server
 ```
 
-The MCP server auto-generates 129 typed tools from the Click command tree
-with progressive discovery — agents start with 5 meta-tools (`help`,
-`usage`, `focus`, `unfocus`, `run`) and dynamically load typed schemas per
-command group. 22 guide resources are served as `guide://` URIs. Mutations
-are guarded: `yes=true` to apply (dry-run by default).
+The MCP server auto-generates 229 typed tools from the Click command tree
+(SIEM + SOAR) with progressive discovery -- agents start with 5 meta-tools
+(`help`, `usage`, `focus`, `unfocus`, `run`) and dynamically load typed
+schemas per command group. Subgroup-granular focus works for nested groups
+like `soar containers`. 33 guide resources are served as `guide://` URIs.
+Mutations are guarded: `yes=true` to apply (dry-run by default).
 
 ## License
 

splunkctl-0.10.0/splunkctl/__init__.py

@@ -0,0 +1,3 @@
+"""CLI tool for Splunk Enterprise and Splunk SOAR operations."""
+
+__version__ = "0.10.0"

{splunkctl-0.8.0 → splunkctl-0.10.0}/splunkctl/client.py

@@ -15,6 +15,7 @@ from typing import Any
 import click
 import requests
 import splunklib.client as splunk_client
+import urllib3
 
 from splunkctl import config as cfg_mod
 
@@ -186,6 +187,10 @@ class _WebSession:
         self._timeout = timeout
         self._session = requests.Session()
         self._session.verify = verify
+        if not verify:
+            # verify=false is an explicit config choice (lab/self-signed);
+            # without this every request spams InsecureRequestWarning.
+            urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
         self._csrf_token: str | None = None
         self._logged_in = False
 

{splunkctl-0.8.0 → splunkctl-0.10.0}/splunkctl/commands/es.py

@@ -57,7 +57,7 @@ def _status_to_int(value: str) -> str:
     key = value.strip().lower()
     if key in _STATUS_MAP:
         return _STATUS_MAP[key]
-    if value.isdigit():
+    if value.isascii() and value.isdigit():
         return value
     known = ", ".join(_STATUS_MAP)
     raise click.BadParameter(f"'{value}' is not a known status ({known}, or 0-5)")

{splunkctl-0.8.0 → splunkctl-0.10.0}/splunkctl/mcp/server.py

@@ -8,6 +8,7 @@ import subprocess
 import sys
 from typing import Any
 
+import click
 from mcp.server.fastmcp import Context, FastMCP
 from mcp.server.fastmcp.utilities.func_metadata import ArgModelBase, FuncMetadata
 from mcp.types import ToolAnnotations
@@ -20,9 +21,13 @@ from splunkctl.mcp.tools import (
     ToolEntry,
     ToolIndex,
     build_tool_index,
+    direct_commands,
     group_names,
     group_summary,
     group_tools,
+    has_subgroups,
+    leaf_count,
+    subgroup_names,
 )
 
 _INSTRUCTIONS = """\
@@ -32,28 +37,45 @@ the preferred way to run commands (validated arguments, full schemas). \
 `usage <command>` previews one command's schema and auto-loads it as a \
 callable tool. `run` is an escape hatch for raw command strings (no \
 validation). `unfocus` when done to free context. Mutations are guarded: \
-pass yes=true to apply (dry-run by default)."""
+pass yes=true to apply (dry-run by default). \
+The soar tree has nested subgroups (containers, playbooks, actions, ...); \
+focus at subgroup granularity: `focus "soar containers"`, not `focus soar`. \
+`help soar` lists available subgroups."""
 
 _FORCE_FLAGS = ["--json"]
 
 _STRIP_PARAMS = SKIP_PARAMS
 
 
+def _decode_stream(data: bytes) -> str:
+    """Decode subprocess output, tolerating binary payloads.
+
+    Commands like ``soar playbooks export`` emit raw bytes (a tgz) on
+    stdout when ``--out`` is omitted — surface a hint instead of dying
+    on a UTF-8 decode error.
+    """
+    try:
+        return data.decode()
+    except UnicodeDecodeError:
+        return f"(binary output: {len(data)} bytes — pass --out FILE to save it)"
+
+
 def _exec_cli(args: list[str]) -> str:
     """Run ``splunkctl <args>`` as a subprocess and return output."""
     cmd = [sys.executable, "-m", "splunkctl", *args, *_FORCE_FLAGS]
     result = subprocess.run(  # noqa: S603
         cmd,
         capture_output=True,
-        text=True,
         timeout=120,
     )
-    out = result.stdout.strip()
-    err = result.stderr.strip()
+    out = _decode_stream(result.stdout).strip()
+    err = _decode_stream(result.stderr).strip()
     if result.returncode != 0:
         return err or out or f"Command failed with exit code {result.returncode}"
     if err and out:
-        return f"{out}\n\n{err}"
+        # stderr carries the guard banner / info lines — they precede
+        # the payload semantically, so keep them first.
+        return f"{err}\n\n{out}"
     return out or err or "(no output)"
 
 
@@ -96,10 +118,15 @@ def _build_cli_args(entry: ToolEntry, params: dict[str, Any]) -> list[str]:
             items = value if isinstance(value, list) else [value]
             positional[pname] = [str(v) for v in items]
             continue
-        flag = f"--{pname.replace('_', '-')}"
+        # Renamed Click options (--severity → severity_override) make the
+        # schema name diverge from the CLI flag; the entry's flag map is
+        # authoritative.
+        flag = entry.flags.get(pname, f"--{pname.replace('_', '-')}")
         if isinstance(value, bool):
             if value:
                 args.append(flag)
+            elif pname in entry.neg_flags:
+                args.append(entry.neg_flags[pname])
         elif isinstance(value, list):
             for item in value:
                 args.extend([flag, str(item)])
@@ -149,11 +176,40 @@ def create_server() -> FastMCP:
         """List command groups, or subcommands within a group."""
         if group is None:
             rows = group_summary(cli)
-            lines = [
-                f"{r['group']:16s} {r['description']} ({r['count']} cmds)" for r in rows
-            ]
+            lines: list[str] = []
+            for r in rows:
+                line = f"{r['group']:16s} {r['description']} ({r['count']} cmds)"
+                lines.append(line)
+                if "subgroups" in r:
+                    lines.append(f"{'':16s}   subgroups: {r['subgroups']}")
+                    lines.append(
+                        f"{'':16s}   focus at subgroup level: "
+                        f'focus "{r["group"]} <subgroup>"'
+                    )
             return "\n".join(lines)
-        return _exec_cli([group, "--help"])
+        # For groups with subgroups, show the two-level layout
+        parts = _split_command(group)
+        if len(parts) == 1 and has_subgroups(cli, parts[0]):
+            grp = parts[0]
+            top_cmd = cli.commands.get(grp)
+            if not isinstance(top_cmd, click.Group):  # guaranteed by has_subgroups
+                raise TypeError(f"expected group for {grp!r}")
+            sg = subgroup_names(cli, grp)
+            dc = direct_commands(cli, grp)
+            lines = [f'{grp} subgroups (focus "{grp} <subgroup>"):']
+            for s in sg:
+                sub_cmd = top_cmd.commands[s]
+                desc = (sub_cmd.help or "").split("\n")[0]
+                n = leaf_count(sub_cmd) if isinstance(sub_cmd, click.Group) else 0
+                lines.append(f"  {grp} {s:16s} {desc} ({n} cmds)")
+            if dc:
+                lines.append(f"\n{grp} direct commands:")
+                for c in dc:
+                    sub_cmd = top_cmd.commands[c]
+                    desc = (sub_cmd.help or "").split("\n")[0]
+                    lines.append(f"  {grp} {c:16s} {desc}")
+            return "\n".join(lines)
+        return _exec_cli([*parts, "--help"])
 
     # --- Meta-tool: usage ---
 
@@ -161,7 +217,8 @@ def create_server() -> FastMCP:
         name="usage",
         description=(
             "Show flags, args, and description for one command. "
-            "Auto-loads it as a callable tool."
+            "Auto-loads it as a callable tool. "
+            'Accepts nested paths: usage "soar playbooks run".'
         ),
         annotations=ToolAnnotations(readOnlyHint=True),
     )
@@ -193,7 +250,8 @@ def create_server() -> FastMCP:
         name="focus",
         description=(
             "Load typed tools for a command group (enables full schemas). "
-            "Preferred over run for validated arguments."
+            "Preferred over run for validated arguments. "
+            'Nested groups like soar require subgroup: focus "soar containers".'
         ),
         annotations=ToolAnnotations(readOnlyHint=True),
     )
@@ -203,6 +261,26 @@ def create_server() -> FastMCP:
             count = len(focused[group])
             return f"Group '{group}' already focused ({count} tools)."
 
+        # Reject bare groups that have nested subgroups (too many tools).
+        parts = _split_command(group)
+        if len(parts) == 1 and has_subgroups(cli, parts[0]):
+            sg = subgroup_names(cli, parts[0])
+            dc = direct_commands(cli, parts[0])
+            lines = [
+                f"'{parts[0]}' has nested subgroups — focus at "
+                f"subgroup level to avoid flooding context.",
+                "",
+                "Subgroups:",
+            ]
+            for s in sg:
+                lines.append(f'  focus "{parts[0]} {s}"')
+            if dc:
+                lines.append(
+                    f"\nDirect commands ({', '.join(dc)}) can be "
+                    f"loaded individually via usage."
+                )
+            return "\n".join(lines)
+
         entries = group_tools(all_tools, group)
         if not entries:
             available = group_names(cli)
@@ -249,14 +327,22 @@ def create_server() -> FastMCP:
                 await ctx.session.send_tool_list_changed()
             return f"Unloaded all focused tools ({removed} total)."
 
-        if group not in focused:
+        # Try exact key first, then normalized form for subgroup paths
+        key = group if group in focused else None
+        if key is None:
+            norm = group.replace(" ", "_").replace("-", "_")
+            for k in focused:
+                if k.replace(" ", "_").replace("-", "_") == norm:
+                    key = k
+                    break
+        if key is None:
             return f"Group '{group}' is not focused."
-        for n in focused[group]:
+        for n in focused[key]:
             try:
                 mcp.remove_tool(n)
             except Exception:  # noqa: BLE001, S110
                 pass
-        count = len(focused.pop(group))
+        count = len(focused.pop(key))
         if ctx is not None:
             await ctx.session.send_tool_list_changed()
         return f"Unloaded {count} tools for '{group}'."
@@ -276,6 +362,19 @@ def create_server() -> FastMCP:
     async def run_tool(command: str, yes: bool = False) -> str:
         """Execute a raw splunkctl command string."""
         tokens = _split_command(command)
+        # The tool's yes parameter is the only mutation switch — a --yes
+        # smuggled inside the command string must not bypass the guard.
+        # Reject rather than silently strip: after shlex a quoted option
+        # VALUE of '-y' is indistinguishable from the flag, and eating
+        # it would shift arguments or corrupt the value.
+        if any(t in ("--yes", "-y") for t in tokens):
+            return (
+                "Error: '--yes'/'-y' is not accepted inside the command "
+                "string — the tool's yes parameter is the only mutation "
+                "switch. Remove it and pass yes=true to apply. If you "
+                "need the literal value '-y', use a focused typed tool "
+                "instead."
+            )
         if yes:
             tokens.append("--yes")
         result = _exec_cli(tokens)
@@ -286,9 +385,17 @@ def create_server() -> FastMCP:
         if tool_name in all_tools and not any(
             tool_name in names for names in focused.values()
         ):
+            if len(tokens) >= 2 and tokens[1] in subgroup_names(cli, tokens[0]):
+                suggestion = f'focus "{tokens[0]} {tokens[1]}"'
+            elif has_subgroups(cli, tokens[0]):
+                # Bare focus on a nested group is refused; point at usage
+                # for direct commands instead.
+                suggestion = f'usage "{" ".join(tokens[:2])}"'
+            else:
+                suggestion = f"focus {tokens[0]}"
             result += (
-                f"\n\nTip: run `focus {tokens[0]}` to load typed tools "
-                f"with validated schemas for this group."
+                f"\n\nTip: run `{suggestion}` to load a typed tool "
+                f"with a validated schema for this command."
             )
         return result