procproxy 0.1.0__py3-none-any.whl

proxycore/dns/modes.py

@@ -0,0 +1,451 @@
+"""DNS 三模式（`profile.dns_mode`）：`local` / `remote` / `bypass`。
+
+* `remote`（默认）：不本地解析，把域名字符串交给上游（SOCKS5 ATYP=3 / SOCKS4a /
+  CONNECT 传域名）。没有本地 DNS 泄漏。
+* `local`：本地解析成 IP 再交给代理。本地 DNS 查询可能直连出去，是泄漏点。
+* `dns_local_transport=proxy` 尚未实现（配置校验会拒绝），避免出现
+  "以为 DNS 走代理、实际直连"的静默泄漏。
+* `bypass` + `dns_bypass`：列表内域名走 local，其余走 remote。
+
+红线：
+* `local` 模式下本地 DNS 服务器必须进守卫 G3 白名单，否则 DNS 查询本身会被代理并成环；
+* `local` + `dns_local_transport=proxy` 时拿到的是解析结果而非域名，`dst_name` 规则不可用；
+* `remote` 模式禁止在本地做 `getaddrinfo`。
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import secrets
+import socket
+import time
+from dataclasses import dataclass
+from typing import Any
+
+from ..config import Profile
+from ..log import EventLogger, get_logger
+from .cache import DnsCache
+
+LOG = EventLogger(get_logger("proxycore.dns"))
+
+MODE_LOCAL = "local"
+MODE_REMOTE = "remote"
+MODE_BYPASS = "bypass"
+VALID_MODES = {MODE_LOCAL, MODE_REMOTE, MODE_BYPASS}
+
+TRANSPORT_DIRECT = "direct"
+TRANSPORT_PROXY = "proxy"
+
+
+def normalize_mode(value: str) -> str:
+    """非法/未知模式落到 `remote`（最安全的一种：本地不查 DNS）。"""
+    return value if value in VALID_MODES else MODE_REMOTE
+
+
+def normalize_transport(value: str) -> str:
+    return value if value in {TRANSPORT_DIRECT, TRANSPORT_PROXY} else TRANSPORT_DIRECT
+
+
+@dataclass(slots=True)
+class ResolutionPlan:
+    """一次连接的目标解析计划。"""
+
+    mode: str  # 实际生效的模式（bypass 会在这里落到 local 或 remote）
+    hostname: str | None  # 交给上游的域名（None = 只能用 IP）
+    addr: str  # 上游最终要连的地址（domain 模式下就是域名）
+    used_local_dns: bool = False
+    reason: str = ""
+
+
+class DnsPolicy:
+    """按 `dns_mode` 决定"这条连接要不要在本地解析"。"""
+
+    def __init__(
+        self,
+        *,
+        mode: str = MODE_REMOTE,
+        bypass: list[str] | None = None,
+        local_transport: str = TRANSPORT_DIRECT,
+        local_server: str = "",
+        cache: DnsCache | None = None,
+        timeout: float = 5.0,
+    ) -> None:
+        self.mode = normalize_mode(mode)
+        self.bypass = list(bypass or [])
+        self.local_transport = normalize_transport(local_transport)
+        self.local_server = local_server
+        self.cache = cache or DnsCache()
+        self.timeout = timeout
+
+    def configure(self, profile: Profile) -> None:
+        """按 `Profile` 原地更新（热重载用）。
+
+        原地更新而不是新建对象：`Sink` 持有这个 policy 并可能在 worker 线程上
+        随时读它。换对象就要同步改 `Sink.dns`，漏掉一处就是"热重载后 DNS 配置
+        静默不生效"。缓存也刻意保留。
+        """
+        self.mode = normalize_mode(str(getattr(profile, "dns_mode", MODE_REMOTE)))
+        self.bypass = [str(b) for b in (getattr(profile, "dns_bypass", None) or [])]
+        self.local_transport = normalize_transport(
+            str(getattr(profile, "dns_local_transport", TRANSPORT_DIRECT))
+        )
+        self.local_server = str(getattr(profile, "dns_local_server", "") or "")
+
+    # ------------------------------------------------------------ 判定 -----
+    def effective_mode(self, hostname: str | None) -> tuple[str, str]:
+        """返回 `(生效模式, reason)`。"""
+        if self.mode != MODE_BYPASS:
+            return self.mode, f"dns_mode:{self.mode}"
+        if hostname and self.matches_bypass(hostname):
+            return MODE_LOCAL, "dns-bypass"
+        return MODE_REMOTE, "dns-bypass-default-remote"
+
+    def matches_bypass(self, hostname: str) -> bool:
+        from ..rules import wildcard_match
+
+        host = hostname.lower()
+        return any(wildcard_match(pattern.lower(), host) for pattern in self.bypass)
+
+    # ------------------------------------------------- 运行时接线（Runtime）--
+    def plan_for_connection(self, addr: str) -> ResolutionPlan:
+        """sink 在 dial 之前调用：这个目标地址该怎么交给上游。
+
+        `addr` 可能是 IP（应用自己解析过 → 路线 A/B 的常态），也可能是域名
+        （测试模式直接把域名给了 sink，或将来有别的名字来源）。区别在于：
+
+        * 是域名 → 直接按域名走 `plan()`（`local` 模式会在本地解析掉）；
+        * 是 IP → 只能查 DNS 缓存找名字，且只用可信项（见 `trusted_name_for`）。
+
+        没有可用名字时返回"按 IP 上代理"。应用自己已经解析了，
+        这是应用行为决定的，无法改变，不是缺陷。
+        """
+        if not _is_ip_literal(addr):
+            return self.plan(addr, addr)
+        return self.plan(addr, self.trusted_name_for(addr))
+
+    def trusted_name_for(self, addr: str) -> str | None:
+        """取该 IP 的确定域名；推断出来的映射不返回（`None`）。
+
+        红线：DNS 嗅探得到的
+        映射只是近似，TTL 内有效且会因 CDN 误判。拿它去 dial 等于"猜一个域名
+        然后让上游连过去"，猜错就是连到别人的站点，所以 dial 只用可信项，
+        推断项只喂给 `dst_name` 规则的近似匹配（并打 `name-inferred` 标记）。
+        """
+        entry = self.cache.entry(addr)
+        if entry is None or entry.inferred:
+            return None
+        return entry.name
+
+    def inferred_names(self) -> set[str]:
+        """未过期的推断域名（`GuardSet.inferred_names` 的来源）。"""
+        return self.cache.inferred_names()
+
+    def revision(self) -> int:
+        """缓存内容版本号，供调用方判断要不要刷新 `inferred_names`。"""
+        return self.cache.revision
+
+    # ------------------------------------------------------------ 计划 -----
+    def plan(self, addr: str, hostname: str | None) -> ResolutionPlan:
+        """决定交给上游的地址形态。
+
+        `hostname` 为 None 表示"应用自己已经解析过了"（我们只看到 IP，只能按 IP 走）。
+        """
+        mode, reason = self.effective_mode(hostname)
+
+        if hostname is None:
+            return ResolutionPlan(
+                mode=mode, hostname=None, addr=addr, used_local_dns=False, reason=f"{reason};app-resolved"
+            )
+
+        if mode == MODE_REMOTE:
+            # 远端解析：域名原样透传（禁止本地 getaddrinfo）
+            return ResolutionPlan(mode=mode, hostname=hostname, addr=hostname, reason=reason)
+
+        # local / bypass：本地解析成 IP
+        resolved = self.resolve_local(hostname)
+        if resolved is None:
+            # 解析失败 → 退化为"按原地址 + 域名"交给上游（比直接失败更安全，不泄漏也不断流）
+            LOG.warn("dns_local_resolve_failed", hostname=hostname, fallback="remote")
+            return ResolutionPlan(
+                mode=MODE_REMOTE, hostname=hostname, addr=hostname, reason=f"{reason};local-failed->remote"
+            )
+        return ResolutionPlan(
+            mode=MODE_LOCAL, hostname=None, addr=resolved, used_local_dns=True, reason=reason
+        )
+
+    # ------------------------------------------------------------ 解析 -----
+    def resolve_local(self, hostname: str) -> str | None:
+        """本地解析；`local_server` 非空时向指定 DNS 服务器查询，否则用系统解析器。
+
+        配了 `local_server` 却查询失败时**不回退系统解析器**：那会绕开用户指定的
+        服务器（可能正是为了不泄漏），把 DNS 查询发到本机默认 DNS。失败返回 None，
+        由 `plan()` 退化为"域名交给上游远端解析"（不泄漏，只是本模式没生效）。
+        """
+        try:
+            ipaddress.ip_address(hostname)
+            return hostname  # 已经是 IP 字面量
+        except ValueError:
+            pass
+
+        if self.local_server:
+            resolved = query_a_record(hostname, self.local_server, timeout=self.timeout)
+            if resolved:
+                self.cache.put(resolved, hostname, inferred=False, source="local-dns")
+            return resolved
+
+        try:
+            infos = socket.getaddrinfo(hostname, None, socket.AF_INET, socket.SOCK_STREAM)
+        except OSError as exc:
+            LOG.warn("getaddrinfo_failed", hostname=hostname, error=str(exc))
+            return None
+        if not infos:
+            return None
+        addr = str(infos[0][4][0])
+        self.cache.put(addr, hostname, inferred=False, source="getaddrinfo")
+        return addr
+
+    # --------------------------------------------------- 守卫 G3 白名单 ----
+    def guard_endpoints(self) -> set[tuple[str, int]]:
+        """`local` 模式的 DNS 服务器必须进白名单（否则查询会被代理并成环）。"""
+        if not self.local_server:
+            return set()
+        return {(self.local_server, 53)}
+
+    # ------------------------------------------------------------ 嗅探 -----
+    def note_answer(
+        self, addr: str, name: str, *, ttl_s: float | None = None, inferred: bool = True
+    ) -> None:
+        """记录一条 IP→域名映射。
+
+        `inferred=True`（默认）= DNS 嗅探到的，只是近似：TTL 内有效、CDN 会误判，
+        所以它只喂 `dst_name` 规则的近似匹配，不参与 dial、不参与 BLOCK
+        。
+
+        `inferred=False` = 权威来源（应用真的连的就是这个域名），可以拿去 dial。
+    但抓包式后端给不出这种映射：内核不向用户态提供主机名，过滤器里只有地址，
+        里没有任何名字类字段，`ALE_AUTH_CONNECT` 的层数据结构 `FWPS_CONNECT_REQUEST0`
+        只有 `localAddressAndPort` / `remoteAddressAndPort`（2026-10-02 对着本机
+        WDK 10.0.26100.0 的 `fwpsk.h` 逐项核过）。所以 `inferred=False` 目前
+        没有任何 in-tree 生产者，只有单测和将来的手工/API 喂入口在用。
+        """
+        self.cache.put(
+            addr,
+            name,
+            ttl_s=ttl_s,
+            inferred=inferred,
+            source="dns-sniff" if inferred else "authoritative",
+        )
+        LOG.debug("dns_answer_cached", addr=addr, name=name, inferred=inferred)
+
+    def name_for(self, addr: str) -> str | None:
+        return self.cache.get(addr)
+
+    def describe(self) -> dict[str, Any]:
+        return {
+            "mode": self.mode,
+            "bypass": list(self.bypass),
+            "local_transport": self.local_transport,
+            "local_server": self.local_server or "(system)",
+            "guard_endpoints": sorted(f"{h}:{p}" for h, p in self.guard_endpoints()),
+            "cache": self.cache.stats(),
+        }
+
+
+def _is_ip_literal(text: str) -> bool:
+    try:
+        ipaddress.ip_address(text)
+    except ValueError:
+        return False
+    return True
+
+
+def build_dns_policy(profile: Profile, *, cache: DnsCache | None = None) -> DnsPolicy:
+    """从 `Profile` 装配 `DnsPolicy`（`Runtime` 与 `api.make_runtime` 共用）。
+
+    `cache` 不传 = 新建一份。热重载时必须把旧缓存传进来复用
+    （见 `Runtime.apply_profile`）：否则每次改配置都会把 DNS 记录扔光，
+    `dst_name` 规则会在重载后集体失效一段时间，而这与"改配置"毫无关系。
+    """
+    policy = DnsPolicy(cache=cache)
+    policy.configure(profile)
+    return policy
+
+
+# ------------------------------------------------------ 最小 DNS 客户端 ----
+def build_query(name: str, qtype: int = 1, *, txid: int | None = None) -> bytes:
+    """构造一个 DNS 查询报文（A 记录）。
+
+    `txid` 默认随机：固定事务 ID 会让响应更容易被伪造。`query_a_record()`
+    会记住本次使用的 ID 并严格校验回包。
+    """
+    import struct
+
+    if txid is None:
+        txid = secrets.randbits(16)
+    header = struct.pack("!HHHHHH", txid & 0xFFFF, 0x0100, 1, 0, 0, 0)
+    qname = b"".join(bytes([len(part)]) + part.encode("idna") for part in name.split(".")) + b"\x00"
+    return header + qname + struct.pack("!HH", qtype, 1)
+
+
+def _read_name(packet: bytes, pos: int) -> tuple[str, int]:
+    """读取域名，返回 `(名字, 名字字段结束之后的偏移)`。
+
+    关键：压缩指针（`0xC0 xx`）表示"名字的其余部分在别处"，名字字段本身只占 2 字节。
+    因此跟随指针之前必须先把"字段结束位置"记下来，否则后面的 rtype/ttl/rdata
+    会读到被指向的位置（踩过：ttl/rdata 全错位）。
+    """
+    labels: list[str] = []
+    after_field = -1  # 名字字段在原始字节流里的结束偏移
+    visited: set[int] = set()
+    while 0 <= pos < len(packet):
+        length = packet[pos]
+        if length == 0:
+            pos += 1
+            if after_field < 0:
+                after_field = pos
+            break
+        if length & 0xC0 == 0xC0:
+            if pos + 1 >= len(packet):
+                break
+            pointer = ((length & 0x3F) << 8) | packet[pos + 1]
+            if after_field < 0:
+                after_field = pos + 2
+            if pointer in visited:
+                break  # 真环，跳出
+            visited.add(pointer)
+            pos = pointer
+            continue
+        if pos + 1 + length > len(packet):
+            break
+        labels.append(packet[pos + 1 : pos + 1 + length].decode("latin1"))
+        pos += 1 + length
+    if after_field < 0:  # 解析中途失败
+        after_field = pos
+    return ".".join(labels), after_field
+
+
+def parse_answers(packet: bytes) -> list[tuple[str, str, int]]:
+    """解析响应里的 A/AAAA 记录，返回 `[(name, ip, ttl)]`。"""
+    import struct
+
+    if len(packet) < 12:
+        return []
+    _id, _flags, qdcount, ancount, _ns, _ar = struct.unpack_from("!HHHHHH", packet, 0)
+    offset = 12
+
+    for _ in range(qdcount):
+        _qname, offset = _read_name(packet, offset)
+        offset += 4  # qtype + qclass
+
+    answers: list[tuple[str, str, int]] = []
+    for _ in range(ancount):
+        if offset >= len(packet):
+            break
+        name, offset = _read_name(packet, offset)
+        if offset + 10 > len(packet):
+            break
+        rtype, _rclass, ttl, rdlength = struct.unpack_from("!HHIH", packet, offset)
+        offset += 10
+        rdata = packet[offset : offset + rdlength]
+        offset += rdlength
+        if rtype == 1 and rdlength == 4:
+            answers.append((name, socket.inet_ntoa(rdata), int(ttl)))
+        elif rtype == 28 and rdlength == 16:
+            answers.append((name, socket.inet_ntop(socket.AF_INET6, rdata), int(ttl)))
+    return answers
+
+
+def _is_query_response(packet: bytes, txid: int) -> bool:
+    """回包是否属于本次查询：长度、事务 ID、QR 位三项都要对。"""
+    import struct
+
+    if len(packet) < 12:
+        return False
+    resp_id, flags = struct.unpack_from("!HH", packet, 0)
+    return resp_id == txid and bool(flags & 0x8000)
+
+
+def query_a_record(name: str, server: str, *, timeout: float = 5.0, port: int = 53) -> str | None:
+    """向指定 DNS 服务器发一次 A 查询（UDP）。失败返回 None。
+
+    安全约束：
+    * 每次查询随机事务 ID；
+    * socket 先 `connect()` 到服务器，内核只交付该源地址/端口的报文；
+    * 回包必须匹配事务 ID 与 QR 位，否则丢弃并继续等，直到总超时。
+    """
+    if not server:
+        return None
+    txid = secrets.randbits(16)
+    deadline = time.monotonic() + max(0.05, timeout)
+    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    try:
+        sock.connect((server, port))
+        sock.send(build_query(name, txid=txid))
+        packet = b""
+        while True:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise TimeoutError("DNS 查询超时")
+            sock.settimeout(remaining)
+            candidate = sock.recv(4096)
+            if _is_query_response(candidate, txid):
+                packet = candidate
+                break
+    except OSError as exc:
+        LOG.warn("dns_query_failed", server=server, name=name, error=str(exc))
+        return None
+    finally:
+        sock.close()
+    answers = parse_answers(packet)
+    for record_name, addr, _ttl in answers:
+        if record_name.lower().rstrip(".") == name.lower().rstrip("."):
+            return addr
+    return answers[0][1] if answers else None
+
+
+def sniff_queries(payload: bytes) -> list[str]:
+    """从 DNS 查询报文中提取被查询的域名（用于建立"即将解析"的映射）。"""
+    import struct
+
+    if len(payload) < 12:
+        return []
+    _id, flags, qdcount, _an, _ns, _ar = struct.unpack_from("!HHHHHH", payload, 0)
+    if flags & 0x8000:  # 是响应而不是查询
+        return []
+    offset = 12
+    names: list[str] = []
+    for _ in range(qdcount):
+        labels: list[str] = []
+        while offset < len(payload):
+            length = payload[offset]
+            if length == 0:
+                offset += 1
+                break
+            if length & 0xC0:
+                offset += 2
+                break
+            labels.append(payload[offset + 1 : offset + 1 + length].decode("latin1"))
+            offset += 1 + length
+        if labels:
+            names.append(".".join(labels))
+        offset += 4
+    return names
+
+
+__all__ = [
+    "MODE_BYPASS",
+    "MODE_LOCAL",
+    "MODE_REMOTE",
+    "TRANSPORT_DIRECT",
+    "TRANSPORT_PROXY",
+    "VALID_MODES",
+    "DnsPolicy",
+    "ResolutionPlan",
+    "build_dns_policy",
+    "build_query",
+    "normalize_mode",
+    "normalize_transport",
+    "parse_answers",
+    "query_a_record",
+    "sniff_queries",
+]