pawdance/README.md

Paw Dance

paws to paws, a stealth‑grade, post‑quantum SSH VPN

Pawdance is a tool that uses OpenSSH you already trust into a fully working Layer‑3 VPN.

Pawdance can also fuction as transparent vpn if needed. Good for prodcution, when accsess to server is required and its network. why use third party vpns if you have ssh?

No fixed packet signature, but strong censorship resistance

WireGuard and SSTP send a recognisable first‑flight; OpenVPN’s TLS ClientHello can be fingerprinted.
SSH randomises its initial IV and padding, so every session’s first packet length is different, defeating simple length‑based fingerprints.

Stealthy

http://witch.valdikss.org.ru/ test detected as internet modem.

Important one‑time step on the server

OpenSSH must be told to allow tunnel devices.
Edit the daemon config manually and restart the service:

sudo vim /etc/ssh/sshd_config         
# ──────────────────────────────────────────────
PermitTunnel yes                         # add this line (or PermitTunnel point-to-point)
# ──────────────────────────────────────────────

sudo systemctl restart sshd

Installation client and server

# run installer on each side
sudo bash install.sh

The installer simply copies pawdance into /usr/local/bin/

1 – Prepare the client

# generate a template
pawdance make-config --role client -o pawdance-client.conf

# edit it
vim pawdance-client.conf

Example client config:

# ---------------------------------------------------------------------------
# pawdance
# ---------------------------------------------------------------------------
ROLE="client"              # client or server

CONNECT_MODE="auto"         # dns|ip|auto
REMOTE_HOST="vpn.example.com"   # used when dns/auto
# REMOTE_CONNECT_IP4="203.0.113.42"   # used when ip/auto with no REMOTE_HOST.
# REMOTE_CONNECT_IP6="2001:db8::42"
CONNECT_PREFER="auto"       # auto|ipv4|ipv6

# --- SSH authentication -----------------------------------------------------
REMOTE_USER="youruser"
SSH_KEY_MODE="false"        # true = pass explicit key; false = default chain
SSH_KEY="/home/alice/.ssh/id_ed25519" # only if SSH_KEY_MODE=true

# --- Tunnel parameters ------------------------------------------------------
TUN_INDEX="1"
TUN_DEV="tun${TUN_INDEX}"
LOCAL_IP4="10.0.1.2/24"
REMOTE_IP4="10.0.1.1"
LOCAL_IP6="2001:db8:1::2/64"
REMOTE_IP6="2001:db8:1::1"
MTU="1500"

# --- Crypto preferences -----------------------------------------
SSH_KEX="mlkem768x25519-sha256"
SSH_CIPHERS="chacha20-poly1305@openssh.com"
SSH_MACS="hmac-sha2-512-etm@openssh.com,hmac-sha2-256-etm@openssh.com"

# use remote server as vpn for all traffic.
# if set to false, vpn becomes transparent.
DEFAULT_ROUTE_IPV4="true"
DEFAULT_ROUTE_IPV6="true"

2 – Prepare the server

pawdance make-config --role server -o srv-config.conf
vim srv-config.conf

Example server config:

# ---------------------------------------------------------------------------
# pawdance
# ---------------------------------------------------------------------------
ROLE="server"

# --- Tunnel parameters ------------------------------------------------------
TUN_INDEX="1"
TUN_DEV="tun${TUN_INDEX}"
LOCAL_IP4="10.0.1.1/24"
LOCAL_IP6="2001:db8:1::1/64"
MTU="1500"

# allow clients to accsess networks on the server?
VPN_FORWARD="true"  # iptables/ip6tables FORWARD rules

#keep this to true. It is required for the tunnel to work.
# this enables net.ipv4.ip_forward + net.ipv6.conf.all.forwarding
IP_FORWARD="true"

3 – Bring the tunnel up

On the server

sudo pawdance up --config srv-config.conf

server is now ready. client can connect.

On the client

sudo pawdance up --config pawdance-client.conf

First run may prompt for:

• “Are you sure you want to continue connecting (yes/no)?”
• SSH password or pass‑phrase (unless key‑based auth already set up)

Once authenticated:

ip addr show tun1          # should list 10.0.1.2/24
ping 10.0.1.1              # ping the server’s tunnel IP
curl ifconfig.me           # should show the VPS public IP if default routed

4 – Tear down

# either side:
sudo pawdance down --config <your‑config>.conf

This removes:

• per‑family default routes
• passthrough routes to the SSH endpoint
• the TUN interface
• any iptables/ip6tables FORWARD rules added by Pawdance

(Kernel forwarding sysctls remain as you set them.) useful if script was terminated forcefully. Or you wanna remove tun from server.

---

Why Pawdance is stealthier than “normal” VPNs

1. Looks like vanilla SSH — no OpenVPN/WireGuard/IPsec signatures.
2. Randomised first‑packet length — SSH padding defeats length‑marker DPI.
3. Nothing new listening — only your hardened sshd.
4. PQ‑safe handshake — same post‑quantum KEX most modern OpenSSH clients now use.

---