~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
"""
Security validation for notification service URLs.
This module provides validation for user-configured notification service URLs
to prevent Server-Side Request Forgery (SSRF) attacks and other security issues.
"""
import ipaddress
import re
import socket
from concurrent.futures import ThreadPoolExecutor, TimeoutError
from typing import ClassVar, List, Optional, Tuple, Union
from urllib.parse import unquote, urlparse
from loguru import logger
from urllib3.exceptions import LocationParseError
from urllib3.util import parse_url
from .notification_destination import (
NotificationDestinationError,
NotificationDestinationKind,
normalize_host_for_transport,
parse_notification_destination,
)
from .ip_ranges import PRIVATE_IP_RANGES as _PRIVATE_IP_RANGES
from .legacy_ipv4 import (
AMBIGUOUS_NUMERIC_IPV4_HOST_ERROR,
ENCODED_NUMERIC_IPV4_HOST_ERROR,
is_ambiguous_numeric_ipv4_host,
is_percent_encoded_numeric_ipv4_host,
)
from .log_sanitizer import redact_and_bound_for_log
from .ssrf_validator import (
RFC_FORBIDDEN_URL_CHARS_RE,
is_metadata_hostname,
redact_url_for_log,
)
# (#6938) Cap for a request-supplied hostname or scheme in a log line, and
# in the rejection messages this module returns, which callers log
# (``NotificationService.test_service``) — a scoped IPv6 literal such as
# ``[fe80::1%25<100k chars>]`` is accepted by the parser and rejected here
# with its full host. 256 keeps every name within the 253-char DNS limit
# intact. Each value is redacted before it is cut (``redact_and_bound_for_log``).
_LOG_HOST_MAX_CHARS = 256
# Type alias for resolved IP addresses (avoids referencing the private
# ipaddress._BaseAddress API).
ResolvedIP = Union[ipaddress.IPv4Address, ipaddress.IPv6Address]
# ``localhost`` carries an inline case-insensitive group rather than a
# pattern-wide re.IGNORECASE: hostnames are case-insensitive, but the other two
# alternatives are already case-agnostic (``\d`` and explicit ``A-Za-z``
# classes), and a blanket flag would additionally fold Unicode look-alikes
# (U+017F, U+212A) into those ``A-Za-z`` classes. Scoping the flag keeps the
# widening to the one alternative that needed it.
# ``(?://)?`` mirrors the IPv6 arm below: a scheme-relative fragment names the
# same host as its bare spelling, so ``//localhost/x`` has to fail closed
# exactly like ``localhost/x``.
_SCHEMELESS_URL_FRAGMENT_RE = re.compile(
r"^(?://)?(?:(?i:localhost)|(?:\d{1,3}\.){3}\d{1,3}|"
r"(?:[A-Za-z0-9-]+\.)+[A-Za-z]{2,})"
r"(?::\d+)?(?:[/?#]|$)"
)
# A userinfo prefix hides the host from the anchored pattern above, so
# ``[email protected]/x`` would otherwise read as opaque data. Two deliberate
# narrowings keep this from swallowing ordinary URL data:
# * only the loopback-name and IPv4-literal alternatives are carried over.
# This alternation, not the trailer below, is what keeps
# ``[email protected]`` in a ``?to=`` list an e-mail address:
# ``more:secret:[email protected]/webhook`` is credentials in front of an
# ordinary domain — exactly the shape an Apprise service URL uses — and a
# public domain is not a blocked shortcut in the first place.
# * a ``[/?#]`` trailer is required rather than also accepting
# end-of-string. That is what keeps a bare ``admin@localhost`` or
# ``[email protected]`` — a recipient whose domain part happens to be
# spelled like a loopback host — an address rather than an authority.
_USERINFO_URL_FRAGMENT_RE = re.compile(
r"^(?://)?[^/?#@\s]*@(?:(?i:localhost)|(?:\d{1,3}\.){3}\d{1,3})"
r"(?::\d+)?[/?#]"
)
# Legacy inet_aton spellings (decimal, hexadecimal, octal, shortened) name the
# same host as their dotted-quad form; ``legacy_ipv4`` already owns that
# grammar for whole URLs. The ``[/?#]`` trailer is NOT the safeguard here —
# it is the common case. Apprise's comma-separated target lists put a ``/``
# or a ``?`` directly after the last id (``tgram://…/111111111,222222222?
# format=markdown``, ``twilio://…/2125551234,4085551234?batch=yes``), and the
# one-component inet_aton form accepts every decimal below 2**32, so a bare
# id would read as a host. ``_names_legacy_numeric_host`` therefore demands
# an authority marker as well: two or more dot-separated components, a
# ``//`` prefix, or a ``userinfo@`` prefix. ``%`` is in the host class so the
# percent-encoded spellings reach the same decision.
_NUMERIC_HOST_FRAGMENT_RE = re.compile(
r"^(?P<prefix>(?://)?(?:[^/?#@\s]*@)?)"
r"(?P<host>[0-9A-Fa-fXx.%]+)(?::\d+)?[/?#]"
)
# Keep candidate detection deliberately broad. IPv6Address below is the sole
# authority for validity, including dotted-quad and scoped IPv6 forms.
# Brackets delimit the authority instead of belonging to the address, so the
# bracketed arm takes a repeated or unclosed pair and any trailing run that
# is not a separator: ``[::1``, ``[[::1]]`` and ``[::1]x`` each name ``::1``.
_IPV6_FRAGMENT_CANDIDATE_RE = re.compile(
r"^(?://)?(?:\[+(?P<bracketed>[^\s,\[\]/?#]+)"
r"[^\s,/?#]*|"
r"(?P<bare>(?=[^\s,/?#]*:[^\s,/?#]*:)[^\s,/?#]+))"
r"(?:[/?#]|$)"
)
_PERCENT_ENCODED_BRACKETS = {"%5b": "[", "%5d": "]"}
_PERCENT_ENCODED_BRACKET_RE = re.compile(
"|".join(_PERCENT_ENCODED_BRACKETS), re.IGNORECASE
)
# ``%2e`` spells the label separator, so it decides both where a host's
# trailing root dot ends and how many components the host has.
_PERCENT_ENCODED_DOTS = ("%2e", "%2E")
# One scan finds the end of a fragment's authority for every helper below.
_AUTHORITY_END_RE = re.compile(r"[/?#]")
_URL_SCHEME_RE = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]{0,31}://")
# Keep this boundary zero-width to avoid quadratic backtracking on
# separator runs.
_URL_BOUNDARY_RE = re.compile(r"(?<=[,\s])(?=[A-Za-z][A-Za-z0-9+.-]{0,31}://)")
_APPRISE_TELEGRAM_URL_RE = re.compile(
r"^tgram://(?:bot)?[0-9]+(?::|%3A)[a-z0-9_-]+(?:/|\?|$)",
re.IGNORECASE,
)
def _strip_notification_url_delimiters(entry: str) -> str:
start = 0
end = len(entry)
while start < end and (entry[start] == "," or entry[start].isspace()):
start += 1
while end > start and (entry[end - 1] == "," or entry[end - 1].isspace()):
end -= 1
return entry[start:end]
def _is_ipv6_literal(host: str) -> bool:
try:
ipaddress.IPv6Address(host)
except ipaddress.AddressValueError:
return False
return True
def _decode_bracket_escapes(fragment: str) -> str:
"""Decode ``%5b``/``%5d`` so an encoded IPv6 literal stays recognizable."""
return _PERCENT_ENCODED_BRACKET_RE.sub(
lambda match: _PERCENT_ENCODED_BRACKETS[match.group(0).lower()],
fragment,
)
def _has_label_separator(host: str) -> bool:
"""Return whether a host carries a dot in either spelling."""
return "." in host or any(dot in host for dot in _PERCENT_ENCODED_DOTS)
def _strip_trailing_host_dots(host: str) -> str:
r"""Drop a host's trailing root dots, ``%2e`` included.
A fragment's authority is attacker-supplied and unbounded, so the
literal dots come off with one C-level ``rstrip`` and the encoded ones
walk back by index. Repeated slicing and a ``(?:\.|%2e)+$`` regex are
both quadratic on a long run of dots.
"""
stripped = host.rstrip(".")
if not stripped.endswith(_PERCENT_ENCODED_DOTS):
return stripped
end = len(stripped)
while True:
if end >= 3 and stripped[end - 3 : end].lower() == "%2e":
end -= 3
elif end > 0 and stripped[end - 1] == ".":
end -= 1
else:
return stripped[:end]
def _authority_end(rest: str) -> int:
"""Return the offset of a fragment's first ``/``, ``?`` or ``#``."""
boundary = _AUTHORITY_END_RE.search(rest)
return len(rest) if boundary is None else boundary.start()
def _strip_fragment_host_dots(fragment: str) -> str:
"""Drop a host's trailing dots the way ``_normalize_host`` does.
``localhost.`` and ``localhost`` are one host to every resolver, so the
fully-qualified spelling must not read as opaque data here when the bare
one fails closed. ``%2e`` spells the same dot, so ``localhost%2e``
normalizes onto the same host as ``localhost.`` does.
"""
prefix, rest = "", fragment
if rest.startswith("//"):
prefix, rest = "//", rest[2:]
boundary = _authority_end(rest)
host, tail = rest[:boundary], rest[boundary:]
port = ""
colon = host.rfind(":")
# Split a port off a colon-free host, or off a bracketed one: a BARE
# IPv6 literal's own colons are part of the address rather than a port
# delimiter, but a bracketed literal has already closed, so ``[::1].:80``
# has to split the way ``[::1]:80`` does.
if (
colon > 0
and (":" not in host[:colon] or "]" in host[:colon])
and host[colon + 1 :].isdigit()
):
host, port = host[:colon], host[colon:]
stripped = _strip_trailing_host_dots(host)
if stripped == host:
return fragment
return prefix + stripped + port + tail
def _strip_fragment_userinfo(fragment: str) -> str:
"""Drop a ``userinfo@`` prefix from a fragment's authority component."""
prefix, rest = "", fragment
if rest.startswith("//"):
prefix, rest = "//", rest[2:]
authority_end = _authority_end(rest)
# The LAST ``@`` inside the authority delimits userinfo; any ``@`` in the
# path or query belongs to the data, not to the host.
at_sign = rest.rfind("@", 0, authority_end)
return fragment if at_sign < 0 else prefix + rest[at_sign + 1 :]
def _is_ipv6_url_fragment(fragment: str) -> bool:
candidate = _IPV6_FRAGMENT_CANDIDATE_RE.match(fragment)
if candidate is None:
return False
bracketed = candidate.group("bracketed")
host = bracketed or candidate.group("bare")
if _is_ipv6_literal(host):
return True
if bracketed is not None:
return False
# The bare alternative has no port group, so its greedy run swallows a
# trailing ``:<port>``. Without this retry ``::1:99999`` -- a valid host
# with an out-of-range port -- fails ``IPv6Address`` as one literal and is
# silently accepted as URL data, while the bracketed ``[::1]:99999`` is
# refused. Retry once with the final colon-segment removed so both forms
# fail closed on the same input.
head, sep, _tail = host.rpartition(":")
return bool(sep) and _is_ipv6_literal(head)
def _names_legacy_numeric_host(prefix: str, host: str) -> bool:
"""Return whether a fragment's leading token is an inet_aton authority.
A one-component inet_aton host is any integer below 2**32, which is also
the shape of every Telegram chat id, Twilio number and Unix timestamp
that an Apprise comma-separated target list leaves in front of a ``/``
or ``?``. Such a token only names a host once the fragment carries an
authority marker of its own: a second dot-separated component (a
trailing root dot does not count), a ``//`` prefix, or a ``userinfo@``
prefix.
"""
# A trailing root dot (``.`` or ``%2e``) is not a second component:
# ``222222222%2e`` is still a one-component numeric token.
bare_host = re.sub(r"(?:\.|%2[eE])+$", "", host)
if not prefix and not _has_label_separator(bare_host):
return False
return is_ambiguous_numeric_ipv4_host(
host
) or is_percent_encoded_numeric_ipv4_host(host)
def _matches_scheme_less_url_shape(fragment: str) -> bool:
if _SCHEMELESS_URL_FRAGMENT_RE.match(fragment):
return True
if _USERINFO_URL_FRAGMENT_RE.match(fragment):
return True
numeric = _NUMERIC_HOST_FRAGMENT_RE.match(fragment)
if numeric is not None and _names_legacy_numeric_host(
numeric.group("prefix"), numeric.group("host")
):
return True
return _is_ipv6_url_fragment(fragment)
def _is_scheme_less_url_fragment(fragment: str) -> bool:
"""Recognize a comma-separated fragment that names a host without a scheme.
Every check is additive: an alternate spelling is only ever consulted
after the literal fragment has been cleared, so normalization can widen
the refusal set but can never readmit a fragment that already fails
closed.
"""
if _matches_scheme_less_url_shape(fragment):
return True
# Spellings that normalize onto a host the checks above already refuse:
# percent-encoded brackets and a trailing root dot, encoded or literal.
normalized = _strip_fragment_host_dots(_decode_bracket_escapes(fragment))
if normalized != fragment and _matches_scheme_less_url_shape(normalized):
return True
# A userinfo prefix hides an IPv6 authority from the anchored patterns
# above. Only the IPv6 arm is retried on the stripped form: stripping
# userinfo from ``[email protected]`` would read an e-mail address as
# a hostname, which is why the hostname arm demands the ``[/?#]`` trailer
# that proves an authority instead.
without_userinfo = _strip_fragment_userinfo(normalized)
return without_userinfo != normalized and _is_ipv6_url_fragment(
without_userinfo
)
def parse_notification_url_list(
urls: str, separator: str = ","
) -> tuple[list[str], Optional[str]]:
r"""Partition notification URLs without dropping malformed fragments.
A boundary is a comma or whitespace sequence followed by a URL scheme.
This preserves commas inside one Apprise service URL while keeping
whitespace a hard separator. Commas and surrounding whitespace — any
Unicode whitespace, matching the bare ``str.strip()`` every other
consumer of an entry applies — are trimmed from each entry's ENDS
before it is inspected, so a value pasted with a trailing NBSP is not
mistaken for a URL with an illegal character in it. An entry whose
head carries a scheme but which contains characters that are illegal
unencoded in a URI (whitespace, control bytes, backslash —
``RFC_FORBIDDEN_URL_CHARS_RE``, the same class ``validate_service_url``
rejects) is malformed no matter what trails it: the token after the first illegal character is returned
as the invalid fragment, so ``discord://x garbage`` fails closed exactly
like ``discord://x example.com/hook`` instead of being dispatched as a
single entry. When the illegal character only TRAILS the entry
(``slack://t/x/y\``) there is no token after it, so the whole entry is
returned as the fragment. URL-like fragments without a scheme are
returned separately so callers can fail closed instead of dispatching
only the valid subset.
``invalid_fragment`` is a REFUSAL SIGNAL, not a substitute URL, and it
carries three warnings for callers:
* It may CARRY A SCHEME. ``RFC_FORBIDDEN_URL_CHARS_RE`` covers
backslash and the non-``\s`` control bytes, which the
scheme-boundary regex does not split on, so
``a://h1/p\https://h2/q`` stays ONE entry whose fragment is
``https://h2/q``. A caller that validates the fragment *in place of*
the entry validates a decoy while the raw original string — pointing
at ``h1`` — is what gets dispatched.
* It may be VALID on its own. Never assume validating it yields an
error message.
* It may CONTAIN CREDENTIALS. When the illegal character trails the
entry the fragment IS the entry, and for token-in-authority Apprise
schemes even a ``scheme://host`` redaction of it is the secret. Log
its length, never its content.
The only correct response to a non-``None`` fragment is to refuse the
whole input.
Custom separators are explicit boundaries: commas and whitespace inside
each resulting URL remain data, subject to service URL validation. Every
parsed entry still requires a top-level URL scheme. The scheme-less
fragment check below is the one guard a custom separator does NOT get:
its entries take ``validate_service_url`` but are never scanned for
comma-separated scheme-less fragments, because with an explicit separator
a comma is ordinary data inside one URL.
Returns ``(parsed_urls, invalid_fragment)``. Custom separators retain the
historical explicit-split behavior.
"""
if separator != ",":
parsed_urls = [
entry.strip() for entry in urls.split(separator) if entry.strip()
]
else:
parsed_urls = []
for entry in _URL_BOUNDARY_RE.split(urls):
normalized_entry = _strip_notification_url_delimiters(entry)
if normalized_entry:
parsed_urls.append(normalized_entry)
for entry in parsed_urls:
if not _URL_SCHEME_RE.match(entry):
return parsed_urls, entry
if separator != ",":
continue
# A URL entry containing characters illegal unencoded in a URI is
# malformed regardless of what trails it: ``discord://x garbage``
# is not one URL with "garbage" in it, it is a URL followed by
# junk. Any token after the first illegal character surfaces as
# the invalid fragment so every caller fails closed on the shape.
if RFC_FORBIDDEN_URL_CHARS_RE.search(entry):
fragments = [
fragment
for fragment in RFC_FORBIDDEN_URL_CHARS_RE.split(entry)
if fragment
]
# fragments[0] is the prefix before the illegal character; the
# next non-empty token is the smuggled fragment. When the
# illegal character only trails the entry, the entry itself
# is the malformed fragment.
return parsed_urls, fragments[1] if len(fragments) > 1 else entry
# Commas are legal inside one Apprise URL (e.g. a multi-target
# ``?to=id1,id2``), so a comma-separated fragment only fails closed
# when it is itself a scheme-less URL that Apprise could repair
# away or absorb into a neighbouring entry.
for fragment in re.split(r",+", entry)[1:]:
if _is_scheme_less_url_fragment(fragment):
return parsed_urls, fragment
return parsed_urls, None
class NotificationURLValidationError(ValueError):
"""Raised when a notification service URL fails security validation."""
pass
class NotificationURLValidator:
"""Validates notification service URLs to prevent SSRF and other attacks."""
# Dangerous protocols that should never be used for notifications
BLOCKED_SCHEMES = (
"file", # Local file access
"ftp", # FTP can be abused for SSRF
"ftps", # Secure FTP can be abused for SSRF
"data", # Data URIs can leak sensitive data
"javascript", # XSS/code execution
"vbscript", # XSS/code execution
"about", # Browser internal
"blob", # Browser internal
)
# Allowed protocols for notification services
ALLOWED_SCHEMES = (
"http", # Webhook services
"https", # Webhook services (preferred)
"mailto", # Email notifications
"discord", # Discord webhooks
"slack", # Slack webhooks
"tgram", # Apprise Telegram scheme
"gotify", # Gotify notifications
"pushover", # Pushover notifications
"ntfy", # ntfy.sh notifications (http)
"ntfys", # ntfy.sh notifications (https)
"signal", # Signal via signal-api-rest container
"matrix", # Matrix protocol
"mattermost", # Mattermost webhooks
"rocketchat", # Rocket.Chat webhooks
"teams", # Microsoft Teams
"json", # Generic JSON webhooks
"xml", # Generic XML webhooks
"form", # Form-encoded webhooks
)
# Apprise query parameters that can select a second outbound destination
# or resource independently of the URL authority screened below.
#
# ``template`` is consumed by Discord/Slack/Workflows (including native
# HTTPS webhook URLs that Apprise converts to those plugins) as an
# unrestricted AppriseAttachment, which can read local files or fetch
# remote URLs. ``redirect`` overrides the hardened AppriseAsset setting
# used by the notification service and would re-enable redirect-based SSRF.
BLOCKED_APPRISE_QUERY_KEYS = frozenset(("redirect", "template"))
# mailto-specific secondary egress/resource selectors. ``smtp`` replaces
# the actual SMTP host; PGP key paths are unrestricted attachments; and
# WKD derives HTTPS fetches from recipient-controlled domains.
BLOCKED_MAILTO_QUERY_KEYS = frozenset(
("smtp", "pgppub", "pgpkey", "pgpprv", "wkd")
)
# Schemes whose authority identifies a network destination. Token-style
# schemes such as discord and slack deliberately do not belong here.
HOST_BEARING_PLUGIN_SCHEMES: ClassVar[frozenset[str]] = frozenset(
{
"signal",
"gotify",
"ntfy",
"ntfys",
"mattermost",
"rocketchat",
"matrix",
"json",
"xml",
"form",
"mailto",
}
)
ADDRESS_BEARING_SCHEMES: ClassVar[frozenset[str]] = (
frozenset({"http", "https"}) | HOST_BEARING_PLUGIN_SCHEMES
)
# Reuse shared private IP range definitions
PRIVATE_IP_RANGES = _PRIVATE_IP_RANGES
# Prefix emitted by validate_service_url when an http(s) URL targets a
# private/internal IP. Pinned as a class-level constant so the
# validator, the hint logic, and the call site (service.py) share a
# single source of truth.
PRIVATE_IP_REJECTION_PREFIX = "Blocked private/internal IP address:"
@staticmethod
def _ip_matches_blocked_range(
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
single source of truth.
Honors:
- ALWAYS_BLOCKED_METADATA_IPS (cloud metadata, absolute)
- is_nat64_wrapped_metadata_ip (NAT64-wrapped IMDS, absolute)
- security.allow_nat64 env carve-out for the two NAT64 prefixes
(overridable via ``allow_nat64``: None reads env, an explicit
bool answers the "would NAT64 unblock this?" hint probe)
- allow_private_ips: when True, RFC1918 / CGNAT / loopback /
link-local / IPv6 ULA are allowed BUT the two absolute checks
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. The notification validator and send
guards pass it for every host-bearing destination (http(s)
included) so metadata reachable in link-local beyond the
always-blocked literals cannot slip through the opt-in.
"""
from .ssrf_validator import is_ip_blocked
return is_ip_blocked(
str(ip),
allow_private_ips=allow_private_ips,
allow_nat64=allow_nat64,
block_link_local=block_link_local,
)
@staticmethod
def _resolve_hostname_ips(
hostname: str,
) -> Optional[List[ResolvedIP]]:
"""Resolve hostname to a list of ipaddress objects, with a 5s
timeout. Returns None on resolution failure or timeout.
Extracted from ``_is_private_ip`` so multiple policy decisions
can share a single resolution pass — see
``validate_service_url_with_hint`` for the single-pass call
site that closes a DNS-rebinding TOCTOU window between the
default-level and elevated-level decisions.
"""
# NOTE: best-effort, validation-time check. Apprise re-resolves
# the hostname when it actually sends the request (via
# 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.
#
# 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. Every partition requires the operator's private-IP
# opt-in for private addresses (LAN targets or a private forward
# proxy); cloud metadata remains blocked. Because the pin/block are thread-local,
# they never disturb a legitimate private request on another thread.
#
# DEFENSE IN DEPTH: the whole outbound-notification path is still
# 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://,
# tgram://, mattermost://, etc.) that hardcode their endpoints.
#
# Plugin schemes are not categorically exempt from authority
# validation: some have hardcoded destinations (Discord, Slack,
# Teams Workflows), some send against the URL authority (Signal,
# Gotify, generic webhooks), and ntfy/Matrix are mode-dependent.
#
# concurrent.futures for thread-safe timeout instead of
# socket.setdefaulttimeout() which is process-global.
try:
executor = ThreadPoolExecutor(max_workers=1)
try:
future = executor.submit(
socket.getaddrinfo,
hostname,
None,
socket.AF_UNSPEC,
socket.SOCK_STREAM,
)
resolved_ips = future.result(timeout=5)
finally:
executor.shutdown(wait=False, cancel_futures=True)
return [
ipaddress.ip_address(sockaddr[0])
for _family, _, _, _, sockaddr in resolved_ips
]
except (socket.gaierror, OSError, TimeoutError, ValueError):
logger.warning(
"DNS resolution failed for hostname {} — "
"allowing request (unable to determine if private)",
redact_and_bound_for_log(hostname, _LOG_HOST_MAX_CHARS),
)
return None
@staticmethod
def _host_blocks_at_level(
hostname: str,
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
a prior DNS resolution.
Pre-resolved IPs can be passed via ``resolved_ips`` to share a
single resolution across multiple policy decisions, closing
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).
"""
# Cloud-metadata endpoints reachable by NAME (GCP, IBM Cloud classic)
# are blocked at every level and in every partition (http(s) and
# plugin schemes both reach here via _is_private_ip). IBM's
# api.service.softlayer.com resolves to RFC1918, so the IP checks
# below would pass it under allow_private_ips=True. Shared with
# validate_url via ssrf_validator.is_metadata_hostname.
if is_metadata_hostname(hostname):
return True
# Localhost-string shortcuts only apply when the operator hasn't
# opted into private-IP reachability. With allow_private_ips=True
# we let the IP path (DNS-resolved or literal) make the decision
# so metadata-IP literals like "169.254.169.254" still block.
if not allow_private_ips and hostname.lower() in (
"localhost",
"127.0.0.1",
"::1",
# Recognize and validate a local address; no socket is bound here.
"0.0.0.0", # nosec B104
"::",
):
return True
# Try to parse as IP address first.
try:
ip = ipaddress.ip_address(hostname)
return NotificationURLValidator._ip_matches_blocked_range(
ip,
allow_private_ips=allow_private_ips,
allow_nat64=allow_nat64,
block_link_local=block_link_local,
)
except ValueError:
pass
# Hostname — use pre-resolved IPs if provided, otherwise resolve.
if resolved_ips is None:
resolved_ips = NotificationURLValidator._resolve_hostname_ips(
hostname
)
if resolved_ips is None:
# DNS failed — allow (matches the historical behaviour).
return False
for ip in resolved_ips:
if NotificationURLValidator._ip_matches_blocked_range(
ip,
allow_private_ips=allow_private_ips,
allow_nat64=allow_nat64,
block_link_local=block_link_local,
):
return True
return False
@staticmethod
def _extract_host(url: str) -> Optional[str]:
"""Extract the raw hostname from ``url`` using urllib3's
``parse_url`` (the same parser requests uses internally).
Returns None if urllib3 rejects the URL.
"""
try:
u3 = parse_url(url)
except LocationParseError:
return None
return u3.host
@staticmethod
def _normalize_host(hostname: Optional[str]) -> str:
"""Normalize a raw hostname from ``parse_url``: strip IPv6
bracket notation and trailing dots. Shared by
``validate_service_url`` and ``validate_service_url_with_hint``
so the two call sites cannot drift.
"""
if hostname and hostname.startswith("[") and hostname.endswith("]"):
hostname = hostname[1:-1]
if hostname:
hostname = hostname.rstrip(".")
return hostname or ""
@staticmethod
def _apprise_query_keys(url: str) -> Tuple[List[str], bool]:
"""Return canonical query keys using Apprise 1.12 semantics.
Apprise splits pairs on both ``&`` and ``;``, preserves a leading
``+`` key namespace marker, converts later ``+`` characters to spaces,
percent-decodes once, then lowercases and strips the key. Its URL
parser also treats everything after the first ``?`` as query data,
including text that ``urllib.parse`` would classify as a fragment.
The boolean reports malformed percent escapes in a key. Values are
intentionally neither decoded nor returned: they can contain secrets,
file paths, and alternate destinations and are irrelevant to policy.
"""
query_at = url.find("?")
if query_at < 0:
return [], False
raw_query = url[query_at + 1 :]
keys = []
hex_digits = "0123456789abcdefABCDEF"
for amp_pair in raw_query.split("&"):
for pair in amp_pair.split(";"):
raw_key = pair.split("=", 1)[0]
index = 0
while index < len(raw_key):
if raw_key[index] != "%":
index += 1
continue
if (
index + 2 >= len(raw_key)
or raw_key[index + 1] not in hex_digits
or raw_key[index + 2] not in hex_digits
):
return keys, True
index += 3
apprise_key = (
raw_key[:1] + raw_key[1:].replace("+", " ")
if raw_key
else ""
)
keys.append(unquote(apprise_key).lower().strip())
return keys, False
@staticmethod
def _validate_apprise_query_policy(url: str, scheme: str) -> Optional[str]:
"""Reject Apprise query options that bypass destination validation."""
keys, malformed = NotificationURLValidator._apprise_query_keys(url)
if malformed:
logger.warning(
"Blocked notification URL with malformed percent-encoding "
"in a query parameter name"
)
return "Malformed percent-encoding in notification parameter name"
blocked_keys = NotificationURLValidator.BLOCKED_APPRISE_QUERY_KEYS
if scheme == "mailto":
blocked_keys = (
blocked_keys
| NotificationURLValidator.BLOCKED_MAILTO_QUERY_KEYS
)
for key in keys:
if key in blocked_keys:
# Never log the value: it may contain a token, local path, or
# alternate destination selected by an attacker.
logger.warning(
"Blocked unsafe notification parameter {} for {} URL",
key,
scheme,
)
return f"Blocked unsafe notification parameter: {key}"
return None
@staticmethod
def _is_private_ip(
hostname: str,
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.
Args:
hostname: Hostname to check
allow_private_ips: When True, RFC1918 / CGNAT / loopback /
link-local / IPv6 ULA are NOT considered private. Cloud
metadata IPs and NAT64-wrapped metadata IPs are blocked
regardless — the operator opt-in cannot license IMDS
exposure.
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. Passed for every
host-bearing notification destination, http(s) included
(metadata lives in link-local beyond the always-blocked
literals).
Returns:
True if hostname is a private IP or localhost (subject to
allow_private_ips), or wraps a metadata IP unconditionally
"""
return NotificationURLValidator._host_blocks_at_level(
hostname,
allow_private_ips=allow_private_ips,
allow_nat64=allow_nat64,
resolved_ips=_resolved_ips,
block_link_local=block_link_local,
)
@staticmethod
def validate_service_url(
url: str,
allow_private_ips: bool = False,
allow_nat64: Optional[bool] = None,
) -> Tuple[bool, Optional[str]]:
"""Validate a notification service URL for security issues.
Thin public wrapper around ``_validate_service_url_impl``.
Always performs its own DNS resolution (no caller-supplied
resolution state).
Args:
url: Service URL to validate (e.g., "discord://webhook_id/token")
allow_private_ips: Whether to allow private IPs (default: False)
Set to True for development/testing environments
allow_nat64: Override for the ``security.allow_nat64``
carve-out. None (default) reads the env setting;
an explicit bool overrides it.
Returns:
Tuple of (is_valid, error_message)
"""
return NotificationURLValidator._validate_service_url_impl(
url,
allow_private_ips=allow_private_ips,
allow_nat64=allow_nat64,
)
@staticmethod
def _validate_service_url_impl(
url: str,
allow_private_ips: bool = False,
allow_nat64: Optional[bool] = None,
resolved_ips: Optional[List[ResolvedIP]] = None,
) -> Tuple[bool, Optional[str]]:
"""Internal validation with optional pre-resolved DNS state.
``resolved_ips`` is trusted internal state used by
``validate_service_url_with_hint`` to share a single DNS
resolution across multiple policy decisions. Must NEVER be
exposed on the public API — callers could pass ``[]`` to
bypass hostname resolution and private-IP checks.
Returns:
Tuple of (is_valid, error_message)
- is_valid: True if URL passes security checks
- error_message: None if valid, error description if invalid
Examples:
>>> validate_service_url("discord://webhook_id/token")
(True, None)
>>> validate_service_url("file:///etc/passwd")
(False, "Blocked unsafe protocol: file")
>>> validate_service_url("http://localhost:5000/webhook")
(False, "Blocked private/internal IP address: localhost")
Caller contract:
``notifications.service.NotificationService.test_service``
calls ``validate_service_url_with_hint`` (single-pass sibling
below) to obtain the validation result AND, when the URL is
rejected, a ``hint_would_help`` flag indicating whether the
rejection targets a recoverable destination — one that
``LDR_NOTIFICATIONS_ALLOW_PRIVATE_IPS=true`` (for RFC1918 /
CGNAT / loopback / IPv6 ULA, plus NAT64-wrapped
non-metadata destinations via the NAT64 carve-out) would
actually unblock. If ``hint_would_help`` is False the URL
targets an always-blocked category (link-local, which every
host-bearing notification destination blocks, cloud-metadata IPs, 6to4,
Teredo, discard prefix, IPv4-mapped IPv6 of metadata,
IPv4-Compatible IPv6, IPv4-Translated/SIIT, NAT64-wrapped
metadata) and the hint is suppressed because
naming the env var would mislead. The parametrized
integration test ``test_test_service_ip_rejection_matrix``
in tests/web/services/test_notification_coverage.py locks
this contract end-to-end across every IP category — if the
wording here changes, that test fails and the call site
needs updating.
"""
if not url or not isinstance(url, str):
return False, "Service URL must be a non-empty string"
# Strip whitespace (must run before the RFC-illegal char check
# so legitimate URLs with surrounding whitespace are not rejected).
url = url.strip()
# Reject URLs containing characters that drive parser-differential
# SSRF bypasses (backslash, whitespace, control bytes) — see
# GHSA-g23j-2vwm-5c25. The URL is omitted from the log line because
# userinfo (RFC 3986 §3.2.1) may contain credentials and rejected
# URLs are by definition adversarial-shaped.
if RFC_FORBIDDEN_URL_CHARS_RE.search(url):
logger.warning(
"Blocked notification URL containing RFC-illegal characters"
)
return (
False,
"URL contains characters that are not allowed (whitespace, backslash, or control bytes)",
)
# Parse URL
try:
parsed = urlparse(url)
except Exception:
# Never echo the parser exception back to the caller: this error
# string is surfaced to the user by the test-URL endpoint, and the
# exception text can carry parser internals / stack-trace fragments
# (CWE-209, py/stack-trace-exposure). Log at WARNING without a
# traceback to match the sibling LocationParseError handler below
# — a malformed URL is benign user input, not a server fault, so an
# ERROR-level stack trace would only add noise.
logger.warning("Failed to parse service URL")
return False, "Invalid URL format"
# Check for scheme
if not parsed.scheme:
return False, "Service URL must have a protocol (e.g., https://)"
scheme = parsed.scheme.lower()
# Check for blocked schemes
if scheme in NotificationURLValidator.BLOCKED_SCHEMES:
logger.warning(
"Blocked unsafe notification protocol: {} in URL: {}",
redact_and_bound_for_log(scheme, _LOG_HOST_MAX_CHARS),
redact_url_for_log(url),
)
return (
False,
"Blocked unsafe protocol: "
f"{redact_and_bound_for_log(scheme, _LOG_HOST_MAX_CHARS)}",
)
# Check for allowed schemes
if scheme not in NotificationURLValidator.ALLOWED_SCHEMES:
if scheme == "telegram":
# Dedicated migration error: 'telegram://' was an Apprise
# scheme removed upstream; point users at the canonical
# 'tgram://' form instead of the generic allowed-list.
return (
False,
"The 'telegram://' scheme is no longer supported by "
"Apprise (removed upstream); replace it with Apprise's "
"canonical 'tgram://<bot_token>/<chat_id>' form "
"(e.g. tgram://123456789:AAexample_token/123456789)",
)
logger.warning(
"Unknown notification protocol: {} in URL: {}",
redact_and_bound_for_log(scheme, _LOG_HOST_MAX_CHARS),
redact_url_for_log(url),
)
return (
False,
"Unsupported protocol: "
f"{redact_and_bound_for_log(scheme, _LOG_HOST_MAX_CHARS)}. "
f"Allowed: {', '.join(NotificationURLValidator.ALLOWED_SCHEMES[:5])}...",
)
# Apprise supports query parameters that can select resources or
# outbound destinations independently of the authority we validate
# below. Enforce this deterministic policy before parsing the host or
# performing any attacker-controlled DNS lookup.
query_error = NotificationURLValidator._validate_apprise_query_policy(
url, scheme
)
if query_error:
return False, query_error
# 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",
)
# ``tgram://`` is checked here, BEFORE host extraction, because its
# authority is a CREDENTIAL (``<bot_id>:<token>``), not a network
# destination: Apprise's Telegram plugin always dials the hardcoded
# api.telegram.org endpoint. urllib3 cannot parse that authority at
# all (it reads ``:<token>`` as a port and raises LocationParseError),
# so the host-based checks below can never run for a valid tgram URL.
#
# ORDERING NOTE for future merges: this early return deliberately
# precedes the numeric-IPv4 screening below, and that is safe ONLY
# because ``tgram`` is not in ADDRESS_BEARING_SCHEMES. The regex below
# is a strict allowlist that already rejects every legacy IPv4 host
# form with a non-decimal component (``0x7f000001``, ``0177.0.0.1``,
# ``127.1`` all fail ``[0-9]+``). The one remaining overlap — a bare
# decimal integer such as ``2130706433`` — is exactly the shape of a
# legitimate Telegram bot id, so it must NOT be rejected as an
# ambiguous numeric IPv4 host. Any check that IS address-bearing must
# be placed above this block, not below it.
if scheme == "tgram":
if not _APPRISE_TELEGRAM_URL_RE.match(url):
return (
False,
"Invalid Telegram service URL; expected "
"tgram://<bot_id>:<token>/<chat_id>",
)
return True, None
# Extract the host for address-bearing schemes. We use urllib3 (the
# parser ``requests`` uses internally) instead of urlparse —
# urlparse is vulnerable to parser-differential bypasses like
# ``http://127.0.0.1\@1.1.1.1`` (GHSA-g23j-2vwm-5c25).
#
# Effective destinations are classified below. A token/topic in a
# fixed vendor URL is not a host; an authority-bearing plugin must
# pass the same private-IP opt-in as an HTTP URL. The urllib3 host and
# classified endpoint must agree before a URL can be dispatched.
#
# urllib3 2.8 decodes unreserved escapes in HTTP(S) hosts (for
# example ``127%2e0%2e0%2e1`` becomes ``127.0.0.1``). Check their
# original spelling before normalization, even when private
# addresses are explicitly allowed. ``raw_hostname`` is reused by
# the plugin-host escape check below.
raw_hostname = None
if scheme in NotificationURLValidator.ADDRESS_BEARING_SCHEMES:
try:
raw_hostname = parsed.hostname
except ValueError:
return False, "Invalid URL format (parser rejected)"
if raw_hostname and is_percent_encoded_numeric_ipv4_host(
raw_hostname
):
logger.warning(
"Blocked notification URL with encoded numeric IPv4 host"
)
return False, ENCODED_NUMERIC_IPV4_HOST_ERROR
try:
u3 = parse_url(url)
except LocationParseError:
logger.warning(
"Blocked notification URL: urllib3 parser rejected it"
)
return False, "Invalid URL format (parser rejected)"
hostname = u3.host
# Authority must be ASCII printable (forward-defence vs urllib3
# ever loosening its IDN handling).
if hostname and any(ord(c) < 0x20 or ord(c) > 0x7E for c in hostname):
logger.warning(
"Blocked notification URL with non-ASCII / control bytes in host"
)
return False, "URL host contains disallowed characters"
hostname = NotificationURLValidator._normalize_host(hostname)
hostname = normalize_host_for_transport(hostname)
# A populated ``//`` authority that urllib3 parses to an EMPTY host
# (e.g. ``json://169.254.169.254:80@/`` — an IP smuggled into the
# 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 (
hostname
and scheme in NotificationURLValidator.ADDRESS_BEARING_SCHEMES
):
# The encoded-numeric spelling was already refused above, before
# urllib3 normalized it.
# Apprise plugins do not share Requests' URL preparation path,
# and several decode every escape in the host (``%2F`` turns
# ``evil.com%2F.local`` into ``evil.com``). Any escape in a
# plugin authority host is ambiguous; fail before DNS.
if (
scheme not in ("http", "https")
and raw_hostname
and "%" in raw_hostname
):
return False, "Notification destination host is ambiguous"
if is_ambiguous_numeric_ipv4_host(hostname):
logger.warning(
"Blocked notification URL with ambiguous numeric IPv4 host"
)
return False, AMBIGUOUS_NUMERIC_IPV4_HOST_ERROR
try:
destination = parse_notification_destination(url)
except NotificationDestinationError:
logger.warning(
"Blocked notification URL with ambiguous destination"
)
return False, "Notification destination is unsupported or ambiguous"
effective_host = NotificationURLValidator._normalize_host(
destination.effective_host
)
if destination.kind is NotificationDestinationKind.VENDOR_PLUGIN:
return True, None
if not effective_host or effective_host.lower() != hostname.lower():
# The effective endpoint and urllib3's connection host must
# agree. A parser disagreement is unsafe to dispatch. Host names
# are case-insensitive, and urllib3 lowercases only http(s)
# hosts, so a case-only difference is not a disagreement.
return False, "Notification destination host is ambiguous"
# Every host-bearing destination blocks the whole link-local range,
# even with the private-IP opt-in. Apprise turns some http(s) URLs
# into plugins that post to the URL host (Apprise API, Workflows),
# and cloud metadata lives across link-local beyond the
# always-blocked literals.
block_link_local = True
if resolved_ips is None:
try:
ipaddress.ip_address(effective_host)
except ValueError:
# Direct validation (without the admin hint) must reuse one
# DNS answer for both the block and recoverability decision.
# An empty list keeps a failed lookup from being retried.
resolved_ips = (
NotificationURLValidator._resolve_hostname_ips(
effective_host
)
or []
)
if NotificationURLValidator._is_private_ip(
effective_host,
allow_private_ips=allow_private_ips,
_resolved_ips=resolved_ips,
allow_nat64=allow_nat64,
block_link_local=block_link_local,
):
if NotificationURLValidator._is_private_ip(
effective_host,
allow_private_ips=True,
_resolved_ips=resolved_ips,
allow_nat64=True,
block_link_local=block_link_local,
):
if is_metadata_hostname(effective_host):
# Blocked by name (GCP, IBM Cloud classic), not by
# address: IBM's name resolves to an RFC1918 address.
logger.warning("Blocked cloud-metadata notification host")
return (
False,
"Blocked cloud-metadata hostname: "
f"{redact_and_bound_for_log(effective_host, _LOG_HOST_MAX_CHARS)}",
)
logger.warning(
"Blocked metadata or link-local notification host"
)
return (
False,
"Blocked cloud-metadata / link-local IP address: "
f"{redact_and_bound_for_log(effective_host, _LOG_HOST_MAX_CHARS)}",
)
logger.warning("Blocked private/internal notification host")
return (
False,
f"{NotificationURLValidator.PRIVATE_IP_REJECTION_PREFIX} "
f"{redact_and_bound_for_log(effective_host, _LOG_HOST_MAX_CHARS)}",
)
# Passed all security checks
return True, None
@staticmethod
def _compute_hint(
hostname: str,
resolved_ips: Optional[List[ResolvedIP]],
*,
block_link_local: bool = False,
) -> bool:
"""Return True iff the combined elevated policy
(LDR_NOTIFICATIONS_ALLOW_PRIVATE_IPS=true AND
LDR_SECURITY_ALLOW_NAT64=true) would unblock every resolved
IP. Probing both flags jointly — rather than each in
isolation — is required for mixed address lists where
neither flag alone unblocks every IP (e.g. 10.0.0.1 needs
the private-IPs flag, 64:ff9b::5db8:d822 needs the NAT64
flag).
"""
hint = not NotificationURLValidator._host_blocks_at_level(
hostname,
allow_private_ips=True,
allow_nat64=True,
resolved_ips=resolved_ips,
block_link_local=block_link_local,
)
if not hint:
logger.opt(lazy=True).debug(
"hint suppressed: {} targets an always-blocked "
"category (metadata / 6to4 / Teredo / discard / "
"IPv4-Compatible / IPv4-Translated-SIIT / "
"NAT64-wrapped metadata)",
lambda: redact_and_bound_for_log(hostname, _LOG_HOST_MAX_CHARS),
)
return hint
@staticmethod
def validate_service_url_with_hint(
url: str, allow_private_ips: bool = False
) -> Tuple[bool, Optional[str], bool]:
"""Validate URL and compute the admin-hint decision, using a
two-phase approach to ensure DNS is only queried for URLs that
pass ALL deterministic (non-network) checks.
Phase 1 — structural validation (no DNS):
Calls ``_validate_service_url_impl`` with ``resolved_ips=[]``, which
suppresses DNS for every host-bearing private-IP check. IP literals
are still evaluated directly. This means bad schemes, illegal characters, parse
errors, and malformed URLs are all rejected WITHOUT network
activity.
Phase 2 — DNS resolution + IP policy (host-bearing destinations):
Only reached for HTTP or authority-plugin URLs with non-literal hosts that
passed Phase 1. Resolves DNS ONCE and shares the result across
the default-level rejection and the combined elevated-policy hint check,
closing the DNS-rebinding TOCTOU window. When DNS fails, the
failure is authoritative (``[]`` sentinel prevents retries).
For IP literals there is no DNS to rebind.
Args:
url: Service URL to validate
allow_private_ips: Operator-level flag. When True, the
private address categories (RFC1918 / CGNAT / loopback
/ IPv6 ULA; link-local stays blocked) are already permitted at this
level. ``hint_would_help`` may still be True for a
rejected NAT64-wrapped non-metadata destination,
because the NAT64 carve-out is governed by the separate
``allow_nat64`` path rather than this flag.
Returns:
``(is_valid, error_msg, hint_would_help)``:
* ``is_valid`` — True iff URL passes at the requested
``allow_private_ips`` level.
* ``error_msg`` — None on success, the validator's reason
on rejection (identical to ``validate_service_url``).
* ``hint_would_help`` — True iff enabling the documented
escape hatches together
(``LDR_NOTIFICATIONS_ALLOW_PRIVATE_IPS`` for
RFC1918/CGNAT/loopback/IPv6 ULA, never link-local), and
``LDR_SECURITY_ALLOW_NAT64`` for NAT64-wrapped
non-metadata destinations) would unblock all resolved
addresses — covering cases needing one or both flags.
Always False when ``is_valid`` is True. May still be
True under ``allow_private_ips=True`` for a rejected
NAT64-wrapped non-metadata destination, because the
NAT64 carve-out is governed by the separate
``allow_nat64`` path. Only meaningful when
``error_msg`` starts with
``PRIVATE_IP_REJECTION_PREFIX`` (i.e., the URL was
rejected for an http(s) private-IP target).
Caller contract:
``notifications.service.NotificationService.test_service``
calls this to surface the validator's reason AND decide
whether to append the admin env-var hint in a single pass.
The previous design called ``validate_service_url`` two to
three times (once at the default level, then one or two
more via the former ``_admin_hint_would_help`` helper for
the private-IPs and NAT64 probes), opening a DNS-rebinding
window between the resolutions. The parametrized test
``test_test_service_ip_rejection_matrix`` and the direct
contract test
``test_validate_service_url_with_hint_contract`` in
tests/web/services/test_notification_coverage.py pin this
end-to-end.
"""
if not url or not isinstance(url, str):
return False, "Service URL must be a non-empty string", False
url = url.strip()
if allow_private_ips and not url:
return (
False,
"Service URL must have a protocol (e.g., https://)",
False,
)
# ------------------------------------------------------------------
# Phase 1: structural validation (no DNS for hostnames).
#
# resolved_ips=[] suppresses DNS in host-bearing private-IP checks
# (_host_blocks_at_level treats [] as "no blocked IPs"). IP
# literals are still checked directly. This means
# ALL deterministic rejections (bad scheme, illegal chars, parse
# errors, non-ASCII host, invalid structure) complete before any
# attacker-controlled DNS query.
# ------------------------------------------------------------------
is_valid, error_msg = (
NotificationURLValidator._validate_service_url_impl(
url,
allow_private_ips=allow_private_ips,
resolved_ips=[],
)
)
try:
destination = parse_notification_destination(url)
except NotificationDestinationError:
return is_valid, error_msg, False
hostname = NotificationURLValidator._normalize_host(
destination.effective_host
)
# Same link-local policy as ``_validate_service_url_impl``: the
# opt-in never unblocks link-local, so the hint must not offer it.
block_link_local = True
if not is_valid:
if error_msg in (
AMBIGUOUS_NUMERIC_IPV4_HOST_ERROR,
ENCODED_NUMERIC_IPV4_HOST_ERROR,
):
return False, error_msg, False
if (
not error_msg
or not error_msg.startswith(
NotificationURLValidator.PRIVATE_IP_REJECTION_PREFIX
)
or not hostname
):
logger.opt(lazy=True).debug(
"hint suppressed: non-private-IP rejection ({})",
# (#6938: redacted before it is cut, and only when a
# DEBUG sink takes the line.)
lambda: (
redact_and_bound_for_log(error_msg, 60)
if error_msg
else "<none>"
),
)
return False, error_msg, False
return (
False,
error_msg,
NotificationURLValidator._compute_hint(
hostname, None, block_link_local=block_link_local
),
)
if (
not hostname
or destination.kind is NotificationDestinationKind.VENDOR_PLUGIN
):
return True, None, False
try:
ipaddress.ip_address(hostname)
except ValueError:
pass
else:
return True, None, False
# Resolve once after structural validation, then reuse that address
# set for the decision and operator hint. The send-time guard covers
# any later DNS change.
dns_result = NotificationURLValidator._resolve_hostname_ips(hostname)
resolved_ips: List[ResolvedIP] = (
dns_result if dns_result is not None else []
)
is_valid, error_msg = (
NotificationURLValidator._validate_service_url_impl(
url,
allow_private_ips=allow_private_ips,
resolved_ips=resolved_ips,
)
)
if is_valid:
return True, None, False
if not error_msg or not error_msg.startswith(
NotificationURLValidator.PRIVATE_IP_REJECTION_PREFIX
):
return False, error_msg, False
return (
False,
error_msg,
NotificationURLValidator._compute_hint(
hostname, resolved_ips, block_link_local=block_link_local
),
)
@staticmethod
def validate_service_url_strict(
url: str, allow_private_ips: bool = False
) -> bool:
"""
Strict validation that raises an exception on invalid URLs.
Args:
url: Service URL to validate
allow_private_ips: Whether to allow private IPs (default: False)
Returns:
True if valid
Raises:
NotificationURLValidationError: If URL fails security validation
"""
is_valid, error_message = NotificationURLValidator.validate_service_url(
url, allow_private_ips
)
if not is_valid:
raise NotificationURLValidationError(
f"Notification service URL validation failed: {error_message}"
)
return True
@staticmethod
def validate_multiple_urls(
urls: str, allow_private_ips: bool = False, separator: str = ","
) -> Tuple[bool, Optional[str]]:
"""
Validate multiple separator-delimited service URLs.
Args:
urls: Service URLs delimited by ``separator``
allow_private_ips: Whether to allow private IPs (default: False)
separator: URL separator (default: ",")
Returns:
Tuple of (all_valid, error_message)
- all_valid: True if all URLs pass validation
- error_message: None if all valid, first error if any invalid
"""
if not urls or not isinstance(urls, str):
return False, "Service URLs must be a non-empty string"
# Match Apprise's scheme-aware partition so commas inside one service
# URL are preserved, while rejecting URL-like fragments it repairs
# away or absorbs into another entry.
url_list, invalid_fragment = parse_notification_url_list(
urls, separator
)
if invalid_fragment is not None:
# The fragment is refused because the INPUT does not partition
# unambiguously, not because the fragment itself is a bad URL.
# A fragment can be a perfectly valid URL on its own — the
# illegal character that carved it out may only trail the
# entry, or the token after it may be a well-formed vendor URL
# smuggled behind a hostile one — in which case
# ``validate_service_url`` returns ``(True, None)`` and the
# unconditional interpolation below produced the nonsense
# "Invalid notification service URL: None". Fall back to the
# parse-level reason, whose static text echoes nothing at all.
# The fragment's raw text is never echoed WHOLE, but the
# ``validate_service_url`` message used by the other branch is
# not credential-free by construction: a few of its returns
# interpolate a piece the caller supplied (the scheme in
# "Unsupported protocol: …", the hostname in the private-IP /
# metadata rejections). That is the same exposure the
# single-URL path already has, and no Apprise credential lives
# in a scheme or a resolvable hostname — but do not read this
# as a guarantee that nothing derived from the fragment can
# reach the user.
_, error_message = NotificationURLValidator.validate_service_url(
invalid_fragment, allow_private_ips
)
if not error_message:
error_message = (
"the URL list could not be parsed unambiguously "
"(unencoded space, backslash or control character, "
"or a fragment with no scheme)"
)
return (
False,
f"Invalid notification service URL: {error_message}",
)
if not url_list:
return False, "No valid URLs found after parsing"
# Validate each URL
for url in url_list:
is_valid, error_message = (
NotificationURLValidator.validate_service_url(
url, allow_private_ips
)
)
if not is_valid:
# Return first error found
return (
False,
f"Invalid notification service URL: {error_message}",
)
# All URLs passed validation
return True, None