splunkctl 0.8.0__tar.gz → 0.9.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: splunkctl
-Version: 0.8.0
+Version: 0.9.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,21 @@ 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 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 +136,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 +193,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 +265,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 237 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.9.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,21 @@ 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 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 +98,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 +155,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 +227,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 237 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.9.0/splunkctl/__init__.py

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

{splunkctl-0.8.0 → splunkctl-0.9.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,12 @@ from splunkctl.mcp.tools import (
     ToolEntry,
     ToolIndex,
     build_tool_index,
+    direct_commands,
     group_names,
     group_summary,
     group_tools,
+    has_subgroups,
+    subgroup_names,
 )
 
 _INSTRUCTIONS = """\
@@ -32,7 +36,10 @@ 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"]
 
@@ -149,11 +156,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 = len(sub_cmd.commands) 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 +197,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 +230,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 +241,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 +307,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}'."

{splunkctl-0.8.0 → splunkctl-0.9.0}/splunkctl/mcp/tools.py

@@ -207,13 +207,51 @@ def group_names(root: click.Group) -> list[str]:
 
 
 def group_tools(index: ToolIndex, group: str) -> list[ToolEntry]:
-    """Return all tools under a given top-level group."""
-    prefix = group.replace("-", "_") + "_"
+    """Return all tools under a group or subgroup path.
+
+    Accepts space-separated paths (``"soar containers"``) as well as
+    plain group names (``"indexes"``).
+    """
+    prefix = group.replace(" ", "_").replace("-", "_") + "_"
     return [t for t in index.values() if t.name.startswith(prefix)]
 
 
+def subgroup_names(root: click.Group, group: str) -> list[str]:
+    """Return subgroup names within a top-level group.
+
+    For ``soar`` this yields ``["actions", "apps", "artifacts", ...]`` —
+    only the children that are themselves ``click.Group`` instances.
+    """
+    top = root.commands.get(group)
+    if not isinstance(top, click.Group):
+        return []
+    return sorted(
+        name for name, cmd in top.commands.items() if isinstance(cmd, click.Group)
+    )
+
+
+def has_subgroups(root: click.Group, group: str) -> bool:
+    """Return True if the group has nested subgroups."""
+    return bool(subgroup_names(root, group))
+
+
+def direct_commands(root: click.Group, group: str) -> list[str]:
+    """Return direct (non-group) command names under a top-level group."""
+    top = root.commands.get(group)
+    if not isinstance(top, click.Group):
+        return []
+    return sorted(
+        name for name, cmd in top.commands.items() if not isinstance(cmd, click.Group)
+    )
+
+
 def group_summary(root: click.Group) -> list[dict[str, str]]:
-    """Build a summary of command groups with descriptions and counts."""
+    """Build a summary of command groups with descriptions and counts.
+
+    Groups that contain nested subgroups (like ``soar``) include a
+    ``subgroups`` key with the two-level layout so agents can discover
+    subgroup focus paths without flooding context.
+    """
     skip = {"mcp", "commands", "skill", "config", "doctor", "info"}
     rows: list[dict[str, str]] = []
     for name, cmd in sorted(root.commands.items()):
@@ -222,12 +260,14 @@ def group_summary(root: click.Group) -> list[dict[str, str]]:
         if isinstance(cmd, click.Group):
             subs = list(cmd.commands.keys())
             desc = (cmd.help or "").split("\n")[0]
-            rows.append(
-                {
-                    "group": name,
-                    "description": desc,
-                    "subcommands": ", ".join(sorted(subs)),
-                    "count": str(len(subs)),
-                }
-            )
+            row: dict[str, str] = {
+                "group": name,
+                "description": desc,
+                "subcommands": ", ".join(sorted(subs)),
+                "count": str(len(subs)),
+            }
+            sg = subgroup_names(root, name)
+            if sg:
+                row["subgroups"] = ", ".join(sg)
+            rows.append(row)
     return rows

splunkctl-0.9.0/splunkctl/soar/cimcef.py

@@ -0,0 +1,254 @@
+"""CIM-to-CEF field mapping and row-to-artifact transform.
+
+Pure functions and data — no I/O. The ``CIM_CEF_MAP`` encodes the official
+Splunk SOAR Connector for Splunk mapping (``bytesIn`` typo fixed).
+``CEF_CONTAINS_MAP`` maps CEF keys to SOAR contains types for artifact
+actionability. ``SEVERITY_MAP`` converts Splunk severity/urgency strings
+to SOAR severity levels.
+
+Used by ``soar ingest`` (CLI) and ``soar artifacts create`` (auto cef_types).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+# ---- CIM -> CEF default map ------------------------------------------------
+# Source: github.com/splunk-soar-connectors/splunk src/splunk_consts.py
+# Fixed: upstream has ``butesIn`` typo for bytes_in -> ships as ``bytesIn``.
+
+CIM_CEF_MAP: dict[str, str] = {
+    "action": "act",
+    "action_name": "act",
+    "app": "app",
+    "bytes_in": "bytesIn",
+    "bytes_out": "bytesOut",
+    "category": "cat",
+    "dest": "destinationAddress",
+    "dest_ip": "destinationAddress",
+    "dest_mac": "destinationMacAddress",
+    "dest_nt_domain": "destinationNtDomain",
+    "dest_port": "destinationPort",
+    "dest_translated_ip": "destinationTranslatedAddress",
+    "dest_translated_port": "destinationTranslatedPort",
+    "direction": "deviceDirection",
+    "dns": "destinationDnsDomain",
+    "dvc": "dvc",
+    "dvc_ip": "deviceAddress",
+    "dvc_mac": "deviceMacAddress",
+    "file_create_time": "fileCreateTime",
+    "file_hash": "fileHash",
+    "file_modify_time": "fileModificationTime",
+    "file_name": "fileName",
+    "file_path": "filePath",
+    "file_size": "fileSize",
+    "message": "message",
+    "protocol": "transportProtocol",
+    "transport": "transportProtocol",
+    "request_payload": "request",
+    "request_payload_type": "requestMethod",
+    "src": "sourceAddress",
+    "src_dns": "sourceDnsDomain",
+    "src_ip": "sourceAddress",
+    "src_mac": "sourceMacAddress",
+    "src_nt_domain": "sourceNtDomain",
+    "src_port": "sourcePort",
+    "src_translated_ip": "sourceTranslatedAddress",
+    "src_translated_port": "sourceTranslatedPort",
+    "src_user": "sourceUserId",
+    "url": "requestURL",
+    "user": "destinationUserName",
+    "user_id": "destinationUserId",
+}
+
+# ---- CEF contains-type map (canonical) -------------------------------------
+# Maps CEF key -> list of SOAR contains types.  Imported by
+# ``splunkctl/commands/soar/artifacts.py`` for auto cef_types on create.
+
+CEF_CONTAINS_MAP: dict[str, list[str]] = {
+    "destinationAddress": ["ip", "host name"],
+    "destinationMacAddress": ["mac address"],
+    "destinationNtDomain": ["domain"],
+    "destinationPort": ["port"],
+    "destinationTranslatedAddress": ["ip"],
+    "destinationTranslatedPort": ["port"],
+    "destinationDnsDomain": ["domain"],
+    "dvc": ["ip", "host name"],
+    "deviceAddress": ["ip"],
+    "deviceMacAddress": ["mac address"],
+    "fileHash": ["hash"],
+    "fileName": ["file name"],
+    "filePath": ["file path"],
+    "sourceAddress": ["ip", "host name"],
+    "sourceDnsDomain": ["domain"],
+    "sourceMacAddress": ["mac address"],
+    "sourceNtDomain": ["domain"],
+    "sourcePort": ["port"],
+    "sourceTranslatedAddress": ["ip"],
+    "sourceTranslatedPort": ["port"],
+    "sourceUserId": ["user name"],
+    "requestURL": ["url"],
+    "destinationUserName": ["user name"],
+    "destinationUserId": ["user name"],
+}
+
+# ---- Severity map -----------------------------------------------------------
+# Check ``severity`` first, then ``urgency``; default ``medium``.
+# Multivalue -> highest wins.
+
+_SEVERITY_ORDER: dict[str, int] = {
+    "informational": 0,
+    "low": 1,
+    "medium": 2,
+    "high": 3,
+    "critical": 4,
+}
+
+_SPLUNK_TO_SOAR: dict[str, str] = {
+    "informational": "low",
+    "low": "low",
+    "medium": "medium",
+    "high": "high",
+    "critical": "high",
+}
+
+
+def map_severity(row: dict[str, Any]) -> str:
+    """Derive SOAR severity from a Splunk result row.
+
+    Checks ``severity`` first, then ``urgency``. If both are absent,
+    returns ``medium``. When the field contains multiple values
+    (comma-separated or list), the highest wins.
+    """
+    raw = row.get("severity") or row.get("urgency") or ""
+    if isinstance(raw, list):
+        values = [str(v).strip().lower() for v in raw if v]
+    else:
+        values = [v.strip().lower() for v in str(raw).split(",") if v.strip()]
+
+    if not values:
+        return "medium"
+
+    best_rank = -1
+    best_sev = "medium"
+    for v in values:
+        rank = _SEVERITY_ORDER.get(v, -1)
+        if rank > best_rank:
+            best_rank = rank
+            best_sev = _SPLUNK_TO_SOAR.get(v, "medium")
+    return best_sev
+
+
+# ---- Row -> artifact transform ----------------------------------------------
+
+
+def row_sdi(row: dict[str, Any], sdi_field: str) -> str:
+    """Compute the source_data_identifier for a result row.
+
+    If ``sdi_field`` names a field present in the row, use its value.
+    Otherwise hash the full row (SHA-256).
+    """
+    val = row.get(sdi_field)
+    if val is not None and str(val).strip():
+        return str(val).strip()
+    canonical = json.dumps(row, sort_keys=True, default=str)
+    return hashlib.sha256(canonical.encode()).hexdigest()
+
+
+def row_to_cef(
+    row: dict[str, Any],
+    *,
+    cim_map: dict[str, str] | None = None,
+    include_unmapped: bool = False,
+) -> dict[str, str]:
+    """Map a Splunk result row to a CEF dict.
+
+    Args:
+        row: Single Splunk result dict.
+        cim_map: CIM->CEF mapping; defaults to ``CIM_CEF_MAP``.
+        include_unmapped: If True, fields not in the map are passed
+            through as custom CEF keys.
+
+    Returns:
+        CEF dict suitable for ``POST /rest/artifact``.
+    """
+    effective = cim_map if cim_map is not None else CIM_CEF_MAP
+    cef: dict[str, str] = {}
+    mapped_keys: set[str] = set()
+
+    for cim_field, cef_key in effective.items():
+        val = row.get(cim_field)
+        if val is not None and str(val).strip():
+            cef[cef_key] = str(val)
+            mapped_keys.add(cim_field)
+
+    if include_unmapped:
+        skip = {"_raw", "_time", "_si", "_serial", "_sourcetype", "_indextime"}
+        for key, val in row.items():
+            if key in mapped_keys or key in skip or key.startswith("_"):
+                continue
+            if key in effective:
+                continue
+            if val is not None and str(val).strip():
+                cef[key] = str(val)
+
+    return cef
+
+
+def auto_cef_types(
+    cef: dict[str, Any],
+    *,
+    contains_map: dict[str, list[str]] | None = None,
+) -> dict[str, list[str]]:
+    """Build cef_types from the contains map for a CEF dict."""
+    effective = contains_map if contains_map is not None else CEF_CONTAINS_MAP
+    types: dict[str, list[str]] = {}
+    for key in cef:
+        if key in effective:
+            types[key] = effective[key]
+    return types
+
+
+def container_name_for_row(
+    row: dict[str, Any],
+    *,
+    template: str | None = None,
+    name_field: str | None = None,
+) -> str:
+    """Derive a container name for a result row.
+
+    Priority:
+    1. ``name_field`` — use that row field's value.
+    2. ``template`` — use as literal name.
+    3. ``rule_name`` field (ES notable convention).
+    4. Fallback ``"Splunk Log Entry on <_time>: <source>"``.
+    """
+    if name_field:
+        val = row.get(name_field)
+        if val and str(val).strip():
+            return str(val).strip()
+
+    if template:
+        return template
+
+    rule_name = row.get("rule_name") or row.get("search_name")
+    if rule_name and str(rule_name).strip():
+        return str(rule_name).strip()
+
+    _time = row.get("_time", "unknown")
+    source = row.get("source", "unknown")
+    return f"Splunk Log Entry on {_time}: {source}"
+
+
+def artifact_name_for_row(row: dict[str, Any]) -> str:
+    """Derive an artifact name for a result row.
+
+    Uses ``search_name`` if present, else ``"Field Values"``
+    (connector convention).
+    """
+    name = row.get("search_name")
+    if name and str(name).strip():
+        return str(name).strip()
+    return "Field Values"

{splunkctl-0.8.0 → splunkctl-0.9.0}/splunkctl/soar/client.py

@@ -269,11 +269,13 @@ class SOARClient:
         if not isinstance(body, dict):
             return body
 
-        # {results} envelope (search)
+        # {results} envelope (search) — server paginates (1-based pages)
+        # and returns real num_pages; forward it instead of hardcoding 1.
         if endpoint_root in _RESULTS_ENVELOPE_ENDPOINTS and "results" in body:
             results = body["results"]
             count = body.get("count", len(results))
-            return {"count": count, "num_pages": 1, "data": results}
+            num_pages = body.get("num_pages", 1)
+            return {"count": count, "num_pages": num_pages, "data": results}
 
         return body
 
@@ -368,8 +370,14 @@ class SOARClient:
 
         Yields individual items from each page, transparently fetching
         subsequent pages as needed.
+
+        Pagination origin varies by endpoint:
+        - ``search`` (``_RESULTS_ENVELOPE_ENDPOINTS``): 1-based pages.
+        - All other endpoints: 0-based pages.
         """
-        page = 0
+        endpoint_root = path.lstrip("/").split("/")[0]
+        origin = 1 if endpoint_root in _RESULTS_ENVELOPE_ENDPOINTS else 0
+        page = origin
         while True:
             page_params = dict(params or {})
             page_params["page"] = page
@@ -381,5 +389,5 @@ class SOARClient:
 
             num_pages = result.get("num_pages", 1)
             page += 1
-            if page >= num_pages or not data:
+            if page - origin >= num_pages or not data:
                 break

{splunkctl-0.8.0 → splunkctl-0.9.0}/splunkctl.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: splunkctl
-Version: 0.8.0
+Version: 0.9.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,21 @@ 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 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 +136,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 +193,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 +265,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 237 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.9.0}/splunkctl.egg-info/SOURCES.txt

@@ -56,6 +56,7 @@ splunkctl/mcp/resources.py
 splunkctl/mcp/server.py
 splunkctl/mcp/tools.py
 splunkctl/soar/__init__.py
+splunkctl/soar/cimcef.py
 splunkctl/soar/client.py
 tests/test_client.py
 tests/test_config.py

{splunkctl-0.8.0 → splunkctl-0.9.0}/tests/test_version.py

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

splunkctl-0.8.0/splunkctl/__init__.py

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