🛰️ DNS Tunneling Messenger

Smuggle messages inside DNS queries.

"He isn't browsing. He's talking."

What is it?

DNS is the one protocol that is always allowed out. Firewalls may block everything else, but something has to resolve names — and that something can carry cargo. DNS Tunneling Messenger encodes a message in base32, slices it into DNS-label-sized chunks, and ships it as subdomains of a zone you control. A listener parses the query names on the other end and reassembles the message.

The protocol itself is boring, standard DNS. The payload is in the names.

Features

• ✉️ Encode any text into a valid dotted DNS name
• 📡 Ship it as a real UDP DNS query (send)
• 👂 Decode it live from the wire (listen)
• 🧩 Handles long messages (automatic 63-char label slicing)
• 📦 Zero dependencies — pure Python standard library

v0.2.0 — protocol hardening & operations toolkit

• 🚦 Traffic shaping (shaping) — beacon scheduling with jitter profiles (constant / uniform / poisson / bursty), token-bucket rate limiting, and adaptive pacing that backs off on RCODE_REFUSED/SERVFAIL and cautiously recovers on success.
• 🧱 Fragmentation strategies (fragmentation) — fixed-size, label-budget-aware (stay under a fraction of the 253-octet name limit), and priority-queue chunking (control frames first), behind a pluggable strategy registry.
• 💾 Session persistence (persistence) — save/resume client state (pending messages, acked seqs, counters) to versioned, fingerprint-checked JSON so a restart resumes instead of retransmitting.
• 🛡️ Replay protection (replay) — bounded TTL nonce ledger, timestamp-window validation, and a challenge-response handshake riding the existing frame format.
• 📈 Benchmarks (bench) — deterministic codec/name/chunker throughput benchmarks plus per-codec capacity planning and zone-length sweeps.
• 🎲 Fuzz suite — seeded random payloads shaken through every layer (codecs, frames, chunking, crypto, packet parser) asserting roundtrip integrity and typed errors, never crashes.

Install

pip install dns-tunnel-messenger

From source:

git clone https://github.com/AnonymoDGH/dns-tunnel-messenger
cd dns-tunnel-messenger
pip install -e .

Quickstart — lab test on loopback

Terminal A (the listener):

dns-tunnel listen --port 5353 --zone t.example.com
# [+] Listening on udp://0.0.0.0:5353 for zone t.example.com

Terminal B (the courier):

dns-tunnel send "meet at dawn, bring the book" \
    --zone t.example.com --server 127.0.0.1 --port 5353

Terminal A prints:

  [*] 127.0.0.1 -> meet at dawn, bring the book

CLI reference

Shaping a transmission

dns-tunnel shape-plan 20 --profile bursty --interval 1.0 --rate-limit 5 --verbose
# profile=bursty interval=1.0s frames=20
# total=...s effective=... qps  [rate-limited]

Capacity planning

dns-tunnel capacity --zone t.example.com
#   base32       140 B/name      1400.0 B/s
#   base64url    170 B/name      1700.0 B/s
#   hex          111 B/name      1110.0 B/s

How it works

Tests

pip install pytest
pytest

Includes an end-to-end test that ships a real message over loopback UDP.

License

MIT — a fiction research prop. Point it at zones you control and keep the novel's intrigue on the page, not the network.