142 lines
5.1 KiB
Markdown
142 lines
5.1 KiB
Markdown
# DNS Lookup Tool - Project Overview
|
|
|
|
## What This Project Does
|
|
|
|
This is a professional DNS reconnaissance tool built as a command-line application. It performs DNS queries, reverse lookups, resolution tracing, and WHOIS information gathering. The tool is designed for network analysis, security research, and learning how DNS infrastructure works at a technical level.
|
|
|
|
Unlike simple `dig` or `nslookup` wrappers, this project implements concurrent async DNS queries, resolution path tracing from root servers, and structured output formatting suitable for both human analysis and automated processing.
|
|
|
|
## Core Capabilities
|
|
|
|
**DNS Record Queries** (`dnslookup/cli.py:112-167`)
|
|
- Query multiple record types simultaneously (A, AAAA, MX, NS, TXT, CNAME, SOA)
|
|
- Custom DNS server selection
|
|
- Configurable timeouts
|
|
- JSON output for parsing
|
|
|
|
**Reverse DNS Lookups** (`dnslookup/cli.py:170-216`)
|
|
- IPv4 and IPv6 PTR record resolution
|
|
- Useful for identifying server ownership and detecting hosting patterns
|
|
|
|
**DNS Trace** (`dnslookup/cli.py:219-263`)
|
|
- Traces complete resolution path from root servers through TLD to authoritative nameservers
|
|
- Visualizes DNS delegation hierarchy
|
|
- Shows which servers are queried at each step
|
|
|
|
**Batch Operations** (`dnslookup/cli.py:266-350`)
|
|
- Process hundreds of domains from a file
|
|
- Concurrent async queries for speed
|
|
- Results export to JSON
|
|
|
|
**WHOIS Lookups** (`dnslookup/cli.py:353-393`)
|
|
- Domain registration details
|
|
- Registrar information, creation dates, expiration dates
|
|
- Name server information
|
|
|
|
## Why This Matters for Security
|
|
|
|
DNS is a fundamental attack surface. This tool teaches:
|
|
|
|
1. **Reconnaissance Techniques**: How attackers enumerate infrastructure
|
|
2. **DNS Architecture**: Understanding delegation makes spoofing and hijacking clearer
|
|
3. **Information Leakage**: What data DNS exposes about your infrastructure
|
|
4. **Attack Detection**: Recognizing unusual DNS patterns
|
|
|
|
Real incidents this knowledge applies to:
|
|
- **Dyn DDoS Attack (2016)**: Massive DNS infrastructure disruption affected Twitter, Netflix, Reddit
|
|
- **Sea Turtle Campaign (2019)**: Nation-state DNS hijacking targeting government agencies (MITRE ATT&CK: T1584.002)
|
|
- **DNSpionage (2018)**: DNS hijacking for credential harvesting
|
|
|
|
## Technical Architecture
|
|
```
|
|
User Command
|
|
↓
|
|
cli.py (Typer interface)
|
|
↓
|
|
resolver.py (dnspython async wrapper)
|
|
↓
|
|
DNS Protocol Operations
|
|
↓
|
|
output.py (Rich formatting)
|
|
↓
|
|
Terminal Display
|
|
```
|
|
|
|
The architecture separates concerns cleanly:
|
|
- **CLI layer**: User interaction, argument parsing (`cli.py`)
|
|
- **Resolution layer**: DNS protocol operations (`resolver.py`)
|
|
- **Presentation layer**: Output formatting (`output.py`)
|
|
|
|
## Learning Path
|
|
|
|
This project teaches:
|
|
1. **DNS Protocol Mechanics**: How queries actually work at the packet level
|
|
2. **Async Python**: Using `asyncio` for concurrent network operations
|
|
3. **CLI Design**: Building professional command-line tools with Typer
|
|
4. **Error Handling**: Network timeouts, NXDOMAIN, SERVFAIL responses
|
|
5. **Data Structures**: Modeling DNS records cleanly
|
|
6. **Security Mindset**: Thinking like both defender and attacker
|
|
|
|
## Quick Start Examples
|
|
```bash
|
|
# Basic query - all record types
|
|
dnslookup query example.com
|
|
|
|
# Specific records with custom DNS server
|
|
dnslookup query example.com --type A,MX --server 8.8.8.8
|
|
|
|
# Trace resolution path (shows DNS hierarchy)
|
|
dnslookup trace example.com
|
|
|
|
# Reverse lookup to find hostname
|
|
dnslookup reverse 8.8.8.8
|
|
|
|
# Batch reconnaissance
|
|
echo "example.com" > domains.txt
|
|
echo "example.org" >> domains.txt
|
|
dnslookup batch domains.txt --output results.json
|
|
```
|
|
|
|
## Key Files to Understand
|
|
|
|
| File | Purpose | Lines of Code |
|
|
|------|---------|---------------|
|
|
| `resolver.py` | Core DNS logic | ~400 |
|
|
| `cli.py` | Command interface | ~400 |
|
|
| `output.py` | Terminal formatting | ~400 |
|
|
| `whois_lookup.py` | WHOIS operations | ~200 |
|
|
|
|
## Security Features
|
|
|
|
- **No caching**: Every query is fresh (prevents stale data)
|
|
- **Custom nameserver support**: Test against specific DNS servers
|
|
- **Timeout controls**: Prevents hanging on unresponsive servers
|
|
- **Error transparency**: Shows exactly what failed and why
|
|
|
|
## What You'll Build On
|
|
|
|
After mastering this project, you'll be ready for:
|
|
- DNS tunnel detection systems
|
|
- Custom DNS servers with security monitoring
|
|
- Automated subdomain enumeration tools
|
|
- DNS-based threat intelligence gathering
|
|
|
|
## Real World Applications
|
|
|
|
This exact functionality is used in:
|
|
- **Penetration Testing**: Initial reconnaissance phase
|
|
- **Incident Response**: Investigating suspicious domains
|
|
- **Threat Hunting**: Tracking C2 infrastructure
|
|
- **Infrastructure Monitoring**: Validating DNS configurations
|
|
- **Security Research**: Analyzing DNS patterns
|
|
|
|
## Attack Vectors This Tool Helps Understand
|
|
|
|
1. **DNS Reconnaissance** (MITRE T1590.002): Information gathering attackers perform
|
|
2. **DNS Tunneling**: Exfiltrating data through DNS queries
|
|
3. **DNS Cache Poisoning**: How spoofed responses could redirect traffic
|
|
4. **Subdomain Enumeration**: Finding hidden infrastructure
|
|
5. **DNS Amplification**: How DNS can be weaponized for DDoS
|
|
|
|
Next, dive into `01-CONCEPTS.md` to understand the DNS protocol fundamentals this tool leverages.
|