splunkctl 0.11.2__tar.gz → 0.13.0__tar.gz

{splunkctl-0.11.2 → splunkctl-0.13.0}/MANIFEST.in

@@ -3,3 +3,4 @@ prune docs
 prune samples
 prune scripts
 prune installers
+graft docs/guides

{splunkctl-0.11.2/splunkctl.egg-info → splunkctl-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: splunkctl
-Version: 0.11.2
+Version: 0.13.0
 Summary: Open-source MCP server and CLI for Splunk Enterprise SIEM and Splunk SOAR.
 Author: dannyota
 License-Expression: Apache-2.0
@@ -27,7 +27,7 @@ Requires-Dist: pyyaml>=6.0
 Requires-Dist: tabulate>=0.9
 Requires-Dist: requests>=2.32
 Requires-Dist: defusedxml>=0.7
-Requires-Dist: mcp<2,>=1.28.1
+Requires-Dist: mcp<3,>=2
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: ruff>=0.6; extra == "dev"
@@ -36,6 +36,8 @@ Requires-Dist: types-requests; extra == "dev"
 Requires-Dist: types-PyYAML; extra == "dev"
 Requires-Dist: types-tabulate; extra == "dev"
 Requires-Dist: types-defusedxml; extra == "dev"
+Provides-Extra: browser
+Requires-Dist: playwright>=1.45; extra == "browser"
 Dynamic: license-file
 
 <div align="center">
@@ -114,6 +116,7 @@ splunkctl rules disable 'My Rule'
 # Add and verify Splunk SOAR when needed
 splunkctl config init --soar
 splunkctl soar test
+splunkctl auth login --target siem             # browser SAML/MFA login
 splunkctl soar containers list
 ```
 
@@ -192,6 +195,7 @@ streamable HTTP configuration.
 |---|---|
 | `doctor` | Check connection, authentication, health, and permissions |
 | `config` | Configure profiles and test connectivity |
+| `auth` | Browser SAML login, session status, and logout |
 | `info` | Show server version, operating system, and license details |
 | `search` | Run, export, upload, and manage search jobs |
 | `rules` | Manage detection rules and YAML import/export |

{splunkctl-0.11.2 → splunkctl-0.13.0}/README.md

@@ -74,6 +74,7 @@ splunkctl rules disable 'My Rule'
 # Add and verify Splunk SOAR when needed
 splunkctl config init --soar
 splunkctl soar test
+splunkctl auth login --target siem             # browser SAML/MFA login
 splunkctl soar containers list
 ```
 
@@ -152,6 +153,7 @@ streamable HTTP configuration.
 |---|---|
 | `doctor` | Check connection, authentication, health, and permissions |
 | `config` | Configure profiles and test connectivity |
+| `auth` | Browser SAML login, session status, and logout |
 | `info` | Show server version, operating system, and license details |
 | `search` | Run, export, upload, and manage search jobs |
 | `rules` | Manage detection rules and YAML import/export |

splunkctl-0.13.0/docs/guides/alerts.md

@@ -0,0 +1,79 @@
+# Alerts
+
+Fired alerts are the SOC's incoming work queue. During an incident, you
+need to see what triggered, when, and at what severity. During planned
+maintenance, you need to suppress noisy rules before they flood the
+on-call channel. After the fact, auditors ask which alerts fired and
+which were suppressed. These commands cover all three workflows.
+
+## Commands
+
+```bash
+splunkctl alerts list                         # list fired alerts
+splunkctl alerts get 'Alert Name'             # details for one alert group
+splunkctl alerts actions                      # list alert action types
+splunkctl alerts suppress 'Alert Name' \
+    --duration 7200 --yes                     # suppress for 2 hours
+```
+
+## Triage during an incident
+
+List all currently fired alerts to see what the environment is telling you.
+Output includes name, trigger count, triggered time, and severity.
+
+```bash
+splunkctl alerts list
+splunkctl alerts get 'Brute Force Login Attempts'
+```
+
+## Check alert action types
+
+See which action types (email, webhook, script, etc.) are configured on
+the instance. Useful before creating or modifying saved searches that
+fire alerts.
+
+```bash
+splunkctl alerts actions
+```
+
+## Suppress during a maintenance window
+
+Suppression is guarded -- dry-run by default. The first command below
+previews the change; the second applies it. Duration is in seconds.
+
+```bash
+splunkctl alerts suppress 'Brute Force Login Attempts' --duration 7200
+splunkctl alerts suppress 'Brute Force Login Attempts' --duration 7200 --yes
+```
+
+Suppress multiple alerts in a loop during a planned outage:
+
+```bash
+for rule in 'Brute Force Login Attempts' 'Failed VPN Auth' 'DNS Exfil'; do
+  splunkctl alerts suppress "$rule" --duration 14400 --yes
+done
+```
+
+## JSON output for scripts and agents
+
+Pass `--json` to get structured output suitable for piping into `jq`,
+feeding into an LLM agent, or storing as audit evidence.
+
+```bash
+splunkctl alerts list --json                          # all fired alerts
+splunkctl alerts list --json | jq '.[] | select(.severity >= 6)'
+splunkctl alerts get 'Brute Force Login Attempts' --json > alert_detail.json
+```
+
+An LLM agent can consume the JSON directly to decide next steps --
+for example, correlating fired alerts with a change window calendar
+or auto-filing tickets for high-severity triggers.
+
+## Options
+
+| Flag | Applies to | Description |
+|------|-----------|-------------|
+| `--duration` | `suppress` | Suppression length in seconds (default 3600) |
+| `--json` | all | Force JSON output regardless of TTY |
+| `--format` | all | Output format: `table`, `json`, `csv`, `jsonl` |
+| `--yes` | `suppress` | Apply the mutation (skip dry-run preview) |

splunkctl-0.13.0/docs/guides/apps.md

@@ -0,0 +1,65 @@
+# Apps
+
+Splunk's detection and enrichment capabilities live in apps --
+Technology Add-ons (TAs) for data normalization, security content packs
+like Splunk Enterprise Security, and custom apps with org-specific
+detections. Managing these remotely lets you deploy, update, and audit
+apps across instances without SSH or manual Web UI clicks.
+
+## Commands
+
+```bash
+splunkctl apps list                           # list installed apps
+splunkctl apps get SplunkForwarder            # get app details
+splunkctl apps install --path ./app.spl --yes # install from local file
+splunkctl apps install --path ./app.tar.gz \
+    --force --yes                             # force overwrite
+splunkctl apps uninstall my_app --yes         # uninstall
+splunkctl apps update my_app --enabled \
+    --visible --yes                           # enable + show
+splunkctl apps update my_app --disabled \
+    --hidden --yes                            # disable + hide
+splunkctl apps reload --yes                   # reload all apps
+```
+
+## Remote install
+
+`apps install --path` uploads a local `.spl` or `.tar.gz` package to
+the remote Splunk instance via the Web UI handler. No SSH, no SCP, no
+server filesystem access needed -- push from your laptop to any
+reachable instance.
+
+Use `--force` to overwrite an existing app of the same name.
+
+## Practical examples
+
+```bash
+# Deploy a TA for Windows event log normalization
+splunkctl apps install \
+    --path ./Splunk_TA_windows-8.9.0.spl --yes
+
+# Upgrade a security content pack (force overwrite)
+splunkctl apps install \
+    --path ./DA-ESS-ContentUpdate-4.29.0.spl --force --yes
+
+# Disable an app during an incident (stop its scheduled searches)
+splunkctl apps update SplunkEnterpriseSecuritySuite \
+    --disabled --yes
+
+# Re-enable after the incident
+splunkctl apps update SplunkEnterpriseSecuritySuite \
+    --enabled --yes
+
+# Audit installed apps -- pipe JSON to jq for scripting
+splunkctl apps list --json | jq '.[] | {name, version, disabled}'
+
+# Reload all app configs after a bulk change
+splunkctl apps reload --yes
+```
+
+## Notes
+
+- App install may require a Splunk restart to activate new modular
+  inputs or scripted lookups. The CLI does not restart automatically.
+- `--force` is required when reinstalling or upgrading an app that
+  already exists on the instance.

splunkctl-0.13.0/docs/guides/audit.md

@@ -0,0 +1,125 @@
+# Change audit & RBAC attestation
+
+Regulator-facing evidence for bank SOC operations: who changed what
+(`audit changes`) and who can do what (`audit rbac`). Both commands are
+**read-only** — no `guard`, no `--yes` needed.
+
+## Why this matters
+
+Banks carry regulator obligations for change-management evidence ("who
+changed this saved search / role / index, and when") and periodic access
+recertification ("who has which capabilities, and why"). Today an agent
+would have to hand-write `index=_audit` SPL and know that Splunk mixes
+**two incompatible event shapes** in that one index — this group
+normalizes both into one schema and joins the RBAC graph so neither
+requires bespoke SPL per engagement.
+
+## Commands
+
+```bash
+splunkctl audit changes                                   # last 24h, up to 500
+splunkctl audit changes --since -7d --until -1d            # explicit window
+splunkctl audit changes --user jdoe                        # exact-match user
+splunkctl audit changes --action edit                      # substring-match action
+splunkctl audit changes --object-type saved_search          # exact-match object type
+splunkctl audit changes --limit 2000 --json                # raise the display cap
+
+splunkctl audit rbac                                        # one row per user
+splunkctl audit rbac --format csv --out recert-2026-07.csv  # recertification export
+splunkctl audit rbac --roles-only                            # one row per role
+```
+
+## `audit changes`: normalized schema
+
+Every row has exactly six keys, in this order: `time`, `user`, `action`,
+`object`, `object_type`, `app`. Splunk's `_audit` index mixes two
+sourcetypes and this command normalizes both:
+
+| Sourcetype | Shape | Mapping |
+|---|---|---|
+| `audittrail` (legacy) | `Audit:[timestamp=..., user=..., action=..., <tail>]` plain text | `user`/`action` parsed directly; `object` only when the line carries a literal `object="..."` marker (common on capability checks like `edit_user`/`edit_roles`); `object_type` is always empty — the legacy format has no per-action type field; `app` from `app="..."` or unquoted `app=...`, when present |
+| `audittrailv2` (structured) | one JSON object per line | `user` = `actor.name`; `action` = top-level `action`; `object` = `data.name`; `object_type` = `data.type`; `app` = `data.ownership.app` or `data.attributes.app` |
+
+`time` always comes from Splunk's own indexed `_time` (not a re-parse of
+either embedded timestamp format) — it's present on every event
+regardless of shape and gives one consistent, sortable value.
+
+There is no literal `data.object`/`data.object_type` key on real
+`audittrailv2` events; `data.name`/`data.type` are the nearest
+equivalents and confirmed present for object/system-category events
+(config changes). Action/authn/check-category events (ad-hoc searches,
+logins, capability grants) carry `data.type` sometimes but rarely
+`data.name` — `object` stays empty for those, which is correct: they
+aren't changes to a named object.
+
+An event matching neither shape is **never dropped** — it comes back as
+`action: "unparsed"` with the full raw line in `object`, so evidence
+stays complete even for audit-log formats this parser doesn't yet know.
+
+## `audit changes`: SPL safety
+
+The dispatched search is always the constant `search index=_audit` —
+nothing else, ever. `--since`/`--until` go through the oneshot job's
+`earliest_time`/`latest_time` kwargs (not string-composed), and
+`--user`/`--action`/`--object-type` filter the already-normalized rows
+**client-side**, after the fetch. No flag value — however adversarial —
+reaches the SPL string. Verified live with `--debug`:
+
+```bash
+$ splunkctl --debug audit changes --user 'x" | delete' --action 'y | outputlookup evil.csv'
+...
+POST .../search/v2/jobs/ (body: {'search': 'search index=_audit', ...})
+```
+
+`--limit` (default 500) applies **after** filtering, not to the raw
+fetch — the raw fetch itself is unbounded (`count=0`) within the
+`--since`/`--until` window, so a `--user`/`--action` filter never misses
+a match just because it fell outside an arbitrary raw-fetch cutoff.
+A very wide `--since` over a large `_audit` index may fetch all events in that range before limiting, which can be slow; narrow `--since` when possible.
+`--user`/`--object-type` are case-insensitive exact match; `--action` is case-insensitive substring match.
+
+## `audit rbac`: aggregation
+
+One row per user by default: `user`, `email`, `roles` (direct roles,
+semicolon-joined), `capabilities`, `srch_indexes_allowed`. The last two
+are aggregated across the user's direct roles **and the full transitive
+closure of their imported roles** — deduplicated, sorted, and
+semicolon-joined. `--roles-only` flips to one row per role instead:
+`role`, `imported_roles` (direct only), `capabilities`,
+`srch_indexes_allowed` (both aggregated the same transitive way, rooted
+at that role).
+
+Example: role `soc_analyst` imports `power`, which imports `user`. A
+`soc_analyst` user's effective `capabilities` is the union of all three
+roles' own capabilities — this is what a role with zero capabilities of
+its own (e.g. Splunk's built-in `splunk-system-role`, which only imports
+`admin`) needs to show its real effective grant, not an empty cell.
+
+## CSV round-trip safety
+
+Multi-value fields (`roles`, `capabilities`, `srch_indexes_allowed`,
+`imported_roles`) join with `;`, never `\n` — Splunk role/capability/index
+names can't contain a semicolon, so this is a safe, lossless join that
+never produces an embedded newline inside a CSV cell. `--format csv`
+output round-trips cleanly through Python's `csv` module.
+
+## Options
+
+| Flag | Applies to | Description |
+|------|-----------|--------------|
+| `--since` | `changes` | Earliest time (default `-24h`) |
+| `--until` | `changes` | Latest time (default `now`) |
+| `--user` | `changes` | Filter by user, case-insensitive exact match |
+| `--action` | `changes` | Filter by action, case-insensitive substring match |
+| `--object-type` | `changes` | Filter by object type, case-insensitive exact match |
+| `--limit` | `changes` | Max results after client-side filtering (default 500) |
+| `--roles-only` | `rbac` | One row per role instead of per user |
+
+## Implementation notes
+
+`changes` runs over the existing oneshot-search infrastructure
+(`svc.jobs.oneshot`); the event-shape parsers live in a sibling module,
+`splunkctl/commands/audit_parse.py`, kept separate from the click
+commands since they're pure functions with their own fixture-driven test
+suite. `rbac` is SDK reads only (`svc.roles`, `svc.users`) — no oneshot
+search involved.

splunkctl-0.13.0/docs/guides/auth.md

@@ -0,0 +1,61 @@
+# Browser SAML authentication
+
+splunkctl can complete Splunk SAML single sign-on (including a second factor)
+in a headed Chromium window and then reuse the resulting product session until
+it expires. The browser handles the identity provider; splunkctl never reads or
+stores TOTP secrets or codes.
+
+## How it works
+
+1. `splunkctl config init` probes the public login route. When it sees a
+   redirect to an external identity provider, it records `auth_mode: browser`
+   and stores the product `web_url`.
+2. `splunkctl auth login --target <siem|soar>` opens Chromium at the product
+   login route. You complete the IdP prompts, including any TOTP code.
+3. splunkctl extracts only the product session (Splunk `splunkd_<port>` cookie,
+   or SOAR `sessionid` + `csrftoken`) and proves it against the product API.
+4. Normal commands reuse the cached session whenever the active profile selects
+   browser mode. A missing or expired session never opens a browser; the command
+   prints the exact login instruction instead.
+
+## Commands
+
+```text
+splunkctl auth login --target siem
+splunkctl auth login --target soar
+splunkctl auth status [--target siem|soar|both]
+splunkctl auth logout [--target siem|soar|both]
+```
+
+`login` requires exactly one target; two back-to-back browser flows are easy to
+confuse. `status` reports `missing`, `valid`, `expired`, or `unreachable`.
+`logout` always removes the local session, even if the remote endpoint refuses.
+
+## Optional dependency
+
+Browser login needs Playwright and Chromium:
+
+```bash
+pip install 'splunkctl[browser]'
+python -m playwright install chromium
+```
+
+Configuration still succeeds without them. `splunkctl auth login` prints the
+exact commands when they are missing.
+
+## Session storage and security
+
+Sessions are stored under `~/.splunkctl/sessions/<profile>/<target>.json` with
+directory mode `0700` and file mode `0600`. A record holds only the target,
+profile, product origin, product session values, and validation timestamps. It
+never stores passwords, Playwright storage state, identity-provider cookies, or
+TOTP secrets. Session values are redacted from all output.
+
+## What is and is not supported
+
+Supported: SAML browser login for SIEM and SOAR, one target per login, session
+status and logout, automatic SAML detection, and a reusable Keycloak lab.
+
+Not supported in this release: reading or storing TOTP secrets, native Splunk
+Duo or RSA flows, OpenID Connect or OAuth, logging in to both products in one
+command, and a local splunkctl callback redirect.

splunkctl-0.13.0/docs/guides/conf.md

@@ -0,0 +1,84 @@
+# Conf
+
+Generic conf file/stanza editor over the REST `confs` API — the escape
+hatch for any Splunk conf file that doesn't have a dedicated command
+group yet: `macros`, `eventtypes`, `tags`, `limits`, `authorize`,
+`server`, `web`, and everything else under `$SPLUNK_HOME/etc/*/local`.
+
+## Why this matters
+
+Detections depend on more than saved searches: macros expand reusable
+SPL fragments, eventtypes classify events, tags drive CIM compliance,
+and calculated fields live in `props.conf` alongside sourcetypes.
+`parsers` only reaches `props.conf`/`transforms.conf`; `conf` reaches
+every other conf file the same way, so nothing detection-relevant is
+locked out of code review or CI.
+
+There is **no blocklist** — `conf` can edit `authorize.conf`,
+`server.conf`, and `web.conf` just as readily as `macros.conf`. The
+dry-run guard and `--yes` are the only safety net: every `set`/`unset`/
+`reload` preview names the exact file and stanza before it touches
+anything, so review the preview before applying to a sensitive file.
+
+## Commands
+
+```bash
+splunkctl conf files                          # list conf files
+splunkctl conf list macros                    # list stanzas in macros.conf
+splunkctl conf list macros --app my_app       # scope to one app's stanzas
+splunkctl conf get macros my_macro            # full stanza config
+splunkctl conf get macros my_macro --key definition  # one key
+splunkctl conf set macros my_macro \
+    definition='index=main' --yes             # create/update keys
+splunkctl conf unset macros my_macro definition --yes  # clear a key
+splunkctl conf reload macros --yes            # reload the conf file
+```
+
+## Recipes
+
+### Add a macro
+
+Create a macro and verify it before rollout:
+
+```bash
+splunkctl conf set macros my_macro \
+    definition='index=main sourcetype=syslog' --yes
+splunkctl conf get macros my_macro
+```
+
+### Audit an eventtype
+
+```bash
+splunkctl conf get eventtypes authentication --json | jq .
+```
+
+### Review a stanza change before applying
+
+`conf set` always previews a field-level diff — old value on the left,
+new value on the right, `add` for a brand-new key:
+
+```bash
+splunkctl conf set macros my_macro definition='index=main'
+# [DRY RUN] ...
+#   definition: index=old -> index=main
+```
+
+### List conf files to find the right one
+
+```bash
+splunkctl conf files --filter tag
+```
+
+## Tips
+
+- `conf set` creates the stanza if it doesn't exist yet — there's no
+  separate create step.
+- The REST API has no true per-key delete; `conf unset` sets keys to
+  the empty string (same mechanism `parsers unset` uses). To fully
+  remove a stanza, use the dedicated command group for that conf file
+  when one exists (e.g. `parsers delete` for `props.conf`).
+- `--app` on `conf list`/`conf files` matters: the unscoped default
+  view can miss app-private stanzas, same as `rules list`/`dashboards
+  list`.
+- Reload the conf file after a `set`/`unset` if the change needs to
+  take effect immediately (`conf reload <file> --yes`).

splunkctl-0.13.0/docs/guides/configure.md

@@ -0,0 +1,120 @@
+# Configure
+
+## Interactive setup
+
+```bash
+splunkctl config init
+```
+
+Prompts for host, port, auth method (token or username/password), tests the
+connection, and writes `~/.splunkctl/config.yaml` with `0600` permissions.
+
+## Config file
+
+Location: `~/.splunkctl/config.yaml`
+
+```yaml
+host: "localhost"
+port: 8089
+scheme: "https"
+username: "admin"
+password: ""            # optional, can use token instead
+token: ""               # bearer token (preferred)
+verify: true            # TLS cert verification (default: on)
+app: "search"           # default app context
+owner: "nobody"         # default owner context
+```
+
+**TLS verification is on by default.** Production instances with valid
+certificates work out of the box. For lab/dev instances with self-signed
+certs, set `verify: false` explicitly in the profile — `config init` asks
+during setup (default: yes).
+
+## Profiles (dev/UAT/prod)
+
+For more than one Splunk instance, add a `profiles:` map and a `current:`
+pointer instead of the flat keys above:
+
+```yaml
+profiles:
+  dev:
+    host: "dev.splunk.internal"
+    username: "admin"
+    password: "devpass"
+  uat:
+    host: "uat.splunk.internal"
+    token: "..."
+  prod:
+    host: "prod.splunk.internal"
+    token: "..."
+current: "uat"           # active profile when nothing else selects one
+```
+
+```bash
+splunkctl config init --profile uat ...   # create/update one named profile
+splunkctl config use uat                  # point 'current' at it (no connectivity test)
+splunkctl config show                     # active profile (redacted) + other names
+splunkctl config show --profile prod      # show a specific profile without switching
+splunkctl --profile prod rules list       # override for a single invocation
+```
+
+**Selection precedence**: `--profile <name>` global flag > `current:`
+pointer > `default`.
+
+**Legacy files keep working.** A plain flat file (no `profiles:` key) is
+treated as an implicit profile named `default` — nothing to migrate. Bare
+`config init` writes that flat shape — unless the destination file already
+has a `profiles:` key, in which case it folds the new values into
+`profiles.default` instead, leaving sibling profiles and `current`
+untouched (bare `config init` never clobbers an existing multi-profile
+file). The first time you run `config init --profile <name>` against a
+legacy file, it's upgraded to the `profiles:` schema in place: the old flat
+keys move under `profiles.default`, the new named profile is added
+alongside it, and file permissions stay `0600`.
+
+**Guard banner.** Every dry-run preview and `--yes` confirmation prints
+which instance is about to be mutated —
+`[DRY RUN] ... (profile: uat @ uat.splunk.internal:8089)` — so switching
+between dev/UAT/prod never happens silently. The banner is built from local
+config only; it never opens a connection.
+
+## Environment variables
+
+| Variable | Maps to |
+|---|---|
+| `SPLUNK_HOST` | `host` |
+| `SPLUNK_PORT` | `port` |
+| `SPLUNK_TOKEN` | `token` |
+| `SPLUNK_USER` | `username` |
+| `SPLUNK_PASS` | `password` |
+
+Env vars override fields of whichever profile is selected — same as they
+override the flat config today.
+
+## Resolution priority
+
+1. CLI flags (`--host`, `--port`, `--token`)
+2. Environment variables
+3. Profile (config file)
+
+## Watch mode
+
+Re-run any read-only command at a fixed interval, clearing the screen
+between runs (like `watch(1)` on Linux). Errors are printed in place and
+the loop continues. Press Ctrl-C to stop.
+
+```bash
+splunkctl --watch 5 indexes list        # refresh every 5 seconds
+splunkctl --watch 10 server health      # poll server health
+splunkctl --watch 3 rules list --filter brute   # filtered view
+```
+
+Requires an interactive terminal (TTY). Mutation commands (those guarded
+by `--yes`) are rejected.
+
+## Verify
+
+```bash
+splunkctl config show    # display config (secrets redacted)
+splunkctl config test    # test connectivity + auth
+```

splunkctl-0.13.0/docs/guides/dashboards.md

@@ -0,0 +1,17 @@
+# Dashboards
+
+## Commands
+
+```bash
+splunkctl dashboards list                 # list dashboards
+splunkctl dashboards list --app search    # filter by app
+splunkctl dashboards get <name>           # get definition (XML)
+splunkctl dashboards create --name new_dash --file dash.xml \
+    --app search --yes
+splunkctl dashboards update <name> --file updated.xml \
+    --app search --yes
+splunkctl dashboards delete <name> --app search --yes
+splunkctl dashboards export <name> --out dash.xml
+```
+
+Uses the `Dashboard`/`Dashboards` entity classes from the SDK fork.