Metadata-Version: 2.4
Name: dns-tunnel-messenger
Version: 0.2.0
Summary: Smuggle messages inside DNS queries — encode, ship, and decode via subdomain labels.
License: MIT
Keywords: dns,tunneling,exfiltration,espionage,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Security
Classifier: Topic :: Communications
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

<div align="center">

# 🛰️ DNS Tunneling Messenger

<img src="https://raw.githubusercontent.com/AnonymoDGH/dns-tunnel-messenger/main/logo.svg" alt="DNS Tunneling Messenger" width="180"/>

**Smuggle messages inside DNS queries.**

[![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![PyPI](https://img.shields.io/badge/PyPI-dns--tunnel--messenger-orange.svg)](https://pypi.org/project/dns-tunnel-messenger/)
[![Platform](https://img.shields.io/badge/platform-osx%20%7C%20linux%20%7C%20windows-lightgrey.svg)]()

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

</div>

---

## 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

```bash
pip install dns-tunnel-messenger
```

From source:

```bash
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):

```bash
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):

```bash
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

| Command | What it does |
|---|---|
| `dns-tunnel send <msg> --zone <z> [--server] [--port]` | Ship a message as a DNS query |
| `dns-tunnel listen [--port] [--zone]` | Decode incoming queries live |
| `dns-tunnel encode <msg> --zone <z>` | Print the encoded dotted name |
| `dns-tunnel decode --name <n> [--zone <z>]` | Decode a name back to text |
| `dns-tunnel bench {codec,name,chunker,capacity,all} [--json]` | CPU benchmarks & capacity |
| `dns-tunnel capacity [--zone <z>] [--sweep] [--json]` | Per-codec throughput table |
| `dns-tunnel shape-plan <frames> [--profile <p>] [--rate-limit <qps>]` | Print a shaped send timetable |
| `dns-tunnel session-save <file> --zone <z>` | Save a client session state file |
| `dns-tunnel session-load <file> [--json]` | Load & verify a session state file |

### Shaping a transmission

```bash
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

```bash
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

<img src="https://raw.githubusercontent.com/AnonymoDGH/dns-tunnel-messenger/main/assets/architecture.svg" alt="Architecture" width="820"/>

## Tests

```bash
pip install pytest
pytest
```

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

## License

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