~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
fix(security): validate effective notification destinations (#7004)
LearningCircuit33bef5eaa49e
diff --git a/SECURITY.md b/SECURITY.mdindex 7dc63f35b7..736b9e6fbc 100644--- a/SECURITY.md+++ b/SECURITY.md@@ -115,19 +115,19 @@ docker run --cap-add IPC_LOCK -e LDR_DB_CONFIG_CIPHER_MEMORY_SECURITY=ON ...### Notification Webhook SSRF-**Outbound notifications via Apprise are disabled by default.** To enable them, the operator must set `LDR_NOTIFICATIONS_ALLOW_OUTBOUND=true` in the server environment. This gate is retained as defense-in-depth: the send-time DNS-rebinding window described below is now closed in code, but the env-only gate keeps turning outbound notifications on an explicit operator decision rather than something any logged-in user can flip via the settings API.+**Outbound notifications via Apprise are disabled by default.** To enable them, the operator must set `LDR_NOTIFICATIONS_ALLOW_OUTBOUND=true` in the server environment. The send-time guards below restrict DNS rebinding and metadata access. The env-only gate keeps outbound delivery an explicit operator decision rather than something any logged-in user can enable via the settings API.-#### The rebinding window and how it is closed+#### Validation and send-time DNS guardsLDR validates user-configured notification service URLs (`NotificationURLValidator`) before handing them to Apprise. Hostnames are resolved once at validation time and the resulting IPs are checked against private/internal ranges. Apprise (and its underlying `requests`/`urllib3` stack) then resolves the hostname *again* when it sends — a classic **DNS-rebinding resolve-vs-connect TOCTOU**: an attacker controlling a domain could serve a public IP to the validator and a private/metadata IP to Apprise's send-time resolver, reaching internal services on the LDR server (e.g., `127.0.0.1:<internal-port>`) or cloud-metadata (`169.254.169.254`).-This window is closed at the socket layer for the delivery path. The deliverable raw-webhook schemes are `json://`, `xml://`, and `form://` (Apprise rejects bare `http(s)://` notification URLs at `add()`, so those never actually deliver); other plugin schemes (`discord://`, `ntfy://`, `gotify://`, …) reach their own hardcoded or self-hosted endpoints.+LDR guards synchronous delivery at the socket-resolution layer, rather than relying on validation-time DNS answers alone. The deliverable raw-webhook schemes are `json://`, `xml://`, and `form://` (Apprise rejects bare `http(s)://` notification URLs at `add()`, so those never actually deliver); other plugin schemes (`discord://`, `ntfy://`, `gotify://`, …) reach their own hardcoded or self-hosted endpoints.- **Synchronous, in-thread delivery.** The notification service builds its Apprise instances with `AppriseAsset(async_mode=False)`, so every plugin's `notify()` runs in the sending thread rather than a `ThreadPoolExecutor` worker. This is what lets the thread-local guards below apply to Apprise's own resolution.- **Redirect-following disabled → the redirect attack class is closed.** The Apprise instances are built with `AppriseAsset(http_redirects=False)`, and each parsed plugin additionally has its `redirects` flag re-forced to `False` after `add()` so a user-supplied `?redirect=yes` query parameter cannot override the default. A user-configured webhook therefore can no longer 30x-redirect the send to a private/loopback host **or** to an arbitrary public host for data exfiltration — the send is simply not redirected. Redirect-following is never needed for legitimate webhook delivery (endpoints answer 2xx directly). Most plugins honour the per-plugin flag (`allow_redirects=self.redirects`), including the raw-webhook `json`/`xml`/`form` schemes and `ntfy`/`gotify`; a few (e.g. `matrix://`) issue their HTTP calls without threading that flag through, so the per-plugin re-force does not reach them — for those the **block-private send window** below is the backstop that still refuses a redirect/rebind to a blocked address at the socket layer.- **Pin the validated address → the original host's rebind is closed.** Each `notify()` is wrapped in `dns_pinning.pinned_notification_send` (see the general fetch path below), which **pins** every raw-webhook host in the batch to the address just validated. `requests`/`urllib3` cannot then connect to a rebind target: the address validated is the address connected to.-- **Block-private send window.** For the duration of the send a thread-local **block-private** mode also refuses any *unpinned* lookup (a plugin scheme's endpoint) that resolves to a private/loopback/link-local/cloud-metadata address, at the `getaddrinfo` layer before any socket is opened. The check runs on the very resolution the client is about to connect to, so there is no residual race. That send-time resolution is bounded by a timeout so a slow / hostile DNS authority cannot hang the sending thread — a timeout fails closed (refuses the send). The bounded lookup runs on a short-lived daemon thread that is abandoned (not force-killed) on timeout, so a sustained hostile-DNS attack against an outbound-enabled instance can accumulate a small number of parked daemon threads (each blocked in libc `getaddrinfo`) before the send gives up; this is a bounded resource cost, not a bypass — the send is still refused.-- **Per-scheme policy, matching the validator.** `http`/`https` block private + metadata unless the operator set `LDR_NOTIFICATIONS_ALLOW_PRIVATE_IPS=true`; plugin and raw-webhook schemes (`json://`, `xml://`, `form://`, `discord://`, `ntfy://`, `gotify://`, …) allow private/LAN targets (self-hosted notifiers keep working) but **always** block cloud-metadata **and the entire link-local range** (IPv4 `169.254.0.0/16`, IPv6 `fe80::/10`) regardless of any operator flag. The link-local block matters because cloud-provider metadata lives across the whole link-local range, not just the always-blocked literals (e.g. Scaleway serves instance metadata at `169.254.42.42`), and no legitimate self-hosted notifier lives on link-local. It is scoped to the plugin/raw-webhook partition: RFC1918, CGNAT, loopback, and non-link-local IPv6 ULA self-hosted notifiers are unaffected, and `http`/`https` still treats link-local as operator-recoverable via `LDR_NOTIFICATIONS_ALLOW_PRIVATE_IPS`. It is threaded end-to-end (a `block_link_local` flag on `is_ip_blocked` / `pinned_notification_send` and the validator's plugin-scheme IMDS guard) rather than changing `is_ip_blocked`'s default, so the general fetch/LLM paths keep their existing link-local-under-`allow_private_ips` behaviour. TLS is unaffected: only name resolution is redirected, so SNI and certificate verification still use the original hostname.+- **Destination-specific send window.** For the duration of the send a thread-local DNS guard checks each *unpinned* lookup (including a plugin endpoint) at `getaddrinfo` before any socket is opened. Private/loopback addresses require the operator's `LDR_NOTIFICATIONS_ALLOW_PRIVATE_IPS=true` opt-in for every partition, including fixed vendor endpoints (whose only private lookup is normally a forward proxy named by `HTTPS_PROXY`); link-local and cloud-metadata addresses remain blocked. The check runs on the very resolution the client is about to connect to, so there is no residual race. That send-time resolution is bounded by a timeout so a slow / hostile DNS authority cannot hang the sending thread — a timeout fails closed (refuses the send). The bounded lookup runs on a short-lived daemon thread that is abandoned (not force-killed) on timeout, so a sustained hostile-DNS attack against an outbound-enabled instance can accumulate a small number of parked daemon threads (each blocked in libc `getaddrinfo`) before the send gives up; this is a bounded resource cost, not a bypass — the send is still refused.+- **Effective-destination policy, matching the validator.** HTTP URLs and authority-bearing plugins (`json://`, `xml://`, `form://`, `signal://`, `gotify://`, `mattermost://`, `rocketchat://`, `mailto://`, ntfy private mode, and Matrix homeserver/webhook modes) block RFC1918, CGNAT, loopback and ULA addresses unless the operator sets `LDR_NOTIFICATIONS_ALLOW_PRIVATE_IPS=true`. Cloud metadata and the entire link-local range (IPv4 `169.254.0.0/16`, IPv6 `fe80::/10`) are blocked for every notification destination even with opt-in, `http(s)://` included: Apprise converts some `http(s)://` URLs into plugins that post to the URL host (for example the Apprise API and Workflows plugins). Fixed vendor endpoints such as Discord, Telegram, ntfy cloud and Matrix t2bot never resolve a token/topic as a host; their send guard is public-only unless the operator opt-in is set. Percent escapes are refused in plugin authority hosts, because several Apprise plugins decode them into a different host, and IPv6 zone identifiers are refused in every notification host. An IPv6 literal host is also refused when the plugin Apprise builds from the URL names a different address: Apprise 1.13's URL parser rewrites compressed literals (`json://[fd00::1]/hook` is sent to `[fd00::]`), so the address LDR checked would not be the address Apprise connects to; the fully written lowercase form (`[fd00:0:0:0:0:0:0:1]`) is kept as written. The port is compared as well: Apprise drops the port of a literal written with uppercase hex digits (`json://[FD00:0:0:0:0:0:0:1]:8080/hook` is sent to port 80), so such a URL is refused. When the notification is dispatched, the user's egress scope is evaluated against the effective host of every `http(s)://` URL and authority plugin: the strict and local-only scopes allow only a private host, a public-only scope allows only a public host, the internal both scope allows any host it can classify, and an unprotected scope allows any host except cloud metadata. Two kinds of authority URL are refused under the strict and local-only scopes whatever their host: `mailto://`, because Apprise's mail plugin can connect to a built-in provider's fixed SMTP host instead of the URL authority, and Matrix homeserver/webhook modes. Apprise runs Matrix server discovery only for `matrixs://`, which LDR does not accept, so a `matrix://` send goes to its URL host; the Matrix refusal is a conservative choice rather than a discovery defence. Fixed vendor endpoints, Matrix t2bot and ntfy cloud included, are refused only under the local-only scope and pass every other scope without a host check. Under a public-only scope, a later DNS answer that names a private address is checked by the send-time guard, so it depends on the operator opt-in rather than on the scope. TLS still uses the original hostname for SNI and certificate checks.- **Fail-closed invariants.** The send is refused (never sent unguarded) if the `getaddrinfo` shim is not the active resolver, or if the Apprise instance is not synchronous, or if a `tag` is supplied — any of which would let delivery fan out to worker threads the thread-local guards do not cover. A confirmed security block is **not retried**: the pin's connect-time rebind catch raises a non-retryable error directly, and a block-private window refusal (which Apprise swallows into a generic delivery failure) is recognised after the failed send via a thread-local marker and re-raised non-retryably — so a hostile / misconfigured destination fails fast in one attempt instead of being retried three times against a slow DNS authority. Invariant violations likewise fail fast.- **Unsafe query options rejected before DNS or `Apprise.add()`.** Apprise query parameters can select a *second* destination or resource that the authority check above never sees. The validator rejects `template` (consumed by Discord/Slack/Workflows as an unrestricted `AppriseAttachment`, which reads local files — `?template=/etc/passwd` — or fetches remote URLs) and `redirect` (which would override the hardened asset setting), plus the mail-specific `smtp` (replaces the actual SMTP host), `pgppub`/`pgpkey`/`pgpprv` (unrestricted key-file attachments), and `wkd` (derives HTTPS fetches from a recipient-controlled domain). Key parsing mirrors Apprise's own `parse_qsd` semantics — `&` and `;` separators, `+`-as-space, one round of percent-decoding, lowercasing, and duplicate keys — so an encoded or semicolon-smuggled key cannot slip past the policy; a malformed percent escape in a key is rejected outright. `apprise>=1.12.0,<2` is declared with 1.12.0 as the reviewed floor, and a test diffs LDR's canonical keys against the *installed* Apprise parser so a future release that changes those semantics fails CI rather than silently opening a bypass.- **Validation-time DNS is still fail-open.** A DNS error or five-second timeout at validation time is allowed (matching historical behavior), so Apprise may perform the first successful resolution at send time. That path is covered by the send-time pin and block-private window above, which are fail-closed.@@ -142,10 +142,10 @@ LDR_NOTIFICATIONS_ALLOW_OUTBOUND=trueBy setting this, the operator acknowledges the residual risk above. To minimise it:- **Prefer a fixed-destination mode when it fits the target.** Against Apprise 1.12.0 (the reviewed dependency floor), `discord://` and `slack://` send to fixed service endpoints after LDR rejects their secondary `template` resource. ntfy cloud mode (`ntfy://<topic>`) sends to `https://ntfy.sh`, and Matrix t2bot mode (`matrix://<64-character-token>`) sends to `https://webhooks.t2bot.io`. Their authority fields are tokens/topics, not send hosts, so authority DNS manipulation cannot redirect the notification.- - **Destination behaviour is URL-mode-dependent.** `signal://`, `gotify://`, ntfy private mode (`ntfy://` or `ntfys://` with `<host>/<topic>?mode=private`), Matrix server/webhook mode, `json://`, `xml://`, and `form://` send to a user-supplied authority host. `mailto://` sends either to an authority subject to the same best-effort screening or to Apprise's fixed built-in SMTP mapping for a recognized provider; the user-controlled `smtp` override is rejected. These modes retain the DNS resolution window described above. Apprise may also translate recognized native `http(s)://` service URLs into plugins; the same query restrictions and redirect policy apply before conversion.+ - **Destination behaviour is URL-mode-dependent.** `signal://`, `gotify://`, ntfy private mode (`ntfy://` or `ntfys://` with `<host>/<topic>` or `<host>?to=<topic>`, optionally `?mode=private`; without `mode=cloud`, Apprise selects it only for a host it considers valid with a non-empty topic in the path or `to=`; LDR reads the mode from Apprise's own parsed plugin, and otherwise treats the URL as ntfy cloud), Matrix server/webhook mode, `json://`, `xml://`, and `form://` send to a user-supplied authority host. `mailto://` sends either to an authority subject to validation-time screening or to Apprise's fixed built-in SMTP mapping for a recognized provider. LDR builds Apprise's mail plugin to check this and rejects a URL whose SMTP host is neither: Apprise discards an authority it does not accept as a hostname (for example one with an empty port) and then takes the SMTP host from an e-mail address in the userinfo or `?user=`. The user-controlled `smtp` override is rejected. These modes remain subject to the send-time DNS guard: private LAN access requires the operator opt-in, while link-local and metadata destinations stay blocked. Apprise may also translate recognized native `http(s)://` service URLs into plugins; the same query restrictions and redirect policy apply before conversion.- **Direct scheme-prefix gap.** LDR's allowlist names `tgram`, so direct Telegram URLs work. Apprise 1.12.0 registers `pover`, `workflow`/`workflows`, `mmost`/`mmosts`, and `rocket`/`rockets`, while LDR's direct-scheme allowlist still names `pushover`, `teams`, `mattermost`, and `rocketchat`. LDR performs no alias translation, so those four direct plugin prefixes do not overlap. Native service `http(s)://` URLs are a separate Apprise conversion path; see `docs/NOTIFICATIONS.md` and use the Test button rather than assuming a direct alias works.- - **Validation-time screening is attempted for every allowed plugin scheme.** A non-literal authority gets exactly one lookup via `_resolve_hostname_ips` inside the Phase 1 plugin IMDS guard; successful answers are screened and any cloud-metadata result is blocked. A DNS failure or timeout is allowed. IP literals are checked directly with no resolver call. Token/topic modes receive the same attempted screening even though Apprise does not send to that authority. This does not close the host-bearing modes' DNS resolution window because Apprise resolves their host when sending.-- **Restrict egress** if private-network exposure is a concern: deploy LDR behind an egress-restricted network so that even a successful rebinding cannot reach internal services.+ - **Validation-time screening follows the effective destination.** A host-bearing plugin gets one lookup after structural checks; successful answers are screened for private and metadata addresses. A DNS failure or timeout is allowed at validation time, but the send-time guard still applies. IP literals need no lookup. Fixed vendor tokens/topics are never resolved as hosts.+- **Restrict egress** for an additional network boundary. The guards apply to resolution through LDR's active `getaddrinfo` shim in the sending thread; a forward proxy chooses its own target addresses and needs equivalent egress restrictions.The general HTTP fetch path (`safe_requests`, used for RAG sources and web scraping) resolves the hostname and connects to that **same** validated address: `security.dns_pinning` pins the resolved IP for the outbound connection (re-resolving and re-validating at connect time, and re-pinning at every redirect hop) so `requests`/`urllib3` cannot connect to a different address than the one the guard checked. The request keeps the original hostname, so TLS SNI and certificate verification are unchanged — only name resolution is pinned. The notification path above reuses this same shim (via `pinned_notification_send`, plus the block-private window for unpinned plugin-endpoint hosts) — but with redirect-following disabled outright rather than validated hop-by-hop, since a notification webhook has no legitimate need to follow redirects. It still does not apply to callers that hand a URL to an external client that re-resolves on its own with no in-thread `getaddrinfo` interception (LLM SDKs — see "LLM Provider URL Validation"); for those, egress restriction remains the primary defense. It also does not apply when `requests` is configured to use a forward proxy (`HTTP(S)_PROXY` / `trust_env`): `urllib3` then resolves the *proxy* host rather than the target, so target-IP selection is delegated to the proxy and the pin is a safe no-op (the pre-connection `validate_url` check still runs).@@ -194,7 +194,7 @@ Both `ssrf_validator.validate_url` and `NotificationURLValidator.validate_servicThe block also catches IPv6-wrapped forms of the IPv4 metadata IPs. When an IPv6 destination falls in a NAT64 prefix (`64:ff9b::/96` RFC 6052 well-known or `64:ff9b:1::/48` RFC 8215 local-use), the validator extracts the embedded IPv4 from the low 32 bits and matches it against this set — so `[64:ff9b::a9fe:a9fe]` cannot reach `169.254.169.254` even on a host with NAT64 routes configured. The check fires before any opt-in carve-out, so the operator switch described below cannot license IMDS exposure.-Both `ssrf_validator.is_ip_blocked` and `NotificationURLValidator.validate_service_url` enforce this absolutely, including under `allow_private_ips=True`. The latter flag is an operator opt-in for self-hosted webhooks on internal networks (RFC1918, CGNAT, loopback, link-local, IPv6 ULA); it does NOT extend to metadata IPs or NAT64-wrapped metadata. Both validators delegate to the same `is_ip_blocked` helper to keep the absolute-block invariant in lockstep. One scoped exception applies on top of this shared block: the **notification plugin/raw-webhook partition** additionally blocks the *entire* link-local range even under `allow_private_ips=True` (opt-in `block_link_local=True`), because cloud metadata is served across link-local beyond the always-blocked literals — see "Notification Webhook SSRF" above. This is scoped to that partition and does not change `is_ip_blocked`'s default (link-local remains allowed under `allow_private_ips=True` for the general fetch/LLM paths).+Both `ssrf_validator.is_ip_blocked` and `NotificationURLValidator.validate_service_url` enforce this absolutely, including under `allow_private_ips=True`. The latter flag is an operator opt-in for self-hosted webhooks on internal networks (RFC1918, CGNAT, loopback, IPv6 ULA); it does NOT extend to metadata IPs, NAT64-wrapped metadata, or the link-local range. Both validators delegate to the same `is_ip_blocked` helper to keep the absolute-block invariant in lockstep. The two differ on link-local: `NotificationURLValidator` blocks the *entire* link-local range (IPv4 `169.254.0.0/16`, IPv6 `fe80::/10`) for every host-bearing notification destination, `http(s)://` included, even under `allow_private_ips=True` (it passes `block_link_local=True` to `is_ip_blocked`), because cloud metadata is served across link-local beyond the always-blocked literals (e.g. Scaleway at `169.254.42.42`) -- see "Notification Webhook SSRF" above. `is_ip_blocked`'s own default is unchanged: link-local remains allowed under `allow_private_ips=True` for the general fetch/LLM paths that do not pass `block_link_local=True`.Future contributors must not remove entries from this set. Adding a new cloud provider's metadata IP is encouraged when a new public-cloud target appears.diff --git a/changelog.d/+notification-effective-destination.security.md b/changelog.d/+notification-effective-destination.security.mdnew file mode 100644index 0000000000..11f5a99566--- /dev/null+++ b/changelog.d/+notification-effective-destination.security.md@@ -0,0 +1 @@+Classify Apprise notification URLs by their effective outbound destination. Self-hosted and raw-webhook plugins now require the operator's `LDR_NOTIFICATIONS_ALLOW_PRIVATE_IPS=true` opt-in for private hosts, have the user's egress scope applied to the host Apprise will contact when the notification is dispatched, and retain send-time DNS checks. Under a public-only scope, a later DNS answer that names a private address is checked by the send-time guard, so it depends on the operator opt-in rather than on the scope. ntfy URLs are classified from the plugin Apprise itself builds: when Apprise selects private mode (a valid host with a non-empty topic in the path or `?to=`), that host is checked like any other self-hosted plugin; when it selects cloud mode (for example an empty `?to=` or a host Apprise considers invalid), the URL is treated as the fixed ntfy.sh endpoint, which local-only scopes refuse. Matrix URLs follow Apprise's own mode decision: its t2bot mode (for example `matrix://<token>` or `matrix://user@<token>`) is the fixed webhooks.t2bot.io endpoint, and every other mode is checked against the URL host, including rooms given as `/#room`, `/%23room` or `?to=`. `mailto://` URLs are checked against the plugin Apprise builds and are rejected when Apprise would connect to an SMTP host other than the URL authority or a built-in provider's fixed SMTP host (for example an authority with an empty port, which Apprise discards in favour of the domain of an address in the userinfo or `?user=`). Fixed vendor endpoints use the same opt-in: their sends are public-only by default, so delivery through a forward proxy on a private or loopback address (`HTTPS_PROXY`) needs `LDR_NOTIFICATIONS_ALLOW_PRIVATE_IPS=true`. Link-local addresses (`169.254.0.0/16`, `fe80::/10`) are now blocked for every notification URL, `http(s)://` included, even with that opt-in, because Apprise converts some `http(s)://` URLs into plugins that post to the URL host. Percent-encoded characters in a plugin authority host and IPv6 zone identifiers in any notification host are rejected, and the shared address check normalises IPv6 zone identifiers before the metadata check. IPv6 literal hosts that Apprise's URL parser rewrites to a different address (for example `json://[fd00::1]/hook`, which Apprise 1.13 sends to `[fd00::]`) are rejected; write the address in full, in lowercase (`json://[fd00:0:0:0:0:0:0:1]/hook`), instead. An IPv6 literal whose port Apprise drops (an uppercase literal with a port, such as `json://[FD00:0:0:0:0:0:0:1]:8080/hook`, which Apprise sends to the default port) is rejected too. Existing LAN notification setups may need that env flag after upgrading to v2, and an egress scope that permits their host: under a public-only scope (for example the adaptive default with a public primary search engine), LAN plugin destinations are refused when the notification is dispatched. The strict and local-only scopes allow only private plugin hosts, so under the strict scope a self-hosted plugin on a public host (for example `json://` or `gotify://`) is now refused like a public `http(s)://` webhook, and under the local-only scope a private self-hosted plugin is now allowed instead of being refused with the vendor schemes. `mailto://` and Matrix homeserver/webhook URLs are refused under both of those scopes whatever their host; fixed vendor endpoints, Matrix t2bot included, are still refused only under the local-only scope. The settings Test button does not apply the egress scope.diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.mdindex 99b6cbddf4..71895d0d3e 100644--- a/docs/CONFIGURATION.md+++ b/docs/CONFIGURATION.md@@ -38,7 +38,7 @@ They are not available in the Web UI because they are needed to start the applic| `LDR_DB_CONFIG_WAL_AUTOCHECKPOINT` | Integer | `250` | No | 10..10000 | WAL frames threshold for automatic PASSIVE checkpoint at commit. Lower = smaller WAL high-water-mark, faster recovery on open, slightly more frequent fsyncs. | Db Config | || `LDR_NEWS_SCHEDULER_ALLOW_API_CONTROL` | Boolean | `False` | No | | Allow authenticated users to start/stop the global news scheduler via API. Disable in multi-user deployments to prevent users from affecting each other. | News Scheduler | || `LDR_NEWS_SCHEDULER_ENABLED` | Boolean | `True` | No | | Enable or disable the news subscription scheduler | News Scheduler | |-| `LDR_NOTIFICATIONS_ALLOW_OUTBOUND` | Boolean | `False` | No | | Master switch for outbound notification webhooks (Apprise). Disabled by default because Apprise re-resolves DNS at send time, leaving a DNS-rebinding TOCTOU window that cannot be closed in code (Apprise exposes no Session/DNS hook). See SECURITY.md 'Notification Webhook SSRF' for details. Set to true only after reviewing the residual risk. Distinct from the per-user notifications.enabled toggle in the settings UI: this is the server-level operator gate, env-only so it cannot be flipped via the user-writable settings API. | Security | |+| `LDR_NOTIFICATIONS_ALLOW_OUTBOUND` | Boolean | `False` | No | | Master switch for outbound notification webhooks (Apprise). Disabled by default so outbound delivery requires an explicit operator decision. The send path uses a synchronous DNS guard against rebinding and private/metadata access; see SECURITY.md 'Notification Webhook SSRF' for details. Distinct from the per-user notifications.enabled toggle in the settings UI: this is the server-level operator gate, env-only so it cannot be flipped via the user-writable settings API. | Security | || `LDR_NOTIFICATIONS_ALLOW_PRIVATE_IPS` | Boolean | `False` | No | | Allow notification webhooks to target private/local IP addresses. Environment-only to prevent SSRF bypass via the user-writable settings API. Only enable this if your notification endpoints are on a trusted local network. | Security | || `LDR_POLICY_ALLOW_UNPROTECTED_EGRESS` | Boolean | `False` | No | | Allow users to select the UNPROTECTED egress scope. Disabled by default; this is an environment-only operator gate and cannot be changed through the user-writable settings API. Hard SSRF and cloud-metadata protections remain active when enabled. | Security | || `LDR_RESEARCH_LIBRARY_ALLOW_FILESYSTEM_PDF_STORAGE` | Boolean | `False` | No | | Allow users to select the UNENCRYPTED 'filesystem' PDF storage mode for library-downloaded PDFs. Disabled by default; this is an environment-only operator gate and cannot be changed through the user-writable settings API. Filesystem mode writes fetched third-party PDFs as PLAINTEXT to a shared library directory (cleartext storage of sensitive information, CWE-312). When off, the 'filesystem' option is withheld from the settings UI and any stored or environment value of 'filesystem' is coerced to the encrypted 'database' mode at write time. Previously-written plaintext files remain readable. Enable only when the library directory lives on an operator-controlled encrypted volume. | Security | |diff --git a/docs/NOTIFICATIONS.md b/docs/NOTIFICATIONS.mdindex 5e34169efc..3c8acd048a 100644--- a/docs/NOTIFICATIONS.md+++ b/docs/NOTIFICATIONS.md@@ -18,9 +18,9 @@ The notification system uses [Apprise](https://github.com/caronc/apprise) to sup### Why?-Notification webhooks have a known **DNS resolution TOCTOU window** that cannot be closed in code: immediately before a test or dispatch, LDR attempts one DNS lookup and screens successful answers, but allows a lookup failure or five-second timeout. The underlying Apprise library resolves the hostname at send time and exposes no DNS/Session hook to pin a validated IP. A logged-in user with a controllable domain can serve a public IP—or make the validation lookup fail—and then serve a private IP at send time, causing the LDR server to make outbound HTTP requests to its own internal services (e.g. `127.0.0.1:<internal-port>`) or the local network.+Validating a notification URL once does not control where a later DNS lookup connects. LDR therefore sends notifications synchronously under `pinned_notification_send`: it pins supported webhook hosts and checks unpinned plugin destinations against the DNS answer used for connection. Every notification send requires the operator's separate `LDR_NOTIFICATIONS_ALLOW_PRIVATE_IPS=true` opt-in before it connects to a private or loopback address, whether that is a LAN destination or a private forward proxy (`HTTPS_PROXY`) in front of a fixed vendor endpoint. Without the opt-in, such a send is refused as a security block and is not retried. Link-local and metadata destinations remain blocked. A validation-time lookup failure does not bypass these send-time checks, and delivery is refused if the DNS guard is unavailable.-Because LDR is multi-user (per-user encrypted SQLCipher databases behind an authenticated session — `Depends(require_auth)`), the right default is to keep this feature off until the operator explicitly opts in — flipping the env var is the operator's acknowledgement of the residual risk. See [SECURITY.md](../SECURITY.md#notification-webhook-ssrf) for the full rationale and operator-side mitigations (prefer a fixed-destination notification mode when one fits, and restrict egress).+Outbound delivery can send research data to an external service, so the server gate keeps that capability an explicit operator choice on a multi-user instance. The DNS guard covers resolution in the sending thread; a configured forward proxy selects its own destinations and needs equivalent network restrictions. See [SECURITY.md](../SECURITY.md#notification-webhook-ssrf) for destination policies, redirect handling and egress restrictions.### Symptoms when the gate is closed@@ -296,19 +296,19 @@ except RateLimitError as e:The "Test" button in the notifications settings page returns the validator's reason directly. Common categories and the fix:**"Blocked private/internal IP address: \<host\>"**-- **Cause**: The URL resolves to a loopback (`127.0.0.1`, `::1`), RFC1918 (`10.x`, `172.16-31.x`, `192.168.x`), CGNAT (`100.64.0.0/10`), link-local (`169.254.0.0/16`), or IPv6 private (`fc00::/7`, `fe80::/10`) address. The default SSRF policy blocks these for outbound webhooks.-- **Fix (operator-only, env-only)**: Set `LDR_NOTIFICATIONS_ALLOW_PRIVATE_IPS=true` in the server environment. This is intentionally not exposed in the user-writable settings API. Only enable it if the notification endpoints are on a trusted local network.+- **Cause**: The URL resolves to a loopback (`127.0.0.1`, `::1`), RFC1918 (`10.x`, `172.16-31.x`, `192.168.x`), CGNAT (`100.64.0.0/10`), or IPv6 unique-local (`fc00::/7`) address. The default SSRF policy blocks these for outbound webhooks. Link-local addresses (`169.254.0.0/16`, `fe80::/10`) are reported as `Blocked cloud-metadata / link-local IP address` instead (see below).+- **Fix (operator-only, env-only)**: Set `LDR_NOTIFICATIONS_ALLOW_PRIVATE_IPS=true` in the server environment. This is intentionally not exposed in the user-writable settings API. Only enable it if the notification endpoints are on a trusted local network. In v2, this opt-in also applies to `json://`, `xml://`, `form://` and self-hosted Apprise plugins such as Signal, Gotify and ntfy private mode; older releases allowed private plugin hosts without the flag. Link-local hosts (for every scheme, `http(s)://` included) and cloud-metadata endpoints remain blocked even with opt-in.- **Fix (IPv6-only deployments using NAT64)**: If the host wraps IPv4 through `64:ff9b::/96` (RFC 6052 well-known) or `64:ff9b:1::/48` (RFC 8215 local-use), additionally set `LDR_SECURITY_ALLOW_NAT64=true`. The opt-in is scoped strictly to those two prefixes — 6to4 (`2002::/16`), Teredo (`2001::/32`), the discard prefix (`100::/64`), the deprecated IPv4-Compatible IPv6 form (`::/96`, except `::1` loopback which follows the loopback/private-IPs flags), and the IPv4-Translated SIIT form (`::ffff:0:0:0/96`, RFC 2765) remain blocked.-- **Note (cloud-metadata IPs)**: If `\<host\>` is a cloud-metadata IP (see the next bullet), the env-var hint above is intentionally **not** surfaced by the "Test" button — neither flag re-opens metadata, so the hint would mislead. The user-visible error is just the bare `"Blocked private/internal IP address: 169.254.169.254"`.+- **Note (cloud-metadata IPs)**: If `\<host\>` is a cloud-metadata IP (see the next bullet), the env-var hint above is intentionally **not** surfaced by the "Test" button — neither flag re-opens metadata, so the hint would mislead. The validator reports it as `"Blocked cloud-metadata / link-local IP address: 169.254.169.254"` (see the next bullet).-**"Blocked cloud-metadata IP address: \<host\>"**-- **Cause**: An allowed Apprise plugin URL has an authority that is, or successfully resolves to, a cloud-metadata endpoint. A non-literal authority gets exactly one resolution attempt during the Phase 1 plugin IMDS guard; successful answers are screened, while a DNS failure or five-second timeout is allowed. An IP literal is checked directly without a DNS call. The guard runs for user-host modes (`signal://`, `gotify://`, ntfy private, Matrix server/webhook, `json://`, `xml://`, and `form://`), `mailto://`, and fixed-destination token/topic modes (`discord://`, `slack://`, ntfy cloud, and Matrix t2bot). Mail sends either to an authority subject to this best-effort screening or to Apprise's fixed built-in SMTP mapping for a recognized provider. In another fixed-destination mode the authority is only an opaque token/topic, but LDR still attempts the same screening consistently.-- **Always blocked**: AWS IMDS / ECS, Azure, OCI, DigitalOcean, AlibabaCloud, Tencent — both as plain IPv4 and wrapped through any NAT64 prefix. No env var re-opens these. See [SECURITY.md](../SECURITY.md#cloud-metadata-endpoint-block-list).+**"Blocked cloud-metadata / link-local IP address: \<host\>"**+- **Cause**: A host-bearing notification URL names a cloud-metadata or link-local endpoint. Literal addresses are checked directly; hostnames get one bounded validation-time resolution and are checked again at send time. Fixed-destination token/topic modes (Discord, Slack, ntfy cloud, Matrix t2bot and Telegram) are not resolved as user-supplied hosts.+- **Always blocked**: AWS IMDS / ECS, Azure, OCI, DigitalOcean, AlibabaCloud, Tencent — both as plain IPv4 and wrapped through any NAT64 prefix. No env var re-opens these. See [SECURITY.md](../SECURITY.md#cloud-metadata-endpoint-block-list). The rest of the link-local range is blocked for every notification URL as well; `LDR_NOTIFICATIONS_ALLOW_PRIVATE_IPS` does not reopen it.- **Fix**: Choose a different webhook destination. Metadata endpoints expose IAM/instance credentials and are never legitimate webhook targets.**"Blocked unsafe protocol: \<scheme\>"** / **"Unsupported protocol: \<scheme\>"**- **Cause**: The URL uses a scheme that is either denylisted (`file`, `ftp`, `ftps`, `data`, `javascript`, `vbscript`, `about`, `blob`) or not in LDR's URL-scheme allowlist.-- **Fix**: Use one of the schemes in LDR's URL-scheme allowlist — `http`, `https`, `mailto`, `discord`, `slack`, `tgram`, `gotify`, `pushover`, `ntfy`, `ntfys`, `signal`, `matrix`, `mattermost`, `rocketchat`, `teams`, `json`, `xml`, `form` — and verify it with the Test button. Against Apprise 1.12.0 (the reviewed dependency floor), direct `discord://` and `slack://` URLs use fixed service endpoints; LDR blocks their `template` option so it cannot fetch a second resource. ntfy cloud (`ntfy://<topic>`) and Matrix t2bot (`matrix://<64-character-token>`) are fixed-destination modes too. `signal://`, `gotify://`, ntfy private, Matrix server/webhook, `json://`, `xml://`, and `form://` use a user-supplied authority host. `mailto://` uses its authority or Apprise's fixed SMTP mapping for a recognized provider. The user-host cases retain the DNS-rebinding risk described in [SECURITY.md](../SECURITY.md#notification-webhook-ssrf).+- **Fix**: Use one of the schemes in LDR's URL-scheme allowlist — `http`, `https`, `mailto`, `discord`, `slack`, `tgram`, `gotify`, `pushover`, `ntfy`, `ntfys`, `signal`, `matrix`, `mattermost`, `rocketchat`, `teams`, `json`, `xml`, `form` — and verify it with the Test button. Against Apprise 1.12.0 (the reviewed dependency floor), direct `discord://` and `slack://` URLs use fixed service endpoints; LDR blocks their `template` option so it cannot fetch a second resource. ntfy cloud (`ntfy://<topic>`) and Matrix t2bot (`matrix://<64-character-token>`) are fixed-destination modes too. `signal://`, `gotify://`, ntfy private, Matrix server/webhook, `json://`, `xml://`, and `form://` use a user-supplied authority host. `mailto://` uses its authority or Apprise's fixed SMTP mapping for a recognized provider; LDR rejects a mail URL that Apprise would send to any other SMTP host. The user-host cases remain subject to the send-time DNS guard described in [SECURITY.md](../SECURITY.md#notification-webhook-ssrf).**Direct scheme-prefix gap (Apprise 1.12.0 floor vs LDR's URL-scheme allowlist).** Telegram is accepted under Apprise's own `tgram` prefix. Four other names in LDR's allowlist do not overlap the direct prefixes Apprise 1.12.0 registers, and LDR has no alias translation:@@ -329,6 +329,10 @@ The "Test" button in the notifications settings page returns the validator's rea- **Cause**: A query parameter name contains `%` without two hexadecimal digits. LDR rejects this before DNS resolution to avoid parser-version differences with Apprise.- **Fix**: Correct or remove the malformed parameter name.+**"Notification destination is unsupported or ambiguous"**+- **Cause**: LDR could not establish the one host Apprise would contact for this URL, so the URL is refused rather than checked against the wrong address. For example, an IPv6 literal host that Apprise's URL parser rewrites: Apprise 1.13 sends `json://[fd00::1]/hook` to `[fd00::]`, and drops the port of a literal written with uppercase hex digits (`json://[FD00:0:0:0:0:0:0:1]:8080/hook` goes to port 80). Other causes include an unsupported ntfy `mode=` value and a `mailto://` URL that Apprise would send to an SMTP host other than its authority or a built-in provider's.+- **Fix**: Write an IPv6 literal in full and in lowercase (`json://[fd00:0:0:0:0:0:0:1]:8080/hook`), or use a hostname. Otherwise remove the ambiguous part of the URL and check it with the Test button.+**"URL contains characters that are not allowed (whitespace, backslash, or control bytes)"**- **Cause**: Layer-1 defense against parser-differential SSRF bypasses (GHSA-g23j-2vwm-5c25) — RFC 3986 forbids these characters in URLs.- **Fix**: Remove the whitespace / backslash / control bytes. Percent-encode if a legitimate use case requires them.diff --git a/src/local_deep_research/notifications/manager.py b/src/local_deep_research/notifications/manager.pyindex 7b8fea6859..9c6e2e243a 100644--- a/src/local_deep_research/notifications/manager.py+++ b/src/local_deep_research/notifications/manager.py@@ -6,6 +6,7 @@ from dataclasses import dataclassfrom datetime import datetime, timezone, timedeltafrom enum import Enumfrom typing import Dict, Optional, Any+from urllib.parse import urlunsplitfrom collections import dequeimport threading@@ -13,6 +14,11 @@ from loguru import loggerfrom ..security.notification_validator import parse_notification_url_listfrom ..security.ssrf_validator import redact_url_for_log+from ..security.notification_destination import (+ NotificationDestinationError,+ NotificationDestinationKind,+ parse_notification_destination,+)from ..settings.env_registry import get_env_settingfrom .service import NotificationServicefrom .templates import EventType@@ -386,10 +392,13 @@ class NotificationManager:),)- # Egress policy: classify raw HTTP(S) URLs with evaluate_url.- # PRIVATE_ONLY refuses non-HTTP Apprise schemes because their- # effective destinations cannot be classified reliably; other- # scopes pass plugin schemes to the service's URL validator.+ # Egress policy: each URL is classified by the endpoint Apprise+ # will contact. HTTP URLs and authority-bearing plugins are+ # checked with evaluate_url against that host; fixed vendor+ # endpoints (Matrix t2bot included) are refused under+ # PRIVATE_ONLY only, and mailto plus Matrix homeserver/webhook+ # modes under PRIVATE_ONLY and STRICT (see+ # _filter_urls_by_egress_policy).# No separator is passed here, so this parses/rejoins with the# default ",". If a non-default separator is ever exposed to# callers, it must be passed here too and to service.send_event@@ -730,48 +739,82 @@ class NotificationManager:)return None- # Apprise accepts space- or comma-separated URLs and has non-HTTP- # schemes (discord://, slack://, tgram://, mailto://, msteams://,- # ntfy://, ...) whose effective destination may be a fixed provider,- # a user-supplied authority, or a provider mapping. evaluate_url only- # understands HTTP(S), so it cannot classify those modes reliably.- #- # Under PRIVATE_ONLY ("nothing leaves the box"), a non-HTTP scheme is- # therefore refused — fail closed. Services that expose a raw HTTP(S) webhook- # can use that URL and be classified by evaluate_url; Apprise SMTP and- # other plugin URLs remain unavailable under PRIVATE_ONLY. Under the- # other scopes the prior pass-through stands (the modeled threat there- # is internal-http SSRF via a raw webhook, not vendor APIs).+ # Classify the endpoint Apprise will contact. Authority-bearing+ # plugins must obey the same user egress scope as an HTTP webhook;+ # token-based vendor plugins (Matrix t2bot and ntfy cloud included)+ # are refused in PRIVATE_ONLY and pass every other scope.parts = []for url_entry in url_entries:- scheme = (- url_entry.split(":", 1)[0].lower() if ":" in url_entry else ""- )- if scheme not in ("http", "https"):+ try:+ destination = parse_notification_destination(url_entry)+ except NotificationDestinationError:+ # Preserve the invalid-URL outcome: the service validator+ # will reject this entry before Apprise sees it. Dropping it+ # here would misreport a malformed URL as an egress refusal.+ parts.append(url_entry)+ continue+ if destination.kind is NotificationDestinationKind.VENDOR_PLUGIN:if ctx.scope == EgressScope.PRIVATE_ONLY:logger.bind(policy_audit=True).warning(- "notification refused under PRIVATE_ONLY egress "- "scope: non-http vendor scheme cannot be verified "- "local",- scheme=scheme or "(none)",+ "notification vendor destination refused under "+ "PRIVATE_ONLY egress scope")continueparts.append(url_entry)continue- decision = evaluate_url(url_entry, ctx)+ # Mail and Matrix homeserver/webhook URLs are refused under+ # PRIVATE_ONLY and STRICT whatever their host. Apprise's mail+ # plugin can connect to a built-in provider's fixed SMTP host+ # instead of the URL authority. The Matrix refusal is+ # conservative: Apprise runs server discovery only for+ # ``matrixs://``, which the classifier rejects, so ``matrix://``+ # sends to its URL host. Matrix t2bot is a VENDOR_PLUGIN and was+ # handled above (refused only under PRIVATE_ONLY).+ scheme = url_entry.split(":", 1)[0].lower()+ if scheme in {"matrix", "mailto"} and ctx.scope in {+ EgressScope.PRIVATE_ONLY,+ EgressScope.STRICT,+ }:+ logger.bind(policy_audit=True).warning(+ "notification destination refused: dynamic endpoint "+ "cannot be verified local",+ scheme=scheme,+ )+ continue+ if destination.kind is NotificationDestinationKind.HTTP:+ policy_url = url_entry+ else:+ effective_host = destination.effective_host+ if not effective_host:+ continue+ policy_host = (+ f"[{effective_host}]"+ if ":" in effective_host+ else effective_host+ )+ policy_url = urlunsplit(("http", policy_host, "", "", ""))+ try:+ decision = evaluate_url(policy_url, ctx)+ except (+ AttributeError,+ ImportError,+ RuntimeError,+ TypeError,+ ValueError,+ ) as exc:+ logger.bind(policy_audit=True).warning(+ "notification URL refused: egress policy evaluation failed",+ reason=type(exc).__name__,+ )+ continueif decision.allowed:parts.append(url_entry)else:- # Log the redacted ``scheme://host[:port]`` form, never- # the entry: this branch only sees http(s) URLs, whose- # userinfo may carry the operator's credentials- # (RFC 3986 §3.2.1) and whose path may itself be the- # webhook secret. The host is what an operator needs to- # act on a policy refusal, and it is the part the policy- # decided on.- logger.bind(policy_audit=True).warning(+ audit = logger.bind(policy_audit=True)+ if destination.kind is NotificationDestinationKind.HTTP:+ audit = audit.bind(url=redact_url_for_log(url_entry))+ audit.warning("notification URL refused by egress policy",- url=redact_url_for_log(url_entry),scope=ctx.scope.value,reason=decision.reason,)diff --git a/src/local_deep_research/notifications/service.py b/src/local_deep_research/notifications/service.pyindex 45e5e72023..f457fe009f 100644--- a/src/local_deep_research/notifications/service.py+++ b/src/local_deep_research/notifications/service.py@@ -21,6 +21,11 @@ from .exceptions import ServiceError, SendError, SecurityBlockErrorfrom .apprise_log_utils import install_apprise_log_record_factoryfrom .templates import EventType, NotificationTemplatefrom ..security import dns_pinning+from ..security.notification_destination import (+ NotificationDestinationError,+ NotificationDestinationKind,+ parse_notification_destination,+)from ..security.notification_validator import (NotificationURLValidator,parse_notification_url_list,@@ -212,12 +217,9 @@ class NotificationService:entries when a URL scheme follows it, so commas INSIDE one Apprise URL(e.g. a multi-target Telegram ``?to=id1,id2``) are preserved anddispatched as a single entry; an explicit custom separator preserves- commas and whitespace inside each URL outright. The two groups get- different send-time SSRF policies (see :meth:`_dispatch`), mirroring- the notification validator's per-scheme rules: ``http``/``https``- block private IPs unless the operator opted in, while plugin /- raw-webhook schemes allow private (self-hosted LAN) but always block- cloud-metadata.+ commas and whitespace inside each URL outright. ``_dispatch``+ further separates host-bearing plugins from fixed vendor plugins+ and applies the matching send-time DNS policy.NOTE: the ``strict`` (``http``/``https``) partition is onlyPARTLY deliverable. Apprise has no generic http(s) notifier, so an@@ -637,15 +639,17 @@ class NotificationService:``strict_urls`` (http/https): pin each host and block private +metadata resolution for the send (honoring the operator``allow_private_ips`` opt-in) — closes rebinding and- redirect-to-internal.-- ``lenient_urls`` (plugin / raw-webhook schemes): pin the raw-webhook- hosts (json/xml/form) and block cloud-metadata AND the whole- link-local range (``allow_private_ips=True`` + ``block_link_local=True``)- — self-hosted LAN targets (RFC1918 / loopback / non-link-local ULA)- keep working while a send-time rebind/redirect to a metadata or- link-local IP is refused. This mirrors the notification validator's- per-scheme policy exactly.+ redirect-to-internal. Link-local stays blocked even with the+ opt-in: Apprise turns some http(s) URLs into plugins that post to+ the URL host (Apprise API, Workflows).++ ``lenient_urls`` are classified by effective destination. Plugins+ whose authority selects the connection host use the operator's+ private-IP opt-in and a link-local block. Fixed vendor endpoints+ use the same operator opt-in (public-only by default): their hosts+ are fixed, so a private answer normally means a forward proxy+ (``HTTPS_PROXY``) that the operator must approve. Link-local and+ cloud-metadata addresses stay blocked for both.Each non-empty partition is dispatched (and retried by Tenacity)under its own guard. A partition that adds no URLs returns False@@ -663,23 +667,45 @@ class NotificationService:strict_urls,allow_localhost=False,allow_private_ips=self.allow_private_ips,+ block_link_local=True,),))- if lenient_urls:+ authority_urls = []+ vendor_urls = []+ for entry in lenient_urls:+ try:+ destination = parse_notification_destination(entry)+ except NotificationDestinationError as exc:+ raise SecurityBlockError(+ "Notification destination is unsupported or ambiguous"+ ) from exc+ if destination.kind is NotificationDestinationKind.AUTHORITY_PLUGIN:+ authority_urls.append(entry)+ elif destination.kind is NotificationDestinationKind.VENDOR_PLUGIN:+ vendor_urls.append(entry)+ else:+ raise SecurityBlockError("Notification partition is ambiguous")+ if authority_urls:partitions.append((- lenient_urls,+ authority_urls,lambda: dns_pinning.pinned_notification_send(- lenient_urls,+ authority_urls,allow_localhost=False,- allow_private_ips=True,- # Plugin/raw-webhook schemes allow private LAN targets- # but NOT link-local: cloud-provider metadata lives- # there beyond the always-blocked literals (e.g.- # some providers' IMDS) and no legitimate self-hosted- # notifier does. Mirrors the validator's plugin-scheme- # IMDS guard.+ allow_private_ips=self.allow_private_ips,+ block_link_local=True,+ ),+ )+ )+ if vendor_urls:+ partitions.append(+ (+ vendor_urls,+ lambda: dns_pinning.pinned_notification_send(+ vendor_urls,+ allow_localhost=False,+ allow_private_ips=self.allow_private_ips,block_link_local=True,),)@@ -981,33 +1007,24 @@ class NotificationService:# send path (:meth:`_guarded_notify`) — fail-closed invariants,# per-plugin redirect-disable, and the pin + block-private window# — instead of re-implementing it here. Single-shot (no Tenacity- # retry) for fast test feedback. allow_private_ips mirrors the- # validator's per-scheme policy: the operator flag for http/https,- # True (metadata-only) for plugin / raw-webhook schemes. tag is- # always None here.- #- # With multi-entry input the batch takes the STRICTEST policy of- # the schemes present: deriving it from the leading entry alone- # would let ``json://…,http://…`` run the http target under the- # plugin batch's allow_private_ips=True.- schemes = {- entry.split(":", 1)[0].lower()- for entry in url_entries- if ":" in entry- }- has_http = bool(schemes & {"http", "https"})- is_plugin_scheme = not schemes or bool(schemes - {"http", "https"})- allow_private = self.allow_private_ips if has_http else True- # Plugin/raw-webhook schemes run with allow_private_ips=True but- # must still block the whole link-local range (metadata territory- # beyond the always-blocked literals). Mirrors _dispatch's lenient- # partition and the validator's plugin-scheme IMDS guard.+ # retry) for fast test feedback. Every partition uses the+ # operator's private-IP opt-in (public-only by default) and+ # blocks the whole link-local range, as ``_dispatch`` does.+ # Tag is always None here.+ try:+ for entry in url_entries:+ parse_notification_destination(entry)+ except NotificationDestinationError:+ return {+ "success": False,+ "error": "Notification destination is unsupported or ambiguous",+ }guard_factory = functools.partial(dns_pinning.pinned_notification_send,list(url_entries),allow_localhost=False,- allow_private_ips=allow_private,- block_link_local=is_plugin_scheme,+ allow_private_ips=self.allow_private_ips,+ block_link_local=True,)result = self._guarded_notify(diff --git a/src/local_deep_research/security/dns_pinning.py b/src/local_deep_research/security/dns_pinning.pyindex 0379c0a0a4..1887949218 100644--- a/src/local_deep_research/security/dns_pinning.py+++ b/src/local_deep_research/security/dns_pinning.py@@ -148,10 +148,8 @@ _thread_state = threading.local()# resolvable host — the "opaque token" description does not apply to them.# They are left unpinned because their per-plugin URL→endpoint mapping is# plugin-specific (path/port rewriting) rather than a plain connect to the-# URL host, and because their partition intentionally allows private/LAN-# targets: the block-private window (metadata-only for this partition) is-# the right guarantee for them, and pinning would add complexity without-# changing the metadata outcome.+# URL host. The send-time block-private window enforces the selected+# destination policy even when there is no precomputed pin.## This block-window guarantee holds only for schemes whose network I/O resolves# through the shimmed ``socket.getaddrinfo`` — which every scheme reachable@@ -713,7 +711,7 @@ def block_private_resolution(``socket.gaierror``. Pinned hosts are unaffected (they short-circuit totheir validated addresses), and public unpinned hosts resolve normally.- ``block_link_local`` (notification lenient partition): when True, the+ ``block_link_local`` (every notification partition): when True, thewhole link-local range stays refused even under ``allow_private_ips=True``— closing metadata reachable in link-local beyond the always-blockedliterals (e.g. Scaleway ``169.254.42.42``) without over-blocking RFC1918 /@@ -854,17 +852,14 @@ def pinned_notification_send((``AppriseAsset(async_mode=False)``); an async fan-out would resolve inworker threads that carry neither the pin nor the block.- ``allow_private_ips`` mirrors the notification validator's per-scheme- policy: pass the operator flag for ``http``/``https`` batches (private- blocked unless opted in) and ``True`` for the plugin/raw-webhook batch- (private allowed, cloud-metadata still always blocked).-- ``block_link_local`` should be ``True`` for the plugin/raw-webhook batch- (which runs with ``allow_private_ips=True``) so the whole link-local- range stays blocked there — cloud-provider metadata lives in link-local- beyond the always-blocked literals, and no legitimate self-hosted- notifier does. It is forwarded to both the pin's connect-time validation- and the block-private window.+ ``allow_private_ips`` is the operator flag for every notification+ partition (HTTP, host-bearing plugins and fixed vendor endpoints). It+ is public-only by default; with the opt-in, private targets and a+ private forward proxy (``HTTPS_PROXY``) are allowed.++ ``block_link_local`` is True for every notification partition so the+ whole link-local range stays blocked even when private LAN addresses+ are operator-approved. It applies to both pin and send-time resolution.Raises:NotificationGuardUnavailableError: if the ``getaddrinfo`` shim is notdiff --git a/src/local_deep_research/security/egress/README.md b/src/local_deep_research/security/egress/README.mdindex abd0dd5f7d..5c2e854e32 100644--- a/src/local_deep_research/security/egress/README.md+++ b/src/local_deep_research/security/egress/README.md@@ -364,4 +364,4 @@ be retriever-backed or dynamically injected engines the factory evaluatesvia its own path) — the pre-filter is never stricter than the factory PEPit fronts.-> **Notification footnote.** The notification PEP (`notifications/manager.py` `_filter_urls_by_egress_policy`) gates **http/https** webhook URLs through `evaluate_url`. Apprise vendor schemes (`slack://`, `discord://`, `tgram://`, `mailto://`, …) dispatch to external vendor APIs: under **PRIVATE_ONLY** (incl. Adaptive-private) they are **refused outright** (we can't verify a vendor token is local — fail closed; address a self-hosted notifier by its `http(s)://` URL, which `evaluate_url` allows as a private host). Under the other scopes they pass the URL gate (the modeled threat there is internal-http SSRF, not vendor APIs); the audit-hook net is an additional backstop for the actual connection when armed.+> **Notification footnote.** The notification PEP (`notifications/manager.py` `_filter_urls_by_egress_policy`) classifies each Apprise URL by the endpoint Apprise will contact (`security/notification_destination.py`). `http(s)://` URLs and authority plugins whose URL host is the connection host (`json://`, `xml://`, `form://`, `gotify://`, `signal://`, `mattermost://`, `rocketchat://`, ntfy private mode, Matrix homeserver/webhook modes, `mailto://`) go through `evaluate_url` against that effective host under every scope, so the row above applies to them: STRICT and PRIVATE_ONLY allow only a private host, PUBLIC_ONLY only a public host, BOTH any classified host. On top of that, `mailto://` and Matrix homeserver/webhook URLs are **refused outright** under PRIVATE_ONLY and STRICT whatever their host (Apprise's mail plugin can connect to a built-in provider's fixed SMTP host instead of the authority; the Matrix refusal is conservative, since Apprise runs server discovery only for `matrixs://`, which LDR rejects). Fixed vendor endpoints (`slack://`, `discord://`, `tgram://`, `pushover://`, `teams://`, ntfy cloud mode, Matrix t2bot mode) have no user host to evaluate: under **PRIVATE_ONLY** (incl. Adaptive-private) they are **refused outright** (fail closed; a vendor API is never local), and under every other scope, STRICT included, they pass the URL gate without a host check. A URL the classifier cannot place is passed to the notification validator, which rejects it before Apprise sees it. The send-time DNS guard and, when armed, the audit-hook net are additional backstops for the actual connection.diff --git a/src/local_deep_research/security/notification_destination.py b/src/local_deep_research/security/notification_destination.pynew file mode 100644index 0000000000..accb1232b4--- /dev/null+++ b/src/local_deep_research/security/notification_destination.py@@ -0,0 +1,467 @@+"""Classify the network destination represented by an Apprise URL."""++from dataclasses import dataclass+from enum import Enum+import ipaddress+import re+from string import ascii_letters, digits, hexdigits+from urllib.parse import SplitResult, unquote, urlsplit++from urllib3.exceptions import LocationParseError+from urllib3.util import parse_url+++class NotificationDestinationKind(str, Enum):+ HTTP = "http"+ AUTHORITY_PLUGIN = "authority_plugin"+ VENDOR_PLUGIN = "vendor_plugin"+++@dataclass(frozen=True, slots=True)+class NotificationDestination:+ kind: NotificationDestinationKind+ effective_host: str | None+++class NotificationDestinationError(ValueError):+ """A notification URL whose destination cannot be classified safely."""++ def __init__(self, reason: str) -> None:+ super().__init__(reason)+ self.reason = reason++ def __str__(self) -> str:+ return self.reason+++_UNRESERVED_HOST_ESCAPES = re.compile(r"%([0-9A-Fa-f]{2})")+_UNRESERVED_HOST_CHARACTERS = frozenset(ascii_letters + digits + "-._~")+++def normalize_host_for_transport(host: str) -> str:+ """Decode one pass of unreserved host escapes as Requests prepares URLs."""++ def unescape(match: re.Match[str]) -> str:+ decoded = chr(int(match.group(1), 16))+ return (+ decoded+ if decoded in _UNRESERVED_HOST_CHARACTERS+ else match.group(0)+ )++ return _UNRESERVED_HOST_ESCAPES.sub(unescape, host)+++def _required_host(parsed: SplitResult) -> str:+ try:+ host = parsed.hostname+ except ValueError as exc:+ raise NotificationDestinationError("invalid authority") from exc+ if not host:+ raise NotificationDestinationError("destination host is missing")+ if ":" in host and "%" in host:+ # An IPv6 zone identifier (``[fd00::1%25eth0]``) scopes a literal to+ # an interface; no notification endpoint needs one, and a scoped+ # address no longer equals the unscoped metadata literals.+ raise NotificationDestinationError("IPv6 zone identifier in host")+ # urlsplit leaves percent escapes in the hostname. Requests decodes+ # unreserved escapes while preparing the outbound URL, but urllib3's+ # parse_url changed its own decoding behavior between 2.7 and 2.8.+ # Normalize once so policy resolves the same host under either version.+ authority = f"[{host}]" if ":" in host else host+ try:+ network_host = parse_url(f"http://{authority}/").host+ except LocationParseError as exc:+ raise NotificationDestinationError("invalid authority") from exc+ if not network_host:+ raise NotificationDestinationError("destination host is missing")+ if network_host.startswith("[") and network_host.endswith("]"):+ network_host = network_host[1:-1]+ return normalize_host_for_transport(network_host).rstrip(".")+++def _plugin_host(parsed: SplitResult) -> str:+ """Return the authority host of an Apprise plugin URL.++ Several plugins (Signal, ntfy, Matrix, email) parse with+ ``verify_host=False`` and fully percent-decode the host, so an escape+ such as ``%2F`` or ``%40`` moves the real destination+ (``evil.com%2F.local`` is sent to ``evil.com``). No legitimate plugin+ host needs an escape, so any ``%`` is refused instead of guessing each+ plugin's decoding.+ """+ try:+ raw_host = parsed.hostname+ except ValueError as exc:+ raise NotificationDestinationError("invalid authority") from exc+ if raw_host and "%" in raw_host:+ raise NotificationDestinationError(+ "percent-encoded plugin host is ambiguous"+ )+ return _required_host(parsed)+++def parse_apprise_query(url: str) -> dict[str, list[str]]:+ """Parse query keys with the same normalization Apprise applies."""+ _, separator, query = url.partition("?")+ if not separator or not query:+ return {}++ parsed_query: dict[str, list[str]] = {}+ pairs = [+ part for section in query.split("&") for part in section.split(";")+ ]+ for pair in pairs:+ raw_key, _, raw_value = pair.partition("=")+ index = 0+ while index < len(raw_key):+ if raw_key[index] != "%":+ index += 1+ continue+ if (+ index + 2 >= len(raw_key)+ or raw_key[index + 1] not in hexdigits+ or raw_key[index + 2] not in hexdigits+ ):+ raise NotificationDestinationError(+ "Malformed percent-encoding in notification parameter name"+ )+ index += 3++ apprise_key = (+ raw_key[:1] + raw_key[1:].replace("+", " ") if raw_key else ""+ )+ canonical_key = unquote(apprise_key).lower().strip()+ parsed_query.setdefault(canonical_key, []).append(+ unquote(raw_value).strip()+ )+ return parsed_query+++def _query_value(url: str, key: str) -> str | None:+ values = parse_apprise_query(url).get(key)+ if values is None:+ return None+ if len(values) != 1 or not values[0].strip():+ raise NotificationDestinationError(f"ambiguous {key} parameter")+ return values[0].strip().lower()+++def _apprise_host(host: object) -> str:+ """Normalize a host reported by Apprise for comparison with ours."""+ if not isinstance(host, str) or not host:+ raise NotificationDestinationError("destination host is missing")+ if host.startswith("[") and host.endswith("]"):+ host = host[1:-1]+ return host.rstrip(".").lower()+++def _confirm_apprise_ipv6_host(url: str, host: str) -> str:+ """Refuse an IPv6 literal that Apprise would send somewhere else.++ Apprise's generic URL parser rewrites compressed IPv6 literals in the+ authority: on Apprise 1.13 ``json://[fd00::1]/x`` builds a plugin whose+ host is ``[fd00::]`` and ``[::ffff:10.0.0.5]`` becomes ``[::ffff:10]``.+ Policy would then vet one address while Apprise connects to another.+ For an IPv6 literal the plugin is therefore built the way+ ``Apprise.add`` builds it (``Apprise.instantiate``, no network I/O) and+ its host must be the same address. A URL Apprise cannot build is+ returned unchanged: ``Apprise.add`` rejects it and nothing is sent.+ Hostnames and IPv4 literals are not rewritten by that parser and are+ returned as they are.++ The port is compared too: Apprise's port regex for a bracketed literal+ is case-sensitive, so ``json://[FD00:0:0:0:0:0:0:1]:8080/x`` keeps the+ host but silently drops ``:8080`` and would post to the default port.+ """+ try:+ expected = ipaddress.ip_address(host)+ except ValueError:+ return host+ if expected.version != 6:+ return host++ from apprise import Apprise, AppriseAsset++ plugin = Apprise.instantiate(+ url, asset=AppriseAsset(async_mode=False, http_redirects=False)+ )+ if plugin is None:+ return host+ try:+ actual = ipaddress.ip_address(+ _apprise_host(getattr(plugin, "host", None))+ )+ except ValueError as exc:+ raise NotificationDestinationError(+ "IPv6 host is rewritten by Apprise"+ ) from exc+ if actual != expected:+ raise NotificationDestinationError("IPv6 host is rewritten by Apprise")+ try:+ expected_port = urlsplit(url).port+ except ValueError as exc:+ raise NotificationDestinationError("IPv6 port is malformed") from exc+ actual_port = getattr(plugin, "port", None)+ if isinstance(actual_port, str) and actual_port.isdigit():+ actual_port = int(actual_port)+ if actual_port != expected_port:+ raise NotificationDestinationError("IPv6 port is rewritten by Apprise")+ return host+++def _apprise_ntfy_destination(url: str, host: str) -> NotificationDestination:+ """Classify an ntfy URL from the plugin object Apprise itself builds.++ ntfy picks cloud mode (a fixed POST to ntfy.sh, with the authority used+ as a topic) or private mode (a POST to the authority host) from the+ host's validity, the path, ``to=`` and ``mode=``. Re-implementing those+ rules drifts in both directions, so the decision is read from the plugin+ built the way ``Apprise.instantiate`` (called by ``Apprise.add``) builds+ it: ``url_to_dict`` followed by the plugin constructor. Construction+ performs no network I/O.+ """+ from apprise import AppriseAsset+ from apprise.plugins import url_to_dict+ from apprise.plugins.ntfy import NotifyNtfy++ results = url_to_dict(url)+ if not results or str(results.get("schema", "")).lower() not in (+ "ntfy",+ "ntfys",+ ):+ raise NotificationDestinationError(+ "ntfy URL is not accepted by Apprise"+ )+ try:+ plugin = NotifyNtfy(+ **{+ **results,+ "asset": AppriseAsset(async_mode=False, http_redirects=False),+ "tag": set(),+ }+ )+ except Exception as exc: # Apprise.instantiate treats any error as reject+ raise NotificationDestinationError(+ "ntfy URL is not accepted by Apprise"+ ) from exc+ mode = str(getattr(plugin, "mode", "") or "").strip().lower()+ if mode == "cloud":+ return NotificationDestination(+ NotificationDestinationKind.VENDOR_PLUGIN,+ None,+ )+ if mode != "private":+ raise NotificationDestinationError("unsupported ntfy mode")+ if not getattr(plugin, "topics", None):+ # Apprise would send nothing; refuse rather than guess.+ raise NotificationDestinationError("private ntfy target is missing")+ apprise_host = _apprise_host(getattr(plugin, "host", None))+ if apprise_host != host:+ raise NotificationDestinationError("ntfy host is ambiguous")+ if apprise_host == "ntfy.sh":+ return NotificationDestination(+ NotificationDestinationKind.VENDOR_PLUGIN,+ None,+ )+ return NotificationDestination(+ NotificationDestinationKind.AUTHORITY_PLUGIN,+ apprise_host,+ )+++def _apprise_matrix_details(url: str) -> tuple[bool, str]:+ """Return Apprise's own (is_t2bot, host) for a Matrix URL.++ Uses the parser ``Apprise.add`` calls (``url_to_dict``) without building+ the plugin, whose constructor reads Apprise's persistent store.+ """+ from apprise.plugins import url_to_dict++ results = url_to_dict(url)+ if not results or str(results.get("schema", "")).lower() != "matrix":+ raise NotificationDestinationError(+ "matrix URL is not accepted by Apprise"+ )+ mode = str(results.get("mode") or "").strip().lower()+ return mode == "t2bot", str(results.get("host") or "")+++def _email_template_smtp_hosts() -> frozenset[str]:+ """Return the fixed SMTP hosts of Apprise's built-in mail providers."""+ from apprise.plugins.email.templates import EMAIL_TEMPLATES++ return frozenset(+ str(template[2]["smtp_host"]).rstrip(".").lower()+ for template in EMAIL_TEMPLATES+ if template[2].get("smtp_host")+ )+++def _apprise_mail_host(url: str, host: str) -> str:+ """Confirm that Apprise's mail plugin connects to ``host`` or a provider.++ Apprise's email parser discards an authority it does not accept as a+ hostname (an empty port, an underscore) and then takes the SMTP host from+ the domain of an e-mail address in the userinfo or ``?user=``. The URL+ authority would then no longer be the host Apprise connects to. The+ plugin is therefore built the way ``Apprise.instantiate`` builds it+ (``url_to_dict`` and the constructor, no network I/O), and only two+ outcomes are accepted: Apprise keeps ``host`` and connects to it, or it+ connects to the fixed SMTP host of one of its built-in providers selected+ by ``host``. A URL whose plugin cannot be built is returned unchanged:+ ``Apprise.add`` builds the same plugin, rejects the URL and sends nothing.+ """+ from apprise import AppriseAsset+ from apprise.plugins import url_to_dict+ from apprise.plugins.email import NotifyEmail++ results = url_to_dict(url)+ if not results or str(results.get("schema", "")).lower() != "mailto":+ raise NotificationDestinationError(+ "mailto URL is not accepted by Apprise"+ )+ parsed_host = results.get("host")+ if not parsed_host or _apprise_host(parsed_host) != host:+ raise NotificationDestinationError("mail host is ambiguous")+ try:+ plugin = NotifyEmail(+ **{+ **results,+ "asset": AppriseAsset(async_mode=False, http_redirects=False),+ "tag": set(),+ }+ )+ except Exception: # Apprise.instantiate treats any error as reject+ return host+ smtp_host = _apprise_host(getattr(plugin, "smtp_host", None))+ if smtp_host != host and smtp_host not in _email_template_smtp_hosts():+ raise NotificationDestinationError("mail host is ambiguous")+ return host+++def _smtp_override_host(value: str) -> str:+ if any(character.isspace() for character in value):+ raise NotificationDestinationError("invalid smtp override")+ try:+ parsed = urlsplit(f"//{value}")+ port = parsed.port+ except ValueError as exc:+ raise NotificationDestinationError("invalid smtp override") from exc+ if (+ parsed.username is not None+ or parsed.password is not None+ or port is not None+ or parsed.path+ or parsed.query+ or parsed.fragment+ ):+ raise NotificationDestinationError("invalid smtp override")+ if "%" in value:+ raise NotificationDestinationError("invalid smtp override")+ return _required_host(parsed)+++def parse_notification_destination(url: str) -> NotificationDestination:+ """Return the effective outbound destination for one Apprise URL."""+ if not isinstance(url, str) or not url.strip():+ raise NotificationDestinationError("notification URL is empty")+ try:+ normalized_url = url.strip()+ parsed = urlsplit(normalized_url)+ except ValueError as exc:+ raise NotificationDestinationError(+ "notification URL is malformed"+ ) from exc++ scheme = parsed.scheme.lower()+ match scheme:+ case "http" | "https":+ return NotificationDestination(+ NotificationDestinationKind.HTTP,+ _confirm_apprise_ipv6_host(+ normalized_url, _required_host(parsed)+ ),+ )+ case (+ "json"+ | "xml"+ | "form"+ | "gotify"+ | "signal"+ | "mattermost"+ | "rocketchat"+ ):+ return NotificationDestination(+ NotificationDestinationKind.AUTHORITY_PLUGIN,+ _confirm_apprise_ipv6_host(+ normalized_url, _plugin_host(parsed)+ ),+ )+ case "discord" | "slack" | "tgram" | "pushover" | "teams":+ if not parsed.netloc:+ raise NotificationDestinationError("vendor token is missing")+ return NotificationDestination(+ NotificationDestinationKind.VENDOR_PLUGIN,+ None,+ )+ case "ntfy" | "ntfys":+ # A duplicate or empty mode is ambiguous; fail before Apprise+ # silently picks one spelling.+ mode = _query_value(normalized_url, "mode")+ if mode not in (None, "cloud", "private"):+ raise NotificationDestinationError("unsupported ntfy mode")+ return _apprise_ntfy_destination(+ normalized_url, _plugin_host(parsed)+ )+ case "mailto":+ smtp_override = _query_value(normalized_url, "smtp")+ effective_host = (+ _smtp_override_host(smtp_override)+ if smtp_override is not None+ else _apprise_mail_host(normalized_url, _plugin_host(parsed))+ )+ return NotificationDestination(+ NotificationDestinationKind.AUTHORITY_PLUGIN,+ effective_host,+ )+ case "matrix":+ mode = _query_value(normalized_url, "mode")+ if mode not in (+ None,+ "off",+ "matrix",+ "slack",+ "hookshot",+ "t2bot",+ ):+ raise NotificationDestinationError("unsupported matrix mode")+ # Apprise alone decides between t2bot (a fixed POST to+ # webhooks.t2bot.io, with the authority used as the token) and a+ # homeserver/webhook mode that sends to the authority host.+ # Mirroring that rule here drifted from Apprise and refused+ # documented forms such as ``user@<token>`` and ``/#room``.+ apprise_t2bot, apprise_host = _apprise_matrix_details(+ normalized_url+ )+ if apprise_t2bot:+ token = parsed.netloc.rpartition("@")[2]+ if not re.fullmatch(r"[A-Za-z0-9]{64}", token):+ raise NotificationDestinationError(+ "vendor token is invalid"+ )+ return NotificationDestination(+ NotificationDestinationKind.VENDOR_PLUGIN,+ None,+ )+ host = _plugin_host(parsed)+ if _apprise_host(apprise_host) != host:+ raise NotificationDestinationError("matrix host is ambiguous")+ return NotificationDestination(+ NotificationDestinationKind.AUTHORITY_PLUGIN,+ host,+ )+ case _:+ raise NotificationDestinationError(+ "unsupported notification scheme"+ )diff --git a/src/local_deep_research/security/notification_validator.py b/src/local_deep_research/security/notification_validator.pyindex d27aba8a16..54181a04a9 100644--- a/src/local_deep_research/security/notification_validator.py+++ b/src/local_deep_research/security/notification_validator.py@@ -16,6 +16,12 @@ from loguru import loggerfrom urllib3.exceptions import LocationParseErrorfrom urllib3.util import parse_url+from .notification_destination import (+ NotificationDestinationError,+ NotificationDestinationKind,+ normalize_host_for_transport,+ parse_notification_destination,+)from .ip_ranges import PRIVATE_IP_RANGES as _PRIVATE_IP_RANGESfrom .legacy_ipv4 import (AMBIGUOUS_NUMERIC_IPV4_HOST_ERROR,@@ -496,9 +502,10 @@ class NotificationURLValidator:and let metadata IPs through the notification path.- block_link_local: when True, the whole link-local range(169.254.0.0/16, fe80::/10) stays blocked even under- allow_private_ips=True. Used by the plugin-scheme IMDS guard so- metadata reachable in link-local beyond the always-blocked- literals cannot slip through the lenient partition.+ allow_private_ips=True. The notification validator and send+ guards pass it for every host-bearing destination (http(s)+ included) so metadata reachable in link-local beyond the+ always-blocked literals cannot slip through the opt-in."""from .ssrf_validator import is_ip_blocked@@ -547,11 +554,9 @@ class NotificationURLValidator:# address is refused at the ``getaddrinfo`` layer — on a# timeout-bounded resolution — before a socket is opened. The block# runs on the very resolution the client connects to, so there is no- # residual race. Per-scheme policy mirrors this validator: http/https- # block private+metadata (unless the operator opts in), plugin /- # raw-webhook schemes block only cloud-metadata (self-hosted LAN- # targets keep working); cloud-metadata is ALWAYS blocked regardless- # of scheme or operator flag. Because the pin/block are thread-local,+ # residual race. Every partition requires the operator's private-IP+ # opt-in for private addresses (LAN targets or a private forward+ # proxy); cloud metadata remains blocked. Because the pin/block are thread-local,# they never disturb a legitimate private request on another thread.## DEFENSE IN DEPTH: the whole outbound-notification path is still@@ -784,9 +789,10 @@ class NotificationURLValidator:None (default) reads the env setting; an explicit boolanswers the hint probe.block_link_local: When True, the whole link-local range stays- blocked even under allow_private_ips=True. Used by the- plugin-scheme IMDS guard (metadata lives in link-local- beyond the always-blocked literals).+ blocked even under allow_private_ips=True. Passed for every+ host-bearing notification destination, http(s) included+ (metadata lives in link-local beyond the always-blocked+ literals).Returns:True if hostname is a private IP or localhost (subject to@@ -866,10 +872,11 @@ class NotificationURLValidator:rejected, a ``hint_would_help`` flag indicating whether therejection targets a recoverable destination — one that``LDR_NOTIFICATIONS_ALLOW_PRIVATE_IPS=true`` (for RFC1918 /- CGNAT / loopback / link-local / IPv6 ULA, plus NAT64-wrapped+ CGNAT / loopback / IPv6 ULA, plus NAT64-wrappednon-metadata destinations via the NAT64 carve-out) wouldactually unblock. If ``hint_would_help`` is False the URL- targets an always-blocked category (cloud-metadata IPs, 6to4,+ targets an always-blocked category (link-local, which every+ host-bearing notification destination blocks, cloud-metadata IPs, 6to4,Teredo, discard prefix, IPv4-mapped IPv6 of metadata,IPv4-Compatible IPv6, IPv4-Translated/SIIT, NAT64-wrappedmetadata) and the hint is suppressed because@@ -1041,24 +1048,17 @@ class NotificationURLValidator:# urlparse is vulnerable to parser-differential bypasses like# ``http://127.0.0.1\@1.1.1.1`` (GHSA-g23j-2vwm-5c25).#- # Per-scheme policy applied below:- # - http/https: full ``_is_private_ip`` check, honoring the- # operator ``allow_private_ips`` opt-in. RFC1918 / loopback- # are allowed through with the flag, but cloud-metadata and- # NAT64-wrapped metadata always block.- # - Apprise plugin schemes: private-IP authority values are- # intentionally allowed for self-hosted modes, but the absolute- # cloud-metadata block still applies. Some modes send against the- # authority (for example Signal and ntfy private); fixed-destination- # modes such as Discord, Slack, ntfy cloud, and Matrix t2bot treat it- # as a token/topic instead. Mail can use its authority or a fixed- # provider mapping. Screening every authority uniformly prevents- # host-bearing modes from bypassing the IMDS protection without- # incorrectly claiming every authority is the network destination.- # Secondary resource/destination parameters were rejected above.- # urllib3 2.8 decodes unreserved escapes in HTTP(S) hosts. Check- # their original spelling before normalization, even when private- # addresses are explicitly allowed.+ # Effective destinations are classified below. A token/topic in a+ # fixed vendor URL is not a host; an authority-bearing plugin must+ # pass the same private-IP opt-in as an HTTP URL. The urllib3 host and+ # classified endpoint must agree before a URL can be dispatched.+ #+ # urllib3 2.8 decodes unreserved escapes in HTTP(S) hosts (for+ # example ``127%2e0%2e0%2e1`` becomes ``127.0.0.1``). Check their+ # original spelling before normalization, even when private+ # addresses are explicitly allowed. ``raw_hostname`` is reused by+ # the plugin-host escape check below.+ raw_hostname = Noneif scheme in NotificationURLValidator.ADDRESS_BEARING_SCHEMES:try:raw_hostname = parsed.hostname@@ -1088,6 +1088,7 @@ class NotificationURLValidator:)return False, "URL host contains disallowed characters"hostname = NotificationURLValidator._normalize_host(hostname)+ hostname = normalize_host_for_transport(hostname)# A populated ``//`` authority that urllib3 parses to an EMPTY host# (e.g. ``json://169.254.169.254:80@/`` — an IP smuggled into the@@ -1113,60 +1114,88 @@ class NotificationURLValidator:hostnameand scheme in NotificationURLValidator.ADDRESS_BEARING_SCHEMES):- if is_percent_encoded_numeric_ipv4_host(hostname):- logger.warning(- "Blocked notification URL with encoded numeric IPv4 host"- )- return False, ENCODED_NUMERIC_IPV4_HOST_ERROR+ # The encoded-numeric spelling was already refused above, before+ # urllib3 normalized it.+ # Apprise plugins do not share Requests' URL preparation path,+ # and several decode every escape in the host (``%2F`` turns+ # ``evil.com%2F.local`` into ``evil.com``). Any escape in a+ # plugin authority host is ambiguous; fail before DNS.+ if (+ scheme not in ("http", "https")+ and raw_hostname+ and "%" in raw_hostname+ ):+ return False, "Notification destination host is ambiguous"if is_ambiguous_numeric_ipv4_host(hostname):logger.warning("Blocked notification URL with ambiguous numeric IPv4 host")return False, AMBIGUOUS_NUMERIC_IPV4_HOST_ERROR- if scheme in ("http", "https"):- if hostname and NotificationURLValidator._is_private_ip(- hostname,- allow_private_ips=allow_private_ips,- _resolved_ips=resolved_ips,- allow_nat64=allow_nat64,- ):- logger.warning(- f"Blocked private/internal IP in notification URL: "- f"{hostname}"- )- return (- False,- f"{NotificationURLValidator.PRIVATE_IP_REJECTION_PREFIX} {hostname}",+ try:+ destination = parse_notification_destination(url)+ except NotificationDestinationError:+ logger.warning(+ "Blocked notification URL with ambiguous destination"+ )+ return False, "Notification destination is unsupported or ambiguous"++ effective_host = NotificationURLValidator._normalize_host(+ destination.effective_host+ )+ if destination.kind is NotificationDestinationKind.VENDOR_PLUGIN:+ return True, None+ if not effective_host or effective_host.lower() != hostname.lower():+ # The effective endpoint and urllib3's connection host must+ # agree. A parser disagreement is unsafe to dispatch. Host names+ # are case-insensitive, and urllib3 lowercases only http(s)+ # hosts, so a case-only difference is not a disagreement.+ return False, "Notification destination host is ambiguous"+ # Every host-bearing destination blocks the whole link-local range,+ # even with the private-IP opt-in. Apprise turns some http(s) URLs+ # into plugins that post to the URL host (Apprise API, Workflows),+ # and cloud metadata lives across link-local beyond the+ # always-blocked literals (Scaleway serves it at 169.254.42.42).+ block_link_local = True+ if resolved_ips is None:+ try:+ ipaddress.ip_address(effective_host)+ except ValueError:+ # Direct validation (without the admin hint) must reuse one+ # DNS answer for both the block and recoverability decision.+ # An empty list keeps a failed lookup from being retried.+ resolved_ips = (+ NotificationURLValidator._resolve_hostname_ips(+ effective_host+ )+ or [])- elif scheme in NotificationURLValidator.HOST_BEARING_PLUGIN_SCHEMES:- # Plugin-scheme IMDS guard. ``allow_private_ips=True`` leaves- # ALWAYS_BLOCKED_METADATA_IPS and NAT64-wrapped metadata as- # active blocks in ``_is_private_ip``; ``block_link_local=True``- # additionally keeps the whole link-local range blocked — cloud- # metadata lives in link-local beyond the always-blocked literals- # (e.g. Scaleway 169.254.42.42) and no legitimate self-hosted- # notifier does. Exactly the set we want to enforce regardless of- # operator flags (RFC1918 / loopback / non-link-local ULA still- # allowed).- #- # resolved_ips is intentionally NOT forwarded here: the- # plugin-scheme guard must always perform its own resolution- # (it cannot rely on http(s)-centric pre-resolution).- if hostname and NotificationURLValidator._is_private_ip(- hostname,+ if NotificationURLValidator._is_private_ip(+ effective_host,+ allow_private_ips=allow_private_ips,+ _resolved_ips=resolved_ips,+ allow_nat64=allow_nat64,+ block_link_local=block_link_local,+ ):+ if NotificationURLValidator._is_private_ip(+ effective_host,allow_private_ips=True,- allow_nat64=allow_nat64,- block_link_local=True,+ _resolved_ips=resolved_ips,+ allow_nat64=True,+ block_link_local=block_link_local,):logger.warning(- "Blocked cloud-metadata / link-local IP in notification "- f"URL: {hostname}"+ "Blocked metadata or link-local notification host")return (False,- f"Blocked cloud-metadata / link-local IP address: {hostname}",+ f"Blocked cloud-metadata / link-local IP address: {effective_host}",)+ logger.warning("Blocked private/internal notification host")+ return (+ False,+ f"{NotificationURLValidator.PRIVATE_IP_REJECTION_PREFIX} {effective_host}",+ )# Passed all security checksreturn True, None@@ -1175,6 +1204,8 @@ class NotificationURLValidator:def _compute_hint(hostname: str,resolved_ips: Optional[List[ResolvedIP]],+ *,+ block_link_local: bool = False,) -> bool:"""Return True iff the combined elevated policy(LDR_NOTIFICATIONS_ALLOW_PRIVATE_IPS=true AND@@ -1190,6 +1221,7 @@ class NotificationURLValidator:allow_private_ips=True,allow_nat64=True,resolved_ips=resolved_ips,+ block_link_local=block_link_local,)if not hint:logger.debug(@@ -1211,14 +1243,13 @@ class NotificationURLValidator:Phase 1 — structural validation (no DNS):Calls ``_validate_service_url_impl`` with ``resolved_ips=[]``, which- suppresses DNS for the http(s) private-IP check. IP literals- are still evaluated directly. Plugin-scheme IMDS guard resolves- internally. This means bad schemes, illegal characters, parse+ suppresses DNS for every host-bearing private-IP check. IP literals+ are still evaluated directly. This means bad schemes, illegal characters, parseerrors, and malformed URLs are all rejected WITHOUT networkactivity.- Phase 2 — DNS resolution + IP policy (http(s) hostnames only):- Only reached for http(s) URLs with non-literal hostnames that+ Phase 2 — DNS resolution + IP policy (host-bearing destinations):+ Only reached for HTTP or authority-plugin URLs with non-literal hosts thatpassed Phase 1. Resolves DNS ONCE and shares the result acrossthe default-level rejection and the combined elevated-policy hint check,closing the DNS-rebinding TOCTOU window. When DNS fails, the@@ -1230,7 +1261,7 @@ class NotificationURLValidator:url: Service URL to validateallow_private_ips: Operator-level flag. When True, theprivate address categories (RFC1918 / CGNAT / loopback- / link-local / IPv6 ULA) are already permitted at this+ / IPv6 ULA; link-local stays blocked) are already permitted at thislevel. ``hint_would_help`` may still be True for arejected NAT64-wrapped non-metadata destination,because the NAT64 carve-out is governed by the separate@@ -1246,7 +1277,7 @@ class NotificationURLValidator:* ``hint_would_help`` — True iff enabling the documentedescape hatches together(``LDR_NOTIFICATIONS_ALLOW_PRIVATE_IPS`` for- RFC1918/CGNAT/loopback/link-local/IPv6 ULA, and+ RFC1918/CGNAT/loopback/IPv6 ULA, never link-local), and``LDR_SECURITY_ALLOW_NAT64`` for NAT64-wrappednon-metadata destinations) would unblock all resolvedaddresses — covering cases needing one or both flags.@@ -1287,12 +1318,11 @@ class NotificationURLValidator:)# ------------------------------------------------------------------- # Phase 1: structural validation (no DNS for http(s) hostnames).+ # Phase 1: structural validation (no DNS for hostnames).#- # resolved_ips=[] suppresses DNS in the http(s) private-IP check+ # resolved_ips=[] suppresses DNS in host-bearing private-IP checks# (_host_blocks_at_level treats [] as "no blocked IPs"). IP- # literals are still checked directly. Plugin-scheme IMDS guard- # resolves internally (does not use resolved_ips). This means+ # literals are still checked directly. This means# ALL deterministic rejections (bad scheme, illegal chars, parse# errors, non-ASCII host, invalid structure) complete before any# attacker-controlled DNS query.@@ -1305,69 +1335,53 @@ class NotificationURLValidator:))- # If the URL was rejected in Phase 1, no DNS was needed.+ try:+ destination = parse_notification_destination(url)+ except NotificationDestinationError:+ return is_valid, error_msg, False+ hostname = NotificationURLValidator._normalize_host(+ destination.effective_host+ )+ # Same link-local policy as ``_validate_service_url_impl``: the+ # opt-in never unblocks link-local, so the hint must not offer it.+ block_link_local = True+if not is_valid:- if error_msg in (- AMBIGUOUS_NUMERIC_IPV4_HOST_ERROR,- ENCODED_NUMERIC_IPV4_HOST_ERROR,- ):- return False, error_msg, False- if not error_msg or not error_msg.startswith(- NotificationURLValidator.PRIVATE_IP_REJECTION_PREFIX- ):- logger.debug(- "hint suppressed: non-private-IP rejection ({})",- error_msg[:60] if error_msg else "<none>",+ if (+ not error_msg+ or not error_msg.startswith(+ NotificationURLValidator.PRIVATE_IP_REJECTION_PREFIX)- return False, error_msg, False- # Private-IP rejection — must be an IP literal (hostnames- # weren't resolved in Phase 1). Compute hint without DNS.- hostname = NotificationURLValidator._normalize_host(- NotificationURLValidator._extract_host(url)- )- if not hostname:+ or not hostname+ ):return False, error_msg, Falsereturn (False,error_msg,- NotificationURLValidator._compute_hint(hostname, None),+ NotificationURLValidator._compute_hint(+ hostname, None, block_link_local=block_link_local+ ),)- # URL passed Phase 1. For non-http(s) URLs or IP literals,- # validation is complete.+ if (+ not hostname+ or destination.kind is NotificationDestinationKind.VENDOR_PLUGIN+ ):+ return True, None, Falsetry:- parsed_scheme = urlparse(url).scheme.lower()- except Exception:- parsed_scheme = ""-- hostname = NotificationURLValidator._normalize_host(- NotificationURLValidator._extract_host(url)- )-- is_http_hostname = False- if hostname and parsed_scheme in ("http", "https"):- try:- ipaddress.ip_address(hostname)- except ValueError:- is_http_hostname = True-- if not is_http_hostname:- # Non-http(s) or IP literal — fully validated in Phase 1.+ ipaddress.ip_address(hostname)+ except ValueError:+ pass+ else:return True, None, False- # ------------------------------------------------------------------- # Phase 2: resolve DNS ONCE for the http(s) hostname and run the- # real IP check. resolved_ips is authoritative for the rejection- # and hint check — no additional DNS lookups.- #- # [] = DNS attempted and failed (fail-open, no retry).- # [...] = resolved IPs shared across all policy decisions.- # ------------------------------------------------------------------+ # Resolve once after structural validation, then reuse that address+ # set for the decision and operator hint. The send-time guard covers+ # any later DNS change.dns_result = NotificationURLValidator._resolve_hostname_ips(hostname)- resolved_ips: Optional[List[ResolvedIP]] = (+ resolved_ips: List[ResolvedIP] = (dns_result if dns_result is not None else [])-is_valid, error_msg = (NotificationURLValidator._validate_service_url_impl(url,@@ -1381,11 +1395,12 @@ class NotificationURLValidator:NotificationURLValidator.PRIVATE_IP_REJECTION_PREFIX):return False, error_msg, False-return (False,error_msg,- NotificationURLValidator._compute_hint(hostname, resolved_ips),+ NotificationURLValidator._compute_hint(+ hostname, resolved_ips, block_link_local=block_link_local+ ),)@staticmethoddiff --git a/src/local_deep_research/security/ssrf_validator.py b/src/local_deep_research/security/ssrf_validator.pyindex f0939b288b..020809abdc 100644--- a/src/local_deep_research/security/ssrf_validator.py+++ b/src/local_deep_research/security/ssrf_validator.py@@ -244,6 +244,12 @@ def is_ip_blocked(try:ip = ipaddress.ip_address(ip_str)+ # Normalise an IPv6 zone identifier (``fd00:ec2::254%eth0``) away+ # before any check: a scoped address compares unequal to the same+ # unscoped literal, so the metadata set below would not match it.+ if isinstance(ip, ipaddress.IPv6Address) and ip.scope_id:+ ip = ipaddress.IPv6Address(ip.packed)+# Unwrap IPv4-mapped IPv6 addresses (e.g. ::ffff:127.0.0.1 → 127.0.0.1)# These bypass IPv4 range checks if not converted.if isinstance(ip, ipaddress.IPv6Address) and ip.ipv4_mapped:diff --git a/src/local_deep_research/settings/env_definitions/security.py b/src/local_deep_research/settings/env_definitions/security.pyindex b4764a44b4..0ae83fb317 100644--- a/src/local_deep_research/settings/env_definitions/security.py+++ b/src/local_deep_research/settings/env_definitions/security.py@@ -69,11 +69,10 @@ SECURITY_SETTINGS = [key="notifications.allow_outbound",description=("Master switch for outbound notification webhooks (Apprise). "- "Disabled by default because Apprise re-resolves DNS at send time, "- "leaving a DNS-rebinding TOCTOU window that cannot be closed in code "- "(Apprise exposes no Session/DNS hook). See SECURITY.md "- "'Notification Webhook SSRF' for details. Set to true only after "- "reviewing the residual risk. Distinct from the per-user "+ "Disabled by default so outbound delivery requires an explicit "+ "operator decision. The send path uses a synchronous DNS guard "+ "against rebinding and private/metadata access; see SECURITY.md "+ "'Notification Webhook SSRF' for details. Distinct from the per-user ""notifications.enabled toggle in the settings UI: this is the ""server-level operator gate, env-only so it cannot be flipped via ""the user-writable settings API."diff --git a/tests/notifications/test_notification_destination_guard.py b/tests/notifications/test_notification_destination_guard.pynew file mode 100644index 0000000000..c67ee57531--- /dev/null+++ b/tests/notifications/test_notification_destination_guard.py@@ -0,0 +1,812 @@+"""Effective notification destination and send-time guard regressions."""++from contextlib import nullcontext+import ipaddress+from unittest.mock import MagicMock, patch++import pytest++from local_deep_research.notifications.service import NotificationService+from local_deep_research.security import dns_pinning+from local_deep_research.security.notification_validator import (+ NotificationURLValidator,+)+++ "url",+ [+ "json://127.0.0.1:8000/hook",+ "signal://10.0.0.5:8739/+15551234567/+15557654321",+ "gotify://10.0.0.5:8080/token",+ "ntfy://127.0.0.1/topic?mode=private",+ "matrix://user:[email protected]/%23room?mode=matrix",+ ],+)+def test_authority_plugin_needs_operator_private_opt_in(url):+ denied, reason = NotificationURLValidator.validate_service_url(url)+ allowed, _ = NotificationURLValidator.validate_service_url(+ url, allow_private_ips=True+ )+ assert denied is False+ assert "private/internal" in reason.lower()+ assert allowed is True+++def test_authority_plugin_link_local_remains_blocked_with_opt_in():+ allowed, reason = NotificationURLValidator.validate_service_url(+ "json://169.254.42.42/hook", allow_private_ips=True+ )+ assert allowed is False+ assert "link-local" in reason.lower()+++def test_dispatch_separates_authority_and_vendor_dns_guards(monkeypatch):+ service = NotificationService(allow_private_ips=True, outbound_allowed=True)+ service._new_apprise = MagicMock()+ service._new_apprise.return_value.add.return_value = True+ guards = []++ def fake_guard(urls, **policy):+ guards.append((urls, policy))+ return nullcontext()++ def fake_send(_title, _body, _apprise, guard_factory, _tag, _attach):+ with guard_factory():+ pass+ return True++ monkeypatch.setattr(dns_pinning, "pinned_notification_send", fake_guard)+ monkeypatch.setattr(service, "_send_with_retry", fake_send)+ assert service._dispatch(+ "title",+ "body",+ [],+ ["json://10.0.0.5/hook", "discord://id/token"],+ None,+ None,+ )+ assert len(guards) == 2+ assert guards[0][0] == ["json://10.0.0.5/hook"]+ assert guards[0][1]["allow_private_ips"] is True+ assert guards[0][1]["block_link_local"] is True+ assert guards[1][0] == ["discord://id/token"]+ # Fixed vendor endpoints follow the operator opt-in too (a private+ # forward proxy is the only private lookup they make).+ assert guards[1][1]["allow_private_ips"] is True+ assert guards[1][1]["block_link_local"] is True+++def test_dispatch_vendor_guard_is_public_only_by_default(monkeypatch):+ service = NotificationService(outbound_allowed=True)+ service._new_apprise = MagicMock()+ service._new_apprise.return_value.add.return_value = True+ guards = []++ def fake_guard(urls, **policy):+ guards.append((urls, policy))+ return nullcontext()++ def fake_send(_title, _body, _apprise, guard_factory, _tag, _attach):+ with guard_factory():+ pass+ return True++ monkeypatch.setattr(dns_pinning, "pinned_notification_send", fake_guard)+ monkeypatch.setattr(service, "_send_with_retry", fake_send)+ assert service._dispatch(+ "title", "body", [], ["discord://id/token"], None, None+ )+ assert guards == [+ (+ ["discord://id/token"],+ {+ "allow_localhost": False,+ "allow_private_ips": False,+ "block_link_local": True,+ },+ )+ ]+++ "url",+ [+ "signal://evil.com%2F.local/+15551234567/+15557654321",+ "signal://evil.com%23.local/+15551234567/+15557654321",+ "signal://evil.com%3F.local/+15551234567/+15557654321",+ "signal://10.0.0.5%2Fevil.com/+15551234567/+15557654321",+ "json://evil.com%2F.local/hook",+ "gotify://evil.com%252F.local/token",+ "ntfy://evil.com%2F.local/topic",+ "mailto://u:[email protected]%2F.local",+ "matrix://u:[email protected]%2F.local/%23room",+ ],+)+def test_percent_encoded_plugin_host_is_refused(url):+ from local_deep_research.security.notification_destination import (+ NotificationDestinationError,+ parse_notification_destination,+ )++ with pytest.raises(NotificationDestinationError):+ parse_notification_destination(url)+ with patch.object(+ NotificationURLValidator,+ "_resolve_hostname_ips",+ side_effect=AssertionError("ambiguous plugin host must not resolve"),+ ):+ allowed, _reason = NotificationURLValidator.validate_service_url(+ url, allow_private_ips=True+ )+ assert allowed is False+++def test_destination_error_survives_contextmanager_traceback():+ from contextlib import contextmanager++ from local_deep_research.security.notification_destination import (+ NotificationDestinationError,+ )++ @contextmanager+ def scope():+ yield++ with pytest.raises(NotificationDestinationError) as caught:+ with scope():+ raise NotificationDestinationError("reason")+ assert str(caught.value) == "reason"+ assert caught.value.reason == "reason"+++def test_admin_test_url_explains_private_plugin_opt_in():+ service = NotificationService(outbound_allowed=True)+ result = service.test_service("json://127.0.0.1:8000/hook")+ assert result["success"] is False+ assert "LDR_NOTIFICATIONS_ALLOW_PRIVATE_IPS=true" in result["error"]+++def test_admin_test_url_does_not_suggest_opt_in_for_link_local():+ service = NotificationService(allow_private_ips=True, outbound_allowed=True)+ result = service.test_service("json://169.254.42.42/hook")+ assert result["success"] is False+ assert "LDR_NOTIFICATIONS_ALLOW_PRIVATE_IPS" not in result["error"]+++def test_direct_plugin_validation_uses_one_dns_answer_for_decision():+ with patch.object(+ NotificationURLValidator,+ "_resolve_hostname_ips",+ return_value=[ipaddress.ip_address("10.0.0.5")],+ ) as resolver:+ allowed, reason = NotificationURLValidator.validate_service_url(+ "json://hook.example/hook"+ )+ assert allowed is False+ assert "private/internal" in reason.lower()+ resolver.assert_called_once_with("hook.example")+++ "url",+ [+ "ntfy://169.254.169.254?to=x",+ "ntfys://169.254.169.254/?to=alerts",+ "ntfy://169.254.169.254?x=1;To=x",+ ],+)+def test_ntfy_to_query_topic_still_blocks_metadata_host(url):+ allowed, reason = NotificationURLValidator.validate_service_url(+ url, allow_private_ips=True+ )+ assert allowed is False+ assert "metadata" in reason.lower()+++def test_ntfy_to_query_topic_needs_private_opt_in_like_path_topic():+ for url in ("ntfy://10.0.0.5/topic", "ntfy://10.0.0.5?to=topic"):+ denied, reason = NotificationURLValidator.validate_service_url(url)+ allowed, _ = NotificationURLValidator.validate_service_url(+ url, allow_private_ips=True+ )+ assert denied is False+ assert "private/internal" in reason.lower()+ assert allowed is True+++# The classification must match where Apprise really sends, in BOTH+# directions: VENDOR skips host checks, so Apprise must not send to the URL+# host; AUTHORITY(host) passes the egress scope on that host, so Apprise must+# not send anywhere else (for example ntfy cloud mode posting to ntfy.sh).+# ntfy ground truth is the URL Apprise actually POSTs to with requests+# mocked; Matrix ground truth is the mode and host of the plugin Apprise+# builds.+_TOKEN = "a" * 64+_VENDOR_HOSTS = {"ntfy.sh", "webhooks.t2bot.io"}+_APPRISE_HOST_CASES = [+ f"{scheme}://{host}{path}{query}"+ for scheme, hosts in (+ (+ "ntfy",+ (+ "evil.example.com",+ "10.0.0.5",+ "localhost:8080",+ "topic",+ "homelab_",+ "a.1.lan",+ "foo..lan",+ "Ntfy.Sh.",+ ),+ ),+ ("ntfys", ("evil.example.com", "[fd00::1]")),+ ("matrix", ("evil.example.com", _TOKEN, "[email protected]")),+ )+ for host in hosts+ for path in ("", "/", "/t", "/%20", "#t", "/#/t", "/#x/t", "#x?to=t")+ for query in (+ "",+ "?to=t",+ "?To=t",+ "?%74o=t",+ "?x=1;to=t",+ "?to=",+ "?to=,",+ "?to=%20",+ "?mode=private",+ "?mode=cloud&to=t",+ "?mode=private&to=t",+ "?mode=hookshot",+ )+] + [+ "ntfy://localhost?to=",+ "ntfy://ntfy?to=,",+ "ntfy://homelab_/alerts",+ "ntfy://nas.lan/?to=%20",+ "ntfys://ntfy-server?to=",+ "ntfy://10.0.0.5:8080/#/alerts",+]+++def _apprise_send_hosts(url):+ from urllib.parse import urlsplit++ import apprise+ from apprise.plugins.matrix import NotifyMatrix+ from apprise.plugins.ntfy import NotifyNtfy++ plugin = apprise.Apprise.instantiate(+ url, asset=apprise.AppriseAsset(async_mode=False)+ )+ if url.startswith("matrix"):+ # The plugin Apprise.add builds (url_to_dict rewrites ``/#`` to+ # ``/%23`` before parsing, so NotifyMatrix.parse_url alone differs).+ if not isinstance(plugin, NotifyMatrix):+ return set()+ if str(plugin.mode or "").lower() == "t2bot":+ return {"webhooks.t2bot.io"}+ return {plugin.host.strip("[]").rstrip(".").lower()}+ if not isinstance(plugin, NotifyNtfy):+ return set()+ plugin.request_rate_per_sec = 0+ hosts = set()++ def record(target, *args, **kwargs):+ hosts.add((urlsplit(target).hostname or "").rstrip(".").lower())+ response = MagicMock(status_code=200, content=b"{}", text="{}")+ response.json.return_value = {}+ return response++ with patch("apprise.plugins.ntfy.requests.post", side_effect=record):+ plugin.send(body="body", title="title")+ return hosts+++ "url", _APPRISE_HOST_CASES, ids=range(len(_APPRISE_HOST_CASES))+)+def test_classification_matches_apprise_send_destination(url):+ from local_deep_research.security.notification_destination import (+ NotificationDestinationError,+ NotificationDestinationKind,+ parse_notification_destination,+ )++ try:+ destination = parse_notification_destination(url)+ except NotificationDestinationError:+ return+ sent_to = _apprise_send_hosts(url)+ if destination.kind is NotificationDestinationKind.VENDOR_PLUGIN:+ assert sent_to <= _VENDOR_HOSTS, (url, sent_to)+ else:+ assert destination.kind is NotificationDestinationKind.AUTHORITY_PLUGIN+ assert sent_to <= {destination.effective_host}, (url, sent_to)+++ ("url", "kind", "host"),+ [+ # Apprise cloud mode: an empty/blank ``to=`` is not a topic and an+ # invalid host becomes a topic; both POST to ntfy.sh.+ ("ntfy://localhost?to=", "vendor_plugin", None),+ ("ntfy://ntfy?to=,", "vendor_plugin", None),+ ("ntfy://nas.lan/?to=%20", "vendor_plugin", None),+ ("ntfy://homelab_/alerts", "vendor_plugin", None),+ ("ntfy://a.1.lan/topic", "vendor_plugin", None),+ # Apprise private mode: a topic in ``to=`` or after ``/#/`` sends+ # to the URL host.+ (+ "ntfy://evil.example.com?to=topic",+ "authority_plugin",+ "evil.example.com",+ ),+ (+ "ntfy://evil.example.com/#/topic",+ "authority_plugin",+ "evil.example.com",+ ),+ ("ntfy://10.0.0.5:8080/#/alerts", "authority_plugin", "10.0.0.5"),+ ("ntfy://nas.lan/topic", "authority_plugin", "nas.lan"),+ ("ntfy://topic", "vendor_plugin", None),+ ],+)+def test_ntfy_classification_follows_apprise_mode(url, kind, host):+ from local_deep_research.security.notification_destination import (+ parse_notification_destination,+ )++ destination = parse_notification_destination(url)+ assert (destination.kind.value, destination.effective_host) == (kind, host)+++ ("url", "host"),+ [+ ("json://Hook.Example.com/hook", "hook.example.com"),+ ("gotify://NAS.Example.com:8080/token", "nas.example.com"),+ ("mailto://me:[email protected]", "mail.example.com"),+ ("ntfy://Ntfy.Example.com/topic", "ntfy.example.com"),+ ],+)+def test_mixed_case_plugin_host_is_not_ambiguous(url, host):+ with patch.object(+ NotificationURLValidator,+ "_resolve_hostname_ips",+ return_value=[ipaddress.ip_address("93.184.216.34")],+ ) as resolver:+ assert NotificationURLValidator.validate_service_url(url) == (+ True,+ None,+ )+ resolver.assert_called_once_with(host)+++def test_mixed_case_ipv6_plugin_literal_follows_private_policy():+ # Uncompressed: Apprise 1.13 rewrites a compressed literal such as+ # ``[FD00::1]`` (see test_ipv6_literal_rewritten_by_apprise_is_refused).+ url = "json://[FD00:0:0:0:0:0:0:1]/hook"+ denied, reason = NotificationURLValidator.validate_service_url(url)+ assert denied is False+ assert "private/internal" in reason.lower()+ assert NotificationURLValidator.validate_service_url(+ url, allow_private_ips=True+ ) == (True, None)+++def _zone_id_metadata_hosts():+ from local_deep_research.security.ssrf_validator import (+ ALWAYS_BLOCKED_METADATA_IPS,+ )++ hosts = []+ for ip in sorted(ALWAYS_BLOCKED_METADATA_IPS):+ literal = ip if ":" in ip else f"::ffff:{ip}"+ hosts += [f"[{literal}%25eth0]", f"[{literal}%eth0]"]+ return hosts++[email protected]("allow_private_ips", [False, True])[email protected]("scheme", ["http", "https", "json", "gotify"])[email protected]("host", _zone_id_metadata_hosts())+def test_zone_id_metadata_literal_is_refused(host, scheme, allow_private_ips):+ url = f"{scheme}://{host}/path"+ with patch.object(+ NotificationURLValidator,+ "_resolve_hostname_ips",+ side_effect=AssertionError("an IP literal must not resolve"),+ ):+ allowed, _reason = NotificationURLValidator.validate_service_url(+ url, allow_private_ips=allow_private_ips+ )+ assert allowed is False++[email protected]("allow_private_ips", [False, True])+def test_scoped_metadata_address_is_blocked_at_send_time(allow_private_ips):+ from local_deep_research.security.ssrf_validator import is_ip_blocked++ assert is_ip_blocked(+ "fd00:ec2::254%eth0", allow_private_ips=allow_private_ips+ )+++# Apprise's email parser discards an authority it does not accept as a+# hostname (an empty port, an underscore) and takes the SMTP host from the+# domain of an address in the userinfo or ``?user=``. LDR must not classify+# such a URL by its authority.+_MAIL_REDIRECT_URLS = [+ "mailto://public.example.com:[email protected]",+ "mailto://public.example.com:[email protected]",+ "mailto://u%40intranet.test:[email protected]:",+ "mailto://u:pw@[email protected]",+]++[email protected]("url", _MAIL_REDIRECT_URLS)+def test_mailto_smtp_host_moved_by_apprise_is_refused(url):+ from local_deep_research.security.notification_destination import (+ NotificationDestinationError,+ parse_notification_destination,+ )++ with pytest.raises(NotificationDestinationError):+ parse_notification_destination(url)+ with patch.object(+ NotificationURLValidator,+ "_resolve_hostname_ips",+ return_value=[ipaddress.ip_address("93.184.216.34")],+ ):+ allowed, _reason = NotificationURLValidator.validate_service_url(+ url, allow_private_ips=True+ )+ assert allowed is False+++ ("url", "host"),+ [+ ("mailto://u:[email protected]", "mail.example.com"),+ ("mailto://[email protected]", "example.com"),+ # Built-in provider: Apprise connects to its fixed smtp.gmail.com.+ ("mailto://u:[email protected]", "gmail.com"),+ ("mailto://[email protected]", "gmail.com"),+ ],+)+def test_mailto_authority_or_provider_mapping_is_accepted(url, host):+ from local_deep_research.security.notification_destination import (+ parse_notification_destination,+ )++ destination = parse_notification_destination(url)+ assert (destination.kind.value, destination.effective_host) == (+ "authority_plugin",+ host,+ )+++_MAIL_DIFFERENTIAL_CASES = [+ f"mailto://{userinfo}{host}{port}{query}"+ for userinfo in ("", "u:p@", "u%40intranet.test:p@", "x@")+ for host in ("public.example.com", "lo_cal.lan", "10.0.0.5", "gmail.com")+ for port in ("", ":", ":25")+ for query in ("", "[email protected]", "[email protected]")+]+++ "url", _MAIL_DIFFERENTIAL_CASES, ids=range(len(_MAIL_DIFFERENTIAL_CASES))+)+def test_mailto_classification_matches_apprise_smtp_host(url):+ import apprise+ from apprise.plugins.email.templates import EMAIL_TEMPLATES++ from local_deep_research.security.notification_destination import (+ NotificationDestinationError,+ parse_notification_destination,+ )++ try:+ destination = parse_notification_destination(url)+ except NotificationDestinationError:+ return+ plugin = apprise.Apprise.instantiate(+ url, asset=apprise.AppriseAsset(async_mode=False)+ )+ if plugin is None:+ return+ provider_hosts = {+ template[2]["smtp_host"]+ for template in EMAIL_TEMPLATES+ if template[2].get("smtp_host")+ }+ smtp_host = plugin.smtp_host.strip("[]").rstrip(".").lower()+ assert smtp_host in {destination.effective_host} | provider_hosts, (+ url,+ smtp_host,+ )+++_MATRIX_TOKEN = "a" * 64+++ ("url", "kind", "host"),+ [+ # Apprise's documented room-alias forms reach the URL host.+ (+ "matrix://user:[email protected]/#room",+ "authority_plugin",+ "matrix.example.com",+ ),+ (+ "matrix://user:[email protected]/?to=%23room",+ "authority_plugin",+ "matrix.example.com",+ ),+ (+ "matrix://user:[email protected]",+ "authority_plugin",+ "matrix.example.com",+ ),+ # Apprise's t2bot forms post to webhooks.t2bot.io.+ (f"matrix://user@{_MATRIX_TOKEN}", "vendor_plugin", None),+ (f"matrix://{_MATRIX_TOKEN}/", "vendor_plugin", None),+ (f"matrix://{_MATRIX_TOKEN}", "vendor_plugin", None),+ ],+)+def test_matrix_forms_accepted_by_apprise_are_classified(url, kind, host):+ from apprise.plugins import url_to_dict++ from local_deep_research.security.notification_destination import (+ parse_notification_destination,+ )++ apprise_mode = str(url_to_dict(url).get("mode") or "").lower()+ assert (apprise_mode == "t2bot") is (kind == "vendor_plugin")+ destination = parse_notification_destination(url)+ assert (destination.kind.value, destination.effective_host) == (+ kind,+ host,+ )+ with patch.object(+ NotificationURLValidator,+ "_resolve_hostname_ips",+ return_value=[ipaddress.ip_address("93.184.216.34")],+ ):+ assert NotificationURLValidator.validate_service_url(url) == (+ True,+ None,+ )+++ "url",+ ["http://169.254.42.42/notify/abc", "https://[fe80::1]/x"],+)+def test_http_link_local_is_blocked_even_with_opt_in(url):+ # Apprise turns http://<host>/notify/<token> into its Apprise API+ # plugin, which posts to the URL host.+ allowed, reason = NotificationURLValidator.validate_service_url(+ url, allow_private_ips=True+ )+ assert allowed is False+ assert "link-local" in reason.lower()+++def test_dispatch_http_guard_blocks_link_local(monkeypatch):+ service = NotificationService(allow_private_ips=True, outbound_allowed=True)+ service._new_apprise = MagicMock()+ service._new_apprise.return_value.add.return_value = True+ guards = []++ def fake_guard(urls, **policy):+ guards.append((urls, policy))+ return nullcontext()++ def fake_send(_title, _body, _apprise, guard_factory, _tag, _attach):+ with guard_factory():+ pass+ return True++ monkeypatch.setattr(dns_pinning, "pinned_notification_send", fake_guard)+ monkeypatch.setattr(service, "_send_with_retry", fake_send)+ assert service._dispatch(+ "title", "body", ["http://hook.example/notify/abc"], [], None, None+ )+ assert guards == [+ (+ ["http://hook.example/notify/abc"],+ {+ "allow_localhost": False,+ "allow_private_ips": True,+ "block_link_local": True,+ },+ )+ ]+++def test_test_service_http_guard_blocks_link_local(monkeypatch):+ service = NotificationService(allow_private_ips=True, outbound_allowed=True)+ guards = []++ def fake_guard(urls, **policy):+ guards.append((urls, policy))+ return nullcontext()++ monkeypatch.setattr(dns_pinning, "pinned_notification_send", fake_guard)+ monkeypatch.setattr(+ NotificationURLValidator,+ "validate_service_url_with_hint",+ staticmethod(lambda *_args, **_kwargs: (True, None, False)),+ )++ def fake_notify(_title, _body, _apprise, guard_factory, *_args, **_kw):+ with guard_factory():+ return True++ monkeypatch.setattr(service, "_guarded_notify", fake_notify)+ service.test_service("http://hook.example/notify/abc")+ assert guards, "test_service never built its send guard"+ assert guards[0][1]["block_link_local"] is True+++ "url", ["http://[fd00::1%25eth0]/x", "https://[fe80::1%25eth0]/x"]+)+def test_zone_identifier_is_refused_by_the_classifier(url):+ from local_deep_research.security.notification_destination import (+ NotificationDestinationError,+ parse_notification_destination,+ )++ with pytest.raises(NotificationDestinationError):+ parse_notification_destination(url)+++# Apprise 1.13's generic URL parser rewrites compressed IPv6 literals:+# ``json://[fd00::1]/x`` builds a plugin whose host is ``[fd00::]`` and+# ``[::ffff:10.0.0.5]`` becomes ``[::ffff:10]``. Policy would vet one+# address while Apprise connects to another, so the classifier refuses it.+_APPRISE_REWRITTEN_IPV6_URLS = [+ "json://[fd00::1]/hook",+ "json://[fd00::1]:8080/hook",+ "xml://[2001:db8::1]/hook",+ "form://[::ffff:10.0.0.5]/hook",+ "gotify://[FD00::1]/token",+ "json://[fe80::1]/hook",+ "signal://[::ffff:10.0.0.5]:8080/+15551234567/+15557654321",+ "signal://[FD00::1]:8080/+15551234567/+15557654321",+]++[email protected]("url", _APPRISE_REWRITTEN_IPV6_URLS)+def test_ipv6_literal_rewritten_by_apprise_is_refused(url):+ from urllib.parse import urlsplit++ from apprise import Apprise++ from local_deep_research.security.notification_destination import (+ NotificationDestinationError,+ parse_notification_destination,+ )++ # Premise: Apprise builds this URL with a host that is not the URL's+ # address (another address, or for Signal with a port a mixed-case or+ # mapped literal that keeps ``:port`` inside the host).+ plugin = Apprise.instantiate(url)+ assert plugin is not None+ literal = ipaddress.ip_address(urlsplit(url).hostname)+ try:+ assert ipaddress.ip_address(plugin.host.strip("[]")) != literal+ except ValueError:+ pass++ with pytest.raises(NotificationDestinationError):+ parse_notification_destination(url)+ for allow_private_ips in (False, True):+ assert NotificationURLValidator.validate_service_url(+ url, allow_private_ips=allow_private_ips+ ) == (False, "Notification destination is unsupported or ambiguous")+++ ("url", "host"),+ [+ ("json://[fd00:0:0:0:0:0:0:1]/hook", "fd00:0:0:0:0:0:0:1"),+ ("gotify://[fd00::]:8080/token", "fd00::"),+ ("xml://[::1]/hook", "::1"),+ (+ "signal://[fd00::1]/+15551234567/+15557654321",+ "fd00::1",+ ),+ # Apprise does not build these, so it sends nothing to any host.+ ("mattermost://[fd00::1]/token", "fd00::1"),+ ("http://[fd00::1]/notify/key", "fd00::1"),+ ],+)+def test_ipv6_literal_kept_by_apprise_is_classified(url, host):+ from apprise import Apprise++ from local_deep_research.security.notification_destination import (+ parse_notification_destination,+ )++ destination = parse_notification_destination(url)+ assert destination.effective_host == host+ plugin = Apprise.instantiate(url)+ if plugin is not None:+ assert ipaddress.ip_address(+ plugin.host.strip("[]")+ ) == ipaddress.ip_address(host)+++# Apprise's port regex for a bracketed literal only matches lowercase hex, so+# an uppercase literal keeps its host but loses its port: the plugin built+# from ``json://[FD00:0:0:0:0:0:0:1]:8080/hook`` posts to port 80. The+# classifier compares the port as well as the host and refuses it.+_APPRISE_PORT_DROPPED_IPV6_URLS = [+ "json://[FD00:0:0:0:0:0:0:1]:8080/hook",+ "xml://[FD00:0:0:0:0:0:0:1]:8080/hook",+ "form://[Fd00:0:0:0:0:0:0:1]:8443/hook",+ "gotify://[FD00::]:8080/token",+ "json://[fd00:0:0:0:0:0:0:A]:8080/hook",+]++[email protected]("url", _APPRISE_PORT_DROPPED_IPV6_URLS)+def test_ipv6_literal_whose_port_apprise_drops_is_refused(url):+ from urllib.parse import urlsplit++ from apprise import Apprise++ from local_deep_research.security.notification_destination import (+ NotificationDestinationError,+ parse_notification_destination,+ )++ # Premise: Apprise keeps the address but drops the URL's port.+ plugin = Apprise.instantiate(url)+ assert plugin is not None+ parts = urlsplit(url)+ assert ipaddress.ip_address(+ plugin.host.strip("[]")+ ) == ipaddress.ip_address(parts.hostname)+ assert parts.port is not None+ assert plugin.port != parts.port++ with pytest.raises(NotificationDestinationError):+ parse_notification_destination(url)+ for allow_private_ips in (False, True):+ assert NotificationURLValidator.validate_service_url(+ url, allow_private_ips=allow_private_ips+ ) == (False, "Notification destination is unsupported or ambiguous")+++ "url",+ [+ "json://[fd00:0:0:0:0:0:0:1]:8080/hook",+ "gotify://[fd00::]:8443/token",+ "signal://[fd00::1]:8080/+15551234567/+15557654321",+ "json://[FD00:0:0:0:0:0:0:1]/hook",+ ],+)+def test_ipv6_literal_whose_port_apprise_keeps_is_classified(url):+ from urllib.parse import urlsplit++ from apprise import Apprise++ from local_deep_research.security.notification_destination import (+ parse_notification_destination,+ )++ parts = urlsplit(url)+ destination = parse_notification_destination(url)+ assert ipaddress.ip_address(+ destination.effective_host+ ) == ipaddress.ip_address(parts.hostname)+ plugin = Apprise.instantiate(url)+ assert plugin is not None+ assert plugin.port == parts.portdiff --git a/tests/notifications/test_notification_webhook_dns_pin.py b/tests/notifications/test_notification_webhook_dns_pin.pyindex 8d88c7aea3..61dd8a2786 100644--- a/tests/notifications/test_notification_webhook_dns_pin.py+++ b/tests/notifications/test_notification_webhook_dns_pin.py@@ -202,8 +202,10 @@ def _connect_spy():yield targets-def _service():- return NotificationService(allow_private_ips=False, outbound_allowed=True)+def _service(*, allow_private_ips=False):+ return NotificationService(+ allow_private_ips=allow_private_ips, outbound_allowed=True+ )# ==========================================================================@@ -332,7 +334,7 @@ def test_public_json_webhook_delivers_through_apprise():resolver = _Resolver({"good.example": [["127.0.0.1"]]})try:with patch.object(dns_pinning, "_real_getaddrinfo", resolver):- result = _service().send(+ result = _service(allow_private_ips=True).send(title="t",body="b",service_urls=f"json://good.example:{port}/notify",@@ -369,6 +371,20 @@ def test_rebind_to_metadata_blocked_through_apprise():)+def test_raw_plugin_private_rebind_refused_without_operator_opt_in():+ """A public validation answer cannot become a loopback send target."""+ resolver = _Resolver({"rebind.example": [["93.184.216.34"], ["127.0.0.1"]]})+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):+ with _connect_spy() as targets:+ with pytest.raises(SecurityBlockError):+ _service().send(+ title="t",+ body="b",+ service_urls="json://rebind.example/notify",+ )+ assert not any(addr[0] == "127.0.0.1" for addr in targets)++def test_multi_url_batch_guards_every_host():"""A single notify() fans out to several raw-webhook URLs. EVERY host inthe batch is pinned/checked: one host that rebinds to metadata refuses@@ -388,7 +404,9 @@ def test_multi_url_batch_guards_every_host():with patch.object(dns_pinning, "_real_getaddrinfo", resolver):with _connect_spy() as targets:with pytest.raises(SecurityBlockError):- _service().send(title="t", body="b", service_urls=urls)+ _service(allow_private_ips=True).send(+ title="t", body="b", service_urls=urls+ )try:assert not any(addr[0] == "169.254.169.254" for addr in targets)finally:@@ -415,7 +433,7 @@ def test_redirect_to_metadata_blocked_at_socket_layer():with patch.object(dns_pinning, "_real_getaddrinfo", resolver):with _connect_spy() as targets:with pytest.raises(SendError):- _service().send(+ _service(allow_private_ips=True).send(title="t",body="b",service_urls=f"json://public.example:{port}/hook",@@ -452,7 +470,7 @@ def test_redirect_following_disabled_by_default():with patch.object(dns_pinning, "_real_getaddrinfo", resolver):with _connect_spy() as targets:with pytest.raises(SendError):- _service().send(+ _service(allow_private_ips=True).send(title="t",body="b",service_urls=f"json://public.example:{hook_port}/hook",@@ -532,7 +550,7 @@ def test_redirect_param_yes_cannot_reenable_redirects():with patch.object(dns_pinning, "_real_getaddrinfo", resolver):with _connect_spy() as targets:with pytest.raises(SendError):- _service().send(+ _service(allow_private_ips=True).send(title="t",body="b",service_urls=(@@ -1438,7 +1456,10 @@ def test_rfc1918_json_webhook_still_delivers_end_to_end():# / a bare IPv6 ``fe80::`` address, both ordinary link-local space that# ``allow_private_ips=True`` would otherwise ADMIT. So a refusal here can# only come from the ``block_link_local=True`` threaded through the-# call site under test, giving each test real teeth against that one wire.+# call site under test. The two ``_dispatch`` tests build the service with+# ``allow_private_ips=True`` so they have real teeth against that one wire;+# the ``test_service`` test below uses the default service and locks the+# refusal only (its flag is locked in test_notification_destination_guard.py).# ==========================================================================def test_link_local_rebind_refused_by_dispatch_lenient_partition():"""WIRING lock for ``_dispatch``'s lenient-partition@@ -1448,16 +1469,17 @@ def test_link_local_rebind_refused_by_dispatch_lenient_partition():validation (resolver call #1) but rebinds to Scaleway's link-localmetadata address ``169.254.42.42`` at ``_dispatch``'s ``pin_hosts``resolution (call #2, "pin time" — json:// is a pinnable scheme).- ``169.254.42.42`` is ordinary link-local space, allowed under- ``allow_private_ips=True`` (the lenient partition's policy); it is- refused ONLY because ``_dispatch`` also passes+ ``169.254.42.42`` is ordinary link-local space, which the+ ``allow_private_ips=True`` opt-in (set on the service here) would+ otherwise admit; it is refused ONLY because ``_dispatch`` also passes``block_link_local=True`` into that same ``pinned_notification_send``call. ``send()`` must refuse it and no connection may reach thelink-local IP.- Teeth: change ``block_link_local=True`` to ``False`` at _dispatch's- lenient ``pinned_notification_send`` call (service.py ~line 535,- leaving ``is_ip_blocked`` / the validator untouched) and this test+ Teeth: the service uses ``allow_private_ips=True`` so the address is+ NOT refused as private. Change ``block_link_local=True`` to ``False``+ at _dispatch's authority-partition ``pinned_notification_send`` call+ (leaving ``is_ip_blocked`` / the validator untouched) and this testfails — the rebind pins successfully and the connect spy sees169.254.42.42.@@ -1472,7 +1494,7 @@ def test_link_local_rebind_refused_by_dispatch_lenient_partition():with patch.object(dns_pinning, "_real_getaddrinfo", resolver):with _connect_spy() as targets:with pytest.raises(SecurityBlockError):- _service().send(+ _service(allow_private_ips=True).send(title="t",body="b",service_urls="json://ll-rebind.example/notify",@@ -1487,7 +1509,9 @@ def test_link_local_rebind_refused_by_dispatch_lenient_partition_ipv6():public IPv6 (resolver call #1) but rebinds to a bare IPv6 link-localaddress ``fe80::1`` (fe80::/10, not an always-blocked literal) at``_dispatch``'s pin resolution (call #2). Same wiring lock —- refused only by ``_dispatch``'s ``block_link_local=True``. The+ refused only by ``_dispatch``'s ``block_link_local=True`` (the+ service sets ``allow_private_ips=True``, so it is not refused as+ private). Theconfirmed rebind raises ``SecurityBlockError`` (non-retryable, a``ServiceError`` subclass), not SendError. Asserting the subclass pinsthis to the send-time rebind path, not a pre-dispatch reject."""@@ -1502,7 +1526,7 @@ def test_link_local_rebind_refused_by_dispatch_lenient_partition_ipv6():with patch.object(dns_pinning, "_real_getaddrinfo", resolver):with _connect_spy() as targets:with pytest.raises(SecurityBlockError):- _service().send(+ _service(allow_private_ips=True).send(title="t",body="b",service_urls="json://ll-rebind6.example/notify",@@ -1514,8 +1538,7 @@ def test_link_local_rebind_refused_by_dispatch_lenient_partition_ipv6():def test_test_service_link_local_rebind_refused_by_guard_factory():"""WIRING lock for ``test_service``'s guard-factory- ``block_link_local=is_plugin_scheme`` (``notifications/service.py``- ~line 710).+ ``block_link_local=True`` (``notifications/service.py``).``ntfy://`` is a plugin scheme (not in ``_PINNABLE_SCHEMES``), so``pin_hosts`` never resolves/pins it; the send-time lookup instead runs@@ -1523,17 +1546,14 @@ def test_test_service_link_local_rebind_refused_by_guard_factory():consults the SAME ``block_link_local`` flag ``test_service`` threadsinto its guard factory. The host validates public at ``test_service``'spre-send validation (resolver call #1) and rebinds to Scaleway's- link-local ``169.254.42.42`` at send time (call #2) — refused only- because ``block_link_local=True`` is threaded through THIS call site,- not because the address is otherwise blocked (it is ordinary link-local- space, allowed under ``allow_private_ips=True``, which plugin schemes- always run with).-- Teeth: change ``block_link_local=is_plugin_scheme`` to- ``block_link_local=False`` in test_service's guard_factory (service.py- ~line 710) and this test fails — the block window admits the- link-local resolution, Apprise connects, and the connect spy sees- 169.254.42.42.+ link-local ``169.254.42.42`` at send time (call #2), and the window+ refuses it.++ Teeth: with ``allow_private_ips=False`` (the service used here) the+ address is refused as private even without ``block_link_local``, so+ this test locks the refusal rather than that one flag;+ ``test_test_service_http_guard_blocks_link_local`` in+ ``test_notification_destination_guard.py`` locks the flag itself."""resolver = _Resolver({"ll-rebind-ts.example": [["93.184.216.34"], ["169.254.42.42"]]}@@ -1574,3 +1594,39 @@ def test_empty_authority_metadata_in_path_rejected_before_send():service_urls="json:///169.254.169.254/path",)assert not any(addr[0] == "169.254.169.254" for addr in targets), targets+++# ==========================================================================+# Fixed vendor endpoints behind a private forward proxy. requests honours+# HTTPS_PROXY, so the only lookup in the sending thread is the proxy host,+# and the send-time guard checks it. The vendor partition follows the+# operator's private-IP opt-in: refused by default, allowed with the flag.+# ==========================================================================[email protected]("allow_private_ips", [False, True])+def test_vendor_send_through_private_proxy_follows_operator_opt_in(+ monkeypatch, allow_private_ips+):+ for name in ("NO_PROXY", "no_proxy", "ALL_PROXY", "all_proxy"):+ monkeypatch.delenv(name, raising=False)+ monkeypatch.setenv("HTTPS_PROXY", "http://proxy.lan:3128")+ monkeypatch.setenv("https_proxy", "http://proxy.lan:3128")+ resolver = _Resolver({"proxy.lan": [["10.0.0.8"]]})+ targets = []++ def refuse_connect(self, address):+ # Record the attempt but never open a real connection.+ targets.append(address)+ raise ConnectionRefusedError("test proxy is not listening")++ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):+ with patch.object(socket.socket, "connect", refuse_connect):+ result = _service(allow_private_ips=allow_private_ips).test_service(+ "discord://123456789/abcdefghijklmnop"+ )++ assert result["success"] is False+ assert ("proxy.lan", 3128) in resolver.calls+ reached_proxy = any(addr[0] == "10.0.0.8" for addr in targets)+ assert reached_proxy is allow_private_ips, targets+ if not allow_private_ips:+ assert "SSRF" in result["error"], result["error"]diff --git a/tests/security/test_egress_notifications_callsite.py b/tests/security/test_egress_notifications_callsite.pyindex 881079b58f..7e5453c573 100644--- a/tests/security/test_egress_notifications_callsite.py+++ b/tests/security/test_egress_notifications_callsite.py@@ -246,3 +246,64 @@ def test_test_service_endpoint_respects_private_only():allow_mgr = _build_manager(_snapshot("both"))allow_mgr.test_service(url)allow_mgr.service.test_service.assert_called_once_with(url)+++# Authority-bearing plugins must use the same address scope as HTTP webhooks.+# Token-bearing vendor URLs continue to use the vendor branch above.+def test_authority_plugin_obeys_public_and_private_scopes():+ local = "json://10.1.2.3/hook"+ public = "json://93.184.216.34/hook"++ public_mgr = _build_manager(_snapshot("public_only"))+ assert public_mgr._filter_urls_by_egress_policy(local) == ""+ assert public_mgr._filter_urls_by_egress_policy(public) == public++ private_mgr = _build_manager(_snapshot("private_only"))+ assert private_mgr._filter_urls_by_egress_policy(local) == local+ assert private_mgr._filter_urls_by_egress_policy(public) == ""+++def test_dynamic_matrix_and_mail_destinations_refused_when_local_only():+ manager = _build_manager(_snapshot("private_only"))+ for url in (+ "matrix://user:[email protected]/%23room?mode=off",+ "mailto://user:[email protected]/recipient",+ ):+ assert manager._filter_urls_by_egress_policy(url) == ""+++# Apprise reads ntfy topics from ``?to=`` as well as the path, and then+# sends to the URL host in private mode. That spelling must not take the+# vendor branch and skip the address scope.+def test_ntfy_to_query_topic_obeys_strict_scope_like_path_topic():+ with patch(_CLASSIFY, return_value=False):+ manager = _build_manager(_snapshot("strict"))+ for url in (+ "ntfy://public.example/topic",+ "ntfy://public.example?to=topic",+ "ntfys://public.example/?to=topic",+ ):+ assert manager._filter_urls_by_egress_policy(url) == ""+++# Apprise sends these ntfy URLs in cloud mode to the public ntfy.sh even+# though their authority looks local, so a local-only scope must refuse them.+def test_ntfy_cloud_mode_with_local_looking_host_refused_when_local_only():+ manager = _build_manager(_snapshot("private_only"))+ for url in (+ "ntfy://localhost?to=",+ "ntfy://ntfy?to=,",+ "ntfy://homelab_/alerts",+ ):+ assert manager._filter_urls_by_egress_policy(url) == ""+++def test_ntfy_fragment_topic_obeys_strict_scope():+ with patch(_CLASSIFY, return_value=False):+ manager = _build_manager(_snapshot("strict"))+ assert (+ manager._filter_urls_by_egress_policy(+ "ntfy://public.example/#/topic"+ )+ == ""+ )diff --git a/tests/security/test_encoded_numeric_host.py b/tests/security/test_encoded_numeric_host.pyindex 21fd55d1ec..f3d929fe60 100644--- a/tests/security/test_encoded_numeric_host.py+++ b/tests/security/test_encoded_numeric_host.py@@ -8,6 +8,9 @@ import requestsfrom local_deep_research.security.notification_validator import (NotificationURLValidator,)+from local_deep_research.security.notification_destination import (+ parse_notification_destination,+)from local_deep_research.security.ssrf_validator import validate_url@@ -69,6 +72,7 @@ def test_non_numeric_percent_encoded_hosts_preserve_current_outcomes():@pytest.mark.parametrize("scheme", ("http", "https"))def test_escaped_dns_name_resolves_the_hostname_requests_will_contact(scheme):url = f"{scheme}://ex%61mple.com/"+ assert parse_notification_destination(url).effective_host == "example.com"with patch.object(NotificationURLValidator,"_resolve_hostname_ips",@@ -83,6 +87,27 @@ def test_escaped_dns_name_resolves_the_hostname_requests_will_contact(scheme):resolver.assert_called_once_with("example.com")+def test_escaped_plugin_host_fails_closed_on_parser_disagreement():+ url = "json://ex%61mple.com/hook"+ with patch.object(+ NotificationURLValidator,+ "_resolve_hostname_ips",+ side_effect=AssertionError("ambiguous plugin host must not resolve"),+ ):+ assert NotificationURLValidator.validate_service_url_with_hint(url) == (+ False,+ "Notification destination host is ambiguous",+ False,+ )+++def test_double_encoded_host_is_not_decoded_twice():+ url = "https://127.0.0.1%252e/"+ assert (+ parse_notification_destination(url).effective_host == "127.0.0.1%252e"+ )++@pytest.mark.parametrize("url",(diff --git a/tests/security/test_notification_validator.py b/tests/security/test_notification_validator.pyindex 52b2faaa35..2e4479aca5 100644--- a/tests/security/test_notification_validator.py+++ b/tests/security/test_notification_validator.py@@ -444,12 +444,12 @@ class TestParserDifferentialBypass:"""signal:// (Apprise's Signal-API-REST transport) is allowed.Regression test for #4006: the validator previously rejected the- Signal scheme with "Unsupported protocol". Apprise handles its- own host validation for non-http schemes, so private-IP hosts- like signal-api-rest containers on the LAN must round-trip.+ Signal scheme with "Unsupported protocol". Private signal-api-rest+ hosts require the operator's private-IP opt-in."""is_valid, error = NotificationURLValidator.validate_service_url(- "signal://192.168.50.20:8739/+15551234567/+15557654321"+ "signal://192.168.50.20:8739/+15551234567/+15557654321",+ allow_private_ips=True,)assert is_valid is Trueassert error is None@@ -514,7 +514,11 @@ class TestCloudMetadataBlockedForPluginSchemes:@pytest.mark.parametrize("ip", METADATA_IPS)@pytest.mark.parametrize("scheme", PLUGIN_AUTHORITY_FIXTURES)def test_metadata_ip_blocked_by_default(self, scheme, ip):- url = f"{scheme}://{ip}/path"+ url = (+ f"matrix://user:pass@{ip}/%23room"+ if scheme == "matrix"+ else f"{scheme}://{ip}/path"+ )is_valid, error = NotificationURLValidator.validate_service_url(url)assert is_valid is Falseassert "cloud-metadata" in error.lower()@@ -523,7 +527,11 @@ class TestCloudMetadataBlockedForPluginSchemes:@pytest.mark.parametrize("scheme", PLUGIN_AUTHORITY_FIXTURES)def test_metadata_ip_blocked_even_with_allow_private_ips(self, scheme, ip):"""allow_private_ips=True unlocks LAN reach, NOT IMDS."""- url = f"{scheme}://{ip}/path"+ url = (+ f"matrix://user:pass@{ip}/%23room"+ if scheme == "matrix"+ else f"{scheme}://{ip}/path"+ )is_valid, error = NotificationURLValidator.validate_service_url(url, allow_private_ips=True)@@ -538,30 +546,23 @@ class TestCloudMetadataBlockedForPluginSchemes:assert is_valid is Falseassert "cloud-metadata" in error.lower()- def test_signal_lan_host_still_allowed(self):- """LAN signal-api-rest container (#4006 use case) keeps working."""- is_valid, error = NotificationURLValidator.validate_service_url(- "signal://192.168.50.20:8739/+15551234567/+15557654321"- )- assert is_valid is True- assert error is None-- def test_gotify_lan_host_still_allowed(self):- is_valid, error = NotificationURLValidator.validate_service_url(- "gotify://10.0.0.5:8080/AbCdEf123"- )- assert is_valid is True- assert error is None-- def test_signal_loopback_still_allowed(self):- """Plugin schemes pointing at localhost (same-host self-hosted- container) round-trip without the operator opt-in — only the- absolute IMDS block fires for plugin schemes."""- is_valid, error = NotificationURLValidator.validate_service_url(- "signal://127.0.0.1:8739/+15551234567/+15557654321"+ @pytest.mark.parametrize(+ "url",+ [+ "signal://192.168.50.20:8739/+15551234567/+15557654321",+ "gotify://10.0.0.5:8080/AbCdEf123",+ "signal://127.0.0.1:8739/+15551234567/+15557654321",+ "json://127.0.0.1:8000/internal",+ ],+ )+ def test_private_plugin_requires_operator_opt_in(self, url):+ denied, reason = NotificationURLValidator.validate_service_url(url)+ allowed, _ = NotificationURLValidator.validate_service_url(+ url, allow_private_ips=True)- assert is_valid is True- assert error is None+ assert denied is False+ assert "private/internal" in reason.lower()+ assert allowed is Truedef test_allowlisted_token_shaped_urls_pass_validator(self):"""Non-IP authority values pass the validator's IMDS check.@@ -814,7 +815,10 @@ class TestLinkLocalBlockedForPluginSchemes:def test_ipv6_link_local_blocked(self):is_valid, error = NotificationURLValidator.validate_service_url(- "json://[fe80::1]/path", allow_private_ips=True+ # Uncompressed: Apprise rewrites a compressed literal, which+ # the classifier refuses before the link-local check.+ "json://[fe80:0:0:0:0:0:0:1]/path",+ allow_private_ips=True,)assert is_valid is Falseassert "link-local" in error.lower()@@ -831,21 +835,27 @@ class TestLinkLocalBlockedForPluginSchemes:assert is_valid is True, f"{url} should be allowed, got: {error}"def test_loopback_and_ula_still_allowed(self):- for url in ("json://127.0.0.1/hook", "json://[fd00::1]/hook"):+ # Uncompressed IPv6: Apprise rewrites ``[fd00::1]`` to ``[fd00::]``,+ # so the compressed form is refused as ambiguous.+ for url in (+ "json://127.0.0.1/hook",+ "json://[fd00:0:0:0:0:0:0:1]/hook",+ ):is_valid, error = NotificationURLValidator.validate_service_url(url, allow_private_ips=True)assert is_valid is True, f"{url} should be allowed, got: {error}"- def test_http_scheme_link_local_still_operator_recoverable(self):- """The link-local block is scoped to the PLUGIN partition. Under- http/https the operator opt-in still permits link-local (it is- unreachable for delivery today and the hint contract treats it as- recoverable) — so the scoped fix must NOT change that."""- is_valid, _error = NotificationURLValidator.validate_service_url(+ def test_http_scheme_link_local_blocked_even_with_opt_in(self):+ """The link-local block covers http/https too. Apprise converts+ some http(s) URLs into plugins that post to the URL host (Apprise+ API, Workflows), so an http link-local host is as reachable as a+ plugin one and the opt-in must not reopen it."""+ is_valid, error = NotificationURLValidator.validate_service_url("http://169.254.1.1/x", allow_private_ips=True)- assert is_valid is True+ assert is_valid is False+ assert "link-local" in error.lower()class TestEmptyAuthorityRejected:diff --git a/tests/security/test_security_documentation_contracts.py b/tests/security/test_security_documentation_contracts.pyindex 0ba882806a..9b9396f6c0 100644--- a/tests/security/test_security_documentation_contracts.py+++ b/tests/security/test_security_documentation_contracts.py@@ -9,9 +9,6 @@ notification service tests.from pathlib import Path-import pytest--REPO_ROOT = Path(__file__).resolve().parents[2]SECURITY_DOC = REPO_ROOT / "SECURITY.md"NOTIFICATIONS_DOC = REPO_ROOT / "docs" / "NOTIFICATIONS.md"@@ -25,18 +22,6 @@ NOTIFICATION_ENV_DEFINITION = ()- strict=True,- reason=(- "DOCUMENTATION DEFECT: SECURITY.md says the notification send-time "- "DNS-rebinding window is now closed in code, while NOTIFICATIONS.md "- "and the generated environment-setting description say that it "- "cannot be closed in code. SECURITY.md itself later says host-bearing "- "Apprise plugin modes retain the window. Replace both blanket claims "- "with one per-scheme account: pinned/direct HTTP paths versus plugin "- "modes whose client performs its own resolution. Tracked in #6047."- ),-)def test_notification_dns_rebinding_claims_are_scoped_consistently():security = SECURITY_DOC.read_text(encoding="utf-8")notifications = NOTIFICATIONS_DOC.read_text(encoding="utf-8")@@ -51,7 +36,11 @@ def test_notification_dns_rebinding_claims_are_scoped_consistently():):assert "cannot be closed in code" not in text, path- # Keep both sides of the real, scoped contract visible after the blanket- # statements are removed.+ # Both pinned hosts and unpinned plugin lookups are guarded during the+ # synchronous send; proxy-side resolution remains an operator boundary.assert "pinned_notification_send" in security- assert "retain the DNS resolution window" in security+ assert "remain subject to the send-time DNS guard" in security+ assert "retain the DNS resolution window" not in security+ assert "retain the DNS-rebinding risk" not in notifications+ assert "forward proxy" in security+ assert "forward proxy" in notificationsdiff --git a/tests/web/services/test_notification_coverage.py b/tests/web/services/test_notification_coverage.pyindex d05f273407..f5c14f7aaf 100644--- a/tests/web/services/test_notification_coverage.py+++ b/tests/web/services/test_notification_coverage.py@@ -305,12 +305,10 @@ class TestPluginSchemeDNSContract:"signal://signal-api.example.com:8739/+15551234567/+15557654321","signal-api.example.com",),- ("ntfy://topic", "topic"),("ntfy://ntfy.example.com/topic?mode=private","ntfy.example.com",),- ("matrix://" + MATRIX_TOKEN, MATRIX_TOKEN),("matrix://user:[email protected]/%23room?mode=matrix","matrix.example.com",@@ -522,6 +520,22 @@ class TestPluginSchemeDNSContract:assert post.call_args.args[0] == destinationassert post.call_args.kwargs["allow_redirects"] is False+ @pytest.mark.parametrize(+ "url", ["ntfy://topic", "matrix://" + MATRIX_TOKEN]+ )+ def test_vendor_modes_do_not_resolve_token_authority(self, url):+ with patch.object(+ NotificationURLValidator, "_resolve_hostname_ips"+ ) as resolver:+ assert NotificationURLValidator.validate_service_url_with_hint(+ url+ ) == (+ True,+ None,+ False,+ )+ resolver.assert_not_called()+@pytest.mark.parametrize(("fixture", "hostname"), DNS_FIXTURES)@pytest.mark.parametrize(("resolved_ip", "expect_valid"),@@ -874,6 +888,12 @@ class TestNotificationService:False,id="nat64-rfc6052-wrap-of-alibaba-metadata",),+ # Link-local stays blocked for every notification URL, even+ # with the private-IP opt-in, so the hint must not offer it.+ pytest.param("http://[fe80::1]/", False, id="link-local-fe80"),+ pytest.param(+ "http://169.254.42.42/", False, id="link-local-scaleway"+ ),# Plugin-scheme metadata (different validator prefix)pytest.param("signal://169.254.169.254:8080/path",@@ -894,7 +914,6 @@ class TestNotificationService:pytest.param("http://100.64.0.1/", True, id="cgnat-100-64"),pytest.param("http://[::1]/", True, id="ipv6-loopback"),pytest.param("http://[fc00::1]/", True, id="ula-fc00"),- pytest.param("http://[fe80::1]/", True, id="link-local-fe80"),pytest.param("http://localhost/", True, id="localhost-dns"),# NAT64-wrapped NON-metadata IPv4 — recoverable ONLY via# LDR_SECURITY_ALLOW_NAT64=true (the private-IPs flag cannot@@ -991,7 +1010,6 @@ class TestNotificationService:("http://100.64.0.1/", True),("http://[::1]/", True),("http://[fc00::1]/", True),- ("http://[fe80::1]/", True),("http://localhost/", True),# NAT64-wrapped NON-metadata IPv4 — hint is True ONLY via# the NAT64 carve-out probe, not the private-IPs probe.@@ -1008,6 +1026,9 @@ class TestNotificationService:("http://[100::]/", False),("http://[::169.254.169.254]/", False),("http://[::ffff:169.254.169.254]/", False),+ # Link-local: the opt-in never reopens it.+ ("http://[fe80::1]/", False),+ ("http://169.254.42.42/", False),# Plugin-scheme metadata — never reaches the hint branch via# test_service (prefix guard short-circuits earlier) but pin# the decision directly in case a future caller uses it.