Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`**.
Expand Down
2 changes: 1 addition & 1 deletion SA-S4R/default/app.conf
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/poc/API_REFERENCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/poc/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
2 changes: 1 addition & 1 deletion docs/poc/CONFIGURATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
2 changes: 1 addition & 1 deletion docs/poc/TROUBLESHOOTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<name>` 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**:

Expand Down
2 changes: 1 addition & 1 deletion scripts/register-s4r-mcp-tools.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
4 changes: 2 additions & 2 deletions scripts/setup-splunk.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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}..."

Expand Down
Loading