splunkctl 0.13.0__tar.gz → 0.15.0__tar.gz

splunkctl-0.15.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: splunkctl
+Version: 0.15.0
+Summary: Open-source MCP server and CLI for Splunk Enterprise SIEM and Splunk SOAR.
+Author: dannyota
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/dannyota/splunkctl
+Project-URL: Documentation, https://splunkctl.danny.vn
+Project-URL: Repository, https://github.com/dannyota/splunkctl
+Project-URL: Issues, https://github.com/dannyota/splunkctl/issues
+Project-URL: Changelog, https://github.com/dannyota/splunkctl/blob/master/CHANGELOG.md
+Keywords: splunk,mcp,model-context-protocol,siem,soar,security,cli,detection,spl
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: splunk-sdk>=2.0
+Requires-Dist: click>=8.2
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: tabulate>=0.9
+Requires-Dist: requests>=2.32
+Requires-Dist: defusedxml>=0.7
+Requires-Dist: mcp<3,>=2.3
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
+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
+
+# splunkctl
+
+<a href="https://splunkctl.danny.vn"><img src="https://raw.githubusercontent.com/dannyota/splunkctl/master/docs/assets/banner.svg" alt="splunkctl: CLI and MCP server for Splunk Enterprise, Enterprise Security, and SOAR" width="600"></a>
+
+Operate Splunk Enterprise, Enterprise Security, and Splunk SOAR from a terminal, or give an AI agent the same commands through MCP.
+
+Requires Python 3.12+ and credentials for your Splunk instance.
+
+## Quickstart
+
+```bash
+python -m pip install splunkctl
+splunkctl config init
+splunkctl doctor
+```
+
+[Documentation](https://splunkctl.danny.vn) · [Installation requirements](https://splunkctl.danny.vn/#/guides/install)
+
+## Tasks
+
+- Investigate: run SPL, read fired alerts, and triage Enterprise Security notables. [Search](https://splunkctl.danny.vn/#/guides/search), [Triage notables](https://splunkctl.danny.vn/#/guides/es)
+- Deploy detections: export saved searches to YAML, review the diff, and import them on another instance. [Manage detection rules](https://splunkctl.danny.vn/#/guides/rules)
+- Respond with SOAR: work containers, artifacts, vault files, notes, and playbook runs. [Work SOAR incidents](https://splunkctl.danny.vn/#/guides/soar-incidents)
+- Review configuration drift: pull live state, diff it against version control, and push approved changes with a change report. [Manage configuration as code](https://splunkctl.danny.vn/#/guides/state)
+
+## Safety
+
+Every command that changes a remote Splunk or SOAR instance is guarded. Without `--yes` it prints a preview and exits without changing anything; some previews read the current state first to show a diff. The preview names the target host, and the active profile for Splunk Enterprise, so a change aimed at production is visible before it happens:
+
+```text
+$ splunkctl --profile uat rules delete 'My Rule'
+[DRY RUN] Delete saved search 'My Rule' (profile: uat @ uat.splunk.internal:8089)
+Pass --yes to apply.
+```
+
+Add `--yes` to apply. `splunkctl state push --report FILE` writes a change report with the before and after state for each object, which you can attach to a change ticket.
+
+Local configuration writes are not guarded: `splunkctl config init`, `splunkctl config use`, `splunkctl auth login`, and `splunkctl mcp install` write to your own machine immediately.
+
+## Agent access
+
+The MCP server exposes the command tree to Claude Code, Claude Desktop, Cursor, or any other MCP client. Setup, transports, and the progressive tool-loading model are in the [MCP guide](https://splunkctl.danny.vn/#/guides/mcp).
+
+```bash
+splunkctl mcp install           # register the server in ./.mcp.json
+splunkctl commands --json       # machine-readable command tree
+```
+
+Guarded tools keep the same contract as the CLI: a call previews until the agent passes `yes=true` explicitly.
+
+## Requirements and limitations
+
+- Python 3.12 or newer.
+- A Splunk account with REST API access on port 8089 (or your configured port). Each command needs the Splunk capability or SOAR permission its action requires; `splunkctl doctor` reports which checks pass for the active profile.
+- Enterprise Security commands (`splunkctl es ...`) check for the `SplunkEnterpriseSecuritySuite` app and exit 1 with a `not_found` error when it is not installed.
+- Browser SAML login needs the `browser` extra: `python -m pip install 'splunkctl[browser]'`.
+
+## Project and support
+
+splunkctl is an independent community project. It is not affiliated with or endorsed by Splunk Inc.
+
+Splunk Inc. publishes an unrelated Go CLI with the same executable name, [`splunk/splunkctl`](https://github.com/splunk/splunkctl). This package also installs `splunkctl-py` and leaves a Splunk-format config file untouched, so both tools can be installed together; see [Relationship to Splunk's splunkctl](https://splunkctl.danny.vn/#/guides/splunk-cli).
+
+- [Releases](https://github.com/dannyota/splunkctl/releases) and [changelog](https://github.com/dannyota/splunkctl/blob/master/CHANGELOG.md)
+- [Issues](https://github.com/dannyota/splunkctl/issues) for bugs and feature requests; see [SECURITY.md](SECURITY.md) for vulnerabilities
+- [CONTRIBUTING.md](CONTRIBUTING.md) for development setup
+- License: [Apache-2.0](https://github.com/dannyota/splunkctl/blob/master/LICENSE)

splunkctl-0.15.0/README.md

@@ -0,0 +1,67 @@
+# splunkctl
+
+<a href="https://splunkctl.danny.vn"><img src="https://raw.githubusercontent.com/dannyota/splunkctl/master/docs/assets/banner.svg" alt="splunkctl: CLI and MCP server for Splunk Enterprise, Enterprise Security, and SOAR" width="600"></a>
+
+Operate Splunk Enterprise, Enterprise Security, and Splunk SOAR from a terminal, or give an AI agent the same commands through MCP.
+
+Requires Python 3.12+ and credentials for your Splunk instance.
+
+## Quickstart
+
+```bash
+python -m pip install splunkctl
+splunkctl config init
+splunkctl doctor
+```
+
+[Documentation](https://splunkctl.danny.vn) · [Installation requirements](https://splunkctl.danny.vn/#/guides/install)
+
+## Tasks
+
+- Investigate: run SPL, read fired alerts, and triage Enterprise Security notables. [Search](https://splunkctl.danny.vn/#/guides/search), [Triage notables](https://splunkctl.danny.vn/#/guides/es)
+- Deploy detections: export saved searches to YAML, review the diff, and import them on another instance. [Manage detection rules](https://splunkctl.danny.vn/#/guides/rules)
+- Respond with SOAR: work containers, artifacts, vault files, notes, and playbook runs. [Work SOAR incidents](https://splunkctl.danny.vn/#/guides/soar-incidents)
+- Review configuration drift: pull live state, diff it against version control, and push approved changes with a change report. [Manage configuration as code](https://splunkctl.danny.vn/#/guides/state)
+
+## Safety
+
+Every command that changes a remote Splunk or SOAR instance is guarded. Without `--yes` it prints a preview and exits without changing anything; some previews read the current state first to show a diff. The preview names the target host, and the active profile for Splunk Enterprise, so a change aimed at production is visible before it happens:
+
+```text
+$ splunkctl --profile uat rules delete 'My Rule'
+[DRY RUN] Delete saved search 'My Rule' (profile: uat @ uat.splunk.internal:8089)
+Pass --yes to apply.
+```
+
+Add `--yes` to apply. `splunkctl state push --report FILE` writes a change report with the before and after state for each object, which you can attach to a change ticket.
+
+Local configuration writes are not guarded: `splunkctl config init`, `splunkctl config use`, `splunkctl auth login`, and `splunkctl mcp install` write to your own machine immediately.
+
+## Agent access
+
+The MCP server exposes the command tree to Claude Code, Claude Desktop, Cursor, or any other MCP client. Setup, transports, and the progressive tool-loading model are in the [MCP guide](https://splunkctl.danny.vn/#/guides/mcp).
+
+```bash
+splunkctl mcp install           # register the server in ./.mcp.json
+splunkctl commands --json       # machine-readable command tree
+```
+
+Guarded tools keep the same contract as the CLI: a call previews until the agent passes `yes=true` explicitly.
+
+## Requirements and limitations
+
+- Python 3.12 or newer.
+- A Splunk account with REST API access on port 8089 (or your configured port). Each command needs the Splunk capability or SOAR permission its action requires; `splunkctl doctor` reports which checks pass for the active profile.
+- Enterprise Security commands (`splunkctl es ...`) check for the `SplunkEnterpriseSecuritySuite` app and exit 1 with a `not_found` error when it is not installed.
+- Browser SAML login needs the `browser` extra: `python -m pip install 'splunkctl[browser]'`.
+
+## Project and support
+
+splunkctl is an independent community project. It is not affiliated with or endorsed by Splunk Inc.
+
+Splunk Inc. publishes an unrelated Go CLI with the same executable name, [`splunk/splunkctl`](https://github.com/splunk/splunkctl). This package also installs `splunkctl-py` and leaves a Splunk-format config file untouched, so both tools can be installed together; see [Relationship to Splunk's splunkctl](https://splunkctl.danny.vn/#/guides/splunk-cli).
+
+- [Releases](https://github.com/dannyota/splunkctl/releases) and [changelog](https://github.com/dannyota/splunkctl/blob/master/CHANGELOG.md)
+- [Issues](https://github.com/dannyota/splunkctl/issues) for bugs and feature requests; see [SECURITY.md](SECURITY.md) for vulnerabilities
+- [CONTRIBUTING.md](CONTRIBUTING.md) for development setup
+- License: [Apache-2.0](https://github.com/dannyota/splunkctl/blob/master/LICENSE)

splunkctl-0.15.0/docs/guides/alerts.md

@@ -0,0 +1,98 @@
+<!-- summary: Review fired alerts, inspect alert actions, and manage alert suppression on a Splunk instance from the terminal. -->
+
+# Review fired alerts
+
+When to use: an incident is under way and you need to see which rules fired, when, and at what severity; a maintenance window is coming and noisy rules must be throttled before they flood the on-call channel; or an auditor asks which alerts fired and which were suppressed.
+
+## Prerequisites
+
+- A profile that passes `splunkctl doctor` (see [Configure](configure.md)).
+- Read access to fired alerts for `list`, `get`, and `actions`.
+- Write access to the saved search that owns the rule for `suppress` and `unsuppress`.
+
+## Synopsis
+
+```text
+splunkctl alerts list [--filter SUBSTRING] [--limit N] [--offset N]
+splunkctl alerts get <NAME>
+splunkctl alerts actions
+splunkctl alerts suppress <NAME> [--duration SECONDS] [--yes]
+splunkctl alerts unsuppress <NAME> [--yes]
+```
+
+`NAME` is the rule's saved search name, matched exactly and case-sensitively.
+
+## Workflow
+
+### Triage during an incident
+
+```bash
+splunkctl alerts list
+splunkctl alerts list --filter brute
+splunkctl alerts get 'Brute Force Login Attempts'
+```
+
+Expected result: one row per firing with `rule`, `triggered`, `severity`, `sid`, and `actions`. `--filter` matches the rule name; `--limit` and `--offset` page the firing rows client side, so a row is one firing, not one rule. `get` prints every firing of one rule and the firing count.
+
+### Check alert action types
+
+```bash
+splunkctl alerts actions
+```
+
+Expected result: the action types (email, webhook, script, and app-provided actions) configured on the instance. Check this before creating or changing saved searches that fire alerts.
+
+### Suppress during a maintenance window
+
+> **Safety:** Target is the Splunk host in the active profile. Impact: `alert.suppress=1` and `alert.suppress.period=<SECONDS>s` are written to the rule's saved search, so repeat firings are throttled for that window. Preview with `splunkctl alerts suppress 'Brute Force Login Attempts' --duration 7200`, apply by adding `--yes`, and verify with `splunkctl conf get savedsearches 'Brute Force Login Attempts' --key alert.suppress`.
+
+```bash
+splunkctl alerts suppress 'Brute Force Login Attempts' --duration 7200
+splunkctl alerts suppress 'Brute Force Login Attempts' --duration 7200 --yes
+```
+
+Expected result: the preview prints `[DRY RUN] Throttle alerts for rule (profile: NAME @ HOST:8089)` and the settings it will write; the apply prints `Throttled 'Brute Force Login Attempts' for 7200s.`. `--duration` is in seconds and defaults to 3600. Splunk's fired-alerts endpoint cannot be edited; throttling is a property of the underlying saved search.
+
+Suppress several rules 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
+```
+
+### Remove suppression after the window
+
+> **Safety:** Target is the Splunk host in the active profile. Impact: `alert.suppress=0` is written to the rule's saved search and it alerts normally again. Preview with `splunkctl alerts unsuppress 'Brute Force Login Attempts'`, apply by adding `--yes`, and verify with `splunkctl conf get savedsearches 'Brute Force Login Attempts' --key alert.suppress`.
+
+```bash
+splunkctl alerts unsuppress 'Brute Force Login Attempts'
+splunkctl alerts unsuppress 'Brute Force Login Attempts' --yes
+```
+
+Expected result: `Removed throttling from 'Brute Force Login Attempts'.`. The throttle setting stays on the saved search until you remove it; it does not expire on its own.
+
+### Produce JSON for scripts and agents
+
+```bash
+splunkctl alerts list --json
+splunkctl alerts list --json | jq '.[] | select((.severity | tonumber) >= 5)'
+splunkctl alerts get 'Brute Force Login Attempts' --json > alert_detail.json
+```
+
+Expected result: a JSON array of firing rows, suitable for `jq`, an agent, or audit evidence. `--format table|json|csv|jsonl` picks another output format. An agent can consume the JSON directly to correlate fired alerts with a change calendar or file tickets for high-severity triggers.
+
+## Troubleshooting
+
+- `not_found` from `alerts get`: the name must match the rule exactly; run `splunkctl alerts list --filter <text>` to find the spelling.
+- `not_found` from `suppress` or `unsuppress`: no saved search with that name is visible to your account; check `splunkctl rules list --filter <text>`.
+- `permission` from `suppress` or `unsuppress`: your role cannot edit the saved search in its owning app.
+- `No fired alerts.`: nothing has fired within Splunk's fired-alert retention; this is not an error.
+- A rule keeps firing after `suppress --yes`: throttling suppresses repeat firings for the period after a trigger; it does not disable the search. Disable the rule itself with the commands in [Manage detection rules](rules.md).
+
+## See also
+
+- [Manage detection rules](rules.md)
+- [Triage ES notables](es.md)
+- [Edit any conf file](conf.md)
+- [Command reference: alerts](../commands/alerts.md)

splunkctl-0.15.0/docs/guides/apps.md

@@ -0,0 +1,94 @@
+<!-- summary: Install, update, reload, and uninstall Splunk apps from local packages with a preview before every change. -->
+
+# Manage apps
+
+When to use: you need to deploy or upgrade a Technology Add-on, a content pack such as Enterprise Security content, or a custom detection app on a remote instance, disable an app during an incident, or audit what is installed, without SSH or the Web UI.
+
+## Prerequisites
+
+- A profile that passes `splunkctl doctor`, including the `Web UI reachable` check: `install` uploads the package through the Splunk Web UI handler.
+- An account allowed to install and edit apps (for example the `admin` role).
+- For `install`: a local `.spl` or `.tar.gz` package.
+
+## Synopsis
+
+```text
+splunkctl apps list [--filter SUBSTRING] [--limit N] [--offset N]
+splunkctl apps get <NAME>
+splunkctl apps install --path <PACKAGE.spl|PACKAGE.tar.gz> [--force] [--yes]
+splunkctl apps update <NAME> [--enabled|--disabled] [--visible|--hidden] [--yes]
+splunkctl apps uninstall <NAME> [--yes]
+splunkctl apps reload [--yes]
+```
+
+## Workflow
+
+### List and inspect
+
+```bash
+splunkctl apps list
+splunkctl apps list --filter TA-
+splunkctl apps get SplunkForwarder
+splunkctl apps list --json | jq '.[] | {name, version, disabled}'
+```
+
+Expected result: one row per installed app; `get` prints the app's full settings. `--filter`, `--limit`, and `--offset` apply client side.
+
+### Install or upgrade from a local package
+
+> **Safety:** Target is the Splunk host in the active profile. Impact: the package is uploaded through Splunk Web and installed; with `--force` an existing app of the same name is overwritten. Preview with `splunkctl apps install --path ./Splunk_TA_windows-8.9.0.spl`, apply by adding `--yes`, and verify with `splunkctl apps get Splunk_TA_windows`.
+
+```bash
+splunkctl apps install --path ./Splunk_TA_windows-8.9.0.spl
+splunkctl apps install --path ./Splunk_TA_windows-8.9.0.spl --yes
+splunkctl apps install --path ./DA-ESS-ContentUpdate-4.29.0.spl --force --yes
+```
+
+Expected result: the app appears in `splunkctl apps list`. The upload goes from your machine to the Splunk Web UI handler, so no SSH, SCP, or server filesystem access is needed. `--force` is required when the app already exists on the instance (reinstall or upgrade). An install may still need a Splunk restart to activate new modular inputs or scripted lookups; the CLI does not restart Splunk.
+
+### Disable an app during an incident
+
+> **Safety:** Target is the Splunk host in the active profile. Impact: the app's scheduled searches and knowledge objects stop running until re-enabled. Preview with `splunkctl apps update SplunkEnterpriseSecuritySuite --disabled`, apply by adding `--yes`, and verify with `splunkctl apps get SplunkEnterpriseSecuritySuite --json` (check `disabled`).
+
+```bash
+splunkctl apps update SplunkEnterpriseSecuritySuite --disabled
+splunkctl apps update SplunkEnterpriseSecuritySuite --disabled --yes
+splunkctl apps update SplunkEnterpriseSecuritySuite --enabled --yes
+splunkctl apps update my_app --enabled --visible --yes
+splunkctl apps update my_app --disabled --hidden --yes
+```
+
+Expected result: `Updated app 'NAME'.`. `--visible` and `--hidden` control whether the app shows in the Splunk Web app menu; at least one of the four flags is required.
+
+### Uninstall an app
+
+> **Safety:** Target is the Splunk host in the active profile. Impact: the app and its configuration are removed from the instance. Preview with `splunkctl apps uninstall my_app`, apply by adding `--yes`, and verify with `splunkctl apps list --filter my_app`.
+
+```bash
+splunkctl apps uninstall my_app
+splunkctl apps uninstall my_app --yes
+```
+
+### Reload all apps after a bulk change
+
+> **Safety:** Target is the Splunk host in the active profile. Impact: every app's configuration is re-read by splunkd. Preview with `splunkctl apps reload`, apply with `splunkctl apps reload --yes`, and verify with `splunkctl apps list`.
+
+```bash
+splunkctl apps reload --yes
+```
+
+## Troubleshooting
+
+- `not_found` from `get`, `update`, or `uninstall`: the app id (directory name) differs from its label; find it with `splunkctl apps list --filter <text>`.
+- `App install failed` or a `web` error: Splunk Web is not reachable from this machine; run `splunkctl doctor` and check `Web UI reachable`.
+- Install fails because the app already exists: add `--force`.
+- `No settings specified`: `update` needs `--enabled`, `--disabled`, `--visible`, or `--hidden`.
+- `permission` on `update` or `uninstall`: the account lacks app administration rights; use an `admin` account.
+- New inputs or lookups from an installed app do not run: restart Splunk from the server; the CLI does not restart it.
+
+## See also
+
+- [Diagnose a connection](doctor.md)
+- [Manage detection rules](rules.md)
+- [Manage configuration as code](state.md)
+- [Command reference: apps](../commands/apps.md)

splunkctl-0.15.0/docs/guides/audit.md

@@ -0,0 +1,92 @@
+<!-- summary: Produce change-audit and role-based access control attestation reports from Splunk for regulators and reviewers. -->
+
+# Audit changes and attest RBAC
+
+When to use: a regulator or reviewer asks who changed a saved search, role, or index and when (`audit changes`), or who holds which capabilities and index access for periodic access recertification (`audit rbac`). Both commands are read-only: no guard, no `--yes`.
+
+## Prerequisites
+
+- A profile that passes `splunkctl doctor` (see [Configure](configure.md)).
+- For `changes`: search access to `index=_audit` (the `admin` role has it by default).
+- For `rbac`: read access to users and roles (`edit_user` and `edit_roles`, or an `admin` account).
+
+## Synopsis
+
+```text
+splunkctl audit changes [--since TIME] [--until TIME] [--user USER] [--action SUBSTRING] [--object-type TYPE] [--limit N]
+splunkctl audit rbac [--roles-only] [--format csv] [--out FILE]
+```
+
+## Workflow
+
+### Pull the change log for a window
+
+```bash
+splunkctl audit changes
+splunkctl audit changes --since -7d --until -1d
+splunkctl audit changes --limit 2000 --json
+```
+
+Expected result: one row per `_audit` event, newest first, with exactly six keys in this order: `time`, `user`, `action`, `object`, `object_type`, `app`. The default window is the last 24 hours (`--since -24h`, `--until now`) and the display cap is 500 rows. Splunk mixes two incompatible event shapes in `_audit`; this command normalizes both:
+
+| Sourcetype | Shape | Mapping |
+|---|---|---|
+| `audittrail` (legacy) | `Audit:[timestamp=..., user=..., action=..., <tail>]` plain text | `user` and `action` parsed directly; `object` only when the line carries a literal `object="..."` marker (common on capability checks like `edit_user` and `edit_roles`); `object_type` 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 indexed `_time`, not a re-parse of either embedded timestamp, so every row has one consistent, sortable value. Real `audittrailv2` events have no `data.object` or `data.object_type` key; `data.name` and `data.type` are the nearest equivalents and are present on object and system category events (config changes). Action, authn, and check category events (ad-hoc searches, logins, capability grants) carry `data.type` sometimes but rarely `data.name`, so `object` stays empty for them, which is correct: they are not 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 for formats the parser does not know yet.
+
+### Filter by user, action, or object type
+
+```bash
+splunkctl audit changes --user jdoe
+splunkctl audit changes --action edit
+splunkctl audit changes --object-type saved_search
+splunkctl audit changes --since -30d --user svc_deploy --action edit --format csv --out changes.csv
+```
+
+Expected result: only matching rows. `--user` and `--object-type` are case-insensitive exact matches; `--action` is a case-insensitive substring match. Filters run client side on the normalized rows after the fetch, and `--limit` applies after filtering. The raw fetch is unbounded (`count=0`) within the `--since` and `--until` window, so a filter never misses a match because of an arbitrary raw-fetch cutoff. A very wide `--since` over a large `_audit` index fetches every event in that range before limiting, which can be slow; narrow `--since` when you can.
+
+### Confirm no flag value reaches the SPL
+
+```bash
+splunkctl --debug audit changes --user 'x" | delete' --action 'y | outputlookup evil.csv'
+```
+
+Expected result: the debug log shows `POST .../search/v2/jobs/ (body: {'search': 'search index=_audit', ...})`. The dispatched search is always the constant `search index=_audit`; `--since` and `--until` go through the job's `earliest_time` and `latest_time` arguments, and the other flags filter rows client side. No flag value, however adversarial, is composed into the SPL string.
+
+### Export an RBAC recertification report
+
+```bash
+splunkctl audit rbac
+splunkctl audit rbac --format csv --out recert-2026-07.csv
+```
+
+Expected result: one row per user with `user`, `email`, `roles` (direct roles, semicolon-joined), `capabilities`, and `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. 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 needs (Splunk's built-in `splunk-system-role` only imports `admin`) to show its real effective grant instead of an empty cell. `rbac` reads roles and users through the SDK only; it dispatches no search.
+
+### Attest per role instead of per user
+
+```bash
+splunkctl audit rbac --roles-only
+splunkctl audit rbac --roles-only --format csv --out roles-2026-07.csv
+```
+
+Expected result: one row per role with `role`, `imported_roles` (direct only), `capabilities`, and `srch_indexes_allowed`, the last two aggregated the same transitive way, rooted at that role.
+
+Multi-value fields (`roles`, `capabilities`, `srch_indexes_allowed`, `imported_roles`) join with `;`, never a newline. Splunk role, capability, and index names cannot contain a semicolon, so the join is lossless and never produces an embedded newline inside a CSV cell; `--format csv` output round-trips through Python's `csv` module.
+
+## Troubleshooting
+
+- `permission` or an empty result from `changes`: your role cannot search `index=_audit`; use an `admin` account or add `_audit` to the role's allowed indexes.
+- `timeout` on `changes`: the window is too wide; narrow `--since` or raise the global `--timeout`.
+- Rows show `action: "unparsed"`: the event matched neither audit shape; the raw line is in `object`, so the evidence is still complete.
+- `object_type` is empty on every row: the instance writes only the legacy `audittrail` shape, which has no type field; filter on `--action` instead.
+- `permission` from `rbac`: the account cannot list users or roles; it needs `edit_user` and `edit_roles` or an `admin` role.
+- Fewer rows than expected: `--limit` defaults to 500 after filtering; raise it.
+
+## See also
+
+- [Manage users and roles](users.md)
+- [Run searches](search.md)
+- [Exit codes](exit-codes.md)
+- [Command reference: audit](../commands/audit.md)

splunkctl-0.15.0/docs/guides/auth.md

@@ -0,0 +1,96 @@
+<!-- summary: Complete Splunk and SOAR SAML single sign-on, including a second factor, in a browser and reuse the session from every splunkctl command. -->
+
+# Log in through browser SAML
+
+When to use: your Splunk or SOAR instance authenticates through a SAML identity provider (with or without a second factor), so a username and password or a token cannot be stored in the profile, and you want every splunkctl command to reuse one browser login until it expires.
+
+## Prerequisites
+
+- splunkctl with the browser extra and Chromium:
+
+  ```bash
+  python -m pip install 'splunkctl[browser]'
+  python -m playwright install chromium
+  ```
+
+  Configuration succeeds without them; `splunkctl auth login` prints these commands when they are missing.
+
+- A machine with a display: login opens a headed Chromium window. The browser handles the identity provider; splunkctl never reads or stores TOTP secrets or codes.
+- A profile in browser mode (`auth_mode: browser` with a `web_url`), written by `config init` as shown below.
+- Not supported: 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.
+
+## Synopsis
+
+```text
+splunkctl config init --web-url <https://splunk.example.com:8000> [--profile NAME] [--auth-mode auto|browser]
+splunkctl config init --soar --web-url <https://soar.example.com> [--sso-url URL] [--profile NAME]
+splunkctl auth login --target <siem|soar>
+splunkctl auth status [--target siem|soar|both]
+splunkctl auth logout [--target siem|soar|both]
+```
+
+## Workflow
+
+### Detect SAML during setup
+
+```bash
+splunkctl config init --web-url https://splunk.example.com:8000
+splunkctl config init --soar --web-url https://soar.example.com --sso-url 'https://soar.example.com/saml2/login?idp=okta&next=/'
+```
+
+Expected result: `config init` probes the product's public login route. When it sees a redirect to an external identity provider it records `auth_mode: browser` and stores the product `web_url` in the profile. SAML detection runs only when `--web-url` is given. Pass `--auth-mode browser` to force browser mode without probing. For SOAR, pass `--sso-url` because SOAR's `/login` route is local-only.
+
+### Log in
+
+```bash
+splunkctl auth login --target siem
+splunkctl auth login --target soar
+```
+
+Expected result: Chromium opens at the product login route; you complete the identity provider prompts, including any TOTP code; splunkctl extracts only the product session (the Splunk `splunkd_<port>` cookie, or the SOAR `sessionid` and `csrftoken` cookies), proves it against the product API, and prints `siem session stored (profile 'NAME').`. `login` requires exactly one target because two back-to-back browser flows are easy to confuse.
+
+### Check the session
+
+```bash
+splunkctl auth status
+splunkctl auth status --target siem
+```
+
+Expected result: one row per target with `status` set to `missing`, `valid`, `expired`, or `unreachable`. Without `--target`, only targets configured for browser mode are checked; if none are, it prints `No browser-authenticated targets configured.`.
+
+### Use the session from normal commands
+
+```bash
+splunkctl search oneshot 'index=_internal | head 5'
+splunkctl soar test
+```
+
+Expected result: commands reuse the cached session whenever the active profile selects browser mode. A missing or expired session never opens a browser; the command fails with the exact `splunkctl auth login --target ...` instruction to run instead.
+
+### Log out
+
+```bash
+splunkctl auth logout --target siem
+splunkctl auth logout --target both
+```
+
+Expected result: a best-effort remote logout, then `Logout complete.`. The local session is always removed, even if the remote endpoint refuses; a refused remote logout prints a warning.
+
+Sessions live 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, and session values are redacted from all output.
+
+## Troubleshooting
+
+- `usage` error `siem is configured for token authentication, not browser login`: the profile has `auth_mode: token` or `password`; rerun `splunkctl config init --web-url URL` so SAML is detected, or pass `--auth-mode browser`.
+- `login` prints `pip install` and `playwright install` commands: the browser extra is missing; run them and retry.
+- `auth` error `login finished but the product session was rejected`: the browser ended on a different origin than `web_url`, or the identity provider flow did not complete; check `web_url` with `splunkctl config show` and log in again.
+- `connection` error `SIEM is unreachable while checking the browser session`: the product API is down or blocked; fix connectivity with [Diagnose a connection](doctor.md).
+- A command reports the session is missing or expired: run the `splunkctl auth login --target ...` command it prints; commands never open a browser on their own.
+- `remote logout failed; clearing local session`: the product refused the logout call; the local file is still removed and a new `login` is required.
+
+## See also
+
+- [Configure](configure.md)
+- [Install](install.md)
+- [Set up and check SOAR](soar.md)
+- [Contributor lab: Keycloak SAML](keycloak-lab.md)
+- [Command reference: auth](../commands/auth.md)