Skip to content

~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.

harden(notifications): pin resolved IPs and block private resolution for the Apprise send (#5575)

LearningCircuit34756532ae4d
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 08e67fcc9d..15bcbf2043 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -447,6 +447,18 @@ repos:
description: "Block test modules that import nothing from local_deep_research
(shadow tests). Opt out a legitimate no-import test with
'# allow: no-sut-import — <reason>'. See CONTRIBUTING.md."
+ - id: check-no-src-test-imports
+ name: Forbid src.local_deep_research imports in tests
+ entry: .pre-commit-hooks/check-no-src-test-imports.py
+ language: script
+ files: ^tests/.*\.py$
+ # tests/hooks carry the alias as literal test data for the hook checks.
+ exclude: ^tests/hooks/
+ description: "Ban 'src.local_deep_research' imports and patch-target strings
+ in tests. The 'src.' alias is a DISTINCT module object from the canonical
+ 'local_deep_research'; importing a module under both loads two copies and
+ breaks process-global singletons (the security.dns_pinning getaddrinfo
+ shim the notification send fails closed on). Use 'local_deep_research'."
- id: check-weak-tests
name: Check for tautological / no-op tests
entry: .pre-commit-hooks/check-weak-tests.py
diff --git a/.pre-commit-hooks/check-no-src-test-imports.py b/.pre-commit-hooks/check-no-src-test-imports.py
new file mode 100755
index 0000000000..249dbf1d20
--- /dev/null
+++ b/.pre-commit-hooks/check-no-src-test-imports.py
@@ -0,0 +1,159 @@
+#!/usr/bin/env python3
+"""Pre-commit hook: forbid ``src.local_deep_research`` references in tests.
+
+The package is importable under two distinct names: the canonical
+``local_deep_research`` (what the running app and every production module use)
+and ``src.local_deep_research`` (resolvable only because the repo root is on
+``sys.path`` during test collection). Python treats these as SEPARATE module
+objects with separate globals — so importing the SAME module under both names
+loads TWO copies of it.
+
+For most modules that is merely wasteful, but for process-global singletons it
+is a latent bug. ``security/dns_pinning`` installs a process-wide
+``socket.getaddrinfo`` shim and the notification send path fails CLOSED unless
+that shim is *this* module's object (strict identity). A single ``src.``
+import anywhere in the suite loads a second ``dns_pinning``, whose shim
+displaces the canonical one, so the notification-send guard reports "shim
+missing" and refuses to send — a failure that surfaces only in the full/xdist
+run where a ``src.`` importer lands in the same worker before the send tests.
+
+The fix was to normalize every test import to the canonical package; this hook
+keeps it that way. It flags, in ``tests/**/*.py``:
+
+* ``import src.local_deep_research...`` / ``from src.local_deep_research... import ...``
+* string literals that START with ``src.local_deep_research`` — i.e. mock
+ ``patch(...)`` / ``patch.object(...)`` targets and ``module_path`` values,
+ which import the ``src.`` module tree when the patch is entered exactly as a
+ real import would.
+
+Backtick-wrapped prose in comments/docstrings that merely NAMES the banned
+alias is not flagged (AST ignores comments; a docstring value does not *start*
+with the alias). ``tests/hooks/`` is exempt: those tests carry the alias as
+literal test data for the hook checks themselves.
+"""
+
+import ast
+import sys
+from pathlib import Path
+
+BANNED_PREFIX = "src.local_deep_research"
+
+# Directories (as path components) whose test files legitimately carry the
+# banned alias as test data for the pre-commit hooks themselves.
+EXEMPT_DIR_COMPONENTS = ("hooks",)
+
+
+def _is_test_file(p: Path) -> bool:
+ parts = p.parts
+ if "tests" not in parts:
+ return False
+ # Everything under tests/hooks is exempt (hook test data).
+ tests_idx = parts.index("tests")
+ tail = parts[tests_idx + 1 :]
+ return not any(c in tail for c in EXEMPT_DIR_COMPONENTS)
+
+
+def _banned(name) -> bool:
+ return isinstance(name, str) and (
+ name == BANNED_PREFIX or name.startswith(BANNED_PREFIX + ".")
+ )
+
+
+class _Checker(ast.NodeVisitor):
+ def __init__(self):
+ self.errors = []
+
+ def visit_Import(self, node):
+ for alias in node.names:
+ # import src.local_deep_research[...] OR import src (aliased)
+ if _banned(alias.name) or alias.name == "src":
+ self.errors.append(
+ (node.lineno, f"import of banned alias '{alias.name}'")
+ )
+ self.generic_visit(node)
+
+ def visit_ImportFrom(self, node):
+ module = node.module or ""
+ # from src.local_deep_research[...] import ...
+ if _banned(module):
+ self.errors.append(
+ (node.lineno, f"import from banned alias '{module}'")
+ )
+ # from src import local_deep_research
+ elif module == "src" and any(
+ a.name == "local_deep_research" for a in node.names
+ ):
+ self.errors.append(
+ (node.lineno, "import of 'local_deep_research' from 'src'")
+ )
+ self.generic_visit(node)
+
+ def visit_Constant(self, node):
+ # patch(...) targets / module_path values that START with the alias.
+ if isinstance(node.value, str) and _banned(node.value):
+ self.errors.append(
+ (
+ node.lineno,
+ f"string references banned alias '{node.value}'",
+ )
+ )
+ self.generic_visit(node)
+
+
+def check_file(filename: str) -> bool:
+ p = Path(filename)
+ if not _is_test_file(p):
+ return True
+ try:
+ content = p.read_text(encoding="utf-8")
+ except Exception as e: # pragma: no cover - unreadable file
+ print(f"Error reading {filename}: {e}")
+ return False
+ try:
+ tree = ast.parse(content, filename=filename)
+ except SyntaxError:
+ # Let ruff / the compiler report syntax errors.
+ return True
+ checker = _Checker()
+ checker.visit(tree)
+ if checker.errors:
+ print(f"\n{filename}:")
+ for lineno, msg in checker.errors:
+ print(f" Line {lineno}: {msg}")
+ return False
+ return True
+
+
+def main() -> int:
+ if len(sys.argv) < 2:
+ print("Usage: check-no-src-test-imports.py <file1> <file2> ...")
+ return 1
+ has_errors = False
+ for filename in sys.argv[1:]:
+ if filename.endswith(".py") and not check_file(filename):
+ has_errors = True
+ if has_errors:
+ print("\n" + "=" * 70)
+ print("Banned 'src.local_deep_research' reference in tests!")
+ print("=" * 70)
+ print(
+ "\nImport the package under its canonical name 'local_deep_research'"
+ " instead\nof 'src.local_deep_research'. The two names are DISTINCT"
+ " module objects;\nimporting a module under both loads two copies,"
+ " which breaks process-\nglobal singletons (e.g. the"
+ " security.dns_pinning getaddrinfo shim that\nthe notification send"
+ " path fails closed on).\n"
+ )
+ print("Examples:")
+ print(" BAD: from src.local_deep_research.chat.service import X")
+ print(" GOOD: from local_deep_research.chat.service import X")
+ print(
+ ' BAD: patch("src.local_deep_research.config.llm_config.get_llm")'
+ )
+ print(' GOOD: patch("local_deep_research.config.llm_config.get_llm")')
+ return 1
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/SECURITY.md b/SECURITY.md
index 0589b98695..99cacb19be 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -107,14 +107,21 @@ 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 is intentional: notifications carry a known residual SSRF risk that cannot be fully closed in code, and the env-only gate makes turning them 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. 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.
-#### The residual risk
+#### The rebinding window and how it is closed
-LDR 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. There is a known **DNS rebinding TOCTOU window** between this check and the actual outbound request:
+LDR 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`).
-- **The window.** Apprise (and its underlying `requests`/`urllib3` stack) resolves the hostname *again* when it sends the notification. A DNS-rebinding attacker controlling a domain can serve a public IP to LDR's validator and a private IP to Apprise's send-time resolver — bypassing the private-IP check and reaching internal services on the LDR server (e.g., `127.0.0.1:<internal-port>`) or the local network. This is exploitable by any logged-in user, not just by the deployment operator.
-- **Why it isn't closed in code.** Apprise exposes no Session/adapter/DNS hook. Closing the window would require monkey-patching `requests` inside Apprise's plugin namespace — fragile across Apprise versions, HTTPS-only, and doesn't handle redirects correctly. The blast radius outweighs the benefit.
+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.
+
+- **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).
+- **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.
+- **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.
+- **Thread-scoped.** The pin and the block are thread-local, so they only affect the sending thread and can never wrongly block a legitimate private request running concurrently elsewhere.
#### How to enable notifications
@@ -127,7 +134,7 @@ By setting this, the operator acknowledges the residual risk above. To minimise
- **Prefer plugin schemes over raw `http(s)://`.** Apprise plugin schemes (`discord://`, `slack://`, `ntfy://`, `ntfys://`, `gotify://`, `telegram://`, `mattermost://`, `rocketchat://`, `teams://`, `matrix://`, `mailto://`, etc.) hardcode their endpoints internally and have no user-controllable hostname — no SSRF surface. Use them whenever the target service supports them.
- **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.
-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. This does not apply to callers that hand a URL to an external client that re-resolves on its own (Apprise above; 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).
+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).
### JS-Rendering Browser Redirect SSRF
@@ -152,6 +159,10 @@ A reporter ([@Fushuling](https://github.com/Fushuling), [@RacerZ-fighting](https
Both `ssrf_validator.validate_url` and `NotificationURLValidator.validate_service_url` (HTTP/HTTPS branch) carry the fix. Future edits to the SSRF path should preserve `RFC_FORBIDDEN_URL_CHARS_RE` and the `urllib3.util.parse_url` host extraction — reverting either reintroduces the bypass.
+**Multiple-`@` authority (notification path).** A related parser differential affects Apprise specifically: for an authority with more than one `@` (e.g. `json://[email protected]@decoy-public.example.com/path`), `urllib3.util.parse_url` — which the notification validator and the DNS pin use — reads the host after the *last* `@` (`decoy-public.example.com`, which validates and gets pinned), while Apprise's own `parse_url` reads `169.254.169.254` and connects there. Because Apprise re-parses and connects independently of the address the guard validated/pinned, `NotificationURLValidator` rejects any notification service URL whose authority (the `urlparse` netloc, so path/query `@`s do not count) contains more than one `@` — fail-closed, before the host is ever extracted. A single `@` (RFC 3986 userinfo, e.g. `mailto://user:pass@host`) is still accepted. This is on the notification path only; the general `safe_requests` path has no such differential because its validator and its HTTP client both use `urllib3`.
+
+**Empty `//`-authority (notification path).** Another Apprise-specific parser differential: for a URL whose `scheme://` authority is empty but with content in the path (e.g. `json:///169.254.169.254/path`), `urllib3`/`requests` see *no host* — so the validator's per-scheme IP check would be skipped and the URL accepted — while Apprise falls back to treating the first path segment as the host and dials it (`169.254.169.254`). `NotificationURLValidator` rejects any notification service URL that carries the `//` authority marker but parses to an empty authority, before host extraction — fail-closed. This fires only when the `//` marker is present, so a scheme that legitimately has no `//` authority is untouched. It is defense-in-depth: the send-time block-private window backstops it (the in-path metadata host still resolves to a blocked address during the send), but rejecting it at validation stops the URL from ever being stored/attempted.
+
### Cloud Metadata Endpoint Block List
`ssrf_validator.ALWAYS_BLOCKED_METADATA_IPS` is a frozenset of cloud-provider metadata IPs that are blocked under every flag combination, including `allow_localhost=True` and `allow_private_ips=True`. These IPs expose IAM / instance-role credentials and are never legitimate destinations for outbound HTTP. The current set is:
@@ -163,10 +174,13 @@ Both `ssrf_validator.validate_url` and `NotificationURLValidator.validate_servic
| `169.254.170.23` | AWS ECS task metadata v4 |
| `169.254.0.23` | Tencent Cloud |
| `100.100.100.200` | AlibabaCloud |
+| `fd00:ec2::254` | AWS IMDS over IPv6 |
+
+`fd00:ec2::254` is AWS's native IPv6 instance-metadata endpoint. It is a ULA (`fc00::/7`), **not** an IPv4-mapped or NAT64-wrapped form of `169.254.169.254`, so it is not covered by the IPv4 entries or the NAT64 embedded-IPv4 check above and must be listed explicitly — otherwise it stays reachable under `allow_private_ips=True`, which permits the whole `fc00::/7` range. Entries are matched by canonical string form (`is_ip_blocked` parses the candidate with `ipaddress.ip_address` first), so uppercase / zero-padded / expanded variants all normalise to the listed form before the membership test.
-The block also catches IPv6-wrapped forms of these 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.
+The 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.
+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).
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/+pin-notification-send-dns.security.md b/changelog.d/+pin-notification-send-dns.security.md
new file mode 100644
index 0000000000..11e84f3890
--- /dev/null
+++ b/changelog.d/+pin-notification-send-dns.security.md
@@ -0,0 +1,40 @@
+Hardened the outbound notification (Apprise) path against send-time DNS
+rebinding. Notification service URLs were validated once at configuration
+time, but Apprise re-resolves the hostname (and follows redirects) when it
+actually sends, so a rebinding host could serve a public address to the
+validator and a private/cloud-metadata address to the sender. The delivery
+path now runs synchronously in-thread with HTTP redirect-following disabled
+(closing redirect-to-internal and redirect-to-exfil outright, even against a
+user-supplied `?redirect=yes`) and, for the duration of each send, pins every
+raw-webhook host to the address just validated and refuses any unpinned lookup
+that resolves to a private/loopback/link-local/cloud-metadata IP — blocking it
+at the socket layer before a connection is made. Send-time DNS resolution is
+bounded by a timeout (a slow/hostile resolver cannot hang the sending thread),
+and the send fails closed if the pinning shim is not the active resolver or if
+delivery would fan out to worker threads the thread-local guards do not cover.
+Per-scheme policy matches the validator (http/https block private unless opted
+in; plugin/self-hosted schemes allow LAN targets but always block
+cloud-metadata), the original hostname is kept for TLS SNI and certificate
+verification, and the pin/block are thread-local so concurrent requests are
+unaffected. The `LDR_NOTIFICATIONS_ALLOW_OUTBOUND` gate remains as defense in
+depth.
+
+A follow-up review round closed further gaps: AWS's native IPv6 instance-metadata
+endpoint (`fd00:ec2::254`, a ULA that the IPv4 metadata list and the NAT64
+embedded-IPv4 check did not cover) is now always blocked, including under the
+private-IP opt-in; notification service URLs whose authority contains more than
+one `@` are rejected before the host is extracted (the validator/pin parser and
+Apprise's own parser pick different hosts for such authorities); a confirmed
+send-time SSRF block is now recognised and fails fast in a single attempt
+instead of being retried; and the bounded send-time DNS lookup runs on a daemon
+thread so a hung hostile resolver can never block graceful process shutdown.
+
+A further round closed a residual and tightened defense in depth: the
+notification plugin/raw-webhook partition now blocks the entire link-local range
+(IPv4 `169.254.0.0/16`, IPv6 `fe80::/10`) even under the private-IP opt-in —
+cloud-provider metadata is served across link-local beyond the always-blocked
+literals (e.g. Scaleway's `169.254.42.42`), while self-hosted RFC1918 / loopback /
+non-link-local ULA notifiers keep working; and notification URLs with an empty
+`//` authority but an in-path host (e.g. `json:///169.254.169.254/path`, where
+the validator's parser sees no host but Apprise dials the path segment) are
+rejected before host extraction.
diff --git a/src/local_deep_research/notifications/service.py b/src/local_deep_research/notifications/service.py
index 9113d1f2bc..99140c8ed2 100644
--- a/src/local_deep_research/notifications/service.py
+++ b/src/local_deep_research/notifications/service.py
@@ -2,8 +2,10 @@
Core notification service using Apprise.
"""
+import contextlib
+import functools
import re
-from typing import Dict, List, Optional, Any
+from typing import Dict, List, Optional, Any, Tuple
from urllib.parse import urlparse
import apprise
@@ -12,11 +14,12 @@ from tenacity import (
retry,
stop_after_attempt,
wait_exponential,
- retry_if_exception_type,
+ retry_if_not_exception_type,
)
from .exceptions import ServiceError, SendError
from .templates import EventType, NotificationTemplate
+from ..security import dns_pinning
from ..security.url_builder import mask_sensitive_url
from ..security.notification_validator import (
NotificationURLValidator,
@@ -65,14 +68,236 @@ class NotificationService:
the operator opts in. See SECURITY.md "Notification
Webhook SSRF" for the rationale.
"""
- self.apprise = apprise.Apprise()
+ self.apprise = self._new_apprise()
self.allow_private_ips = allow_private_ips
self.outbound_allowed = outbound_allowed
+ @staticmethod
+ def _new_apprise() -> apprise.Apprise:
+ """Create an Apprise instance that delivers synchronously and does
+ not follow HTTP redirects.
+
+ ``async_mode=False`` forces Apprise to run every plugin's
+ ``notify()`` in the calling thread instead of fanning out to a
+ ``ThreadPoolExecutor``. This is required for the SSRF hardening in
+ :meth:`_send_with_retry`: the DNS pin and the block-private window
+ (``security.dns_pinning``) are thread-local, so they only apply to
+ the resolution the sending thread performs. With the default async
+ fan-out the plugins would resolve in worker threads that carry no
+ pin/block and the guard would silently not apply (verified: the
+ default asset resolves target hosts on worker threads).
+
+ ``http_redirects=False`` disables 30x redirect-following for the
+ raw-webhook plugins (``json``/``xml``/``form``, which pass
+ ``allow_redirects=self.redirects`` to ``requests``). This closes the
+ redirect attack class outright: a user-configured webhook can no
+ longer 30x-redirect the send to a private/loopback host or to an
+ arbitrary public host for data exfiltration. The pin +
+ block-private window is then only responsible for the original
+ validated host's own rebind, not for chasing redirect hops. It is a
+ DEFAULT: a per-URL ``?redirect=yes`` can still override it, so
+ :meth:`_disable_redirects` re-forces it off per-plugin after
+ ``add()`` (see there).
+ """
+ return apprise.Apprise(
+ asset=apprise.AppriseAsset(async_mode=False, http_redirects=False)
+ )
+
+ @staticmethod
+ def _disable_redirects(apprise_instance: apprise.Apprise) -> None:
+ """Force redirect-following OFF on every added plugin.
+
+ ``_new_apprise`` sets the asset-level ``http_redirects=False``
+ default, but Apprise lets a per-URL ``?redirect=yes`` query
+ parameter override that default (``self.redirects =
+ parse_bool(kwargs.get("redirect", asset.http_redirects))``). A
+ low-privilege user could therefore re-enable redirect-following on
+ their own webhook and reopen redirect-to-private / redirect-to-exfil.
+ Setting ``redirects = False`` directly on each plugin AFTER it is
+ parsed makes the closure airtight: the value is read at send time
+ (``allow_redirects=self.redirects``), so this wins over any URL
+ parameter. Redirect-following is never needed for legitimate
+ webhook/plugin delivery (real endpoints answer 2xx directly), so
+ this cannot break a genuine send.
+
+ Not every plugin threads ``self.redirects`` into its HTTP call: the
+ raw-webhook ``json``/``xml``/``form`` schemes and e.g. ``ntfy`` /
+ ``gotify`` honour it, but a few (e.g. ``matrix://``) issue requests
+ without it, so re-forcing the flag has no effect there. Those are
+ backstopped by the block-private send window
+ (``dns_pinning.pinned_notification_send``), which refuses a
+ redirect/rebind to a blocked address at the ``getaddrinfo`` layer
+ regardless of whether the plugin followed the redirect.
+ """
+ try:
+ servers = list(apprise_instance)
+ except TypeError as exc:
+ # A mocked Apprise in unit tests is not iterable, so there is
+ # nothing to harden (those tests never exercise a real redirect).
+ # But if a REAL Apprise ever stops being iterable (upstream API
+ # drift), silently returning here would leave the per-plugin
+ # redirect-disable un-applied — fail-open. The asset-level
+ # ``http_redirects=False`` default and the block-private window
+ # still apply, but a per-URL ``?redirect=yes`` could re-enable
+ # redirect-following. Log a warning (narrowed to TypeError) so
+ # that drift is visible instead of silent.
+ logger.warning(
+ "Could not enumerate Apprise servers to force "
+ "redirect-following off per plugin ({}); relying on the "
+ "asset-level default and the block-private window",
+ type(exc).__name__,
+ )
+ return
+ for server in servers:
+ server.redirects = False
+
+ def _enforce_guarded_send_invariants(
+ self, apprise_instance: apprise.Apprise, tag: Optional[str]
+ ) -> None:
+ """Enforce the fail-closed invariants for a DNS-guarded send.
+
+ The pin + block-private window (``security.dns_pinning``) are
+ thread-local and only cover IN-THREAD delivery. Refuse the send
+ (fail closed) rather than silently sending unguarded unless:
+
+ * ``async_mode`` is off — otherwise Apprise fans the plugins out to
+ worker threads that carry neither the pin nor the block; and
+ * ``tag`` is None — a multi-token tag likewise makes Apprise
+ dispatch matching plugins across worker threads. No production
+ caller passes a tag; this neutralizes a future one.
+
+ Then force redirect-following off per plugin so a per-URL
+ ``?redirect=yes`` cannot override the asset-level default.
+
+ Raises:
+ RuntimeError: if either invariant is violated (excluded from
+ Tenacity retries so it fails fast).
+ """
+ if getattr(apprise_instance.asset, "async_mode", True) is True:
+ raise RuntimeError(
+ "Guarded notification send requires async_mode=False; "
+ "refusing to send (the thread-local DNS pin/block would not "
+ "apply to Apprise's worker-thread fan-out)."
+ )
+ if tag is not None:
+ raise RuntimeError(
+ "Guarded notification send does not support tag targeting; "
+ "refusing to send (a tag can fan delivery out to worker "
+ "threads that bypass the thread-local DNS pin/block)."
+ )
+ self._disable_redirects(apprise_instance)
+
+ @staticmethod
+ def _partition_urls(service_urls: str) -> Tuple[List[str], List[str]]:
+ """Split an Apprise URL string into (http(s), everything-else).
+
+ Splits on commas and whitespace — the separators Apprise's own
+ ``add()`` accepts — so the partition matches what Apprise will
+ actually dispatch. 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.
+
+ NOTE: the ``strict`` (``http``/``https``) partition is UNREACHABLE
+ for delivery today — Apprise rejects bare ``http(s)://`` notification
+ URLs at ``add()`` (verified: ``apprise.Apprise().add("http://x/")``
+ is False), so a strict-partition ``add()`` in :meth:`_dispatch`
+ returns False and nothing is sent. The stricter policy is retained
+ as defense-in-depth for a hypothetical future where a raw ``http(s)``
+ scheme becomes deliverable; deliverable webhooks use the raw-webhook
+ schemes ``json``/``xml``/``form`` (in the ``lenient`` partition).
+ """
+ strict: List[str] = []
+ lenient: List[str] = []
+ for entry in service_urls.replace(",", " ").split():
+ entry = entry.strip()
+ if not entry:
+ continue
+ scheme = entry.split(":", 1)[0].lower() if ":" in entry else ""
+ if scheme in ("http", "https"):
+ strict.append(entry)
+ else:
+ lenient.append(entry)
+ return strict, lenient
+
+ def _guarded_notify(
+ self,
+ title: str,
+ body: str,
+ apprise_instance: apprise.Apprise,
+ guard_factory=None,
+ tag: Optional[str] = None,
+ attach: Optional[List[str]] = None,
+ ) -> bool:
+ """Run a single Apprise ``notify()`` under the DNS-guard and the
+ fail-closed invariants. Returns Apprise's raw boolean result.
+
+ Single source of truth for the guarded send: both the retrying
+ delivery path (:meth:`_send_with_retry`) and the admin
+ "Send Test Notification" path (:meth:`test_service`) call this, so
+ neither re-implements the invariant-enforcement / redirect-disable /
+ guarded-``notify`` sequence that the SSRF hardening depends on.
+
+ When ``guard_factory`` is provided, the fail-closed invariants are
+ enforced (``async_mode`` off, no ``tag``, redirects forced off) and
+ the send runs inside the pin + block-private window it returns. The
+ per-thread SSRF-block marker is reset first so a block during THIS
+ ``notify`` is attributable to it (see
+ ``dns_pinning.consume_ssrf_block``). ``None`` sends without a guard.
+
+ Args:
+ title: Notification title
+ body: Notification body text
+ apprise_instance: Apprise instance to use for sending
+ guard_factory: Optional zero-arg callable returning a context
+ manager wrapped around the ``notify()`` call (the DNS pin +
+ block-private window; see ``security.dns_pinning``).
+ tag: Optional tag to target specific services
+ attach: Optional list of file paths to attach
+
+ Returns:
+ True iff Apprise reported the notification delivered.
+ """
+ if guard_factory is not None:
+ # Guarded (user-supplied URL) send: enforce the fail-closed
+ # invariants the thread-local pin/block depend on and disable
+ # redirects before dispatching, then clear any stale SSRF-block
+ # marker so consume_ssrf_block reflects only this attempt.
+ self._enforce_guarded_send_invariants(apprise_instance, tag)
+ dns_pinning.reset_ssrf_block()
+
+ guard = (
+ guard_factory()
+ if guard_factory is not None
+ else contextlib.nullcontext()
+ )
+
+ # Send notification inside the guard so the pin + block-private
+ # window (if any) governs Apprise's send-time DNS resolution.
+ # ``notify`` is typed ``bool | None``; coerce to a definite bool
+ # (None == nothing delivered == False).
+ with guard:
+ return bool(
+ apprise_instance.notify(
+ title=title,
+ body=body,
+ tag=tag,
+ attach=attach,
+ )
+ )
+
@retry(
stop=stop_after_attempt(3),
wait=wait_exponential(multiplier=1, min=0.5, max=10),
- retry=retry_if_exception_type((Exception,)),
+ # Retry transient delivery failures (SendError, connection errors,
+ # …) but NOT deliberate security refusals: a ValueError is a
+ # connect-time SSRF block (the pin's rebind-to-private/metadata catch,
+ # or the block-private window's send-time refusal surfaced below) and
+ # a RuntimeError is a fail-closed invariant violation (shim not
+ # installed, async_mode/tag guard). A confirmed-malicious or
+ # misconfigured destination must fail fast, not be retried 3x.
+ retry=retry_if_not_exception_type((ValueError, RuntimeError)),
reraise=True,
)
def _send_with_retry(
@@ -80,6 +305,7 @@ class NotificationService:
title: str,
body: str,
apprise_instance: apprise.Apprise,
+ guard_factory=None,
tag: Optional[str] = None,
attach: Optional[List[str]] = None,
) -> bool:
@@ -87,11 +313,15 @@ class NotificationService:
Send a notification using the provided Apprise instance with retry logic.
This method is decorated with Tenacity to handle retries automatically.
+ A fresh guard context is created per attempt (via ``guard_factory``)
+ so retries re-resolve and re-pin.
Args:
title: Notification title
body: Notification body text
apprise_instance: Apprise instance to use for sending
+ guard_factory: Optional zero-arg callable returning the per-send
+ DNS guard context (see :meth:`_guarded_notify`).
tag: Optional tag to target specific services
attach: Optional list of file paths to attach
@@ -99,24 +329,45 @@ class NotificationService:
True if notification was sent successfully
Raises:
- SendError: If sending fails after all retry attempts
+ SendError: If sending fails after all retry attempts (transient).
+ ValueError: If a guarded send failed because the block-private
+ window refused a send-time resolution as an SSRF target —
+ a confirmed security block, raised non-retryably so it fails
+ fast instead of being retried.
"""
logger.debug(
f"Sending notification: title='{title[:50]}...', tag={tag}"
)
logger.debug(f"Body preview: {body[:200]}...")
- # Send notification
- notify_result = apprise_instance.notify(
- title=title,
- body=body,
- tag=tag,
- attach=attach,
+ notify_result = self._guarded_notify(
+ title, body, apprise_instance, guard_factory, tag, attach
)
if notify_result:
logger.debug(f"Notification sent successfully: '{title[:50]}...'")
return True
+
+ # A guarded send that failed AND tripped the block-private window is a
+ # confirmed SSRF block: the window raised socket.gaierror on a
+ # send-time resolution to an internal/private/metadata IP, which
+ # Apprise swallowed into a generic delivery failure. Fail fast — raise
+ # a non-retryable ValueError (excluded from the retry predicate above)
+ # instead of a retryable SendError, so a confirmed-malicious /
+ # misconfigured destination is not retried 3x (~10s and 3x DNS to a
+ # hostile authority). The pin path's own rebind catch already raises
+ # ValueError before this point; this covers the UNPINNED block-window
+ # path (plugin-scheme endpoints, unresolvable-at-pin-time hosts).
+ if guard_factory is not None and dns_pinning.consume_ssrf_block():
+ logger.warning(
+ "Notification send blocked by the SSRF block-private window; "
+ "failing fast (not retrying)"
+ )
+ raise ValueError(
+ "Notification send refused: a send-time DNS resolution was "
+ "blocked as internal/private/metadata (possible SSRF)"
+ )
+
error_msg = "Failed to send notification to any service"
logger.warning(error_msg)
raise SendError(error_msg)
@@ -184,29 +435,38 @@ class NotificationService:
raise ServiceError(f"Invalid service URL: {error_msg}")
try:
- # If service_urls are provided, create a new Apprise instance
+ # If service_urls are provided, partition them by scheme and
+ # dispatch each group with its own SSRF send-time guard.
if service_urls:
- temp_apprise = apprise.Apprise()
- result = temp_apprise.add(service_urls, tag=tag)
-
- if not result:
+ strict_urls, lenient_urls = self._partition_urls(service_urls)
+ if not strict_urls and not lenient_urls:
logger.error(
- f"Failed to add service URLs to Apprise: "
+ f"No service URLs after parsing: "
f"{mask_sensitive_url(service_urls)}"
)
return False
-
- # Send notification with the temp instance (with retry)
- return self._send_with_retry(
- title, body, temp_apprise, tag, attach
+ return self._dispatch(
+ title, body, strict_urls, lenient_urls, tag, attach
)
- # Use the configured apprise instance
+ # The pre-configured instance (self.apprise) is created empty in
+ # __init__ and is never populated by this class — all delivery
+ # goes through the guarded per-call service_urls path above.
if len(self.apprise) == 0:
logger.debug("No notification services configured in Apprise")
return False
- # Send notification (with retry)
- return self._send_with_retry(title, body, self.apprise, tag, attach)
+ # Defense-in-depth: if a future caller ever adds URLs directly to
+ # self.apprise, refuse rather than deliver them here — this branch
+ # has no DNS pin / block-private guard, so sending would silently
+ # bypass the SSRF hardening the service_urls path enforces. Fail
+ # closed. See SECURITY.md "Notification Webhook SSRF".
+ logger.error(
+ "Refusing to send via the pre-configured Apprise instance: "
+ "it is populated but this path is unguarded. Pass "
+ "service_urls to send() so the DNS pin / block-private guard "
+ "applies."
+ )
+ return False
except Exception as e:
# Tenacity will retry, but if all retries fail, raise SendError
@@ -215,6 +475,89 @@ class NotificationService:
)
raise SendError(f"Failed to send notification: {str(e)}")
+ def _dispatch(
+ self,
+ title: str,
+ body: str,
+ strict_urls: List[str],
+ lenient_urls: List[str],
+ tag: Optional[str],
+ attach: Optional[List[str]],
+ ) -> bool:
+ """Send each scheme-partition under its SSRF send-time guard.
+
+ ``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.
+
+ Each non-empty partition is dispatched (and retried by Tenacity)
+ under its own guard. A partition that adds no URLs returns False
+ (matching the historical add-failure behavior); a partition that
+ fails to deliver after all retries raises ``SendError`` (which the
+ caller re-wraps), so overall success requires every partition to
+ deliver.
+ """
+ partitions = []
+ if strict_urls:
+ partitions.append(
+ (
+ strict_urls,
+ lambda: dns_pinning.pinned_notification_send(
+ strict_urls,
+ allow_localhost=False,
+ allow_private_ips=self.allow_private_ips,
+ ),
+ )
+ )
+ if lenient_urls:
+ partitions.append(
+ (
+ lenient_urls,
+ lambda: dns_pinning.pinned_notification_send(
+ lenient_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.
+ block_link_local=True,
+ ),
+ )
+ )
+
+ any_ok = False
+ for urls, guard_factory in partitions:
+ temp_apprise = self._new_apprise()
+ # apprise types ``add(servers=...)`` as an invariant ``list`` whose
+ # element union includes ``str``; a ``list[str]`` is valid at
+ # runtime but mypy rejects it on list invariance (upstream should
+ # use ``Sequence``).
+ if not temp_apprise.add(urls, tag=tag): # type: ignore[arg-type]
+ logger.error(
+ f"Failed to add service URLs to Apprise: "
+ f"{mask_sensitive_url(' '.join(urls))}"
+ )
+ return False
+ # _send_with_retry returns True or raises SendError after
+ # Tenacity exhausts its retries; a raise propagates to send().
+ self._send_with_retry(
+ title, body, temp_apprise, guard_factory, tag, attach
+ )
+ any_ok = True
+ return any_ok
+
def send_event(
self,
event_type: EventType,
@@ -331,8 +674,9 @@ class NotificationService:
"error": user_error,
}
- # Create temporary Apprise instance
- temp_apprise = apprise.Apprise()
+ # Create temporary Apprise instance (synchronous so the pin +
+ # block-private window below applies in this thread).
+ temp_apprise = self._new_apprise()
add_result = temp_apprise.add(url)
if not add_result:
@@ -341,13 +685,40 @@ class NotificationService:
"error": "Failed to add service URL",
}
- # Send test notification
- result = temp_apprise.notify(
- title="Test Notification",
- body=(
+ # Send the test through the SAME guarded dispatch core as the real
+ # 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.
+ scheme = url.strip().split(":", 1)[0].lower() if ":" in url else ""
+ is_plugin_scheme = scheme not in ("http", "https")
+ allow_private = (
+ self.allow_private_ips if not is_plugin_scheme 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.
+ guard_factory = functools.partial(
+ dns_pinning.pinned_notification_send,
+ [url.strip()],
+ allow_localhost=False,
+ allow_private_ips=allow_private,
+ block_link_local=is_plugin_scheme,
+ )
+
+ result = self._guarded_notify(
+ "Test Notification",
+ (
"This is a test notification from Local Deep Research. "
"If you see this, your service is configured correctly!"
),
+ temp_apprise,
+ guard_factory,
+ tag=None,
)
if result:
@@ -355,6 +726,33 @@ class NotificationService:
"success": True,
"message": "Test notification sent successfully",
}
+
+ # A guarded test send that failed AND tripped the block-private
+ # window is a confirmed SSRF block: the window raised
+ # socket.gaierror on a send-time resolution to an
+ # internal/private/metadata IP, which Apprise swallowed into a
+ # generic delivery failure. Surface the specific reason to the
+ # admin instead of the generic message — mirrors the
+ # consume_ssrf_block short-circuit in _send_with_retry. (The pin
+ # path's own connect-time rebind catch raises ValueError before
+ # this point and is reported via the except below; this covers the
+ # UNPINNED block-window path — plugin-scheme endpoints and
+ # unresolvable-at-pin-time hosts.)
+ if dns_pinning.consume_ssrf_block():
+ logger.warning(
+ "Test notification blocked by the SSRF block-private "
+ "window (send-time resolution to internal/private/"
+ "metadata)"
+ )
+ return {
+ "success": False,
+ "error": (
+ "Test notification refused: the destination resolved "
+ "to an internal/private/metadata address at send time "
+ "(possible SSRF). See SECURITY.md 'Notification "
+ "Webhook SSRF'."
+ ),
+ }
return {
"success": False,
"error": "Failed to send test notification",
diff --git a/src/local_deep_research/security/dns_pinning.py b/src/local_deep_research/security/dns_pinning.py
index 9094347518..13949bd16c 100644
--- a/src/local_deep_research/security/dns_pinning.py
+++ b/src/local_deep_research/security/dns_pinning.py
@@ -36,6 +36,24 @@ Why a ``getaddrinfo`` shim rather than a custom ``HTTPAdapter``:
``security/egress`` ``socket.connect`` audit hook, which also installs a
process-wide, thread-local-gated interposition.
+The outbound-notification path (Apprise) reuses the same shim through
+:func:`pinned_notification_send`. Apprise fans out to arbitrary user URLs
+via ``requests``/``urllib3`` and re-resolves at send time — the exact
+resolve-vs-connect gap the shim closes — but it also follows redirects and
+can be pointed at a *new*, unpinned host. So the notification window pins
+every raw-webhook host in the batch AND activates a thread-local
+"block-private" mode (:func:`block_private_resolution`): for its duration,
+any UNPINNED lookup that resolves to a private/loopback/link-local/
+cloud-metadata address is refused at the ``getaddrinfo`` layer (a
+``socket.gaierror``), so a redirect-to-internal is blocked at the socket
+layer before a connection is made. Public unpinned hosts resolve normally.
+The block is thread-local, so it only affects the sending thread and can
+never wrongly block a legitimate private request running concurrently in
+another thread. It is activated only after Apprise is forced into
+synchronous, in-thread delivery (``AppriseAsset(async_mode=False)``); with
+the default async fan-out the send would run in worker threads that carry
+no thread-local pin/block and the guard would silently not apply.
+
Import-order dependency: the pin only works while ``socket.getaddrinfo``
is still THIS module's shim. If something replaces ``socket.getaddrinfo``
wholesale AFTER this module is imported — e.g. ``gevent``/``eventlet``
@@ -101,8 +119,61 @@ _real_getaddrinfo = _capture_real_getaddrinfo()
# host (normalized) -> list of addrinfo 5-tuples that are safe to connect
# to. Thread-local so concurrent fetches in different worker threads cannot
# see one another's pins.
+#
+# The same thread-local also carries an optional ``block_private`` entry —
+# a ``(allow_localhost, allow_private_ips, block_link_local)`` tuple set by
+# :func:`block_private_resolution`. While present, every UNPINNED lookup on
+# this thread is resolved and re-checked against the SSRF policy, and a
+# result containing any blocked (private/loopback/link-local/metadata)
+# address is refused. See :func:`_resolve_maybe_block`.
_thread_state = threading.local()
+# Schemes whose URL host is a real, resolvable connection target that the
+# client will connect to verbatim — so pinning the validated address is both
+# possible and worthwhile. These are the raw-webhook Apprise schemes
+# (``json``/``xml``/``form`` and their TLS variants) plus plain
+# ``http``/``https``.
+#
+# Every OTHER reachable Apprise scheme is deliberately excluded from pinning,
+# for one of two reasons — but both remaining kinds are still resolve-time
+# block-checked by the block-private window (:func:`block_private_resolution`),
+# so excluding them from pinning never leaves a cloud-metadata hole:
+#
+# * Token-host schemes (``discord://``, ``slack://``, ``tgram://`` …) put an
+# opaque credential/token in ``parse_url``'s host field, not a hostname.
+# Pinning would try to resolve that token as a name and break the send;
+# these plugins POST to their own hardcoded public API endpoints anyway.
+# * Self-hosted plugin schemes (``gotify://``, ``ntfy(s)://``, ``mattermost://``,
+# ``matrix://``, ``rocketchat://``, ``teams://`` …) DO carry a real,
+# 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.
+#
+# This block-window guarantee holds only for schemes whose network I/O resolves
+# through the shimmed ``socket.getaddrinfo`` — which every scheme reachable
+# today does (they send via ``requests``/``urllib3`` or ``smtplib``, both of
+# which call ``getaddrinfo``). Which schemes can reach this send path at all is
+# gated upstream by ``NotificationURLValidator.ALLOWED_SCHEMES``; a scheme that
+# connects via a primitive the shim cannot see (e.g. a raw ``socket.sendto``
+# datagram, as Apprise's ``rsyslog://`` uses) would bypass BOTH the pin and the
+# block window, so such a scheme must never be added to that allowlist.
+_PINNABLE_SCHEMES = frozenset(
+ {
+ "http",
+ "https",
+ "json",
+ "jsons",
+ "xml",
+ "xmls",
+ "form",
+ "forms",
+ }
+)
+
_installed = False
@@ -125,6 +196,22 @@ def _normalize_host(host: Optional[str]) -> Optional[str]:
return host or None
+def _host_for_log(host) -> str:
+ """Best-effort text form of a host for a log message.
+
+ ``getaddrinfo`` accepts a ``bytes``/``bytearray`` host as well as a
+ ``str``; decode one to text so the block-window warning reads cleanly.
+ Decoding is for the log line only — the SSRF check runs on resolved IPs,
+ never on the host string — so it must never raise: ``surrogateescape``
+ round-trips any byte sequence. (The ``idna`` codec is deliberately NOT
+ used here: it does not support an error handler and raises on non-hostname
+ bytes.)
+ """
+ if isinstance(host, (bytes, bytearray)):
+ return bytes(host).decode("utf-8", errors="surrogateescape")
+ return str(host)
+
+
def _get_pins() -> dict:
pins = getattr(_thread_state, "pins", None)
if pins is None:
@@ -133,6 +220,89 @@ def _get_pins() -> dict:
return pins
+def reset_ssrf_block() -> None:
+ """Clear the per-thread "an SSRF block occurred" marker.
+
+ Called before a guarded ``notify()`` so :func:`consume_ssrf_block`
+ reflects only that attempt. See :func:`_resolve_maybe_block`.
+ """
+ _thread_state.ssrf_block_occurred = False
+
+
+def consume_ssrf_block() -> bool:
+ """Return whether the block-private window refused a lookup on this
+ thread since the last :func:`reset_ssrf_block`, and clear the marker.
+
+ Apprise swallows the ``socket.gaierror`` the block raises inside its
+ plugin, surfacing only a generic delivery failure. The sender
+ (``notifications.service._send_with_retry``) consults this after a failed
+ send to tell a confirmed security block apart from a transient error, so
+ the block can fail fast instead of being retried 3x.
+ """
+ occurred = getattr(_thread_state, "ssrf_block_occurred", False)
+ _thread_state.ssrf_block_occurred = False
+ return bool(occurred)
+
+
+# Send-time DNS resolution is bounded so a slow / hostile DNS authority
+# cannot hang the sending thread — which, on the notification path, is an
+# HTTP request handler (test_service is reached straight from the "Send Test
+# Notification" endpoint). Mirrors
+# ``notification_validator._resolve_hostname_ips``.
+_RESOLVE_TIMEOUT_SECONDS = 5
+
+
+def _getaddrinfo_bounded(host, port, family, type, proto, flags):
+ """Call the genuine resolver with a bounded timeout; fail closed.
+
+ Runs ``_real_getaddrinfo`` on a short-lived DAEMON thread (thread-safe
+ timeout, no ``socket.setdefaulttimeout`` process-global mutation) so a
+ hostile DNS authority that never answers cannot block the caller past
+ ``_RESOLVE_TIMEOUT_SECONDS``. On timeout a ``socket.gaierror`` is raised
+ — the lookup is REFUSED, never returned as a blank/partial answer a
+ caller might treat as "resolved" — so the timeout can only ever fail
+ closed. A resolution error raised by the resolver itself
+ (``socket.gaierror`` / ``OSError``) propagates unchanged.
+
+ The worker is a DAEMON thread deliberately: a ``getaddrinfo`` call that
+ hangs in C cannot be cancelled, and a non-daemon worker (as a
+ ``concurrent.futures`` pool thread is) would be joined by the interpreter
+ at shutdown — letting an in-flight hostile lookup block graceful process
+ exit / restart. A daemon worker is abandoned on timeout and never blocks
+ interpreter exit.
+ """
+ result: dict = {}
+
+ def _worker() -> None:
+ try:
+ result["value"] = _real_getaddrinfo(
+ host, port, family, type, proto, flags
+ )
+ except BaseException as exc: # noqa: BLE001 - propagated to caller
+ result["error"] = exc
+
+ worker = threading.Thread(
+ target=_worker,
+ name="ldr-dns-pin-resolve",
+ daemon=True,
+ )
+ worker.start()
+ worker.join(_RESOLVE_TIMEOUT_SECONDS)
+ if worker.is_alive():
+ # Timed out. The daemon worker is abandoned (it dies with the
+ # process) and the lookup is refused — fail closed.
+ raise socket.gaierror(
+ getattr(socket, "EAI_AGAIN", socket.EAI_FAIL),
+ f"DNS resolution for {host!r} timed out after "
+ f"{_RESOLVE_TIMEOUT_SECONDS}s during a pinned send (fail closed)",
+ )
+ if "error" in result:
+ # Re-raise the resolver's own error unchanged (e.g. gaierror for
+ # NXDOMAIN) so existing gaierror/OSError handling stays intact.
+ raise result["error"]
+ return result["value"]
+
+
def _pinned_getaddrinfo(host, port, family=0, type=0, proto=0, flags=0):
"""Process-wide ``socket.getaddrinfo`` replacement.
@@ -184,7 +354,76 @@ def _pinned_getaddrinfo(host, port, family=0, type=0, proto=0, flags=0):
getattr(socket, "EAI_ADDRFAMILY", socket.EAI_FAIL),
"No pinned address for the requested family/socktype",
)
- return _real_getaddrinfo(host, port, family, type, proto, flags)
+ # Not pinned. Delegate to the real resolver, but if a block-private
+ # window is active on this thread, refuse any answer that resolves to a
+ # blocked address (redirect-to-internal / rebind-to-metadata guard).
+ return _resolve_maybe_block(host, port, family, type, proto, flags)
+
+
+def _resolve_maybe_block(host, port, family, type, proto, flags):
+ """Real resolution for an unpinned host, honoring the block window.
+
+ When no block-private window is active this is a transparent
+ pass-through to the genuine resolver — with NO added timeout/thread
+ overhead, so ordinary process-wide DNS is completely unaffected by the
+ shim. When a window IS active (set by :func:`block_private_resolution`,
+ i.e. during a notification send), the resolution is (a) bounded by a
+ timeout so a slow / hostile DNS authority cannot hang the sending thread
+ (fail closed — a timeout refuses the lookup, it never returns a blank
+ answer), and (b) the resolved addresses are checked against the SSRF
+ policy and the lookup is refused with ``socket.gaierror`` if ANY of them
+ is blocked — closing a redirect-to-internal or rebind-to-metadata that
+ targets a host that was never pinned. The check runs on the SAME address
+ list the caller will connect to (this IS the ``getaddrinfo`` the client
+ uses), so there is no second resolution to race against.
+ """
+ block = getattr(_thread_state, "block_private", None)
+ if block is None:
+ # No window active: transparent, zero-overhead pass-through.
+ return _real_getaddrinfo(host, port, family, type, proto, flags)
+ # Window active — bound the resolution (send path) and fail closed on a
+ # timeout by letting the gaierror propagate to the client.
+ results = _getaddrinfo_bounded(host, port, family, type, proto, flags)
+ # A ``None`` host is an AF_PASSIVE bind
+ # (``getaddrinfo(None, port, ..., AI_PASSIVE)`` — a local listening-socket
+ # setup, not an outbound name to rebind), so it carries no attacker-
+ # controllable destination and is exempt from the block check. EVERY other
+ # host is checked, INCLUDING a ``bytes``/``bytearray`` host: ``getaddrinfo``
+ # accepts a bytes name and a bytes host (e.g. ``b"169.254.169.254"``)
+ # resolves to metadata/link-local exactly as a ``str`` host would, so
+ # returning it unchecked would be the one guard that fails OPEN. The check
+ # itself runs on the resolved IPs regardless of the host type — only the
+ # log line needs a text host, so a bytes host is decoded for display.
+ if host is None:
+ return results
+ host_display = _host_for_log(host)
+ allow_localhost, allow_private_ips, block_link_local = block
+ for info in results:
+ ip_str = str(info[4][0])
+ if ssrf_validator.is_ip_blocked(
+ ip_str,
+ allow_localhost=allow_localhost,
+ allow_private_ips=allow_private_ips,
+ block_link_local=block_link_local,
+ ):
+ logger.warning(
+ "Blocked send-time resolution of {} to internal/private/"
+ "metadata IP {} during the pinned notification window "
+ "(possible SSRF / redirect-to-internal)",
+ host_display,
+ ip_str,
+ )
+ # Mark the thread so the sender can tell this confirmed security
+ # block apart from a transient failure once Apprise has swallowed
+ # the gaierror below — a confirmed block must fail fast, not be
+ # retried. Consumed by ``consume_ssrf_block``.
+ _thread_state.ssrf_block_occurred = True
+ raise socket.gaierror(
+ getattr(socket, "EAI_FAIL", -1),
+ "Blocked resolution to an internal/private/metadata IP "
+ "during the pinned notification send window",
+ )
+ return results
# Stamp our shim so a later capture (e.g. after ``importlib.reload``) can tell
@@ -208,52 +447,94 @@ def install() -> None:
global _installed
if _installed:
return
- # A reload resets ``_installed`` to False, so also refuse to reinstall
- # when our shim is already the active resolver. Combined with the capture
- # guard above, this keeps a reload from ever chaining shim-onto-shim.
- if not getattr(socket.getaddrinfo, _SHIM_MARKER, False):
+ # Install our shim unless it is ALREADY EXACTLY this module's shim
+ # (identity check, not just the marker). A reload resets ``_installed`` to
+ # False and rebuilds ``_pinned_getaddrinfo`` as a fresh function object,
+ # while ``socket.getaddrinfo`` still points at the PREVIOUS load's shim —
+ # a stale, marker-stamped resolver whose thread-local reads live in the
+ # old module. Reinstalling here keeps ``socket.getaddrinfo`` in lockstep
+ # with the reloaded module so ``_shim_installed()`` — the invariant the
+ # notification send fails closed on — holds after a reload, instead of
+ # silently reporting the shim as missing forever.
+ #
+ # This cannot chain shim-onto-shim: ``_real_getaddrinfo`` is captured via
+ # ``_capture_real_getaddrinfo``, which never returns a shim, so the newly
+ # installed shim's pass-through calls the genuine resolver, not the old
+ # shim.
+ if socket.getaddrinfo is not _pinned_getaddrinfo:
socket.getaddrinfo = _pinned_getaddrinfo
_installed = True
-def _extract_host(url: Optional[str]) -> Tuple[Optional[str], bool]:
- """Return ``(normalized_host, is_ip_literal)`` for ``url``.
+def _shim_installed() -> bool:
+ """True iff THIS module's shim is still the active ``getaddrinfo``.
+
+ The pin and block-private guarantees only hold while
+ ``socket.getaddrinfo`` is exactly this module's ``_pinned_getaddrinfo``:
+ the thread-local pin/block state lives here, so a wholesale replacement
+ after import (``gevent``/``eventlet`` monkeypatch, another socket shim,
+ or a stale post-reload shim) would consult different state and silently
+ drop the guard. The check is strict identity — a *different* shim, even
+ one stamped with our marker, does not satisfy it because it would read a
+ different ``_thread_state``. Callers on the send path treat a False here
+ as fail-closed rather than sending unguarded.
+ """
+ return socket.getaddrinfo is _pinned_getaddrinfo
+
+
+def _extract_scheme_host(
+ url: Optional[str],
+) -> Tuple[Optional[str], Optional[str], bool]:
+ """Return ``(scheme, normalized_host, is_ip_literal)`` for ``url``.
- ``host`` is ``None`` when the URL is empty or the parser rejects it.
- Uses ``urllib3.util.parse_url`` — the same parser ``requests`` uses
+ ``scheme`` is lower-cased (``None`` when absent). ``host`` is ``None``
+ when the URL is empty or the parser rejects it. Uses
+ ``urllib3.util.parse_url`` — the same parser ``requests`` uses
internally and the same one ``ssrf_validator.validate_url`` validates
against — so the host we pin is the host the client will resolve.
"""
if not url:
- return None, False
+ return None, None, False
try:
parsed = parse_url(url)
except (LocationParseError, ValueError):
- return None, False
+ return None, None, False
+ scheme = (parsed.scheme or "").lower() or None
host = _normalize_host(parsed.host)
if host is None:
- return None, False
+ return scheme, None, False
try:
ipaddress.ip_address(host)
- return host, True # IP literal — no DNS to rebind
+ return scheme, host, True # IP literal — no DNS to rebind
except ValueError:
- return host, False
+ return scheme, host, False
+
+
+def _extract_host(url: Optional[str]) -> Tuple[Optional[str], bool]:
+ """Return ``(normalized_host, is_ip_literal)`` for ``url``.
+
+ Thin wrapper over :func:`_extract_scheme_host` for callers that don't
+ need the scheme (e.g. :func:`pinned_request`).
+ """
+ _scheme, host, is_literal = _extract_scheme_host(url)
+ return host, is_literal
def _resolve_and_validate(
host: str,
allow_localhost: bool,
allow_private_ips: bool,
+ block_link_local: bool = False,
) -> List[tuple]:
"""Resolve ``host`` once and validate every returned address.
Uses the real resolver (never the shim, to avoid recursion and to
ignore any pin) and applies exactly the ``is_ip_blocked`` policy that
``validate_url`` applies — honoring ``allow_localhost`` /
- ``allow_private_ips`` while the ``ALWAYS_BLOCKED_METADATA_IPS`` set
- keeps firing regardless. This is the connect-time re-validation that
- the pin adds: an answer that changed since ``validate_url`` ran is
- caught here.
+ ``allow_private_ips`` (and ``block_link_local`` for the notification
+ path) while the ``ALWAYS_BLOCKED_METADATA_IPS`` set keeps firing
+ regardless. This is the connect-time re-validation that the pin adds: an
+ answer that changed since ``validate_url`` ran is caught here.
Returns the addrinfo list to pin (all entries validated safe).
@@ -261,12 +542,14 @@ def _resolve_and_validate(
ValueError: if any resolved address is blocked. SSRF-style message
so existing callers/tests catch it uniformly.
requests.ConnectionError: if the host no longer resolves at pin
- time — fail closed as an ordinary transport error so the
- existing retry / ``RequestException`` handling stays intact.
+ time, OR if resolution times out (a slow / hostile DNS authority
+ cannot hang the send) — fail closed as an ordinary transport
+ error so the existing retry / ``RequestException`` handling stays
+ intact.
"""
try:
- addr_info = _real_getaddrinfo(
- host, None, socket.AF_UNSPEC, socket.SOCK_STREAM
+ addr_info = _getaddrinfo_bounded(
+ host, None, socket.AF_UNSPEC, socket.SOCK_STREAM, 0, 0
)
except socket.gaierror as exc:
raise requests.ConnectionError(
@@ -283,6 +566,7 @@ def _resolve_and_validate(
ip_str,
allow_localhost=allow_localhost,
allow_private_ips=allow_private_ips,
+ block_link_local=block_link_local,
):
logger.warning(
"Blocked connect-time address for host {}: resolves to "
@@ -345,6 +629,175 @@ def pinned_request(
pins.pop(host, None)
+def block_private_resolution(
+ allow_localhost: bool = False,
+ allow_private_ips: bool = False,
+ block_link_local: bool = False,
+) -> Iterator[None]:
+ """Refuse UNPINNED lookups that resolve to a blocked address.
+
+ While this context is active on the calling thread, any host that is
+ NOT covered by an active pin and resolves to a private / loopback /
+ link-local / cloud-metadata address (per ``ssrf_validator.is_ip_blocked``
+ with the supplied flags) is refused at the ``getaddrinfo`` layer with a
+ ``socket.gaierror``. Pinned hosts are unaffected (they short-circuit to
+ their validated addresses), and public unpinned hosts resolve normally.
+
+ ``block_link_local`` (notification lenient partition): when True, the
+ whole link-local range stays refused even under ``allow_private_ips=True``
+ — closing metadata reachable in link-local beyond the always-blocked
+ literals (e.g. Scaleway ``169.254.42.42``) without over-blocking RFC1918 /
+ loopback / non-link-local ULA self-hosted notifiers.
+
+ This closes redirect-to-internal / rebind-to-metadata for hosts that
+ were never pinned (e.g. a webhook that 302-redirects to
+ ``169.254.169.254`` or ``127.0.0.1``): the block runs on the very
+ resolution the client is about to connect to, so there is no window to
+ race.
+
+ Thread-local: only the calling thread is affected, so a legitimate
+ private request in another thread is never disturbed. Windows nest
+ (inner replaces outer, restored on exit).
+ """
+ prev = getattr(_thread_state, "block_private", None)
+ _thread_state.block_private = (
+ allow_localhost,
+ allow_private_ips,
+ block_link_local,
+ )
+ try:
+ yield
+ finally:
+ _thread_state.block_private = prev
+
+
+def pin_hosts(
+ urls,
+ allow_localhost: bool = False,
+ allow_private_ips: bool = False,
+ block_link_local: bool = False,
+) -> Iterator[None]:
+ """Pin the validated address of every pinnable host in ``urls``.
+
+ For each URL whose scheme is in :data:`_PINNABLE_SCHEMES` and whose host
+ is a real (non-literal) name, resolves once, validates every returned
+ address against the SSRF policy, and pins those addresses for the
+ duration of the context. IP literals, token-host plugin schemes, and
+ unparseable URLs are skipped (nothing to rebind, or the host is not a
+ resolvable name). A host that fails to resolve right now is also skipped
+ rather than aborting the whole batch — it is left unpinned so the
+ accompanying block-private window still governs its send-time lookup and
+ Apprise fails only that one URL.
+
+ ``block_link_local`` is forwarded to the connect-time validation so a
+ raw-webhook host that resolves into link-local (metadata territory) is
+ refused even under ``allow_private_ips=True`` (notification lenient
+ partition).
+
+ Raises:
+ ValueError: if a pinnable host resolves to a blocked address (the
+ batch is refused — fail closed).
+ """
+ pins = _get_pins()
+ saved: List[Tuple[str, bool, Optional[list]]] = []
+ pinned_now = set()
+ try:
+ for url in urls:
+ scheme, host, is_literal = _extract_scheme_host(url)
+ if scheme not in _PINNABLE_SCHEMES:
+ continue
+ if host is None or is_literal or host in pinned_now:
+ continue
+ try:
+ entry = _resolve_and_validate(
+ host,
+ allow_localhost,
+ allow_private_ips,
+ block_link_local=block_link_local,
+ )
+ except requests.ConnectionError:
+ logger.debug(
+ "Skipping pin for currently-unresolvable host {}", host
+ )
+ continue
+ saved.append((host, host in pins, pins.get(host)))
+ pins[host] = entry
+ pinned_now.add(host)
+ yield
+ finally:
+ for host, had_previous, previous in reversed(saved):
+ if had_previous:
+ pins[host] = previous
+ else:
+ pins.pop(host, None)
+
+
+def pinned_notification_send(
+ urls,
+ allow_localhost: bool = False,
+ allow_private_ips: bool = False,
+ block_link_local: bool = False,
+) -> Iterator[None]:
+ """Guard a single in-thread Apprise ``notify()`` over ``urls``.
+
+ Combines :func:`pin_hosts` (pin every raw-webhook host in the batch to
+ its validated address) with :func:`block_private_resolution` (refuse any
+ unpinned lookup — a redirect target or a token-scheme endpoint — that
+ resolves to a blocked address). Both are thread-local, so the caller
+ MUST run the ``notify()`` synchronously in this thread
+ (``AppriseAsset(async_mode=False)``); an async fan-out would resolve in
+ worker 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.
+
+ Raises:
+ RuntimeError: if the ``getaddrinfo`` shim is not the active resolver
+ (see :func:`_shim_installed`). The pin/block cannot be
+ guaranteed in that state, so the send is REFUSED (fail closed)
+ rather than proceeding unguarded.
+ """
+ # Fail closed if our shim is not installed: without it the pin registry
+ # and the block-private window are never consulted, so proceeding would
+ # send completely unguarded (silent fail-open). Refuse instead.
+ if not _shim_installed():
+ raise RuntimeError(
+ "DNS pin shim is not the active socket.getaddrinfo; refusing the "
+ "notification send (fail closed). The resolve-vs-connect pin and "
+ "block-private window cannot be guaranteed — see "
+ "security.dns_pinning."
+ )
+ with contextlib.ExitStack() as stack:
+ stack.enter_context(
+ pin_hosts(
+ urls,
+ allow_localhost,
+ allow_private_ips,
+ block_link_local=block_link_local,
+ )
+ )
+ stack.enter_context(
+ block_private_resolution(
+ allow_localhost,
+ allow_private_ips,
+ block_link_local=block_link_local,
+ )
+ )
+ yield
+
+
# Install on import: safe_requests imports this module, so the shim is in
# place before any fetch. Transparent until a pin is active.
install()
diff --git a/src/local_deep_research/security/notification_validator.py b/src/local_deep_research/security/notification_validator.py
index 743068810d..3e551b952f 100644
--- a/src/local_deep_research/security/notification_validator.py
+++ b/src/local_deep_research/security/notification_validator.py
@@ -76,7 +76,10 @@ class NotificationURLValidator:
@staticmethod
def _ip_matches_blocked_range(
- ip, allow_private_ips: bool = False, allow_nat64: Optional[bool] = None
+ ip,
+ allow_private_ips: bool = False,
+ allow_nat64: Optional[bool] = None,
+ block_link_local: bool = False,
) -> bool:
"""Block-decision for a parsed IP, delegating to
``ssrf_validator.is_ip_blocked`` so the two validators share a
@@ -93,6 +96,11 @@ class NotificationURLValidator:
above still fire. This closes the historical bypass where
``allow_private_ips=True`` skipped the host check entirely
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.
"""
from .ssrf_validator import is_ip_blocked
@@ -100,6 +108,7 @@ class NotificationURLValidator:
str(ip),
allow_private_ips=allow_private_ips,
allow_nat64=allow_nat64,
+ block_link_local=block_link_local,
)
@staticmethod
@@ -117,31 +126,43 @@ class NotificationURLValidator:
"""
# NOTE: best-effort, validation-time check. Apprise re-resolves
# the hostname when it actually sends the request (via
- # requests/urllib3), so an attacker controlling DNS can serve a
- # public IP here and a private IP at send time — a classic DNS
- # rebinding TOCTOU window. Apprise exposes no Session/adapter/
- # DNS hook to close this in code without fragile monkey-patching
- # of its plugin internals.
+ # requests/urllib3), so a DNS-rebinding attacker could serve a
+ # public IP here and a private/metadata IP at send time — the
+ # classic resolve-vs-connect TOCTOU window.
#
- # RESIDUAL RISK (documented, not closed here): the ``safe_requests``
- # fetch path now pins the validated address for the actual
- # connection (``security.dns_pinning``). That pin is NOT reused for
- # Apprise: a single ``notify()`` can fan out to multiple service
- # URLs and Apprise's plugins re-resolve — and may follow redirects
- # to further hosts — inside their own request stack, so a partial
- # pin here would give false confidence rather than a guarantee.
- # The env-only master switch below remains the boundary; pinning
- # the full Apprise delivery path is a tracked follow-up.
+ # SEND-TIME GUARD (this window is now closed in code for the
+ # delivery path): ``notifications.service`` forces Apprise into
+ # synchronous, in-thread delivery (``AppriseAsset(async_mode=False)``),
+ # disables HTTP redirect-following for the send (asset-level
+ # ``http_redirects=False`` re-forced per plugin, so a user-supplied
+ # ``?redirect=yes`` cannot re-enable it), and wraps every ``notify()``
+ # in ``dns_pinning.pinned_notification_send`` (see
+ # ``security.dns_pinning``). Together, for the duration of the send,
+ # that (a) closes the redirect attack class outright — a webhook can
+ # no longer 30x-redirect the send to a private/loopback host or to an
+ # arbitrary public host for data exfiltration, because the send is
+ # simply not redirected; (b) pins every raw-webhook host in the batch
+ # to the address validated here, so the ORIGINAL host's own DNS
+ # rebind cannot steer the connection to a different address; and
+ # (c) activates a thread-local block-private mode so any UNPINNED
+ # lookup (a plugin scheme's endpoint) that resolves to a blocked
+ # 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,
+ # they never disturb a legitimate private request on another thread.
#
- # Because the window cannot be closed cleanly in code, the
- # whole outbound-notification path is gated behind an env-only
- # master switch (LDR_NOTIFICATIONS_ALLOW_OUTBOUND, default off);
- # turning it on is the operator's explicit risk-acceptance. See
- # SECURITY.md "Notification Webhook SSRF". Operators wanting to
- # avoid the window entirely should prefer plugin schemes
- # (discord://, slack://, ntfy://, ntfys://, gotify://,
- # telegram://, mattermost://, etc.) that hardcode their
- # endpoints instead of raw http(s):// webhooks.
+ # DEFENSE IN DEPTH: the whole outbound-notification path is still
+ # gated behind an env-only master switch
+ # (LDR_NOTIFICATIONS_ALLOW_OUTBOUND, default off); enabling it is the
+ # operator's explicit decision. See SECURITY.md "Notification Webhook
+ # SSRF". Operators can further avoid raw webhooks by preferring
+ # plugin schemes (discord://, slack://, ntfy://, ntfys://, gotify://,
+ # telegram://, mattermost://, etc.) that hardcode their endpoints.
#
# concurrent.futures for thread-safe timeout instead of
# socket.setdefaulttimeout() which is process-global.
@@ -176,6 +197,7 @@ class NotificationURLValidator:
allow_private_ips: bool = False,
allow_nat64: Optional[bool] = None,
resolved_ips: Optional[List[ResolvedIP]] = None,
+ block_link_local: bool = False,
) -> bool:
"""Decide whether ``hostname`` is blocked at the given
``allow_private_ips`` / ``allow_nat64`` level, optionally reusing
@@ -186,6 +208,9 @@ class NotificationURLValidator:
DNS-rebinding TOCTOU windows between calls. If ``resolved_ips``
is None and ``hostname`` is not an IP literal, DNS is resolved
via ``_resolve_hostname_ips``.
+
+ ``block_link_local`` forces the whole link-local range blocked even
+ under ``allow_private_ips=True`` (plugin-scheme IMDS guard).
"""
# Localhost-string shortcuts only apply when the operator hasn't
# opted into private-IP reachability. With allow_private_ips=True
@@ -207,6 +232,7 @@ class NotificationURLValidator:
ip,
allow_private_ips=allow_private_ips,
allow_nat64=allow_nat64,
+ block_link_local=block_link_local,
)
except ValueError:
pass
@@ -224,6 +250,7 @@ class NotificationURLValidator:
ip,
allow_private_ips=allow_private_ips,
allow_nat64=allow_nat64,
+ block_link_local=block_link_local,
):
return True
return False
@@ -259,6 +286,7 @@ class NotificationURLValidator:
allow_private_ips: bool = False,
allow_nat64: Optional[bool] = None,
_resolved_ips: Optional[List[ResolvedIP]] = None,
+ block_link_local: bool = False,
) -> bool:
"""
Check if hostname resolves to a private IP address.
@@ -273,6 +301,10 @@ class NotificationURLValidator:
allow_nat64: Override for the ``security.allow_nat64`` carve-out.
None (default) reads the env setting; an explicit bool
answers 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).
Returns:
True if hostname is a private IP or localhost (subject to
@@ -283,6 +315,7 @@ class NotificationURLValidator:
allow_private_ips=allow_private_ips,
allow_nat64=allow_nat64,
resolved_ips=_resolved_ips,
+ block_link_local=block_link_local,
)
@staticmethod
@@ -423,6 +456,56 @@ class NotificationURLValidator:
f"Allowed: {', '.join(NotificationURLValidator.ALLOWED_SCHEMES[:5])}...",
)
+ # Reject authorities with more than one "@" (fail closed). urllib3's
+ # parse_url (which the SSRF host-check + the DNS pin validate against)
+ # and Apprise's own parse_url disagree on which host a multi-"@"
+ # authority denotes: for
+ # ``json://[email protected]@decoy-public.example.com/path``
+ # urllib3 sees ``decoy-public.example.com`` (validated/pinned) while
+ # Apprise connects to ``169.254.169.254``. This is the same
+ # parser-differential class as GHSA-g23j-2vwm-5c25; there is no
+ # legitimate reason for a second "@" in a notification authority, so
+ # reject it before the host is ever extracted. ``netloc`` is the
+ # authority only (path/query/fragment excluded), so an "@" in a query
+ # string is not counted. A single "@" (RFC 3986 userinfo, e.g.
+ # ``mailto://user:pass@host``) is still allowed.
+ if parsed.netloc.count("@") > 1:
+ logger.warning(
+ "Blocked notification URL: authority contains multiple '@' "
+ "(parser-differential SSRF risk)"
+ )
+ return (
+ False,
+ "URL authority contains multiple '@' characters, "
+ "which is not allowed",
+ )
+
+ # Reject a scheme://-form URL whose authority is EMPTY while content
+ # (a host smuggled into the path) follows — another parser-differential
+ # SSRF (defense-in-depth; the send-time block window backstops it).
+ # urllib3/requests parse an empty ``//`` authority as "no host", so the
+ # per-scheme IP checks below are skipped and the URL is accepted, but
+ # Apprise falls back to treating the first path segment as the host and
+ # dials it: ``json:///169.254.169.254/path`` reaches
+ # ``169.254.169.254``. No legitimate notification URL has an empty
+ # ``//`` authority, so reject it before host extraction. This fires
+ # ONLY when the ``//`` authority marker is present — a scheme that
+ # legitimately has no ``//`` authority (an RFC ``mailto:user@host``
+ # form) never reaches here, so it is not broken.
+ after_scheme = url[len(parsed.scheme) + 1 :]
+ if after_scheme.startswith("//") and not parsed.netloc:
+ remainder = after_scheme[2:] # everything past the '//'
+ if remainder:
+ logger.warning(
+ "Blocked notification URL with empty authority but "
+ "in-path host (parser-differential SSRF risk)"
+ )
+ return (
+ False,
+ "URL host (authority) is empty; a host in the path after "
+ "'scheme:///' is not allowed",
+ )
+
# Extract the host for any allowed scheme. We use urllib3 (the
# parser ``requests`` uses internally) instead of urlparse —
# urlparse is vulnerable to parser-differential bypasses like
@@ -460,6 +543,26 @@ class NotificationURLValidator:
return False, "URL host contains disallowed characters"
hostname = NotificationURLValidator._normalize_host(hostname)
+ # A populated ``//`` authority that urllib3 parses to an EMPTY host
+ # (e.g. ``json://169.254.169.254:80@/`` — an IP smuggled into the
+ # userinfo with nothing after the ``@``) is the sibling of the
+ # multi-``@`` / empty-``//``-authority cases above: urllib3 returns no
+ # host, so the per-scheme ``_is_private_ip`` checks below (guarded on
+ # ``if hostname``) are skipped and the URL is accepted, yet the
+ # authority still carries a target that another parser could dial. No
+ # legitimate notification URL has a non-empty ``//`` authority with an
+ # empty host, so reject it fail-closed before the scheme checks.
+ if after_scheme.startswith("//") and parsed.netloc and not hostname:
+ logger.warning(
+ "Blocked notification URL: non-empty authority with empty host "
+ "(parser-differential SSRF risk)"
+ )
+ return (
+ False,
+ "URL authority has no host; a host smuggled into the userinfo "
+ "is not allowed",
+ )
+
if scheme in ("http", "https"):
if hostname and NotificationURLValidator._is_private_ip(
hostname,
@@ -478,8 +581,13 @@ class NotificationURLValidator:
else:
# Plugin-scheme IMDS guard. ``allow_private_ips=True`` leaves
# ALWAYS_BLOCKED_METADATA_IPS and NAT64-wrapped metadata as
- # the only active blocks in ``_is_private_ip`` — exactly the
- # set we want to enforce regardless of operator flags.
+ # 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
@@ -488,13 +596,15 @@ class NotificationURLValidator:
hostname,
allow_private_ips=True,
allow_nat64=allow_nat64,
+ block_link_local=True,
):
logger.warning(
- f"Blocked cloud-metadata IP in notification URL: {hostname}"
+ "Blocked cloud-metadata / link-local IP in notification "
+ f"URL: {hostname}"
)
return (
False,
- f"Blocked cloud-metadata IP address: {hostname}",
+ f"Blocked cloud-metadata / link-local IP address: {hostname}",
)
# Passed all security checks
diff --git a/src/local_deep_research/security/ssrf_validator.py b/src/local_deep_research/security/ssrf_validator.py
index 45adc76867..e4c00fc4e7 100644
--- a/src/local_deep_research/security/ssrf_validator.py
+++ b/src/local_deep_research/security/ssrf_validator.py
@@ -20,6 +20,11 @@ from .ip_ranges import NAT64_PREFIXES
# Cloud-provider metadata endpoints — always blocked, even with
# allow_localhost=True or allow_private_ips=True. These IPs expose IAM /
# instance-role credentials and are never legitimate destinations.
+#
+# Entries are matched by canonical string form: is_ip_blocked parses the
+# candidate with ipaddress.ip_address first, so any textual variant
+# (uppercase / zero-padded / expanded IPv6) is normalized to the canonical
+# form below before the membership test.
# nosec B104 - Hardcoded IPs are intentional for SSRF prevention
ALWAYS_BLOCKED_METADATA_IPS = frozenset(
{
@@ -28,9 +33,29 @@ ALWAYS_BLOCKED_METADATA_IPS = frozenset(
"169.254.170.23", # AWS ECS task metadata v4
"169.254.0.23", # Tencent Cloud
"100.100.100.200", # AlibabaCloud
+ # AWS native IPv6 IMDS endpoint. Documented by AWS as the IPv6
+ # instance-metadata address ([fd00:ec2::254]). It is a ULA
+ # (fc00::/7), NOT an IPv4-mapped / NAT64-wrapped form of
+ # 169.254.169.254, so the IPv4 entries above and the NAT64
+ # embedded-IPv4 check do not cover it — it must be listed
+ # explicitly or it stays reachable under allow_private_ips=True
+ # (which permits fc00::/7).
+ "fd00:ec2::254", # AWS IMDS over IPv6
}
)
+# Link-local ranges. When ``block_link_local`` is set (notification path),
+# these stay blocked even under ``allow_private_ips=True`` — cloud-provider
+# metadata lives here beyond the always-blocked literals and no legitimate
+# self-hosted notifier does. Kept as a distinct list (a subset of the private
+# ranges) so the carve-out is explicit and testable. Module-level (built once
+# at import) rather than rebuilt on every ``is_ip_blocked`` call.
+# nosec B104 - Hardcoded ranges are intentional for SSRF prevention
+LINK_LOCAL_RANGES = [
+ ipaddress.ip_network("169.254.0.0/16"), # IPv4 link-local
+ ipaddress.ip_network("fe80::/10"), # IPv6 link-local
+]
+
# Allowed URL schemes
ALLOWED_SCHEMES = {"http", "https"}
@@ -54,6 +79,30 @@ def is_nat64_wrapped_metadata_ip(ip: ipaddress._BaseAddress) -> bool:
return False
+def is_nat64_wrapped_link_local_ip(ip: ipaddress._BaseAddress) -> bool:
+ """True iff ``ip`` is an IPv6 address inside a NAT64 prefix whose embedded
+ IPv4 (low 32 bits) is IPv4 link-local (``169.254.0.0/16``).
+
+ Mirrors ``is_nat64_wrapped_metadata_ip`` for the ``block_link_local``
+ notification guard. The ``security.allow_nat64`` opt-in re-opens general
+ IPv4 reachability via NAT64, but it must not re-open link-local — where
+ cloud-provider metadata lives beyond the always-blocked literals (e.g.
+ Scaleway's ``169.254.42.42``). Consulted only when ``block_link_local`` is
+ set, so non-notification callers (which permit link-local under
+ ``allow_private_ips``) keep the opt-in's reachability unchanged.
+ """
+ if not isinstance(ip, ipaddress.IPv6Address):
+ return False
+ for nat64_prefix in NAT64_PREFIXES:
+ if ip in nat64_prefix:
+ embedded_v4 = ipaddress.IPv4Address(int(ip) & 0xFFFFFFFF)
+ return any(
+ isinstance(r, ipaddress.IPv4Network) and embedded_v4 in r
+ for r in LINK_LOCAL_RANGES
+ )
+ return False
+
+
# RFC 3986 forbids these characters in URLs; their presence in a URL signals
# a parser-differential attempt (GHSA-g23j-2vwm-5c25). \s covers space, \t,
# \n, \r, \v, \f. Backslash is the load-bearing payload — Python's urlparse
@@ -68,6 +117,7 @@ def is_ip_blocked(
allow_localhost: bool = False,
allow_private_ips: bool = False,
allow_nat64: Optional[bool] = None,
+ block_link_local: bool = False,
) -> bool:
"""
Check if an IP address is in a blocked range.
@@ -83,6 +133,19 @@ def is_ip_blocked(
Note: cloud metadata endpoints in ``ALWAYS_BLOCKED_METADATA_IPS``
(AWS / Azure / OCI / DigitalOcean / AlibabaCloud / Tencent / ECS)
are ALWAYS blocked regardless of these flags.
+ block_link_local: When True, the entire link-local range — IPv4
+ ``169.254.0.0/16`` and IPv6 ``fe80::/10`` — is treated as blocked
+ EVEN under ``allow_private_ips=True``. Used by the notification
+ send path (see ``security.dns_pinning`` /
+ ``notification_validator``): the lenient plugin/raw-webhook
+ partition allows private LAN targets, but link-local is where
+ cloud-provider metadata lives beyond the six always-blocked
+ literals (e.g. Scaleway's ``169.254.42.42``) and is never a
+ legitimate self-hosted notifier, so it stays blocked there. Has no
+ effect unless ``allow_private_ips=True`` — without the opt-in
+ link-local is already blocked. Default False preserves the
+ behavior every non-notification caller relies on (RFC1918 /
+ loopback / non-link-local ULA remain allowed under the flag).
allow_nat64: Override for the ``security.allow_nat64`` carve-out.
``None`` (default) reads the env setting — the behavior every
existing caller relies on. An explicit ``bool`` answers a
@@ -144,6 +207,16 @@ def is_ip_blocked(
if is_nat64_wrapped_metadata_ip(ip):
return True
+ # For the notification send path (``block_link_local``), a NAT64-wrapped
+ # link-local address must also stay blocked even under the allow_nat64
+ # opt-in — otherwise the carve-out below `continue`s past the link-local
+ # check for the IPv6-wrapped form of e.g. Scaleway's 169.254.42.42.
+ # (When NAT64 is off the whole prefix is already blocked in the loop, so
+ # this only changes the opt-in case; gated on block_link_local so
+ # non-notification callers are unaffected.)
+ if block_link_local and is_nat64_wrapped_link_local_ip(ip):
+ return True
+
# Operator escape hatch for IPv6-only deployments using DNS64+NAT64.
# Read lazily (not at import) so test monkeypatching works and so the
# value is not cached across env mutations. Cloud-metadata IPs are
@@ -173,6 +246,17 @@ def is_ip_blocked(
if allow_private_ips:
is_loopback = any(ip in lr for lr in LOOPBACK_RANGES)
is_private = any(ip in pr for pr in PRIVATE_RANGES)
+ # Notification path: link-local stays blocked even under
+ # the private-IP opt-in (metadata lives here beyond the
+ # always-blocked literals; no legitimate self-hosted
+ # notifier does). Fires before the private/loopback skip so
+ # it cannot be un-blocked by it. Metadata literals already
+ # returned True above, so this only governs the rest of the
+ # link-local range.
+ if block_link_local and any(
+ ip in llr for llr in LINK_LOCAL_RANGES
+ ):
+ return True
if is_loopback or is_private:
continue
# If allow_localhost is True, skip blocking for loopback only
diff --git a/tests/auth_tests/test_encrypted_db.py b/tests/auth_tests/test_encrypted_db.py
index da780de0ff..655b63ebaf 100644
--- a/tests/auth_tests/test_encrypted_db.py
+++ b/tests/auth_tests/test_encrypted_db.py
@@ -292,12 +292,12 @@ class TestConnectionVerification:
def test_verify_connection_correct_password(self, db_manager, auth_user):
"""Verify connection verification returns True with correct password."""
- from src.local_deep_research.database.sqlcipher_utils import (
+ from local_deep_research.database.sqlcipher_utils import (
apply_sqlcipher_pragmas,
set_sqlcipher_key,
verify_sqlcipher_connection,
)
- from src.local_deep_research.database.sqlcipher_compat import (
+ from local_deep_research.database.sqlcipher_compat import (
get_sqlcipher_module,
)
@@ -320,11 +320,11 @@ class TestConnectionVerification:
def test_verify_connection_wrong_password(self, db_manager, auth_user):
"""Verify accessing encrypted data with wrong password fails."""
- from src.local_deep_research.database.sqlcipher_utils import (
+ from local_deep_research.database.sqlcipher_utils import (
apply_sqlcipher_pragmas,
set_sqlcipher_key,
)
- from src.local_deep_research.database.sqlcipher_compat import (
+ from local_deep_research.database.sqlcipher_compat import (
get_sqlcipher_module,
)
@@ -351,7 +351,7 @@ class TestConnectionVerification:
def test_all_pragmas_applied_comprehensive(self, db_manager, auth_user):
"""Comprehensive test verifying ALL SQLCipher pragmas are applied."""
- from src.local_deep_research.database.sqlcipher_utils import (
+ from local_deep_research.database.sqlcipher_utils import (
get_sqlcipher_settings,
)
@@ -408,7 +408,7 @@ class TestConnectionVerification:
def test_create_sqlcipher_connection_helper(self, db_manager, auth_user):
"""Test the create_sqlcipher_connection helper function."""
- from src.local_deep_research.database.sqlcipher_utils import (
+ from local_deep_research.database.sqlcipher_utils import (
create_sqlcipher_connection,
)
@@ -433,7 +433,7 @@ class TestConnectionVerification:
self, db_manager, auth_user
):
"""Test create_sqlcipher_connection fails with wrong password."""
- from src.local_deep_research.database.sqlcipher_utils import (
+ from local_deep_research.database.sqlcipher_utils import (
create_sqlcipher_connection,
)
diff --git a/tests/auth_tests/test_sqlcipher_backwards_compat.py b/tests/auth_tests/test_sqlcipher_backwards_compat.py
index 4a62889ddd..514aed984d 100644
--- a/tests/auth_tests/test_sqlcipher_backwards_compat.py
+++ b/tests/auth_tests/test_sqlcipher_backwards_compat.py
@@ -12,13 +12,13 @@ from pathlib import Path
import pytest
-from src.local_deep_research.database.sqlcipher_utils import (
+from local_deep_research.database.sqlcipher_utils import (
apply_cipher_defaults_before_key,
apply_performance_pragmas,
apply_sqlcipher_pragmas,
set_sqlcipher_key,
)
-from src.local_deep_research.database.sqlcipher_compat import (
+from local_deep_research.database.sqlcipher_compat import (
get_sqlcipher_module,
)
@@ -371,7 +371,7 @@ class TestOldToNewPragmaOrderMigration:
OLD order: key -> cipher_page_size -> cipher_hmac_algorithm -> kdf_iter
This simulates how databases were created before this PR.
"""
- from src.local_deep_research.database.sqlcipher_utils import (
+ from local_deep_research.database.sqlcipher_utils import (
get_sqlcipher_settings,
set_sqlcipher_key,
)
@@ -583,7 +583,7 @@ class TestOldToNewPragmaOrderMigration:
Verify password change (rekey) works on databases created with
OLD pragma order when using NEW pragma order code.
"""
- from src.local_deep_research.database.sqlcipher_utils import (
+ from local_deep_research.database.sqlcipher_utils import (
set_sqlcipher_rekey,
)
diff --git a/tests/auth_tests/test_sqlcipher_compatibility.py b/tests/auth_tests/test_sqlcipher_compatibility.py
index a95dda4920..a45b99c3e9 100644
--- a/tests/auth_tests/test_sqlcipher_compatibility.py
+++ b/tests/auth_tests/test_sqlcipher_compatibility.py
@@ -11,11 +11,11 @@ from pathlib import Path
import pytest
-from src.local_deep_research.database.encrypted_db import DatabaseManager
-from src.local_deep_research.database.sqlcipher_compat import (
+from local_deep_research.database.encrypted_db import DatabaseManager
+from local_deep_research.database.sqlcipher_compat import (
get_sqlcipher_module,
)
-from src.local_deep_research.database.sqlcipher_utils import (
+from local_deep_research.database.sqlcipher_utils import (
apply_cipher_defaults_before_key,
apply_sqlcipher_pragmas,
get_sqlcipher_settings,
@@ -59,11 +59,11 @@ def auth_user(temp_data_dir, monkeypatch):
"""Create a test user in auth database."""
monkeypatch.setenv("LDR_DATA_DIR", str(temp_data_dir))
- from src.local_deep_research.database.auth_db import (
+ from local_deep_research.database.auth_db import (
get_auth_db_session,
init_auth_database,
)
- from src.local_deep_research.database.models.auth import User
+ from local_deep_research.database.models.auth import User
init_auth_database()
auth_db = get_auth_db_session()
diff --git a/tests/auth_tests/test_sqlcipher_key_derivation.py b/tests/auth_tests/test_sqlcipher_key_derivation.py
index 3faf3021c9..243e807990 100644
--- a/tests/auth_tests/test_sqlcipher_key_derivation.py
+++ b/tests/auth_tests/test_sqlcipher_key_derivation.py
@@ -11,14 +11,14 @@ from pathlib import Path
import pytest
-from src.local_deep_research.database.sqlcipher_utils import (
+from local_deep_research.database.sqlcipher_utils import (
LEGACY_PBKDF2_SALT,
_get_key_from_password,
get_sqlcipher_settings,
set_sqlcipher_key,
set_sqlcipher_rekey,
)
-from src.local_deep_research.database.sqlcipher_compat import (
+from local_deep_research.database.sqlcipher_compat import (
get_sqlcipher_module,
)
@@ -155,7 +155,7 @@ class TestKeyDerivationWithDatabase:
def test_derived_key_opens_database(self, sqlcipher_module, temp_db_path):
"""Verify derived key can create and open a database."""
- from src.local_deep_research.database.sqlcipher_utils import (
+ from local_deep_research.database.sqlcipher_utils import (
apply_cipher_defaults_before_key,
)
@@ -175,7 +175,7 @@ class TestKeyDerivationWithDatabase:
conn.close()
# Reopen with same password
- from src.local_deep_research.database.sqlcipher_utils import (
+ from local_deep_research.database.sqlcipher_utils import (
apply_sqlcipher_pragmas,
)
@@ -192,7 +192,7 @@ class TestKeyDerivationWithDatabase:
def test_wrong_password_cannot_open(self, sqlcipher_module, temp_db_path):
"""Verify wrong password cannot open database."""
- from src.local_deep_research.database.sqlcipher_utils import (
+ from local_deep_research.database.sqlcipher_utils import (
apply_cipher_defaults_before_key,
)
@@ -209,7 +209,7 @@ class TestKeyDerivationWithDatabase:
conn.close()
# Try to open with password2
- from src.local_deep_research.database.sqlcipher_utils import (
+ from local_deep_research.database.sqlcipher_utils import (
apply_sqlcipher_pragmas,
)
@@ -228,7 +228,7 @@ class TestKeyDerivationWithDatabase:
def test_rekey_uses_same_derivation(self, sqlcipher_module, temp_db_path):
"""Verify rekey produces key compatible with set_sqlcipher_key."""
- from src.local_deep_research.database.sqlcipher_utils import (
+ from local_deep_research.database.sqlcipher_utils import (
apply_cipher_defaults_before_key,
)
@@ -249,7 +249,7 @@ class TestKeyDerivationWithDatabase:
conn.close()
# Open with new password using set_sqlcipher_key
- from src.local_deep_research.database.sqlcipher_utils import (
+ from local_deep_research.database.sqlcipher_utils import (
apply_sqlcipher_pragmas,
)
diff --git a/tests/auth_tests/test_sqlcipher_performance.py b/tests/auth_tests/test_sqlcipher_performance.py
index c73ca17297..6df23d92a8 100644
--- a/tests/auth_tests/test_sqlcipher_performance.py
+++ b/tests/auth_tests/test_sqlcipher_performance.py
@@ -11,13 +11,13 @@ from pathlib import Path
import pytest
-from src.local_deep_research.database.sqlcipher_utils import (
+from local_deep_research.database.sqlcipher_utils import (
apply_cipher_defaults_before_key,
apply_performance_pragmas,
apply_sqlcipher_pragmas,
set_sqlcipher_key,
)
-from src.local_deep_research.database.sqlcipher_compat import (
+from local_deep_research.database.sqlcipher_compat import (
get_sqlcipher_module,
)
diff --git a/tests/auth_tests/test_sqlcipher_rekey.py b/tests/auth_tests/test_sqlcipher_rekey.py
index b7cb776bba..02d6d61f13 100644
--- a/tests/auth_tests/test_sqlcipher_rekey.py
+++ b/tests/auth_tests/test_sqlcipher_rekey.py
@@ -12,7 +12,7 @@ from unittest.mock import Mock, patch
import pytest
-from src.local_deep_research.database.sqlcipher_utils import (
+from local_deep_research.database.sqlcipher_utils import (
LEGACY_PBKDF2_SALT,
apply_cipher_defaults_before_key,
apply_sqlcipher_pragmas,
@@ -21,7 +21,7 @@ from src.local_deep_research.database.sqlcipher_utils import (
set_sqlcipher_rekey,
_get_key_from_password,
)
-from src.local_deep_research.database.sqlcipher_compat import (
+from local_deep_research.database.sqlcipher_compat import (
get_sqlcipher_module,
)
@@ -249,13 +249,13 @@ class TestRekeyWithSQLAlchemy:
"""Verify rekey works through SQLAlchemy connection."""
from sqlalchemy import create_engine, event, text
- from src.local_deep_research.database.sqlcipher_utils import (
+ from local_deep_research.database.sqlcipher_utils import (
apply_cipher_defaults_before_key,
apply_sqlcipher_pragmas,
set_sqlcipher_key,
set_sqlcipher_rekey,
)
- from src.local_deep_research.database.sqlcipher_compat import (
+ from local_deep_research.database.sqlcipher_compat import (
get_sqlcipher_module,
)
@@ -322,7 +322,7 @@ class TestSetSqlcipherRekey:
mock_conn.execute.side_effect = [TypeError("not sqlalchemy"), None]
with patch(
- "src.local_deep_research.database.sqlcipher_utils.get_key_from_password",
+ "local_deep_research.database.sqlcipher_utils.get_key_from_password",
return_value=b"\xab\xcd\xef",
) as mock_get_key:
set_sqlcipher_rekey(mock_conn, "new_password")
@@ -334,7 +334,7 @@ class TestSetSqlcipherRekey:
mock_conn.execute.side_effect = [TypeError("not sqlalchemy"), None]
with patch(
- "src.local_deep_research.database.sqlcipher_utils.get_key_from_password",
+ "local_deep_research.database.sqlcipher_utils.get_key_from_password",
return_value=b"\xab\xcd\xef",
):
set_sqlcipher_rekey(mock_conn, "test_password")
@@ -352,7 +352,7 @@ class TestSetSqlcipherRekey:
mock_conn = Mock()
with patch(
- "src.local_deep_research.database.sqlcipher_utils.get_key_from_password",
+ "local_deep_research.database.sqlcipher_utils.get_key_from_password",
return_value=b"\xab\xcd\xef",
):
set_sqlcipher_rekey(mock_conn, "new_password")
diff --git a/tests/auth_tests/test_sqlcipher_settings.py b/tests/auth_tests/test_sqlcipher_settings.py
index 6c9a8c5128..0f146cd0e7 100644
--- a/tests/auth_tests/test_sqlcipher_settings.py
+++ b/tests/auth_tests/test_sqlcipher_settings.py
@@ -11,7 +11,7 @@ from pathlib import Path
import pytest
-from src.local_deep_research.database.sqlcipher_utils import (
+from local_deep_research.database.sqlcipher_utils import (
DEFAULT_KDF_ITERATIONS,
DEFAULT_PAGE_SIZE,
DEFAULT_HMAC_ALGORITHM,
@@ -21,7 +21,7 @@ from src.local_deep_research.database.sqlcipher_utils import (
apply_performance_pragmas,
set_sqlcipher_key,
)
-from src.local_deep_research.database.sqlcipher_compat import (
+from local_deep_research.database.sqlcipher_compat import (
get_sqlcipher_module,
)
diff --git a/tests/auth_tests/test_sqlcipher_threads.py b/tests/auth_tests/test_sqlcipher_threads.py
index 437325ed0a..8dce3faab8 100644
--- a/tests/auth_tests/test_sqlcipher_threads.py
+++ b/tests/auth_tests/test_sqlcipher_threads.py
@@ -14,13 +14,13 @@ from pathlib import Path
import pytest
-from src.local_deep_research.database.sqlcipher_utils import (
+from local_deep_research.database.sqlcipher_utils import (
apply_cipher_defaults_before_key,
apply_performance_pragmas,
apply_sqlcipher_pragmas,
set_sqlcipher_key,
)
-from src.local_deep_research.database.sqlcipher_compat import (
+from local_deep_research.database.sqlcipher_compat import (
get_sqlcipher_module,
)
diff --git a/tests/chat/conftest.py b/tests/chat/conftest.py
index de2c2f905f..5d07f58980 100644
--- a/tests/chat/conftest.py
+++ b/tests/chat/conftest.py
@@ -35,16 +35,16 @@ from local_deep_research.database.session_context import (
get_user_db_session as _REAL_GET_USER_DB_SESSION,
)
-# ``chat.routes`` is importable as BOTH of these under the CI import layout
-# (``src`` on PYTHONPATH + the repo root on sys.path); each resolves to a
-# DISTINCT module object with its own ``ChatService`` attribute. The running
-# app registers the non-``src`` blueprint, but the heal fixture rebinds every
-# alias that is loaded so a poisoner targeting either object cannot bleed into
-# a later chat test.
-_CHAT_ROUTES_ALIASES = (
- "local_deep_research.chat.routes",
- "src.local_deep_research.chat.routes",
-)
+# ``chat.routes`` binds process-global names (``ChatService``,
+# ``SettingsManager``, ``get_user_db_session``, ``_load_settings``) that a mock
+# leaked by an earlier test can poison. Tests import it under exactly one
+# canonical name: the ``src.local_deep_research`` alias is banned in tests (see
+# ``.pre-commit-hooks/check-no-src-test-imports.py``) precisely because
+# importing a module under both names loads two distinct copies and breaks
+# process-global singletons -- so ``chat.routes`` now resolves to a single
+# module object and the heal fixture only needs to rebind that one. Kept as a
+# tuple so the heal loop stays uniform if another canonical alias is ever added.
+_CHAT_ROUTES_ALIASES = ("local_deep_research.chat.routes",)
def _capture_real_load_settings():
@@ -111,16 +111,17 @@ def _restore_chat_routes_service():
``send_message`` commits ``UserActiveResearch(..., settings_snapshot=...)``
(#5549), turning an expected 200/429 into a generic 500.
- Two subtleties this heals that a single-module rebind missed:
+ A subtlety this heals that a naive re-read missed:
- * **Module duplication.** ``chat.routes`` is loaded under two distinct
- module objects (see ``_CHAT_ROUTES_ALIASES``), each with its own
- attributes. Rebind whichever aliases are loaded.
* **A poisoned source module.** Re-reading ``ChatService`` /
``SettingsManager`` / ``get_user_db_session`` at heal time would re-bind a
*leaked mock* if that module is the one poisoned. Rebind the genuine
objects captured at import time (``_REAL_CHAT_SERVICE`` et al.) instead.
+ (``chat.routes`` resolves to a single canonical module object now -- the
+ ``src.`` alias that used to create a second copy is banned in tests, see
+ ``_CHAT_ROUTES_ALIASES`` -- so the heal rebinds that one object.)
+
Rebinding before AND after each test heals any leak inflicted by an earlier
test (pre-yield) and prevents this test from leaking to the next
(post-yield). Tests that establish their own ``with patch(...)`` inside the
@@ -200,7 +201,7 @@ def mock_user_db_session():
yield session_mock
with patch(
- "src.local_deep_research.chat.service.get_user_db_session",
+ "local_deep_research.chat.service.get_user_db_session",
side_effect=_mock_session,
):
yield session_mock
@@ -209,7 +210,7 @@ def mock_user_db_session():
@pytest.fixture
def chat_service(setup_database_for_all_tests):
"""Provide ChatService with test database."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
return ChatService(username="test_user")
diff --git a/tests/chat/test_chat_accumulated_context.py b/tests/chat/test_chat_accumulated_context.py
index e95d2e8062..d8a11e84d0 100644
--- a/tests/chat/test_chat_accumulated_context.py
+++ b/tests/chat/test_chat_accumulated_context.py
@@ -36,7 +36,7 @@ class TestAccumulatedContextStructure:
def test_context_structure_from_manager(self):
"""Test context structure created by ChatContextManager."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
messages = [
{"role": "user", "content": "Test query", "message_type": "query"}
@@ -59,7 +59,7 @@ class TestAccumulatedContextStructure:
def test_context_limits_entities(self):
"""Test that entities are limited to 20."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
# Create more than 20 entities
many_entities = [f"entity{i}" for i in range(30)]
@@ -72,7 +72,7 @@ class TestAccumulatedContextStructure:
def test_context_limits_topics(self):
"""Test that topics are limited to 10."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
# Create more than 10 topics
many_topics = [f"topic{i}" for i in range(15)]
@@ -89,7 +89,7 @@ class TestContextMerging:
def test_merge_entities_deduplicates(self):
"""Test that merging entities removes duplicates."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
accumulated = {"key_entities": ["entity1", "entity2"]}
manager = ChatContextManager("test-session", [], accumulated)
@@ -107,7 +107,7 @@ class TestContextSummary:
def test_summary_created_from_content(self):
"""Test that summaries are created from content."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
manager = ChatContextManager("test-session", [], {})
@@ -125,7 +125,7 @@ Third paragraph with more details."""
def test_summary_skips_headers(self):
"""Test that summary skips markdown headers."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
manager = ChatContextManager("test-session", [], {})
@@ -144,7 +144,7 @@ More content here."""
def test_summary_handles_short_paragraphs(self):
"""Test that summary handles content with short paragraphs."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
manager = ChatContextManager("test-session", [], {})
@@ -236,7 +236,7 @@ class TestEdgeCases:
def test_empty_accumulated_context_handled(self):
"""Test handling of None/empty accumulated context."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
manager1 = ChatContextManager("test", [], None)
manager2 = ChatContextManager("test", [], {})
@@ -250,7 +250,7 @@ class TestEdgeCases:
def test_special_characters_in_context(self):
"""Test handling of special characters in context."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
accumulated = {
"key_entities": ["<script>", "O'Reilly", '"quotes"'],
@@ -267,7 +267,7 @@ class TestEdgeCases:
def test_unicode_in_context(self):
"""Test handling of unicode in context."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
messages = [
{"role": "user", "content": "你好世界", "message_type": "query"},
diff --git a/tests/chat/test_chat_add_progress_step.py b/tests/chat/test_chat_add_progress_step.py
index 15740f36a6..8f0f4e697c 100644
--- a/tests/chat/test_chat_add_progress_step.py
+++ b/tests/chat/test_chat_add_progress_step.py
@@ -23,8 +23,8 @@ import uuid
import pytest
-from src.local_deep_research.chat.service import ChatService
-from src.local_deep_research.database.models import (
+from local_deep_research.chat.service import ChatService
+from local_deep_research.database.models import (
ChatProgressStep,
ChatSession,
ChatSessionStatus,
@@ -71,7 +71,7 @@ def _patch_user_db(monkeypatch, SessionLocal):
db.close()
monkeypatch.setattr(
- "src.local_deep_research.chat.service.get_user_db_session", _ctx
+ "local_deep_research.chat.service.get_user_db_session", _ctx
)
diff --git a/tests/chat/test_chat_archive_atomic_guard.py b/tests/chat/test_chat_archive_atomic_guard.py
index b7fd636530..d3812264cf 100644
--- a/tests/chat/test_chat_archive_atomic_guard.py
+++ b/tests/chat/test_chat_archive_atomic_guard.py
@@ -24,8 +24,8 @@ import uuid
import pytest
-from src.local_deep_research.chat.service import ChatService
-from src.local_deep_research.database.models import (
+from local_deep_research.chat.service import ChatService
+from local_deep_research.database.models import (
ChatMessage,
ChatSession,
ChatSessionStatus,
diff --git a/tests/chat/test_chat_archive_blocked_in_progress.py b/tests/chat/test_chat_archive_blocked_in_progress.py
index 1c31cbbf69..fff1630b49 100644
--- a/tests/chat/test_chat_archive_blocked_in_progress.py
+++ b/tests/chat/test_chat_archive_blocked_in_progress.py
@@ -22,12 +22,12 @@ from unittest.mock import patch
import pytest
-from src.local_deep_research.chat.service import (
+from local_deep_research.chat.service import (
ArchiveBlockedError,
ChatService,
)
-from src.local_deep_research.constants import ResearchStatus
-from src.local_deep_research.database.models import (
+from local_deep_research.constants import ResearchStatus
+from local_deep_research.database.models import (
ChatSession,
ChatSessionStatus,
ResearchHistory,
@@ -69,7 +69,7 @@ def _run_archive(SessionLocal, service, session_id):
yield db
with patch(
- "src.local_deep_research.chat.service.get_user_db_session",
+ "local_deep_research.chat.service.get_user_db_session",
side_effect=lambda *_args, **_kwargs: _managed_test_session(),
):
return service.archive_session(session_id)
diff --git a/tests/chat/test_chat_attempt_delete_retry.py b/tests/chat/test_chat_attempt_delete_retry.py
index 75b7f32154..add7aa511b 100644
--- a/tests/chat/test_chat_attempt_delete_retry.py
+++ b/tests/chat/test_chat_attempt_delete_retry.py
@@ -28,13 +28,13 @@ from unittest.mock import patch
import pytest
-from src.local_deep_research.chat.service import (
+from local_deep_research.chat.service import (
AttemptInProgress,
AttemptNotFound,
ChatService,
)
-from src.local_deep_research.constants import ResearchStatus
-from src.local_deep_research.database.models import (
+from local_deep_research.constants import ResearchStatus
+from local_deep_research.database.models import (
ChatMessage,
ChatProgressStep,
ChatRole,
@@ -64,7 +64,7 @@ def _service_db(SessionLocal):
yield db
with patch(
- "src.local_deep_research.chat.service.get_user_db_session",
+ "local_deep_research.chat.service.get_user_db_session",
side_effect=lambda *_args, **_kwargs: _managed_test_session(),
):
yield
@@ -386,11 +386,11 @@ class TestDeleteAttemptService:
flagged = []
with (
patch(
- "src.local_deep_research.chat.service.set_termination_flag",
+ "local_deep_research.chat.service.set_termination_flag",
side_effect=lambda rid: flagged.append(rid),
),
patch(
- "src.local_deep_research.chat.service.is_research_thread_alive",
+ "local_deep_research.chat.service.is_research_thread_alive",
return_value=True,
),
_service_db(SessionLocal),
@@ -431,7 +431,7 @@ class TestDeleteAttemptService:
# is_research_thread_alive returns False → sweep reclaims.
with (
patch(
- "src.local_deep_research.chat.service.is_research_thread_alive",
+ "local_deep_research.chat.service.is_research_thread_alive",
return_value=False,
),
_service_db(SessionLocal),
diff --git a/tests/chat/test_chat_boundaries.py b/tests/chat/test_chat_boundaries.py
index 10c33b2d03..26efc2d6b2 100644
--- a/tests/chat/test_chat_boundaries.py
+++ b/tests/chat/test_chat_boundaries.py
@@ -13,7 +13,7 @@ class TestMessageBoundaries:
def test_message_with_empty_content_accepted(self):
"""Test that empty message content is accepted."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
mock_session_obj = MagicMock()
mock_session_obj.id = "test-session"
@@ -35,7 +35,7 @@ class TestMessageBoundaries:
yield mock_session
with patch(
- "src.local_deep_research.chat.service.get_user_db_session",
+ "local_deep_research.chat.service.get_user_db_session",
mock_get_user_db_session,
):
service = ChatService(username="testuser")
@@ -54,7 +54,7 @@ class TestMessageBoundaries:
"""chat_messages.content is NOT NULL.
add_message must reject content=None at the application layer."""
import pytest
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
service = ChatService(username="testuser")
with pytest.raises(ValueError, match="content is required"):
@@ -72,7 +72,7 @@ class TestContextBoundaries:
def test_accumulated_context_entities_limited_to_50(self):
"""Test that key_entities are limited to 50 items."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
mock_session_obj = MagicMock()
mock_session_obj.id = "test-session"
@@ -91,7 +91,7 @@ class TestContextBoundaries:
yield mock_session
with patch(
- "src.local_deep_research.chat.service.get_user_db_session",
+ "local_deep_research.chat.service.get_user_db_session",
mock_get_user_db_session,
):
service = ChatService(username="testuser")
@@ -107,7 +107,7 @@ class TestContextBoundaries:
def test_accumulated_context_topics_limited_to_20(self):
"""Test that topics are limited to 20 items."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
mock_session_obj = MagicMock()
mock_session_obj.id = "test-session"
@@ -126,7 +126,7 @@ class TestContextBoundaries:
yield mock_session
with patch(
- "src.local_deep_research.chat.service.get_user_db_session",
+ "local_deep_research.chat.service.get_user_db_session",
mock_get_user_db_session,
):
service = ChatService(username="testuser")
@@ -142,7 +142,7 @@ class TestContextBoundaries:
def test_accumulated_summary_truncated_to_8000_chars(self):
"""Test that summary is truncated to 8000 characters."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
mock_session_obj = MagicMock()
mock_session_obj.id = "test-session"
@@ -161,7 +161,7 @@ class TestContextBoundaries:
yield mock_session
with patch(
- "src.local_deep_research.chat.service.get_user_db_session",
+ "local_deep_research.chat.service.get_user_db_session",
mock_get_user_db_session,
):
service = ChatService(username="testuser")
@@ -181,7 +181,7 @@ class TestSessionBoundaries:
def test_session_title_at_max_100_chars(self):
"""Test that title from query is limited to 100 chars + ellipsis."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
added_sessions = []
@@ -197,7 +197,7 @@ class TestSessionBoundaries:
yield mock_session
with patch(
- "src.local_deep_research.chat.service.get_user_db_session",
+ "local_deep_research.chat.service.get_user_db_session",
mock_get_user_db_session,
):
service = ChatService(username="testuser")
@@ -216,7 +216,7 @@ class TestSessionBoundaries:
def test_session_title_exactly_100_chars_no_ellipsis(self):
"""Test that 100-char query doesn't get ellipsis."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
added_sessions = []
@@ -232,7 +232,7 @@ class TestSessionBoundaries:
yield mock_session
with patch(
- "src.local_deep_research.chat.service.get_user_db_session",
+ "local_deep_research.chat.service.get_user_db_session",
mock_get_user_db_session,
):
service = ChatService(username="testuser")
@@ -251,7 +251,7 @@ class TestContextManagerBoundaries:
def test_findings_limited_to_5(self):
"""Test that findings are limited to MAX_FINDINGS_TO_INCLUDE (5)."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
# Create 10 assistant messages with research_id
messages = [
@@ -280,7 +280,7 @@ class TestContextManagerBoundaries:
def test_create_summary_truncates_long_paragraphs_to_300(self):
"""Test that _create_summary truncates paragraphs to 300 chars."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
long_paragraph = "Z" * 500
@@ -302,7 +302,7 @@ class TestEdgeCases:
def test_entity_deduplication(self):
"""Test that duplicate entities are deduplicated."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
mock_session_obj = MagicMock()
mock_session_obj.id = "test-session"
@@ -321,7 +321,7 @@ class TestEdgeCases:
yield mock_session
with patch(
- "src.local_deep_research.chat.service.get_user_db_session",
+ "local_deep_research.chat.service.get_user_db_session",
mock_get_user_db_session,
):
service = ChatService(username="testuser")
diff --git a/tests/chat/test_chat_concurrency.py b/tests/chat/test_chat_concurrency.py
index dfd1621e61..d0b0a972ab 100644
--- a/tests/chat/test_chat_concurrency.py
+++ b/tests/chat/test_chat_concurrency.py
@@ -19,7 +19,7 @@ class TestChatConcurrency:
def test_concurrent_session_creation_unique_ids(self):
"""Test that concurrent session creation generates unique IDs."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
created_ids = []
lock = threading.Lock()
@@ -43,7 +43,7 @@ class TestChatConcurrency:
# Apply patch at test level (outside threads) to avoid race conditions
# during patch application/removal across threads
with patch(
- "src.local_deep_research.chat.service.get_user_db_session",
+ "local_deep_research.chat.service.get_user_db_session",
mock_get_user_db_session,
):
# Create sessions concurrently
@@ -65,7 +65,7 @@ class TestChatConcurrency:
def test_multiple_sessions_same_user_isolated(self):
"""Test that multiple sessions for the same user are independent."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
sessions_created = []
lock = threading.Lock()
@@ -106,7 +106,7 @@ class TestChatConcurrency:
# Patch at module level before spawning threads
with patch(
- "src.local_deep_research.chat.service.get_user_db_session",
+ "local_deep_research.chat.service.get_user_db_session",
mock_get_user_db_session,
):
# Create multiple sessions concurrently
@@ -125,7 +125,7 @@ class TestChatConcurrency:
def test_concurrent_reads_during_write_consistent(self):
"""Test that reads during writes return consistent data."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
# Shared state for the mock
mock_sessions = {}
@@ -192,7 +192,7 @@ class TestChatConcurrency:
# Apply patch at test level (outside threads) to avoid race conditions
with patch(
- "src.local_deep_research.chat.service.get_user_db_session",
+ "local_deep_research.chat.service.get_user_db_session",
mock_get_user_db_session,
):
# Now do concurrent reads
@@ -208,7 +208,7 @@ class TestChatConcurrency:
def test_rapid_message_sends_no_data_loss(self):
"""Test that rapidly sending messages doesn't lose any messages."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
messages_added = []
lock = threading.Lock()
@@ -243,7 +243,7 @@ class TestChatConcurrency:
# Patch at module level before spawning threads
with patch(
- "src.local_deep_research.chat.service.get_user_db_session",
+ "local_deep_research.chat.service.get_user_db_session",
mock_get_user_db_session,
):
# Send many messages rapidly
@@ -266,7 +266,7 @@ class TestChatConcurrency:
def test_concurrent_context_updates_preserve_data(self):
"""Test that concurrent context updates don't lose entities."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
# The implementation uses with_for_update() for row-level locking
# to ensure atomic read-modify-write operations
@@ -320,7 +320,7 @@ class TestChatConcurrency:
# Apply patch at test level (outside threads) to avoid race conditions
with patch(
- "src.local_deep_research.chat.service.get_user_db_session",
+ "local_deep_research.chat.service.get_user_db_session",
mock_get_user_db_session,
):
with ThreadPoolExecutor(max_workers=num_updates) as executor:
@@ -341,7 +341,7 @@ class TestChatConcurrency:
def test_thread_local_services_independent(self):
"""Test that ChatService instances in different threads are independent."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
service_ids = []
lock = threading.Lock()
@@ -385,7 +385,7 @@ class TestAddMessageSequenceRace:
from datetime import datetime, UTC
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker
- from src.local_deep_research.database.models import (
+ from local_deep_research.database.models import (
Base,
ChatSession,
)
@@ -425,8 +425,8 @@ class TestAddMessageSequenceRace:
constraint fires.
"""
from contextlib import contextmanager
- from src.local_deep_research.chat.service import ChatService
- from src.local_deep_research.database.models import ChatMessage
+ from local_deep_research.chat.service import ChatService
+ from local_deep_research.database.models import ChatMessage
engine, Session, session_id = self._setup_real_db(tmp_path)
@@ -455,7 +455,7 @@ class TestAddMessageSequenceRace:
return None
with patch(
- "src.local_deep_research.chat.service.get_user_db_session",
+ "local_deep_research.chat.service.get_user_db_session",
real_get_user_db_session,
):
with ThreadPoolExecutor(max_workers=num_messages) as executor:
diff --git a/tests/chat/test_chat_context_advanced.py b/tests/chat/test_chat_context_advanced.py
index 01a7795aa5..051ae01659 100644
--- a/tests/chat/test_chat_context_advanced.py
+++ b/tests/chat/test_chat_context_advanced.py
@@ -4,7 +4,7 @@ Advanced tests for ChatContextManager.
Tests context window limits, summarization, and context building.
"""
-from src.local_deep_research.chat.context import ChatContextManager
+from local_deep_research.chat.context import ChatContextManager
class TestContextBuilding:
diff --git a/tests/chat/test_chat_context_manager.py b/tests/chat/test_chat_context_manager.py
index df693d6450..28a776ef53 100644
--- a/tests/chat/test_chat_context_manager.py
+++ b/tests/chat/test_chat_context_manager.py
@@ -8,7 +8,7 @@ class TestChatContextManagerBuildResearchContext:
self, sample_messages, sample_accumulated_context
):
"""Test that build_research_context returns all required keys."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
manager = ChatContextManager(
session_id="session-123",
@@ -36,7 +36,7 @@ class TestChatContextManagerBuildResearchContext:
self, sample_accumulated_context
):
"""Test that is_multi_turn is False when no previous messages."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
manager = ChatContextManager(
session_id="session-123",
@@ -51,7 +51,7 @@ class TestChatContextManagerBuildResearchContext:
self, sample_messages, sample_accumulated_context
):
"""Test that is_multi_turn is True when previous messages exist."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
manager = ChatContextManager(
session_id="session-123",
@@ -66,7 +66,7 @@ class TestChatContextManagerBuildResearchContext:
self, sample_messages, sample_accumulated_context
):
"""Test that turn_count is included in the context."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
manager = ChatContextManager(
session_id="session-123",
@@ -81,7 +81,7 @@ class TestChatContextManagerBuildResearchContext:
self, sample_messages, sample_accumulated_context
):
"""Test that session_id is included in the context."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
manager = ChatContextManager(
session_id="test-session-abc",
@@ -100,7 +100,7 @@ class TestChatContextManagerExtraction:
self, sample_messages, sample_accumulated_context
):
"""Test that only assistant messages with research_id are extracted."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
manager = ChatContextManager(
session_id="session-123",
@@ -124,7 +124,7 @@ class TestChatContextManagerExtraction:
self, many_messages, sample_accumulated_context
):
"""Test that findings are limited to 5 most recent."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
manager = ChatContextManager(
session_id="session-123",
@@ -148,7 +148,7 @@ class TestChatContextManagerCreateSummary:
def test_create_summary_finds_first_paragraph(self):
"""Test that _create_summary finds the first substantial paragraph."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
content = """# Heading
@@ -170,7 +170,7 @@ This is the second paragraph."""
def test_create_summary_skips_headers(self):
"""Test that _create_summary skips markdown headers when substantial content follows."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
# Content with a substantial paragraph (>50 chars) after headers
content = """# Main Heading
@@ -193,7 +193,7 @@ This is the actual content paragraph with more than fifty characters of meaningf
def test_create_summary_truncates_long_content(self):
"""Test that _create_summary truncates long paragraphs to 300 chars."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
long_paragraph = "X" * 500
@@ -214,7 +214,7 @@ class TestChatContextManagerExtractContextUpdates:
def test_extract_context_updates_returns_required_keys(self):
"""Test that extract_context_updates returns all required keys."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
manager = ChatContextManager(
session_id="session-123",
@@ -238,7 +238,7 @@ class TestChatContextManagerKeyEntitiesAndTopics:
self, sample_messages, sample_accumulated_context
):
"""Test that key entities are retrieved from accumulated context."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
manager = ChatContextManager(
session_id="session-123",
@@ -256,7 +256,7 @@ class TestChatContextManagerKeyEntitiesAndTopics:
self, sample_messages, sample_accumulated_context
):
"""Test that topics are retrieved from accumulated context."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
manager = ChatContextManager(
session_id="session-123",
@@ -291,14 +291,14 @@ class TestBuildResearchContextFocusedSummary:
def test_focused_summary_used_as_past_findings(self, mocker):
"""With a query + snapshot, past_findings is the focused LLM summary."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
fake_llm = mocker.Mock()
fake_llm.invoke.return_value = mocker.Mock(
content="Prior work, focused on cost."
)
get_llm = mocker.patch(
- "src.local_deep_research.config.llm_config.get_llm",
+ "local_deep_research.config.llm_config.get_llm",
return_value=fake_llm,
)
@@ -323,11 +323,9 @@ class TestBuildResearchContextFocusedSummary:
def test_no_current_query_uses_raw_findings(self, mocker):
"""A no-arg call (no focus question) makes no LLM call."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
- get_llm = mocker.patch(
- "src.local_deep_research.config.llm_config.get_llm"
- )
+ get_llm = mocker.patch("local_deep_research.config.llm_config.get_llm")
manager = ChatContextManager(
session_id="s1",
messages=self._conversation(),
@@ -359,7 +357,7 @@ class TestFollowupContextModes:
]
def _manager(self, mode):
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
return ChatContextManager(
session_id="s1",
@@ -369,9 +367,7 @@ class TestFollowupContextModes:
)
def test_raw_mode_uses_recent_findings_no_llm(self, mocker):
- get_llm = mocker.patch(
- "src.local_deep_research.config.llm_config.get_llm"
- )
+ get_llm = mocker.patch("local_deep_research.config.llm_config.get_llm")
result = self._manager("raw").build_research_context(
current_query="cost?"
)
@@ -380,9 +376,7 @@ class TestFollowupContextModes:
assert "qubits" in result["past_findings"].lower()
def test_full_mode_sends_whole_transcript_no_llm(self, mocker):
- get_llm = mocker.patch(
- "src.local_deep_research.config.llm_config.get_llm"
- )
+ get_llm = mocker.patch("local_deep_research.config.llm_config.get_llm")
result = self._manager("full").build_research_context(
current_query="cost?"
)
@@ -393,9 +387,7 @@ class TestFollowupContextModes:
assert "What is quantum computing?" in past
def test_none_mode_sends_no_prior_findings_no_llm(self, mocker):
- get_llm = mocker.patch(
- "src.local_deep_research.config.llm_config.get_llm"
- )
+ get_llm = mocker.patch("local_deep_research.config.llm_config.get_llm")
result = self._manager("none").build_research_context(
current_query="cost?"
)
@@ -407,7 +399,7 @@ class TestFollowupContextModes:
fake_llm = mocker.Mock()
fake_llm.invoke.return_value = mocker.Mock(content="Focused summary.")
mocker.patch(
- "src.local_deep_research.config.llm_config.get_llm",
+ "local_deep_research.config.llm_config.get_llm",
return_value=fake_llm,
)
result = self._manager("summary").build_research_context(
@@ -421,7 +413,7 @@ class TestFollowupContextModes:
"""A get_llm() failure (e.g. misconfigured provider) degrades the
summary to empty rather than crashing the follow-up request."""
mocker.patch(
- "src.local_deep_research.config.llm_config.get_llm",
+ "local_deep_research.config.llm_config.get_llm",
side_effect=RuntimeError("no provider configured"),
)
result = self._manager("summary").build_research_context(
diff --git a/tests/chat/test_chat_delete_terminates_research.py b/tests/chat/test_chat_delete_terminates_research.py
index d2d687b35f..ff22a43bd4 100644
--- a/tests/chat/test_chat_delete_terminates_research.py
+++ b/tests/chat/test_chat_delete_terminates_research.py
@@ -27,9 +27,9 @@ import uuid
from contextlib import contextmanager
from unittest.mock import patch
-from src.local_deep_research.chat.service import ChatService
-from src.local_deep_research.constants import ResearchStatus
-from src.local_deep_research.database.models import (
+from local_deep_research.chat.service import ChatService
+from local_deep_research.constants import ResearchStatus
+from local_deep_research.database.models import (
ChatSession,
ChatSessionStatus,
ResearchHistory,
@@ -72,7 +72,7 @@ def _patched_service_db(SessionLocal):
yield db
with patch(
- "src.local_deep_research.chat.service.get_user_db_session",
+ "local_deep_research.chat.service.get_user_db_session",
side_effect=lambda *_args, **_kwargs: _managed_test_session(),
):
yield
@@ -104,7 +104,7 @@ def test_delete_session_flags_in_progress_research_for_termination(
# delete_session once the import has captured the reference.
with (
patch(
- "src.local_deep_research.chat.service.set_termination_flag",
+ "local_deep_research.chat.service.set_termination_flag",
side_effect=_capture,
),
_patched_service_db(SessionLocal),
@@ -136,7 +136,7 @@ def test_delete_session_skips_completed_research(setup_database_for_all_tests):
with (
patch(
- "src.local_deep_research.chat.service.set_termination_flag",
+ "local_deep_research.chat.service.set_termination_flag",
side_effect=lambda rid: flagged.append(rid),
),
_patched_service_db(SessionLocal),
@@ -160,7 +160,7 @@ def test_delete_session_returns_false_for_missing_session(
flagged = []
with (
patch(
- "src.local_deep_research.chat.service.set_termination_flag",
+ "local_deep_research.chat.service.set_termination_flag",
side_effect=lambda rid: flagged.append(rid),
),
_patched_service_db(SessionLocal),
diff --git a/tests/chat/test_chat_followup_context_logging.py b/tests/chat/test_chat_followup_context_logging.py
index 530630a6b2..0edccbe8c0 100644
--- a/tests/chat/test_chat_followup_context_logging.py
+++ b/tests/chat/test_chat_followup_context_logging.py
@@ -4,9 +4,9 @@ The summary path is otherwise silent (no token-counter entry), so a follow-up
looked like an unexplained pause. One info line per follow-up records what ran.
"""
-from src.local_deep_research.chat.context import ChatContextManager
+from local_deep_research.chat.context import ChatContextManager
-_LOGGER = "src.local_deep_research.chat.context.logger"
+_LOGGER = "local_deep_research.chat.context.logger"
def _conversation():
diff --git a/tests/chat/test_chat_fuzz.py b/tests/chat/test_chat_fuzz.py
index 1b2f88574d..a3fee66a08 100644
--- a/tests/chat/test_chat_fuzz.py
+++ b/tests/chat/test_chat_fuzz.py
@@ -88,7 +88,7 @@ class TestChatContextManagerFuzz:
self, messages, accumulated
):
"""Test that build_research_context never crashes on arbitrary input."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
try:
manager = ChatContextManager(
@@ -112,7 +112,7 @@ class TestChatContextManagerFuzz:
@settings(max_examples=50, suppress_health_check=[HealthCheck.too_slow])
def test_accumulated_context_handles_arbitrary_data(self, accumulated):
"""Test that accumulated context with arbitrary data is handled."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
try:
manager = ChatContextManager(
@@ -138,7 +138,7 @@ class TestChatContextManagerFuzz:
@settings(max_examples=50, suppress_health_check=[HealthCheck.too_slow])
def test_create_summary_handles_arbitrary_content(self, content):
"""Test that summary creation handles arbitrary content."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
try:
manager = ChatContextManager("test-session", [], {})
@@ -156,7 +156,7 @@ class TestChatContextManagerFuzz:
@settings(max_examples=30, suppress_health_check=[HealthCheck.too_slow])
def test_extract_context_updates_handles_arbitrary_input(self, content):
"""Test that context update extraction handles arbitrary input."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
try:
manager = ChatContextManager("test-session", [], {})
@@ -186,7 +186,7 @@ class TestChatServiceFuzz:
@settings(max_examples=50, suppress_health_check=[HealthCheck.too_slow])
def test_title_generation_handles_any_string(self, query):
"""Test that title generation handles any input string."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
try:
service = ChatService(username="test_user")
@@ -208,7 +208,7 @@ class TestChatServiceFuzz:
@settings(max_examples=30, suppress_health_check=[HealthCheck.too_slow])
def test_add_message_handles_unicode(self, content, role, message_type):
"""Test that add_message handles various Unicode content."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
# Skip empty content for valid messages
assume(len(content.strip()) > 0)
@@ -226,7 +226,7 @@ class TestChatServiceFuzz:
yield mock_session
with patch(
- "src.local_deep_research.chat.service.get_user_db_session",
+ "local_deep_research.chat.service.get_user_db_session",
mock_get_user_db_session,
):
try:
@@ -422,7 +422,7 @@ class TestPromptContextFuzz:
@settings(max_examples=20, suppress_health_check=[HealthCheck.too_slow])
def test_findings_extraction_handles_many_messages(self, messages):
"""Test that findings extraction handles many messages."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
try:
manager = ChatContextManager("test-session", messages, {})
@@ -445,7 +445,7 @@ class TestEdgeCases:
def test_empty_messages_list(self):
"""Test handling of empty messages list."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
manager = ChatContextManager("test-session", [], {})
context = manager.build_research_context()
@@ -455,7 +455,7 @@ class TestEdgeCases:
def test_none_messages_list(self):
"""Test handling of None messages."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
manager = ChatContextManager("test-session", None, {})
context = manager.build_research_context()
@@ -464,7 +464,7 @@ class TestEdgeCases:
def test_none_accumulated_context(self):
"""Test handling of None accumulated context."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
manager = ChatContextManager("test-session", [], None)
entities = manager._get_key_entities()
@@ -475,7 +475,7 @@ class TestEdgeCases:
def test_very_long_content_truncation(self):
"""Test that very long content is properly truncated."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
# Create message with very long content
long_content = "A" * 10000
@@ -497,7 +497,7 @@ class TestEdgeCases:
def test_special_characters_in_entities(self):
"""Test handling of special characters in entities."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
accumulated = {
"key_entities": [
diff --git a/tests/chat/test_chat_research_history_integration.py b/tests/chat/test_chat_research_history_integration.py
index f9b1304c02..832eab90db 100644
--- a/tests/chat/test_chat_research_history_integration.py
+++ b/tests/chat/test_chat_research_history_integration.py
@@ -18,7 +18,7 @@ class TestResearchHistoryLinking:
def test_message_stores_research_id(self):
"""Test that message with research correctly stores research_id."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
mock_session = MagicMock()
captured_message = None
@@ -43,7 +43,7 @@ class TestResearchHistoryLinking:
yield mock_session
with patch(
- "src.local_deep_research.chat.service.get_user_db_session",
+ "local_deep_research.chat.service.get_user_db_session",
mock_get_user_db_session,
):
service = ChatService(username="test_user")
@@ -62,7 +62,7 @@ class TestResearchHistoryLinking:
def test_message_with_research_id_increments_message_count(self):
"""Test that session message count is incremented when research_id is set."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
from tests.chat.conftest import setup_query_mock_with_session
mock_session = MagicMock()
@@ -79,7 +79,7 @@ class TestResearchHistoryLinking:
yield mock_session
with patch(
- "src.local_deep_research.chat.service.get_user_db_session",
+ "local_deep_research.chat.service.get_user_db_session",
mock_get_user_db_session,
):
service = ChatService(username="test_user")
diff --git a/tests/chat/test_chat_research_integration.py b/tests/chat/test_chat_research_integration.py
index 7224f01f33..b098ba1ea9 100644
--- a/tests/chat/test_chat_research_integration.py
+++ b/tests/chat/test_chat_research_integration.py
@@ -9,7 +9,7 @@ class TestResearchIntegration:
def test_research_context_built_from_conversation_history(self):
"""Test that research context reflects the conversation turns."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
messages = [
{
@@ -56,7 +56,7 @@ class TestResearchIntegration:
def test_context_includes_previous_research_findings(self):
"""Test that context includes findings from previous research."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
messages = [
{
@@ -90,7 +90,7 @@ class TestResearchIntegration:
def test_multi_turn_flag_correct_for_first_message(self):
"""Test that is_multi_turn is False for first message."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
manager = ChatContextManager(
session_id="test-session",
@@ -105,7 +105,7 @@ class TestResearchIntegration:
def test_multi_turn_flag_correct_for_followup(self):
"""Test that is_multi_turn is True for follow-up messages."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
messages = [
{
@@ -140,7 +140,7 @@ class TestContextExtraction:
def test_extract_context_updates_from_new_research(self):
"""Test extracting context updates from new research content."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
manager = ChatContextManager(
session_id="test-session",
diff --git a/tests/chat/test_chat_route_helpers.py b/tests/chat/test_chat_route_helpers.py
index c8f9df00a0..37fa25172f 100644
--- a/tests/chat/test_chat_route_helpers.py
+++ b/tests/chat/test_chat_route_helpers.py
@@ -13,14 +13,14 @@ class TestParseIntParam:
def test_parse_int_param_valid_value(self):
"""Test parsing a valid integer string."""
- from src.local_deep_research.chat.routes import _parse_int_param
+ from local_deep_research.chat.routes import _parse_int_param
result = _parse_int_param("42", default=10)
assert result == 42
def test_parse_int_param_default_on_invalid(self):
"""Test that invalid values return the default."""
- from src.local_deep_research.chat.routes import _parse_int_param
+ from local_deep_research.chat.routes import _parse_int_param
# Non-numeric string
result = _parse_int_param("abc", default=10)
@@ -32,7 +32,7 @@ class TestParseIntParam:
def test_parse_int_param_respects_min_val(self):
"""Test that values below min_val are clamped."""
- from src.local_deep_research.chat.routes import _parse_int_param
+ from local_deep_research.chat.routes import _parse_int_param
# Value below minimum
result = _parse_int_param("-5", default=10, min_val=0)
@@ -44,7 +44,7 @@ class TestParseIntParam:
def test_parse_int_param_respects_max_val(self):
"""Test that values above max_val are clamped."""
- from src.local_deep_research.chat.routes import _parse_int_param
+ from local_deep_research.chat.routes import _parse_int_param
# Value above maximum
result = _parse_int_param("200", default=10, min_val=0, max_val=100)
@@ -56,14 +56,14 @@ class TestParseIntParam:
def test_parse_int_param_handles_none(self):
"""Test that None values return the default."""
- from src.local_deep_research.chat.routes import _parse_int_param
+ from local_deep_research.chat.routes import _parse_int_param
result = _parse_int_param(None, default=25)
assert result == 25
def test_parse_int_param_handles_float_string(self):
"""Test that float strings fall back to default."""
- from src.local_deep_research.chat.routes import _parse_int_param
+ from local_deep_research.chat.routes import _parse_int_param
result = _parse_int_param("3.14", default=10)
assert result == 10
diff --git a/tests/chat/test_chat_send_message_reclaim.py b/tests/chat/test_chat_send_message_reclaim.py
index 4bd0314aa4..7e1013a24b 100644
--- a/tests/chat/test_chat_send_message_reclaim.py
+++ b/tests/chat/test_chat_send_message_reclaim.py
@@ -29,14 +29,14 @@ import uuid
from datetime import datetime, timedelta, UTC
from unittest.mock import patch
-from src.local_deep_research.constants import ResearchStatus
-from src.local_deep_research.database.models import (
+from local_deep_research.constants import ResearchStatus
+from local_deep_research.database.models import (
ChatSession,
ChatSessionStatus,
ResearchHistory,
UserActiveResearch,
)
-from src.local_deep_research.web.routes.globals import (
+from local_deep_research.web.routes.globals import (
is_research_thread_alive,
reclaim_stale_user_active_research,
)
@@ -177,7 +177,7 @@ def test_reclaim_skips_live_thread(setup_database_for_all_tests):
)
with patch(
- "src.local_deep_research.web.routes.globals.is_research_thread_alive",
+ "local_deep_research.web.routes.globals.is_research_thread_alive",
return_value=True,
):
with SessionLocal() as db:
diff --git a/tests/chat/test_chat_service.py b/tests/chat/test_chat_service.py
index 77a7654194..3b9ec8eeaa 100644
--- a/tests/chat/test_chat_service.py
+++ b/tests/chat/test_chat_service.py
@@ -14,7 +14,7 @@ class TestChatServiceSessionCreation:
def test_create_session_returns_uuid(self, mock_user_db_session):
"""Test that create_session returns a valid UUID."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
mock_user_db_session.add = MagicMock()
mock_user_db_session.commit = MagicMock()
@@ -31,7 +31,7 @@ class TestChatServiceSessionCreation:
def test_create_session_with_initial_query(self, mock_user_db_session):
"""Test creating a session with an initial query."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
mock_user_db_session.add = MagicMock()
mock_user_db_session.commit = MagicMock()
@@ -46,7 +46,7 @@ class TestChatServiceSessionCreation:
def test_create_session_with_custom_title(self, mock_user_db_session):
"""Test creating a session with a custom title."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
mock_user_db_session.add = MagicMock()
mock_user_db_session.commit = MagicMock()
@@ -63,7 +63,7 @@ class TestChatServiceSessionCreation:
self, mock_user_db_session, long_query_text
):
"""Test that title is generated from query and truncated to 100 chars + '...'."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
mock_user_db_session.add = MagicMock()
mock_user_db_session.commit = MagicMock()
@@ -90,7 +90,7 @@ class TestChatServiceSessionCreation:
self, mock_user_db_session
):
"""Test that title is generated in format 'Chat YYYY-MM-DD HH:MM' when no query."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
mock_user_db_session.add = MagicMock()
mock_user_db_session.commit = MagicMock()
@@ -110,7 +110,7 @@ class TestChatServiceSessionCreation:
self, mock_user_db_session
):
"""Test that accumulated_context is initialized with proper structure."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
mock_user_db_session.add = MagicMock()
mock_user_db_session.commit = MagicMock()
@@ -137,7 +137,7 @@ class TestChatServiceAddMessage:
self, mock_user_db_session, mock_chat_session
):
"""Test that add_message returns a valid UUID."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
# Set up query mock to return session (handles with_for_update)
setup_query_mock_with_session(mock_user_db_session, mock_chat_session)
@@ -162,7 +162,7 @@ class TestChatServiceAddMessage:
self, mock_user_db_session, mock_chat_session
):
"""Test that sequence number increments with each message."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
mock_chat_session.message_count = 5
setup_query_mock_with_session(mock_user_db_session, mock_chat_session)
@@ -186,7 +186,7 @@ class TestChatServiceAddMessage:
self, mock_user_db_session, mock_chat_session
):
"""Test that session message_count is updated."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
mock_chat_session.message_count = 5
setup_query_mock_with_session(mock_user_db_session, mock_chat_session)
@@ -206,7 +206,7 @@ class TestChatServiceAddMessage:
def test_add_message_raises_for_invalid_session(self, mock_user_db_session):
"""Test that add_message raises ValueError for non-existent session."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
# Set up query mock to return None (session not found)
setup_query_mock_with_session(mock_user_db_session, None)
@@ -231,7 +231,7 @@ class TestChatServiceContextAccumulation:
self, mock_user_db_session, mock_chat_session
):
"""Test that new entities are added to accumulated context."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
mock_chat_session.accumulated_context = {
"key_entities": ["entity1"],
@@ -266,7 +266,7 @@ class TestChatServiceContextAccumulation:
self, mock_user_db_session, mock_chat_session
):
"""Test that entities are limited to 50."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
mock_chat_session.accumulated_context = {
"key_entities": [],
@@ -291,7 +291,7 @@ class TestChatServiceContextAccumulation:
self, mock_user_db_session, mock_chat_session
):
"""Test that topics are limited to 20."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
mock_chat_session.accumulated_context = {
"key_entities": [],
@@ -316,7 +316,7 @@ class TestChatServiceContextAccumulation:
self, mock_user_db_session, mock_chat_session
):
"""Test that summary is truncated to 8000 characters."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
mock_chat_session.accumulated_context = {
"key_entities": [],
@@ -345,7 +345,7 @@ class TestChatServiceGetSession:
self, mock_user_db_session, mock_chat_session
):
"""Test that get_session returns the correct session as a dict."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
query_mock = MagicMock()
query_mock.filter_by.return_value.first.return_value = mock_chat_session
@@ -364,7 +364,7 @@ class TestChatServiceGetSession:
):
"""Test that get_session raises ChatSessionNotFound for missing rows."""
import pytest
- from src.local_deep_research.chat.service import (
+ from local_deep_research.chat.service import (
ChatService,
ChatSessionNotFound,
)
@@ -387,7 +387,7 @@ class TestChatServiceGetSessionMessages:
):
"""get_session_messages does TWO queries (ChatMessage
+ ChatProgressStep). Helper sets up the side_effect to dispatch."""
- from src.local_deep_research.database.models import (
+ from local_deep_research.database.models import (
ChatMessage,
ChatProgressStep,
)
@@ -412,7 +412,7 @@ class TestChatServiceGetSessionMessages:
self, mock_user_db_session, sample_messages
):
"""Test that get_session_messages returns messages in order."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
mock_messages = []
for msg in sample_messages:
@@ -432,7 +432,7 @@ class TestChatServiceGetSessionMessages:
self, mock_user_db_session
):
"""Test that get_session_messages returns empty list when no messages."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
self._setup_query_side_effect(mock_user_db_session, [], [])
@@ -445,7 +445,7 @@ class TestChatServiceGetSessionMessages:
self, mock_user_db_session, sample_messages
):
"""Test that get_session_messages respects limit and offset."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
mock_messages = []
for msg in sample_messages[:2]:
@@ -472,8 +472,8 @@ class TestChatServiceGetSessionMessages:
milestones. The merged stream must surface step entries with
that exact discriminator value.
"""
- from src.local_deep_research.chat.service import ChatService
- from src.local_deep_research.database.models import (
+ from local_deep_research.chat.service import ChatService
+ from local_deep_research.database.models import (
ChatMessage,
ChatProgressStep,
)
@@ -565,7 +565,7 @@ class TestChatServiceTitleGeneration:
generation out of the POST /api/chat/sessions path so the HTTP
response isn't blocked on a model round-trip.
"""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
mock_user_db_session.add = MagicMock()
mock_user_db_session.commit = MagicMock()
@@ -573,7 +573,7 @@ class TestChatServiceTitleGeneration:
settings_snapshot = {"chat.llm_title_generation": {"value": True}}
with patch(
- "src.local_deep_research.config.llm_config.get_llm"
+ "local_deep_research.config.llm_config.get_llm"
) as mock_get_llm:
service = ChatService(username="testuser")
service.create_session(
@@ -587,7 +587,7 @@ class TestChatServiceTitleGeneration:
self, mock_user_db_session, mock_chat_session
):
"""regenerate_title_with_llm writes the LLM-returned title to the session."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
# Title must equal the non-LLM fallback so the idempotency check
# at the top of regenerate_title_with_llm doesn't short-circuit.
@@ -605,11 +605,11 @@ class TestChatServiceTitleGeneration:
with (
patch(
- "src.local_deep_research.config.llm_config.get_llm",
+ "local_deep_research.config.llm_config.get_llm",
return_value=fake_llm,
),
patch(
- "src.local_deep_research.config.thread_settings.get_setting_from_snapshot",
+ "local_deep_research.config.thread_settings.get_setting_from_snapshot",
return_value=True,
),
):
@@ -636,7 +636,7 @@ class TestChatServiceTitleGeneration:
second log entry in aggregators (log injection). The stored
title must have all CR/LF flattened to spaces.
"""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
query = "Does quantum entanglement violate locality?"
mock_chat_session.title = query # equals fallback → not skipped
@@ -654,11 +654,11 @@ class TestChatServiceTitleGeneration:
with (
patch(
- "src.local_deep_research.config.llm_config.get_llm",
+ "local_deep_research.config.llm_config.get_llm",
return_value=fake_llm,
),
patch(
- "src.local_deep_research.config.thread_settings.get_setting_from_snapshot",
+ "local_deep_research.config.thread_settings.get_setting_from_snapshot",
return_value=True,
),
):
@@ -685,7 +685,7 @@ class TestChatServiceTitleGeneration:
"""If the title no longer matches the non-LLM fallback (because the
user manually edited it, or a sibling tab's LLM-gen already ran),
skip the LLM call to avoid burning credits to overwrite their work."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
query = "Does quantum entanglement violate locality?"
mock_chat_session.title = "My Custom Title" # user-edited
@@ -696,11 +696,11 @@ class TestChatServiceTitleGeneration:
with (
patch(
- "src.local_deep_research.config.llm_config.get_llm",
+ "local_deep_research.config.llm_config.get_llm",
return_value=fake_llm,
),
patch(
- "src.local_deep_research.config.thread_settings.get_setting_from_snapshot",
+ "local_deep_research.config.thread_settings.get_setting_from_snapshot",
return_value=True,
),
):
@@ -722,7 +722,7 @@ class TestChatServiceTitleGeneration:
self, mock_user_db_session
):
"""Empty query → None (no LLM call, no DB write)."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
service = ChatService(username="testuser")
assert (
@@ -753,7 +753,7 @@ class TestChatMessageEnumValidation:
from datetime import datetime as _dt, UTC as _utc
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker
- from src.local_deep_research.database.models import (
+ from local_deep_research.database.models import (
Base,
ChatSession,
)
@@ -786,7 +786,7 @@ class TestChatMessageEnumValidation:
def test_add_message_rejects_invalid_role(self, tmp_path):
"""Unknown role → ValueError (which routes map to HTTP 400)."""
from contextlib import contextmanager
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
engine, Session, session_id = self._setup_real_db(tmp_path)
@@ -797,7 +797,7 @@ class TestChatMessageEnumValidation:
service = ChatService(username="testuser")
with patch(
- "src.local_deep_research.chat.service.get_user_db_session",
+ "local_deep_research.chat.service.get_user_db_session",
real_get_user_db_session,
):
with pytest.raises(ValueError, match="Invalid role"):
@@ -812,7 +812,7 @@ class TestChatMessageEnumValidation:
def test_add_message_rejects_invalid_message_type(self, tmp_path):
"""Unknown message_type → ValueError."""
from contextlib import contextmanager
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
engine, Session, session_id = self._setup_real_db(tmp_path)
@@ -823,7 +823,7 @@ class TestChatMessageEnumValidation:
service = ChatService(username="testuser")
with patch(
- "src.local_deep_research.chat.service.get_user_db_session",
+ "local_deep_research.chat.service.get_user_db_session",
real_get_user_db_session,
):
with pytest.raises(ValueError, match="Invalid message_type"):
@@ -838,8 +838,8 @@ class TestChatMessageEnumValidation:
def test_add_message_accepts_string_values(self, tmp_path):
"""Valid string values are coerced to enum members transparently."""
from contextlib import contextmanager
- from src.local_deep_research.chat.service import ChatService
- from src.local_deep_research.database.models import (
+ from local_deep_research.chat.service import ChatService
+ from local_deep_research.database.models import (
ChatMessage,
ChatMessageType,
ChatRole,
@@ -854,7 +854,7 @@ class TestChatMessageEnumValidation:
service = ChatService(username="testuser")
with patch(
- "src.local_deep_research.chat.service.get_user_db_session",
+ "local_deep_research.chat.service.get_user_db_session",
real_get_user_db_session,
):
service.add_message(
@@ -887,7 +887,7 @@ class TestChatServiceGetInProgressResearchId:
def test_returns_none_when_no_in_progress_research(
self, mock_user_db_session
):
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
mock_user_db_session.query.return_value.filter.return_value.first.return_value = None
@@ -897,7 +897,7 @@ class TestChatServiceGetInProgressResearchId:
def test_returns_id_when_in_progress_research_exists(
self, mock_user_db_session
):
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
mock_user_db_session.query.return_value.filter.return_value.first.return_value = (
"research-abc-123",
@@ -919,7 +919,7 @@ class TestChatServiceGetInProgressResearchId:
import pytest
from sqlalchemy.exc import OperationalError
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
mock_user_db_session.query.side_effect = OperationalError(
"stmt", {}, Exception("boom")
@@ -935,9 +935,9 @@ class TestChatServiceGetInProgressResearchId:
"""Locks the query shape against accidental regressions — the
partial-unique-index lookup depends on the predicate matching
the index's WHERE clause exactly."""
- from src.local_deep_research.chat.service import ChatService
- from src.local_deep_research.constants import ResearchStatus
- from src.local_deep_research.database.models import ResearchHistory
+ from local_deep_research.chat.service import ChatService
+ from local_deep_research.constants import ResearchStatus
+ from local_deep_research.database.models import ResearchHistory
query_mock = MagicMock()
query_mock.filter.return_value.first.return_value = None
diff --git a/tests/chat/test_chat_settings_integration.py b/tests/chat/test_chat_settings_integration.py
index 96c191121e..9c52fd8932 100644
--- a/tests/chat/test_chat_settings_integration.py
+++ b/tests/chat/test_chat_settings_integration.py
@@ -21,7 +21,7 @@ class TestLoadSettingsHelper:
so a UI setting change just before the chat send takes effect on
the very next research run (matches the behaviour of
``research_routes.start_research``)."""
- from src.local_deep_research.chat import routes as chat_routes
+ from local_deep_research.chat import routes as chat_routes
with (
patch.object(chat_routes, "get_user_db_session") as mock_get_db,
@@ -52,7 +52,7 @@ class TestLoadSettingsHelper:
backs the snapshot semantics relied on by the research pipeline,
where the snapshot is supposed to survive global setting changes
that happen during the research run."""
- from src.local_deep_research.chat import routes as chat_routes
+ from local_deep_research.chat import routes as chat_routes
snapshots: list[dict] = [
{"llm.model": {"value": "first"}},
diff --git a/tests/chat/test_chat_socket_events.py b/tests/chat/test_chat_socket_events.py
index 266f3cb23a..6bcd79dfe1 100644
--- a/tests/chat/test_chat_socket_events.py
+++ b/tests/chat/test_chat_socket_events.py
@@ -12,7 +12,7 @@ from unittest.mock import MagicMock, patch
import pytest
-from src.local_deep_research.web.services.socket_service import SocketIOService
+from local_deep_research.web.services.socket_service import SocketIOService
@pytest.fixture(autouse=True)
@@ -35,18 +35,18 @@ class TestSocketIOHandlers:
def test_on_connect_logs_client_sid(self, app):
"""Test that client connection is logged with SID."""
- from src.local_deep_research.web.services.socket_service import (
+ from local_deep_research.web.services.socket_service import (
SocketIOService,
)
with patch(
- "src.local_deep_research.web.services.socket_service.SocketIO"
+ "local_deep_research.web.services.socket_service.SocketIO"
) as mock_socketio_class:
mock_socketio = MagicMock()
mock_socketio_class.return_value = mock_socketio
with patch(
- "src.local_deep_research.web.services.socket_service.logger"
+ "local_deep_research.web.services.socket_service.logger"
) as mock_logger:
service = SocketIOService(app=app)
@@ -75,7 +75,7 @@ class TestSocketIOHandlers:
def test_on_disconnect_cleans_up_subscriptions(self):
"""Test that client disconnection cleans up subscriptions."""
- from src.local_deep_research.web.services.socket_service import (
+ from local_deep_research.web.services.socket_service import (
SocketIOService,
)
@@ -83,7 +83,7 @@ class TestSocketIOHandlers:
mock_app.config = {"SECRET_KEY": "test-secret"}
with patch(
- "src.local_deep_research.web.services.socket_service.SocketIO"
+ "local_deep_research.web.services.socket_service.SocketIO"
) as mock_socketio_class:
mock_socketio = MagicMock()
mock_socketio_class.return_value = mock_socketio
@@ -113,7 +113,7 @@ class TestSocketIOHandlers:
def test_on_subscribe_adds_to_subscription_set(self):
"""Test that subscribe event adds client to subscription set."""
- from src.local_deep_research.web.services.socket_service import (
+ from local_deep_research.web.services.socket_service import (
SocketIOService,
)
@@ -122,17 +122,17 @@ class TestSocketIOHandlers:
with (
patch(
- "src.local_deep_research.web.services.socket_service.SocketIO"
+ "local_deep_research.web.services.socket_service.SocketIO"
) as mock_socketio_class,
patch(
- "src.local_deep_research.web.services.socket_service.session",
+ "local_deep_research.web.services.socket_service.session",
{"username": "alice", "session_id": "sess-alice"},
),
patch.object(
SocketIOService, "_user_owns_research", return_value=True
),
patch(
- "src.local_deep_research.web.auth.session_manager."
+ "local_deep_research.web.auth.session_manager."
"session_manager.validate_session",
return_value="alice",
),
@@ -157,7 +157,7 @@ class TestSocketIOHandlers:
def test_on_subscribe_sends_current_status_if_available(self):
"""Test that subscribe sends current status when research is active."""
- from src.local_deep_research.web.services.socket_service import (
+ from local_deep_research.web.services.socket_service import (
SocketIOService,
)
@@ -166,17 +166,17 @@ class TestSocketIOHandlers:
with (
patch(
- "src.local_deep_research.web.services.socket_service.SocketIO"
+ "local_deep_research.web.services.socket_service.SocketIO"
) as mock_socketio_class,
patch(
- "src.local_deep_research.web.services.socket_service.session",
+ "local_deep_research.web.services.socket_service.session",
{"username": "alice", "session_id": "sess-alice"},
),
patch.object(
SocketIOService, "_user_owns_research", return_value=True
),
patch(
- "src.local_deep_research.web.auth.session_manager."
+ "local_deep_research.web.auth.session_manager."
"session_manager.validate_session",
return_value="alice",
),
@@ -185,7 +185,7 @@ class TestSocketIOHandlers:
mock_socketio_class.return_value = mock_socketio
with patch(
- "src.local_deep_research.web.services.socket_service.get_active_research_snapshot"
+ "local_deep_research.web.services.socket_service.get_active_research_snapshot"
) as mock_snapshot:
mock_snapshot.return_value = {
"progress": 50,
@@ -207,7 +207,7 @@ class TestSocketIOHandlers:
def test_emit_to_subscribers_broadcasts_to_room(self):
"""Test that emit_to_subscribers broadcasts to all subscribers."""
- from src.local_deep_research.web.services.socket_service import (
+ from local_deep_research.web.services.socket_service import (
SocketIOService,
)
@@ -215,7 +215,7 @@ class TestSocketIOHandlers:
mock_app.config = {"SECRET_KEY": "test-secret"}
with patch(
- "src.local_deep_research.web.services.socket_service.SocketIO"
+ "local_deep_research.web.services.socket_service.SocketIO"
) as mock_socketio_class:
mock_socketio = MagicMock()
mock_socketio_class.return_value = mock_socketio
@@ -243,7 +243,7 @@ class TestSocketIOHandlers:
def test_emit_socket_event_handles_exceptions(self):
"""Test that emit_socket_event handles exceptions gracefully."""
- from src.local_deep_research.web.services.socket_service import (
+ from local_deep_research.web.services.socket_service import (
SocketIOService,
)
@@ -251,7 +251,7 @@ class TestSocketIOHandlers:
mock_app.config = {"SECRET_KEY": "test-secret"}
with patch(
- "src.local_deep_research.web.services.socket_service.SocketIO"
+ "local_deep_research.web.services.socket_service.SocketIO"
) as mock_socketio_class:
mock_socketio = MagicMock()
mock_socketio.emit.side_effect = Exception("Network error")
@@ -266,7 +266,7 @@ class TestSocketIOHandlers:
def test_concurrent_subscribe_unsubscribe_thread_safety(self):
"""Test that concurrent subscribe/unsubscribe operations are thread-safe."""
- from src.local_deep_research.web.services.socket_service import (
+ from local_deep_research.web.services.socket_service import (
SocketIOService,
)
@@ -275,17 +275,17 @@ class TestSocketIOHandlers:
with (
patch(
- "src.local_deep_research.web.services.socket_service.SocketIO"
+ "local_deep_research.web.services.socket_service.SocketIO"
) as mock_socketio_class,
patch(
- "src.local_deep_research.web.services.socket_service.session",
+ "local_deep_research.web.services.socket_service.session",
{"username": "alice", "session_id": "sess-alice"},
),
patch.object(
SocketIOService, "_user_owns_research", return_value=True
),
patch(
- "src.local_deep_research.web.auth.session_manager."
+ "local_deep_research.web.auth.session_manager."
"session_manager.validate_session",
return_value="alice",
),
@@ -336,7 +336,7 @@ class TestSocketIOHandlers:
def test_subscription_cleanup_on_error(self):
"""Test that subscriptions are cleaned up even if emit fails."""
- from src.local_deep_research.web.services.socket_service import (
+ from local_deep_research.web.services.socket_service import (
SocketIOService,
)
@@ -345,17 +345,17 @@ class TestSocketIOHandlers:
with (
patch(
- "src.local_deep_research.web.services.socket_service.SocketIO"
+ "local_deep_research.web.services.socket_service.SocketIO"
) as mock_socketio_class,
patch(
- "src.local_deep_research.web.services.socket_service.session",
+ "local_deep_research.web.services.socket_service.session",
{"username": "alice", "session_id": "sess-alice"},
),
patch.object(
SocketIOService, "_user_owns_research", return_value=True
),
patch(
- "src.local_deep_research.web.auth.session_manager."
+ "local_deep_research.web.auth.session_manager."
"session_manager.validate_session",
return_value="alice",
),
@@ -383,7 +383,7 @@ class TestSocketIOHandlers:
# Now disconnect - should clean up even with errors
with patch(
- "src.local_deep_research.web.services.socket_service.logger"
+ "local_deep_research.web.services.socket_service.logger"
):
service._SocketIOService__handle_disconnect(
mock_request, "close"
diff --git a/tests/chat/test_chat_user_isolation.py b/tests/chat/test_chat_user_isolation.py
index e1a3403583..0ee1e92b77 100644
--- a/tests/chat/test_chat_user_isolation.py
+++ b/tests/chat/test_chat_user_isolation.py
@@ -20,7 +20,7 @@ from unittest.mock import MagicMock, patch
import pytest
from sqlalchemy.exc import SQLAlchemyError
-from src.local_deep_research.chat.service import ChatSessionNotFound
+from local_deep_research.chat.service import ChatSessionNotFound
# Exceptions every isolation test must tolerate: the MagicMock query
# chains don't match the real SQLAlchemy shape used by some methods, so
@@ -50,7 +50,7 @@ def username_capturing_db():
yield mock_session
with patch(
- "src.local_deep_research.chat.service.get_user_db_session",
+ "local_deep_research.chat.service.get_user_db_session",
_fake_get_user_db_session,
):
yield captured, mock_session
@@ -63,7 +63,7 @@ class TestUserIsolation:
self, username_capturing_db
):
"""get_session queries the correct user's database."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
captured, mock_session = username_capturing_db
mock_session.query.return_value.filter_by.return_value.first.return_value = None
@@ -78,7 +78,7 @@ class TestUserIsolation:
self, username_capturing_db
):
"""get_session_messages queries the correct user's database."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
captured, _ = username_capturing_db
@@ -92,7 +92,7 @@ class TestUserIsolation:
self, username_capturing_db
):
"""list_sessions queries the correct user's database."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
captured, _ = username_capturing_db
@@ -106,7 +106,7 @@ class TestUserIsolation:
self, username_capturing_db
):
"""update_accumulated_context queries the correct user's database."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
captured, mock_session = username_capturing_db
mock_session.query.return_value.filter_by.return_value.with_for_update.return_value.first.return_value = None
@@ -121,7 +121,7 @@ class TestUserIsolation:
self, username_capturing_db
):
"""delete_session queries the correct user's database."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
captured, mock_session = username_capturing_db
mock_session.query.return_value.filter_by.return_value.first.return_value = None
@@ -139,7 +139,7 @@ class TestCrossUserAccess:
self, username_capturing_db
):
"""Different ChatService instances use their own usernames."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
captured, _ = username_capturing_db
@@ -158,7 +158,7 @@ class TestCrossUserAccess:
self, username_capturing_db
):
"""All CRUD operations consistently use the service username."""
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
captured, mock_session = username_capturing_db
mock_session.query.return_value.filter_by.return_value.first.return_value = None
diff --git a/tests/chat/test_chat_xss_prevention.py b/tests/chat/test_chat_xss_prevention.py
index a878d47450..8306293425 100644
--- a/tests/chat/test_chat_xss_prevention.py
+++ b/tests/chat/test_chat_xss_prevention.py
@@ -229,7 +229,7 @@ class TestContextManagerXSS:
def test_xss_in_messages_handled_in_context(self):
"""Test that XSS in messages doesn't affect context building."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
messages = [
{
@@ -259,7 +259,7 @@ class TestContextManagerXSS:
def test_xss_in_accumulated_context(self):
"""Test that XSS in accumulated context is handled safely."""
- from src.local_deep_research.chat.context import ChatContextManager
+ from local_deep_research.chat.context import ChatContextManager
accumulated = {
"key_entities": [
diff --git a/tests/database/test_chat_models.py b/tests/database/test_chat_models.py
index a69de41964..a22b2b46dd 100644
--- a/tests/database/test_chat_models.py
+++ b/tests/database/test_chat_models.py
@@ -10,7 +10,7 @@ class TestChatSessionModel:
def test_chat_session_table_exists(self, setup_database_for_all_tests):
"""Test that the chat_sessions table exists in the database."""
- from src.local_deep_research.database.models import Base
+ from local_deep_research.database.models import Base
# Get all table names from metadata
table_names = set(Base.metadata.tables.keys())
@@ -24,7 +24,7 @@ class TestChatSessionModel:
self, setup_database_for_all_tests
):
"""Test that ChatSession has all required columns."""
- from src.local_deep_research.database.models.chat import ChatSession
+ from local_deep_research.database.models.chat import ChatSession
required_columns = {
"id",
@@ -47,7 +47,7 @@ class TestChatSessionModel:
):
"""Test that accumulated_context JSON field serializes correctly."""
from datetime import datetime, UTC
- from src.local_deep_research.database.models.chat import ChatSession
+ from local_deep_research.database.models.chat import ChatSession
SessionLocal = setup_database_for_all_tests
session = SessionLocal()
@@ -85,7 +85,7 @@ class TestChatSessionModel:
):
"""Test that default status is 'active'."""
from datetime import datetime, UTC
- from src.local_deep_research.database.models.chat import ChatSession
+ from local_deep_research.database.models.chat import ChatSession
SessionLocal = setup_database_for_all_tests
session = SessionLocal()
@@ -116,7 +116,7 @@ class TestChatMessageModel:
def test_chat_message_table_exists(self, setup_database_for_all_tests):
"""Test that the chat_messages table exists in the database."""
- from src.local_deep_research.database.models import Base
+ from local_deep_research.database.models import Base
table_names = set(Base.metadata.tables.keys())
@@ -129,7 +129,7 @@ class TestChatMessageModel:
self, setup_database_for_all_tests
):
"""Test that ChatMessage has all required columns."""
- from src.local_deep_research.database.models.chat import ChatMessage
+ from local_deep_research.database.models.chat import ChatMessage
required_columns = {
"id",
@@ -153,7 +153,7 @@ class TestChatMessageModel:
self, setup_database_for_all_tests
):
"""Test that ChatMessage has foreign key relationship to ChatSession."""
- from src.local_deep_research.database.models.chat import ChatMessage
+ from local_deep_research.database.models.chat import ChatMessage
# Check foreign keys
foreign_keys = [
@@ -169,7 +169,7 @@ class TestChatMessageModel:
):
"""Test that research_id column is nullable."""
from datetime import datetime, UTC
- from src.local_deep_research.database.models.chat import (
+ from local_deep_research.database.models.chat import (
ChatMessage,
ChatSession,
)
@@ -224,7 +224,7 @@ class TestChatModelCascade:
):
"""Test that deleting a session also deletes its messages."""
from datetime import datetime, UTC
- from src.local_deep_research.database.models.chat import (
+ from local_deep_research.database.models.chat import (
ChatSession,
ChatMessage,
)
@@ -286,7 +286,7 @@ class TestChatModelCascade:
):
"""Test that messages are properly ordered by sequence number."""
from datetime import datetime, UTC
- from src.local_deep_research.database.models.chat import (
+ from local_deep_research.database.models.chat import (
ChatSession,
ChatMessage,
)
@@ -343,7 +343,7 @@ class TestChatSessionStatus:
def test_session_can_be_archived(self, setup_database_for_all_tests):
"""Test that a session status can be changed to 'archived'."""
from datetime import datetime, UTC
- from src.local_deep_research.database.models.chat import ChatSession
+ from local_deep_research.database.models.chat import ChatSession
SessionLocal = setup_database_for_all_tests
session = SessionLocal()
@@ -389,7 +389,7 @@ class TestChatMessageContentNotNull:
import pytest
from datetime import datetime, UTC
from sqlalchemy.exc import IntegrityError
- from src.local_deep_research.database.models.chat import (
+ from local_deep_research.database.models.chat import (
ChatMessage,
ChatSession,
)
@@ -426,7 +426,7 @@ class TestChatMessageContentNotNull:
"""ChatService.add_message validates content!=None before any DB
write, raising ValueError so the route layer can surface a 400."""
import pytest
- from src.local_deep_research.chat.service import ChatService
+ from local_deep_research.chat.service import ChatService
service = ChatService(username="not-real-for-validator-test")
with pytest.raises(ValueError, match="content is required"):
@@ -451,7 +451,7 @@ class TestChatMessageContentNotNull:
@pytest.fixture
def fk_enforced_engine(tmp_path):
"""Fresh-install SQLite engine with FK enforcement on for every connection."""
- from src.local_deep_research.database.models import Base
+ from local_deep_research.database.models import Base
db_path = tmp_path / "fk_test.db"
engine = create_engine(f"sqlite:///{db_path}")
diff --git a/tests/news/test_document_scheduler_settings.py b/tests/news/test_document_scheduler_settings.py
index 0a02f49229..c9c050372e 100644
--- a/tests/news/test_document_scheduler_settings.py
+++ b/tests/news/test_document_scheduler_settings.py
@@ -8,7 +8,7 @@ from dataclasses import FrozenInstanceError
import pytest
-from src.local_deep_research.scheduler.background import (
+from local_deep_research.scheduler.background import (
DocumentSchedulerSettings,
)
diff --git a/tests/notifications/test_notification_webhook_dns_pin.py b/tests/notifications/test_notification_webhook_dns_pin.py
new file mode 100644
index 0000000000..7da278edc6
--- /dev/null
+++ b/tests/notifications/test_notification_webhook_dns_pin.py
@@ -0,0 +1,1302 @@
+"""SSRF hardening for the notification (Apprise) delivery path.
+
+These tests prove that the DNS pin + block-private send window
+(``security.dns_pinning`` + ``notifications.service``) close the
+resolve-vs-connect / DNS-rebinding TOCTOU that Apprise's own send-time
+re-resolution would otherwise reopen:
+
+* the ``getaddrinfo`` shim actually intercepts *Apprise's* resolution
+ (Apprise is forced synchronous/in-thread so the thread-local guard
+ applies) — an end-to-end ``json://`` webhook is delivered, rebound, and
+ redirected through the real Apprise + ``requests`` stack;
+* a host that validated public but rebinds to a private/metadata IP is
+ refused before any connection;
+* a webhook that redirects to an internal IP is refused at the socket
+ layer during the window;
+* plugin schemes with a token "host" (``discord://``) are never resolved
+ as a hostname (not broken by pinning); and
+* TLS SNI + certificate verification still use the original hostname while
+ the socket connects to the pinned IP.
+"""
+
+import contextlib
+import datetime
+import ipaddress
+import socket
+import ssl
+import threading
+import time
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from unittest.mock import patch
+
+import apprise
+import pytest
+import requests
+from cryptography import x509
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import rsa
+from cryptography.x509.oid import NameOID
+
+from local_deep_research.notifications.exceptions import SendError, ServiceError
+from local_deep_research.notifications.service import NotificationService
+from local_deep_research.security import dns_pinning
+
+
+# --------------------------------------------------------------------------
+# Test doubles
+# --------------------------------------------------------------------------
+class _Resolver:
+ """Drive ``dns_pinning._real_getaddrinfo`` with scripted answers.
+
+ ``answers`` maps host -> list of successive answers (each a list of IP
+ strings). Each lookup consumes the next answer; the final answer sticks
+ for every later call, so a two-element list simulates a rebind that then
+ stays put (validation sees answer #1, the pin/send sees answer #2).
+ """
+
+ def __init__(self, answers):
+ self._answers = {
+ h.lower().rstrip("."): list(v) for h, v in answers.items()
+ }
+ self.calls = []
+
+ def __call__(self, host, port, family=0, type=0, proto=0, flags=0):
+ self.calls.append((host, port))
+ norm = (host or "").lower().rstrip(".")
+ # A numeric IP literal resolves to ITSELF — exactly what the real
+ # getaddrinfo does. Without this, a redirect/rebind whose target is a
+ # bare IP literal (e.g. 169.254.169.254) would raise "no answer" here
+ # BEFORE any block check could run, making such a test pass for the
+ # wrong reason (vacuously green even if the block were deleted).
+ try:
+ ipaddress.ip_address(norm)
+ is_literal = True
+ except ValueError:
+ is_literal = False
+ if is_literal:
+ ips = [norm]
+ else:
+ seq = self._answers.get(norm)
+ if not seq:
+ raise socket.gaierror(
+ socket.EAI_NONAME, f"no answer for {host}"
+ )
+ ips = seq[0] if len(seq) == 1 else seq.pop(0)
+ results = []
+ for ip in ips:
+ fam = socket.AF_INET6 if ":" in ip else socket.AF_INET
+ sockaddr = (
+ (ip, port or 0, 0, 0)
+ if fam == socket.AF_INET6
+ else (ip, port or 0)
+ )
+ results.append(
+ (fam, socket.SOCK_STREAM, socket.IPPROTO_TCP, "", sockaddr)
+ )
+ return results
+
+
+class _RecordingHandler(BaseHTTPRequestHandler):
+ """200 OK that records every request path it served."""
+
+ hits = None # set on the subclass
+ redirect_to = None # optional Location target
+
+ def _handle(self):
+ type(self).hits.append(self.path)
+ if type(self).redirect_to:
+ self.send_response(302)
+ self.send_header("Location", type(self).redirect_to)
+ self.end_headers()
+ return
+ body = b"OK"
+ self.send_response(200)
+ self.send_header("Content-Length", str(len(body)))
+ self.end_headers()
+ self.wfile.write(body)
+
+ def do_GET(self):
+ self._handle()
+
+ def do_POST(self):
+ length = int(self.headers.get("Content-Length", 0) or 0)
+ if length:
+ self.rfile.read(length)
+ self._handle()
+
+ def log_message(self, *args):
+ pass
+
+
+def _start_server(redirect_to=None, tls_cert=None):
+ """Start a loopback HTTP(S) server; return (server, port, hits)."""
+ hits = []
+ handler = type(
+ "BoundHandler",
+ (_RecordingHandler,),
+ {"hits": hits, "redirect_to": redirect_to},
+ )
+ server = HTTPServer(("127.0.0.1", 0), handler)
+ if tls_cert is not None:
+ cert_file, key_file = tls_cert
+ ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
+ ctx.load_cert_chain(certfile=cert_file, keyfile=key_file)
+ server.socket = ctx.wrap_socket(server.socket, server_side=True)
+ threading.Thread(target=server.serve_forever, daemon=True).start()
+ return server, server.server_address[1], hits
+
+
+def _make_self_signed_cert(hostname, tmp_path):
+ """Mint a self-signed cert (SAN=DNS:hostname); return (cert, key) paths."""
+ key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
+ name = x509.Name([x509.NameAttribute(NameOID.COMMON_NAME, hostname)])
+ now = datetime.datetime.now(datetime.timezone.utc)
+ cert = (
+ x509.CertificateBuilder()
+ .subject_name(name)
+ .issuer_name(name)
+ .public_key(key.public_key())
+ .serial_number(x509.random_serial_number())
+ .not_valid_before(now - datetime.timedelta(minutes=5))
+ .not_valid_after(now + datetime.timedelta(days=1))
+ .add_extension(
+ x509.SubjectAlternativeName([x509.DNSName(hostname)]),
+ critical=False,
+ )
+ .add_extension(
+ x509.BasicConstraints(ca=True, path_length=None), critical=True
+ )
+ .sign(key, hashes.SHA256())
+ )
+ cert_file = tmp_path / "cert.pem"
+ key_file = tmp_path / "key.pem"
+ cert_file.write_bytes(cert.public_bytes(serialization.Encoding.PEM))
+ key_file.write_bytes(
+ key.private_bytes(
+ encoding=serialization.Encoding.PEM,
+ format=serialization.PrivateFormat.TraditionalOpenSSL,
+ encryption_algorithm=serialization.NoEncryption(),
+ )
+ )
+ return str(cert_file), str(key_file)
+
+
+def _connect_spy():
+ """Record every ``socket.connect`` target address for the duration."""
+ targets = []
+ real_connect = socket.socket.connect
+
+ def spy(self, address):
+ targets.append(address)
+ return real_connect(self, address)
+
+ with patch.object(socket.socket, "connect", spy):
+ yield targets
+
+
+def _service():
+ return NotificationService(allow_private_ips=False, outbound_allowed=True)
+
+
+# ==========================================================================
+# dns_pinning primitives: block_private_resolution
+# ==========================================================================
+def test_block_private_refuses_metadata_at_socket_layer():
+ """An unpinned lookup that resolves to cloud-metadata is refused with a
+ gaierror while the block-private window is active (even with
+ allow_private_ips=True, metadata is always blocked)."""
+ resolver = _Resolver({"redir.example": [["169.254.169.254"]]})
+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
+ with dns_pinning.block_private_resolution(allow_private_ips=True):
+ with pytest.raises(socket.gaierror):
+ socket.getaddrinfo("redir.example", 80)
+ # Outside the window the same lookup resolves normally.
+ assert socket.getaddrinfo("redir.example", 80)[0][4][0] == (
+ "169.254.169.254"
+ )
+
+
+def test_block_private_refuses_rfc1918_when_not_opted_in():
+ resolver = _Resolver({"redir.example": [["10.1.2.3"]]})
+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
+ with dns_pinning.block_private_resolution(allow_private_ips=False):
+ with pytest.raises(socket.gaierror):
+ socket.getaddrinfo("redir.example", 80)
+
+
+def test_block_private_allows_rfc1918_when_opted_in_but_still_blocks_metadata():
+ resolver = _Resolver(
+ {"lan.example": [["10.1.2.3"]], "imds.example": [["169.254.169.254"]]}
+ )
+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
+ with dns_pinning.block_private_resolution(allow_private_ips=True):
+ # Private allowed under the opt-in...
+ assert socket.getaddrinfo("lan.example", 80)[0][4][0] == "10.1.2.3"
+ # ...but metadata is still refused.
+ with pytest.raises(socket.gaierror):
+ socket.getaddrinfo("imds.example", 80)
+
+
+def test_block_private_passes_public_through():
+ resolver = _Resolver({"ok.example": [["93.184.216.34"]]})
+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
+ with dns_pinning.block_private_resolution(allow_private_ips=False):
+ assert (
+ socket.getaddrinfo("ok.example", 80)[0][4][0] == "93.184.216.34"
+ )
+
+
+def test_block_private_is_thread_scoped():
+ """The window on one thread must not affect another thread's lookup."""
+ resolver = _Resolver({"lan.example": [["10.1.2.3"]]})
+ other_result = {}
+
+ def worker():
+ # No window active on this thread -> resolves normally.
+ other_result["ip"] = socket.getaddrinfo("lan.example", 80)[0][4][0]
+
+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
+ with dns_pinning.block_private_resolution(allow_private_ips=False):
+ t = threading.Thread(target=worker)
+ t.start()
+ t.join()
+ assert other_result["ip"] == "10.1.2.3"
+
+
+# ==========================================================================
+# dns_pinning primitives: pin_hosts
+# ==========================================================================
+def test_pin_hosts_pins_only_pinnable_schemes():
+ """json:// (raw webhook) is resolved+pinned; discord:// (token host) is
+ left untouched — pinning must never try to resolve an opaque token."""
+ resolver = _Resolver({"hook.example": [["93.184.216.34"]]})
+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
+ with dns_pinning.pin_hosts(
+ ["json://hook.example/x", "discord://webhook_id/token"],
+ allow_private_ips=True,
+ ):
+ # hook.example is pinned; a lookup returns the pinned address
+ # without consulting the resolver again.
+ calls_before = len(resolver.calls)
+ got = socket.getaddrinfo("hook.example", 443)
+ assert got[0][4][0] == "93.184.216.34"
+ assert len(resolver.calls) == calls_before # served from pin
+ # discord's token was never resolved.
+ assert not any(h == "webhook_id" for h, _ in resolver.calls)
+
+
+def test_pin_hosts_rejects_rebind_to_metadata():
+ """A pinnable host that validates public but resolves to metadata at pin
+ time is refused (fail closed) before the window is active."""
+ resolver = _Resolver({"hook.example": [["169.254.169.254"]]})
+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
+ with pytest.raises(ValueError, match="SSRF"):
+ with dns_pinning.pin_hosts(
+ ["json://hook.example/x"], allow_private_ips=True
+ ):
+ pass
+
+
+def test_pin_hosts_skips_unresolvable_host_without_aborting():
+ """A host that doesn't resolve right now is skipped (left unpinned), not
+ fatal — so a sibling URL in the same batch is unaffected."""
+ resolver = _Resolver({"good.example": [["93.184.216.34"]]})
+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
+ with dns_pinning.pin_hosts(
+ ["json://dead.example/x", "json://good.example/y"],
+ allow_private_ips=True,
+ ):
+ assert (
+ socket.getaddrinfo("good.example", 443)[0][4][0]
+ == "93.184.216.34"
+ )
+
+
+# ==========================================================================
+# End-to-end through the real Apprise + requests stack (proves the shim
+# intercepts Apprise's own resolution)
+# ==========================================================================
+def test_public_json_webhook_delivers_through_apprise():
+ """A legitimate raw webhook is delivered end-to-end: Apprise resolves the
+ host through the shim, connects to the pinned address, and the loopback
+ server receives the POST."""
+ server, port, hits = _start_server()
+ resolver = _Resolver({"good.example": [["127.0.0.1"]]})
+ try:
+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
+ result = _service().send(
+ title="t",
+ body="b",
+ service_urls=f"json://good.example:{port}/notify",
+ )
+ assert result is True
+ assert hits, "loopback webhook server never received the request"
+ finally:
+ server.shutdown()
+
+
+def test_rebind_to_metadata_blocked_through_apprise():
+ """Validation sees a public IP; the pin's connect-time re-validation
+ catches the rebind to cloud-metadata and refuses the send before any
+ connection is made."""
+ resolver = _Resolver(
+ {"rebind.example": [["93.184.216.34"], ["169.254.169.254"]]}
+ )
+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
+ with _connect_spy() as targets:
+ with pytest.raises(SendError):
+ _service().send(
+ title="t",
+ body="b",
+ service_urls="json://rebind.example/notify",
+ )
+ assert not any(addr[0] == "169.254.169.254" for addr in targets), (
+ f"connected to metadata IP: {targets}"
+ )
+
+
+def test_multi_url_batch_guards_every_host():
+ """A single notify() fans out to several raw-webhook URLs. EVERY host in
+ the batch is pinned/checked: one host that rebinds to metadata refuses
+ the whole batch (fail closed) and no connection to the metadata IP is
+ made — proving the guard is not applied to just the first URL."""
+ server, port, _hits = _start_server()
+ resolver = _Resolver(
+ {
+ "a.example": [["127.0.0.1"]],
+ "b.example": [["93.184.216.34"], ["169.254.169.254"]],
+ }
+ )
+ urls = f"json://a.example:{port}/x,json://b.example/y"
+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
+ with _connect_spy() as targets:
+ with pytest.raises(SendError):
+ _service().send(title="t", body="b", service_urls=urls)
+ try:
+ assert not any(addr[0] == "169.254.169.254" for addr in targets)
+ finally:
+ server.shutdown()
+
+
+def test_redirect_to_metadata_blocked_at_socket_layer():
+ """A public webhook host that 302-redirects to a cloud-metadata IP:
+ defense-in-depth. Redirect-following is disabled for the send
+ (``http_redirects=False`` + per-plugin re-force), so Apprise does NOT
+ follow the 302 at all — the initial request to the (pinned) public host
+ happens, the send fails on the unfollowed 302, and no connection to the
+ metadata IP is ever made. Even if the redirect WERE followed, the
+ block-private window would refuse the ``169.254.169.254`` resolution at
+ the getaddrinfo layer (the mock resolver now resolves that literal to
+ itself, so that block genuinely fires — see
+ ``test_block_private_refuses_metadata_at_socket_layer`` for the isolated
+ teeth). Two independent layers; this asserts the end-to-end outcome."""
+ server, port, hits = _start_server(
+ redirect_to="http://169.254.169.254/latest/meta-data/"
+ )
+ resolver = _Resolver({"public.example": [["127.0.0.1"]]})
+ try:
+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
+ with _connect_spy() as targets:
+ with pytest.raises(SendError):
+ _service().send(
+ title="t",
+ body="b",
+ service_urls=f"json://public.example:{port}/hook",
+ )
+ assert hits, "initial request to the public host never happened"
+ assert not any(addr[0] == "169.254.169.254" for addr in targets), (
+ f"connected to metadata IP: {targets}"
+ )
+ finally:
+ server.shutdown()
+
+
+def test_redirect_following_disabled_by_default():
+ """Fix B, isolated from the block-private backstop: a webhook that
+ 302-redirects to a target the send window does NOT independently block
+ (``redir-target.example`` -> loopback, which the lenient plugin policy
+ allows) is still never followed, because redirect-following is disabled
+ for the send. So ONLY the redirect-disable stops the second hop — this
+ gives fix B clean teeth (deleting the redirect-disable makes the target
+ server receive the request and this test fail). Also closes
+ redirect-to-arbitrary-public exfil, of which the loopback target is a
+ stand-in."""
+ target_server, target_port, target_hits = _start_server()
+ hook_server, hook_port, hook_hits = _start_server(
+ redirect_to=f"http://redir-target.example:{target_port}/pwn"
+ )
+ resolver = _Resolver(
+ {
+ "public.example": [["127.0.0.1"]],
+ "redir-target.example": [["127.0.0.1"]],
+ }
+ )
+ try:
+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
+ with _connect_spy() as targets:
+ with pytest.raises(SendError):
+ _service().send(
+ title="t",
+ body="b",
+ service_urls=f"json://public.example:{hook_port}/hook",
+ )
+ assert hook_hits, "initial request to the webhook host never happened"
+ assert not target_hits, (
+ "redirect was FOLLOWED to the target server "
+ f"(hits={target_hits}) — redirect-following was not disabled"
+ )
+ assert not any(addr[1] == target_port for addr in targets), (
+ f"connected to the redirect target port {target_port}: {targets}"
+ )
+ finally:
+ hook_server.shutdown()
+ target_server.shutdown()
+
+
+def test_redirect_param_yes_cannot_reenable_redirects():
+ """Airtight redirect-disable: a user-supplied ``?redirect=yes`` on the
+ webhook URL would, via Apprise's per-URL override, normally re-enable
+ redirect-following even when the asset default is off. The per-plugin
+ re-force (``NotificationService._disable_redirects``) neutralizes it, so
+ the redirect is STILL not followed. The redirect target is again a
+ loopback stand-in that the block-private window does not itself block, so
+ this isolates the re-force (deleting it makes the redirect follow through
+ to the target server and this test fail)."""
+ target_server, target_port, target_hits = _start_server()
+ hook_server, hook_port, hook_hits = _start_server(
+ redirect_to=f"http://redir-target.example:{target_port}/pwn"
+ )
+ resolver = _Resolver(
+ {
+ "public.example": [["127.0.0.1"]],
+ "redir-target.example": [["127.0.0.1"]],
+ }
+ )
+ try:
+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
+ with _connect_spy() as targets:
+ with pytest.raises(SendError):
+ _service().send(
+ title="t",
+ body="b",
+ service_urls=(
+ f"json://public.example:{hook_port}"
+ "/hook?redirect=yes"
+ ),
+ )
+ assert hook_hits, "initial request to the webhook host never happened"
+ assert not target_hits, (
+ "?redirect=yes re-enabled redirect-following "
+ f"(target hits={target_hits}) — the per-plugin re-force failed"
+ )
+ assert not any(addr[1] == target_port for addr in targets), (
+ f"connected to the redirect target port {target_port}: {targets}"
+ )
+ finally:
+ hook_server.shutdown()
+ target_server.shutdown()
+
+
+def test_redirect_to_loopback_blocked_for_http_scheme_default_policy():
+ """The strict (http/https) policy blocks a redirect to loopback even
+ though the plugin policy would allow it. Exercised at the primitive level
+ because Apprise does not accept raw http(s):// notification URLs."""
+ resolver = _Resolver({"redir.example": [["127.0.0.1"]]})
+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
+ with dns_pinning.pinned_notification_send(
+ ["http://public.example/hook"], allow_private_ips=False
+ ):
+ with pytest.raises(socket.gaierror):
+ socket.getaddrinfo("redir.example", 80)
+
+
+def test_discord_plugin_scheme_not_pinned_and_unaffected():
+ """A discord:// URL (hardcoded public endpoint, opaque token host) is a
+ plugin scheme, not a raw webhook: pinning must not try to resolve its
+ token as a hostname, and the send still reaches Apprise's discord plugin
+ with the guard in place."""
+ # Empty resolver: any hostname lookup (e.g. the validator's fail-open
+ # probe of the token) returns gaierror rather than hitting the network.
+ resolver = _Resolver({})
+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
+ with patch(
+ "apprise.plugins.discord.NotifyDiscord.send", return_value=True
+ ) as mock_send:
+ result = _service().send(
+ title="t",
+ body="b",
+ service_urls="discord://123456789/abcdefg",
+ )
+ # Delivered (guard did not break the plugin) and the plugin actually ran.
+ assert result is True
+ assert mock_send.called
+
+
+# ==========================================================================
+# Fail-closed hardening invariants
+# ==========================================================================
+def test_pinned_notification_send_fails_closed_when_shim_missing():
+ """If ``socket.getaddrinfo`` is no longer our shim (e.g. a late
+ gevent/eventlet monkeypatch), the thread-local pin/block would silently
+ not apply. pinned_notification_send must REFUSE the send (fail closed)
+ rather than proceed unguarded. Teeth: drop the ``_shim_installed`` guard
+ and this raises nothing."""
+ saved = socket.getaddrinfo
+ resolver = _Resolver({}) # empty: any real lookup would gaierror
+ try:
+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
+ # Displace our shim with a plain non-shim resolver.
+ socket.getaddrinfo = resolver
+ assert not dns_pinning._shim_installed()
+ with pytest.raises(RuntimeError, match="shim"):
+ with dns_pinning.pinned_notification_send(
+ ["json://x.example/y"], allow_private_ips=True
+ ):
+ pass
+ finally:
+ socket.getaddrinfo = saved
+ # Shim restored for the rest of the suite.
+ assert dns_pinning._shim_installed()
+
+
+def _fixed_resolver(ip):
+ """A resolver that answers EVERY host (str or bytes) with ``ip``."""
+
+ def resolver(host, port, family=0, type=0, proto=0, flags=0):
+ return [
+ (
+ socket.AF_INET,
+ socket.SOCK_STREAM,
+ socket.IPPROTO_TCP,
+ "",
+ (ip, port or 0),
+ )
+ ]
+
+ return resolver
+
+
+def test_block_window_refuses_bytes_host_resolving_to_metadata():
+ """``getaddrinfo`` accepts a ``bytes`` host, so an attacker/plugin can
+ hand the shim ``b"..."`` that resolves to cloud metadata. Under an active
+ block-private window a bytes host must be block-checked and REFUSED on the
+ resolved IP exactly like a ``str`` host — not returned unchecked (the one
+ guard that used to fail OPEN).
+
+ Teeth: restore the old ``if not isinstance(host, str): return results``
+ early-return in ``_resolve_maybe_block`` and the bytes host resolves to
+ the metadata IP and is returned unchecked — no gaierror — so this test
+ fails.
+ """
+ dns_pinning.reset_ssrf_block()
+ with patch.object(
+ dns_pinning, "_real_getaddrinfo", _fixed_resolver("169.254.169.254")
+ ):
+ with dns_pinning.block_private_resolution(
+ allow_private_ips=True, block_link_local=True
+ ):
+ with pytest.raises(socket.gaierror):
+ dns_pinning._pinned_getaddrinfo(b"metadata.example", 80)
+ # A CONFIRMED security block (not a transient error) so the sender fails
+ # fast instead of retrying.
+ assert dns_pinning.consume_ssrf_block()
+
+
+def test_block_window_allows_bytes_host_resolving_to_public_ip():
+ """The bytes-host fix fails CLOSED without over-blocking: a bytes host
+ that resolves to a public address is still returned (the block check runs
+ on the resolved IP, which is not blocked), so a legitimate bytes host is
+ never refused just for being bytes."""
+ dns_pinning.reset_ssrf_block()
+ with patch.object(
+ dns_pinning, "_real_getaddrinfo", _fixed_resolver("93.184.216.34")
+ ):
+ with dns_pinning.block_private_resolution(
+ allow_private_ips=True, block_link_local=True
+ ):
+ got = dns_pinning._pinned_getaddrinfo(b"public.example", 443)
+ assert got[0][4][0] == "93.184.216.34"
+ assert not dns_pinning.consume_ssrf_block()
+
+
+def test_block_window_exempts_none_host_passive_bind():
+ """A ``None`` host is an AF_PASSIVE bind
+ (``getaddrinfo(None, port, ..., AI_PASSIVE)``) — a local listening-socket
+ setup, not a rebindable outbound name — so it is exempt from the block
+ check even while a window is active (it must not raise)."""
+ dns_pinning.reset_ssrf_block()
+ with patch.object(
+ dns_pinning, "_real_getaddrinfo", _fixed_resolver("169.254.169.254")
+ ):
+ with dns_pinning.block_private_resolution(
+ allow_private_ips=True, block_link_local=True
+ ):
+ # No raise even though the resolver answers with a metadata IP:
+ # a None (passive-bind) host is not an outbound destination.
+ got = dns_pinning._pinned_getaddrinfo(
+ None,
+ 8080,
+ socket.AF_INET,
+ socket.SOCK_STREAM,
+ 0,
+ socket.AI_PASSIVE,
+ )
+ assert got # returned unchecked
+ assert not dns_pinning.consume_ssrf_block()
+
+
+def test_send_time_resolution_timeout_fails_closed(monkeypatch):
+ """A slow/hostile DNS authority must not hang the sending thread: the
+ block-window resolution is bounded and fails closed (gaierror) well
+ before the resolver would have returned. Teeth: remove the timeout
+ wrapping and this call blocks for the full sleep instead."""
+ monkeypatch.setattr(dns_pinning, "_RESOLVE_TIMEOUT_SECONDS", 0.2)
+
+ def slow(host, *a, **k):
+ # Intentional "hang" the 0.2s bound must interrupt; the test itself
+ # returns in ~0.2s (the sleep only lingers in the abandoned worker).
+ time.sleep(1.5) # allow: unmarked-sleep
+ return [
+ (
+ socket.AF_INET,
+ socket.SOCK_STREAM,
+ socket.IPPROTO_TCP,
+ "",
+ ("93.184.216.34", 0),
+ )
+ ]
+
+ with patch.object(dns_pinning, "_real_getaddrinfo", slow):
+ with dns_pinning.block_private_resolution(allow_private_ips=True):
+ start = time.monotonic()
+ with pytest.raises(socket.gaierror):
+ socket.getaddrinfo("slow.example", 80)
+ elapsed = time.monotonic() - start
+ assert elapsed < 1.0, (
+ f"resolution was not bounded (took {elapsed:.2f}s; timeout was 0.2s)"
+ )
+
+
+def test_guarded_send_refuses_async_mode_and_tag():
+ """The guarded-send invariants fail closed: async_mode must be off and
+ tag must be None, or the thread-local pin/block would be bypassed by
+ Apprise's worker-thread fan-out. Teeth: drop the checks in
+ ``_enforce_guarded_send_invariants`` and neither raises."""
+ svc = _service()
+ # Correct config: synchronous, no tag -> accepted.
+ good = svc._new_apprise()
+ svc._enforce_guarded_send_invariants(good, None)
+ # async_mode=True -> refused.
+ bad_async = apprise.Apprise(asset=apprise.AppriseAsset(async_mode=True))
+ with pytest.raises(RuntimeError, match="async_mode"):
+ svc._enforce_guarded_send_invariants(bad_async, None)
+ # tag present -> refused.
+ with pytest.raises(RuntimeError, match="tag"):
+ svc._enforce_guarded_send_invariants(good, "urgent")
+
+
+def test_ssrf_block_is_not_retried():
+ """A confirmed SSRF block (pin's connect-time rebind-to-metadata) must
+ fail fast, not be retried 3x by Tenacity. The rebind host resolves
+ public at validation (call #1) and metadata at the guarded pin (call
+ #2), which raises the SSRF ValueError; with that excluded from retries
+ the guarded pin runs exactly ONCE. Teeth: restore
+ ``retry_if_exception_type((Exception,))`` and the pin is retried, so
+ rebind.example is resolved 4 times (1 validation + 3 pin attempts)."""
+ resolver = _Resolver(
+ {"rebind.example": [["93.184.216.34"], ["169.254.169.254"]]}
+ )
+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
+ with pytest.raises(SendError):
+ _service().send(
+ title="t",
+ body="b",
+ service_urls="json://rebind.example/notify",
+ )
+ rebind_calls = [
+ c
+ for c in resolver.calls
+ if (c[0] or "").lower().rstrip(".") == "rebind.example"
+ ]
+ assert len(rebind_calls) == 2, (
+ f"expected 1 validation + 1 (non-retried) pin resolution, got "
+ f"{len(rebind_calls)}: {rebind_calls}"
+ )
+
+
+# ==========================================================================
+# TLS: SNI + cert verification use the hostname, not the pinned IP
+# ==========================================================================
+def test_tls_sni_and_cert_use_hostname_while_connecting_to_pinned_ip(
+ tmp_path,
+):
+ """With the host pinned to the loopback server, an HTTPS request to the
+ hostname still completes certificate verification against that
+ hostname's cert. If the pin had leaked the IP into SNI / cert
+ validation, verification would fail — so success proves only name
+ resolution is redirected.
+
+ Teeth: the hostname resolves to a NON-loopback, unreachable TEST-NET-3
+ address (203.0.113.9) by DEFAULT; ONLY the pin redirects the connection
+ to 127.0.0.1 where the cert is actually served. The pinned address is
+ injected directly (what ``pin_hosts`` installs after validating) so it
+ is independent of the resolver's default answer — that independence is
+ what gives the test teeth: drop the pin and the request targets
+ 203.0.113.9 and never reaches the loopback server, so the assertions
+ fail. The ``_connect_spy`` below pins that down: the socket connects to
+ 127.0.0.1 (the pin), never to 203.0.113.9 (the default resolution)."""
+ hostname = "pinned-tls.example"
+ cert_file, key_file = _make_self_signed_cert(hostname, tmp_path)
+ server, port, _hits = _start_server(tls_cert=(cert_file, key_file))
+ # Default resolution is a non-loopback, unreachable address.
+ resolver = _Resolver({hostname: [["203.0.113.9"]]})
+ # The pin points at the loopback server. Port 0 is rewritten to the
+ # lookup's port by the shim (matching how _resolve_and_validate pins).
+ loopback_pin = [
+ (
+ socket.AF_INET,
+ socket.SOCK_STREAM,
+ socket.IPPROTO_TCP,
+ "",
+ ("127.0.0.1", 0),
+ )
+ ]
+ try:
+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
+ pins = dns_pinning._get_pins()
+ pins[hostname] = loopback_pin
+ try:
+ with _connect_spy() as targets:
+ resp = requests.get(
+ f"https://{hostname}:{port}/",
+ verify=cert_file,
+ timeout=5,
+ )
+ finally:
+ pins.pop(hostname, None)
+ assert resp.status_code == 200
+ # Connected to the PINNED loopback IP, never the default non-loopback
+ # resolution — proving the pin (not the resolver) chose the address.
+ assert any(addr[0] == "127.0.0.1" for addr in targets), targets
+ assert not any(addr[0] == "203.0.113.9" for addr in targets), targets
+ finally:
+ server.shutdown()
+
+
+# ==========================================================================
+# P1.3: a block-window block fails fast (not retried 3x)
+# ==========================================================================
+def test_block_window_block_is_not_retried():
+ """A confirmed SSRF block from the BLOCK-PRIVATE WINDOW (an UNPINNED
+ plugin-scheme host that rebinds to metadata at send time) must fail fast,
+ not be retried 3x by Tenacity. ntfy:// is a plugin scheme (not pinned),
+ so the pin's own connect-time ValueError does not apply — the block is a
+ socket.gaierror that Apprise swallows into a generic failure. The service
+ consults ``dns_pinning.consume_ssrf_block()`` after the failed send and
+ re-raises it non-retryably. The rebind host resolves public at validation
+ (call #1) and metadata at the send-time window resolution (call #2), so
+ with the block excluded from retries the host is resolved exactly TWICE.
+ Teeth: drop the ``consume_ssrf_block`` short-circuit in ``_send_with_retry``
+ and the send is retried, resolving the host 4 times (1 validation + 3
+ send attempts)."""
+ resolver = _Resolver(
+ {"rebind.example": [["93.184.216.34"], ["169.254.169.254"]]}
+ )
+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
+ with _connect_spy() as targets:
+ with pytest.raises(SendError):
+ _service().send(
+ title="t",
+ body="b",
+ service_urls="ntfy://rebind.example/mytopic",
+ )
+ rebind_calls = [
+ c
+ for c in resolver.calls
+ if (c[0] or "").lower().rstrip(".") == "rebind.example"
+ ]
+ assert len(rebind_calls) == 2, (
+ f"expected 1 validation + 1 (non-retried) send resolution, got "
+ f"{len(rebind_calls)}: {rebind_calls}"
+ )
+ assert not any(addr[0] == "169.254.169.254" for addr in targets), targets
+
+
+# ==========================================================================
+# P0.1: AWS IPv6 IMDS (fd00:ec2::254) blocked through the pin/block path
+# ==========================================================================
+def test_ipv6_imds_rejected_by_pin_at_connect_time():
+ """A pinnable raw-webhook host that resolves to AWS's IPv6 IMDS
+ (fd00:ec2::254) at pin time is refused (fail closed) even under
+ allow_private_ips=True — which permits the fc00::/7 ULA range the address
+ sits in. The cloud-metadata block is absolute."""
+ resolver = _Resolver({"hook.example": [["fd00:ec2::254"]]})
+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
+ with pytest.raises(ValueError, match="SSRF"):
+ with dns_pinning.pin_hosts(
+ ["json://hook.example/x"], allow_private_ips=True
+ ):
+ pass
+
+
+def test_ipv6_imds_refused_by_block_window():
+ """An UNPINNED lookup that resolves to AWS's IPv6 IMDS is refused at the
+ getaddrinfo layer while the block-private window is active, even with
+ allow_private_ips=True."""
+ resolver = _Resolver({"redir.example": [["fd00:ec2::254"]]})
+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
+ with dns_pinning.block_private_resolution(allow_private_ips=True):
+ with pytest.raises(socket.gaierror):
+ socket.getaddrinfo("redir.example", 80)
+
+
+# ==========================================================================
+# P2.10: additional coverage
+# ==========================================================================
+def test_send_with_tag_is_refused_end_to_end():
+ """send(..., tag=...) is refused end-to-end: a tag can fan delivery out
+ to worker threads that bypass the thread-local pin/block, so the
+ guarded-send invariant rejects it (RuntimeError, wrapped as SendError)
+ before any connection — no socket is opened to the target."""
+ resolver = _Resolver({"good.example": [["93.184.216.34"]]})
+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
+ with _connect_spy() as targets:
+ with pytest.raises(SendError):
+ _service().send(
+ title="t",
+ body="b",
+ service_urls="json://good.example/notify",
+ tag="a,b",
+ )
+ assert not any(addr[0] == "93.184.216.34" for addr in targets), targets
+
+
+def test_rfc1918_host_pinned_and_allowed_by_notification_guard():
+ """A raw-webhook (json) host that resolves to an RFC1918 address is
+ PINNED (not blocked) by the lenient notification guard — self-hosted LAN
+ webhooks keep working. The pinned lookup returns the validated RFC1918
+ address without re-resolving."""
+ resolver = _Resolver({"lan.example": [["10.11.12.13"]]})
+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
+ with dns_pinning.pinned_notification_send(
+ ["json://lan.example/hook"], allow_private_ips=True
+ ):
+ got = socket.getaddrinfo("lan.example", 443)
+ assert got[0][4][0] == "10.11.12.13"
+
+
+def test_selfhosted_private_plugin_delivers_end_to_end():
+ """A self-hosted plugin notifier (ntfy / gotify) on a private host
+ delivers end-to-end: the lenient partition allows private/LAN targets
+ (cloud-metadata still always blocked). The loopback server stands in for
+ the private endpoint; the guard pins/permits it and the plugin POSTs
+ successfully through the real Apprise + requests stack."""
+ server, port, hits = _start_server()
+ resolver = _Resolver({"lan.example": [["127.0.0.1"]]})
+ svc = NotificationService(allow_private_ips=True, outbound_allowed=True)
+ try:
+ for url in (
+ f"ntfy://lan.example:{port}/topic",
+ f"gotify://lan.example:{port}/atoken",
+ ):
+ hits.clear()
+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
+ result = svc.send(title="t", body="b", service_urls=url)
+ assert result is True, url
+ assert hits, f"self-hosted plugin never received the POST: {url}"
+ finally:
+ server.shutdown()
+
+
+def test_non_json_plugin_redirect_not_followed():
+ """redirect-disable applies to a NON-json plugin too (ntfy honors the
+ per-plugin ``redirects`` flag). An ntfy endpoint that 302-redirects to
+ another host is NOT followed: the target server is never hit and the send
+ fails on the unfollowed 302. The redirect target is a loopback stand-in
+ the lenient block-window does NOT itself block, so ONLY the
+ redirect-disable stops the second hop (teeth)."""
+ target_server, target_port, target_hits = _start_server()
+ hook_server, hook_port, hook_hits = _start_server(
+ redirect_to=f"http://redir-target.example:{target_port}/pwn"
+ )
+ resolver = _Resolver(
+ {
+ "ntfyhost.example": [["127.0.0.1"]],
+ "redir-target.example": [["127.0.0.1"]],
+ }
+ )
+ svc = NotificationService(allow_private_ips=True, outbound_allowed=True)
+ try:
+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
+ with pytest.raises(SendError):
+ svc.send(
+ title="t",
+ body="b",
+ service_urls=f"ntfy://ntfyhost.example:{hook_port}/topic",
+ )
+ assert hook_hits, "initial request to the ntfy host never happened"
+ assert not target_hits, (
+ f"ntfy redirect was FOLLOWED to the target (hits={target_hits}) "
+ "— redirect-disable did not apply to the plugin"
+ )
+ finally:
+ hook_server.shutdown()
+ target_server.shutdown()
+
+
+# ==========================================================================
+# test_service (admin "Send Test Notification") is guarded like send()
+# ==========================================================================
+def test_test_service_rebind_to_metadata_blocked_through_apprise():
+ """The admin "Send Test Notification" path (``test_service``) runs through
+ the SAME guarded core (:meth:`NotificationService._guarded_notify`) as the
+ real send, so a plugin-scheme host that validates public but rebinds to
+ cloud-metadata at send time is refused: the block-private window raises a
+ gaierror on the send-time resolution (Apprise swallows it), NO connection
+ to the metadata IP is made, and ``test_service`` reports failure. The
+ consume_ssrf_block cosmetic then surfaces the SPECIFIC SSRF-block reason to
+ the admin instead of the generic "Failed to send" message.
+
+ Teeth: pass ``guard_factory=None`` to ``_guarded_notify`` in
+ ``test_service`` (drop the pin/block window) and Apprise resolves
+ ``rebind.example`` to ``169.254.169.254`` and connects to it — the connect
+ spy sees the metadata IP and this test fails. Dropping only the
+ consume_ssrf_block branch makes the error revert to the generic message
+ and the reason assertion fails."""
+ resolver = _Resolver(
+ {"rebind.example": [["93.184.216.34"], ["169.254.169.254"]]}
+ )
+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
+ with _connect_spy() as targets:
+ result = _service().test_service("ntfy://rebind.example/mytopic")
+ assert result["success"] is False
+ assert not any(addr[0] == "169.254.169.254" for addr in targets), (
+ f"connected to metadata IP: {targets}"
+ )
+ # Cosmetic: the specific SSRF-block reason is surfaced (consume_ssrf_block),
+ # not the generic delivery-failure message.
+ assert "SSRF" in result["error"], (
+ f"expected the specific SSRF-block reason, got: {result['error']!r}"
+ )
+
+
+def test_test_service_selfhosted_loopback_delivers():
+ """Counterpart to the block test: ``test_service`` against a self-hosted
+ loopback plugin endpoint still delivers end-to-end through the real
+ Apprise + requests stack (the lenient partition permits private/loopback;
+ only metadata / link-local are refused)."""
+ server, port, hits = _start_server()
+ resolver = _Resolver({"lan.example": [["127.0.0.1"]]})
+ svc = NotificationService(allow_private_ips=True, outbound_allowed=True)
+ try:
+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
+ result = svc.test_service(f"ntfy://lan.example:{port}/topic")
+ assert result["success"] is True, result
+ assert hits, "self-hosted loopback endpoint never received the POST"
+ finally:
+ server.shutdown()
+
+
+# ==========================================================================
+# IPv6 IMDS (fd00:ec2::254) refused end-to-end through send() (sockaddr path)
+# ==========================================================================
+def test_ipv6_imds_rebind_refused_through_send():
+ """End-to-end IPv6 sockaddr path: a raw-webhook (json) host that validates
+ to a public IPv6 but rebinds to AWS's IPv6 IMDS (``fd00:ec2::254``) at the
+ guarded pin is refused before any connection — the IPv6 analogue of
+ ``test_rebind_to_metadata_blocked_through_apprise``. The pin's connect-time
+ re-validation catches the rebind (the cloud-metadata block is absolute even
+ under allow_private_ips=True, which permits the fc00::/7 ULA the address
+ sits in) and raises the SSRF ValueError, wrapped as SendError.
+
+ Teeth: drop the ``is_ip_blocked`` check in
+ ``dns_pinning._resolve_and_validate`` (or remove ``fd00:ec2::254`` from
+ ``ALWAYS_BLOCKED_METADATA_IPS``) and the send connects to the IPv6 IMDS —
+ the connect spy sees it and this test fails."""
+ resolver = _Resolver(
+ {
+ "rebind6.example": [
+ ["2606:2800:220:1:248:1893:25c8:1946"], # public IPv6
+ ["fd00:ec2::254"], # AWS IPv6 IMDS
+ ]
+ }
+ )
+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
+ with _connect_spy() as targets:
+ with pytest.raises(SendError):
+ _service().send(
+ title="t",
+ body="b",
+ service_urls="json://rebind6.example/notify",
+ )
+ assert not any(str(addr[0]) == "fd00:ec2::254" for addr in targets), (
+ f"connected to IPv6 IMDS: {targets}"
+ )
+
+
+# ==========================================================================
+# Fix 1: link-local blocked for the lenient notification partition even under
+# allow_private_ips=True (metadata beyond the always-blocked literals), while
+# RFC1918 self-hosted notifiers keep working.
+# ==========================================================================
+def test_link_local_refused_by_notification_block_window():
+ """An UNPINNED lookup that resolves into the link-local range (Scaleway's
+ metadata ``169.254.42.42`` is the canonical example — NOT one of the six
+ always-blocked literals) is refused by the notification block-private
+ window when ``block_link_local=True``, even though allow_private_ips=True
+ permits RFC1918. Teeth: drop ``block_link_local`` and this lookup
+ resolves normally (link-local is otherwise allowed under the private-IP
+ opt-in)."""
+ resolver = _Resolver({"scaleway.example": [["169.254.42.42"]]})
+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
+ with dns_pinning.block_private_resolution(
+ allow_private_ips=True, block_link_local=True
+ ):
+ with pytest.raises(socket.gaierror):
+ socket.getaddrinfo("scaleway.example", 80)
+
+
+def test_ipv6_link_local_refused_by_notification_block_window():
+ """IPv6 link-local (fe80::/10) is likewise refused under
+ ``block_link_local=True`` even with allow_private_ips=True."""
+ resolver = _Resolver({"ll6.example": [["fe80::1"]]})
+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
+ with dns_pinning.block_private_resolution(
+ allow_private_ips=True, block_link_local=True
+ ):
+ with pytest.raises(socket.gaierror):
+ socket.getaddrinfo("ll6.example", 80)
+
+
+def test_rfc1918_still_allowed_under_block_link_local():
+ """``block_link_local=True`` must NOT over-block: RFC1918 / loopback /
+ non-link-local ULA self-hosted notifiers still resolve under the lenient
+ partition. Only link-local is refused."""
+ resolver = _Resolver(
+ {
+ "lan.example": [["10.11.12.13"]],
+ "lan2.example": [["192.168.1.5"]],
+ "loop.example": [["127.0.0.1"]],
+ "ula.example": [["fd00::1"]],
+ }
+ )
+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
+ with dns_pinning.block_private_resolution(
+ allow_private_ips=True, block_link_local=True
+ ):
+ assert (
+ socket.getaddrinfo("lan.example", 80)[0][4][0] == "10.11.12.13"
+ )
+ assert (
+ socket.getaddrinfo("lan2.example", 80)[0][4][0] == "192.168.1.5"
+ )
+ assert (
+ socket.getaddrinfo("loop.example", 80)[0][4][0] == "127.0.0.1"
+ )
+ assert socket.getaddrinfo("ula.example", 80)[0][4][0] == "fd00::1"
+
+
+def test_link_local_scaleway_pin_rejects_rebind():
+ """A pinnable raw-webhook host that rebinds INTO link-local at pin time is
+ refused (fail closed) under ``block_link_local=True`` — the connect-time
+ re-validation catches metadata that lives in link-local beyond the
+ always-blocked literals."""
+ resolver = _Resolver({"hook.example": [["169.254.42.42"]]})
+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
+ with pytest.raises(ValueError, match="SSRF"):
+ with dns_pinning.pin_hosts(
+ ["json://hook.example/x"],
+ allow_private_ips=True,
+ block_link_local=True,
+ ):
+ pass
+
+
+def test_scaleway_link_local_refused_end_to_end_through_send():
+ """End-to-end: ``send()`` refuses a json:// webhook whose IP-literal host
+ is a link-local metadata address (Scaleway ``169.254.42.42``). The
+ validator's plugin-scheme IMDS guard rejects it pre-send, so ``send``
+ raises ServiceError and no connection is made to the link-local IP."""
+ resolver = _Resolver({})
+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
+ with _connect_spy() as targets:
+ with pytest.raises(ServiceError):
+ _service().send(
+ title="t",
+ body="b",
+ service_urls="json://169.254.42.42/notify",
+ )
+ assert not any(addr[0] == "169.254.42.42" for addr in targets), targets
+
+
+def test_rfc1918_json_webhook_still_delivers_end_to_end():
+ """The link-local block does not regress self-hosted delivery: a json://
+ webhook on an RFC1918 host still delivers end-to-end through the lenient
+ partition (loopback stands in for the private endpoint)."""
+ server, port, hits = _start_server()
+ resolver = _Resolver({"lan.example": [["127.0.0.1"]]})
+ svc = NotificationService(allow_private_ips=True, outbound_allowed=True)
+ try:
+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
+ result = svc.send(
+ title="t",
+ body="b",
+ service_urls=f"json://lan.example:{port}/notify",
+ )
+ assert result is True
+ assert hits, "RFC1918 self-hosted webhook never received the POST"
+ finally:
+ server.shutdown()
+
+
+# ==========================================================================
+# WIRING locks: block_link_local=True is threaded through the two
+# notification send call sites themselves (service.py's ``_dispatch``
+# lenient partition and ``test_service``'s guard factory) — not just
+# present somewhere in the shared ``is_ip_blocked`` / validator machinery.
+#
+# Every test above that exercises link-local either drives the primitives
+# directly (``dns_pinning.block_private_resolution`` /
+# ``dns_pinning.pin_hosts``) or uses an IP-LITERAL URL
+# (``test_scaleway_link_local_refused_end_to_end_through_send``), which the
+# validator's plugin-scheme IMDS guard rejects PRE-SEND — ``_dispatch`` /
+# ``pinned_notification_send`` is never reached. So none of them would
+# notice if ``block_link_local=True`` were dropped at either call site while
+# the shared validator/``is_ip_blocked`` stayed intact.
+#
+# These tests use a HOSTNAME that validates PUBLIC (the validator's own
+# resolution, call #1 of the scripted resolver) but rebinds to a link-local
+# address that is NOT one of the six always-blocked metadata literals (call
+# #2, at the guarded send call site itself) — Scaleway's ``169.254.42.42``
+# / 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.
+# ==========================================================================
+def test_link_local_rebind_refused_by_dispatch_lenient_partition():
+ """WIRING lock for ``_dispatch``'s lenient-partition
+ ``block_link_local=True`` (``notifications/service.py`` ~line 535).
+
+ ``ll-rebind.example`` validates PUBLIC at ``send()``'s pre-send
+ validation (resolver call #1) but rebinds to Scaleway's link-local
+ metadata 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
+ ``block_link_local=True`` into that same ``pinned_notification_send``
+ call. ``send()`` must refuse it and no connection may reach the
+ link-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
+ fails — the rebind pins successfully and the connect spy sees
+ 169.254.42.42.
+ """
+ resolver = _Resolver(
+ {"ll-rebind.example": [["93.184.216.34"], ["169.254.42.42"]]}
+ )
+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
+ with _connect_spy() as targets:
+ with pytest.raises(SendError):
+ _service().send(
+ title="t",
+ body="b",
+ service_urls="json://ll-rebind.example/notify",
+ )
+ assert not any(addr[0] == "169.254.42.42" for addr in targets), (
+ f"connected to link-local IP: {targets}"
+ )
+
+
+def test_link_local_rebind_refused_by_dispatch_lenient_partition_ipv6():
+ """IPv6 analogue of the test above: ``ll-rebind6.example`` validates
+ public IPv6 (resolver call #1) but rebinds to a bare IPv6 link-local
+ address ``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``."""
+ resolver = _Resolver(
+ {
+ "ll-rebind6.example": [
+ ["2606:2800:220:1:248:1893:25c8:1946"], # public IPv6
+ ["fe80::1"], # IPv6 link-local
+ ]
+ }
+ )
+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
+ with _connect_spy() as targets:
+ with pytest.raises(SendError):
+ _service().send(
+ title="t",
+ body="b",
+ service_urls="json://ll-rebind6.example/notify",
+ )
+ assert not any(str(addr[0]) == "fe80::1" for addr in targets), (
+ f"connected to IPv6 link-local IP: {targets}"
+ )
+
+
+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).
+
+ ``ntfy://`` is a plugin scheme (not in ``_PINNABLE_SCHEMES``), so
+ ``pin_hosts`` never resolves/pins it; the send-time lookup instead runs
+ under the block-private WINDOW (``block_private_resolution``), which
+ consults the SAME ``block_link_local`` flag ``test_service`` threads
+ into its guard factory. The host validates public at ``test_service``'s
+ pre-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.
+ """
+ resolver = _Resolver(
+ {"ll-rebind-ts.example": [["93.184.216.34"], ["169.254.42.42"]]}
+ )
+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
+ with _connect_spy() as targets:
+ result = _service().test_service(
+ "ntfy://ll-rebind-ts.example/mytopic"
+ )
+ assert result["success"] is False
+ assert not any(addr[0] == "169.254.42.42" for addr in targets), (
+ f"connected to link-local IP: {targets}"
+ )
+ # Cosmetic corroboration that the block-private WINDOW (not some other
+ # failure) is what fired.
+ assert "SSRF" in result["error"], (
+ f"expected the specific SSRF-block reason, got: {result['error']!r}"
+ )
+
+
+# ==========================================================================
+# Fix 2: empty-authority notification URLs (host smuggled into the path) are
+# rejected at the validator before send.
+# ==========================================================================
+def test_empty_authority_metadata_in_path_rejected_before_send():
+ """``json:///169.254.169.254/path`` has an empty ``//`` authority:
+ urllib3/requests see no host (so the validator's IP check would be
+ skipped) but Apprise dials the in-path host ``169.254.169.254``. The
+ empty-authority guard rejects it at validation, so ``send`` raises
+ ServiceError and no connection to the metadata IP is made."""
+ resolver = _Resolver({})
+ with patch.object(dns_pinning, "_real_getaddrinfo", resolver):
+ with _connect_spy() as targets:
+ with pytest.raises(ServiceError):
+ _service().send(
+ title="t",
+ body="b",
+ service_urls="json:///169.254.169.254/path",
+ )
+ assert not any(addr[0] == "169.254.169.254" for addr in targets), targets
diff --git a/tests/search_engines/test_base_helpers.py b/tests/search_engines/test_base_helpers.py
index bb0b3c5edc..14bb79d1a8 100644
--- a/tests/search_engines/test_base_helpers.py
+++ b/tests/search_engines/test_base_helpers.py
@@ -14,10 +14,10 @@ from unittest.mock import Mock, patch
import pytest
-from src.local_deep_research.web_search_engines.search_engine_base import (
+from local_deep_research.web_search_engines.search_engine_base import (
BaseSearchEngine,
)
-from src.local_deep_research.web_search_engines.rate_limiting import (
+from local_deep_research.web_search_engines.rate_limiting import (
RateLimitError,
)
diff --git a/tests/security/test_notification_validator.py b/tests/security/test_notification_validator.py
index 66ac7161ed..d2cdf208e9 100644
--- a/tests/security/test_notification_validator.py
+++ b/tests/security/test_notification_validator.py
@@ -390,6 +390,47 @@ class TestParserDifferentialBypass:
assert is_valid is True
assert error is None
+ def test_multi_at_authority_rejected(self):
+ """A second '@' in the authority is a parser-differential SSRF:
+ urllib3 (the validator/pin parser) reads the host after the LAST
+ '@' (``decoy-public.example.com``) while Apprise's own parser reads
+ ``169.254.169.254`` and connects there. Reject any authority with
+ more than one '@' before the host is ever extracted (fail closed)."""
+ is_valid, error = NotificationURLValidator.validate_service_url(
+ "json://[email protected]@decoy-public.example.com/path",
+ allow_private_ips=True,
+ )
+ assert is_valid is False
+ assert error is not None
+ assert "@" in error
+
+ def test_multi_at_authority_rejected_http_scheme(self):
+ is_valid, _ = NotificationURLValidator.validate_service_url(
+ "http://a@[email protected]/x"
+ )
+ assert is_valid is False
+
+ def test_single_at_userinfo_still_allowed(self):
+ """A single '@' (RFC 3986 userinfo) is legitimate and must not be
+ collateral damage of the multi-'@' rejection."""
+ for url in (
+ "json://[email protected]/path",
+ "json://user:[email protected]/path",
+ "mailto://user:[email protected]",
+ ):
+ is_valid, error = NotificationURLValidator.validate_service_url(
+ url, allow_private_ips=True
+ )
+ assert is_valid is True, (url, error)
+
+ def test_at_in_query_not_counted(self):
+ """The multi-'@' check counts only the authority (urlparse netloc),
+ so an '@' in the query string is not a rejection cause."""
+ is_valid, error = NotificationURLValidator.validate_service_url(
+ "json://hook.example.com/path?to=a@b@c", allow_private_ips=True
+ )
+ assert is_valid is True, error
+
def test_apprise_signal_url_accepted(self):
"""signal:// (Apprise's Signal-API-REST transport) is allowed.
@@ -552,6 +593,170 @@ class TestCloudMetadataBlockedForPluginSchemes:
assert "cloud-metadata" in error.lower()
+class TestLinkLocalBlockedForPluginSchemes:
+ """Plugin-scheme link-local guard (metadata beyond the always-blocked
+ literals).
+
+ The lenient plugin/raw-webhook partition runs with
+ ``allow_private_ips=True`` so self-hosted LAN notifiers work. But
+ cloud-provider metadata lives across the WHOLE link-local range
+ (169.254.0.0/16, fe80::/10), not just the six always-blocked literals
+ (e.g. Scaleway's 169.254.42.42). ``validate_service_url`` must reject
+ any link-local plugin-scheme target while still allowing RFC1918 /
+ loopback / non-link-local ULA.
+ """
+
+ # Link-local metadata / auto-config addresses that are NOT in
+ # ALWAYS_BLOCKED_METADATA_IPS — these were reachable before the fix.
+ LINK_LOCAL_IPS = (
+ "169.254.42.42", # Scaleway metadata (verified reachable pre-fix)
+ "169.254.1.1",
+ "169.254.255.254",
+ )
+ PLUGIN_SCHEMES = ("json", "xml", "form", "signal", "gotify", "ntfy")
+
+ @pytest.mark.parametrize("ip", LINK_LOCAL_IPS)
+ @pytest.mark.parametrize("scheme", PLUGIN_SCHEMES)
+ def test_ipv4_link_local_blocked_even_with_allow_private_ips(
+ self, scheme, ip
+ ):
+ url = f"{scheme}://{ip}/path"
+ is_valid, error = NotificationURLValidator.validate_service_url(
+ url, allow_private_ips=True
+ )
+ assert is_valid is False, f"{url} should be blocked"
+ assert "link-local" in error.lower()
+
+ def test_ipv6_link_local_blocked(self):
+ is_valid, error = NotificationURLValidator.validate_service_url(
+ "json://[fe80::1]/path", allow_private_ips=True
+ )
+ assert is_valid is False
+ assert "link-local" in error.lower()
+
+ def test_rfc1918_still_allowed(self):
+ for url in (
+ "json://10.11.12.13/hook",
+ "json://172.16.5.5/hook",
+ "json://192.168.50.20/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_loopback_and_ula_still_allowed(self):
+ for url in ("json://127.0.0.1/hook", "json://[fd00::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(
+ "http://169.254.1.1/x", allow_private_ips=True
+ )
+ assert is_valid is True
+
+
+class TestEmptyAuthorityRejected:
+ """Empty-authority parser-differential SSRF (host smuggled into path).
+
+ ``json:///169.254.169.254/path`` has an empty ``//`` authority:
+ urllib3/requests see no host (the IP check is skipped) while Apprise
+ dials the first path segment as the host. ``validate_service_url``
+ rejects any empty-authority ``scheme://`` URL before host extraction,
+ without breaking legitimate URLs.
+ """
+
+ @pytest.mark.parametrize(
+ "url",
+ [
+ "json:///169.254.169.254/path",
+ "xml:///10.0.0.1/x",
+ "form:///metadata",
+ "https:///example.com/webhook",
+ "json:///path-only",
+ ],
+ )
+ def test_empty_authority_rejected(self, url):
+ is_valid, error = NotificationURLValidator.validate_service_url(
+ url, allow_private_ips=True
+ )
+ assert is_valid is False, f"{url} should be rejected"
+ assert "empty" in error.lower()
+
+ @pytest.mark.parametrize(
+ "url",
+ [
+ "json://host.example/path",
+ "json://169.254.169.254.example/path", # host, not empty authority
+ "mailto://user:[email protected]",
+ "ntfy://host.example/topic",
+ "discord://webhook_id/token",
+ "slack://TestApp@TokenA/TokenB/TokenC",
+ "https://example.com/webhook",
+ "signal://192.168.50.20:8739/+15551234567/+15557654321",
+ ],
+ )
+ def test_legit_urls_with_authority_still_pass(self, url):
+ is_valid, error = NotificationURLValidator.validate_service_url(
+ url, allow_private_ips=True
+ )
+ assert is_valid is True, f"{url} should pass, got: {error}"
+
+
+class TestEmptyHostAuthorityRejected:
+ """Non-empty ``//`` authority that urllib3 parses to an EMPTY host.
+
+ ``json://169.254.169.254:80@/`` smuggles an IP into the userinfo with
+ nothing after the trailing ``@``: urllib3 returns no host, so the
+ per-scheme private-IP check (guarded on ``if hostname``) is skipped and the
+ URL would be accepted, yet the authority still carries a target another
+ parser could dial. Sibling of the multi-``@`` / empty-``//``-authority
+ guards — rejected fail-closed before the scheme checks.
+ """
+
+ def test_ip_in_userinfo_empty_host_rejected(self):
+ is_valid, error = NotificationURLValidator.validate_service_url(
+ "json://169.254.169.254:80@/", allow_private_ips=True
+ )
+ assert is_valid is False
+ assert "host" in error.lower()
+
+ @pytest.mark.parametrize(
+ "url",
+ [
+ "json://169.254.169.254:80@/",
+ "json://169.254.169.254@",
+ "xml://10.0.0.5:443@/x",
+ ],
+ )
+ def test_empty_host_variants_rejected(self, url):
+ is_valid, _ = NotificationURLValidator.validate_service_url(
+ url, allow_private_ips=True
+ )
+ assert is_valid is False, f"{url} should be rejected"
+
+
+class TestAllowedSchemesRawSocketRegression:
+ """``ALLOWED_SCHEMES`` gates which Apprise schemes reach the guarded send
+ path. A scheme whose plugin does network I/O via a primitive the DNS-pin
+ shim cannot see — a raw ``socket.sendto`` datagram (``rsyslog://``) or
+ similar — would bypass BOTH the address pin and the block-private window.
+ Lock such schemes out of the allowlist so one can't be added later without
+ matching pin/block coverage.
+ """
+
+ @pytest.mark.parametrize("scheme", ["rsyslog", "aprs", "syslog", "xmpp"])
+ def test_raw_socket_scheme_not_allowed(self, scheme):
+ assert scheme not in NotificationURLValidator.ALLOWED_SCHEMES
+
+
class TestValidateServiceUrlStrict:
"""Tests for validate_service_url_strict static method."""
diff --git a/tests/security/test_ssrf_validator.py b/tests/security/test_ssrf_validator.py
index e4b9725008..b02cf841b4 100644
--- a/tests/security/test_ssrf_validator.py
+++ b/tests/security/test_ssrf_validator.py
@@ -126,7 +126,7 @@ class TestIsIpBlocked:
def test_cgnat_blocked_by_default(self):
"""CGNAT addresses (100.64.x.x) should be blocked by default."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
is_ip_blocked,
)
@@ -136,7 +136,7 @@ class TestIsIpBlocked:
def test_cgnat_allowed_with_allow_private_ips(self):
"""CGNAT addresses (100.64.x.x) should be allowed with allow_private_ips=True."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
is_ip_blocked,
)
@@ -147,7 +147,7 @@ class TestIsIpBlocked:
def test_link_local_allowed_with_allow_private_ips(self):
"""Link-local addresses (169.254.x.x) should be allowed with allow_private_ips=True."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
is_ip_blocked,
)
@@ -159,7 +159,7 @@ class TestIsIpBlocked:
def test_ipv6_ula_blocked_by_default(self):
"""IPv6 Unique Local Addresses (fc00::/7) should be blocked by default."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
is_ip_blocked,
)
@@ -168,7 +168,7 @@ class TestIsIpBlocked:
def test_ipv6_ula_allowed_with_allow_private_ips(self):
"""IPv6 ULA (fc00::/7) should be allowed with allow_private_ips=True."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
is_ip_blocked,
)
@@ -177,7 +177,7 @@ class TestIsIpBlocked:
def test_ipv6_link_local_blocked_by_default(self):
"""IPv6 link-local addresses (fe80::/10) should be blocked by default."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
is_ip_blocked,
)
@@ -186,7 +186,7 @@ class TestIsIpBlocked:
def test_ipv6_link_local_allowed_with_allow_private_ips(self):
"""IPv6 link-local (fe80::/10) should be allowed with allow_private_ips=True."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
is_ip_blocked,
)
@@ -384,7 +384,7 @@ class TestContainerNetworking:
def test_podman_host_containers_internal(self):
"""Podman's host.containers.internal (resolves to CGNAT) should work with allow_private_ips."""
- from src.local_deep_research.security.ssrf_validator import validate_url
+ from local_deep_research.security.ssrf_validator import validate_url
with patch("socket.getaddrinfo") as mock_getaddrinfo:
# Podman rootless containers typically resolve host.containers.internal to 100.64.x.x
@@ -399,7 +399,7 @@ class TestContainerNetworking:
def test_ollama_in_podman(self):
"""Ollama running on host accessible via Podman's CGNAT should work."""
- from src.local_deep_research.security.ssrf_validator import validate_url
+ from local_deep_research.security.ssrf_validator import validate_url
with patch("socket.getaddrinfo") as mock_getaddrinfo:
# Ollama on host via Podman CGNAT
@@ -416,7 +416,7 @@ class TestContainerNetworking:
def test_searxng_in_podman(self):
"""SearXNG running on host accessible via Podman's CGNAT should work."""
- from src.local_deep_research.security.ssrf_validator import validate_url
+ from local_deep_research.security.ssrf_validator import validate_url
with patch("socket.getaddrinfo") as mock_getaddrinfo:
# SearXNG on host via Podman CGNAT
@@ -431,7 +431,7 @@ class TestContainerNetworking:
def test_cgnat_url_blocked_by_default(self):
"""CGNAT URLs should be blocked by default (without allow_private_ips)."""
- from src.local_deep_research.security.ssrf_validator import validate_url
+ from local_deep_research.security.ssrf_validator import validate_url
# Direct CGNAT IP
assert validate_url("http://100.64.0.1:8080") is False
@@ -444,7 +444,7 @@ class TestContainerNetworking:
def test_docker_bridge_network(self):
"""Docker bridge network IPs should work with allow_private_ips."""
- from src.local_deep_research.security.ssrf_validator import validate_url
+ from local_deep_research.security.ssrf_validator import validate_url
# Docker typically uses 172.17.x.x for bridge network
assert (
@@ -472,91 +472,91 @@ class TestParserDifferentialBypass:
def test_advisory_canonical_payload(self):
"""The exact PoC from the advisory must be rejected."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
assert validate_url("http://127.0.0.1:6666\\@1.1.1.1") is False
def test_backslash_no_port(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
assert validate_url("http://127.0.0.1\\@1.1.1.1") is False
def test_double_backslash(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
assert validate_url("http://127.0.0.1\\\\@1.1.1.1") is False
def test_slash_then_backslash(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
assert validate_url("http://127.0.0.1/\\@1.1.1.1") is False
def test_tab_at_seam(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
assert validate_url("http://127.0.0.1\[email protected]") is False
def test_carriage_return_at_seam(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
assert validate_url("http://127.0.0.1\[email protected]") is False
def test_newline_at_seam(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
assert validate_url("http://127.0.0.1\[email protected]") is False
def test_space_at_seam(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
assert validate_url("http://127.0.0.1 @1.1.1.1") is False
def test_ipv6_loopback_with_backslash(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
assert validate_url("http://[::1]\\@1.1.1.1") is False
def test_ipv4_mapped_ipv6_with_backslash(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
assert validate_url("http://[::ffff:127.0.0.1]\\@1.1.1.1") is False
def test_backslash_with_trailing_port(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
assert validate_url("http://127.0.0.1\\@1.1.1.1:80") is False
def test_trailing_dot_loopback_with_backslash(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
assert validate_url("http://127.0.0.1.\\@1.1.1.1") is False
def test_null_byte_in_userinfo(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -564,7 +564,7 @@ class TestParserDifferentialBypass:
def test_idn_unicode_host_rejected(self):
"""IDN/Unicode hosts are rejected by urllib3 / ASCII guard."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -575,7 +575,7 @@ class TestParserDifferentialBypass:
def test_octal_ip_resolves_to_loopback(self):
"""Octal IP form '0177.0.0.1' resolves to 127.0.0.1 via getaddrinfo."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -587,7 +587,7 @@ class TestParserDifferentialBypass:
def test_decimal_int_ip_resolves_to_loopback(self):
"""Decimal-int IP form '2130706433' resolves to 127.0.0.1."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -605,35 +605,35 @@ class TestParserDifferentialBypass:
Layer 1 doesn't match ``%5C`` (it's three printable ASCII chars);
Layer 2 is the load-bearing defence on the SafeSession.send path.
"""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
assert validate_url("http://127.0.0.1:6666/%[email protected]") is False
def test_backslash_deep_in_path(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
assert validate_url("http://example.com/path\\@1.1.1.1") is False
def test_backslash_in_userinfo_password(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
assert validate_url("http://user:pass\\@127.0.0.1/") is False
def test_backslash_with_port_on_trailing_host(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
assert validate_url("http://127.0.0.1\\@evil.com:8080") is False
def test_interior_whitespace_at_seam(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -644,7 +644,7 @@ class TestParserDifferentialBypass:
connections to ``[::]:port`` to a service bound on ``[::1]:port``,
so it must be blocked alongside ``0.0.0.0`` (the IPv4 equivalent,
already covered via 0.0.0.0/8 in BLOCKED_IP_RANGES)."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -654,7 +654,7 @@ class TestParserDifferentialBypass:
"""Equivalent representation ``0::`` — must normalise to ``::``
before the IP-range check or this bypasses the literal-string
allow-list in notification_validator."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -662,7 +662,7 @@ class TestParserDifferentialBypass:
def test_ipv6_unspecified_full_form_blocked(self):
"""Equivalent representation ``0:0:0:0:0:0:0:0``."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -680,7 +680,7 @@ class TestDnsResolvedBypass:
"""
def test_hostname_resolving_to_loopback_blocked(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -691,7 +691,7 @@ class TestDnsResolvedBypass:
assert validate_url("http://attacker.example.com/") is False
def test_hostname_resolving_to_rfc1918_blocked(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -702,7 +702,7 @@ class TestDnsResolvedBypass:
assert validate_url("http://attacker.example.com/") is False
def test_hostname_resolving_to_link_local_blocked(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -714,7 +714,7 @@ class TestDnsResolvedBypass:
def test_hostname_resolving_to_aws_metadata_blocked(self):
"""Hardcoded AWS metadata block fires even with allow_private_ips."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -735,7 +735,7 @@ class TestDnsResolvedBypass:
DNS returning a public IP first then a private IP must still block.
Round-robin / multi-A-record DNS could otherwise be a bypass.
"""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -750,7 +750,7 @@ class TestDnsResolvedBypass:
def test_dns_resolution_failure_fails_closed(self):
"""``getaddrinfo`` raising ``gaierror`` must return False (not allow)."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -759,7 +759,7 @@ class TestDnsResolvedBypass:
def test_ipv6_dns_resolution_to_loopback_blocked(self):
"""Hostname resolving to IPv6 ``::1`` must be blocked."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -774,7 +774,7 @@ class TestDnsResolvedBypass:
Hostname resolving to ``::ffff:127.0.0.1`` (IPv4-mapped IPv6) must
be blocked — exercises the IPv4-mapped unwrap in is_ip_blocked.
"""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -794,7 +794,7 @@ class TestAlternateIpFormsBlocked:
def test_octal_loopback_blocked(self):
"""``0177.0.0.1`` → ``127.0.0.1`` via getaddrinfo on Linux."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -805,7 +805,7 @@ class TestAlternateIpFormsBlocked:
assert validate_url("http://0177.0.0.1/") is False
def test_decimal_int_loopback_blocked(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -817,7 +817,7 @@ class TestAlternateIpFormsBlocked:
def test_short_ipv4_form_loopback_blocked(self):
"""``127.1`` (short form) → ``127.0.0.1`` via getaddrinfo on Linux."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -829,7 +829,7 @@ class TestAlternateIpFormsBlocked:
def test_ipv4_mapped_ipv6_loopback_literal_blocked(self):
"""``[::ffff:127.0.0.1]`` is an IPv4-mapped IPv6 of loopback."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -837,7 +837,7 @@ class TestAlternateIpFormsBlocked:
def test_ipv4_mapped_ipv6_rfc1918_literal_blocked(self):
"""``[::ffff:10.0.0.1]`` — IPv4-mapped IPv6 of RFC1918."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -845,7 +845,7 @@ class TestAlternateIpFormsBlocked:
def test_ipv4_mapped_ipv6_aws_metadata_literal_blocked(self):
"""``[::ffff:169.254.169.254]`` — AWS metadata via mapped IPv6."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -860,28 +860,28 @@ class TestAllowFlagMatrix:
"""
def test_loopback_default_blocked(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
assert validate_url("http://127.0.0.1/") is False
def test_loopback_with_allow_localhost(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
assert validate_url("http://127.0.0.1/", allow_localhost=True) is True
def test_loopback_with_allow_private_ips(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
assert validate_url("http://127.0.0.1/", allow_private_ips=True) is True
def test_ipv6_loopback_with_allow_localhost(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -895,7 +895,7 @@ class TestAllowFlagMatrix:
``allow_localhost`` is therefore conservatively scoped to
``::1`` and ``127.0.0.0/8`` and does NOT permit ``::``.
"""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -903,14 +903,14 @@ class TestAllowFlagMatrix:
def test_ipv6_unspecified_blocked_even_with_allow_private_ips(self):
"""Same reasoning: ``::`` is not in any allowed-range carve-out."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
assert validate_url("http://[::]/", allow_private_ips=True) is False
def test_aws_metadata_blocked_under_allow_localhost(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -924,7 +924,7 @@ class TestAllowFlagMatrix:
Codebase comments call this out as ALWAYS blocked. Locks in that
the most permissive flag still doesn't reach AWS metadata.
"""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -937,6 +937,26 @@ class TestAllowFlagMatrix:
class TestAlwaysBlockedMetadataIPs:
"""Cloud-metadata IPs blocked under every flag combination."""
+ def test_aws_ipv6_imds_blocked_under_all_flags(self):
+ """AWS's native IPv6 IMDS endpoint (fd00:ec2::254) is a ULA
+ (fc00::/7), NOT an IPv4-mapped / NAT64-wrapped form of
+ 169.254.169.254, so it is not covered by the IPv4 entries or the
+ NAT64 embedded-IPv4 check and must be listed explicitly. It must be
+ blocked under every flag combination — most importantly
+ allow_private_ips=True, which otherwise permits the whole fc00::/7
+ ULA range. Any textual variant normalizes to the canonical form
+ before the membership test."""
+ from local_deep_research.security.ssrf_validator import is_ip_blocked
+
+ for variant in (
+ "fd00:ec2::254",
+ "FD00:EC2::254",
+ "fd00:ec2:0:0:0:0:0:254",
+ ):
+ assert is_ip_blocked(variant) is True
+ assert is_ip_blocked(variant, allow_localhost=True) is True
+ assert is_ip_blocked(variant, allow_private_ips=True) is True
+
def test_metadata_ip_blocked_under_all_flags(self):
"""Every IP in the always-blocked set must be blocked under all
allow-flag combinations."""
@@ -1070,42 +1090,42 @@ class TestSchemeRejection:
"""Non-http(s) schemes must be rejected outright (not just the host check)."""
def test_file_scheme_rejected(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
assert validate_url("file:///etc/passwd") is False
def test_ftp_scheme_rejected(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
assert validate_url("ftp://example.com/") is False
def test_gopher_scheme_rejected(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
assert validate_url("gopher://example.com/") is False
def test_dict_scheme_rejected(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
assert validate_url("dict://example.com:11211/stat") is False
def test_no_scheme_rejected(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
assert validate_url("127.0.0.1") is False
def test_scheme_relative_url_rejected(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1113,7 +1133,7 @@ class TestSchemeRejection:
def test_uppercase_https_scheme_accepted(self):
"""Schemes are case-insensitive per RFC 3986."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1168,7 +1188,7 @@ class TestNeverRaises:
],
)
def test_pathological_input_returns_bool(self, weird_input):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1186,7 +1206,7 @@ class TestIPv6TransitionPrefixesBlocked:
def test_6to4_wrapped_loopback_blocked(self):
"""``[2002:7f00:1::]`` — 6to4 wrap of 127.0.0.1."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1194,7 +1214,7 @@ class TestIPv6TransitionPrefixesBlocked:
def test_6to4_wrapped_rfc1918_blocked(self):
"""``[2002:c0a8:101::]`` — 6to4 wrap of 192.168.1.1."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1202,7 +1222,7 @@ class TestIPv6TransitionPrefixesBlocked:
def test_nat64_wrapped_loopback_blocked(self):
"""``[64:ff9b::7f00:1]`` — NAT64 wrap of 127.0.0.1."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1210,7 +1230,7 @@ class TestIPv6TransitionPrefixesBlocked:
def test_teredo_prefix_blocked(self):
"""Teredo (2001::/32) tunnels IPv6-over-UDP/IPv4."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1218,7 +1238,7 @@ class TestIPv6TransitionPrefixesBlocked:
def test_ipv6_discard_prefix_blocked(self):
"""RFC 6666 discard prefix (100::/64) is reserved for sinkholes."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1229,7 +1249,7 @@ class TestIPv6TransitionPrefixesBlocked:
Cloud metadata is the highest-value SSRF target; the 2002::/16
block is what catches this case (the IMDS hardcoded literal
check is on the IPv4 form only)."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1237,7 +1257,7 @@ class TestIPv6TransitionPrefixesBlocked:
def test_nat64_wraps_aws_metadata_blocked(self):
"""[64:ff9b::a9fe:a9fe] — NAT64 wrap of 169.254.169.254 (AWS IMDS)."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1245,7 +1265,7 @@ class TestIPv6TransitionPrefixesBlocked:
def test_6to4_wraps_rfc1918_class_a_blocked(self):
"""[2002:0a00:1::] — 6to4 wrap of 10.0.0.1."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1253,7 +1273,7 @@ class TestIPv6TransitionPrefixesBlocked:
def test_6to4_wraps_rfc1918_class_b_blocked(self):
"""[2002:ac10:1::] — 6to4 wrap of 172.16.0.1."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1261,7 +1281,7 @@ class TestIPv6TransitionPrefixesBlocked:
def test_nat64_wraps_rfc1918_class_a_blocked(self):
"""[64:ff9b::a00:1] — NAT64 wrap of 10.0.0.1."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1273,7 +1293,7 @@ class TestIPv6TransitionPrefixesBlocked:
the local-use prefix, [64:ff9b:1::a9fe:a9fe] reaches AWS IMDS
identically to the WKP form. Missing this prefix earned a
HackerOne bounty against the Ruby ssrf_filter library."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1281,7 +1301,7 @@ class TestIPv6TransitionPrefixesBlocked:
def test_nat64_local_use_wraps_aws_metadata_blocked(self):
"""[64:ff9b:1::a9fe:a9fe] — local-use NAT64 wrap of 169.254.169.254."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1292,7 +1312,7 @@ class TestIPv6TransitionPrefixesBlocked:
(DEPRECATED 2006). On hosts with ::/96 routes this reaches IMDS
identically to the IPv4-mapped and NAT64-wrapped forms. Same
defense-in-depth class as the transition prefixes."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1300,7 +1320,7 @@ class TestIPv6TransitionPrefixesBlocked:
def test_ipv4_compatible_imds_hex_form_blocked(self):
"""Same address, hex form: [::a9fe:a9fe]."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1308,7 +1328,7 @@ class TestIPv6TransitionPrefixesBlocked:
def test_ipv4_compatible_rfc1918_blocked(self):
"""[::192.168.1.1] — IPv4-Compatible wrap of RFC1918."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1331,42 +1351,42 @@ class TestIPv6TransitionPrefixesAllowFlagMatrix:
"""
def test_6to4_blocked_under_allow_localhost(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
is_ip_blocked,
)
assert is_ip_blocked("2002:7f00:1::", allow_localhost=True) is True
def test_6to4_blocked_under_allow_private_ips(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
is_ip_blocked,
)
assert is_ip_blocked("2002:c0a8:101::", allow_private_ips=True) is True
def test_nat64_blocked_under_allow_localhost(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
is_ip_blocked,
)
assert is_ip_blocked("64:ff9b::7f00:1", allow_localhost=True) is True
def test_nat64_blocked_under_allow_private_ips(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
is_ip_blocked,
)
assert is_ip_blocked("64:ff9b::a00:1", allow_private_ips=True) is True
def test_teredo_blocked_under_allow_private_ips(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
is_ip_blocked,
)
assert is_ip_blocked("2001::1", allow_private_ips=True) is True
def test_discard_blocked_under_allow_private_ips(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
is_ip_blocked,
)
@@ -1375,7 +1395,7 @@ class TestIPv6TransitionPrefixesAllowFlagMatrix:
def test_6to4_aws_metadata_blocked_under_allow_private_ips(self):
"""High-value: even with the most permissive flag, the 6to4 wrap
of AWS IMDS must remain blocked."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1386,7 +1406,7 @@ class TestIPv6TransitionPrefixesAllowFlagMatrix:
def test_nat64_aws_metadata_blocked_under_allow_private_ips(self):
"""Same locking-in for NAT64 wrap of IMDS."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1404,7 +1424,7 @@ class TestIPv6TransitionPrefixesAntiCollision:
def test_google_dns_v6_passes(self):
"""2001:4860:4860::8888 — Google Public DNS. Second hextet 0x4860
is outside the 2001::/32 Teredo block."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1413,7 +1433,7 @@ class TestIPv6TransitionPrefixesAntiCollision:
def test_cloudflare_dns_v6_passes(self):
"""2606:4700:4700::1111 — Cloudflare Public DNS, far from any
transition prefix."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1422,7 +1442,7 @@ class TestIPv6TransitionPrefixesAntiCollision:
def test_root_server_v6_passes(self):
"""2001:500::/30 root-server allocation — second hextet 0x0500
is outside Teredo."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1430,7 +1450,7 @@ class TestIPv6TransitionPrefixesAntiCollision:
def test_he_tunnelbroker_v6_passes(self):
"""2001:470::/32 Hurricane Electric — second hextet 0x0470."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1438,7 +1458,7 @@ class TestIPv6TransitionPrefixesAntiCollision:
def test_neighbor_above_6to4_passes(self):
"""2003::/16 sits adjacent to 2002::/16 but is not in it."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1447,7 +1467,7 @@ class TestIPv6TransitionPrefixesAntiCollision:
def test_discard_prefix_neighbor_passes(self):
"""100:1::/16 sits outside the 100::/64 discard prefix
(second hextet 0x0001)."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1468,7 +1488,7 @@ class TestNat64EnvOptOut:
"""
def test_nat64_wkp_blocked_when_env_unset(self, monkeypatch):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1476,7 +1496,7 @@ class TestNat64EnvOptOut:
assert validate_url("http://[64:ff9b::a00:1]/") is False
def test_nat64_wkp_allowed_when_env_true(self, monkeypatch):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1486,7 +1506,7 @@ class TestNat64EnvOptOut:
assert validate_url("http://[64:ff9b::808:808]/") is True
def test_nat64_local_use_allowed_when_env_true(self, monkeypatch):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1496,7 +1516,7 @@ class TestNat64EnvOptOut:
def test_env_does_not_unblock_6to4(self, monkeypatch):
"""6to4 has no live legitimate use; the operator switch must
not extend to it."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1504,7 +1524,7 @@ class TestNat64EnvOptOut:
assert validate_url("http://[2002:c0a8:101::]/") is False
def test_env_does_not_unblock_teredo(self, monkeypatch):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1512,7 +1532,7 @@ class TestNat64EnvOptOut:
assert validate_url("http://[2001::1]/") is False
def test_env_does_not_unblock_discard(self, monkeypatch):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1523,19 +1543,90 @@ class TestNat64EnvOptOut:
"""The IPv4-form metadata literal is in ALWAYS_BLOCKED_METADATA_IPS
and is checked BEFORE the prefix loop. The NAT64 carve-out
cannot reach it."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
monkeypatch.setenv("LDR_SECURITY_ALLOW_NAT64", "true")
assert validate_url("http://169.254.169.254/") is False
+ def test_env_does_not_unblock_link_local_for_notification_path(self):
+ """NAT64 opt-in must not reopen link-local metadata for the
+ notification send path. ``64:ff9b::a9fe:2a2a`` is the NAT64 wrap of
+ Scaleway's ``169.254.42.42`` (link-local metadata); with
+ ``block_link_local=True`` it stays blocked even under the carve-out,
+ matching how the direct v4 form is blocked."""
+ from local_deep_research.security.ssrf_validator import is_ip_blocked
+
+ # NAT64 well-known prefix wrap of the link-local metadata address.
+ assert (
+ is_ip_blocked(
+ "64:ff9b::a9fe:2a2a",
+ allow_private_ips=True,
+ block_link_local=True,
+ allow_nat64=True,
+ )
+ is True
+ )
+ # RFC 8215 local-use NAT64 prefix wrap of the same address.
+ assert (
+ is_ip_blocked(
+ "64:ff9b:1::a9fe:2a2a",
+ allow_private_ips=True,
+ block_link_local=True,
+ allow_nat64=True,
+ )
+ is True
+ )
+ # Control: the direct v4 link-local form is blocked on this path.
+ assert (
+ is_ip_blocked(
+ "169.254.42.42",
+ allow_private_ips=True,
+ block_link_local=True,
+ allow_nat64=True,
+ )
+ is True
+ )
+
+ def test_env_still_allows_link_local_wrap_for_default_callers(self):
+ """The link-local NAT64 block is gated on ``block_link_local`` (the
+ notification path). Default callers permit link-local under
+ ``allow_private_ips``, so a NAT64-wrapped link-local stays reachable
+ for them under the opt-in — behavior unchanged."""
+ from local_deep_research.security.ssrf_validator import is_ip_blocked
+
+ assert (
+ is_ip_blocked(
+ "64:ff9b::a9fe:2a2a",
+ allow_private_ips=True,
+ allow_nat64=True,
+ )
+ is False
+ )
+
+ def test_link_local_block_does_not_overblock_public_wrap(self):
+ """The link-local carve-out must not over-block: a NAT64-wrapped
+ *public* IPv4 (Google DNS ``8.8.8.8``) is still reachable under the
+ opt-in even with ``block_link_local=True`` — only link-local closes."""
+ from local_deep_research.security.ssrf_validator import is_ip_blocked
+
+ assert (
+ is_ip_blocked(
+ "64:ff9b::808:808",
+ allow_private_ips=True,
+ block_link_local=True,
+ allow_nat64=True,
+ )
+ is False
+ )
+
def test_env_does_not_unblock_imds_via_nat64_wkp_wrap(self, monkeypatch):
"""The IMDS embedded-IPv4 check fires before the NAT64 carve-out:
even with operator opt-in, [64:ff9b::a9fe:a9fe] (NAT64 WKP wrap
of 169.254.169.254) stays blocked. ALWAYS_BLOCKED_METADATA_IPS
is absolute by design."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1546,7 +1637,7 @@ class TestNat64EnvOptOut:
self, monkeypatch
):
"""Same lock-in for the RFC 8215 local-use prefix wrap."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1558,7 +1649,7 @@ class TestNat64EnvOptOut:
):
"""169.254.170.2 (AWS ECS task metadata v3) is also in the
always-blocked set; NAT64 wrap stays blocked under opt-in."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1568,7 +1659,7 @@ class TestNat64EnvOptOut:
def test_env_falsy_values_keep_blocked(self, monkeypatch):
"""'false', '0', and unset must all keep the block in place."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1581,7 +1672,7 @@ class TestNat64EnvOptOut:
def test_env_true_does_not_bypass_loopback_in_block_list(self, monkeypatch):
"""Sanity: opting into NAT64 must not accidentally unblock
non-NAT64 entries that share a prefix family."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
is_ip_blocked,
)
@@ -1593,7 +1684,7 @@ class TestNat64EnvOptOut:
"""The carve-out's ``continue`` lives in the same loop that walks
ULA (fc00::/7) and link-local (fe80::/10). Pin that opting into
NAT64 does not accidentally unblock these adjacent IPv6 ranges."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
is_ip_blocked,
)
@@ -1602,7 +1693,7 @@ class TestNat64EnvOptOut:
assert is_ip_blocked("fd12:3456:789a::1") is True
def test_env_true_does_not_unblock_ipv6_link_local(self, monkeypatch):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
is_ip_blocked,
)
@@ -1622,7 +1713,7 @@ class TestIsNat64WrappedMetadataIp:
that point the address is no longer IPv6 and the NAT64 check
does not apply."""
import ipaddress
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
is_nat64_wrapped_metadata_ip,
)
@@ -1636,7 +1727,7 @@ class TestIsNat64WrappedMetadataIp:
def test_returns_false_for_non_nat64_ipv6(self):
"""Public IPv6 (Google DNS) is not in any NAT64 prefix."""
import ipaddress
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
is_nat64_wrapped_metadata_ip,
)
@@ -1652,7 +1743,7 @@ class TestIsNat64WrappedMetadataIp:
prefix but the embedded IPv4 is not metadata — helper returns
False so the broader carve-out logic can apply."""
import ipaddress
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
is_nat64_wrapped_metadata_ip,
)
@@ -1665,7 +1756,7 @@ class TestIsNat64WrappedMetadataIp:
def test_returns_true_for_imds_via_wkp(self):
import ipaddress
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
is_nat64_wrapped_metadata_ip,
)
@@ -1678,7 +1769,7 @@ class TestIsNat64WrappedMetadataIp:
def test_returns_true_for_imds_via_local_use(self):
import ipaddress
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
is_nat64_wrapped_metadata_ip,
)
@@ -1694,49 +1785,49 @@ class TestValidateUrlEdgeCases:
"""Robustness: validate_url must never raise, only return bool."""
def test_empty_string_returns_false(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
assert validate_url("") is False
def test_whitespace_only_returns_false(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
assert validate_url(" ") is False
def test_tab_newline_only_returns_false(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
assert validate_url("\t\n") is False
def test_none_returns_false(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
assert validate_url(None) is False
def test_int_returns_false(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
assert validate_url(123) is False
def test_malformed_ipv6_no_crash(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
assert validate_url("http://[::") is False
def test_extremely_long_url_no_crash(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1760,7 +1851,7 @@ class TestLegitimateUrlsStillPass:
)
def test_simple_http_url(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1768,7 +1859,7 @@ class TestLegitimateUrlsStillPass:
assert validate_url("http://example.com/") is True
def test_explicit_port(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1776,7 +1867,7 @@ class TestLegitimateUrlsStillPass:
assert validate_url("http://example.com:8080/") is True
def test_userinfo_is_rfc_legal(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1784,7 +1875,7 @@ class TestLegitimateUrlsStillPass:
assert validate_url("http://user:[email protected]/") is True
def test_userinfo_with_port(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1792,7 +1883,7 @@ class TestLegitimateUrlsStillPass:
assert validate_url("http://user:[email protected]:8080/") is True
def test_trailing_dot_hostname(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1800,7 +1891,7 @@ class TestLegitimateUrlsStillPass:
assert validate_url("http://example.com./") is True
def test_path_query_fragment(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1808,7 +1899,7 @@ class TestLegitimateUrlsStillPass:
assert validate_url("http://example.com/path?q=1#frag") is True
def test_plus_in_query_string(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1817,7 +1908,7 @@ class TestLegitimateUrlsStillPass:
def test_encoded_backslash_in_path_is_rfc_legal(self):
"""%5C in a PATH (not a host bypass) is RFC-legal and must pass."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1825,7 +1916,7 @@ class TestLegitimateUrlsStillPass:
assert validate_url("http://example.com/path%5Cfile") is True
def test_encoded_space_in_path(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1837,7 +1928,7 @@ class TestLegitimateUrlsStillPass:
def test_uppercase_hostname_case_folded(self):
"""Locks in case-folding parity between urlparse and urllib3."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1846,7 +1937,7 @@ class TestLegitimateUrlsStillPass:
def test_ipv6_public(self):
"""IPv6 hosts unwrap from brackets and check correctly."""
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1886,7 +1977,7 @@ class TestUnspecifiedIPv4Blocked:
],
)
def test_unspecified_ipv4_literal_blocked(self, url):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1911,7 +2002,7 @@ class TestDnsResolutionNonGaierror:
[PermissionError("eperm"), OSError("eio"), RuntimeError("boom")],
)
def test_non_gaierror_during_dns_fails_closed(self, exc, loguru_caplog):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1941,7 +2032,7 @@ class TestRfcForbiddenControlChars:
["\x01", "\x1f", "\x7f"],
)
def test_control_byte_in_url_rejected(self, ctrl_char):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1963,7 +2054,7 @@ class TestAlternateIpHexForm:
"""
def test_hex_dword_loopback_resolves_and_blocks(self):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -1993,7 +2084,7 @@ class TestPortEdgeCases:
],
)
def test_port_edge_case_blocked(self, url):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -2016,7 +2107,7 @@ class TestMultipleAtSignsContract:
def test_double_at_resolves_to_last_segment(self):
from urllib3.util import parse_url
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -2046,7 +2137,7 @@ class TestUserinfoContainsIpShape:
def test_userinfo_ip_shape_is_not_a_bypass(self):
from urllib3.util import parse_url
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
@@ -2082,7 +2173,7 @@ class TestIpv6ZoneIdBlocked:
],
)
def test_ipv6_zone_id_link_local_blocked(self, url):
- from src.local_deep_research.security.ssrf_validator import (
+ from local_deep_research.security.ssrf_validator import (
validate_url,
)
diff --git a/tests/security/test_ssrf_validator_high_value.py b/tests/security/test_ssrf_validator_high_value.py
index 9d3fafb2bb..09a3a637d0 100644
--- a/tests/security/test_ssrf_validator_high_value.py
+++ b/tests/security/test_ssrf_validator_high_value.py
@@ -85,6 +85,54 @@ class TestIsIpBlockedSpecialRanges:
def test_loopback_also_allowed_with_private_flag(self):
assert is_ip_blocked("127.0.0.1", allow_private_ips=True) is False
+ def test_link_local_blocked_with_block_link_local_flag(self):
+ """block_link_local=True (notification path) keeps the whole
+ link-local range blocked even under allow_private_ips=True —
+ metadata lives there beyond the always-blocked literals (e.g.
+ Scaleway 169.254.42.42)."""
+ assert (
+ is_ip_blocked(
+ "169.254.42.42",
+ allow_private_ips=True,
+ block_link_local=True,
+ )
+ is True
+ )
+ assert (
+ is_ip_blocked(
+ "169.254.1.1", allow_private_ips=True, block_link_local=True
+ )
+ is True
+ )
+ assert (
+ is_ip_blocked(
+ "fe80::1", allow_private_ips=True, block_link_local=True
+ )
+ is True
+ )
+
+ def test_block_link_local_does_not_overblock_rfc1918_loopback_ula(self):
+ """block_link_local must NOT block RFC1918 / CGNAT / loopback /
+ non-link-local ULA — self-hosted notifiers keep working."""
+ for ip in (
+ "10.11.12.13",
+ "172.16.5.5",
+ "192.168.50.20",
+ "100.64.0.1",
+ "127.0.0.1",
+ "fd00::1",
+ ):
+ assert (
+ is_ip_blocked(ip, allow_private_ips=True, block_link_local=True)
+ is False
+ ), ip
+
+ def test_block_link_local_noop_without_private_flag(self):
+ """Without allow_private_ips, link-local is already blocked; the
+ flag changes nothing there (and public stays allowed)."""
+ assert is_ip_blocked("169.254.1.1", block_link_local=True) is True
+ assert is_ip_blocked("93.184.216.34", block_link_local=True) is False
+
class TestIsIpBlockedCloudMetadata:
"""Cloud-provider metadata endpoints always blocked under all flags."""
@@ -291,5 +339,6 @@ class TestConstants:
"169.254.170.23",
"169.254.0.23",
"100.100.100.200",
+ "fd00:ec2::254",
}
)
diff --git a/tests/vector_stores/test_facade_load.py b/tests/vector_stores/test_facade_load.py
index d4defc3275..576c724412 100644
--- a/tests/vector_stores/test_facade_load.py
+++ b/tests/vector_stores/test_facade_load.py
@@ -10,8 +10,8 @@ import threading
import numpy as np
-from src.local_deep_research.vector_stores import get_vector_store_class
-from src.local_deep_research.vector_stores.facade import VectorIndex
+from local_deep_research.vector_stores import get_vector_store_class
+from local_deep_research.vector_stores.facade import VectorIndex
def _noop(_p):
diff --git a/tests/vector_stores/test_faiss_store.py b/tests/vector_stores/test_faiss_store.py
index 98bb0a58a0..8fd3f4ff50 100644
--- a/tests/vector_stores/test_faiss_store.py
+++ b/tests/vector_stores/test_faiss_store.py
@@ -12,7 +12,7 @@ import faiss
import numpy as np
import pytest
-from src.local_deep_research.vector_stores.implementations.faiss_store import (
+from local_deep_research.vector_stores.implementations.faiss_store import (
FaissVectorStore,
)
@@ -332,7 +332,7 @@ class TestPersistLoad:
raise RuntimeError("simulated write_index failure")
monkeypatch.setattr(
- "src.local_deep_research.vector_stores.implementations."
+ "local_deep_research.vector_stores.implementations."
"faiss_store.write_index",
_boom,
)
diff --git a/tests/vector_stores/test_legacy_cleanup_no_plaintext.py b/tests/vector_stores/test_legacy_cleanup_no_plaintext.py
index d40ceea81a..fe757d6de1 100644
--- a/tests/vector_stores/test_legacy_cleanup_no_plaintext.py
+++ b/tests/vector_stores/test_legacy_cleanup_no_plaintext.py
@@ -17,7 +17,7 @@ import pytest
from langchain_community.vectorstores import FAISS
from langchain_core.embeddings import Embeddings
-from src.local_deep_research.vector_stores.legacy_cleanup import (
+from local_deep_research.vector_stores.legacy_cleanup import (
migrate_legacy_docstores,
_rag_cache_root,
)
@@ -291,7 +291,7 @@ def test_extract_map_sweeps_stale_tmp_but_spares_fresh_concurrent_tmp(
import time
from pathlib import Path
- from src.local_deep_research.vector_stores.legacy_cleanup import (
+ from local_deep_research.vector_stores.legacy_cleanup import (
_STALE_TMP_AGE_SECONDS,
_write_sidecar_atomic,
)
@@ -400,10 +400,10 @@ def test_non_string_idmap_value_is_rejected_without_str_coercion(cache_root):
def test_full_migration_round_trip_no_reembed(cache_root):
"""old LangChain FAISS -> extract sidecar -> re-key to IndexIDMap2 by int id,
without re-embedding; search returns the int ids; orphans dropped."""
- from src.local_deep_research.vector_stores.legacy_cleanup import (
+ from local_deep_research.vector_stores.legacy_cleanup import (
rekey_index_file,
)
- from src.local_deep_research.vector_stores import get_vector_store_class
+ from local_deep_research.vector_stores import get_vector_store_class
userdir = cache_root / "u"
uuids = [uuid.uuid4().hex for _ in range(4)]
@@ -455,7 +455,7 @@ def test_rekey_already_migrated_tolerates_concurrently_deleted_sidecar(
report success — NOT raise FileNotFoundError, which makes the caller
destructively quarantine a perfectly healthy, just-rekeyed index.
"""
- from src.local_deep_research.vector_stores.legacy_cleanup import (
+ from local_deep_research.vector_stores.legacy_cleanup import (
rekey_index_file,
)
@@ -494,8 +494,8 @@ def test_rekey_fresh_build_tolerates_concurrent_migration(cache_root, mocker):
import faiss
import numpy as np
- import src.local_deep_research.vector_stores.legacy_cleanup as lc
- from src.local_deep_research.vector_stores.legacy_cleanup import (
+ import local_deep_research.vector_stores.legacy_cleanup as lc
+ from local_deep_research.vector_stores.legacy_cleanup import (
rekey_index_file,
)
@@ -537,7 +537,7 @@ def test_rekey_on_plain_indexidmap_raises_not_aborts(cache_root):
import faiss
import numpy as np
- from src.local_deep_research.vector_stores.legacy_cleanup import (
+ from local_deep_research.vector_stores.legacy_cleanup import (
rekey_index_file,
)
@@ -569,7 +569,7 @@ def test_rekey_on_plain_indexidmap_raises_not_aborts(cache_root):
def test_rekey_rejects_duplicate_ids_from_sidecar(cache_root):
"""Two legacy positions resolving to the SAME DocumentChunk.id must be
refused (would bake an id-collision the set()-based read-back can't see)."""
- from src.local_deep_research.vector_stores.legacy_cleanup import (
+ from local_deep_research.vector_stores.legacy_cleanup import (
rekey_index_file,
)
@@ -601,10 +601,10 @@ def test_rekey_on_already_migrated_index_does_not_crash(cache_root):
silently reconstructs wrong vectors) — it must detect the new format,
drop the stale sidecar, and leave the index intact.
"""
- from src.local_deep_research.vector_stores.legacy_cleanup import (
+ from local_deep_research.vector_stores.legacy_cleanup import (
rekey_index_file,
)
- from src.local_deep_research.vector_stores import get_vector_store_class
+ from local_deep_research.vector_stores import get_vector_store_class
userdir = cache_root / "u"
uuids = [uuid.uuid4().hex for _ in range(3)]
@@ -664,7 +664,7 @@ def test_rekey_rejects_already_migrated_with_mismatched_ids(cache_root):
import faiss
import numpy as np
- from src.local_deep_research.vector_stores.legacy_cleanup import (
+ from local_deep_research.vector_stores.legacy_cleanup import (
rekey_index_file,
)
@@ -704,7 +704,7 @@ def test_rekey_rejects_foreign_faiss_class_without_segfault(cache_root):
import faiss
import numpy as np
- from src.local_deep_research.vector_stores.legacy_cleanup import (
+ from local_deep_research.vector_stores.legacy_cleanup import (
rekey_index_file,
)
@@ -742,7 +742,7 @@ def test_rekey_rejects_already_migrated_with_duplicate_ids(cache_root):
import faiss
import numpy as np
- from src.local_deep_research.vector_stores.legacy_cleanup import (
+ from local_deep_research.vector_stores.legacy_cleanup import (
rekey_index_file,
)
diff --git a/tests/web/services/conftest.py b/tests/web/services/conftest.py
index 18931a4a8a..4a5630f8b5 100644
--- a/tests/web/services/conftest.py
+++ b/tests/web/services/conftest.py
@@ -33,22 +33,16 @@ def _allow_socket_subscribe(monkeypatch):
Scope: function. The patches are torn down at test exit.
"""
# Lazy import — keep this conftest cheap for tests that never touch
- # the socket service at all. Some tests in this dir import via
- # ``local_deep_research...`` while others use ``src.local_deep_research...``;
- # Python may cache them as separate module identities, so resolve
- # whichever is importable and patch its session binding.
- try:
- from local_deep_research.web.services.socket_service import (
- SocketIOService,
- )
-
- module_path = "local_deep_research.web.services.socket_service"
- except ImportError:
- from src.local_deep_research.web.services.socket_service import (
- SocketIOService,
- )
-
- module_path = "src.local_deep_research.web.services.socket_service"
+ # the socket service at all. Import via the canonical
+ # ``local_deep_research`` package (the module instance the running app
+ # binds its routes to); the ``src.local_deep_research`` alias is banned in
+ # tests (it is a distinct module identity — see the check-no-src-test-imports
+ # pre-commit hook) so there is only one binding to patch.
+ from local_deep_research.web.services.socket_service import (
+ SocketIOService,
+ )
+
+ module_path = "local_deep_research.web.services.socket_service"
# __handle_subscribe / __handle_unsubscribe now also re-validate the
# socket's session id against the SessionManager (defense-in-depth), so
diff --git a/tests/web/services/test_chat_step_decision.py b/tests/web/services/test_chat_step_decision.py
index 39ce8e169c..dbc1792de0 100644
--- a/tests/web/services/test_chat_step_decision.py
+++ b/tests/web/services/test_chat_step_decision.py
@@ -14,7 +14,7 @@ The tests below pin down the contract per scenario.
import pytest
-from src.local_deep_research.web.services.research_service import (
+from local_deep_research.web.services.research_service import (
_chat_step_decision,
_compose_chat_step_content,
_STEP_PHASES,
diff --git a/tests/web/test_socket_subscribe_ownership.py b/tests/web/test_socket_subscribe_ownership.py
index c535778d75..dab2cfbc99 100644
--- a/tests/web/test_socket_subscribe_ownership.py
+++ b/tests/web/test_socket_subscribe_ownership.py
@@ -12,7 +12,7 @@ not need to stand up a Flask app or the singleton wrapper.
from unittest.mock import patch, MagicMock
-from src.local_deep_research.web.services.socket_service import SocketIOService
+from local_deep_research.web.services.socket_service import SocketIOService
def _patched_session(row):
@@ -32,7 +32,7 @@ def _patched_session(row):
def test_owns_research_true_when_row_exists():
with patch(
- "src.local_deep_research.database.session_context.get_user_db_session",
+ "local_deep_research.database.session_context.get_user_db_session",
return_value=_patched_session(("abc",)),
):
assert SocketIOService._user_owns_research("alice", "abc") is True
@@ -41,7 +41,7 @@ def test_owns_research_true_when_row_exists():
def test_owns_research_false_when_row_missing():
"""Cross-user disclosure regression: bob must not see alice's research."""
with patch(
- "src.local_deep_research.database.session_context.get_user_db_session",
+ "local_deep_research.database.session_context.get_user_db_session",
return_value=_patched_session(None),
):
assert (
@@ -57,7 +57,7 @@ def test_owns_research_denies_on_exception():
raise RuntimeError("DB unavailable")
with patch(
- "src.local_deep_research.database.session_context.get_user_db_session",
+ "local_deep_research.database.session_context.get_user_db_session",
raising,
):
assert SocketIOService._user_owns_research("alice", "anything") is False
@@ -89,7 +89,7 @@ def test_owns_benchmark_run_true_for_integer_id():
(ResearchHistory) misses; second (BenchmarkRun) hits.
"""
with patch(
- "src.local_deep_research.database.session_context.get_user_db_session",
+ "local_deep_research.database.session_context.get_user_db_session",
return_value=_patched_session_seq([None, (5,)]),
):
assert SocketIOService._user_owns_research("alice", "5") is True
@@ -99,7 +99,7 @@ def test_owns_benchmark_run_false_when_not_owned():
"""An integer id matching no ResearchHistory and no BenchmarkRun row
in the user's own DB is rejected (no cross-user widening)."""
with patch(
- "src.local_deep_research.database.session_context.get_user_db_session",
+ "local_deep_research.database.session_context.get_user_db_session",
return_value=_patched_session_seq([None, None]),
):
assert SocketIOService._user_owns_research("bob", "5") is False
@@ -122,16 +122,16 @@ def test_unsubscribe_rejected_when_user_does_not_own_research():
with (
patch(
- "src.local_deep_research.web.services.socket_service.SocketIO"
+ "local_deep_research.web.services.socket_service.SocketIO"
) as mock_socketio_class,
patch(
- "src.local_deep_research.web.services.socket_service.session",
+ "local_deep_research.web.services.socket_service.session",
{"username": "alice", "session_id": "sess-alice"},
),
# Session is valid (defense-in-depth check passes) so this test
# exercises the ownership rejection specifically.
patch(
- "src.local_deep_research.web.auth.session_manager."
+ "local_deep_research.web.auth.session_manager."
"session_manager.validate_session",
return_value="alice",
),
@@ -178,14 +178,14 @@ def test_unsubscribe_allowed_when_user_owns_research():
with (
patch(
- "src.local_deep_research.web.services.socket_service.SocketIO"
+ "local_deep_research.web.services.socket_service.SocketIO"
) as mock_socketio_class,
patch(
- "src.local_deep_research.web.services.socket_service.session",
+ "local_deep_research.web.services.socket_service.session",
{"username": "alice", "session_id": "sess-alice"},
),
patch(
- "src.local_deep_research.web.auth.session_manager."
+ "local_deep_research.web.auth.session_manager."
"session_manager.validate_session",
return_value="alice",
),
diff --git a/tests/web_services/conftest.py b/tests/web_services/conftest.py
index 2ca3e0386f..552d76ba06 100644
--- a/tests/web_services/conftest.py
+++ b/tests/web_services/conftest.py
@@ -14,24 +14,17 @@ def _allow_socket_subscribe():
``session.get("username")`` lookup in ``__handle_subscribe`` raises
``RuntimeError: Working outside of request context``.
- Tests in this directory import via ``local_deep_research.web...``
- (no ``src.`` prefix). Patch BOTH paths because Python may treat the
- two import paths as distinct module identities depending on how the
- package is installed.
+ Tests in this directory import via the canonical
+ ``local_deep_research.web...`` package (no ``src.`` prefix). The
+ ``src.local_deep_research`` alias is banned in tests (it is a distinct
+ module identity — see the check-no-src-test-imports pre-commit hook), so
+ there is a single binding to patch.
"""
- # Resolve the module from whichever path is importable.
- try:
- from local_deep_research.web.services.socket_service import (
- SocketIOService,
- )
-
- module_path = "local_deep_research.web.services.socket_service"
- except ImportError:
- from src.local_deep_research.web.services.socket_service import (
- SocketIOService,
- )
-
- module_path = "src.local_deep_research.web.services.socket_service"
+ from local_deep_research.web.services.socket_service import (
+ SocketIOService,
+ )
+
+ module_path = "local_deep_research.web.services.socket_service"
# __handle_subscribe / __handle_unsubscribe now also re-validate the
# socket's session id against the SessionManager (defense-in-depth), so