DomainTwistex

DomainTwistex is a pure Elixir library for domain name permutation generation and typosquatting detection. It generates domain permutations, finds the registered ones with a fast two-stage DNS pipeline, and enriches each hit with DNS, HTTP/TLS, and WHOIS data. It returns raw data and leaves the judgment of what's malicious to an analyst or model.

Features

• 18 permutation algorithms — Addition, Bitsquatting, Hyphenation, HyphenationTldBoundary, Insertion, Omission, Repetition, Replacement, Subdomain, Transposition, VowelSwap, VowelShuffle, DoubleVowelInsertion, Keyword, TLD, FauxTLD, Mapped, and Homoglyph
• IDN-aware — homoglyph permutations are punycode-encoded (xn--) so they actually resolve; the Unicode form is kept for display
• Public-suffix aware — https://mail.example.co.uk/login is analyzed as example.co.uk
• Two-stage scanning — one cheap A query per permutation at high concurrency, full enrichment only for registered names
• Registered, not just resolving — NOERROR vs NXDOMAIN detection finds MX-only and parked domains, not only ones with A records
• Registry wildcard filtering — discards hits that only resolve because their TLD answers for every name
• DNS enrichment — A/AAAA/CNAME/MX/TXT/DMARC/NS/wildcard with EDNS0, TCP fallback on truncation, retries, and custom resolvers
• HTTP/TLS probing — status, Server, Location, page title, and certificate issuer/SANs/age over HTTP and HTTPS
• WHOIS/RDAP enrichment — registrar and date lookups via RDAP-first, WHOIS-fallback (on by default)
• Baseline comparison data — the original domain is enriched too, so you can compare nameservers, IPs, and MX
• Fuzzy matching scores — Jaro, Levenshtein, character diff, keyboard proximity
• SPF record parsing — full RFC 7208 terms, lookup counting, warnings, and provider categorization
• Partial results — slow lookups never drop a domain; timed-out checks are reported per result
• Streaming and distributed scanning — analyze_stream/2, or split work across Erlang nodes
• CLI task — mix twist for command-line scanning

Installation

Add domaintwistex to your list of dependencies in mix.exs:

def deps do
  [
    {:domaintwistex, "~> 0.10.0"}
  ]
end

Prerequisites

• Elixir 1.17 or later
• OTP 27+ (for String.jaro_distance/2)

No Rust toolchain required — permutation generation is pure Elixir.

Usage

Domain Analysis

# Full analysis — resolves original + all permutations
result = DomainTwistex.analyze("example.com")

# Returns:
%{
  domain: "example.com",
  original: %{fqdn: "example.com", resolvable: true, nameservers: [...], ...},
  permutations: [
    %{
      kind: "Homoglyph",
      fqdn: "xn--exmple-jta.com",
      unicode: "exàmple.com",
      registered: true,
      resolvable: true,
      mx_records: [%{priority: 10, server: "mail.xn--exmple-jta.com"}],
      server_response: %{http: %{...}, https: %{status_code: 200, title: "Sign in"}, tls: %{age_days: 3, ...}},
      whois: %{registrar: "...", creation_date: "2026-10-01T...", ...},
      timed_out: [],
      ...
    },
    ...
  ],
  stats: %{
    total: 3312, found: 42, resolvable: 37, mx: 12,
    wildcard_filtered: 5, dns_errors: 0, timeouts: 1, elapsed_ms: 9_876
  }
}

# With options
result = DomainTwistex.analyze("example.com",
  nameservers: ["1.1.1.1", "8.8.8.8"],
  dns_concurrency: 500,
  whois: false,
  kinds: [:homoglyph, :bitsquatting, :tld]
)

Streaming

"example.com"
|> DomainTwistex.analyze_stream()
|> Stream.filter(&(&1.mx_records != []))
|> Enum.each(&notify/1)

MX-Only Filter

# Returns only permutations with MX records (potential phishing)
result = DomainTwistex.analyze_mx("example.com")

Permutation Generation (No Resolution)

permutations = DomainTwistex.permutations("example.com")
# => [%{fqdn: "examplea.com", tld: "com", kind: "Addition"}, ...]

permutations = DomainTwistex.permutations("example.com", tlds: :all, faux_tld: true)

Distributed Scanning

Node.connect(:"node2@host")
result = DomainTwistex.analyze_distributed("example.com")
# Same shape as analyze/2; chunks from failed nodes are re-run locally

CLI

mix twist example.com
mix twist -c 100 --no-whois example.com
mix twist -n 1.1.1.1 -n 8.8.8.8 --dns-concurrency 500 example.com
mix twist --format json -o results.json example.com
mix twist -k homoglyph,bitsquatting example.com

Options

Permutation Options

Inspection Results

Each permutation result includes:

Results where wildcard: true and public_ips: [] are filtered out, as are hits whose IPs match their TLD's registry wildcard.

Permutation Types

Modules

• DomainTwistex — Public API
• DomainTwistex.Twist — Analysis pipeline
• DomainTwistex.Permutate — Permutation generator
• DomainTwistex.Domain — Normalization and public suffix parsing
• DomainTwistex.IDNA — Punycode encoding
• DomainTwistex.DNS — DNS resolution
• DomainTwistex.HTTP — HTTP/HTTPS and TLS certificate probing
• DomainTwistex.Utils — Enrichment, IP classification, fuzzy matching
• DomainTwistex.SPF — SPF record parser with provider categorization
• DomainTwistex.Whois — RDAP/WHOIS domain lookups
• DomainTwistex.ResolverError — Raised when the configured resolvers don't answer at all

License

BSD-3-Clause

Acknowledgments

Permutation algorithms inspired by twistrs. This library was originally a Rust NIF wrapper around twistrs and has been rewritten as pure Elixir.