IamDNS — DNS Spoofing & ARP Poisoning Suite

⚠️ For authorized penetration testing, CTF challenges, and security research ONLY. Using this tool against systems you do not own or have explicit written permission to test may violate local, national, and international laws. The authors accept no liability.

Overview

IamDNS is a modular, multi-threaded DNS spoofing framework built on top of Scapy. It performs a full ARP-poisoning MITM attack to intercept DNS traffic from a target host, injects crafted DNS responses to redirect specified domains to attacker-controlled IPs, and forwards all other traffic transparently.

Target Host  ──ARP poison──►  Attacker (IamDNS)  ──forward──►  Gateway / Internet
                              ↑  sniffs DNS queries
                              │  injects spoofed answers
                              └  forwards non-matched queries

Features

Feature	Details
ARP Poisoning	Bi-directional ARP cache poisoning (target + gateway)
DNS Interception	BPF-filtered sniff of UDP/53 from the target only
Domain Matching	Exact match + wildcard prefix (`*.example.com`)
Rules File	Load `domain=ip` rules from a plain-text file
Inline Rules	Pass rules directly via `--spoof` CLI flag
Config File	INI-style config file (`--config config.ini`)
Network Scan	ARP sweep of local /24 to enumerate hosts
Live Stats	Periodic dashboard: ARP count, DNS spoofed/forwarded, top domains
pcap Export	Save spoofed packets to `.pcap` for analysis in Wireshark
ARP Restoration	Automatically restores target & gateway ARP tables on exit
IP Forwarding	Auto-enables (and restores) Linux IP forwarding
Signal Handling	Clean `SIGINT`/`SIGTERM` shutdown
Privilege Check	Aborts early if not running as root/Administrator

Requirements

Python 3.8+
Root / Administrator privileges (raw socket access)
Linux (primary), macOS, Windows (see notes)

Python packages

pip install -r requirements.txt

Package	Purpose
`scapy`	Packet crafting, ARP, DNS, sniffing
`netifaces`	Interface IP/gateway discovery
`tabulate`	Pretty-printed scan results

Installation

git clone https://github.com/youruser/IamDNS
cd IamDNS
pip install -r requirements.txt

Usage

Quick start — inline spoof rule

sudo python3 iamDNS.py -i eth0 -t 192.168.1.50 -g 192.168.1.1 \
    --spoof example.com=10.10.10.1

Wildcard domain redirection

sudo python3 iamDNS.py -i eth0 -t 192.168.1.50 \
    --spoof '*.bank.com=192.168.1.99' 'update.corp.local=192.168.1.20'

Load rules from file

sudo python3 iamDNS.py -i eth0 -t 192.168.1.50 --rules dns_rules.txt

Scan network first, then attack

sudo python3 iamDNS.py -i eth0 --scan -t 192.168.1.50 --rules dns_rules.txt -v

Save spoofed packets to pcap

sudo python3 iamDNS.py -i eth0 -t 192.168.1.50 --rules dns_rules.txt \
    --pcap capture.pcap

Use a config file

sudo python3 iamDNS.py --config config.ini

Web Dashboard

For a high-fidelity, interactive experience, IamDNS includes a real-time web dashboard.

Features

Live Activity Charts: Real-time visualization of ARP and DNS spoofing rates.
Interactive Network Scanner: Visual radar for host discovery.
Dynamic Rules Management: Add/remove spoofing rules without restarting.
Packet Log: Integrated terminal-style view of all intercepted traffic.
Emergency Stop: One-click restoration of all network tables.

Quick Start (Dashboard)

chmod +x start_dashboard.sh
./start_dashboard.sh

Then navigate to: http://localhost:5000

CLI Reference

usage: iamDNS [-h] [--config FILE] [-i IFACE] [-t IP] [-g IP]
              [--spoof DOMAIN=IP [DOMAIN=IP ...]] [--rules FILE]
              [--scan] [--arp-interval SECS] [--stats-interval SECS]
              [--no-restore-forward] [-v] [--pcap FILE] [--log-file FILE]

Network:
  -i, --iface IFACE       Network interface (e.g. eth0, wlan0)
  -t, --target IP         Target host IP address
  -g, --gateway IP        Gateway IP (auto-detected if omitted)

DNS Spoofing Rules:
  --spoof DOMAIN=IP       Inline rules: --spoof example.com=1.2.3.4
  --rules FILE            Rules file (one domain=ip per line)

Behaviour:
  --scan                  ARP-scan the /24 subnet before starting
  --arp-interval SECS     ARP re-send interval (default: 2.0)
  --stats-interval SECS   Stats print interval (default: 10.0)
  --no-restore-forward    Skip disabling IP forwarding on exit

Output:
  -v, --verbose           Debug output
  --pcap FILE             Save spoofed packets to pcap
  --log-file FILE         Write log to file

DNS Rules File Format

dns_rules.txt — one rule per line:

# Comments start with '#'
example.com=192.168.1.10
*.corp.local=10.0.0.5
login.phishme.fake=192.168.1.99

Configuration File Format (`config.ini`)

[iamDNS]
iface          = eth0
target         = 192.168.1.50
gateway        = 192.168.1.1
rules          = dns_rules.txt
arp_interval   = 2.0
stats_interval = 10.0
verbose        = false
scan           = false

Live Statistics Output

Every --stats-interval seconds (default: 10 s), IamDNS prints a dashboard:

── IamDNS Live Stats ──────────────────────────────
  Uptime        : 42.3s
  ARP packets   : 84
  DNS captured  : 17
  DNS spoofed   : 12
  DNS forwarded : 5
  Top spoofed domains:
    example.com                                12 hits
───────────────────────────────────────────────────

How It Works

1. ARP Poisoning

IamDNS resolves the MAC addresses of both the target and the gateway via ARP. It then repeatedly sends forged ARP replies:

To target: "the gateway's IP is at my MAC"
To gateway: "the target's IP is at my MAC"

This routes all target↔internet traffic through the attacker.

2. DNS Interception

Scapy's sniff() with a BPF filter (src host <target> and udp port 53) captures all DNS queries leaving the target.

3. Domain Matching

Each queried FQDN is tested against the configured rules:

Exact match: example.com
Wildcard prefix: *.example.com catches sub.example.com, www.example.com, etc.

4. Spoofed Response Injection

For matched queries, a crafted DNS A-record response is injected:

qr=1 (response), aa=1 (authoritative), TTL=300
Source IP/MAC spoofed to appear as the target's real DNS server

5. Transparent Forwarding

Non-matched DNS queries are counted and forwarded via the normal IP-forwarding path (enabled automatically on Linux).

6. Graceful Shutdown

On Ctrl-C or SIGTERM:

ARP poisoner stops → sends 5× genuine ARP replies to restore tables
DNS spoofer stops → writes any buffered pcap
IP forwarding is disabled (restored)
Final statistics printed

Platform Notes

Platform	Status	Notes
Linux	✅ Full support	Auto IP-forwarding, BPF, raw sockets
macOS	⚠️ Partial	Manual `sysctl -w net.inet.ip.forwarding=1` required
Windows	⚠️ Limited	Npcap required; IP forwarding not managed

Dependencies In Detail

Scapy

The core packet engine. Used for:

srp() — ARP resolution and network scanning
sendp() — Layer-2 packet injection
sniff() — Live packet capture with BPF filters
ARP, Ether, IP, UDP, DNS, DNSQR, DNSRR — Packet layers

netifaces

Used to query interface addresses and default gateway without shelling out to ip route.

tabulate

Optional — renders the ARP scan results as a formatted table. If not installed, a plain-text fallback is used.

Security Considerations

Privilege requirements are enforced at startup via os.geteuid().
Input validation is applied to all IPs (via ipaddress), interfaces, domains, and file paths before use.
ARP restoration guarantees the network is left in a clean state even if the process crashes (via SIGTERM handler).
IP forwarding is only enabled while the tool runs and is disabled on exit (unless --no-restore-forward).

License

MIT — see LICENSE.

Name		Name	Last commit message	Last commit date
static		static
templates		templates
.gitignore		.gitignore
README.md		README.md
config.ini.example		config.ini.example
database.py		database.py
dns_rules.txt		dns_rules.txt
iamDNS.py		iamDNS.py
phishing_simulation.rules		phishing_simulation.rules
portal.py		portal.py
recon.py		recon.py
requirements.txt		requirements.txt
server.py		server.py
signatures.json		signatures.json
start_dashboard.sh		start_dashboard.sh
striker.py		striker.py

Latest commit

History

Folders and files

Repository files navigation

IamDNS — DNS Spoofing & ARP Poisoning Suite

Overview

Features

Requirements

Python packages

Installation

Usage

Quick start — inline spoof rule

Wildcard domain redirection

Load rules from file

Scan network first, then attack

Save spoofed packets to pcap

Use a config file

Web Dashboard

Features

Quick Start (Dashboard)

CLI Reference

DNS Rules File Format

Configuration File Format (config.ini)

Live Statistics Output

How It Works

1. ARP Poisoning

2. DNS Interception

3. Domain Matching

4. Spoofed Response Injection

5. Transparent Forwarding

6. Graceful Shutdown

Platform Notes

Dependencies In Detail

Scapy

netifaces

tabulate

Security Considerations

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Configuration File Format (`config.ini`)