Skip to content

About

whitenoise proxy

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

whitenoise

XChaCha20-Poly1305 pre-shared key proxy with two transports:

  • TCP proxy server + local SOCKS5 client
  • UDP proxy server + local SOCKS5 client

Requirements

  • Go 1.25+
  • Windows PowerShell (for build.ps1)
  • Optional: make (for Makefile targets on Unix-like systems)

build.ps1 and Makefile force GOTOOLCHAIN=go1.25.4+auto to avoid broken local Go runtime installations.

Project config

Main settings live in config.json:

Field Meaning
serverListen Server bind address (example: 0.0.0.0:8443; on Windows avoid ports inside excluded ranges)
clientListen Local SOCKS5 address (example: 127.0.0.1:1080)
serverAddr Remote server address for the client
transport tcp or udp
timeout Timeout in seconds (number)
bufferSize Client TCP copy buffer size in bytes (default 32768)
verbose true or false (or 1 / 0) for debug logs
pskKey Shared key, exactly 64 hex characters
routing Optional client routing (see below)

Generate a key:

.\build.ps1 genkey

Put the output into pskKey in config.json.

Makefile uses jq only to sanity-check pskKey before run-server / run-client. The client is started with --config config.json so routing and all client fields come from JSON.

Client routing (Xray-style, simplified)

Only the client applies routing: each SOCKS target gets an outbound — proxy (through whitenoise), direct (plain TCP connect), or block (reject).

Add a routing object to config.json:

Field Meaning
geoipFile Path to geoip.dat (v2ray/xray format)
geositeFile Path to geosite.dat
domainStrategy AsIs (default), IpIfNonMatch, or IpOnDemand (last two behave like Xray for our matcher set)
rules Ordered rules (first match wins)
final Outbound when nothing matches (default proxy)

Each rule:

  • domain — string list: geosite:TAG, ext:other.dat:TAG, regexp:…, domain:…, full:…, keyword:…, plain substring (like Xray), plus geosite:TAG@attr for @ attribute filters when present in the list data.
  • ip — string list: geoip:XX, geoip:!XX, ext-ip:file.dat:TAG, or a literal 1.2.3.0/24 / ::1/128.
  • network — optional ["tcp"], ["udp"], or both (omit for both).
  • protocol — optional ["bittorrent"] (TCP only, detected by sniffing BitTorrent handshake).
  • outbound — proxy, direct, or block.

Geo databases (same family as Xray-core), e.g. community builds:

This repo reads .dat entries sequentially (like Xray’s streaming find in infra/conf/router.go): only the matching country/tag slice is unmarshalled, not the whole file into RAM. Domain matching reuses the MPH matcher from Xray (internal/strmatcher, MPL-2.0).

UDP: block is honored; direct is not implemented yet (falls through to proxy and logs at debug). Protocol matching: currently only bittorrent is supported and only for TCP. If the client can't sniff a protocol, rules with protocol won't match.

Example fragment:

"routing": {
  "geoipFile": "C:/path/to/geoip.dat",
  "geositeFile": "C:/path/to/geosite.dat",
  "domainStrategy": "AsIs",
  "rules": [
    { "domain": ["geosite:category-ads-all"], "outbound": "block" },
    { "ip": ["geoip:private"], "outbound": "direct" }
  ],
  "final": "proxy"
}

CLI

Client with the same JSON as build.ps1:

go run ./cmd/whitenoize client --config config.json -v

You can still pass server, key, and -l on the CLI after loading the file to override values from JSON.

Makefile

If you have make and jq (for config.json):

make build
make run-server
make run-client
make genkey
make clean

Direct CLI usage

Server:

go run ./cmd/whitenoize server <64-hex-psk> --listen 0.0.0.0:8443 -T tcp -t 30 -v

Client (config file recommended):

go run ./cmd/whitenoize client --config config.json -v

Client (classic positional args, no routing unless --config):

go run ./cmd/whitenoize client 127.0.0.1:8443 <64-hex-psk> --listen 127.0.0.1:1080 -T tcp -t 30 -v

Switch -T to udp for UDP transport.

Windows quick start (PowerShell) (optional)

Build binary:

.\build.ps1 build

Run TCP server:

# config.json: "transport": "tcp"
.\build.ps1 run-server

Run TCP client (SOCKS5):

# config.json: "transport": "tcp"
.\build.ps1 run-client

Run UDP server/client:

# config.json: "transport": "udp"
.\build.ps1 run-server
.\build.ps1 run-client

Cleanup:

.\build.ps1 clean

About

whitenoise proxy

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages