feat: container healthcheck, alert-flush retries, audit hardening (v0.16.0)

June 12 audit remediation: liveness heartbeat + Dockerfile HEALTHCHECK,
queued-alert flush keeps failed alerts for one retry, model_select callback
validated against registry, blocking pip-audit in CI (aiohttp CVEs assessed
not exploitable, ignored with justification), diagnostic prompt sanitizes
container config, explicit LLM client timeouts.

Author: dervish666

.claude/structure/utils.yaml

@@ -191,3 +191,15 @@ files:
         items: [Path]
       - from: tempfile
         items: [tempfile]
+
+  heartbeat.py:
+    description: Liveness heartbeat loop touching a file the Docker HEALTHCHECK reads; fresh mtime proves the event loop is responsive.
+    exports:
+      - name: heartbeat_loop
+        kind: function
+        description: Touch HEARTBEAT_PATH every interval seconds forever; OSError is logged, never raised
+        params: [{name: path, type: str}, {name: interval, type: float}]
+        returns: None
+    imports:
+      - from: src.constants
+        items: [HEARTBEAT_INTERVAL_SECONDS, HEARTBEAT_PATH]

.github/workflows/ci.yml

@@ -33,7 +33,13 @@ jobs:
       - name: Test (pytest)
         run: uv run pytest tests/
 
-      # Audits the project venv for known CVEs. Non-blocking is deliberate:
-      # a new upstream CVE shouldn't break unrelated PRs — review the log.
+      # Audits the project venv for known CVEs. Blocking, so new CVEs surface
+      # immediately. Ignored IDs are aiohttp issues fixed only in 3.14, which
+      # aiogram caps below; neither is exploitable here (no CookieJar.load(),
+      # no per-request cookies) — see pyproject.toml. Drop the ignores once
+      # aiogram allows aiohttp>=3.14.
       - name: Dependency audit (pip-audit)
-        run: uv run pip-audit || true
+        run: >
+          uv run pip-audit
+          --ignore-vuln CVE-2026-34993
+          --ignore-vuln CVE-2026-47265

CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to UnraidMonitor will be documented in this file.
 
+## [0.16.0] - 2026-06-12
+
+Remediation of the June 12 codebase audit (vault: `audits/Unraid Monitor/reports/audit-2026-06-12-0639.md`) — all actionable findings implemented.
+
+### Added
+- **Container health check** — the bot now touches a liveness heartbeat file from its event loop every 60s (`src/utils/heartbeat.py`), and the Dockerfile gained a `HEALTHCHECK` that fails when the file goes stale. Bot health shows up in `docker ps` and the Unraid dashboard with no port mapping required. The heartbeat starts before the setup wizard too, so a container mid-setup doesn't report unhealthy.
+- 10 new tests (1179 total): flush retry/drop semantics, queue dedup, spoofed `model_select` rejection, heartbeat liveness.
+
+### Fixed
+- **Queued alerts are no longer lost on a failed flush** — the pre-`/start` queue was cleared *before* delivery, so a transient Telegram failure during the flush silently discarded boot-time alerts. An alert now counts as delivered once any chat receives it; alerts that fail every chat get one retry on the next flush, then are dropped with a logged warning.
+- **Identical consecutive alerts dedup at queue time** — two identical crash alerts queued before `/start` no longer both deliver.
+- **Auto-heal save surfaces dropped names** — if `set_containers()` ever filters an invalid name, the `/manage` save answer now says how many were skipped instead of staying silent.
+
+### Security
+- **`model_select:` callback validated against the registry** — the last callback family without input validation. A spoofed callback can no longer persist arbitrary provider/model strings into `data/model_selection.json`; unknown pairs get "Invalid selection".
+- **pip-audit is now blocking in CI** — it previously ran with `|| true`, which is how the aiohttp CVEs went unnoticed. The two known aiohttp advisories (CVE-2026-34993, CVE-2026-47265; fixed only in 3.14, which aiogram caps below) are explicitly `--ignore-vuln`-ed with justification: neither is exploitable here (no `CookieJar.load()`, no per-request cookies). Any *new* CVE now fails the build. aiohttp floor raised to 3.13.5 with a comment documenting the situation.
+- **Diagnostic prompt sanitizes container config** — volume mounts, env vars, and port mappings now pass through `sanitize_for_prompt()` like every other prompt input (defense-in-depth against a compromised container injecting instructions).
+
+### Changed
+- **Explicit LLM timeouts** — Anthropic/OpenAI clients are constructed with a 120s timeout (SDK default is ~10 minutes), Ollama gets 300s (local models on CPU are legitimately slow), and startup model discovery is capped at 15s so a slow API can't stall boot.
+
 ## [0.15.1] - 2026-06-08
 
 ### Changed

CLAUDE.md

@@ -85,14 +85,15 @@ src/unraid/monitors/array_monitor.py - ArrayMonitor for disk health and usage al
 # Utils
 src/utils/api_errors.py - LLM API error handling (Anthropic + OpenAI) with user-friendly messages
 src/utils/formatting.py - Bytes/uptime formatting, safe_reply/safe_edit, format_mute_expiry
+src/utils/heartbeat.py - heartbeat_loop() touching the liveness file the Docker HEALTHCHECK reads
 src/utils/rate_limiter.py - PerUserRateLimiter for per-user API rate limiting
 src/utils/sanitize.py - Prompt injection prevention, sensitive data redaction
 src/utils/telegram_retry.py - Telegram API retry logic for rate limit handling
 src/utils/version_store.py - read/write data/announced_version.json for startup What's new gate (atomic)
 
 ## Project Overview
 
-Unraid Server Monitor Bot (v0.15.1) - A Docker-based Telegram bot for monitoring Unraid servers. Monitors Docker containers (events, logs, resources) and Unraid server health (CPU, memory, disks, array, UPS). Uses multi-provider LLM support (Anthropic, OpenAI, Ollama) for AI-powered diagnostics and natural language interaction. Sends alerts via Telegram with quick-action buttons.
+Unraid Server Monitor Bot (v0.16.0) - A Docker-based Telegram bot for monitoring Unraid servers. Monitors Docker containers (events, logs, resources) and Unraid server health (CPU, memory, disks, array, UPS). Uses multi-provider LLM support (Anthropic, OpenAI, Ollama) for AI-powered diagnostics and natural language interaction. Sends alerts via Telegram with quick-action buttons.
 
 **Version string lives in TWO places** — `pyproject.toml` (`version`) and `src/__init__.py` (`__version__`). Both must be bumped together on release; `tests/test_version.py` guards against drift. `BOT_VERSION` (in `src/bot/health_command.py`) resolves from installed package metadata when available, else falls back to `src.__version__` — the package is not installed in the Docker image, so the `__version__` fallback is what runs in production.
 

Dockerfile

@@ -34,6 +34,12 @@ RUN useradd -m appuser && \
 COPY entrypoint.sh /entrypoint.sh
 RUN chmod +x /entrypoint.sh
 
+# Liveness: the bot touches /tmp/unraidmonitor-heartbeat from its event loop
+# every 60s (src/utils/heartbeat.py); stale or missing file = unhealthy.
+# Surfaces in `docker ps` and the Unraid dashboard.
+HEALTHCHECK --interval=60s --timeout=10s --start-period=90s --retries=3 \
+    CMD ["python", "-c", "import os,sys,time; sys.exit(0 if time.time() - os.stat('/tmp/unraidmonitor-heartbeat').st_mtime < 180 else 1)"]
+
 # Container starts as root; entrypoint drops to PUID:PGID after fixing permissions
 ENTRYPOINT ["/entrypoint.sh"]
 CMD ["python", "-m", "src.main"]

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unraid-monitor-bot"
-version = "0.15.1"
+version = "0.16.0"
 requires-python = ">=3.11"
 dependencies = [
     "docker>=7.0.0,<8.0.0",
@@ -9,7 +9,10 @@ dependencies = [
     "pydantic>=2.0,<3.0",
     "pydantic-settings>=2.0,<3.0",
     "psutil>=6.1.0,<8.0.0",
-    "aiohttp>=3.9.0,<4.0.0",
+    # aiogram caps aiohttp <3.14; CVE-2026-34993/CVE-2026-47265 (fixed in 3.14)
+    # are not exploitable here (no CookieJar.load, no per-request cookies) —
+    # ignored in CI pip-audit. Lift floor to >=3.14 when aiogram allows it.
+    "aiohttp>=3.13.5,<4.0.0",
     "python-dotenv>=1.0.0,<2.0.0",
 ]
 

requirements.txt

@@ -3,7 +3,7 @@
 # the Docker image so all features work out of the box.
 docker>=7.0.0,<8.0.0
 aiogram>=3.4.0,<4.0.0
-aiohttp>=3.9.0,<4.0.0
+aiohttp>=3.13.5,<4.0.0
 pyyaml>=6.0,<7.0
 pydantic>=2.0,<3.0
 pydantic-settings>=2.0,<3.0

src/__init__.py

@@ -1 +1 @@
-__version__ = "0.15.1"
+__version__ = "0.16.0"

src/alert_proxy.py

@@ -30,12 +30,15 @@ def __init__(self, bot: Bot, chat_id_store: ChatIdStore, error_display_max_chars
         self.chat_id_store = chat_id_store
         self.error_display_max_chars = error_display_max_chars
         self._queued_alerts: list[tuple[str, dict[str, Any]]] = []
+        # Queued alerts that failed every chat on their first flush get one
+        # more attempt on the next flush before being dropped.
+        self._retry_alerts: list[tuple[str, dict[str, Any]]] = []
         self._managers: dict[int, AlertManager] = {}
         self._send_lock = asyncio.Lock()
 
     @property
     def queued_count(self) -> int:
-        return len(self._queued_alerts)
+        return len(self._queued_alerts) + len(self._retry_alerts)
 
     def _get_manager(self, chat_id: int) -> AlertManager:
         """Get or create a cached AlertManager for the given chat_id."""
@@ -56,7 +59,7 @@ async def _send_alert(self, method_name: str, **kwargs: Any) -> None:
         if chat_ids:
             async with self._send_lock:
                 # Flush any queued alerts first
-                if self._queued_alerts:
+                if self._queued_alerts or self._retry_alerts:
                     await self._flush_queue(chat_ids)
                 for chat_id in chat_ids:
                     try:
@@ -66,24 +69,42 @@ async def _send_alert(self, method_name: str, **kwargs: Any) -> None:
                         logger.error(f"Failed to send alert to {chat_id}: {e}")
                 await asyncio.sleep(self._SEND_DELAY)
         else:
-            if len(self._queued_alerts) < self.MAX_QUEUED:
-                self._queued_alerts.append((method_name, kwargs))
+            entry = (method_name, kwargs)
+            if self._queued_alerts and self._queued_alerts[-1] == entry:
+                logger.info(f"Skipping duplicate queued {method_name.replace('_', ' ')}")
+            elif len(self._queued_alerts) < self.MAX_QUEUED:
+                self._queued_alerts.append(entry)
                 logger.info(f"Queued {method_name.replace('_', ' ')} (no chat ID yet, {len(self._queued_alerts)} queued)")
             else:
                 logger.warning(f"Alert queue full, dropping {method_name.replace('_', ' ')}")
 
     async def _flush_queue(self, chat_ids: set[int]) -> None:
-        """Deliver all queued alerts to all chat IDs."""
-        queued = self._queued_alerts[:]
-        self._queued_alerts.clear()
-        logger.info(f"Flushing {len(queued)} queued alerts to {len(chat_ids)} users")
-        for method_name, kwargs in queued:
+        """Deliver all queued alerts to all chat IDs.
+
+        An alert counts as delivered once any chat receives it. Alerts that
+        fail every chat (e.g. Telegram still flaky right after /start) are
+        kept for one retry on the next flush, then dropped.
+        """
+        retrying = self._retry_alerts
+        fresh = self._queued_alerts
+        self._retry_alerts = []
+        self._queued_alerts = []
+        logger.info(f"Flushing {len(retrying) + len(fresh)} queued alerts to {len(chat_ids)} users")
+        for entry, is_retry in [(e, True) for e in retrying] + [(e, False) for e in fresh]:
+            method_name, kwargs = entry
+            delivered = False
             for chat_id in chat_ids:
                 try:
                     manager = self._get_manager(chat_id)
                     await getattr(manager, method_name)(**kwargs)
+                    delivered = True
                 except Exception as e:
                     logger.error(f"Failed to send queued alert to {chat_id}: {e}")
+            if not delivered:
+                if is_retry:
+                    logger.warning(f"Dropping queued {method_name.replace('_', ' ')} after failed retry")
+                else:
+                    self._retry_alerts.append(entry)
 
     async def send_crash_alert(
         self,

src/bot/manage_command.py

@@ -702,14 +702,20 @@ def feat_heal_save_callback(
     async def handler(callback: CallbackQuery) -> None:
         user_id = callback.from_user.id if callback.from_user else 0
         selected = sorted(selection_state.get(user_id))
+        saved = selected
         if auto_heal_config is not None:
             auto_heal_config.set_containers(selected)
+            saved = list(auto_heal_config.containers)
         selection_state.clear(user_id)
 
-        count = len(selected)
-        await callback.answer(
-            f"Auto-heal {'on for ' + str(count) + ' container(s)' if count else 'disabled'}"
-        )
+        count = len(saved)
+        answer = f"Auto-heal {'on for ' + str(count) + ' container(s)' if count else 'disabled'}"
+        # set_containers drops names that fail validation — unreachable via the
+        # picker, but if it ever happens the user should hear about it.
+        dropped = len(selected) - len(saved)
+        if dropped:
+            answer += f" ({dropped} invalid name(s) skipped)"
+        await callback.answer(answer)
         if callback.message:
             text, keyboard = _build_features_view(image_update_monitor, auto_heal_config)
             await safe_edit(callback.message, text, reply_markup=keyboard)