oob-server

OOB DNS callback server for dependency confusion testing.

Listens for DNS callbacks from dependency confusion PoC packages, parses the encoded data (package name, username, hostname, path), classifies risk, stores everything in SQLite, sends Discord notifications, and shows a live terminal dashboard.

License: MIT.

Quick Start (VPS + screen)

git clone <your-repo-url> /opt/oob-server
cd /opt/oob-server
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env
nano .env

Set DOMAIN to your callback domain and paste your DISCORD_WEBHOOK.

screen -S oob
sudo .venv/bin/python -m oob_server run
# Ctrl+A, D to detach
# screen -r oob to reattach

Configuration

Copy .env.example to .env and set:

Variable	Default	Description
DOMAIN	oob.example.com	Your OOB callback domain
DISCORD_WEBHOOK	(empty)	Discord webhook URL for notifications
LISTEN_IP	0.0.0.0	Bind address
LISTEN_PORT	53	DNS port (needs root or CAP_NET_BIND_SERVICE)
DEDUP_WINDOW	300	Seconds to suppress duplicate callbacks
RATE_LIMIT_WINDOW	60	Rate limit window in seconds
MAX_QUERIES_PER_IP	100	Max queries per IP in the rate limit window

If You Do Not Have A Domain

Buy a domain from any registrar, then point a callback subdomain at your VPS.

Example with Namecheap:

1. Buy a domain like example.com.
2. In Namecheap, open Domain List -> your domain -> Advanced DNS.
3. Add an A record for oob pointing to your VPS public IP.
4. Set DOMAIN=oob.example.com in .env.
5. Open port 53 on your VPS and start the server in screen.

If you want public callbacks, make sure the domain or subdomain actually resolves to your VPS before testing.

Install

To install from a published release:

pip install oob-server

To install from source while developing:

pip install -e ".[dev]"

CLI Commands

python3 -m oob_server run              # Start the server with live TUI
python3 -m oob_server run --quiet      # Start without TUI (log-only)
python3 -m oob_server run --port 5353  # Use a non-privileged port for testing
python3 -m oob_server recent           # Show last 50 callbacks
python3 -m oob_server stats            # Show summary statistics
python3 -m oob_server search --package mypkg --risk HIGH
python3 -m oob_server export --format json --output callbacks.json

How It Works

DNS Query (UDP:53)
  --> Parse packet (dnslib)
  --> Extract: package.user.host.path.timestamp.oob.yourdomain.xyz
  --> Fingerprint environment (CI, Docker, prod, dev)
  --> Classify risk (HIGH / MEDIUM / LOW)
  --> Deduplicate (SQLite)
  --> Store callback (SQLite)
  --> Send Discord notification
  --> Reply with A record (127.0.0.1)
  --> Update live TUI dashboard

Test It

# With the server running:
dig testpkg.user.host.path.12345.oob.example.com @127.0.0.1
python3 -m oob_server recent

If DISCORD_WEBHOOK is set, each callback should also send a Discord embed.

Running as a systemd Service

sudo cp deploy/packaging/oob-server.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable oob-server
sudo systemctl start oob-server
sudo journalctl -u oob-server -f

Project Layout

oob_server/        Python package
  server.py        Async DNS server + CLI
  parser.py        Query parsing, fingerprinting, risk classification
  storage.py       SQLite persistence + dedup + activity tracking
  notifier.py      Discord webhook with retry/backoff
  ui.py            Rich live terminal dashboard
  config.py        .env configuration loader
  logger.py        Logging setup
deploy/            Systemd service + helper scripts
tests/             pytest test suite

Development

pip install -e ".[dev]"
python -m pytest -q