diff --git a/AGENTS.md b/AGENTS.md index ad7c583..7e686f3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -95,7 +95,7 @@ Workshop agent **roles** remain in **`.cursor/agents/`** (not skills). Do not du ## Common failure modes - **“User lacks required mcp_tool_execute capability”** — Role **`mcp_user`** missing the capability. Re-run setup or POST **`capabilities=mcp_tool_execute`** to **`/services/authorization/roles/mcp_user`** (see **`scripts/setup-splunk.sh`**). -- **`SA-S4R_*` tools missing from `tools/list`, or HTTP 403 “Role not permitted for this tool”** — The user lacks role **`s4r_user`**, which the tools are limited to (Tool Role Policies; `admin` bypasses them). Add the role to the user. If **`splunker`** itself lost the tools, `docker logs splunk-init` for “Role s4r_user not found” (SA-S4R older than 1.1.1 in an existing volume): **`make clean-y && make up`**. +- **`SA-S4R_*` tools missing from `tools/list`, or HTTP 403 “Role not permitted for this tool”** — The user lacks role **`s4r_user`**, which the tools are limited to (Tool Role Policies; `admin` bypasses them). Add the role to the user. If **`splunker`** itself lost the tools, `docker logs splunk-init` for “Role s4r_user not found” (SA-S4R older than 2.0.0 in an existing volume): **`make clean-y && make up`**. - **`splunk-init` exited non-zero** — **`make status`** prints **`FAILED (exit N)`**; Splunk may still be up but roles/token/MCP setup incomplete. **`docker logs splunk-init`**, then **`make down && make up`** or fix env and re-run init. - **`so1` unhealthy / `Errno 30` on SA-S4R** — The app is installed from the GitHub **`.spl`**, not a bind mount. Do not add a **`:ro`** bind of the app tree; Splunk **chowns** that path. Recover with **`./scripts/compose-up.sh`** (or **`make up`**). Bare **`docker compose up`** without **`.env`** blanks Splunkbase creds. Details: **`docs/poc/TROUBLESHOOTING.md`**. - **`mcp_token` “Unknown resource” / mint hangs** — The Splunk MCP Server app is 2.1+ (token API moved to **`/services/mcp_token/tokens`** and **`/key-pair`**) but the checked-out scripts are older, or the key pair expired. **`docs/poc/TROUBLESHOOTING.md`**. diff --git a/SA-S4R/default/app.conf b/SA-S4R/default/app.conf index 90c3ca6..13a8244 100644 --- a/SA-S4R/default/app.conf +++ b/SA-S4R/default/app.conf @@ -8,7 +8,7 @@ description = Buttercup Enterprises workshop sample data (Eventgen access_combin [launcher] author = splunk-mcp contributors description = Splunk4Rookies PoC: synthetic Buttercup web access logs via Eventgen, field extractions, and product_codes lookup for workshop Labs 3–7. -version = 1.1.1 +version = 2.0.0 [package] id = SA-S4R diff --git a/docs/poc/API_REFERENCE.md b/docs/poc/API_REFERENCE.md index 79a8481..8fdb285 100644 --- a/docs/poc/API_REFERENCE.md +++ b/docs/poc/API_REFERENCE.md @@ -157,7 +157,7 @@ The Splunk MCP endpoint is a **JSON-RPC `POST`** handler at `/services/mcp` (not ### Example 1: Create role + user (admin basic auth) -What `scripts/setup-splunk.sh` does, step by step (`make up` runs it for you). `s4r_user` exists only once SA-S4R 1.1.1+ is installed, and `s4r_workshop_control` only once SA-S4R has loaded, so run this after the app is in place. The admin password goes through `splunk_curl` and the `splunker` password through stdin, so neither shows up in `ps`. +What `scripts/setup-splunk.sh` does, step by step (`make up` runs it for you). `s4r_user` exists only once SA-S4R 2.0.0+ is installed, and `s4r_workshop_control` only once SA-S4R has loaded, so run this after the app is in place. The admin password goes through `splunk_curl` and the `splunker` password through stdin, so neither shows up in `ps`. ```bash #!/bin/bash diff --git a/docs/poc/ARCHITECTURE.md b/docs/poc/ARCHITECTURE.md index dc71967..bab567b 100644 --- a/docs/poc/ARCHITECTURE.md +++ b/docs/poc/ARCHITECTURE.md @@ -290,7 +290,7 @@ Claude Desktop ### setup-splunk.sh - Creates or updates Splunk role **`mcp_user`** with capabilities **`mcp_tool_execute`** and **`s4r_workshop_control`** (after an SA-S4R reload) and **`srchJobsQuota=5`** -- Creates **`splunker`** with roles **`user`** + **`mcp_user`** + **`s4r_user`** (`s4r_user` comes from SA-S4R 1.1.1+; left out with a warning if the app lacks it) +- Creates **`splunker`** with roles **`user`** + **`mcp_user`** + **`s4r_user`** (`s4r_user` comes from SA-S4R 2.0.0+; left out with a warning if the app lacks it) - Via **`register-s4r-mcp-tools.sh`**: limits the five **`SA-S4R_*`** tools to **`s4r_user`** with Tool Role Policies, when the role exists and `splunker` holds it - Uses `SPLUNK_SPLUNKER_PASSWORD` (env) for the MCP user (no password written to disk) - REST host, port, and account names come from `scripts/splunk-api-env.sh` (`localhost`, `8089`, `admin`, `splunker` unless already set) diff --git a/docs/poc/CONFIGURATION.md b/docs/poc/CONFIGURATION.md index 713071f..d937a0b 100644 --- a/docs/poc/CONFIGURATION.md +++ b/docs/poc/CONFIGURATION.md @@ -185,7 +185,7 @@ Summary of what runs **inside** `splunk-init` with `SPLUNK_HOST=so1`: 1. Enables the **SA-Eventgen** default modular input (**required**; init **exits 1** if the app is missing or the input stays disabled). 2. Sets MCP server `ssl_verify=false` via REST (dev convenience). 3. Ensures Splunk role **`mcp_user`** exists with capability **`mcp_tool_execute`** and **`srchJobsQuota=5`** (parallel S4R agent headroom). -4. Creates or updates user **`splunker`** with roles **`user`** + **`mcp_user`** + **`s4r_user`**, and clears **`locked-out`** (idempotent unlock on every init). **`s4r_user`** is defined by SA-S4R 1.1.1+. If the installed app is older and lacks it, init warns and leaves it out instead of failing. +4. Creates or updates user **`splunker`** with roles **`user`** + **`mcp_user`** + **`s4r_user`**, and clears **`locked-out`** (idempotent unlock on every init). **`s4r_user`** is defined by SA-S4R 2.0.0+. If the installed app is older and lacks it, init warns and leaves it out instead of failing. 5. Registers SA-S4R MCP tools from `s4r_mcp_tools.json` (`POST /services/mcp_tools`, enable, saved-search reload). Init **exits 1** if that fails. 6. Uses `SPLUNK_SPLUNKER_PASSWORD` from env; this repo does not write passwords to disk. diff --git a/docs/poc/TROUBLESHOOTING.md b/docs/poc/TROUBLESHOOTING.md index 53af55a..041600c 100644 --- a/docs/poc/TROUBLESHOOTING.md +++ b/docs/poc/TROUBLESHOOTING.md @@ -350,7 +350,7 @@ make up **Cause 2: the user lacks role `s4r_user`.** The five tools are limited to that role (Tool Role Policies). A user without it sees no `SA-S4R_*` tools in `tools/list` and gets HTTP 403 `Role not permitted for this tool` on a call, while the generic Splunk tools still work. `admin` bypasses the policies. Check with `GET /services/authentication/users/` and `GET /services/mcp_tool_roles`. -**Cause 3: `splunker` lost the tools after init.** `docker logs splunk-init` shows `Role s4r_user not found` when the installed SA-S4R is older than 1.1.1 (an existing `so1-etc` volume keeps the app it first installed). Init then leaves the role and the policies out, so the tools stay open. A `Restricted 5 SA-S4R MCP tools` line means the policies were applied. +**Cause 3: `splunker` lost the tools after init.** `docker logs splunk-init` shows `Role s4r_user not found` when the installed SA-S4R is older than 2.0.0 (an existing `so1-etc` volume keeps the app it first installed). Init then leaves the role and the policies out, so the tools stay open. A `Restricted 5 SA-S4R MCP tools` line means the policies were applied. **Solution**: diff --git a/scripts/register-s4r-mcp-tools.sh b/scripts/register-s4r-mcp-tools.sh index cc774a0..1177643 100755 --- a/scripts/register-s4r-mcp-tools.sh +++ b/scripts/register-s4r-mcp-tools.sh @@ -58,7 +58,7 @@ restrict_s4r_mcp_tools() { "${SPLUNK_URL}/services/authorization/roles/${role}?output_mode=json" -w "\n%{http_code}" || true)" code="${response##*$'\n'}" if [[ ! "${code}" =~ ^2 ]]; then - echo "⚠️ Role ${role} not found (SA-S4R older than 1.1.1?). SA-S4R tools stay open; make clean-y && make up installs the current app." >&2 + echo "⚠️ Role ${role} not found (SA-S4R older than 2.0.0?). SA-S4R tools stay open; make clean-y && make up installs the current app." >&2 return 0 fi diff --git a/scripts/setup-splunk.sh b/scripts/setup-splunk.sh index a93d671..ca2b073 100755 --- a/scripts/setup-splunk.sh +++ b/scripts/setup-splunk.sh @@ -244,7 +244,7 @@ fi cleanup_last_body # --- 4. MCP user (splunker) --- -# s4r_user is defined by SA-S4R authorize.conf (1.1.1+). An older app kept in an existing so1-etc +# s4r_user is defined by SA-S4R authorize.conf (2.0.0+). An older app kept in an existing so1-etc # volume lacks it, and Splunk rejects an unknown role, so skip it then instead of failing init. s4r_role_ok=0 n=0 @@ -267,7 +267,7 @@ if [ "${s4r_role_ok}" = "1" ]; then user_roles="user + mcp_user + s4r_user" set -- -d "roles=s4r_user" "$@" else - echo "⚠️ Role s4r_user not found (SA-S4R older than 1.1.1?). Not assigning it; make clean-y && make up installs the current app." + echo "⚠️ Role s4r_user not found (SA-S4R older than 2.0.0?). Not assigning it; make clean-y && make up installs the current app." fi echo "🧑 Ensuring Splunk user '${SPLUNK_MCP_USER}' exists with roles ${user_roles}..."