splunk-soar-mcp 0.1.0__tar.gz

splunk_soar_mcp-0.1.0/.env.example

@@ -0,0 +1,36 @@
+# ---------------------------------------------------------------------------
+# Splunk SOAR MCP server — configuration
+# Copy to .env and fill in.  .env is gitignored.
+# ---------------------------------------------------------------------------
+
+# Base URL of your SOAR instance (no trailing slash, no /rest suffix)
+SPLUNK_SOAR_URL=https://soar.example.com
+
+# Automation user API token — SOAR UI: Administration > User Management >
+# Automation Users > (user) > ph-auth-token
+SPLUNK_SOAR_API=your-ph-auth-token-here
+
+# --- Safety -----------------------------------------------------------------
+# readonly : GET-only. Cannot change anything on the instance.
+# standard : readonly + low-risk writes (notes, comments, artifacts,
+#            container status/severity/owner, custom-list rows).   [default]
+# full     : standard + run actions & playbooks, deletes, raw POST/DELETE.
+SOAR_MCP_MODE=standard
+
+# Optional. Comma-separated container labels the server may touch.
+# Empty = all labels. Strongly recommended on multi-tenant/MSSP instances.
+# SOAR_MCP_ALLOWED_LABELS=test_label,lab
+
+# Path to this file, if it is not ./.env — a stdio server inherits its working
+# directory from whatever launched it, so an absolute path is usually safer.
+# SOAR_MCP_ENV_FILE=/etc/splunk-soar-mcp/.env
+
+# --- Connection -------------------------------------------------------------
+# Verify TLS. Set false only for self-signed on-prem certs on a trusted network.
+SOAR_MCP_VERIFY_SSL=true
+# Path to a CA bundle, if you have one (preferred over disabling verification).
+# SOAR_MCP_CA_BUNDLE=/etc/ssl/certs/soar-ca.pem
+
+SOAR_MCP_TIMEOUT=60
+SOAR_MCP_DEFAULT_PAGE_SIZE=25
+SOAR_MCP_MAX_PAGE_SIZE=500

splunk_soar_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: pytest -q
+      - name: Server starts and registers tools
+        env:
+          SPLUNK_SOAR_URL: https://soar.invalid
+          SPLUNK_SOAR_API: ci-placeholder
+        run: |
+          splunk-soar-mcp --list-tools --mode readonly
+          splunk-soar-mcp --list-tools --mode full
+      - name: End-to-end stdio smoke test
+        run: python scripts/smoke_test.py

splunk_soar_mcp-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+# secrets — never commit
+.env
+.env.*
+!.env.example
+secrets.txt
+*.pem
+*.key
+
+# python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# editors / os
+.vscode/
+.idea/
+.DS_Store

splunk_soar_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,84 @@
+# Changelog
+
+All notable changes to this project are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
+project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Administration reads: `soar_get_system_settings` (34 sections, with a guide to
+  which admin page each backs), `soar_get_license`, `soar_get_system_health`,
+  `soar_list_cluster_nodes`, `soar_list_feature_flags`, `soar_list_ingestion_status`.
+- Event metadata: `soar_list_container_statuses`, `soar_list_severities`,
+  `soar_list_custom_fields`, `soar_list_cef_fields`, `soar_list_workbooks`,
+  `soar_get_workbook`.
+- Users and roles: `soar_list_users`, `soar_get_user`, `soar_list_roles`,
+  `soar_get_role` with its permission matrix, plus `soar_create_role`,
+  `soar_update_role` and `soar_delete_role` in `full` mode. Platform built-in
+  roles are refused, and deletion requires the role's exact name.
+- Custom list lifecycle: `soar_create_custom_list`, `soar_update_custom_list_row`
+  (a targeted row replacement rather than rewriting the list), and
+  `soar_delete_custom_list` in `full` mode.
+
+### Fixed
+
+- `soar_run_action` omitted the asset's `app_id` from the action target. SOAR
+  queued the run and then failed it with `app_id has invalid format`, so the
+  call looked like a success while the action never ran.
+- `soar_list_action_runs` and `soar_get_action_run` read `app_run`, the
+  per-asset execution layer, which does not record an action that failed before
+  reaching an app. They now read `action_run`, and `soar_get_action_run` returns
+  the app runs beneath it for their `result_data`.
+
+- `soar_add_comment` posted to `container/<id>`, which SOAR answers with
+  `{"success": true}` while silently creating nothing. It now posts to
+  `container_comment`, verified against 7.1.
+- `soar_get_playbook_run_log` no longer falls back to `playbook_run_log`, an
+  endpoint that returns `403 Not allowed`; an empty log now reports the run's
+  status, since a run still executing has not written one yet.
+- httpx no longer logs one INFO line per REST call into the client's log pane.
+
+### Security
+
+- Credentials are stripped from every response. SOAR returns asset configuration
+  verbatim, including populated `password`, `client_secret`, `api_key` and
+  `ph auth token` fields; these are now replaced before anything leaves the
+  process, including via `soar_rest_get` and error bodies.
+- `SOAR_MCP_ALLOWED_LABELS` now gates reads as well as writes, and container
+  listings are filtered to permitted labels server-side.
+- Refusals no longer name the target's container label or the permitted set, and
+  `soar_system_info` reports only a count. On a multi-tenant instance the
+  allowlist is the customer list, so echoing it let a caller enumerate tenants.
+
+### Changed
+
+- Credentials come from the environment or an env file only. The bespoke
+  `secrets.txt` search was removed; `SOAR_MCP_ENV_FILE` overrides the env file
+  path, which a stdio server usually needs since it inherits its client's
+  working directory.
+- Every tool that reaches the instance is now annotated `open_world_hint=True`;
+  only the local block builders are closed-world.
+
+## [0.1.0]
+
+Initial release.
+
+### Added
+
+- Read tools for apps, assets, app actions, custom functions and repositories.
+- Playbook tools: listing, metadata, block inventory, per-block source, run history,
+  run logs with a substring filter, and app action runs with full `result_data`.
+- Container tools: listing with label/status/severity/owner filters, artifacts, notes
+  and comments.
+- Custom list tools: listing, contents, append and replace.
+- Execution tools for running playbooks and app actions, in `full` mode.
+- Visual editor block tools: decode and encode clipboard payloads, and builders for
+  code, action, decision, format, custom function and child playbook blocks.
+- Raw REST escape hatches, with POST and DELETE gated to `full` mode.
+- Three-tier safety model (`readonly` / `standard` / `full`) that decides which tools are
+  registered, plus a container-label allowlist enforced on every write.
+- Resources for the `phantom.*` callable reference, datapath forms and the editor block
+  format; prompts for debugging a run, triaging a container and designing a block.
+- stdio and streamable-HTTP transports.

splunk_soar_mcp-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing
+
+Bug reports, endpoint corrections and new tools are all welcome.
+
+## Getting set up
+
+```bash
+git clone https://github.com/huseynAgazade/splunk-soar-mcp
+cd splunk-soar-mcp
+pip install -e ".[dev]"
+pytest        # the REST layer is mocked; no SOAR instance required
+ruff check .
+```
+
+## Adding a tool
+
+1. Put it in the `tools/` module that matches its subject.
+2. Give it a `@mcp.tool` decorator with a `description` that says what the tool is *for*,
+   and a docstring whose `Args:` section documents every parameter — both end up in the
+   schema the model reads.
+3. Set `ToolAnnotations` honestly: `read_only_hint` for queries, `destructive_hint` for
+   anything irreversible.
+4. Register it in `server.py` under the **lowest** mode that should have it. A tool that
+   writes belongs in `register_writes`; one that deletes or executes belongs in
+   `register_destructive` or `run.py`.
+5. Raise `SoarError` (or a subclass) for failures the caller could act on. It subclasses
+   the SDK's `ToolError`, so the message reaches the model — a plain exception is masked
+   as "Error executing tool".
+6. Add a test. `tests/conftest.py` has the fixtures; `respx` mocks the REST layer.
+
+## Endpoint corrections
+
+SOAR's REST surface varies between versions, and some of it is undocumented. If a tool
+targets the wrong endpoint on your version, please open an issue with your SOAR version
+and the response you get — that is more useful than a guess at the right path.
+
+## Style
+
+`ruff` enforces the rest. Keep tool descriptions concrete: what it returns and when to
+reach for it beats a restatement of the name.

splunk_soar_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vahab Huseynzada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.