Repository navigation
EN Usage Guide
This is the complete usage overview of SniShaper. Follow the first four sections in order to get up and running; consult the rest as needed.
- Download the latest stable Windows build from Releases (Linux GUI and cross-platform CLI builds are also available — see Platform_EN.md).
- Unzip and run
SniShaper.exe. - Run as administrator is recommended: system proxy writes and TUN mode require elevation; autostart (via Task Scheduler) also requires it, and once configured it launches at logon without a UAC prompt.
- To build from source, see build_EN.md (12-target artifact matrix).
MITM, QUIC and similar modes terminate TLS locally and re-issue certificates, so the SniShaper root CA must be trusted first:
- GUI: Settings → Certificate Management → Reinstall Certificate — see Certificate Installation.
- CLI:
snishaper ca install(requires admin / root).
Note
You can skip this step if you only use modes that do not decrypt traffic (Transparent / TLS-RF, etc.).
- Click Start Proxy in the main window. SniShaper serves HTTP and SOCKS5 on the same mixed port (default port is configurable; via CLI use
port get|set). - A rich set of official rules (~3800 lines of site-group rules) is bundled — usually no manual configuration is needed.
Pick one (or neither, and point apps at the proxy manually):
| Method | Description | Best for |
|---|---|---|
| System proxy | Writes the Windows system proxy setting; browsers follow immediately | Only browsers need the proxy |
| TUN virtual NIC | Transparently captures all traffic with auto-routing and DNS hijacking | Apps that ignore system proxy / global capture |
Note: enabling TUN first turns off the system proxy set by SniShaper, and disabling TUN restores it.
SniShaper offers 5 modes per site group. Full details in Core Proxy Modes:
| Mode | One-liner |
|---|---|
| Transparent | Only fixes DNS / target IP — for plain DNS pollution |
| MITM | Terminates TLS locally, re-handshakes with custom SNI / ECH; enables domain fronting |
| QUIC | Re-emits outbound as HTTP/3 with ClientHello scrambling |
| TLS-RF | TLS handshake fragmentation with precise cut points and timing perturbation |
| Migration | TLS 1.2 session resumption — no fresh handshake after a connection reset |
GFWList-based suffix matching auto-identifies blocked domains, covering sites not present in the rules; auto-routing picks paths based on live measurements. See Auto Routing and the Custom Rules Guide.
-
Encrypted DNS (DoH): built-in anti-pollution resolver with multi-node failover; configure in the DNS page or via
dnscommands. -
ECH Injection: automatically fetches and injects ECH Config with DoH discovery and hot-reload (
ech fetch <domain>refreshes manually). -
Cloudflare IP pool: auto speed-test, health checks and refresh (
cf status|refresh|health). -
NAT64: flexible IPv6 egress to bypass IPv4-only blocking (
nat64 list|test). -
Evolution mode: automatically tests rule combinations to find the optimal access method for a target site and applies it in one click (
evolution start). -
Migration:
migration status|on|off|server|test.
-
GUI: enable autostart in Settings. It uses the Windows Task Scheduler (
LogonTrigger+HighestAvailable): after running the app as admin once, it starts at logon without a UAC prompt; upgrades automatically clean up the legacy registry Run value to prevent double-launch. -
CLI:
snishaper autostart on --with-proxyenables a separate autostart entry for the CLI service (independent from the desktop app); turn it off withautostart off.
Running snishaper with no arguments opens the interactive panel (TUI); single commands work like snishaper status, snishaper tun on. See the full catalog in the CLI Reference.
Certificate warnings, rules not applying, port conflicts and more are covered in the FAQ. For a quick end-to-end check run snishaper selfcheck (verifies service, listening port, proxied request, system proxy and TUN).