procproxy 0.1.0__py3-none-any.whl

proxycore/checkroute.py

@@ -0,0 +1,247 @@
+"""核对某进程的连接到底走了哪条路。
+
+两类用法：
+
+1. 离线核对（不需要管理员），用会话日志 + 配置复算：
+   ```
+   python -m proxycore check-route --target-pid curl.exe --expect proxied \\
+       --sessions %TEMP%\\sessions.jsonl --config samples/profiles/dev.yaml
+   ```
+   它回答的是"按当前规则，curl.exe 连 1.1.1.1:443 应该被代理吗"，
+   以及"日志里 curl.exe 的会话是否真的走了上游"。
+
+2. 在线核对（需要管理员），查本机 TCP 表，看目标进程的连接是不是连到了 sink：
+   ```
+   python -m proxycore check-route --pid-of curl.exe --expect proxied --probe
+   ```
+
+退出码 0 = 符合预期；1 = 不符合；2 = 参数/环境问题。
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import socket
+import sys
+from collections import Counter
+from pathlib import Path
+
+from proxycore.backend.windivert.pidmap import PortPidTable, is_supported
+from proxycore.config import Config, ConfigError
+from proxycore.proc import get_proc_info, iter_pids
+from proxycore.rules import GuardSet, decide
+from proxycore.types import Action, ConnRequest, Endpoint, ProcInfo, Proto
+
+# 合成 PID：仅用于"进程没在跑时只算规则"，见 replay_rule 的说明
+_SYNTHETIC_PID = 999_999
+
+
+def load_sessions(path: Path) -> list[dict]:
+    """读会话日志里的 `session_end` 行。"""
+    if not path.exists():
+        return []
+    out: list[dict] = []
+    for line in path.read_text(encoding="utf-8", errors="replace").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            payload = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(payload, dict) and payload.get("event") == "session_end":
+            out.append(payload)
+    return out
+
+
+def evaluate_sessions(sessions: list[dict], target: str, *, dst: str = "", dport: int = 0) -> str:
+    """返回 `proxied` / `direct` / `failed` / `none`。"""
+    matches = [
+        s
+        for s in sessions
+        if target.lower() in str(s.get("proc", "")).lower()
+        and (not dport or str(dport) in str(s.get("dst", "")))
+        and (not dst or dst in str(s.get("dst", "")))
+    ]
+    if not matches:
+        return "none"
+    last = matches[-1]
+    if last.get("upstream"):
+        return "proxied"
+    if str(last.get("state")) == "failed":
+        return "failed"
+    return "direct"
+
+
+def resolve_target_pid(pattern: str) -> int:
+    """按进程名（或路径片段）查 PID；先精确后包含，找不到返回 0。"""
+    pattern = pattern.lower()
+    stem = pattern[:-4] if pattern.endswith(".exe") else pattern
+    partial = 0
+    for pid in iter_pids():
+        info = get_proc_info(pid)
+        name = info.name.lower()
+        if not name:
+            continue
+        if name in (pattern, stem):
+            return pid
+        if partial == 0 and (pattern in name or name == f"{stem}.exe"):
+            partial = pid
+    return partial
+
+
+def replay_rule(config: Config, proc_name: str, dst: str, dport: int, proto: str) -> tuple[Action, str]:
+    """按当前规则复算"这条连接会被怎么处理"。
+
+    返回 `(动作, 说明)`。
+
+    关于"进程没在跑"这个坑（真机踩过）：
+      规则引擎的第一道分支是"PID 未知 → 按 `service.on_unknown_pid` 处置"，它在规则之前，
+      所以拿 pid=0 去复算，得到的永远是那个策略（常见 `direct`），
+      看起来就像"规则没生效"。这会让"验证配置"这件事直接失效。
+      因此：进程没找到时，用一个合成 PID 只算规则本身，并把这一点打印出来。
+      真机上 PID 查不到时实际走哪条路，由 `on_unknown_pid` 决定（下面会一并列出）。
+    """
+    pid = resolve_target_pid(proc_name)
+    note = ""
+    if pid:
+        found = get_proc_info(pid)
+        info = ProcInfo(pid=pid, name=found.name or proc_name, path=found.path)
+    else:
+        # 合成 PID：只为了跳过"未知 PID"分支，让规则本身被真正评估
+        info = ProcInfo(pid=_SYNTHETIC_PID, name=proc_name, path="")
+        note = (
+            f"进程 {proc_name!r} 当前未运行：这里用合成 PID={_SYNTHETIC_PID} 只做规则复算；"
+            f"真机上若 PID 查不到，会按 service.on_unknown_pid={config.service.on_unknown_pid!r} 处置"
+        )
+    conn = ConnRequest(
+        proc=info,
+        proto=Proto.UDP if proto == "udp" else Proto.TCP,
+        src=Endpoint("127.0.0.1", 40000),
+        dst=Endpoint(dst, dport, is_v6=":" in dst),
+    )
+    guards = GuardSet(
+        self_pids=set(),
+        upstream_endpoints=config.profile.upstream_endpoints(),
+        on_unknown_pid=config.service.on_unknown_pid,
+    )
+    return decide(conn, config.profile, None, guards).action, note
+
+
+def live_connections(pid: int | None, sink_port: int) -> tuple[list[str], str]:
+    """查本机 TCP 表；返回 `(命中行, 说明)`。"""
+    if not is_supported():
+        return [], "在线核对仅 Windows 支持"
+    try:
+        table = PortPidTable(ttl_s=0.0)
+        rows = table.all_rows()
+    except OSError as exc:
+        return [], f"读取 TCP 表失败：{exc}"
+    if not rows:
+        return [], "TCP 表为空或权限不足（需要管理员）"
+
+    hits: list[str] = []
+    for row in rows:
+        if (pid and row.pid != pid) or row.pid == 0:
+            continue
+        target = f"{row.remote_addr}:{row.remote_port}"
+        marker = "SINK" if row.remote_port == sink_port else "remote"
+        hits.append(f"pid={row.pid} local={row.local_addr}:{row.local_port} -> {target} [{marker}]")
+    return hits, f"共 {len(rows)} 行，命中 {len(hits)} 行"
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="procproxy check-route", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--config", default="samples/profiles/dev.yaml")
+    ap.add_argument("--target-pid", default="", help="进程名/通配（如 curl.exe）")
+    ap.add_argument("--pid-of", default="", help="同 --target-pid，按名称查 PID")
+    ap.add_argument("--expect", choices=["proxied", "direct", "blocked"], required=True)
+    ap.add_argument("--proc", default="", help="规则复算用的进程名（默认取 --target-pid）")
+    ap.add_argument("--dst", default="1.1.1.1")
+    ap.add_argument("--port", type=int, default=443)
+    ap.add_argument("--proto", choices=["tcp", "udp"], default="tcp")
+    ap.add_argument("--sessions", default="")
+    ap.add_argument("--probe", action="store_true")
+    ap.add_argument(
+        "--live-required",
+        action="store_true",
+        help="要求在线核对（TCP 表出现连到 sink 的连接）也通过；默认只报告不判定",
+    )
+    args = ap.parse_args(argv)
+
+    target = args.target_pid or args.pid_of
+    if not target:
+        print("需要 --target-pid 或 --pid-of", file=sys.stderr)
+        return 2
+    proc_name = args.proc or target
+
+    try:
+        config = Config.load(args.config)
+    except ConfigError as exc:
+        print(f"配置无效：{exc}", file=sys.stderr)
+        return 2
+
+    print(f"# check_route  target={target} expect={args.expect} config={args.config}")
+    print(f"# 规则复算：{proc_name} -> {args.dst}:{args.port}/{args.proto}")
+
+    actual_action, replay_note = replay_rule(config, proc_name, args.dst, args.port, args.proto)
+    expected_action = {"proxied": Action.PROXY, "direct": Action.DIRECT, "blocked": Action.BLOCK}[args.expect]
+    rule_ok = actual_action is expected_action
+    print(
+        f"规则复算结果: {actual_action.value}  ->  {'OK' if rule_ok else 'MISMATCH'}（期望 {expected_action.value}）"
+    )
+    if replay_note:
+        print(f"  [!] {replay_note}")
+
+    session_verdict = "none"
+    if args.sessions:
+        sessions = load_sessions(Path(args.sessions))
+        session_verdict = evaluate_sessions(sessions, target, dst=args.dst, dport=args.port)
+        counts = Counter(str(s.get("proc", "")) for s in sessions)
+        print(f"会话日志: {len(sessions)} 条；进程分布 top5 = {counts.most_common(5)}")
+        print(f"目标进程最近会话: {session_verdict}")
+
+    pid = resolve_target_pid(target)
+    print(f"PID: {pid or '(未找到)'}")
+    live_ok = True
+    if args.probe or is_supported():
+        sink = config.service.sink
+        hits, note = live_connections(pid or None, sink.port)
+        print(f"在线 TCP 表: {note}")
+        for line in hits[:20]:
+            print(f"  {line}")
+        if pid and hits:
+            proxied = any("SINK" in line for line in hits)
+            live_ok = proxied == (args.expect == "proxied")
+            print(f"在线核对: {'OK' if live_ok else 'MISMATCH'}（期望 {args.expect}）")
+            if not live_ok and not args.live_required:
+                print("  （未使用 --live-required，故不据此判失败；ProcProxy 可能没在跑）")
+                live_ok = True
+
+    if args.probe:
+        probe_sink(config)
+
+    if not rule_ok:
+        return 1
+    if args.sessions and args.expect == "proxied" and session_verdict not in {"none", "proxied"}:
+        return 1
+    return 0 if live_ok else 1
+
+
+def probe_sink(config: Config) -> None:
+    sink = config.service.sink
+    try:
+        with socket.create_connection((sink.host, sink.port), timeout=1.0):
+            print(f"sink 探测: {sink.host}:{sink.port} 正在监听")
+    except OSError as exc:
+        print(f"sink 探测: {sink.host}:{sink.port} 不可达（{exc}）→ ProcProxy 可能没在跑")
+    for alias, upstream in config.profile.upstreams.items():
+        try:
+            with socket.create_connection((upstream.host, upstream.port), timeout=1.0):
+                print(f"上游探测: {alias} ({upstream.host}:{upstream.port}) 可达")
+        except OSError as exc:
+            print(f"上游探测: {alias} ({upstream.host}:{upstream.port}) 不可达（{exc}）")
+
+if __name__ == "__main__":  # pragma: no cover - 也支持以模块方式直接运行
+    raise SystemExit(main())