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>
104 lines
7.6 KiB
Markdown
104 lines
7.6 KiB
Markdown
# 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.
|