WARP

WARP provides an advanced solution for tunneling network traffic through various protocols: SSH, SOCKS5, WireGuard, and Cisco Secure Client. This tool ensures secure and efficient network data routing with a convenient terminal user interface and real-time monitoring.

Note: This is a fork of merzzzl/warp. See Fork Differences for what it adds on top of upstream.

Table of Contents

• Introduction
• Fork Differences
• Features
• Installation
• Usage
  • Command Line Options
  • Configuration File
• Configuration Examples
  • SSH Tunnel
  • SOCKS5 Proxy
  • WireGuard VPN
  • Cisco Secure Client
  • Domain Zones
• Monitoring
• License

Introduction

WARP offers a unified interface for working with different types of tunnels. It creates a virtual TUN interface, configures DNS and routing, and directs traffic through your chosen protocol. Thanks to the integrated text interface, you can monitor connections and track traffic usage in real-time.

Fork Differences

This fork extends the original merzzzl/warp with the following changes:

• Cisco Secure Client protocol — a new tunnel type (cisco) that establishes an AnyConnect / Cisco Secure Client session on a remote host over SSH and routes traffic through it. See Cisco Secure Client.
• Robust domain-zone normalization — a dedicated internal/utils/domain package (with tests) that normalizes and validates domain entries (trims leading dots, lowercases, rejects malformed names) before they are handed to the system DNS. Invalid domains are now skipped with a warning instead of breaking startup.
• Smarter DNS resolution in the service layer:
  • Guards against nil DNS responses so a failing resolver no longer crashes the handler.
  • Filters reserved / private IP answers (RFC 5737 TEST-NET, RFC 1918, loopback, link-local) to avoid poisoning the route table with non-routable addresses.
  • Most-specific protocol matching: when several protocols claim overlapping names, the longest label match wins regardless of config order.

Features

• Multiple Protocol Support:
  • SSH tunneling
  • SOCKS5 proxy
  • WireGuard VPN
  • Cisco Secure Client (AnyConnect)
• Automatic DNS configuration
• Flexible routing with IP address list support
• Domain zone routing to send a whole zone (e.g. all of .ru) through a tunnel
• Real-time monitoring:
  • Active connections
  • Traffic usage statistics
  • Protocol information
• Traffic type detection to identify used protocols
• IPv4 and IPv6 traffic handling

Installation

Before installing, ensure make and Go are installed on your system. The application requires root privileges to create network interfaces.

# Clone the repository
git clone https://github.com/merzzzl/warp.git
cd warp

# Build for your platform
make build

# Alternatively, for macOS ARM64
make build-darwin-arm64

Usage

Create a configuration file ~/.warp.yaml in your home directory and launch WARP:

sudo ./warp

Command Line Options

WARP supports the following command-line options:

• --verbose: Enable verbose logging for detailed operational logs (default: disabled)
• --debug: Enable debug logging with even more detailed information (default: disabled)
• --fun: Enable "magic" mode with colorful visualization (default: disabled)

Configuration File

The ~/.warp.yaml configuration file should contain tunnel and protocol settings:

# Basic configuration
tunnel:
  name: utun11         # Name of the TUN interface to create
  ip: 192.168.127.0    # IP address to assign to the interface
  serve_dns: true      # ServeDNS allow to swap system dns to warp dns

# Connection protocols (only one protocol in each list item is used)
protocols:
  - ssh:               # SSH tunnel configuration
      # ...SSH parameters...
  - socks5:            # SOCKS5 proxy configuration
      # ...SOCKS5 parameters...
  - wireguard:         # WireGuard VPN configuration
      # ...WireGuard parameters...
  - cisco:             # Cisco Secure Client configuration
      # ...Cisco parameters...

# Optional
ipv6: true            # Allow IPv6 traffic handling (default: false)

Configuration Examples

SSH Tunnel

tunnel:
  name: utun11
  ip: 192.168.127.0
protocols:
  - ssh:
      user: username            # SSH username
      password: password123     # Password (SSH keys recommended)
      host: example.com         # SSH server host
      domains:                  # Domains for DNS queries via tunnel
        - corp.example.com 
      dns:                      # Optional: DNS servers to use
        - 8.8.8.8
      ips:                      # Optional: Subnet list for routing
        - 10.0.0.0/8
        - 172.16.0.0/12

SOCKS5 Proxy

tunnel:
  name: utun11
  ip: 192.168.127.0
protocols:
  - socks5:
      user: username                # Optional: SOCKS5 username
      password: password123         # Optional: SOCKS5 password
      host: proxy.example.com:1080  # SOCKS5 proxy server address with port
      domains:                      # Domains for DNS queries via tunnel
        - corp.example.com 
      dns:                          # DNS servers
        - 8.8.8.8
      ips:                          # Subnet list for routing
        - 192.168.1.0/24

WireGuard VPN

tunnel:
  name: utun11
  ip: 192.168.127.0
protocols:
  - wireguard:
      private_key: aCZ7I1s+...        # WireGuard private key (Base64)
      peer_public_key: o78dBF...      # Peer public key (Base64)
      endpoint: wg.example.com:51820  # WireGuard server address with port
      domains:                        # Domains for DNS queries via tunnel
        - corp.example.com 
      address: 10.66.66.2             # IP address for WireGuard interface
      dns:                            # WireGuard DNS servers
        - 10.66.66.1
      ips:                            # Subnet list for routing
        - 10.66.66.0/24

Cisco Secure Client

The cisco protocol connects to a remote host over SSH, starts a Cisco Secure Client (AnyConnect) session there via /opt/cisco/secureclient/bin/vpn, and routes traffic through that host. The host/user/password fields are the SSH credentials of the intermediate machine; the cisco_* fields are the credentials for the Cisco VPN itself.

tunnel:
  name: utun11
  ip: 192.168.127.0
protocols:
  - cisco:
      host: gateway.example.com:22   # SSH host running Cisco Secure Client
      user: username                 # SSH username
      password: password123          # SSH password
      cisco_host: vpn.corp.example   # Cisco VPN profile / gateway
      cisco_username: corp-user       # Cisco VPN username
      cisco_password: corp-secret     # Cisco VPN password
      domains:                       # Domains for DNS queries via tunnel
        - corp.example.com
      dns:                           # Optional: DNS servers (auto-detected if empty)
        - 8.8.8.8
      ips:                           # Optional: Subnet list for routing
        - 10.0.0.0/8

Domain Zones

Any entry of domains may be a whole zone, so the tunnel picks up every host below it. This works for any protocol:

protocols:
  - wireguard:
      # ...WireGuard parameters...
      domains:
        - ru              # the entire .ru zone
        - .su             # a leading dot is allowed too
        - "*.xn--p1ai"    # IDN zones are written in punycode (.рф)

Matching happens on a label boundary, so the ru zone covers yandex.ru and mail.yandex.ru, but never peru.com. When several protocols claim the same name, the most specific one wins regardless of the order in the config: with corp.example.ru on an SSH tunnel and ru on WireGuard, corp.example.ru goes through SSH and the rest of the zone through WireGuard.

Routing is driven by DNS: a host is routed into the tunnel once it is resolved through it, so traffic sent to a bare IP address is not covered by a zone. Use ips for that.

Monitoring

WARP includes a text-based user interface (TUI) for monitoring that shows:

• Logs: Current system messages and events
• Connections: Active network connections, their direction, and protocols
• Bandwidth: Current and cumulative data transfer statistics
• IP List: Routed IP addresses
• Uptime: Application runtime duration

License

WARP is licensed under the MIT License, supporting open and collaborative development.