sentrycove 0.2.1__py3-none-any.whl

sentrycove/__init__.py

@@ -0,0 +1,22 @@
+"""SentryCove: an open-source agent firewall and early-warning layer for web apps."""
+
+from .alerts import Alert, AlertDispatcher, LogSink, WebhookSink
+from .config import Config, load_config
+from .engine import Engine, RequestInfo, Verdict
+from .identity import AgentIdentity
+from .middleware import SentryCove
+
+__all__ = [
+    "SentryCove",
+    "AgentIdentity",
+    "Alert",
+    "AlertDispatcher",
+    "Config",
+    "Engine",
+    "RequestInfo",
+    "Verdict",
+    "LogSink",
+    "WebhookSink",
+    "load_config",
+]
+__version__ = "0.2.1"

sentrycove/__main__.py

@@ -0,0 +1,7 @@
+"""``python -m sentrycove``."""
+
+import sys
+
+from .cli import main
+
+sys.exit(main())

sentrycove/alerts.py

@@ -0,0 +1,165 @@
+"""Early-warning alerts: de-duplicated, non-blocking, routed by severity."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import time
+from collections.abc import Callable
+from dataclasses import asdict, dataclass, field
+from typing import Optional, Protocol
+
+import httpx
+
+from .config import AlertsConfig, SinkConfig
+from .store import TTLCache
+
+log = logging.getLogger("sentrycove.alerts")
+
+SEVERITY_ORDER = {"low": 0, "medium": 1, "high": 2, "critical": 3}
+
+
+@dataclass(frozen=True)
+class Alert:
+    type: str
+    severity: str
+    title: str
+    detail: str = ""
+    client_ip: Optional[str] = None
+    method: Optional[str] = None
+    path: Optional[str] = None
+    agent: Optional[str] = None
+    action_taken: str = "none"
+    dedupe_key: str = ""
+    timestamp: float = field(default_factory=time.time)
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+class AlertSink(Protocol):
+    async def send(self, alert: Alert) -> None: ...
+
+    async def aclose(self) -> None: ...
+
+
+class LogSink:
+    def __init__(self, logger: logging.Logger = log) -> None:
+        self._log = logger
+
+    async def send(self, alert: Alert) -> None:
+        level = logging.WARNING if SEVERITY_ORDER[alert.severity] >= 2 else logging.INFO
+        self._log.log(level, "sentrycove alert %s", json.dumps(alert.to_dict(), sort_keys=True))
+
+    async def aclose(self) -> None:
+        return None
+
+
+def _slack_escape(text: str) -> str:
+    return text.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+
+
+class WebhookSink:
+    """POSTs JSON. ``slack=True`` sends a Slack-compatible ``{"text": ...}`` body."""
+
+    def __init__(self, url: str, timeout: float, slack: bool = False) -> None:
+        self._url = url
+        self._timeout = timeout
+        self._slack = slack
+        self._client: Optional[httpx.AsyncClient] = None
+
+    def _payload(self, alert: Alert) -> dict:
+        if not self._slack:
+            return alert.to_dict()
+        lines = [
+            f"*[{alert.severity.upper()}] {_slack_escape(alert.title)}*",
+            _slack_escape(alert.detail) if alert.detail else "",
+            f"IP: `{_slack_escape(alert.client_ip or '-')}`  Agent: `{_slack_escape(alert.agent or '-')}`",
+            f"Request: `{_slack_escape(alert.method or '-')} {_slack_escape(alert.path or '-')}`"
+            f"  Action: `{alert.action_taken}`",
+        ]
+        return {"text": "\n".join(line for line in lines if line)}
+
+    async def send(self, alert: Alert) -> None:
+        if self._client is None:
+            self._client = httpx.AsyncClient(timeout=self._timeout, follow_redirects=False)
+        resp = await self._client.post(self._url, json=self._payload(alert))
+        if resp.status_code >= 400:
+            log.warning("alert webhook returned HTTP %s", resp.status_code)
+
+    async def aclose(self) -> None:
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+
+def build_sink(cfg: SinkConfig, timeout: float) -> Optional[AlertSink]:
+    if cfg.type == "log":
+        return LogSink()
+    url = os.environ.get(cfg.url_env or "", "")
+    if not url:
+        log.warning("alert sink %s disabled: env var %s is not set", cfg.type, cfg.url_env)
+        return None
+    if not url.startswith("https://"):
+        log.warning("alert sink %s disabled: URL must use https", cfg.type)
+        return None
+    return WebhookSink(url, timeout, slack=cfg.type == "slack")
+
+
+class AlertDispatcher:
+    def __init__(
+        self,
+        sinks: list[tuple[AlertSink, str]],
+        cooldown_seconds: float,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self._sinks = sinks
+        self._cooldown = cooldown_seconds
+        self._recent: Optional[TTLCache[str, bool]] = (
+            TTLCache(50_000, cooldown_seconds, clock) if cooldown_seconds > 0 else None
+        )
+        self._tasks: set[asyncio.Task] = set()
+
+    @classmethod
+    def from_config(cls, cfg: AlertsConfig) -> AlertDispatcher:
+        sinks: list[tuple[AlertSink, str]] = []
+        for sink_cfg in cfg.sinks:
+            sink = build_sink(sink_cfg, cfg.timeout_seconds)
+            if sink is not None:
+                sinks.append((sink, sink_cfg.min_severity))
+        return cls(sinks, cfg.cooldown_seconds)
+
+    def emit(self, alert: Alert) -> bool:
+        """Queue an alert for delivery. Returns False if suppressed as a duplicate."""
+        key = alert.dedupe_key or f"{alert.type}|{alert.client_ip}|{alert.path}"
+        if self._recent is not None:
+            if key in self._recent:
+                return False
+            self._recent.set(key, True)
+        loop = asyncio.get_running_loop()
+        for sink, min_sev in self._sinks:
+            if SEVERITY_ORDER[alert.severity] < SEVERITY_ORDER[min_sev]:
+                continue
+            task = loop.create_task(self._deliver(sink, alert))
+            self._tasks.add(task)
+            task.add_done_callback(self._tasks.discard)
+        return True
+
+    @staticmethod
+    async def _deliver(sink: AlertSink, alert: Alert) -> None:
+        try:
+            await sink.send(alert)
+        except Exception as exc:  # delivery problems must never affect traffic
+            log.warning("alert delivery via %s failed: %s", type(sink).__name__, exc)
+
+    async def drain(self) -> None:
+        """Wait for queued deliveries (useful in tests and on shutdown)."""
+        while self._tasks:
+            await asyncio.gather(*list(self._tasks), return_exceptions=True)
+
+    async def aclose(self) -> None:
+        await self.drain()
+        for sink, _ in self._sinks:
+            await sink.aclose()

sentrycove/cli.py

@@ -0,0 +1,127 @@
+"""Command line entry point: ``sentrycove proxy | sidecar | check-config``."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+import sys
+from collections.abc import Sequence
+from typing import Optional
+
+from . import __version__
+from .config import load_config
+from .engine import Engine
+
+log = logging.getLogger("sentrycove")
+
+
+def _env_int(name: str, default: int) -> int:
+    raw = os.environ.get(name)
+    if raw is None or raw == "":
+        return default
+    try:
+        return int(raw)
+    except ValueError:
+        raise SystemExit(f"{name} must be a number, got {raw!r}") from None
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="sentrycove", description="Agent firewall and early-warning layer.")
+    parser.add_argument("--version", action="version", version=f"sentrycove {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    def common(p: argparse.ArgumentParser, default_port: int) -> None:
+        p.add_argument("--config", default=os.environ.get("SENTRYCOVE_CONFIG"), help="policy YAML file")
+        p.add_argument("--host", default=os.environ.get("SENTRYCOVE_HOST", "127.0.0.1"), help="address to listen on")
+        p.add_argument("--port", type=int, default=_env_int("SENTRYCOVE_PORT", default_port))
+
+    proxy = sub.add_parser("proxy", help="reverse proxy in front of an app in any language")
+    common(proxy, 8080)
+    proxy.add_argument(
+        "--upstream", default=os.environ.get("SENTRYCOVE_UPSTREAM"), help="the app to protect, e.g. http://app:3000"
+    )
+    proxy.add_argument(
+        "--rewrite-host", action="store_true", help="send the upstream's own host name instead of the client's Host"
+    )
+
+    sidecar = sub.add_parser("sidecar", help="decision API for the Node and ASP.NET Core middleware")
+    common(sidecar, 8787)
+
+    check = sub.add_parser("check-config", help="validate a policy file and exit")
+    check.add_argument("path")
+    return parser
+
+
+def _load_engine(config_path: Optional[str]) -> Engine:
+    if not config_path:
+        log.warning("no --config given: running with defaults (monitor mode, no rules, honeypots or login paths)")
+    engine = Engine(config_path or {})
+    log.info("policy loaded: mode=%s rules=%d", engine.config.mode, len(engine.config.rules))
+    return engine
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    args = build_parser().parse_args(argv)
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s %(message)s")
+
+    if args.command == "check-config":
+        try:
+            cfg = load_config(args.path)
+        except Exception as exc:
+            print(f"invalid: {exc}", file=sys.stderr)
+            return 1
+        print(f"ok: mode={cfg.mode}, {len(cfg.rules)} rules, {len(cfg.honeypots.paths)} honeypot paths")
+        return 0
+
+    try:
+        import uvicorn
+    except ImportError:
+        print('this command needs the server extra: pip install "sentrycove[server]"', file=sys.stderr)
+        return 1
+
+    if args.command == "proxy":
+        if not args.upstream:
+            print("--upstream (or SENTRYCOVE_UPSTREAM) is required, e.g. http://127.0.0.1:3000", file=sys.stderr)
+            return 2
+        from .proxy import create_proxy_app
+
+        try:
+            app = create_proxy_app(args.upstream, engine=_load_engine(args.config), preserve_host=not args.rewrite_host)
+        except ValueError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 2
+        log.info("proxying %s:%d -> %s", args.host, args.port, args.upstream)
+        # proxy_headers=False: SentryCove resolves the client address itself (trusted_proxy_hops).
+        uvicorn.run(
+            app,
+            host=args.host,
+            port=args.port,
+            proxy_headers=False,
+            server_header=False,
+            date_header=False,
+            access_log=False,
+            log_config=None,
+        )
+        return 0
+
+    token = os.environ.get("SENTRYCOVE_API_TOKEN", "")
+    from .sidecar import MIN_TOKEN_LENGTH, DecisionAPI
+
+    if len(token) < MIN_TOKEN_LENGTH:
+        print(
+            f"SENTRYCOVE_API_TOKEN must be set to a secret of at least {MIN_TOKEN_LENGTH} characters "
+            '(generate one with: python -c "import secrets; print(secrets.token_urlsafe(32))")',
+            file=sys.stderr,
+        )
+        return 2
+    api = DecisionAPI(_load_engine(args.config), token)
+    log.info("decision API listening on %s:%d", args.host, args.port)
+    uvicorn.run(
+        api, host=args.host, port=args.port, proxy_headers=False, server_header=False, access_log=False, log_config=None
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

sentrycove/clientip.py

@@ -0,0 +1,43 @@
+"""Client IP resolution that cannot be spoofed via X-Forwarded-For.
+
+Only the right-most ``trusted_proxy_hops`` entries of X-Forwarded-For are
+written by proxies you control; anything to their left is client-supplied.
+With ``trusted_proxy_hops: 0`` the header is ignored entirely.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+from typing import Optional
+
+
+def _valid_ip(value: str) -> Optional[str]:
+    try:
+        addr = ipaddress.ip_address(value.strip())
+    except ValueError:
+        return None
+    # "::ffff:203.0.113.9" (IPv4 seen through a dual-stack socket) is the same client as "203.0.113.9".
+    if addr.version == 6 and addr.ipv4_mapped is not None:
+        addr = addr.ipv4_mapped
+    return str(addr)
+
+
+def resolve_client_ip(peer: Optional[str], xff_values: list[str], trusted_proxy_hops: int) -> str:
+    peer_ip = _valid_ip(peer) if peer else None
+    if trusted_proxy_hops > 0 and xff_values:
+        chain = [p.strip() for v in xff_values for p in v.split(",") if p.strip()]
+        if len(chain) >= trusted_proxy_hops:
+            candidate = _valid_ip(chain[-trusted_proxy_hops])
+            if candidate:
+                return candidate
+    return peer_ip or "unknown"
+
+
+def network_prefix(ip: str) -> str:
+    """Coarse network bucket: /24 for IPv4, /48 for IPv6."""
+    try:
+        addr = ipaddress.ip_address(ip)
+    except ValueError:
+        return ip
+    bits = 24 if addr.version == 4 else 48
+    return str(ipaddress.ip_network(f"{addr}/{bits}", strict=False))

sentrycove/config.py

@@ -0,0 +1,187 @@
+"""Configuration model, loaded from YAML.
+
+Unknown keys are rejected so that a typo in a policy file fails loudly
+at startup instead of silently disabling a protection.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Literal, Optional, Union
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+Action = Literal["allow", "monitor", "block"]
+Severity = Literal["low", "medium", "high", "critical"]
+
+AGENT_KINDS = ("verified", "declared", "automation", "unclassified")
+_SELECTOR_RE = re.compile(r"^(\*|(verified|declared|automation|unclassified)(:[A-Za-z0-9_.\-]+)?)$")
+
+
+class _Strict(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+
+class TrustedAgent(_Strict):
+    """A signer whose key directory we are willing to fetch."""
+
+    name: str = Field(pattern=r"^[A-Za-z0-9_.\-]+$")
+    signature_agent: str = Field(description="Origin, e.g. https://agent.example")
+
+    @field_validator("signature_agent")
+    @classmethod
+    def _https_origin(cls, v: str) -> str:
+        v = v.rstrip("/")
+        if not re.fullmatch(r"https://[A-Za-z0-9.\-]+(:[0-9]{1,5})?", v):
+            raise ValueError("signature_agent must be an https origin with no path")
+        return v.lower()
+
+
+class WebBotAuthConfig(_Strict):
+    enabled: bool = True
+    trusted_agents: list[TrustedAgent] = Field(default_factory=list)
+    max_signature_age_seconds: int = Field(default=300, gt=0)
+    max_validity_seconds: int = Field(default=86400, gt=0)
+    clock_skew_seconds: int = Field(default=30, ge=0)
+    directory_cache_seconds: int = Field(default=3600, gt=0)
+    directory_fetch_timeout_seconds: float = Field(default=2.0, gt=0)
+    require_nonce: bool = False
+
+
+class Rule(_Strict):
+    name: str
+    paths: list[str] = Field(default_factory=lambda: ["*"])
+    methods: list[str] = Field(default_factory=lambda: ["*"])
+    agents: list[str] = Field(default_factory=lambda: ["*"])
+    action: Action
+    severity: Severity = "medium"
+
+    @field_validator("methods")
+    @classmethod
+    def _upper(cls, v: list[str]) -> list[str]:
+        return [m.upper() for m in v]
+
+    @field_validator("agents")
+    @classmethod
+    def _selectors(cls, v: list[str]) -> list[str]:
+        for sel in v:
+            if not _SELECTOR_RE.match(sel):
+                raise ValueError(
+                    f"invalid agent selector {sel!r}; use '*', a kind ({', '.join(AGENT_KINDS)}) or 'kind:name'"
+                )
+        return v
+
+
+class HoneypotConfig(_Strict):
+    enabled: bool = True
+    paths: list[str] = Field(default_factory=list)
+    ban_seconds: int = Field(default=3600, ge=0)
+    response_status: int = Field(default=404, ge=400, le=599)
+
+
+class LoginConfig(_Strict):
+    enabled: bool = True
+    paths: list[str] = Field(default_factory=list)
+    failure_statuses: list[int] = Field(default_factory=lambda: [401, 403])
+    per_ip_threshold: int = Field(default=10, gt=0)
+    global_threshold: int = Field(default=200, gt=0)
+    window_seconds: int = Field(default=60, gt=0)
+
+
+class SessionConfig(_Strict):
+    enabled: bool = True
+    cookie_names: list[str] = Field(default_factory=list)
+    ttl_seconds: int = Field(default=86400, gt=0)
+    alert_on_ip_change: bool = False
+
+
+class SinkConfig(_Strict):
+    type: Literal["log", "webhook", "slack"]
+    url_env: Optional[str] = Field(
+        default=None, description="Name of the env var holding the URL (never the URL itself)"
+    )
+    min_severity: Severity = "medium"
+
+    @model_validator(mode="after")
+    def _needs_url(self) -> SinkConfig:
+        if self.type in ("webhook", "slack") and not self.url_env:
+            raise ValueError(f"{self.type} sink requires url_env")
+        return self
+
+
+class AlertsConfig(_Strict):
+    sinks: list[SinkConfig] = Field(default_factory=lambda: [SinkConfig(type="log", min_severity="low")])
+    cooldown_seconds: int = Field(default=300, ge=0)
+    timeout_seconds: float = Field(default=3.0, gt=0)
+
+
+class LimitsConfig(_Strict):
+    max_tracked_keys: int = Field(default=100_000, gt=0)
+
+
+class Config(_Strict):
+    version: Literal[1] = 1
+    mode: Literal["monitor", "enforce"] = "monitor"
+    fail_open: bool = True
+    trusted_proxy_hops: int = Field(default=0, ge=0, le=10)
+    declared_bot_tokens: list[str] = Field(
+        default_factory=lambda: [
+            "GPTBot",
+            "ChatGPT-User",
+            "OAI-SearchBot",
+            "ClaudeBot",
+            "Claude-User",
+            "Claude-SearchBot",
+            "PerplexityBot",
+            "Perplexity-User",
+            "Google-Extended",
+            "Googlebot",
+            "Bingbot",
+            "Meta-ExternalAgent",
+            "Meta-WebIndexer",
+            "Bytespider",
+            "CCBot",
+            "Amazonbot",
+            "Applebot",
+        ]
+    )
+    automation_tokens: list[str] = Field(
+        default_factory=lambda: [
+            "python-requests",
+            "python-httpx",
+            "aiohttp",
+            "curl/",
+            "wget/",
+            "go-http-client",
+            "okhttp",
+            "java/",
+            "libwww-perl",
+            "scrapy",
+            "headlesschrome",
+            "phantomjs",
+            "puppeteer",
+            "playwright",
+            "selenium",
+        ]
+    )
+    web_bot_auth: WebBotAuthConfig = Field(default_factory=WebBotAuthConfig)
+    rules: list[Rule] = Field(default_factory=list)
+    honeypots: HoneypotConfig = Field(default_factory=HoneypotConfig)
+    login: LoginConfig = Field(default_factory=LoginConfig)
+    session: SessionConfig = Field(default_factory=SessionConfig)
+    alerts: AlertsConfig = Field(default_factory=AlertsConfig)
+    limits: LimitsConfig = Field(default_factory=LimitsConfig)
+
+
+def load_config(source: Union[str, Path, dict]) -> Config:
+    """Load configuration from a YAML file path or an already-parsed dict."""
+    if isinstance(source, dict):
+        data = source
+    else:
+        with open(source, encoding="utf-8") as fh:
+            data = yaml.safe_load(fh) or {}
+    if not isinstance(data, dict):
+        raise ValueError("configuration root must be a mapping")
+    return Config.model_validate(data)

sentrycove/detectors.py

@@ -0,0 +1,133 @@
+"""Detectors that produce early warnings without any change to the app."""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+from typing import Optional
+
+from .clientip import network_prefix
+from .config import HoneypotConfig, LoginConfig, SessionConfig
+from .paths import path_matches
+from .store import SlidingWindowCounter, TTLCache
+
+
+class HoneypotDetector:
+    """Decoy paths no legitimate user ever requests (e.g. /.env, /backup.zip)."""
+
+    def __init__(self, cfg: HoneypotConfig) -> None:
+        self._cfg = cfg
+
+    def is_trap(self, path: str) -> bool:
+        return self._cfg.enabled and path_matches(path, self._cfg.paths)
+
+
+@dataclass(frozen=True)
+class LoginSignal:
+    scope: str  # "ip" | "global"
+    count: int
+    window_seconds: int
+
+
+class LoginMonitor:
+    """Detects credential stuffing / brute force from failed-login responses."""
+
+    def __init__(self, cfg: LoginConfig, max_keys: int) -> None:
+        self._cfg = cfg
+        self._per_ip: SlidingWindowCounter[str] = SlidingWindowCounter(
+            cfg.window_seconds, max_keys, cfg.per_ip_threshold
+        )
+        self._global: SlidingWindowCounter[str] = SlidingWindowCounter(cfg.window_seconds, 1, cfg.global_threshold)
+
+    def is_login_path(self, path: str) -> bool:
+        return self._cfg.enabled and path_matches(path, self._cfg.paths)
+
+    def is_failure(self, status: int) -> bool:
+        return status in self._cfg.failure_statuses
+
+    def record_failure(self, client_ip: Optional[str]) -> list[LoginSignal]:
+        """Count one failed login. Pass ``None`` when the client address is unknown:
+        the failure then counts only towards the site-wide total."""
+        signals = []
+        if client_ip is not None:
+            ip_count = self._per_ip.hit(client_ip)
+            if ip_count >= self._cfg.per_ip_threshold:
+                signals.append(LoginSignal("ip", ip_count, self._cfg.window_seconds))
+        global_count = self._global.hit("all")
+        if global_count >= self._cfg.global_threshold:
+            signals.append(LoginSignal("global", global_count, self._cfg.window_seconds))
+        return signals
+
+
+def parse_cookies(header_values: list[str]) -> dict[str, str]:
+    cookies: dict[str, str] = {}
+    for header in header_values:
+        for part in header.split(";"):
+            name, sep, value = part.strip().partition("=")
+            if sep and name and name not in cookies:
+                cookies[name] = value.strip().strip('"')
+    return cookies
+
+
+@dataclass(frozen=True)
+class _Fingerprint:
+    user_agent: str
+    accept_language: str
+    net: str
+
+
+@dataclass(frozen=True)
+class SessionSignal:
+    kind: str  # "device_change" | "network_change"
+    severity: str
+    detail: str
+    session_hash: str
+
+
+class SessionMonitor:
+    """Flags a session token being used from a different device/network.
+
+    The first fingerprint seen for a session is kept (an attacker replaying a
+    stolen cookie cannot overwrite it). Session IDs are stored only as
+    SHA-256 hashes.
+    """
+
+    def __init__(self, cfg: SessionConfig, max_keys: int) -> None:
+        self._cfg = cfg
+        self._seen: TTLCache[str, _Fingerprint] = TTLCache(max_keys, cfg.ttl_seconds)
+
+    def observe(
+        self,
+        cookie_headers: list[str],
+        client_ip: str,
+        user_agent: str,
+        accept_language: str,
+    ) -> Optional[SessionSignal]:
+        if not self._cfg.enabled or not self._cfg.cookie_names:
+            return None
+        cookies = parse_cookies(cookie_headers)
+        token = next((cookies[n] for n in self._cfg.cookie_names if cookies.get(n)), None)
+        if token is None:
+            return None
+        session_hash = hashlib.sha256(token.encode("utf-8")).hexdigest()[:16]
+        current = _Fingerprint(user_agent, accept_language, network_prefix(client_ip))
+        known = self._seen.get(session_hash)
+        if known is None:
+            self._seen.set(session_hash, current)
+            return None
+        if known.user_agent != current.user_agent or known.accept_language != current.accept_language:
+            return SessionSignal(
+                "device_change",
+                "high",
+                f"session first seen from network {known.net}, now used by a different "
+                f"browser/device from {current.net}",
+                session_hash,
+            )
+        if known.net != current.net and self._cfg.alert_on_ip_change:
+            return SessionSignal(
+                "network_change",
+                "low",
+                f"session moved from network {known.net} to {current.net}",
+                session_hash,
+            )
+        return None