feat(notifications): JSON-safe webhook template, SMTP timeout and implicit TLS, test-send buttons (#5064)

#5064 "Notifications that arrive":
- render_webhook: alert.* is escaped to sit inside a JSON string (a quote
  or newline in a rule name no longer breaks the body); raw.* is the plain
  value for |tojson; a missing value reads "no data"; the template runs
  sandboxed and the body is checked to be JSON before it is sent.
- SMTP: 15s timeout; port 465 connects with implicit TLS, otherwise the
  box means STARTTLS; a From address setting (falls back to the username).
- A webhook error no longer carries the URL, which is a secret.
- Settings → Notifications: "Send a test email" / "Send a test webhook"
  send a sample alert with the form's values (unsaved) and show the result
  and the body that went out; template help names alert.* and raw.*.
- Notification audits go through audit_request; the test send is audited
  as settings.notification.tested, with the channel and outcome only.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

steward/core/notifications.py

@@ -8,7 +8,7 @@ import types
 from email.message import EmailMessage
 
 import httpx
-from jinja2 import Template
+from jinja2.sandbox import SandboxedEnvironment
 
 logger = logging.getLogger(__name__)
 
@@ -30,22 +30,37 @@ async def dispatch_notifications(
     return results
 
 
+SMTP_TIMEOUT_S = 15
+
+
+def smtp_mode(port, tls) -> str:
+    """How to talk to the SMTP server: "ssl" (implicit TLS, port 465),
+    "starttls" (upgrade a plain connection, when TLS is ticked) or "plain"."""
+    if int(port or 0) == 465:
+        return "ssl"
+    return "starttls" if tls else "plain"
+
+
+def email_body(alert: dict) -> str:
+    value = "no data" if alert.get("value") is None else alert["value"]
+    return (
+        f"Alert: {alert['state']}\n"
+        f"Rule: {alert['rule_name']}\n"
+        f"Resource: {alert['resource']}\n"
+        f"Metric: {alert['metric']} = {value}\n"
+        f"Threshold: {alert['threshold']}\n"
+        + (f"Note: {alert['note']}\n" if alert.get("note") else "")
+        + f"Time: {alert['timestamp']}\n"
+    )
+
+
 async def _send_email(cfg: dict, alert: dict) -> dict:
     try:
         msg = EmailMessage()
         msg["Subject"] = f"[Steward] {alert['state']} — {alert['rule_name']}"
-        msg["From"] = cfg.get("username", "steward@localhost")
+        msg["From"] = cfg.get("from") or cfg.get("username") or "steward@localhost"
         msg["To"] = ", ".join(cfg["recipients"])
-        value = "no data" if alert.get("value") is None else alert["value"]
-        msg.set_content(
-            f"Alert: {alert['state']}\n"
-            f"Rule: {alert['rule_name']}\n"
-            f"Resource: {alert['resource']}\n"
-            f"Metric: {alert['metric']} = {value}\n"
-            f"Threshold: {alert['threshold']}\n"
-            + (f"Note: {alert['note']}\n" if alert.get("note") else "")
-            + f"Time: {alert['timestamp']}\n"
-        )
+        msg.set_content(email_body(alert))
         loop = asyncio.get_running_loop()
         await loop.run_in_executor(None, _smtp_send_sync, cfg, msg)
         return {"sent": True, "error": None}
@@ -55,37 +70,59 @@ async def _send_email(cfg: dict, alert: dict) -> dict:
 
 
 def _smtp_send_sync(cfg: dict, msg: EmailMessage) -> None:
-    ctx = ssl.create_default_context() if cfg.get("tls", True) else None
-    with smtplib.SMTP(cfg["host"], cfg.get("port", 587)) as smtp:
-        if ctx:
+    port = int(cfg.get("port") or 587)
+    mode = smtp_mode(port, cfg.get("tls", True))
+    ctx = ssl.create_default_context()
+    if mode == "ssl":
+        smtp = smtplib.SMTP_SSL(cfg["host"], port, timeout=SMTP_TIMEOUT_S, context=ctx)
+    else:
+        smtp = smtplib.SMTP(cfg["host"], port, timeout=SMTP_TIMEOUT_S)
+    with smtp:
+        if mode == "starttls":
             smtp.starttls(context=ctx)
         if cfg.get("username"):
             smtp.login(cfg["username"], cfg.get("password", ""))
         smtp.send_message(msg)
 
 
-async def _send_webhook(cfg: dict, alert: dict) -> dict:
-    template_str = cfg.get(
-        "template",
-        '{"content": "{{ alert.state }} — {{ alert.rule_name }}"}',
-    )
+def _json_str(value) -> str:
+    """A value as it may sit between the quotes of a JSON string."""
+    return json.dumps("" if value is None else str(value))[1:-1]
 
-    # Render Jinja2 template with alert as a namespace object (attribute access)
+
+def render_webhook(template_str: str, alert: dict) -> str:
+    """The webhook body for an alert, checked to be JSON.
+
+    In the template, `alert.<field>` is escaped to sit inside a JSON string
+    ("{{ alert.rule_name }}" stays valid whatever the name holds), with a
+    missing value reading "no data"; `raw.<field>` is the plain value for use
+    with |tojson ({{ raw.value | tojson }} gives a number or null). The
+    template runs sandboxed. ValueError says why a body could not be made.
+    """
+    shown = dict(alert)
+    if shown.get("value") is None:
+        shown["value"] = "no data"
+    env = SandboxedEnvironment()
     try:
-        alert_ns = types.SimpleNamespace(**alert)
-        rendered = Template(template_str).render(alert=alert_ns)
+        rendered = env.from_string(template_str).render(
+            alert=types.SimpleNamespace(**{k: _json_str(v) for k, v in shown.items()}),
+            raw=types.SimpleNamespace(**alert))
     except Exception as exc:
-        error = f"Template render failed: {exc}"
-        logger.error(error)
-        return {"sent": False, "error": error}
-
-    # Validate JSON before sending
+        raise ValueError(f"Template render failed: {exc}") from None
     try:
         json.loads(rendered)
     except json.JSONDecodeError as exc:
-        error = f"Rendered webhook template is not valid JSON: {exc}"
-        logger.error(error)
-        return {"sent": False, "error": error}
+        raise ValueError(f"Rendered webhook template is not valid JSON: {exc}") from None
+    return rendered
+
+
+async def _send_webhook(cfg: dict, alert: dict) -> dict:
+    template_str = cfg.get("template") or '{"content": "{{ alert.state }} — {{ alert.rule_name }}"}'
+    try:
+        rendered = render_webhook(template_str, alert)
+    except ValueError as exc:
+        logger.error(str(exc))
+        return {"sent": False, "error": str(exc)}
 
     try:
         async with httpx.AsyncClient(timeout=10) as client:
@@ -97,6 +134,8 @@ async def _send_webhook(cfg: dict, alert: dict) -> dict:
             response.raise_for_status()
         return {"sent": True, "error": None}
     except Exception as exc:
-        error = str(exc)
+        # The URL is a secret (it usually carries its own token) and httpx
+        # puts it in its error messages.
+        error = str(exc).replace(cfg["url"], "<webhook URL>")
         logger.error(f"Webhook notification failed: {error}")
         return {"sent": False, "error": error}

steward/core/settings.py

@@ -55,6 +55,7 @@ DEFAULTS: dict[str, Any] = {
     "smtp.username": "",
     "smtp.password": "",
     "smtp.recipients": [],
+    "smtp.from": "",
     "webhook.url": "",
     "webhook.template": _DEFAULT_WEBHOOK_TEMPLATE,
     "ansible.sources": [],
@@ -370,6 +371,7 @@ def to_smtp_cfg(settings: dict[str, Any]) -> dict:
         "username": settings.get("smtp.username", ""),
         "password": settings.get("smtp.password", ""),
         "recipients": settings.get("smtp.recipients", []),
+        "from": settings.get("smtp.from", ""),
     }
 
 

steward/settings/routes.py

@@ -5,7 +5,7 @@ from pathlib import Path
 from quart import Blueprint, current_app, render_template, request, redirect, url_for, session
 
 from steward.auth.middleware import require_role
-from steward.core.audit import log_audit
+from steward.core.audit import audit_request, log_audit
 from steward.models.users import UserRole
 from steward.core.settings import (
     get_all_settings, set_setting, delete_setting,
@@ -229,17 +229,86 @@ async def save_notifications():
             if form.get("smtp.password"):
                 await set_setting(db, "smtp.password", form.get("smtp.password"))
             await set_setting(db, "smtp.recipients", recipients)
+            await set_setting(db, "smtp.from", form.get("smtp.from", "").strip())
             if "webhook.remove" in form:
                 await set_setting(db, "webhook.url", "")
             elif form.get("webhook.url", "").strip():
                 await set_setting(db, "webhook.url", form.get("webhook.url").strip())
             await set_setting(db, "webhook.template", form.get("webhook.template", ""))
     await _reload_app_config()
-    await log_audit(current_app, session.get("user_id"), session.get("username", ""),
-                    "settings.saved", detail={"section": "notifications"})
+    await audit_request("settings.saved", detail={"section": "notifications"})
     return redirect(url_for("settings.notifications"))
 
 
+def _sample_alert() -> dict:
+    """What a test notification carries: a made-up firing alert whose name
+    has quotes in it, so a template that cannot take them shows it."""
+    from datetime import datetime, timezone
+    return {"rule_name": 'Test alert "from" Steward', "state": "TEST", "metric": "cpu_pct",
+            "value": 97.5, "threshold": 90.0, "resource": "example-host",
+            "source_module": "host_agent", "note": "sent from Settings → Notifications",
+            "timestamp": datetime.now(timezone.utc).isoformat()}
+
+
+async def _notify_test_result(channel: str, ok: bool, result: str, payload: str | None = None):
+    await audit_request("settings.notification.tested", detail={"channel": channel, "sent": ok})
+    return await render_template("settings/_notify_test.html", ok=ok, result=result,
+                                 payload=payload)
+
+
+@settings_bp.post("/notifications/test-webhook")
+@require_role(UserRole.admin)
+async def test_webhook():
+    """Render the webhook template (as in the form, unsaved) for a sample
+    alert and send it to the URL in the form, or the saved one."""
+    from steward.core.notifications import _send_webhook, render_webhook
+    form = await request.form
+    async with current_app.db_sessionmaker() as db:
+        saved = to_webhook_cfg(await get_all_settings(db))
+    url = (form.get("webhook.url") or "").strip() or saved["url"]
+    template = form.get("webhook.template") or saved["template"]
+    alert = _sample_alert()
+    try:
+        payload = render_webhook(template, alert)
+    except ValueError as exc:
+        return await _notify_test_result("webhook", False, str(exc))
+    if not url:
+        return await _notify_test_result(
+            "webhook", False, "No webhook URL is saved or entered. This is the body it would get.",
+            payload)
+    sent = await _send_webhook({"url": url, "template": template}, alert)
+    return await _notify_test_result(
+        "webhook", sent["sent"], "Delivered." if sent["sent"] else sent["error"], payload)
+
+
+@settings_bp.post("/notifications/test-email")
+@require_role(UserRole.admin)
+async def test_email():
+    """Send a sample alert email using the SMTP settings in the form (unsaved);
+    a blank password uses the saved one."""
+    from steward.core.notifications import _send_email, email_body, smtp_mode
+    form = await request.form
+    async with current_app.db_sessionmaker() as db:
+        saved = to_smtp_cfg(await get_all_settings(db))
+    try:
+        port = int(form.get("smtp.port") or 587)
+    except ValueError:
+        return await _notify_test_result("email", False, "The port must be a number.")
+    cfg = {"host": (form.get("smtp.host") or "").strip(), "port": port,
+           "tls": "smtp.tls" in form, "username": form.get("smtp.username", ""),
+           "password": form.get("smtp.password") or saved["password"],
+           "from": (form.get("smtp.from") or "").strip(),
+           "recipients": [r.strip() for r in form.get("smtp.recipients", "").split(",") if r.strip()]}
+    if not cfg["host"] or not cfg["recipients"]:
+        return await _notify_test_result("email", False, "Enter an SMTP host and at least one recipient.")
+    alert = _sample_alert()
+    sent = await _send_email(cfg, alert)
+    how = {"ssl": "implicit TLS", "starttls": "STARTTLS", "plain": "no TLS"}[smtp_mode(port, cfg["tls"])]
+    result = (f"Sent to {', '.join(cfg['recipients'])} via {cfg['host']}:{port} ({how})."
+              if sent["sent"] else f"{cfg['host']}:{port} ({how}): {sent['error']}")
+    return await _notify_test_result("email", sent["sent"], result, email_body(alert))
+
+
 # ── Ansible Sources ───────────────────────────────────────────────────────────
 
 async def _get_ansible_sources() -> list[dict]:

steward/templates/settings/_notify_test.html

@@ -0,0 +1,8 @@
+{# settings/_notify_test.html — result of a test send from Settings → Notifications #}
+<div class="alert {% if ok %}alert-success{% else %}alert-error{% endif %}" style="margin:0.75rem 0 0;">
+  {{ result }}
+</div>
+{% if payload %}
+<p style="font-size:0.75rem;color:var(--text-muted);margin:0.5rem 0 0.2rem;">What was sent:</p>
+<pre style="font-family:ui-monospace,monospace;font-size:0.8rem;white-space:pre-wrap;word-break:break-word;margin:0;">{{ payload }}</pre>
+{% endif %}

steward/templates/settings/notifications.html

@@ -28,9 +28,11 @@
       <div class="form-group" style="display:flex;align-items:center;gap:0.5rem;padding-top:1.5rem;">
         <input type="checkbox" name="smtp.tls" id="smtp-tls"
                {% if settings['smtp.tls'] %}checked{% endif %}>
-        <label for="smtp-tls" style="margin:0;">Use TLS</label>
+        <label for="smtp-tls" style="margin:0;">Use STARTTLS</label>
       </div>
     </div>
+    <p style="font-size:0.75rem;color:var(--text-muted);margin:-0.5rem 0 1rem;">
+      Port 465 always connects with implicit TLS; on other ports the box upgrades the connection with STARTTLS.</p>
 
     <div class="form-group">
       <label>Username</label>
@@ -43,12 +45,23 @@
       <input type="password" name="smtp.password" placeholder="••••••••" autocomplete="new-password">
     </div>
 
+    <div class="form-group">
+      <label>From address <span style="color:var(--text-muted);font-size:0.8rem;">(blank uses the username)</span></label>
+      <input type="text" name="smtp.from" value="{{ settings['smtp.from'] }}"
+             placeholder="steward@example.com">
+    </div>
+
     <div class="form-group">
       <label>Recipients <span style="color:var(--text-muted);font-size:0.8rem;">(comma-separated)</span></label>
       <input type="text" name="smtp.recipients"
              value="{{ settings['smtp.recipients'] | join(', ') }}"
              placeholder="admin@example.com, ops@example.com">
     </div>
+
+    <button type="button" class="btn btn-ghost" hx-post="/settings/notifications/test-email"
+            hx-include="closest form" hx-target="#email-test-result" hx-swap="innerHTML">
+      Send a test email</button>
+    <div id="email-test-result"></div>
   </div>
 
   {# ── Webhook ───────────────────────────────────────────────────────────── #}
@@ -73,7 +86,17 @@
       <label>Payload template <span style="color:var(--text-muted);font-size:0.8rem;">(Jinja2, must produce valid JSON)</span></label>
       <textarea name="webhook.template" rows="4"
                 style="font-family:ui-monospace,monospace;font-size:0.85rem;">{{ settings['webhook.template'] }}</textarea>
+      <p style="font-size:0.75rem;color:var(--text-muted);margin-top:0.2rem;">
+        <code>{{ '{{ alert.rule_name }}' }}</code> is escaped to sit inside a JSON string, so quotes or
+        line breaks in a name can't break the body; a missing value reads "no data".
+        For a bare JSON value use <code>{{ '{{ raw.value | tojson }}' }}</code> (a number, or null).
+        Fields: state, rule_name, resource, metric, value, threshold, source_module, note, timestamp.</p>
     </div>
+
+    <button type="button" class="btn btn-ghost" hx-post="/settings/notifications/test-webhook"
+            hx-include="closest form" hx-target="#webhook-test-result" hx-swap="innerHTML">
+      Send a test webhook</button>
+    <div id="webhook-test-result"></div>
   </div>
 
 </div>