Artifacts/unraid-mcp
2
0
Fork 0
forked from HomeLab/unraid-mcp
Code Pull Requests Actions Packages Releases 5 Activity

fix(security): path traversal, timing-safe auth, stale credential bindings

Browse Source 
Security:
- Remove /mnt/ from _ALLOWED_LOG_PREFIXES to prevent Unraid share exposure
- Add early .. detection for disk/logs and live/log_tail path validation
- Add /boot/ prefix restriction for flash_backup source_path
- Use hmac.compare_digest for timing-safe API key verification in server.py
- Gate include_traceback on DEBUG log level (no tracebacks in production)

Correctness:
- Re-raise CredentialsNotConfiguredError in health check instead of swallowing
- Fix ups_device query (remove non-existent nominalPower/currentPower fields)

Best practices (BP-01, BP-05, BP-06):
- Add # noqa: ASYNC109 to timeout params in _handle_live and unraid()
- Fix start_array* → start_array in docstring (not in ARRAY_DESTRUCTIVE)
- Remove from __future__ import annotations from snapshot.py
- Replace import-time UNRAID_API_KEY/URL bindings with _settings.ATTR pattern
  in manager.py, snapshot.py, utils.py, diagnostics.py — fixes stale binding
  after apply_runtime_config() post-elicitation (BP-05)

CI/CD:
- Add .github/workflows/ci.yml (5-job pipeline: lint, typecheck, test, version-sync, audit)
- Add fail_under = 80 to [tool.coverage.report]
- Add version sync check to scripts/validate-marketplace.sh

Documentation:
- Sync plugin.json version 1.1.1 → 1.1.2 with pyproject.toml
- Update CLAUDE.md: 3 tools, system domain count 18, scripts comment fix
- Update README.md: 3 tools, security notes
- Update docs/AUTHENTICATION.md: H1 title fix
- Add UNRAID_CREDENTIALS_DIR to .env.example

Bump: 1.1.1 → 1.1.2

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Jacob Magar
2026-03-23 11:37:05 -04:00
parent d59f8c22a8
commit 2b777be927
17 changed files with 233 additions and 83 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
unraid_mcp/subscriptions/diagnostics.py
View File

@@ -15,8 +15,8 @@ import websockets
from fastmcp import FastMCP
from websockets.typing import Subprotocol
from ..config import settings as _settings
from ..config.logging import logger
from ..config.settings import UNRAID_API_KEY, UNRAID_API_URL
from ..core.exceptions import ToolError
from ..core.utils import safe_display_url
from .manager import subscription_manager
@@ -130,7 +130,7 @@ def register_diagnostic_tools(mcp: FastMCP) -> None:
json.dumps(
{
"type": "connection_init",
"payload": {"x-api-key": UNRAID_API_KEY},
"payload": {"x-api-key": _settings.UNRAID_API_KEY},
}
)
)
@@ -203,7 +203,7 @@ def register_diagnostic_tools(mcp: FastMCP) -> None:
# Calculate WebSocket URL
ws_url_display: str | None = None
if UNRAID_API_URL:
if _settings.UNRAID_API_URL:
try:
ws_url_display = build_ws_url()
except ValueError:
@@ -215,8 +215,8 @@ def register_diagnostic_tools(mcp: FastMCP) -> None:
"environment": {
"auto_start_enabled": subscription_manager.auto_start_enabled,
"max_reconnect_attempts": subscription_manager.max_reconnect_attempts,
"unraid_api_url": safe_display_url(UNRAID_API_URL),
"api_key_configured": bool(UNRAID_API_KEY),
"unraid_api_url": safe_display_url(_settings.UNRAID_API_URL),
"api_key_configured": bool(_settings.UNRAID_API_KEY),
"websocket_url": ws_url_display,
},
"subscriptions": status,

8
unraid_mcp/subscriptions/manager.py
View File

@@ -15,8 +15,8 @@ from typing import Any
import websockets
from websockets.typing import Subprotocol
from ..config import settings as _settings
from ..config.logging import logger
from ..config.settings import UNRAID_API_KEY
from ..core.client import redact_sensitive
from ..core.types import SubscriptionData
from .utils import build_ws_ssl_context, build_ws_url
@@ -250,7 +250,7 @@ class SubscriptionManager:
ws_url = build_ws_url()
logger.debug(f"[WEBSOCKET:{subscription_name}] Connecting to: {ws_url}")
logger.debug(
f"[WEBSOCKET:{subscription_name}] API Key present: {'Yes' if UNRAID_API_KEY else 'No'}"
f"[WEBSOCKET:{subscription_name}] API Key present: {'Yes' if _settings.UNRAID_API_KEY else 'No'}"
)
ssl_context = build_ws_ssl_context(ws_url)
@@ -287,10 +287,10 @@ class SubscriptionManager:
init_type = "connection_init"
init_payload: dict[str, Any] = {"type": init_type}
if UNRAID_API_KEY:
if _settings.UNRAID_API_KEY:
logger.debug(f"[AUTH:{subscription_name}] Adding authentication payload")
# Use graphql-ws connectionParams format (direct key, not nested headers)
init_payload["payload"] = {"x-api-key": UNRAID_API_KEY}
init_payload["payload"] = {"x-api-key": _settings.UNRAID_API_KEY}
else:
logger.warning(
f"[AUTH:{subscription_name}] No API key available for authentication"

12
unraid_mcp/subscriptions/snapshot.py
View File

@@ -11,8 +11,6 @@ WebSocket per call. This is intentional: MCP tools are request-response.
Use the SubscriptionManager for long-lived monitoring resources.
"""
from __future__ import annotations
import asyncio
import json
from typing import Any
@@ -20,8 +18,8 @@ from typing import Any
import websockets
from websockets.typing import Subprotocol
from ..config import settings as _settings
from ..config.logging import logger
from ..config.settings import UNRAID_API_KEY
from ..core.exceptions import ToolError
from .utils import build_ws_ssl_context, build_ws_url
@@ -51,8 +49,8 @@ async def subscribe_once(
# Handshake
init: dict[str, Any] = {"type": "connection_init"}
if UNRAID_API_KEY:
init["payload"] = {"x-api-key": UNRAID_API_KEY}
if _settings.UNRAID_API_KEY:
init["payload"] = {"x-api-key": _settings.UNRAID_API_KEY}
await ws.send(json.dumps(init))
raw = await asyncio.wait_for(ws.recv(), timeout=timeout)
@@ -126,8 +124,8 @@ async def subscribe_collect(
sub_id = "snapshot-1"
init: dict[str, Any] = {"type": "connection_init"}
if UNRAID_API_KEY:
init["payload"] = {"x-api-key": UNRAID_API_KEY}
if _settings.UNRAID_API_KEY:
init["payload"] = {"x-api-key": _settings.UNRAID_API_KEY}
await ws.send(json.dumps(init))
raw = await asyncio.wait_for(ws.recv(), timeout=timeout)

28
unraid_mcp/subscriptions/utils.py
View File

@@ -3,11 +3,11 @@
import ssl as _ssl
from typing import Any
from ..config.settings import UNRAID_API_URL, UNRAID_VERIFY_SSL
from ..config import settings as _settings
def build_ws_url() -> str:
"""Build a WebSocket URL from the configured UNRAID_API_URL.
"""Build a WebSocket URL from the configured UNRAID_API_URL setting.
Converts http(s) scheme to ws(s) and ensures /graphql path suffix.
@@ -17,19 +17,19 @@ def build_ws_url() -> str:
Raises:
ValueError: If UNRAID_API_URL is not configured or has an unrecognised scheme.
"""
if not UNRAID_API_URL:
if not _settings.UNRAID_API_URL:
raise ValueError("UNRAID_API_URL is not configured")
if UNRAID_API_URL.startswith("https://"):
ws_url = "wss://" + UNRAID_API_URL[len("https://") :]
elif UNRAID_API_URL.startswith("http://"):
ws_url = "ws://" + UNRAID_API_URL[len("http://") :]
elif UNRAID_API_URL.startswith(("ws://", "wss://")):
ws_url = UNRAID_API_URL # Already a WebSocket URL
if _settings.UNRAID_API_URL.startswith("https://"):
ws_url = "wss://" + _settings.UNRAID_API_URL[len("https://") :]
elif _settings.UNRAID_API_URL.startswith("http://"):
ws_url = "ws://" + _settings.UNRAID_API_URL[len("http://") :]
elif _settings.UNRAID_API_URL.startswith(("ws://", "wss://")):
ws_url = _settings.UNRAID_API_URL # Already a WebSocket URL
else:
raise ValueError(
f"UNRAID_API_URL must start with http://, https://, ws://, or wss://. "
f"Got: {UNRAID_API_URL[:20]}..."
f"Got: {_settings.UNRAID_API_URL[:20]}..."
)
if not ws_url.endswith("/graphql"):
@@ -45,13 +45,13 @@ def build_ws_ssl_context(ws_url: str) -> _ssl.SSLContext | None:
ws_url: The WebSocket URL to connect to.
Returns:
An SSLContext configured per UNRAID_VERIFY_SSL, or None for non-TLS URLs.
An SSLContext configured per _settings.UNRAID_VERIFY_SSL, or None for non-TLS URLs.
"""
if not ws_url.startswith("wss://"):
return None
if isinstance(UNRAID_VERIFY_SSL, str):
return _ssl.create_default_context(cafile=UNRAID_VERIFY_SSL)
if UNRAID_VERIFY_SSL:
if isinstance(_settings.UNRAID_VERIFY_SSL, str):
return _ssl.create_default_context(cafile=_settings.UNRAID_VERIFY_SSL)
if _settings.UNRAID_VERIFY_SSL:
return _ssl.create_default_context()
# Explicitly disable verification (equivalent to verify=False)
ctx = _ssl.SSLContext(_ssl.PROTOCOL_TLS_CLIENT)