README

shadowsocks-reborn for Windows

English | Русский | 简体中文 | 中文使用说明

shadowsocks-reborn is a Windows-focused continuation of the classic Shadowsocks for Windows v4 client. Current builds target .NET 10, WinUI 3 / Windows App SDK, x64, and Windows 10 build 19041 or newer.

This is an independent fork, not the upstream shadowsocks/shadowsocks-windows repository.

Current release: 2.2.31

Release 2.2.31 includes working Administrator-mode transparent DNS interception/routing for the System, Direct, Proxy, CustomDoh and DnsCrypt policies, DNSCrypt/DoH management with ODoH disabled, hardened automatic self-update, duplicate-autostart protection, and the current WinUI 3 shell. It also tightens CI/release gates around .NET servicing, NuGet vulnerability auditing, Windows 10 build 19041 compatibility and published EXE version metadata.

See Changelog for the full release history.

Highlights

• Native WinUI 3 desktop interface; WinForms and WPF are no longer part of the product UI.
• Unpackaged, self-contained, win-x64, single-file distribution.
• Release layout contains exactly Shadowsocks.exe.
• File-backed per-user configuration under %LOCALAPPDATA%\Shadowsocks; the product directory is not used as mutable storage.
• Settings, caches, PAC data, logs and startup copy under %LOCALAPPDATA%\Shadowsocks in normal mode.
• Rufus-style Clean Mode (...p.exe) redirects all writable application state to a disposable %TEMP%\Shadowsocks\Clean\... session.
• Managed HTTP/1.1 proxy and HTTPS CONNECT; Privoxy/sysproxy are retired.
• Per-application Proxy, Direct and Block routing.
• Transparent TCP/UDP capture in Admin Mode through WinDivert.
• Automatic Game Mode that suspends Admin capture while configured applications are running.
• Game discovery suggestions for Steam, Epic Games, GOG and Xbox libraries; manual rules remain available.
• SIP003 plugin manager with built-in xray-plugin, v2ray-plugin and qtun choices plus manual ZIP/TAR.GZ import; installed packages live under the active storage root.
• UDP relay, QR import/export, hotkeys and a single embedded CSV localization catalog.

Traffic modes

Only two modes are selectable:

• User Mode — no elevation and no NetworkService extraction. Routing applies to traffic that reaches the local/system proxy.
• Admin Mode — requests UAC, materializes the embedded Shadowsocks.NetworkService.exe under the active storage root, validates it, launches it elevated, and enables transparent TCP/UDP capture through WinDivert.

Game Mode is an automatic compatibility state, not a third traffic mode. When Admin Mode is selected and a configured game/application starts, WinDivert capture is suspended. Admin capture is restored automatically after the application exits.

The Traffic page exposes configured/runtime mode, NetworkService state, WinDivert state, TCP/UDP capture state and redirect ports.

Requirements

• Windows 10 2004 / build 19041 or newer, or Windows 11;
• x64 Windows;
• .NET 10 SDK 10.0.303 or newer when building from source (release builds require the .NET 10.0.11 security baseline).

The published product is self-contained and does not require a separately installed .NET runtime.

Solution layout

• Shadowsocks.Core — protocol, encryption, configuration model, PAC/GeoSite logic, routing models, localization and storage abstractions.
• Shadowsocks.Windows — file-storage bootstrap, WinINet/system proxy, startup, UAC/Admin capture, WinDivert runtime, hotkeys and other Windows integration.
• Shadowsocks.Windows.WinUI — WinUI-specific Windows shell/tray integration.
• Shadowsocks.WinUI — WinUI 3 application shell and product publish project (Shadowsocks.exe).
• Shadowsocks.NetworkService — isolated elevated WinDivert helper embedded into release builds.
• Shadowsocks.UnitTests — Core/Windows tests without presentation dependencies.

See ARCHITECTURE.md for project boundaries and runtime flow.

Build

Use .NET SDK 10.0.303 or newer on Windows:

dotnet restore .\shadowsocks-reborn.sln -p:Platform=x64 -r win-x64
dotnet build .\shadowsocks-reborn.sln -c Release -p:Platform=x64 -m:1 --no-restore
dotnet test .\Shadowsocks.UnitTests\Shadowsocks.UnitTests.csproj -c Release -p:Platform=x64 --no-build

Publish the product:

dotnet restore .\Shadowsocks.WinUI\Shadowsocks.WinUI.csproj -p:Platform=x64 -p:PublishProfile=FolderProfile -r win-x64
dotnet publish .\Shadowsocks.WinUI\Shadowsocks.WinUI.csproj -c Release -p:Platform=x64 -p:PublishProfile=FolderProfile -r win-x64 --self-contained true --no-restore

Or build the release ZIP and SHA-256 file:

.\packaging\Build-Release.ps1 -Version 2.2.31

The canonical GitHub Release asset is Shadowsocks-win-x64.zip, with Shadowsocks-win-x64.zip.sha256 published beside it.

The final publish directory and release ZIP must contain exactly:

Shadowsocks.exe

DLLs, PDBs, runtime JSON files, icons and Shadowsocks.NetworkService.exe sidecars are rejected by release validation.

Storage and startup

Normal mode stores all persistent application-owned state under:

%LOCALAPPDATA%\Shadowsocks

The configuration backend is %LOCALAPPDATA%\Shadowsocks\settings.json with an atomic settings.backup.json. SIP003 packages installed from the Plugins page are stored in %LOCALAPPDATA%\Shadowsocks\Plugins and resolved by plugin id when a server starts. Old HKCU\Software\Shadowsocks Reborn\Settings values are ignored. Localization uses only the i18n.csv embedded inside Shadowsocks.exe; no second catalog is extracted.

The Settings page shows the active storage path and provides a single Open button that opens that directory in either normal or Clean Mode.

Rename the executable so its file name ends in p before .exe to start Clean Mode, for example Shadowsocksp.exe or Shadowsocks-cleanp.exe. Clean Mode redirects settings, caches, PAC data, logs, installed plugin packages, runtime files and helper/component-update working data to a unique %TEMP%\Shadowsocks\Clean\... session and removes that session best-effort on Quit. Start with Windows is unavailable in Clean Mode.

In normal mode, Start with Windows copies the verified product EXE to %LOCALAPPDATA%\Shadowsocks\Startup\Shadowsocks.exe; the Windows Run integration points to that stable copy. Startup migrates a legacy-only matching HKCU\Software\Microsoft\Windows\CurrentVersion\Run entry to the canonical entry, removes stale duplicates, and disabling Start with Windows removes matching legacy entries as well. An executable-identity-independent process gate prevents the LocalAppData startup copy and the original EXE from both starting a controller and racing for the same local port.

See STORAGE_POLICY.md for the complete layout and cleanup rules.

Application updates

Update downloads are staged as *.download; the file handle is closed before the temporary file is atomically promoted to its canonical name on Windows. SHA-256 sidecars may contain either <hash> Shadowsocks-win-x64.zip or just the 64-character hexadecimal digest.

Application updates are automatic by default. After startup, the app checks GitHub Releases, selects an eligible newer version, requires the exact Shadowsocks-win-x64.zip plus .sha256 sidecar, verifies the SHA-256, ZIP layout and payload file version, then stages the new single-file EXE under %TEMP%\Shadowsocks\Updates. Before launch, the staged updater receives its own SHA-256; the source process keeps that staged file open without write/delete sharing across Process.Start/UAC and passes the digest through the internal update handoff. The updater re-verifies its own staged image before replacing the installed product. It then waits for the current process to exit, preserves rollback state, replaces the product EXE and starts the installed new copy. That installed copy removes the temporary updater transaction. If Start with Windows launched the LocalAppData startup copy, the recorded primary EXE is updated instead of only the startup copy.

Embedded NetworkService

Release builds publish Shadowsocks.NetworkService as a self-contained single-file helper and embed it into Shadowsocks.exe.

User Mode never extracts the helper. Admin Mode extracts it on demand below the active storage root (%LOCALAPPDATA%\Shadowsocks\Temp\NetworkService\... in normal mode, the Clean Mode session in Clean Mode). Extraction is serialized, SHA-256 validated and followed by an elevated control-pipe version handshake. The helper is guarded while in use and removed best-effort when the broker stops; stale runtime directories are pruned later.

Development builds may use a separate helper from the build output. That fallback is not part of the release package.

WinDivert verification

Admin Mode is reported active only after the elevated capture process successfully opens WinDivert. A successful startup logs a message similar to:

WinDivert capture confirmed (start): Admin capture active.; TCP redirect port=..., UDP redirect port=...

For a functional test, add curl.exe -> Block, disable the Windows system proxy temporarily, and compare:

curl.exe -4 --noproxy "*" https://example.com

The direct request should bypass application routing in User Mode and be blocked in Admin Mode.

PAC, HTTP forwarding and DNS

Local PAC uses configured GeoSite sources and persistent cache data. Online PAC is downloaded through Shadowsocks and served to WinINet from the local /pac endpoint.

ManagedHttpProxyService handles HTTP/1.1 and HTTPS CONNECT. HTTPS is tunneled as bytes, so HTTP/2 negotiated inside TLS does not require a local HTTP/2 parser. FTP gatewaying is not implemented.

DNS policy contract

The current 2.2.31 configuration/IPC contract contains five DNS policy values, and Administrator Mode implements transparent routing for classic DNS captured on UDP/TCP port 53 through Shadowsocks.NetworkService + WinDivert:

Policy	Current behavior
System	Keeps captured classic DNS on its original/system destination without policy-specific redirection.
Direct	Can keep the original destination or redirect captured DNS to configured primary/fallback IPv4/IPv6 resolvers. The selected DNS endpoint can optionally be reached through the local Shadowsocks SOCKS5 path.
Proxy	Routes captured classic DNS through Shadowsocks.
CustomDoh	Bridges captured DNS wire messages to the configured HTTPS DoH endpoint; the DoH upstream can independently be routed through Shadowsocks.
DnsCrypt	Redirects captured DNS to the dynamically allocated local dnscrypt-proxy listener and operates fail-closed when the secure runtime is unavailable.

Transparent system-wide interception is therefore implemented in 2.2.31, but it requires Administrator Mode. User Mode still uses Shadowsocks-managed DNS/DNSCrypt where applicable, but it does not intercept arbitrary system DNS. Automatic Game Mode pauses system-wide interception while Admin capture is suspended. The transparent interception covers classic DNS on UDP/TCP 53; application-internal DoH, DoT and DoQ are not generically intercepted.

The DNS page manages the optional signed dnscrypt-proxy component. Automatic selects a concrete DNSCrypt/DoH resolver from the signed public catalog using DNSSEC, no-log, unfiltered and address-family constraints, then pins it in server_names. The active runtime uses bootstrap_resolvers = [] and ignore_system_dns = true; resolver-catalog refresh may use one-shot bootstrap DNS only before a signed catalog cache exists. Manual exposes signed DNSCrypt and DoH entries with protocol/country/address-family/privacy filters; ODoH remains disabled.

The DNS page also provides Test DNSCrypt and a DNS privacy self-test. The local listener allocator verifies that one loopback port is usable by both UDP and TCP. DNSCrypt PID/port changes are propagated to NetworkService at runtime. DNSCrypt is fail-closed during startup, restart, recovery and runtime failure instead of silently downgrading intercepted traffic to plaintext system DNS. Fragmented datagrams that would require DNS/proxy rewriting are dropped as a whole so later fragments cannot bypass policy; direct fragmented traffic remains direct.

WinDivert 2.2.2 is downloaded only from the pinned official release URL; the extracted x64 DLL/driver must match release-pinned SHA-256 digests before loading. A read-only FLOW observer supplies endpoint PID ownership for NETWORK-layer routing, with IP Helper lookup as fallback.

DNSCrypt Automatic mode prefers a compatible resolver in the country of the active Shadowsocks server and falls back to the best compatible signed-catalog resolver. Resolver country is derived only from endpoint IP GeoIP data; resolver names/descriptions are not treated as geographic metadata. Manual resolver latency is measured asynchronously and the active resolver uses dnscrypt-proxy's RTT when available. Automatic component update checks are persisted and run no more than once per 24 hours; initial installation remains explicit. When DNSCrypt itself is routed through Shadowsocks, Shadowsocks/forward-proxy endpoints must be IP literals to prevent DNS bootstrap recursion.

Documentation

Long-form Markdown is maintained in this dedicated GitHub Wiki rather than duplicated under the application repository. GitHub issue/PR templates remain under .github/ because GitHub requires those paths.

• ARCHITECTURE.md — project boundaries and runtime architecture.
• STORAGE_POLICY.md — LocalAppData, Clean Mode, component staging and application self-update storage rules.
• WINDOWS11_UI_GUIDE.md — current WinUI design/implementation rules.
• CONTRIBUTING.md — development rules.
• RELEASE_CHECKLIST.md — release validation.
• SECURITY.md — security reporting and sensitive areas.
• CHANGELOG.md — fork changes; upstream history remains in CHANGES.

License

shadowsocks-reborn is distributed under GPL-3.0-or-later. See License and the authoritative LICENSE.txt. Third-party components retain their own licenses; see Third-party notices.