Whonix cheatsheet

Tor Browser protects browser traffic only. Every other application on your system (terminal, email client, file manager network calls, OS telemetry) still uses your real IP. A single misconfigured app or DNS query outside Tor deanonymizes you.

Whonix eliminates this problem entirely - there is no route to the internet that does not pass through Tor. Even if you run curl without any proxy settings, it goes through Tor because the Gateway is the only network path.

Common leak vectors that Whonix blocks:

The OVA import pre-configures networking, but verify it is correct:

Gateway VM - needs TWO network adapters:

Adapter 1: NAT (external - connects to internet)
Adapter 2: Internal Network
  Name: "Whonix"
  Promiscuous Mode: Deny

Workstation VM - needs ONE adapter:

Adapter 1: Internal Network
  Name: "Whonix"
  Promiscuous Mode: Deny

Critical: both VMs must use the same Internal Network name ("Whonix"). The Workstation must NOT have a NAT or Bridged adapter.

# Verify Gateway networking
VBoxManage showvminfo "Whonix-Gateway" | grep NIC

# Verify Workstation networking
VBoxManage showvminfo "Whonix-Workstation" | grep NIC

# Start VMs (Gateway first, then Workstation)
VBoxManage startvm "Whonix-Gateway"
VBoxManage startvm "Whonix-Workstation"

On first boot, both VMs run whonixsetup / setup-dist:

# On Gateway - connect to Tor
sudo setup-dist

# Accept Whonix license
# Choose: Connect to Tor directly
# (or configure bridges if censored)

# Verify Tor connection
whonixcheck
# Should show: Tor connection working

# On Workstation - verify connectivity
whonixcheck
# Should show: connected through Tor

# Check your Tor IP
curl https://check.torproject.org

Default credentials: user user, password changeme. Change immediately.

# Change passwords on both VMs
sudo passwd root
passwd  # for user account

# Create new anonymous AppVM in dom0
qvm-create --template whonix-ws-17 \
  --label red \
  my-anon-vm

# Set networking through Whonix Gateway
qvm-prefs my-anon-vm netvm sys-whonix

# Create a disposable VM template
qvm-create --template whonix-ws-17 \
  --label red \
  --property template_for_dispvms=True \
  whonix-ws-dvm

qvm-prefs whonix-ws-dvm netvm sys-whonix

# Launch disposable VM (destroyed on shutdown)
qvm-run --dispvm=whonix-ws-dvm firefox

Advantage: each Workstation qube is isolated from the others. Compromise of one does not affect the rest. Disposable VMs leave no trace after shutdown.

# Create the isolated internal network
sudo virsh net-define Whonix_internal.xml
sudo virsh net-start Whonix_internal
sudo virsh net-autostart Whonix_internal

# Create the external NAT network
sudo virsh net-define Whonix_external.xml
sudo virsh net-start Whonix_external
sudo virsh net-autostart Whonix_external

# Import VMs
sudo virsh define Whonix-Gateway.xml
sudo virsh define Whonix-Workstation.xml

# Move disk images to libvirt pool
sudo mv Whonix-Gateway.qcow2 /var/lib/libvirt/images/
sudo mv Whonix-Workstation.qcow2 /var/lib/libvirt/images/

# Start VMs
sudo virsh start Whonix-Gateway
sudo virsh start Whonix-Workstation

Verify network isolation:

# List networks
sudo virsh net-list --all

# Confirm Workstation only has internal network
sudo virsh domiflist Whonix-Workstation
# Should show: Whonix_internal ONLY

# Confirm Gateway has both
sudo virsh domiflist Whonix-Gateway
# Should show: Whonix_external + Whonix_internal

Use bridges when your ISP blocks direct Tor connections or when you want to hide the fact that you are using Tor.

# /usr/local/etc/torrc.d/50_user.conf

UseBridges 1
ClientTransportPlugin obfs4 exec /usr/bin/obfs4proxy

# obfs4 bridges (get from bridges.torproject.org)
Bridge obfs4 IP:PORT FINGERPRINT \
  cert=BASE64CERT iat-mode=0
Bridge obfs4 IP:PORT FINGERPRINT \
  cert=BASE64CERT iat-mode=0

# Install obfs4proxy if not present
sudo apt install obfs4proxy

# Request bridges via email
# Send email to [email protected]
# Subject: (empty)
# Body: get transport obfs4

# Or use Whonix Bridge GUI
sudo setup-dist
# Select: Configure bridges

Available pluggable transports:

The Gateway's iptables configuration is the core of Whonix's security. It ensures only Tor traffic leaves the external interface.

# View current rules
sudo iptables -L -n -v
sudo ip6tables -L -n -v

# Key rules (simplified):
# - ACCEPT connections from Workstation to Tor ports
# - ACCEPT Tor daemon output to internet
# - REJECT/DROP everything else
# - IPv6 fully blocked by default

# Whonix firewall script location:
# /usr/bin/whonix-gateway-firewall

# Reload firewall
sudo whonix-gateway-firewall

# Verify no non-Tor leaks from Gateway
sudo iptables -L -n | grep -i drop

Whonix uses sdwdate (Secure Distributed Web Date) instead of NTP. NTP is unencrypted and can be used for fingerprinting. sdwdate fetches time from random Tor onion services over HTTPS.

# Check sdwdate status
sudo systemctl status sdwdate

# Restart sdwdate
sudo systemctl restart sdwdate

# View sdwdate log
journalctl -u sdwdate

# sdwdate adds random time offset to prevent
# time-based correlation attacks

Controls which Tor control port commands the Workstation can send to the Gateway. Prevents Workstation from fingerprinting the Tor connection.

# onion-grater runs on Gateway
# Config: /usr/share/onion-grater-merger/examples/

# Check status (on Gateway)
sudo systemctl status onion-grater

# View allowed commands
cat /etc/onion-grater.d/*.yml

# Workstation uses filtered control port
# 10.152.152.10:9051 (filtered by onion-grater)

# Workstation applications are pre-configured via
# uwt (Unix domain socket wrapper for Tor)

# Check uwt wrappers
ls /usr/lib/uwt/

# Manual SOCKS configuration for custom apps
# Example: route a custom tool through isolated port
export ALL_PROXY=socks5h://10.152.152.10:9100

# torsocks with specific port
torsocks -P 9102 ssh [email protected]

# curl with specific SOCKS port
curl --socks5-hostname 10.152.152.10:9101 \
  https://example.com

# Verify different circuits
curl --socks5-hostname 10.152.152.10:9100 \
  https://api.ipify.org
curl --socks5-hostname 10.152.152.10:9101 \
  https://api.ipify.org
# Should show different Tor exit IPs

How stream isolation prevents correlation:

Without isolation:
  Browser  ----+
  IRC      ----+--> Same Tor circuit --> Same exit IP
  SSH      ----+

  Exit node operator sees all three streams
  from the same circuit = same user

With isolation:
  Browser  ----> Circuit A ----> Exit 1
  IRC      ----> Circuit B ----> Exit 2
  SSH      ----> Circuit C ----> Exit 3

  Each application uses a different circuit
  and exits from a different Tor node

# Backup private key (critical!)
sudo cp /var/lib/tor/mysite/hs_ed25519_secret_key \
  /secure/backup/

# Set restrictive permissions
sudo chmod 700 /var/lib/tor/mysite/
sudo chown debian-tor:debian-tor /var/lib/tor/mysite/

# Onion authentication (client auth)
# Gateway - generate keys
sudo mkdir -p /var/lib/tor/mysite/authorized_clients/

# Client authorization key file
# /var/lib/tor/mysite/authorized_clients/alice.auth
# Format: descriptor:x25519:<base32-public-key>

Security considerations:

Traffic exits Tor at an exit node, then enters a VPN. The destination sees the VPN IP instead of a Tor exit node IP. Useful when targets block Tor exit nodes.

# On Workstation, set up VPN client
sudo apt install openvpn

# VPN config must use TCP (Tor only supports TCP)
# Modify .ovpn file:
#   proto tcp
#   remote vpn-server.com 443

# Start VPN inside Workstation
sudo openvpn --config vpn.ovpn

# Traffic flow:
# Workstation -> Tor (via Gateway) -> VPN -> Internet
# Destination sees: VPN IP
# VPN provider sees: Tor exit IP (anonymous)

Your ISP sees VPN traffic, not Tor. Hides Tor usage from your ISP. Configure the VPN on the HOST machine, before the Gateway.

# On the HOST (not Gateway, not Workstation)
sudo openvpn --config vpn.ovpn

# Gateway's NAT adapter routes through
# the host's VPN tunnel

# Traffic flow:
# Workstation -> Gateway -> Tor -> Host VPN -> ISP
# ISP sees: VPN traffic only
# VPN provider sees: Tor traffic (knows you use Tor)

# On Workstation
sudo apt install i2pd

# Configure i2pd to use Tor as outproxy
# /etc/i2pd/i2pd.conf
# outproxy.enabled = true
# outproxy.address = 127.0.0.1
# outproxy.port = 4444

sudo systemctl start i2pd

# Access I2P console
# http://127.0.0.1:7070

# I2P traffic is tunneled through Tor
# Provides additional anonymity layer

# Whonix ships with AppArmor profiles for key apps
sudo aa-status

# Profiles cover:
# - Tor Browser
# - sdwdate
# - onion-grater
# - Tor daemon

# Enforce a profile
sudo aa-enforce /etc/apparmor.d/usr.bin.torbrowser

# Check profile status
sudo aa-status | grep -A5 "enforce"

# Custom profile for a service
sudo aa-genprof /usr/bin/myapp
# Follow the wizard, then enforce

# Disable swap (prevents sensitive data on disk)
sudo swapoff -a
# Remove swap entries from /etc/fstab

# Secure shared memory
# /etc/fstab:
# tmpfs /run/shm tmpfs defaults,noexec,nosuid 0 0

# Install LKRG (Linux Kernel Runtime Guard)
# Detects kernel exploits at runtime
sudo apt install lkrg

# Verify LKRG is loaded
sudo systemctl status lkrg

# Entropy - ensure strong randomness
sudo apt install haveged jitterentropy-rngd
sudo systemctl enable haveged

# Disable Thunderbolt/Firewire DMA attacks
# Whonix security-misc handles this:
# Blacklists thunderbolt and firewire modules

Hardening checklist:

Run command-and-control infrastructure behind Whonix for maximum anonymity.

# On Gateway - create hidden service for C2
# /usr/local/etc/torrc.d/50_user.conf
HiddenServiceDir /var/lib/tor/c2/
HiddenServicePort 443 10.152.152.11:8443
HiddenServiceVersion 3

# Restart Tor
sudo systemctl restart tor@default

# Get .onion address
sudo cat /var/lib/tor/c2/hostname

# On Workstation - run C2 listener
# Example: simple HTTPS listener
sudo apt install nginx
# Configure reverse proxy to C2 framework
# listening on 10.152.152.11:8443

# Implant callback:
# Target -> Tor -> .onion:443 -> Gateway -> Workstation C2

# Benefits:
# - C2 server IP is hidden (.onion only)
# - No hosting provider to subpoena
# - Traffic blends with Tor network
# - Takedown resistant (no IP to block)

Infrastructure topology:

Implant on target
    |
    v
Tor network (3 hops)
    |
    v
C2 .onion address
    |
    v
Whonix-Gateway (routes to Workstation)
    |
    v
Whonix-Workstation (C2 framework running here)

No single point reveals the operator:
- Target sees .onion address only
- Tor relays see encrypted traffic
- ISP sees Tor traffic (or VPN if chained)
- Host machine IP never touches C2 traffic

# VirtualBox - take snapshot before operations
VBoxManage snapshot "Whonix-Workstation" take \
  "pre-operation" --description "Clean state"

# Restore to clean state after operation
VBoxManage snapshot "Whonix-Workstation" restore \
  "pre-operation"

# KVM snapshots
sudo virsh snapshot-create-as Whonix-Workstation \
  --name "pre-operation" --description "Clean state"

# Restore
sudo virsh snapshot-revert Whonix-Workstation \
  --snapshotname "pre-operation"

# Qubes - use disposable VMs instead
# They are destroyed automatically on shutdown

• Whonix
• Whonix Wiki
• Tor Project
• Kicksecure
• Qubes-Whonix
• Whonix Stream Isolation
• Whonix Security Guide
• Whonix GitHub

• Tails (Amnesic live OS for temporary anonymous sessions)
• Qubes OS (Security through compartmentalization with Xen)
• GrapheneOS (Hardened mobile OS for privacy-focused devices)
• Anonymization (Identity separation and OPSEC methodology)
• Mullvad VPN (Privacy-focused VPN with anonymous signup)
• OPSEC Checklist (Operational security verification steps)
• Cellular OPSEC (Mobile threat model, IMSI catchers, baseband)
• Tor (Tor network internals, circuit building, and onion routing)
• VirtualBox (Hypervisor setup and VM management)