dns-go-core

README

dns-go-core

A high-performance DNS tunneling implementation in Go, ported from the slipstream C/C++ implementation.

Overview

dns-go-core creates covert channels that tunnel TCP traffic through DNS queries. It uses QUIC multipath transport for reliability and performance.

Features

• High Performance: QUIC multipath with custom congestion control
• Multiple Resolvers: Simultaneous connections through multiple DNS resolvers
• Wire Protocol Compatibility: Interoperable with the original C implementation
• Production Ready: Comprehensive test suite with >80% coverage
• Cross-Platform: Builds for Linux, macOS, and Windows

Key Specifications

Specification	Value
Protocol	QUIC over DNS TXT records
Encoding	Base32 with inline dots
Header Overhead	24 bytes
EDNS0 Payload	1232 bytes
Congestion Control	DCUBIC/BBR (client), Unlimited (server)

Installation

From Source

git clone https://github.com/aminsaedi/dns-go-core.git
cd dns-go-core
make build

Using Go Install

go install github.com/aminsaedi/dns-go-core/cmd/dns-go-client@latest
go install github.com/aminsaedi/dns-go-core/cmd/dns-go-server@latest

Pre-built Binaries

Download from the Releases page.

Docker

# Build images
make docker

# Or pull from registry
docker pull ghcr.io/aminsaedi/dns-go-client:latest
docker pull ghcr.io/aminsaedi/dns-go-server:latest

Quick Start

1. Generate TLS Certificates

make gen-certs
# Or manually:
openssl req -x509 -newkey rsa:4096 \
  -keyout key.pem -out cert.pem \
  -days 365 -nodes -subj "/CN=tunnel.example.com"

2. Start the Server

dns-go-server \
  --dns-listen-port=53 \
  --target-address=127.0.0.1:8080 \
  --domain=tunnel.example.com \
  --cert=cert.pem \
  --key=key.pem

3. Start the Client

dns-go-client \
  --tcp-listen-port=5201 \
  --resolver=8.8.8.8:53 \
  --resolver=1.1.1.1:53 \
  --domain=tunnel.example.com \
  --congestion-control=bbr

4. Connect Through the Tunnel

# Any TCP traffic to localhost:5201 is tunneled through DNS
curl -x socks5://localhost:5201 http://example.com

# Or use netcat
nc localhost 5201

Usage

Server Options

dns-go-server [options]

Options:
  --dns-listen-port int     UDP port for DNS listener (default: 53)
  --dns-listen-addr string  Address to bind DNS listener (default: 0.0.0.0)
  --target-address string   Upstream TCP service address (required)
  --domain string           Tunnel domain (required)
  --cert string             TLS certificate file (required)
  --key string              TLS private key file (required)
  --max-connections int     Maximum concurrent connections (default: 1000)
  --enable-ipv6             Enable IPv6 support
  --help                    Show help

Client Options

dns-go-client [options]

Options:
  --tcp-listen-port int        TCP port to listen on (default: 5201)
  --resolver string            DNS resolver address (can be repeated)
  --domain string              Tunnel domain (required)
  --congestion-control string  Congestion control: bbr or dcubic (default: bbr)
  --keep-alive duration        Keep-alive interval (default: 400ms)
  --enable-gso                 Enable Generic Segmentation Offload
  --help                       Show help

Examples

Tunnel SSH

# Server side (where SSH server runs)
dns-go-server \
  --dns-listen-port=53 \
  --target-address=127.0.0.1:22 \
  --domain=tunnel.example.com \
  --cert=cert.pem --key=key.pem

# Client side
dns-go-client \
  --tcp-listen-port=2222 \
  --resolver=8.8.8.8:53 \
  --domain=tunnel.example.com

# Connect via tunnel
ssh -p 2222 user@localhost

Tunnel HTTP/HTTPS

# Server side
dns-go-server \
  --dns-listen-port=53 \
  --target-address=127.0.0.1:80 \
  --domain=tunnel.example.com \
  --cert=cert.pem --key=key.pem

# Client side
dns-go-client \
  --tcp-listen-port=8080 \
  --resolver=8.8.8.8:53 \
  --domain=tunnel.example.com

# Access via tunnel
curl http://localhost:8080

Multiple Resolvers (Multipath)

dns-go-client \
  --tcp-listen-port=5201 \
  --resolver=8.8.8.8:53 \
  --resolver=1.1.1.1:53 \
  --resolver=9.9.9.9:53 \
  --domain=tunnel.example.com

Docker Compose

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Architecture

Client                           Server
+-------------+                  +-------------+
| TCP Listener|                  | DNS Listener|
+------+------+                  +------+------+
       |                                |
+------v------+                  +------v------+
|Stream Mgr   |                  |Stream Mgr   |
+------+------+                  +------+------+
       |                                |
+------v------+                  +------v------+
|QUIC/Multipath|<--- DNS --->   |QUIC/Multipath|
+------+------+                  +------+------+
       |                                |
+------v------+                  +------v------+
|DNS Resolver1|                  |Upstream TCP |
|DNS Resolver2|                  +-------------+
+-------------+

See docs/architecture.md for detailed documentation.

Testing

# Run all tests
make test

# Run with coverage
make test-coverage

# Run benchmarks
make bench

# Run fuzz tests
make fuzz

# Check coverage threshold (80%)
make check-coverage

Building

# Build for current platform
make build

# Build for all platforms
make release

# Build Docker images
make docker

Documentation

• Architecture - System design and components
• Protocol - Wire protocol specification
• Testing - Testing strategy and guidelines
• Contributing - How to contribute

Performance

Typical observed performance (varies by network conditions):

Metric	Value
Throughput	100 Kbps - 1 Mbps
Latency Overhead	+50-200ms
Memory Usage	~10-50 MB

Performance is primarily limited by DNS resolver rate limits and network latency.

Security Notice

This tool is intended for:

• Authorized security testing and penetration testing
• CTF competitions
• Security research
• Educational purposes
• Bypassing restrictive networks (with proper authorization)

Use responsibly and only on systems you own or have explicit permission to test.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT License

Acknowledgments

This is a Go port of slipstream, originally implemented in C/C++.