zapret-kvn/docs/MASKING.md
loop-uh 64f4ee714e Xray owns VMess and Trojan: sidecar path, XHTTP, TLS and masking follow
Owner decision 2026-11-16: VLESS, VMess and Trojan run on the official Xray core;
sing-box stays the gasket (TUN, routing, DNS, protected sockets) and only keeps
Shadowsocks, SOCKS, HTTP and the rest. sing-box had no XHTTP transport for VMess and
Trojan and only approximated the other transports, while Xray runs any of its protocols
over any transport.

- protocol_core: VMess/Trojan in Xray's JSON shape go to Xray; a raw sing-box JSON
  outbound pasted by the user (type key) stays with sing-box.
- link_parser: xray_only for VMess/Trojan (allowInsecure without a pin is dropped like
  VLESS, Xray 26.x has none), TLS validation for all three, VMess alterId > 0 refused,
  vmess:// carries XHTTP mode and extra, WebSocket/HTTPUpgrade drop h2/h3 from alpn.
- masking: VMess/Trojan are Xray servers (shape, presets); sing-box fragment keeps
  AnyTLS, HTTP, ShadowTLS.
- config_builder: dead VMess/Trojan/transport conversion removed.
- tests flipped to Shadowsocks where they need a sing-box server; new
  tests/test_xray_owns_vmess_trojan.py; docs updated.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-16 09:44:27 -05:00

104 lines
7.6 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Masking («Маскировка»)
Owner request 2026-11-15, plan approved 2026-11-16. Off by default: with the master switch off the
runtime plans and the transition signatures are exactly what they were before.
## Who owns what (native cores, sing-box is the gasket)
| Section | Native core | What the app writes (to a runtime copy of the node) |
|---|---|---|
| WireGuard masking | Amnezia runtime (`runtime/amnezia`) | `jc`, `jmin`, `jmax`, `i1`..`i5` in the endpoint's `amnezia` object |
| Xray shaping (VLESS, VMess, Trojan) | Xray sidecar | `mux` on the outbound, `xmux` in XHTTP settings (inside `extra` when present), `finalmask.tcp` fragment |
| TLS fragment | sing-box (AnyTLS, HTTP, ShadowTLS; Trojan and VMess moved to Xray, which uses `finalmask`) | `tls.fragment`, `tls.record_fragment`, `tls.fragment_fallback_delay` |
| Packet tricks | sing-box front, socket to the VLESS server | route options `tls_spoof` / `kvn_desync` (see below) |
| Hysteria2 | official Hysteria | nothing: obfs is part of the link |
H1-H4/S1-S4 are never touched (they must equal the server). Junk and I1-I5 are sent by the
initiator only, so they work with a plain WireGuard server.
## Code
- `xray_fluent/masking/` (pure, no Qt): `model`, `codec` (JSON shared byte for byte with Android
`MaskingCodec`), `merge` (global + per-server override by `node.id`), `wireguard`/`xray`/`singbox`
rules and emitters (limits cite the pinned cores), `presets`, `choices` (what the controls show and
write), `tester` (freeze verdict, candidates, plan, ranking), `apply`.
- `xray_fluent/application/masking_runtime.py`: masked COPIES of the selected node and the pool nodes
for both sing-box planners, and of the Xray pool outbounds; the stored nodes are never edited.
- `AppSettings.masking` holds the codec document. The transition signature includes it only while
masking is on, so users who never enable it get no extra reconnect after an update.
- One `[masking] маскировка: …` log line at each sing-box start (proxy, TUN, transport switch).
- UI: Settings -> group «Маскировка» (presets per section, «Свои значения» = the whole set as JSON
with core validation); node list -> «Ещё» -> «Маскировка» for the selected servers.
## «Подобрать» (the tester)
- Decisions in `xray_fluent/masking/tester.py` (same as Android): candidates (baseline «Без
маскировки», the server's own set, fitting presets), the plan (2 transfers per candidate, jittered
pauses, one target), `judge` (control = the run itself) and the freeze verdict.
- `application/masking_runtime.py`: `begin_trial`/`end_trial`, the in-memory candidate; `settings_of`
(what a connect runs with) applies it, `stored_settings_of` (what the UI and writes use) never does.
While a trial runs the transition signature carries `masking_trial`, so every candidate really
rebuilds the session; without a trial the signature is unchanged.
- `application/masking_tune_service.py` `MaskingTuneRunner` (GUI thread, QTimer + worker only): per
candidate sets the trial, `_request_transition("masking tune")`, waits until the coordinator is idle
and connected (45 s), checks the selected node, runs the transfers (`TransferWorker`: the session's
HTTP inbound, or plain in TUN), then drops the trial and requests `masking tune end`. Counts
`controller.user_disconnects` so a VPN the user switched off is never switched back on.
«Оставить» = `controller.keep_masking_override`.
- `network/masking_transfer.py`: 256 KB (`Range`) of `SPEED_TEST_DEFAULT_URL`, browser User-Agent, read
timeout 12 s, cap 40 s, sampler thread every 0.5 s.
- UI: Settings -> «Маскировка» -> «Подобрать для текущего сервера» -> `ui/masking_tune_dialog.py`.
- Log: `[masking] маскировка: подбор, вариант «…»` at every trial connect.
## «Пакеты-обманки» (desync, VLESS over TCP)
The Xray sidecar dials every server through sing-box (`sockopt.dialerProxy` -> protect inbound ->
`direct`), so the server socket belongs to the sing-box front and the tricks are route options of
that route, one `route-options` rule per server (`masking/desync.py`, inserted just before the
protect route by `runtime_planner._ensure_hybrid_desync_routes`, matched by the server's name and
its known addresses):
| Method | Windows engine | Route option |
|---|---|---|
| «Обманка» (`fake`) | sing-box `tls_spoof` over the WinDivert driver (owner 2026-11-16) | `tls_spoof: <fake SNI>`, `tls_spoof_method: wrong-sequence` |
| «Беспорядок» (`disorder`), «Разрез» (`split`) | `common/kvndesync`, core patch `core-patches/kvn-desync.patch` (same engine as Android 0017) | `kvn_desync: "<method>:<split_at>"` |
| OOB | not on Windows (validation error) | — |
- The Xray emitter puts the plan on the masked outbound copy under `__kvn_desync`; the planner takes
it off before the config reaches Xray (a raw Xray config strips it and the log says so).
- The Windows decoy carries a wrong TCP sequence number, so the server drops it whatever the TTL:
`fakeTtl` stays in the shared format but is not used here (one «Обманка» preset instead of
Android's TTL 3 / TTL 5).
- Patch: `kvndesync/socket_windows.go` sets `IP_TTL` / `IPV6_UNICAST_HOPS` and waits until the
piece left the host by `SIO_TCP_INFO` `BytesOut` (50 ms cap); five upstream files gain the
`kvn_desync` route option. `build_singbox_front.py` applies it only onto the exact pinned blobs and
runs `go test ./common/kvndesync ./route/rule`.
- Lab (win10, 2026-11-16, through the VM's router): disorder at SNI ~310 ms handshake (Windows'
300 ms minimum RTO: the TTL 1 piece died at the first router and was resent with the normal TTL),
split 5 ms; `tls_spoof` capture (pktmon): a `vk.com` decoy ClientHello 304 bytes before the real
sequence goes out first, the handshake succeeds.
- Service slots: a slot's own Xray helper is masked like the main path, but without packet tricks
(the plan is dropped, see `docs/SERVICE_SLOTS.md`).
### Zapret and WinDivert while the tricks run (owner 2026-11-16)
- One desync per flow: for a server with its own tricks, `ServerBypass` makes the winws2 rule
`pass` («не трогать») and bypass is not required for it; winws2 is never started just for that.
Log: `[zapret] у сервера свои пакеты-обманки маскировки: …`.
- WinDivert unloaded and available: sing-box installs the driver as service `WinDivert` from its own
copy and marks it for deletion, but the driver stays loaded after the last handle closes. After a
sing-box process whose config opened WinDivert exited (disconnect, reconnect with spoofing off,
app exit, crash before the next start), `SingBoxManager._release_windivert_steps` runs
`engines/windivert_release.py`: stop the `WinDivert` service unless a known WinDivert user runs
(winws/winws2 of any folder, GoodbyeDPI). Log: `[masking] WinDivert выгружен, драйвер свободен` or
why it was kept.
- The bundled Zapret's `Monkey64.sys` is byte-identical to sing-box's `WinDivert64.sys` 2.2.2 and is
installed as service `Monkey` on the same device `\\.\WinDivert`: either program uses the driver
the other loaded. win10 check 2026-11-16: spoof loads `WinDivert`; winws2 starts on it; release is
refused while winws2 runs; without it the service is gone; winws2 then loads `Monkey` itself and
sing-box spoof works on that driver too.
Note: the Xray sidecar dials through `sockopt.dialerProxy` (the local protect relay), so finalmask
fragment pauses reach sing-box's direct connection, but segment boundaries are not guaranteed;
fragment stays an experiment behind the tester.