Metadata-Version: 2.4
Name: dns-tunnel-messenger
Version: 0.1.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

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

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