Most of the time when you are using a public network, you are behind some kind of firewall or proxy. One of their purpose is to constrain you to only use certain kind of protocols and consult only a subset of the web.
Nowadays, the most widespread protocol is http and is de facto allowed by third party equipment.
Wstunnel uses the websocket protocol which is compatible with http in order to bypass firewalls and proxies. Wstunnel allows you to tunnel whatever traffic you want and access whatever resources/site you need.
My inspiration came from this project but as I don’t want to install npm and nodejs to use this tool, I remade it in Haskell Rust and improved it.
v7.0.0 is a complete rewrite of wstunnel in Rust and is not compatible with previous version. Previous code in Haskell can be found on branch
What to expect from previous version:
Usage: wstunnel client [OPTIONS] <ws[s]|http[s]://wstunnel.server.com[:port]>
Arguments:
<ws[s]|http[s]://wstunnel.server.com[:port]>
Address of the wstunnel server
You can either use websocket or http2 as transport protocol. Use websocket if you are unsure.
Example: For websocket with TLS wss://wstunnel.example.com or without ws://wstunnel.example.com
For http2 with TLS https://wstunnel.example.com or without http://wstunnel.example.com
*WARNING* HTTP2 as transport protocol is harder to make it works because:
- If you are behind a (reverse) proxy/CDN they are going to buffer the whole request before forwarding it to the server
Obviously, this is not going to work for tunneling traffic
- if you have wstunnel behind a reverse proxy, most of them (i.e: nginx) are going to turn http2 request into http1
This is not going to work, because http1 does not support streaming naturally
The only way to make it works with http2 is to have wstunnel directly exposed to the internet without any reverse proxy in front of it
Options:
-L, --local-to-remote <{tcp,udp,socks5,stdio,unix}://[BIND:]PORT:HOST:PORT>
Listen on local and forwards traffic from remote. Can be specified multiple times
examples:
'tcp://1212:google.com:443' => listen locally on tcp on port 1212 and forward to google.com on port 443
'tcp://2:n.lan:4?proxy_protocol' => listen locally on tcp on port 2 and forward to n.lan on port 4
Send a proxy protocol header v2 when establishing connection to n.lan
'udp://1212:1.1.1.1:53' => listen locally on udp on port 1212 and forward to cloudflare dns 1.1.1.1 on port 53
'udp://1212:1.1.1.1:53?timeout_sec=10' timeout_sec on udp force close the tunnel after 10sec. Set it to 0 to disable the timeout [default: 30]
'socks5://[::1]:1212' => listen locally with socks5 on port 1212 and forward dynamically requested tunnel
'tproxy+tcp://[::1]:1212' => listen locally on tcp on port 1212 as a *transparent proxy* and forward dynamically requested tunnel
'tproxy+udp://[::1]:1212?timeout_sec=10' listen locally on udp on port 1212 as a *transparent proxy* and forward dynamically requested tunnel
linux only and requires sudo/CAP_NET_ADMIN
'stdio://google.com:443' => listen for data from stdio, mainly for `ssh -o ProxyCommand="wstunnel client --log-lvl=off -L stdio://%h:%p ws://localhost:8080" my-server`
'unix:///tmp/wstunnel.sock:g.com:443' => listen for data from unix socket of path /tmp/wstunnel.sock and forward to g.com:443
-R, --remote-to-local <{tcp,udp,socks5,unix}://[BIND:]PORT:HOST:PORT>
Listen on remote and forwards traffic from local. Can be specified multiple times. Only tcp is supported
examples:
'tcp://1212:google.com:443' => listen on server for incoming tcp cnx on port 1212 and forward to google.com on port 443 from local machine
'udp://1212:1.1.1.1:53' => listen on server for incoming udp on port 1212 and forward to cloudflare dns 1.1.1.1 on port 53 from local machine
'socks5://[::1]:1212' => listen on server for incoming socks5 request on port 1212 and forward dynamically request from local machine
'unix://wstunnel.sock:g.com:443' => listen on server for incoming data from unix socket of path wstunnel.sock and forward to g.com:443 from local machine
--no-color <NO_COLOR>
Disable color output in logs
[env: NO_COLOR=]
--socket-so-mark <INT>
(linux only) Mark network packet with SO_MARK sockoption with the specified value.
You need to use {root, sudo, capabilities} to run wstunnel when using this option
-c, --connection-min-idle <INT>
Client will maintain a pool of open connection to the server, in order to speed up the connection process.
This option set the maximum number of connection that will be kept open.
This is useful if you plan to create/destroy a lot of tunnel (i.e: with socks5 to navigate with a browser)
It will avoid the latency of doing tcp + tls handshake with the server
[default: 0]
--nb-worker-threads <INT>
*WARNING* The flag does nothing, you need to set the env variable *WARNING*
Control the number of threads that will be used.
By default, it is equal the number of cpus
[env: TOKIO_WORKER_THREADS=]
--log-lvl <LOG_LEVEL>
Control the log verbosity. i.e: TRACE, DEBUG, INFO, WARN, ERROR, OFF
for more details: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#example-syntax
[env: RUST_LOG=]
[default: INFO]
--tls-sni-override <DOMAIN_NAME>
Domain name that will be used as SNI during TLS handshake
Warning: If you are behind a CDN (i.e: Cloudflare) you must set this domain also in the http HOST header.
or it will be flagged as fishy and your request rejected
--tls-sni-disable
Disable sending SNI during TLS handshake
Warning: Most reverse proxies rely on it
--tls-verify-certificate
Enable TLS certificate verification.
Disabled by default. The client will happily connect to any server with self-signed certificate.
-p, --http-proxy <USER:PASS@HOST:PORT>
If set, will use this http proxy to connect to the server
[env: HTTP_PROXY=]
--http-proxy-login <LOGIN>
If set, will use this login to connect to the http proxy. Override the one from --http-proxy
[env: WSTUNNEL_HTTP_PROXY_LOGIN=]
--http-proxy-password <PASSWORD>
If set, will use this password to connect to the http proxy. Override the one from --http-proxy
[env: WSTUNNEL_HTTP_PROXY_PASSWORD=]
-P, --http-upgrade-path-prefix <HTTP_UPGRADE_PATH_PREFIX>
Use a specific prefix that will show up in the http path during the upgrade request.
Useful if you need to route requests server side but don't have vhosts
[env: WSTUNNEL_HTTP_UPGRADE_PATH_PREFIX=]
[default: v1]
--http-upgrade-credentials <USER[:PASS]>
Pass authorization header with basic auth credentials during the upgrade request.
If you need more customization, you can use the http_headers option.
--websocket-ping-frequency-sec <seconds>
Frequency at which the client will send websocket ping to the server.
[default: 30]
--websocket-mask-frame
Enable the masking of websocket frames. Default is false
Enable this option only if you use unsecure (non TLS) websocket server, and you see some issues. Otherwise, it is just overhead.
-H, --http-headers <HEADER_NAME: HEADER_VALUE>
Send custom headers in the upgrade request
Can be specified multiple time
--http-headers-file <FILE_PATH>
Send custom headers in the upgrade request reading them from a file.
It overrides http_headers specified from command line.
File is read everytime and file format must contain lines with `HEADER_NAME: HEADER_VALUE`
--tls-certificate <FILE_PATH>
[Optional] Certificate (pem) to present to the server when connecting over TLS (HTTPS).
Used when the server requires clients to authenticate themselves with a certificate (i.e. mTLS).
The certificate will be automatically reloaded if it changes
--tls-private-key <FILE_PATH>
[Optional] The private key for the corresponding certificate used with mTLS.
The certificate will be automatically reloaded if it changes
SERVER
Usage: wstunnel server [OPTIONS] <ws[s]://0.0.0.0[:port]>
Arguments:
<ws[s]://0.0.0.0[:port]>
Address of the wstunnel server to bind to
Example: With TLS wss://0.0.0.0:8080 or without ws://[::]:8080
The server is capable of detecting by itself if the request is websocket or http2. So you don't need to specify it.
Options:
--socket-so-mark <INT>
(linux only) Mark network packet with SO_MARK sockoption with the specified value.
You need to use {root, sudo, capabilities} to run wstunnel when using this option
--websocket-ping-frequency-sec <seconds>
Frequency at which the server will send websocket ping to client.
--no-color <NO_COLOR>
Disable color output in logs
[env: NO_COLOR=]
--websocket-mask-frame
Enable the masking of websocket frames. Default is false
Enable this option only if you use unsecure (non TLS) websocket server, and you see some issues. Otherwise, it is just overhead.
--nb-worker-threads <INT>
*WARNING* The flag does nothing, you need to set the env variable *WARNING*
Control the number of threads that will be used.
By default, it is equal the number of cpus
[env: TOKIO_WORKER_THREADS=]
--restrict-to <DEST:PORT>
Server will only accept connection from the specified tunnel information.
Can be specified multiple time
Example: --restrict-to "google.com:443" --restrict-to "localhost:22"
--dns-resolver <DNS_RESOLVER>
Dns resolver to use to lookup ips of domain name
This option is not going to work if you use transparent proxy
Can be specified multiple time
Example:
dns://1.1.1.1 for using udp
dns+https://1.1.1.1 for using dns over HTTPS
dns+tls://8.8.8.8 for using dns over TLS
To use libc resolver, use
system://0.0.0.0
--log-lvl <LOG_LEVEL>
Control the log verbosity. i.e: TRACE, DEBUG, INFO, WARN, ERROR, OFF
for more details: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#example-syntax
[env: RUST_LOG=]
[default: INFO]
-r, --restrict-http-upgrade-path-prefix <RESTRICT_HTTP_UPGRADE_PATH_PREFIX>
Server will only accept connection from if this specific path prefix is used during websocket upgrade.
Useful if you specify in the client a custom path prefix, and you want the server to only allow this one.
The path prefix act as a secret to authenticate clients
Disabled by default. Accept all path prefix. Can be specified multiple time
[env: WSTUNNEL_RESTRICT_HTTP_UPGRADE_PATH_PREFIX=]
--restrict-config <RESTRICT_CONFIG>
Path to the location of the restriction yaml config file.
Restriction file is automatically reloaded if it changes
--tls-certificate <FILE_PATH>
[Optional] Use custom certificate (pem) instead of the default embedded self-signed certificate.
The certificate will be automatically reloaded if it changes
--tls-private-key <FILE_PATH>
[Optional] Use a custom tls key (pem, ec, rsa) that the server will use instead of the default embedded one
The private key will be automatically reloaded if it changes
--tls-client-ca-certs <FILE_PATH>
[Optional] Enables mTLS (client authentication with certificate). Argument must be PEM file
containing one or more certificates of CA's of which the certificate of clients needs to be signed with.
The ca will be automatically reloaded if it changesFor more information click here.
Kali Linux 2024.4, the final release of 2024, brings a wide range of updates and…
This Go program applies a lifetime patch to PowerShell to disable ETW (Event Tracing for…
GPOHunter is a comprehensive tool designed to analyze and identify security misconfigurations in Active Directory…
Across small-to-medium enterprises (SMEs) and managed service providers (MSPs), the top priority for cybersecurity leaders…
The free and open-source security platform SecHub, provides a central API to test software with…
Don't worry if there are any bugs in the tool, we will try to fix…