DNS Server for ISP

A comprehensive DNS server solution similar to AdGuard, designed for ISPs and end-users with advanced filtering, monitoring, and multi-tenant capabilities.

✨ NEW: Now with rate limiting and webhook integration! See Rate Limiting Guide and Webhook Integration.

🚀 Features

Core DNS Functionality

✅ Recursive DNS resolver with IPv4 and IPv6 support
✅ DNS-over-HTTPS (DoH) support (RFC 8484)
✅ DNS-over-TLS (DoT) support (RFC 7858)
✅ Intelligent DNS response caching
✅ Blacklist/whitelist domain filtering

Ad-Blocking & Filtering

✅ Automatic blocklist updates from trusted sources
✅ Support for exact match, wildcard, and regex filtering
✅ Custom rules per ISP/customer
✅ Whitelist overrides for trusted domains
✅ Multiple category support (ads, trackers, malware, adult content)

Real-time Monitoring

✅ Complete DNS query logging
✅ Suspicious activity detection (DNS tunneling, malware C2)
✅ Prometheus metrics export
✅ Grafana dashboard integration
✅ Live query statistics and visualizations

Admin Panel & API

✅ Modern React-based web dashboard
✅ Real-time charts with ApexCharts
✅ Role-based access control (super_admin, isp_admin, customer)
✅ RESTful API with FastAPI
✅ Complete API documentation
✅ Dark mode support

Multi-ISP Support

✅ Multi-tenant architecture
✅ ISP-specific configurations and blocklists
✅ API key management for ISP integration
✅ Isolated dashboards per ISP
✅ Subscription tier support

Security & Reliability

✅ JWT-based authentication
✅ TLS encryption for DoH/DoT
✅ Password hashing with bcrypt
✅ Database connection pooling
✅ Docker containerization
✅ Health check endpoints
✅ Rate limiting middleware (NEW)
✅ Webhook signature verification (NEW)

Integration & Extensibility

✅ Webhook support for real-time events (NEW)
✅ Rate limiting with configurable thresholds (NEW)
✅ Event-driven architecture
✅ Complete REST API
✅ Prometheus metrics integration

📋 Requirements

Docker & Docker Compose
Python 3.11+
Node.js 18+
PostgreSQL 15+
Redis 7+

🛠️ Quick Start

Using Docker Compose (Recommended)

Clone the repository:

git clone https://github.com/i4edubd/DNS-for-ISP.git
cd DNS-for-ISP

Configure SSL certificates (for DoH/DoT):

# For testing with self-signed certificates (default)
echo "SSL_SELF_SIGNED=true" >> backend/.env

# For production, use valid certificates
# SSL_SELF_SIGNED=false
# SSL_CERT_FILE=/path/to/cert.pem
# SSL_KEY_FILE=/path/to/key.pem

Start all services:

cd docker
docker-compose up -d

Access the services:

Frontend Dashboard: http://localhost:3000
Backend API: http://localhost:8000
API Documentation: http://localhost:8000/docs
DNS Server: UDP/TCP port 53
DoH Endpoint: https://localhost:443/dns-query
DoT Server: TLS port 853
Prometheus: http://localhost:9090
Grafana: http://localhost:3001 (admin/admin)

Manual Setup

Backend Setup

Install dependencies:

cd backend
pip install -r requirements.txt

Configure environment:

cp .env.example .env
# Edit .env with your settings

Initialize database:

# Database will be auto-initialized on first run

Run the server:

python -m uvicorn app.main:app --host 0.0.0.0 --port 8000

Frontend Setup

Install dependencies:

cd frontend
npm install

Configure API URL:

# Create .env file
echo "REACT_APP_API_URL=http://localhost:8000" > .env

Run development server:

npm start

📖 API Documentation

Authentication

Register User

curl -X POST http://localhost:8000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "username": "newuser",
    "password": "securepassword",
    "full_name": "New User"
  }'

Note: Registration creates a customer role by default. Admin users must be created by super admins through privileged flows.

Login

curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin&password=securepassword"

DNS Operations

Query DNS

curl -X POST http://localhost:8000/api/dns/query \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com",
    "query_type": "A"
  }'

Get Query Logs

curl http://localhost:8000/api/dns/queries?limit=100 \
  -H "Authorization: Bearer YOUR_TOKEN"

Get Statistics

curl http://localhost:8000/api/dns/stats?hours=24 \
  -H "Authorization: Bearer YOUR_TOKEN"

Blocklist Management

Add Domain to Blocklist

curl -X POST http://localhost:8000/api/blocklist/add \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "malicious-site.com",
    "rule_type": "exact",
    "category": "malware"
  }'

Update Blocklists

curl -X POST http://localhost:8000/api/blocklist/update \
  -H "Authorization: Bearer YOUR_TOKEN"

ISP Management

Create ISP

curl -X POST http://localhost:8000/api/isp/create \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My ISP",
    "domain": "myisp.com",
    "subscription_tier": "premium"
  }'

Webhook Management

Register Webhook

curl -X POST http://localhost:8000/api/webhooks/register \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["dns.blocked", "alert.suspicious_activity"],
    "secret": "your-webhook-secret"
  }'

List Webhooks

curl http://localhost:8000/api/webhooks/list \
  -H "Authorization: Bearer YOUR_TOKEN"

See Webhook Integration Guide for complete documentation.

Rate Limiting

Rate limiting is automatically enabled with default settings:

100 requests per 60 seconds per IP
Configurable via environment variables

See Rate Limiting Guide for details.

DNS-over-HTTPS (DoH) and DNS-over-TLS (DoT)

The server now supports encrypted DNS protocols:

Using DoH

# Query using curl (POST method)
curl -H 'Content-Type: application/dns-message' \
     --data-binary @query.bin \
     https://localhost:443/dns-query

# Configure in browsers
# Firefox/Chrome: Settings → DNS over HTTPS → https://localhost:443/dns-query

Using DoT

# Query using kdig
kdig -d @localhost +tls example.com

# Configure systemd-resolved
echo "[Resolve]
DNS=your-server-address
DNSOverTLS=yes" | sudo tee -a /etc/systemd/resolved.conf
sudo systemctl restart systemd-resolved

See DoH/DoT Guide for complete documentation.

🏗️ Architecture

┌─────────────────┐
│   React Frontend │
│   (Port 3000)    │
└────────┬─────────┘
         │
         ▼
┌─────────────────┐      ┌──────────────┐
│   FastAPI       │◄────►│  PostgreSQL   │
│   Backend       │      │  Database     │
│   (Port 8000)   │      └──────────────┘
└────────┬─────────┘
         │                ┌──────────────┐
         ├───────────────►│    Redis      │
         │                │    Cache      │
         │                └──────────────┘
         │
         ▼
┌─────────────────┐      ┌──────────────┐
│   Prometheus    │◄────►│   Grafana     │
│   Metrics       │      │   Dashboard   │
└─────────────────┘      └──────────────┘

🔧 Configuration

Environment Variables

Create a .env file in the backend directory:

# Application
APP_NAME="DNS Server for ISP"
DEBUG=false

# Server
HOST=0.0.0.0
PORT=8000

# DNS
DNS_HOST=0.0.0.0
DNS_PORT=53
DNS_CACHE_TTL=3600
DNS_UPSTREAM_SERVERS=["8.8.8.8", "8.8.4.4", "1.1.1.1"]

# DoH/DoT
DOH_ENABLED=true
DOH_PORT=443
DOT_ENABLED=true
DOT_PORT=853

# SSL/TLS Configuration for DoH/DoT
SSL_CERT_FILE=/etc/ssl/certs/dns_cert.pem
SSL_KEY_FILE=/etc/ssl/private/dns_key.pem
SSL_SELF_SIGNED=true  # Use false in production with valid certs

# Database
DATABASE_URL=postgresql+asyncpg://dns_user:dns_pass@localhost:5432/dns_db

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0

# Security
SECRET_KEY=your-secret-key-change-in-production
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

# CORS
CORS_ORIGINS=["http://localhost:3000"]

# Monitoring
PROMETHEUS_ENABLED=true

📊 Monitoring

Prometheus Metrics

The system exposes the following metrics:

dns_queries_total - Total DNS queries
dns_blocked_queries_total - Total blocked queries
dns_response_time_seconds - DNS response time histogram
dns_cache_hits_total - Cache hit counter
dns_cache_misses_total - Cache miss counter

Grafana Dashboards

Access Grafana at http://localhost:3001 with:

Username: admin
Password: admin

Import the provided dashboard from config/grafana/dashboards/

🔒 Security

Best Practices

Change Default Credentials: Update all default passwords
Use Strong Secret Keys: Generate secure SECRET_KEY
Enable HTTPS: Use TLS certificates for production
Regular Updates: Keep blocklists updated
Monitor Logs: Check for suspicious activity
Backup Database: Regular PostgreSQL backups
Limit API Access: Use firewall rules
Rate Limiting: Implement rate limits for API endpoints

Role-Based Access Control

super_admin: Full system access, manage all ISPs
isp_admin: Manage their ISP's settings and users
customer: View their ISP's dashboard and queries

🚀 Deployment

Kubernetes Deployment

# Apply Kubernetes manifests
kubectl apply -f k8s/

Production Checklist

📝 Testing

Run Backend Tests

cd backend
pytest tests/ -v

Run Frontend Tests

cd frontend
npm test

🤝 Contributing

Fork the repository
Create a feature branch
Commit your changes
Push to the branch
Create a Pull Request

📄 License

This project is licensed under the MIT License.

🙏 Acknowledgments

Built with FastAPI, React, and PostgreSQL
Blocklists from StevenBlack and AdAway
Charts powered by ApexCharts
Monitoring with Prometheus and Grafana

📞 Support

For support, email: support@example.com

🗺️ Roadmap

Recently Completed ✅

Rate limiting middleware
Webhook integration system
Grafana dashboard configuration
Comprehensive documentation

Name		Name	Last commit message	Last commit date
Latest commit History 38 Commits
.github/workflows		.github/workflows
backend		backend
config		config
docker		docker
docs		docs
frontend		frontend
scripts		scripts
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
DEVELOPMENT_COMPLETE.md		DEVELOPMENT_COMPLETE.md
LICENSE		LICENSE
PROJECT_SUMMARY.md		PROJECT_SUMMARY.md
README.md		README.md
SECURITY.md		SECURITY.md
setup.sh		setup.sh

Folders and files

Latest commit

History

Repository files navigation

DNS Server for ISP

🚀 Features

Core DNS Functionality

Ad-Blocking & Filtering

Real-time Monitoring

Admin Panel & API

Multi-ISP Support

Security & Reliability

Integration & Extensibility

📋 Requirements

🛠️ Quick Start

Using Docker Compose (Recommended)

Manual Setup

Backend Setup

Frontend Setup

📖 API Documentation

Authentication

Register User

Login

DNS Operations

Query DNS

Get Query Logs

Get Statistics

Blocklist Management

Add Domain to Blocklist

Update Blocklists

ISP Management

Create ISP

Webhook Management

Register Webhook

List Webhooks

Rate Limiting

DNS-over-HTTPS (DoH) and DNS-over-TLS (DoT)

Using DoH

Using DoT

🏗️ Architecture

🔧 Configuration

Environment Variables

📊 Monitoring

Prometheus Metrics

Grafana Dashboards

🔒 Security

Best Practices

Role-Based Access Control

🚀 Deployment

Kubernetes Deployment

Production Checklist

📝 Testing

Run Backend Tests

Run Frontend Tests

🤝 Contributing

📄 License

🙏 Acknowledgments

📞 Support

🗺️ Roadmap

Recently Completed ✅

Future Enhancements

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages