OnionShield 0.3

Unaudited security prototype. OnionShield does not guarantee anonymity, is not affiliated with the Tor Project, Mullvad, or Proton, and is not a replacement for Tor Browser. Read the security limitations before relying on it.

OnionShield is an experimental Windows system-wide TCP tunnel over Tor. It pairs a WPF desktop interface with an independent Windows service. It is not a finished VPN product and makes no promise of absolute anonymity.

Preview

Connection view	Security overview

These images were generated by the offline UI-preview mode. They do not expose the author's IP address and are not evidence that the network is leak-free.

Installation and use

1. Download and extract the complete release archive.
2. Run OnionShield.exe and approve the Windows UAC prompt.
3. On its first launch, OnionShield automatically installs and starts its Windows service. There is no installer script or extra setup button to run manually.
4. Choose Automatic or an exit country, select a profile, and connect.

The x64 release includes the .NET 8 runtime. Keep the complete extracted folder: the Core directory contains Tor and sing-box, which are required during service installation. The engine is installed in C:\Program Files\OnionShield\Core and stores state in C:\ProgramData\OnionShield\Core. Both locations are restricted to administrators and SYSTEM.

The OnionShieldCore service uses the Automatic start type but starts in the disconnected state, so installing it does not alter routes until the user asks to connect. The current prototype runs its UI elevated because the local service control channel is restricted to administrators and SYSTEM.

• The close button hides the window in the notification area. Windows decides whether the icon is immediately visible or placed under the hidden-icons arrow.
• The tray menu can restore the window, connect or disconnect, close only the UI, or disconnect and then exit.
• Closing or crashing the UI does not stop the service, Tor, or an active tunnel.
• New circuit rebuilds the Tor path while keeping the TUN adapter in place. Existing connections may break, and a different exit IP is not guaranteed.
• Changing the country or performance profile while connected shows Apply and reconnect instead of silently changing the active connection.
• The main page does not scroll. Only the country list and technical log scroll.

Countries and performance profiles

The selected country constrains the exit relay, not every relay in the Tor circuit. OnionShield uses ExitNodes {code} with Tor's GeoIP databases and checks the observed exit country before displaying a verified state. If the constraint cannot be met, the application does not silently fall back to Automatic. A country being listed does not guarantee that a suitable Tor exit is currently available.

Profile	Behaviour
Balanced	Normal Tor selection, one HTTPS verification, and no benchmark download.
Lower latency	Builds two isolated SOCKS identities and compares HTTPS response times.
Speed priority	Downloads at most 512 KiB through each of two candidates and keeps the better measurement.

All profiles retain normal multi-relay Tor circuits and encryption. Measurements are short samples, not guarantees. Both candidates can share an exit. Country restrictions and performance-based selection may reduce path diversity; Automatic with Balanced is the recommended privacy-oriented default.

Interface

The window uses an integrated title bar, rounded translucent panels, custom dark scrollbars, and a 900 ms red/purple-to-green transition when the service reports Connected. Animations respect the Windows animation preference.

The Natural Earth 1:50m map uses a uniform Mercator projection and preserves vector outlines at maximum zoom. Sub-pixel geometry is simplified according to the current zoom, with country render caches rebuilt at that zoom rather than scaling a single low-resolution world image. Drag events are coalesced per render frame, and panning does not rebuild country outlines or markers. World fits the full map, while Recenter returns to the selected destination.

The developer command --ui-design-check <report-path> exercises the interface, palettes, map, resizing, scrolling, tray actions, and languages without connecting, disconnecting, installing the service, or changing the network. Preview captures are explicitly marked UI PREVIEW · network unchanged and use documentation-only addresses. OnionShield.MapBench provides an isolated map benchmark; its callback figures are not GPU frame-time measurements.

Network architecture

Windows applications → sing-box TUN adapter → local SOCKS selector → Tor → Internet

• The TUN captures IPv4 and IPv6 through auto_route and strict_route.
• Captured DNS is sent as DNS-over-HTTPS through Tor. Resolution prefers IPv4, while literal IPv6 destinations remain inside the tunnel.
• Tor does not carry arbitrary UDP. UDP, QUIC, and ICMP are rejected; applications that require UDP may fail. OnionShield does not add per-application exceptions.
• Only the exact installed Tor executable receives a direct path to its relays. OnionShield does not add exceptions for Edge, Python, or other applications.
• Local commands use a named pipe restricted to SYSTEM and administrators. The Tor control port uses cookie authentication, and the sing-box selector listens only on localhost with a random secret.

OnionShield does not change Edge policies, close Edge, install a user proxy, or launch a special browser. Rules left by older prototypes, another VPN, or an organization require separate diagnosis and must not be deleted blindly.

Security limitations

Valid HTTPS protects content between the application and the destination through the Tor exit. OnionShield does not disable certificate validation or install an interception certificate. Plain HTTP remains readable by an exit relay.

Tor does not hide identifying account activity, make a normal browser resistant to fingerprinting, secure a compromised device, or defeat an adversary able to perform traffic correlation. InPrivate mode is not equivalent to Tor Browser.

The service keeps the network engine independent from the UI. If Tor stops while the TUN is still active, traffic has no direct fallback and the service attempts to recover Tor. However, there is no independent WFP-based kill switch: a crash of sing-box or the service can remove the TUN and restore ordinary routes. Automatic recovery does not remove that leak window. A persistent firewall/driver layer and an external audit are required before treating this prototype as a dependable privacy product.

IPv4, IPv6, strict routing, and captured DNS are covered by configuration tests, but that is not proof of leak resistance on every Windows setup. Test Ethernet and Wi-Fi together, WSL/Docker adapters, other VPNs, suspend/resume, service crashes, and connections opened before activation. Diagnostic logs retain at most 40 lines in service memory and engine errors may include a destination.

Languages

The interface supports English, French, Spanish, and German. The selector appears in the top bar and in Connection & security. The preference is applied immediately and stored in %LOCALAPPDATA%\OnionShield\ui-preferences.json; changing it does not modify routes or service settings. Original Tor and tunnel log messages remain untranslated so diagnostic details are preserved.

Building and verification

Development prerequisites are Windows 10/11 x64 and the .NET 8 SDK. Third-party binaries are intentionally excluded from Git. Their expected layout, versions, and hashes are documented in DEPENDENCIES.md.

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\Publish.ps1
dotnet run --project .\OnionShield.ConfigTests -- "$PWD"
dotnet run --project .\OnionShield.UiTests -- .\.test-release\ui-check.txt

The configuration test validates all 12 country configurations, rejects invalid country values and injection attempts, checks IPv6/DNS/routing invariants, and runs sing-box check. It does not start the system tunnel and is not a real-world leak test. UI tests explicitly disable automatic service installation.

Install-Service.ps1 is an internal release helper invoked automatically by OnionShield.exe; users do not need to run it. It will not replace a service that is already running. For an engine update, disconnect and stop the service first. Uninstall-Service.ps1 remains an explicit administrator tool and preserves state files for recovery.

Useful references: .NET self-contained deployment, Tor path selection, sing-box TUN, and sing-box selector.

License

OnionShield's original code is released under GNU GPL version 3; see LICENSE. Tor, sing-box, the .NET runtime, and Natural Earth data remain under their respective licenses, listed in THIRD-PARTY-NOTICES.md.