dns-security-mcp 0.1.0

package/README.md

@@ -0,0 +1,723 @@
+<p align="center">
+  <strong>English</strong> |
+  <a href="docs/README.zh.md">简体中文</a> |
+  <a href="docs/README.zh-TW.md">繁體中文</a> |
+  <a href="docs/README.ko.md">한국어</a> |
+  <a href="docs/README.de.md">Deutsch</a> |
+  <a href="docs/README.es.md">Español</a> |
+  <a href="docs/README.fr.md">Français</a> |
+  <a href="docs/README.it.md">Italiano</a> |
+  <a href="docs/README.da.md">Dansk</a> |
+  <a href="docs/README.ja.md">日本語</a> |
+  <a href="docs/README.pl.md">Polski</a> |
+  <a href="docs/README.ru.md">Русский</a> |
+  <a href="docs/README.bs.md">Bosanski</a> |
+  <a href="docs/README.ar.md">العربية</a> |
+  <a href="docs/README.no.md">Norsk</a> |
+  <a href="docs/README.pt-BR.md">Português (Brasil)</a> |
+  <a href="docs/README.th.md">ไทย</a> |
+  <a href="docs/README.tr.md">Türkçe</a> |
+  <a href="docs/README.uk.md">Українська</a> |
+  <a href="docs/README.bn.md">বাংলা</a> |
+  <a href="docs/README.el.md">Ελληνικά</a> |
+  <a href="docs/README.vi.md">Tiếng Việt</a> |
+  <a href="docs/README.hi.md">हिन्दी</a>
+</p>
+
+<p align="center">
+  <br>
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/badchars/dns-security-mcp/main/docs/banner-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/badchars/dns-security-mcp/main/docs/banner-light.svg">
+    <img alt="dns-security-mcp" src="https://raw.githubusercontent.com/badchars/dns-security-mcp/main/docs/banner-dark.svg" width="700">
+  </picture>
+</p>
+
+<h3 align="center">The most comprehensive DNS security toolkit for AI agents.</h3>
+
+<p align="center">
+  DNSSEC validation, subdomain takeover detection, DNS tunneling analysis, typosquatting, email security audit, certificate transparency monitoring, blocklist checking, infrastructure hardening &mdash; unified into a single MCP server.<br>
+  <b>103 tools. 13 categories. 3 dependencies. 100% local.</b> No external API calls required for core functionality.
+</p>
+
+<br>
+
+<p align="center">
+  <a href="#the-problem">The Problem</a> &bull;
+  <a href="#how-its-different">How It's Different</a> &bull;
+  <a href="#quick-start">Quick Start</a> &bull;
+  <a href="#what-the-ai-can-do">What The AI Can Do</a> &bull;
+  <a href="#tools-reference-103-tools">Tools (103)</a> &bull;
+  <a href="#configuration">Configuration</a> &bull;
+  <a href="#cli-usage">CLI Usage</a> &bull;
+  <a href="#architecture">Architecture</a> &bull;
+  <a href="CONTRIBUTING.md">Contributing</a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/dns-security-mcp"><img src="https://img.shields.io/npm/v/dns-security-mcp.svg" alt="npm"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
+  <img src="https://img.shields.io/badge/tools-103-ef4444" alt="103 Tools">
+  <img src="https://img.shields.io/badge/TypeScript-strict-3178c6" alt="TypeScript">
+  <img src="https://img.shields.io/badge/protocol-MCP-8b5cf6" alt="MCP">
+  <img src="https://img.shields.io/badge/dependencies-3-22c55e" alt="3 Dependencies">
+  <img src="https://img.shields.io/badge/API%20keys-optional-f59e0b" alt="API Keys Optional">
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/badchars/dns-security-mcp/main/docs/demo.gif" alt="dns-security-mcp demo" width="800">
+</p>
+
+---
+
+## The Problem
+
+DNS is the foundation of every internet service, and it is the most overlooked attack surface. Misconfigured DNSSEC, dangling CNAME records, missing SPF/DKIM/DMARC, DNS tunneling, typosquatting domains, expiring certificates, open resolvers &mdash; the attack vectors are everywhere, but the tools to detect them are fragmented across dozens of specialized utilities, each with its own syntax, its own output format, and its own learning curve.
+
+```
+Traditional DNS security workflow:
+  check DNS records              ->  dig / nslookup (manual parsing)
+  validate DNSSEC                ->  dnsviz.net web UI + delv CLI
+  audit email security           ->  mxtoolbox.com + dmarcian.com (2 web UIs)
+  detect subdomain takeover      ->  subjack / nuclei + manual CNAME review
+  find DNS tunneling             ->  Wireshark pcap + custom scripts
+  monitor certificates           ->  crt.sh web UI + certspotter
+  check typosquatting            ->  dnstwist CLI + manual review
+  scan blocklists                ->  multirbl.valli.org + spamhaus lookup
+  test infrastructure            ->  multiple CLI tools + web checkers
+  generate compliance report     ->  copy-paste everything into a doc
+  ─────────────────────────────────
+  Total: 8+ tools, 5+ web UIs, hours of manual correlation
+```
+
+**dns-security-mcp** gives your AI agent 103 tools across 13 categories via the [Model Context Protocol](https://modelcontextprotocol.io). The agent performs DNS reconnaissance, validates DNSSEC chains, audits email authentication, detects hijacking risks, identifies tunneling, monitors certificates, catches typosquatting, checks blocklists, hardens infrastructure, and generates compliance reports &mdash; all in a single conversation, all from local DNS queries.
+
+```
+With dns-security-mcp:
+  You: "Run a full security audit on example.com"
+
+  Agent: -> dns_lookup: 14 record types resolved, 3 nameservers found
+         -> dnssec_full_audit: DNSSEC signed, chain valid, RRSIG expires in 12 days
+         -> email_full_audit: SPF present (strict), DKIM found (3 selectors),
+            DMARC p=reject — excellent email security
+         -> hijack_subdomain_takeover: 2 dangling CNAMEs detected (staging, old-api)
+         -> ct_unauthorized_detect: 1 certificate from unauthorized CA found
+         -> bl_domain_score: Risk score 15/100 — clean
+         -> infra_ns_diversity: 4 NS across 3 ASNs — good diversity
+         -> report_generate: Full SARIF report generated
+
+         "example.com has strong DNS and email security posture.
+          Two critical findings: staging.example.com and old-api.example.com
+          have dangling CNAME records pointing to decommissioned services —
+          immediate subdomain takeover risk. One certificate from a non-
+          authorized CA (Let's Debug) was found in CT logs. DNSSEC RRSIG
+          expires in 12 days — schedule key rotation."
+```
+
+---
+
+## How It's Different
+
+Most DNS tools give you raw records. dns-security-mcp gives your AI agent the ability to **reason across the entire DNS attack surface simultaneously**.
+
+<table>
+<thead>
+<tr>
+<th></th>
+<th>Traditional Approach</th>
+<th>dns-security-mcp</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><b>Interface</b></td>
+<td>8+ CLI tools, 5+ web UIs, manual parsing</td>
+<td>MCP &mdash; AI agent calls tools conversationally</td>
+</tr>
+<tr>
+<td><b>Coverage</b></td>
+<td>One category at a time</td>
+<td>13 categories, 103 tools queried in parallel</td>
+</tr>
+<tr>
+<td><b>DNSSEC</b></td>
+<td>dnsviz.net for visualization, delv for validation</td>
+<td>Agent validates full chain of trust, checks DS/DNSKEY/RRSIG/NSEC, audits algorithms, detects key rollover</td>
+</tr>
+<tr>
+<td><b>Email security</b></td>
+<td>mxtoolbox + dmarcian + manual checks</td>
+<td>Agent checks SPF + DKIM (12 selectors) + DMARC + BIMI + MTA-STS + DANE + PTR + spoofability score</td>
+</tr>
+<tr>
+<td><b>Hijacking</b></td>
+<td>subjack for CNAMEs, manual NS/MX review</td>
+<td>Agent checks dangling CNAME + NS + MX, delegation chain, DNS rebinding, registrar security, BGP impact</td>
+</tr>
+<tr>
+<td><b>Tunneling</b></td>
+<td>Wireshark + custom scripts</td>
+<td>Agent runs entropy analysis, length checks, TXT payload detection, tool signatures (iodine, dnscat2, Cobalt Strike), covert channel timing analysis</td>
+</tr>
+<tr>
+<td><b>API keys</b></td>
+<td>Various, often required</td>
+<td>100% local core &mdash; API keys optional for enrichment only</td>
+</tr>
+<tr>
+<td><b>Dependencies</b></td>
+<td>Dozens of tools to install</td>
+<td><code>npx dns-security-mcp</code> &mdash; 3 dependencies, zero config</td>
+</tr>
+<tr>
+<td><b>Output</b></td>
+<td>Raw text, manual correlation</td>
+<td>JSON, Markdown, or SARIF reports &mdash; AI correlates findings automatically</td>
+</tr>
+</tbody>
+</table>
+
+---
+
+## Quick Start
+
+### Option 1: npx (no install)
+
+```bash
+npx dns-security-mcp
+```
+
+All 103 tools work immediately. No API keys required for core functionality &mdash; everything runs via local DNS queries.
+
+### Option 2: bunx (faster)
+
+```bash
+bunx dns-security-mcp
+```
+
+### Option 3: Clone
+
+```bash
+git clone https://github.com/badchars/dns-security-mcp.git
+cd dns-security-mcp
+bun install
+```
+
+### Connect to your AI agent
+
+<details open>
+<summary><b>Claude Code</b></summary>
+
+```bash
+# With npx
+claude mcp add dns-security-mcp -- npx dns-security-mcp
+
+# With local clone
+claude mcp add dns-security-mcp -- bun run /path/to/dns-security-mcp/src/index.ts
+```
+
+</details>
+
+<details>
+<summary><b>Claude Desktop</b></summary>
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "dns-security": {
+      "command": "npx",
+      "args": ["-y", "dns-security-mcp"],
+      "env": {
+        "SECURITYTRAILS_API_KEY": "optional",
+        "VIRUSTOTAL_API_KEY": "optional",
+        "SAFEBROWSING_API_KEY": "optional",
+        "DNS_RESOLVER": "optional"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>Cursor / Windsurf / other MCP clients</b></summary>
+
+Same JSON config format. Point the command to `npx dns-security-mcp` or your local installation path.
+
+</details>
+
+### Start querying
+
+```
+You: "Check if example.com has any DNS security issues"
+```
+
+That's it. The agent runs reconnaissance, validates DNSSEC, checks email security, scans for hijacking risks, and more &mdash; automatically.
+
+---
+
+## What The AI Can Do
+
+### Full Security Audit
+
+```
+You: "Run a comprehensive DNS security audit on target.com"
+
+Agent: -> report_full_audit {domain: "target.com"}
+       -> "Complete DNS security audit for target.com:
+          CRITICAL: 2 dangling CNAMEs (subdomain takeover risk)
+          HIGH: DNSSEC not enabled — vulnerable to cache poisoning
+          HIGH: DMARC policy is 'none' — email spoofing possible
+          MEDIUM: MTA-STS not configured
+          LOW: 2 NS servers in same /24 subnet
+          Score: 42/100 — significant improvements needed.
+          Full SARIF report generated with 8 findings."
+```
+
+### Email Spoofing Assessment
+
+```
+You: "Can someone spoof emails from our domain bigcorp.com?"
+
+Agent: -> email_spoofability_score {domain: "bigcorp.com"}
+       -> email_check_spf {domain: "bigcorp.com"}
+       -> email_check_dmarc {domain: "bigcorp.com"}
+       -> email_check_dkim {domain: "bigcorp.com"}
+       -> "Spoofability score: 72/100 (HIGH RISK)
+          SPF: Present but uses ~all (softfail) instead of -all
+          DKIM: Only 1 selector found (google), missing others
+          DMARC: Policy is p=none with no rua reporting
+          Recommendation: Change SPF to -all, set DMARC p=reject,
+          add DKIM for all sending services."
+```
+
+### Subdomain Takeover Hunt
+
+```
+You: "Check all subdomains of startup.io for takeover risk"
+
+Agent: -> hijack_subdomain_takeover {domain: "startup.io", use_ct: true}
+       -> hijack_dangling_cname {domain: "startup.io"}
+       -> hijack_dangling_ns {domain: "startup.io"}
+       -> hijack_dangling_mx {domain: "startup.io"}
+       -> "Found 4 subdomains at risk:
+          CRITICAL: docs.startup.io -> CNAME to ReadTheDocs (unclaimed)
+          CRITICAL: staging.startup.io -> CNAME to Heroku (app deleted)
+          HIGH: old-blog.startup.io -> CNAME to Ghost.io (expired)
+          MEDIUM: mail2.startup.io -> MX points to decommissioned server
+          All 4 can be claimed by an attacker. Immediate action required."
+```
+
+### DNS Tunneling Detection
+
+```
+You: "Analyze these DNS queries for tunneling: [list of suspicious queries]"
+
+Agent: -> tunnel_full_scan {queries: [...], timestamps: [...]}
+       -> "Tunneling probability: 94/100 (VERY HIGH)
+          Entropy: 4.8 bits/char avg (normal is <3.5)
+          Query length: 180+ chars avg (normal is <50)
+          Tool signature: Matches iodine encoding pattern
+          Covert channel: Beaconing detected at 30s intervals
+          TXT payloads: Base64-encoded data in responses
+          Verdict: Active DNS tunnel, likely iodine-based C2."
+```
+
+### Typosquatting Detection
+
+```
+You: "Find typosquatting domains targeting mybank.com"
+
+Agent: -> typo_full_scan {domain: "mybank.com", check_registered: true}
+       -> "Generated 847 typosquat variants across 7 techniques.
+          42 are registered and resolving:
+          - myb4nk.com (homoglyph) -> resolves to 185.x.x.x (suspicious)
+          - mybank.co (TLD variation) -> parked page
+          - my-bank.com (combosquat) -> phishing page detected
+          - mybanк.com (IDN/Cyrillic 'к') -> redirect to credential harvester
+          HIGH RISK: 4 domains actively serving phishing content.
+          Recommend takedown requests for mybanк.com and my-bank.com."
+```
+
+### Certificate Transparency Monitoring
+
+```
+You: "Monitor certificates issued for our domain in the last 7 days"
+
+Agent: -> ct_monitor {domain: "company.com", days: 7}
+       -> ct_unauthorized_detect {domain: "company.com"}
+       -> ct_expiry_monitor {domain: "company.com", days_threshold: 30}
+       -> "Certificate activity for company.com (last 7 days):
+          3 new certificates issued:
+          - *.company.com by Let's Encrypt (expected)
+          - api.company.com by DigiCert (expected)
+          - company.com by GoGetSSL (UNAUTHORIZED — not in CAA)
+          Expiring soon: 2 certificates expire within 30 days.
+          Action: Investigate the GoGetSSL certificate — your CAA
+          record only allows Let's Encrypt and DigiCert."
+```
+
+---
+
+## Tools Reference (103 tools)
+
+### Category Overview
+
+| Category | Tools | Description |
+|----------|-------|-------------|
+| :mag: [DNS Reconnaissance](#-dns-reconnaissance-12) | 12 | Record lookup, zone transfer, cache snooping, NSEC walking, propagation, split-horizon |
+| :shield: [DNSSEC Validation](#-dnssec-validation-8) | 8 | Chain of trust, DS/DNSKEY/RRSIG/NSEC checks, algorithm audit, key rollover |
+| :email: [Email Security](#-email-security-9) | 9 | SPF, DKIM, DMARC, BIMI, MTA-STS, DANE, PTR, spoofability scoring |
+| :warning: [Hijacking & Takeover](#-hijacking--takeover-9) | 9 | Dangling CNAME/NS/MX, delegation chain, DNS rebinding, registrar security, BGP impact |
+| :hole: [DNS Tunneling Detection](#-dns-tunneling-detection-7) | 7 | Entropy analysis, length checks, TXT payloads, tool signatures, covert channels |
+| :lock: [Certificate Transparency](#-certificate-transparency-7) | 7 | CT log search, wildcard audit, unauthorized CA detection, expiry monitoring |
+| :globe_with_meridians: [Domain Intelligence](#-domain-intelligence-10) | 10 | WHOIS/RDAP, domain age, history, DGA detection, reputation, hosting info |
+| :dart: [Typosquatting & Brand Protection](#-typosquatting--brand-protection-8) | 8 | Homoglyph, bitsquat, TLD variation, combosquat, soundsquat, IDN homograph, keyboard proximity |
+| :no_entry: [Blocklist & Reputation](#-blocklist--reputation-6) | 6 | DNSBL/RBL, SURBL, phishing lists, malware lists, fast-flux detection, risk scoring |
+| :gear: [Infrastructure Security](#-infrastructure-security-9) | 9 | Open resolver, amplification, rate limiting, software CVE, EDNS, TCP fallback, DNS cookies |
+| :detective: [DNS Privacy](#-dns-privacy-6) | 6 | DoH, DoT, DoQ testing, ECS leak detection, resolver audit, DNS leak test |
+| :biohazard: [Passive DNS & Threat Intel](#-passive-dns--threat-intel-7) | 7 | Passive DNS, co-hosting, IP-to-domains, malicious feeds, C2 detection, sinkhole check |
+| :page_facing_up: [Compliance & Reporting](#-compliance--reporting-5) | 5 | RFC compliance, CIS benchmarks, full audit, SARIF/Markdown/JSON reports, baseline comparison |
+
+---
+
+<details open>
+<summary><h3>:mag: DNS Reconnaissance (12)</h3></summary>
+
+| Tool | Description |
+|------|-------------|
+| `dns_lookup` | Resolve all DNS record types for a domain in parallel |
+| `dns_reverse` | Perform PTR (reverse DNS) lookup with Forward Confirmed rDNS (FCrDNS) validation |
+| `dns_zone_transfer` | Attempt AXFR (full zone transfer) against a domain's nameserver via TCP |
+| `dns_subdomain_enum` | Enumerate subdomains using passive CT (Certificate Transparency) log lookups via crt.sh |
+| `dns_cache_snoop` | Perform DNS cache snooping by sending non-recursive query (RD=0) to a nameserver |
+| `dns_nsec_walk` | Attempt DNSSEC NSEC zone walking to enumerate domain names in a signed zone |
+| `dns_wildcard_detect` | Detect wildcard DNS configurations by resolving random non-existent subdomains |
+| `dns_server_fingerprint` | Fingerprint a DNS server by querying CHAOS class TXT records (version.bind) |
+| `dns_recursive_check` | Test whether a nameserver is an open recursive resolver (RD=1 for external domain) |
+| `dns_propagation` | Check DNS propagation by querying 20+ globally distributed public resolvers |
+| `dns_split_horizon` | Detect split-horizon (split-brain) DNS by comparing internal vs external resolver responses |
+| `dns_ttl_analysis` | Analyze DNS TTL values across all record types for a domain |
+
+</details>
+
+<details>
+<summary><h3>:shield: DNSSEC Validation (8)</h3></summary>
+
+| Tool | Description |
+|------|-------------|
+| `dnssec_validate` | Full DNSSEC chain of trust validation from root to TLD to domain |
+| `dnssec_check_ds` | Check DS (Delegation Signer) records for a domain |
+| `dnssec_check_dnskey` | List all DNSKEY records for a domain |
+| `dnssec_check_rrsig` | Check RRSIG (Resource Record Signature) records and expiry |
+| `dnssec_check_nsec` | Check NSEC/NSEC3 records for a domain |
+| `dnssec_algorithm_audit` | Inventory all DNSSEC algorithms used in DS, DNSKEY, and RRSIG records |
+| `dnssec_key_rollover` | Check for DNSSEC key rollover indicators |
+| `dnssec_full_audit` | Comprehensive DNSSEC audit: all 7 checks combined with unified report |
+
+</details>
+
+<details>
+<summary><h3>:email: Email Security (9)</h3></summary>
+
+| Tool | Description |
+|------|-------------|
+| `email_check_spf` | Check SPF (Sender Policy Framework) record with mechanism analysis |
+| `email_check_dkim` | Check DKIM records by probing common selectors (google, selector1, dkim, etc.) |
+| `email_check_dmarc` | Check DMARC record with policy analysis and reporting configuration |
+| `email_check_bimi` | Check BIMI (Brand Indicators for Message Identification) record |
+| `email_check_mta_sts` | Check MTA-STS (Mail Transfer Agent Strict Transport Security) configuration |
+| `email_check_dane` | Check DANE/TLSA records for a domain's MX hosts |
+| `email_check_ptr` | Check PTR and FCrDNS (Forward-Confirmed reverse DNS) for MX hosts |
+| `email_spoofability_score` | Calculate email spoofability score (0-100) based on SPF, DKIM, DMARC |
+| `email_full_audit` | Comprehensive email security audit across all protocols |
+
+</details>
+
+<details>
+<summary><h3>:warning: Hijacking & Takeover (9)</h3></summary>
+
+| Tool | Description |
+|------|-------------|
+| `hijack_dangling_cname` | Detect dangling CNAME records that could allow subdomain takeover |
+| `hijack_dangling_ns` | Detect dangling NS records that could allow full domain takeover |
+| `hijack_dangling_mx` | Detect dangling MX records that could allow email hijacking |
+| `hijack_ns_delegation` | Walk the DNS delegation chain and verify consistency |
+| `hijack_dns_rebinding` | Detect DNS rebinding candidates via IP changes combined with low TTL |
+| `hijack_registrar_security` | Check domain registrar security posture via RDAP |
+| `hijack_change_monitor` | Monitor DNS record changes by comparing against a stored baseline |
+| `hijack_subdomain_takeover` | Full subdomain takeover scan using CT logs and CNAME resolution |
+| `hijack_bgp_impact` | Assess BGP-level impact of domain hijacking via Team Cymru ASN lookup |
+
+</details>
+
+<details>
+<summary><h3>:hole: DNS Tunneling Detection (7)</h3></summary>
+
+| Tool | Description |
+|------|-------------|
+| `tunnel_entropy_analysis` | Calculate Shannon entropy per subdomain label to detect tunneling |
+| `tunnel_query_length` | Measure subdomain label and total query lengths for anomaly detection |
+| `tunnel_txt_payload` | Detect encoded payloads in TXT records: base64, hex, binary markers |
+| `tunnel_record_anomaly` | Analyze queries for record type abuse patterns used in tunneling |
+| `tunnel_tool_signatures` | Match patterns against known tools: iodine, dns2tcp, dnscat2, Cobalt Strike, Sliver C2, DNSStager |
+| `tunnel_covert_channel` | Detect covert channels through beaconing timing analysis and label pattern analysis |
+| `tunnel_full_scan` | All 6 tunnel checks combined with overall probability score (0-100) |
+
+</details>
+
+<details>
+<summary><h3>:lock: Certificate Transparency (7)</h3></summary>
+
+| Tool | Description |
+|------|-------------|
+| `ct_search` | Search CT logs via crt.sh for certificates issued to a domain |
+| `ct_wildcard_audit` | Audit CT logs for wildcard certificates |
+| `ct_unauthorized_detect` | Detect unauthorized certificates by cross-referencing CT logs with CAA records |
+| `ct_monitor` | Monitor CT logs for recently issued certificates within N days |
+| `ct_check_caa` | Check CAA (Certification Authority Authorization) DNS records |
+| `ct_cert_inventory` | Build a full certificate inventory from CT logs |
+| `ct_expiry_monitor` | Find certificates expiring within N days |
+
+</details>
+
+<details>
+<summary><h3>:globe_with_meridians: Domain Intelligence (10)</h3></summary>
+
+| Tool | Description |
+|------|-------------|
+| `domain_whois` | Query RDAP for domain WHOIS information |
+| `domain_age` | Determine domain age via RDAP creation date |
+| `domain_history` | Retrieve domain event history from RDAP |
+| `domain_expiry_risk` | Assess domain expiry risk via RDAP |
+| `domain_parked_detect` | Detect if a domain is a parked/for-sale page |
+| `domain_dga_detect` | Analyze domains for DGA (Domain Generation Algorithm) characteristics |
+| `domain_newly_registered` | Search CT logs for recently issued certs to discover new domains |
+| `domain_reputation` | Multi-source domain reputation check |
+| `domain_hosting_info` | Get hosting infrastructure details for a domain |
+| `domain_related` | Find related domains through shared NS, MX, IP, and CT co-occurrence |
+
+</details>
+
+<details>
+<summary><h3>:dart: Typosquatting & Brand Protection (8)</h3></summary>
+
+| Tool | Description |
+|------|-------------|
+| `typo_homoglyph` | Generate visually similar domain variants (o/0, l/1, rn/m, Cyrillic lookalikes) |
+| `typo_bitsquat` | Generate all single-bit-flip variants of each character in the domain |
+| `typo_tld_variation` | Test common TLD confusions (.com/.co/.cm/.om/.net, etc.) |
+| `typo_combosquat` | Generate brand+keyword combinations (login-, secure-, my-, -app, etc.) |
+| `typo_soundsquat` | Generate phonetically similar variants using sound substitutions |
+| `typo_idn_homograph` | Generate IDN homograph variants using Cyrillic, Greek, Armenian characters |
+| `typo_keyboard_proximity` | Generate QWERTY keyboard proximity typos: adjacent keys, omissions, doubles, swaps |
+| `typo_full_scan` | All 7 typosquatting techniques combined with optional registration check |
+
+</details>
+
+<details>
+<summary><h3>:no_entry: Blocklist & Reputation (6)</h3></summary>
+
+| Tool | Description |
+|------|-------------|
+| `bl_check_dnsbl` | Check an IP against multiple DNS-based blocklists (DNSBL/RBL) |
+| `bl_check_surbl` | Check a domain against domain-based blocklists (SURBL, Spamhaus DBL, URIBL) |
+| `bl_check_phishing` | Check domain for phishing indicators via blocklists and domain age |
+| `bl_check_malware` | Check domain against malware-specific blocklists (abuse.ch, etc.) |
+| `bl_fast_flux_detect` | Detect fast-flux DNS behavior via multiple timed resolutions |
+| `bl_domain_score` | Aggregated domain risk score (0-100) from DNSBL, age, DNSSEC, SPF/DMARC |
+
+</details>
+
+<details>
+<summary><h3>:gear: Infrastructure Security (9)</h3></summary>
+
+| Tool | Description |
+|------|-------------|
+| `infra_open_resolver` | Test if a nameserver is an open resolver accepting external recursive queries |
+| `infra_amplification` | Measure DNS amplification factor of a nameserver |
+| `infra_rate_limiting` | Test Response Rate Limiting (RRL) on a nameserver |
+| `infra_software_cve` | Fingerprint DNS server software via CHAOS version.bind |
+| `infra_edns_compliance` | Test EDNS0 compliance of a nameserver |
+| `infra_tcp_fallback` | Test TCP fallback support for large responses |
+| `infra_dns_cookie` | Test DNS Cookie support (RFC 7873) |
+| `infra_axfr_protection` | Test zone transfer (AXFR) protection |
+| `infra_ns_diversity` | Analyze nameserver diversity (count, ASN distribution, /24 subnets) |
+
+</details>
+
+<details>
+<summary><h3>:detective: DNS Privacy (6)</h3></summary>
+
+| Tool | Description |
+|------|-------------|
+| `privacy_doh_test` | Test DNS-over-HTTPS (DoH) endpoint connectivity and response |
+| `privacy_dot_test` | Test DNS-over-TLS (DoT) endpoint connectivity and security |
+| `privacy_doq_test` | Test DNS-over-QUIC (DoQ) support |
+| `privacy_ecs_leak` | Test EDNS Client Subnet (ECS) leak on a resolver |
+| `privacy_resolver_audit` | Comprehensive privacy audit of a DNS resolver |
+| `privacy_leak_test` | DNS leak test: determine which resolver(s) your system actually uses |
+
+</details>
+
+<details>
+<summary><h3>:biohazard: Passive DNS & Threat Intel (7)</h3></summary>
+
+| Tool | Description |
+|------|-------------|
+| `threat_passive_dns` | Query passive DNS data for a domain |
+| `threat_cohosting` | Analyze domain co-hosting via reverse DNS and CT logs |
+| `threat_ip_to_domains` | Resolve IP to all known domains via PTR records and CT log searches |
+| `threat_malicious_feed` | Check domain against free threat intelligence feeds (Spamhaus, SURBL, URLhaus) |
+| `threat_c2_detect` | Analyze domains for C2 indicators: DGA score, fast-flux, low TTL, DNSBL |
+| `threat_actor_infra` | Map domain infrastructure: NS, MX, IP, ASN (Team Cymru), registrar (RDAP) |
+| `threat_sinkhole_check` | Check if a domain resolves to known sinkhole operators (Microsoft, Shadowserver, abuse.ch) |
+
+</details>
+
+<details>
+<summary><h3>:page_facing_up: Compliance & Reporting (5)</h3></summary>
+
+| Tool | Description |
+|------|-------------|
+| `report_rfc_compliance` | Test compliance with RFC 1035, 4034, 6891, 7208, 7489 |
+| `report_best_practice` | CIS DNS Benchmark-style checks: DNSSEC, email auth, NS diversity, zone transfer, version hiding |
+| `report_full_audit` | Comprehensive audit across all categories with severity ratings |
+| `report_generate` | Full audit with output in JSON, Markdown, or SARIF format |
+| `report_compare` | Compare current audit against a previous baseline to detect drift |
+
+</details>
+
+---
+
+## Configuration
+
+### Environment Variables
+
+All environment variables are **optional**. Core functionality (103 tools) works entirely via local DNS queries with zero external API calls.
+
+```bash
+# Optional: Custom DNS resolver (default: system resolver)
+export DNS_RESOLVER=8.8.8.8
+
+# Optional: SecurityTrails API for enriched passive DNS data
+export SECURITYTRAILS_API_KEY=your-key
+
+# Optional: VirusTotal API for domain reputation enrichment
+export VIRUSTOTAL_API_KEY=your-key
+
+# Optional: Google Safe Browsing API for phishing/malware URL checks
+export SAFEBROWSING_API_KEY=your-key
+```
+
+| Variable | Required | What it enables |
+|----------|----------|----------------|
+| `DNS_RESOLVER` | No | Override the system DNS resolver for all queries |
+| `SECURITYTRAILS_API_KEY` | No | Enriched passive DNS and domain intelligence data |
+| `VIRUSTOTAL_API_KEY` | No | Domain reputation scoring via VirusTotal |
+| `SAFEBROWSING_API_KEY` | No | Google Safe Browsing checks for phishing/malware domains |
+
+**Without any API keys**, all 103 tools function using local DNS queries, public DNS resolvers, RDAP, crt.sh (Certificate Transparency), and DNS-based blocklists. API keys only add optional enrichment from third-party threat intelligence services.
+
+---
+
+## CLI Usage
+
+```bash
+# Show help
+npx dns-security-mcp --help
+
+# List all 103 tools with descriptions
+npx dns-security-mcp --list
+
+# Run any tool directly from the command line
+npx dns-security-mcp --tool dns_lookup '{"domain":"example.com","types":["A","AAAA","MX","TXT"]}'
+npx dns-security-mcp --tool dnssec_validate '{"domain":"cloudflare.com"}'
+npx dns-security-mcp --tool email_spoofability_score '{"domain":"google.com"}'
+npx dns-security-mcp --tool hijack_subdomain_takeover '{"domain":"target.com","use_ct":true}'
+npx dns-security-mcp --tool tunnel_full_scan '{"queries":["aGVsbG8.tunnel.evil.com","d29ybGQ.tunnel.evil.com"]}'
+npx dns-security-mcp --tool typo_full_scan '{"domain":"mybank.com","check_registered":true}'
+npx dns-security-mcp --tool report_generate '{"domain":"example.com","format":"sarif"}'
+
+# Using Bun (faster startup)
+bunx dns-security-mcp --tool bl_domain_score '{"domain":"suspicious-site.xyz"}'
+
+# With custom DNS resolver
+DNS_RESOLVER=1.1.1.1 npx dns-security-mcp --tool dns_propagation '{"domain":"example.com"}'
+```
+
+---
+
+## Architecture
+
+```
+src/
+  index.ts                # CLI entrypoint (--help, --list, --tool, stdio server)
+  protocol/
+    mcp-server.ts         # MCP server setup (stdio transport)
+    tools.ts              # Tool registry — all 103 tools assembled here
+  types/
+    index.ts              # Shared types (ToolDef, ToolContext, ToolResult)
+  utils/
+    dns-client.ts         # Shared DNS query client (UDP/TCP, dns-packet)
+    rate-limiter.ts       # Per-provider rate limiter
+    cache.ts              # TTL cache for DNS responses
+  dns/                    # DNS Reconnaissance tools (12)
+  dnssec/                 # DNSSEC Validation tools (8)
+  email/                  # Email Security tools (9)
+  hijack/                 # Hijacking & Takeover tools (9)
+  tunnel/                 # DNS Tunneling Detection tools (7)
+  ct/                     # Certificate Transparency tools (7)
+  domain/                 # Domain Intelligence tools (10)
+  typo/                   # Typosquatting & Brand Protection tools (8)
+  blocklist/              # Blocklist & Reputation tools (6)
+  infra/                  # Infrastructure Security tools (9)
+  privacy/                # DNS Privacy tools (6)
+  threat/                 # Passive DNS & Threat Intel tools (7)
+  report/                 # Compliance & Reporting tools (5)
+  data/                   # Static data (DKIM selectors, DNSBL lists, tool signatures)
+```
+
+**Design decisions:**
+
+- **3 dependencies, nothing else** &mdash; `@modelcontextprotocol/sdk` for the MCP protocol, `zod` for input validation, `dns-packet` for raw DNS packet crafting. No bloated dependency tree. No native modules. No C bindings.
+- **100% local core** &mdash; Every tool works via direct DNS queries using `dgram` (UDP) and `net` (TCP) sockets with `dns-packet` for wire-format encoding/decoding. No external API calls required for any core functionality.
+- **13 providers, 1 server** &mdash; Each security category is an independent module. The AI agent picks which tools to use based on the investigation context.
+- **Raw DNS access** &mdash; Unlike tools built on `dns.resolve()`, dns-security-mcp crafts raw DNS packets. This enables DNSSEC record queries (DS, DNSKEY, RRSIG, NSEC), CHAOS class queries (version.bind), non-recursive queries (cache snooping), AXFR attempts (zone transfer), and EDNS options &mdash; none of which are possible with Node's built-in DNS module.
+- **TTL caching** &mdash; DNS responses are cached respecting record TTL values. CT log queries cached for 15 minutes. RDAP responses cached for 10 minutes. Prevents redundant queries during multi-tool workflows.
+- **Graceful degradation** &mdash; Missing API keys never crash the server. Optional enrichment tools return clear messages: "Set SECURITYTRAILS_API_KEY for enriched passive DNS data."
+- **Multiple output formats** &mdash; Reports can be generated as JSON (machine-readable), Markdown (human-readable), or SARIF (IDE/CI integration).
+
+---
+
+## Part of the MCP Security Suite
+
+| Project | Domain | Tools |
+|---|---|---|
+| [hackbrowser-mcp](https://github.com/badchars/hackbrowser-mcp) | Browser-based security testing | 39 tools |
+| [cloud-audit-mcp](https://github.com/badchars/cloud-audit-mcp) | Cloud security (AWS/Azure/GCP) | 38 tools |
+| [github-security-mcp](https://github.com/badchars/github-security-mcp) | GitHub security posture | 39 tools |
+| [cve-mcp](https://github.com/badchars/cve-mcp) | Vulnerability intelligence | 23 tools |
+| [osint-mcp-server](https://github.com/badchars/osint-mcp-server) | OSINT & reconnaissance | 37 tools |
+| [darknet-mcp-server](https://github.com/badchars/darknet-mcp-server) | Dark web & threat intelligence | 66 tools |
+| **dns-security-mcp** | **DNS security intelligence** | **103 tools** |
+
+---
+
+## Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+---
+
+<p align="center">
+<b>For authorized security testing and assessment only.</b><br>
+Always ensure you have proper authorization before performing DNS security testing on any target.
+</p>
+
+<p align="center">
+  <a href="LICENSE">MIT License</a> &bull; Built by <a href="https://github.com/orhanyildirim">Orhan Yildirim</a> &bull; TypeScript + Bun
+</p>