procproxy 0.1.0__py3-none-any.whl

proxycore/backend/windivert/__init__.py

@@ -0,0 +1,657 @@
+"""路线 A · WinDivert 后端。
+
+数据流：
+
+```
+拦截线程
+  WinDivert.recv()
+    ├─ 解析 IP/TCP
+    ├─ src_port == sink 端口？ → 方向一：sink 的应答
+    │     ├─ 查表（按客户端端口）取原始目标；查不到 → 原样放行
+    │     ├─ 改写 src = 原始目标               # 客户端 socket 才认这条应答
+    │     ├─ packet.direction = INBOUND        #  反射：内核才会投递给本地 socket
+    │     └─ send
+    └─ 方向二：出向包
+          ├─ 已在改道表里 → 直接改写目的（后续所有的包都要改，不只 SYN）
+          └─ 新连接的 SYN → 查 PID → decide（先记账、查表竞态）
+                ├─ DIRECT → 原样放行
+                ├─ BLOCK  → 丢弃（不 send）
+                └─ PROXY  → 记账 → 改写 dst = sink → direction = INBOUND → send
+```
+
+为什么必须双向：只改首个 SYN 的话，握手在第二包就断，客户端的后续包仍发往
+原始目标，而 sink 的应答源地址是 sink、四元组对不上，会被内核直接丢弃，
+`accept()` 永不返回。症状是改道日志正常，但应用卡死。
+
+为什么必须翻方向标志：只改地址、不把包标记为"入向"，内核不会把它投递给本地
+socket。这是 WinDivert 官方 `streamdump` 示例的 "reflect" 手法，也是本实现
+最容易漏掉的一环。
+
+设计说明：
+* 不按 PID 过滤（WinDivert 没有这个能力，只能查表）；
+* 上游/sink 端点在用户态再判一次（过滤器排除是静态的，上游地址会变）；
+* 抓取范围是"所有出向 TCP"，本机每个出向 TCP 包都会过一次用户态：路线 A 透明
+  代理的固有开销；
+* 无 pydivert / 非管理员 / 非 Windows → `BackendUnavailable`（绝不静默直连）。
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import socket
+import threading
+import time
+from typing import Any
+
+from proxycore.backend.base import BackendUnavailable, BaseBackend
+from proxycore.log import EventLogger, get_logger
+from proxycore.types import Action, ConnRequest, Endpoint, ProcInfo, Proto
+
+from .filter import build_filter, upstream_ips_from_config
+from .pidmap import PortPidTable, is_supported
+from .pkt import IPPROTO_TCP, PacketError, ParsedPacket, reflect_packet
+
+LOG = EventLogger(get_logger("proxycore.backend.windivert"))
+
+DEFAULT_PRIORITY = 123  # WinDivert 优先级（文档未规定具体值）
+MAX_RECV_ERRORS = 5
+
+# 改道记录存活时长（秒）。反向路径在整条连接期间都要用这张表，
+# 所以不能在 accept 一次后就删。5 分钟是回收策略的取值。
+REDIRECT_TTL_S = 300.0
+# 每隔多少个包做一次 GC（避免每包都遍历字典）
+GC_EVERY_PACKETS = 512
+
+
+class WinDivertBackend(BaseBackend):
+    """路线 A 后端。"""
+
+    name = "windivert"
+    # 路线 A 完全不碰 UDP：两个句柄（v4/v6）的过滤器都以 `tcp` 开头，
+    # UDP 数据报根本进不来，更不可能被改写或阻断。
+    # `udp_policy` 在本后端下整体空转，包括 `443: block`（拦 QUIC）。
+    # 希望路线 A 至少做到"直连/阻断"两种，阻断那一半还没写。
+    supports_udp = False
+    supports_pid_native = False  # PID 必须查 GetExtendedTcpTable
+
+    def __init__(
+        self,
+        *,
+        config: Any = None,
+        dry_run: bool = False,
+        sink: Endpoint | None = None,
+        pid_table: PortPidTable | None = None,
+        **_ignored: Any,
+    ) -> None:
+        super().__init__()
+        self.config = config
+        self.dry_run = dry_run
+        self._sink = sink
+        self.pid_table = pid_table or PortPidTable()
+        self._handle: Any = None
+        self._handle6: Any = None
+        self._thread: threading.Thread | None = None
+        self._thread6: threading.Thread | None = None
+        self._stop = threading.Event()
+        self._filter = ""
+        self._filter6 = ""
+        self._exclude_ips: list[str] = []
+        # (地址族, 客户端源端口) → (原始目标, 记账时间)。反向路径在整条连接期间都要读它。
+        #
+        # 键里必须带地址族：v4 与 v6 的临时端口来自同一段，两条连接完全可能撞同一个端口号。
+        # 只按端口做键的话，v6 的 sink 连接会被拨到 v4 那条连接的原始目标上。
+        # 对代理来说"连错目标"是红线。
+        self._redirects: dict[tuple[bool, int], tuple[Endpoint, float]] = {}
+        # (地址族, 客户端源端口) → (客户端真实地址, 正向包的接口索引)。
+        # 反向路径要把 sink 的应答送回"客户端真实地址"，可回环里的应答包只带着
+        # <回环>:<客户端端口>，反查不出真实地址；接口索引同理（见 _reflect_sink_reply）。
+        # 与 `_redirects` 同生共死：增删一律走 _record_redirect / _forget_redirect。
+        self._redirect_peer: dict[tuple[bool, int], tuple[str, int]] = {}
+        self._recv_errors = 0
+        self._unknown_pid = 0
+        self._packet_count = 0
+        # pydivert 的方向常量，在 start() 里缓存（避免每包都 import）
+        self._dir_inbound: Any = None
+        self._dir_outbound: Any = None
+        self.last_error = ""
+
+    # ------------------------------------------------------------ 生命周期 --
+    def start(self) -> None:
+        if not is_supported():
+            raise BackendUnavailable(
+                f"WinDivert 后端仅支持 Windows（当前 os.name={os.name}）；"
+                "联调请用 backend=null"
+            )
+        try:
+            import pydivert
+        except ImportError as exc:
+            raise BackendUnavailable(
+                f"缺少 pydivert：{exc}。路线 A 需要 `pip install pydivert psutil`，且必须管理员运行"
+            ) from exc
+        # 反射要用它把改写后的包标记为"入向"（否则内核不投递给本地 socket）；
+        # 正向改道反过来要用 OUTBOUND（理由见 _redirect_to_sink）。
+        self._dir_inbound = pydivert.Direction.INBOUND
+        self._dir_outbound = pydivert.Direction.OUTBOUND
+
+        sink = self._sink or self._sink_from_config()
+        self._exclude_ips = upstream_ips_from_config(self.config)
+        self._filter = build_filter(
+            sink_addr=sink.addr, sink_port=sink.port, exclude_ips=self._exclude_ips
+        )
+        LOG.info("windivert_filter", filter_expr=self._filter, sink=str(sink), exclude=self._exclude_ips)
+
+        try:
+            self._handle = pydivert.WinDivert(self._filter, priority=DEFAULT_PRIORITY)
+            self._handle.open()
+        except Exception as exc:
+            raise BackendUnavailable(
+                f"打开 WinDivert 失败：{exc}。常见原因：① 非管理员；② EDR/杀软拦截了 WinDivert；"
+                "③ 已有其它 WinDivert 实例。诊断：`sc query WinDivert`"
+            ) from exc
+
+        self._open_v6_handle(pydivert, sink)
+
+        super().start()
+        self._stop.clear()
+        self._thread = threading.Thread(
+            target=self._capture_loop, args=(self._handle,), name="ppx-windivert", daemon=True
+        )
+        self._thread.start()
+        if self._handle6 is not None:
+            self._thread6 = threading.Thread(
+                target=self._capture_loop, args=(self._handle6,), name="ppx-windivert6", daemon=True
+            )
+            self._thread6.start()
+        LOG.info("windivert_started", dry_run=self.dry_run, ipv6=self._handle6 is not None)
+
+    def _open_v6_handle(self, pydivert: Any, sink: Endpoint) -> None:
+        """开第二个句柄抓 IPv6（一个句柄一条过滤器：WinDivert 的硬约束）。
+
+        不静默直连（AGENTS.md）：v6 打不开时不能装作没事。v4 那条过滤器用的是
+        `ip.DstAddr`（IPv4 专有字段），WinDivert 里"字段与报文不相关 ⇒ test 判 false"，
+        所以 v6 报文一个都不会进 v4 通道，双栈目标由 Windows 优先选 v6，
+        漏过就是真实 IP 直接出网。打不开就 WARN 到日志里，让用户知道覆盖面只有 v4。
+        """
+        try:
+            self._filter6 = build_filter(
+                sink_addr="::1", sink_port=sink.port, exclude_ips=self._exclude_ips, ipv6=True
+            )
+            handle6 = pydivert.WinDivert(self._filter6, priority=DEFAULT_PRIORITY)
+            handle6.open()
+        except Exception as exc:  # noqa: BLE001 - v6 打不开不该让整个后端起不来
+            self._handle6 = None
+            self._filter6 = ""
+            LOG.warn(
+                "windivert_ipv6_not_intercepted",
+                msg="IPv6 句柄打开失败：IPv6 流量不会被拦截，将直连出去（真实 IP 可能泄漏）。"
+                "双栈目标由 Windows 优先选 v6",
+                error=str(exc),
+            )
+            return
+        self._handle6 = handle6
+        LOG.info("windivert_filter_ipv6", filter_expr=self._filter6, sink=f"[::1]:{sink.port}")
+
+    def stop(self) -> None:
+        self._stop.set()
+        handle, self._handle = self._handle, None
+        handle6, self._handle6 = self._handle6, None
+        for item in (handle, handle6):
+            if item is not None:
+                with contextlib.suppress(Exception):
+                    item.close()
+        thread, self._thread = self._thread, None
+        if thread is not None:
+            thread.join(timeout=2.0)  # 契约：stop() 后 2s 内不再回调 decide
+        thread6, self._thread6 = self._thread6, None
+        if thread6 is not None:
+            thread6.join(timeout=2.0)
+        self._redirects.clear()
+        self._redirect_peer.clear()
+        super().stop()
+        LOG.info("windivert_stopped", captured=self.stats().get("captured", 0))
+
+    # ------------------------------------------------------------ 改道 -----
+    def _record_redirect(
+        self, is_v6: bool, client_port: int, original: Endpoint, client_addr: str, ifidx: int
+    ) -> None:
+        """记账。"""
+        key = (bool(is_v6), int(client_port))
+        self._redirects[key] = (original, time.time())
+        self._redirect_peer[key] = (client_addr, ifidx)
+        self.set_active(redirects=len(self._redirects))
+
+    def _forget_redirect(self, key: tuple[bool, int]) -> None:
+        self._redirects.pop(key, None)
+        self._redirect_peer.pop(key, None)
+
+    def _touch_redirect(self, key: tuple[bool, int]) -> None:
+        """刷新活跃连接的时间戳。
+
+        TTL 必须从"最后一次流量"算，而不是从 SYN 算：超过 TTL 的连接一旦被
+        回收，后续包会走 `_send()` 原样发往真实目标，等于绕过代理。
+        """
+        entry = self._redirects.get(key)
+        if entry is not None:
+            self._redirects[key] = (entry[0], time.time())
+
+    @staticmethod
+    def _key_of(sock: object, backend_ctx: int) -> tuple[bool, int]:
+        """从 sink 递过来的套接字判断地址族（路线 A 的 `backend_ctx` 就是客户端源端口）。
+
+        sink 的 v4/v6 是两个监听套接字，`client.family` 天然带族信息，
+        所以不需要改后端契约里的 `backend_ctx: int`。
+        """
+        is_v6 = getattr(sock, "family", None) == socket.AF_INET6
+        return is_v6, int(backend_ctx)
+
+    def redirect(self, conn: ConnRequest, sink: Endpoint) -> bool:
+        """登记 sink 并记账（真正的报文改写发生在抓包循环里）。
+
+        先记账再发包：`_redirects[(地址族, 客户端源端口)] = (原始目标, 时间)`，sink 侧用源端口反查。
+
+        这里只更新目标与时间戳，不动 `_redirect_peer`，客户端真实地址与接口索引
+        只有抓包循环手里有（`_decide_and_record` 已经记过），本方法是给外部调用者的
+        入口，拿不到那两个值，覆写只会把反向路径要用的信息抹掉。
+        """
+        if not self.running:
+            self.count("failed")
+            return False
+        self._sink = sink
+        key = (bool(conn.dst.is_v6), int(conn.backend_id))
+        self._redirects[key] = (conn.dst, time.time())
+        self.set_active(redirects=len(self._redirects))
+        return True
+
+    def lookup_original(self, client_socket: object, backend_ctx: int) -> Endpoint | None:
+        """路线 A 的原始目标由会话表维护，本后端提供自己的映射作为兜底。
+
+        返回 None = 没有重定向记录（sink 必须关闭该连接）；
+        查询出错 = 抛异常（本实现没有会失败的查询路径）。
+
+        不弹出记录：反向路径还要用它把 sink 的应答改写成"来自原始目标"，
+        整条连接生命周期内都必须留着（回收由 `_gc_redirects` 按时间做）。
+        在这里 pop 会让反向路径拿不到目标。
+        按 (地址族, 端口) 查：v4/v6 同名端口是两条不同的连接（见 `_redirects` 的说明）。
+        """
+        entry = self._redirects.get(self._key_of(client_socket, backend_ctx))
+        return entry[0] if entry is not None else None
+
+    def _gc_redirects(self, now: float) -> int:
+        """回收超时的改道记录。"""
+        dead = [key for key, (_t, ts) in self._redirects.items() if now - ts > REDIRECT_TTL_S]
+        for key in dead:
+            self._forget_redirect(key)
+        if dead:
+            self.set_active(redirects=len(self._redirects))
+        return len(dead)
+
+    def on_udp(self, handler: Any) -> None:
+        raise NotImplementedError(
+            "本后端不捕获 UDP（两个句柄的过滤器都以 tcp 开头）：udp_policy 整体空转，"
+            "UDP/QUIC 一律直连出去，既不做 proxy 也不做 block。"
+        )
+    # ------------------------------------------------------------ 抓包 -----
+    def _sink_from_config(self) -> Endpoint:
+        sink_cfg = getattr(getattr(self.config, "service", None), "sink", None)
+        if sink_cfg is not None:
+            host = str(sink_cfg.host)
+            return Endpoint(addr=host, port=int(sink_cfg.port), is_v6=":" in host)
+        return Endpoint("127.0.0.1", 19080)
+
+    def _capture_loop(self, handle: Any) -> None:
+        """一个句柄一条线程：v4 一条、v6 一条（WinDivert 一个句柄只能有一条过滤器）。"""
+        if handle is None:  # pragma: no cover - 启动顺序错误
+            return
+        sink = self._sink or self._sink_from_config()
+        while not self._stop.is_set():
+            try:
+                packet = handle.recv()
+            except Exception as exc:  # noqa: BLE001 - 驱动被卸载 / 句柄失效
+                if self._stop.is_set():
+                    return
+                self._recv_errors += 1
+                self.last_error = str(exc)
+                if self._recv_errors > MAX_RECV_ERRORS:
+                    LOG.error("windivert_recv_failed", error=str(exc), errors=self._recv_errors)
+                    return
+                time.sleep(0.05)
+                continue
+
+            try:
+                self._handle_packet(packet, sink)
+            except Exception as exc:  # noqa: BLE001 - 单包失败不能让抓包线程死掉
+                LOG.error("windivert_packet_failed", error=str(exc))
+
+    def _handle_packet(self, packet: Any, sink: Endpoint) -> None:
+        """处理一个被拦下的包（两个方向都走这里）。
+
+        两个方向的注入方式必须不同：正向改成"回环→sink"并按出向注入，
+        反向改成"原始目标→客户端"并按入向注入。这是本机实测出来的硬约束，
+        细节见 `_redirect_to_sink` 与 `_reflect_sink_reply`。
+        """
+        self.count_decision("captured")
+        raw = bytes(getattr(packet, "raw", b"") or b"")
+        if not raw:  # pragma: no cover - pydivert 一定给 raw
+            self._send(packet)
+            return
+
+        try:
+            parsed = ParsedPacket.parse(raw)
+        except PacketError as exc:
+            LOG.debug("pkt_parse_skipped", error=str(exc))
+            self._send(packet)
+            return
+
+        if parsed.proto != IPPROTO_TCP:
+            # 过滤器以 `tcp` 开头，UDP 报文压根进不来；这里主要是 IPv6 扩展头
+            # （NextHeader=0/43/44/60）被解析器标成 proto=0 的情况。
+            # 放行等于让这部分流量绕过代理直连出去，所以按"无法处理"阻断并计数。
+            self.count("unsupported")
+            LOG.warn(
+                "pkt_unsupported_dropped",
+                proto=parsed.proto,
+                src=f"{parsed.src_addr}:{parsed.src_port}",
+                dst=f"{parsed.dst_addr}:{parsed.dst_port}",
+                warnings=parsed.warnings,
+                hint="报文无法解析/不是 TCP（可能是 IPv6 扩展头），已丢弃而不是直连",
+            )
+            return
+
+        self._packet_count += 1
+        if self._packet_count % GC_EVERY_PACKETS == 0:
+            self._gc_redirects(time.time())
+
+        # ---- 方向一：来自 sink 的包 → 反射成"来自原始目标" ----
+        # 只有本族的回环 sink 端口才算：v4 的 19080 与 v6 的 19080 是两条不同的流。
+        if parsed.src_port == sink.port and parsed.src_addr == self._loopback_for(parsed.is_v6):
+            self._reflect_sink_reply(packet, raw, parsed)
+            return
+
+        # ---- 方向二：出向包（客户端 → 目标） ----
+        self._handle_outbound(packet, raw, parsed, sink)
+
+    def _reflect_sink_reply(self, packet: Any, raw: bytes, parsed: ParsedPacket) -> None:
+        """sink 发出的应答：改写成"来自原始目标、发往客户端真实地址"，入向注入。
+
+        客户端 socket 在 SYN_SENT 里等的是 `原始目标` 的应答。sink 回的是
+        `sink → 客户端`，四元组不匹配，内核会直接丢弃，所以必须把源改掉。
+        查表用的是客户端端口（= 这条包的目的端口）。
+
+        目的地址也必须改：正向改道为了让报文走通回环，把源地址写成了回环地址
+        （v4 `127.0.0.1`、v6 `::1`），于是 sink 的应答目的是 `<回环>:<客户端端口>`，
+        而客户端 socket 其实挂在真实网卡地址上，不改回真实地址的话，这条应答
+        哪也去不了。真实地址存在 `_redirect_peer` 里（回环报文自身查不出来）。
+
+        注入接口索引同样要取正向包记下的那个：sink 的应答是从回环路径出来的，
+        它自带的索引是回环接口（实测 v4/v6 都是 1），拿它注入到网卡地址上会被丢掉。
+        """
+        key = (parsed.is_v6, parsed.dst_port)
+        entry = self._redirects.get(key)
+        if entry is None:
+            # 不是我们改道的连接（或记录已回收）→ 原样放行，不猜
+            self._send(packet)
+            return
+        self._touch_redirect(key)
+
+        original = entry[0]
+        peer = self._redirect_peer.get(key)
+        dst_addr = peer[0] if peer is not None else parsed.dst_addr
+        ifidx = peer[1] if peer is not None else None
+        try:
+            rewritten = reflect_packet(
+                raw,
+                src_addr=original.addr,
+                src_port=original.port,
+                dst_addr=dst_addr,
+                dst_port=parsed.dst_port,
+            )
+        except PacketError as exc:
+            self.count("failed")
+            LOG.error("reverse_rewrite_failed", dst=str(original), error=str(exc))
+            return
+
+        self._send_rewritten(packet, rewritten, outbound=False, ifidx=ifidx)
+
+    def _handle_outbound(
+        self, packet: Any, raw: bytes, parsed: ParsedPacket, sink: Endpoint
+    ) -> None:
+        """出向包：新连接先做决策，已有连接直接改写目的。"""
+        # 查表必须带地址族：v4 的 40000 号端口和 v6 的 40000 号端口是两条连接。
+        key = (parsed.is_v6, parsed.src_port)
+        established = self._redirects.get(key)
+
+        if established is not None:
+            self._touch_redirect(key)
+        else:
+            # 只有首个 SYN（SYN 置位且 ACK 未置位）才做决策；
+            # 其它包不是新连接（可能是没记上的短连接），原样放行。
+            if not parsed.is_syn_only:
+                self._send(packet)
+                return
+            if not self._decide_and_record(packet, parsed, sink):
+                return  # 决策结果是 DIRECT/BLOCK，_decide_and_record 已经处理完
+
+        self._redirect_to_sink(packet, raw, parsed, sink)
+
+    def _redirect_to_sink(
+        self, packet: Any, raw: bytes, parsed: ParsedPacket, sink: Endpoint
+    ) -> None:
+        """把出向包改写成"发给 sink"，用出向方式注入。
+
+        两个反直觉但实测必须的点（2026-10-01 本机逐条验证）：
+
+        1. 源地址也要改成回环地址，不能原样保留客户端的网卡地址。
+           报文得"整条都在回环里"才投递得进去：
+           `127.0.0.1:客户端端口 → 127.0.0.1:sink` 能到 sink；
+           而 `192.168.2.160:客户端端口 → 127.0.0.1:sink`（只改目的）
+           会被内核直接丢掉，协议栈拒绝"从真实接口进来的、目的是 127/8 的报文"。
+        2. 必须按出向注入，不能标成入向。入向注入的目的若是 127.0.0.1，
+           内核同样不投递（连同"挂在回环接口上""置 Loopback 位"都试过，均无效）；
+           出向注入则由协议栈按路由把它当作本机发出的回环流量，正常送到 sink。
+
+        源地址被改掉之后，sink 侧看到的对端是 `127.0.0.1:<客户端端口>`（v6 是
+        `[::1]:<客户端端口>`），所以它只能按端口反查原始目标（sink.py 就是这么做的），
+        客户端真实地址另行记录在 `_redirect_peer`，供反向路径用。
+
+        v6 沿用同一套规则：2026-10-01 用 `pinpoint13_v6.py` 实测，v4 的结论原样
+        搬到 v6 成立，`[::1]:客户端端口 → [::1]:sink`、出向注入、置 Loopback 位，
+        sink 就能 accept；标志位矩阵里其余四种组合（入向、不置 Loopback 位等）全不投递。
+        所以这里的目的地址取本族回环而不是 `sink.addr`：`sink.addr` 是配置里的
+        `127.0.0.1`，写成它的话 v6 报文会被内核丢掉。
+        """
+        loopback = self._loopback_for(parsed.is_v6)
+        try:
+            rewritten = reflect_packet(
+                raw,
+                src_addr=loopback,
+                src_port=parsed.src_port,
+                dst_addr=loopback,
+                dst_port=sink.port,
+            )
+        except PacketError as exc:
+            LOG.error("redirect_rewrite_failed", dst=f"{parsed.dst_addr}:{parsed.dst_port}", error=str(exc))
+            self.count("failed")
+            return
+
+        self.count("redirected")
+        try:
+            self._send_rewritten(packet, rewritten, outbound=True, ifidx=self._ifidx(packet))
+        except Exception as exc:  # noqa: BLE001 - 单包回注失败不能让抓包线程死掉
+            # 绝不静默：改道成功但回注失败 = 应用卡在 SYN_SENT
+            self.count("failed")
+            LOG.error(
+                "redirect_inject_failed",
+                src_port=parsed.src_port,
+                sink=str(sink),
+                error=str(exc),
+                hint="改道成功但回注失败：应用会卡在 SYN_SENT，且上游一条 CONNECT 都不会有",
+            )
+
+    def _decide_and_record(
+        self, packet: Any, parsed: ParsedPacket, sink: Endpoint
+    ) -> bool:
+        """对新连接做决策。返回 True = 应该改道到 sink。"""
+        pid = self.pid_table.lookup(
+            parsed.src_port, parsed.dst_addr, parsed.dst_port, is_v6=parsed.is_v6
+        )
+        if pid == 0:
+            self._unknown_pid += 1
+            LOG.debug(
+                "pid_unknown",
+                src_port=parsed.src_port,
+                dst=f"{parsed.dst_addr}:{parsed.dst_port}",
+                total=self._unknown_pid,
+            )
+        conn = ConnRequest(
+            proc=ProcInfo(pid=pid, name="", path=""),
+            proto=Proto.TCP,
+            src=Endpoint(parsed.src_addr, parsed.src_port, parsed.is_v6),
+            dst=Endpoint(parsed.dst_addr, parsed.dst_port, parsed.is_v6),
+            backend_id=parsed.src_port,
+        )
+
+        decision = self.decide(conn)
+
+        if decision.action is Action.BLOCK:
+            self.count_decision("blocked")
+            LOG.debug("blocked", pid=pid, dst=str(conn.dst), rule=decision.rule_id)
+            return False  # 不回注 = 丢弃
+
+        if self.dry_run:
+            LOG.info("dry_run_redirect", pid=pid, dst=str(conn.dst), sink=str(sink), dry_run=True)
+            self._send(packet)
+            return False
+
+        if decision.action is Action.DIRECT:
+            self.count_decision("direct")
+            self._send(packet)
+            return False
+
+        # ---- 先记账再发包 ----
+        self._record_redirect(
+            parsed.is_v6, parsed.src_port, conn.dst, parsed.src_addr, self._ifidx(packet)
+        )
+
+        LOG.debug(
+            "redirect",
+            pid=pid,
+            proc=conn.proc.name or "?",
+            original=str(conn.dst),
+            sink=str(sink),
+            rule=decision.rule_id,
+        )
+        return True
+
+    def _ifidx(self, packet: Any) -> int:
+        """取抓到的包所属的接口索引（反向注入必须挂回同一个接口）。"""
+        network = getattr(getattr(packet, "wd_addr", None), "Network", None)
+        try:
+            return int(getattr(network, "IfIdx", 0))
+        except (TypeError, ValueError):  # 测试替身没有 wd_addr / 值不是数字
+            return 0
+
+    @staticmethod
+    def _loopback_for(is_v6: bool) -> str:
+        """本族回环地址：正向改写的源/目的、反向路径的识别都用它。
+
+        只能是回环地址，报文才"整条在回环里"，内核才投递（见 `_redirect_to_sink`）。
+        按报文自己的地址族取，不看 sink 配置，sink 的配置地址是 `127.0.0.1`，
+        但 v6 的连接必须改道到 `::1`。
+        """
+        return "::1" if is_v6 else "127.0.0.1"
+
+    def _handle_for(self, packet: Any) -> Any:
+        """按报文地址族挑句柄。v4/v6 各开了一个句柄，回注要还给对应的那个。
+
+        `WinDivertSend` 本身不查过滤器，所以拿 v4 句柄送 v6 包"碰巧"也能通；
+        但那是实现细节，一旦变了就是静默丢包（应用卡在 SYN_SENT，没有任何报错）。
+        地址族从 IP 头首字节的高 4 位取，合成包、改写包、原始包都适用。
+        """
+        raw = getattr(packet, "raw", None)
+        is_v6 = False
+        if raw is not None:
+            try:
+                is_v6 = (bytes(raw)[0] >> 4) == 6
+            except (TypeError, IndexError, ValueError):  # 测试替身没有 raw
+                is_v6 = False
+        if is_v6 and self._handle6 is not None:
+            return self._handle6
+        return self._handle
+
+    def _send(self, packet: Any) -> None:
+        handle = self._handle_for(packet)
+        if handle is None:  # pragma: no cover
+            return
+        handle.send(packet)
+
+    def _send_rewritten(
+        self, packet: Any, raw: bytes, *, outbound: bool, ifidx: int | None = None
+    ) -> None:
+        """回注改写后的报文（必须构造新 Packet，不能原地改 `raw`）。
+
+        pydivert 3.x 的 `Packet.raw` 是 `memoryview`，内部 `__to_buffers()` 走
+        `self.raw.obj`。把 `bytes` 直接赋给 `packet.raw` 之后，`send()` 会抛
+        `AttributeError: 'bytes' object has no attribute 'obj'`，报文永远到不了 sink。
+        这里改为按公开构造方式建新包。
+
+        方向与接口索引不能沿用原包：
+        * 正向改道是出向注入（原包也是出向，但源地址已改成回环，必须显式置出向）；
+        * 反向应答是入向注入，而原包来自回环路径、自带的是回环接口索引（实测为 1），
+          拿它注入到网卡地址上会被内核丢掉，所以传入正向包记下的 `ifidx`。
+        """
+        handle = self._handle_for(packet)
+        if handle is None:  # pragma: no cover
+            return
+
+        import pydivert
+
+        direction = self._dir_outbound if outbound else self._dir_inbound
+        if direction is None:  # pragma: no cover - start() 里已缓存
+            direction = pydivert.Direction.OUTBOUND if outbound else pydivert.Direction.INBOUND
+
+        out = pydivert.Packet(raw, direction=direction)
+        # 用改写后的报文挑句柄（地址族与原始包一致，但这里的数据更权威）
+        handle = self._handle_for(out) or handle
+        addr = getattr(out, "wd_addr", None)
+        if addr is not None:
+            addr.Outbound = 1 if outbound else 0
+            # 回环流量要置 Loopback 位：内核据此把它当本机回环报文处理
+            addr.Loopback = 1 if outbound else 0
+            addr.Sniffed = 0
+            addr.Impostor = 0
+            # 没显式给就沿用原包的接口索引（老行为，够用）；生产路径两个方向都会显式传
+            idx = self._ifidx(packet) if ifidx is None else ifidx
+            if idx:
+                addr.Network.IfIdx = int(idx)
+        # 校验和交给 pydivert 重算兜底（wd_addr 上的 *Checksum 标志会影响 helper 的行为，
+        # 让它自己算最稳）；我们 pkt.py 的校验和另有单测保证正确性。
+        handle.send(out)
+
+    # ------------------------------------------------------------ 统计 -----
+    def stats(self) -> dict[str, Any]:
+        out = super().stats()
+        out["recv_errors"] = self._recv_errors
+        out["unknown_pid"] = self._unknown_pid
+        out["filter"] = self._filter
+        out["pidmap"] = self.pid_table.stats()
+        out["dry_run"] = self.dry_run
+        return out
+
+
+# --------------------------------------------------------- 工具函数 --------
+def probe_availability() -> tuple[bool, str]:
+    """探测 WinDivert 是否可用（`cli doctor` 用），不抛异常。"""
+    if not is_supported():
+        return False, "仅 Windows 支持"
+    try:
+        import pydivert
+    except ImportError:
+        return False, "缺 pydivert（pip install pydivert psutil）"
+    return True, f"pydivert {getattr(pydivert, '__version__', 'unknown')} 已安装；运行需要管理员权限"
+
+
+__all__ = [
+    "WinDivertBackend",
+    "probe_availability",
+]