DNS Guard - Domain Threat Intelligence Platform

May 1, 2025

DNS Guard

Domain threat intelligence platform — analyze any domain for DNS abuse, misconfigurations, phishing, typosquatting, and security threats. Built as a Final Year Project.

Project Repository

https://github.com/Trident09/DNS-Guard_FYP_SEM_X

Features

Architecture

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Frontend  │────▶│   Backend   │────▶│  AI Service │
│  Next.js 14 │     │  FastAPI    │     │  FastAPI    │
│  Port 3000  │     │  Port 8000  │     │  Port 8001  │
└─────────────┘     └──────┬──────┘     └─────────────┘
                           │
              ┌────────────┼────────────┐
              ▼            ▼            ▼
         PostgreSQL      Redis       Qdrant
          Port 5432    Port 6379   Port 6333

• Frontend — Next.js 14 App Router, Tailwind CSS, Recharts, Lucide icons
• Backend — FastAPI, Celery workers, ReportLab PDF generation
• AI Service — FastAPI, scikit-learn ensemble model, Groq API (LLaMA 3.1)
• PostgreSQL — persistent storage
• Redis — Celery task queue / broker
• Qdrant — vector database for RAG (chatbot knowledge base)

Quick Start

Prerequisites

• Docker & Docker Compose
• (Optional) Groq API key for AI chatbot (free tier)

1. Clone & configure

git clone <repo-url>
cd FYP
cp .env.example .env
# Edit .env if needed (defaults work out of the box)

2. Start everything

docker compose up --build -d

3. Open the app

http://localhost:3000

4. Stop

docker compose down

Environment Variables

See .env.example for all variables. Key ones:

Project Structure

FYP/
├── frontend/               # Next.js 14 app
│   ├── app/
│   │   ├── page.tsx                    # Home / search page
│   │   ├── layout.tsx                  # Root layout + SEO metadata
│   │   ├── analyze/[domain]/
│   │   │   ├── page.tsx                # Analysis results page
│   │   │   └── layout.tsx              # Per-domain SEO metadata
│   │   └── api/
│   │       ├── analyze/route.ts        # Proxy → backend /analyze
│   │       ├── chat/route.ts           # Proxy → backend /chat
│   │       └── report/[domain]/pdf/    # Proxy → backend PDF
│   └── components/
│       ├── ThreatScoreCard.tsx         # Radial gauge
│       ├── RiskSummary.tsx             # Recommendations panel
│       ├── FeatureImportanceChart.tsx  # SHAP-style bar chart
│       ├── GeoMap.tsx                  # SVG world map
│       ├── WhoisDiff.tsx               # WHOIS change detection
│       ├── DnssecBadge.tsx             # DNSSEC status badge
│       ├── ThemeToggle.tsx             # Dark/light mode
│       ├── ChatBot.tsx                 # AI assistant
│       └── ...                         # Other data cards
│
├── backend/                # FastAPI backend
│   └── app/
│       ├── api/
│       │   ├── analyze.py              # Main analysis endpoint
│       │   ├── chat.py                 # Chat proxy to AI service
│       │   └── reports.py             # PDF download endpoint
│       ├── services/
│       │   ├── dns_resolver.py         # DNS + DNSSEC resolution
│       │   ├── whois_lookup.py         # WHOIS data
│       │   ├── cert_transparency.py    # crt.sh CT log queries
│       │   ├── passive_dns.py          # Historical DNS records
│       │   ├── typosquat.py            # Brand similarity detection
│       │   ├── subdomain_enum.py       # Subdomain discovery
│       │   ├── reverse_ip.py           # Reverse IP lookup
│       │   ├── threat_intel.py         # Spamhaus + PhishTank
│       │   ├── geo_ip.py               # IP geolocation (ip-api.com)
│       │   └── pdf_report.py           # ReportLab PDF generation
│       ├── workers/tasks.py            # Celery async tasks
│       └── config.py                   # Pydantic settings
│
├── ai/                     # AI / ML service
│   └── app/
│       ├── api/
│       │   ├── score.py                # Threat scoring endpoint
│       │   └── chat.py                 # Chatbot endpoint (Groq API + fallback)
│       ├── features/extractor.py       # 40-feature vector extraction
│       └── models/
│           ├── ensemble.py             # Ensemble model (RF + rules)
│           └── mlp.py                  # MLP neural network
│
├── scripts/
│   └── update_feeds.py                 # Threat feed updater
├── data/
│   ├── raw/                            # Raw feed data
│   ├── threat_feeds/                   # Processed threat feeds
│   └── knowledge_base/                 # Qdrant RAG documents
├── docker-compose.yml
├── .env.example
└── .gitignore

API Reference

See docs/API.md for full endpoint documentation.

Quick reference

ML Model

The threat scoring model uses a 40-feature vector extracted from the domain name and DNS records:

• Lexical features (12) — entropy, length, digit ratio, brand keywords, phishing keywords, TLD risk
• DNS record features (14) — A/MX/NS/TXT presence, SPF/DKIM/DMARC, fast-flux indicators
• DNSSEC features (3) — DNSKEY, RRSIG, DS presence
• Composite features (7) — no DNSSEC, MX without SPF/DMARC, high entropy, brand in subdomain

The ensemble combines rule-based scoring with an MLP neural network. Feature importance is returned with each score for explainability.

Chatbot

The AI assistant uses the Groq API (LLaMA 3.1 8B Instant) when a GROQ_API_KEY is configured. Without a key, it falls back to a comprehensive rule-based engine covering:

• DNSSEC configuration
• SPF / DKIM / DMARC email security
• SSL/TLS certificates
• Subdomain security
• Threat intelligence & blocklists
• Typosquatting & phishing
• Abuse reporting resources

Development

Run frontend locally

cd frontend
npm install
npm run dev        # http://localhost:3000

Run backend locally

cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

Run AI service locally

cd ai
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8001

Update threat feeds

python scripts/update_feeds.py

License

Academic project — Final Year Project. Not for production use without security hardening.