owl

The Obfuscated Web Locator

A fast and extensible Go library by pigeonsec
for generating typo and homoglyph variations of domain names.

owl helps you detect potential phishing or typosquatted domains by generating realistic permutations of a target domain. It’s designed for speed, extensibility, and ease of integration into larger security or reconnaissance tools.

---

✨ Features

• 🔤 Typo Generation – insertions, deletions, swaps, and homoglyphs
• 🧬 Custom Homoglyph Sets – add or override mappings easily
• ⚙️ Configurable Depth – control how many typos per permutation (default = 2)
• ⚡ Fast – pure Go, allocation-aware
• 🧩 Embeddable – library or CLI mode
• 🧱 Deterministic – stable output for the same inputs

---

🚀 Installation

go get github.com/pigeonsec/owl

⸻

🧠 Library Usage

package main

import (
    "fmt"
    "github.com/pigeonsec/owl"
)

func main() {
    // Create generator with defaults
    gen := owl.NewGenerator()
    gen.MaxTypos = 2 // number of typos per permutation

    // Generate typo variants
    variants := gen.Generate("example.com")

    for _, v := range variants {
        fmt.Println(v)
    }
}

Custom homoglyphs

gen.AddHomoglyph('a', []rune{'à', 'á', 'â', 'ä'})
gen.AddHomoglyph('o', []rune{'ö', 'ò', 'ó'})
variants := gen.Generate("domain.com")

⸻

⚙️ Configuration

Option Type Default Description MaxTypos int 2 Maximum number of typos per permutation IncludeIDN bool true Generate IDN-encoded variants ASCIIOnly bool false Skip IDN output, ASCII only AllowedTLDs []string nil Restrict to given TLDs MaxResults int 0 0 = unlimited Deduplicate bool true Remove duplicate domains Homoglyphs map[rune][]rune built-in Override or extend homoglyphs

⸻

🧩 Example Output

examlpe.com
exmaple.com
exampel.com
exåmple.com
exampłe.com
examplr.com

⸻

🦾 CLI Usage

owl also ships as a simple command-line tool for quick testing or integration into recon pipelines.

Install CLI

go install github.com/pigeonsec/owl/cmd/owl@latest

Example

owl example.com

Output:

exampel.com
examp1e.com
exampIe.com
exmaple.com
examplr.com

Options

owl [domain] [flags]

Flag	Description
-max-typos int	Max typos per permutation (default 2)
-ascii-only	Disable IDN variants
-tlds string	Comma-separated list of allowed TLDs
-limit int	Limit total results
-json	Output as JSON
-homoglyphs string	Path to custom homoglyphs JSON file
-dedupe	Remove duplicates (default true)

Example: JSON output

owl example.com -json -limit 10

[
  {"domain": "exampel.com", "method": "swap"},
  {"domain": "exampIe.com", "method": "homoglyph"},
  {"domain": "examplr.com", "method": "omit"}
]

⸻

🧱 Suggested Directory Layout

owl/
 ├── cmd/
 │    └── owl/           # CLI entrypoint
 ├── homoglyphs.go       # Built-in homoglyph map
 ├── generator.go        # Core permutation logic
 ├── types.go            # Variant, options, interfaces
 └── README.md

⸻

💡 Extra Useful Settings

Even if owl only generates permutations, these options make it practical: • AllowedTLDs []string → filter variants to certain suffixes (.com, .net) • ASCIIOnly bool → skip IDN / punycode results for ASCII-only systems • Deduplicate bool → skip duplicates after combining fuzzers • MaxResults int → safety cap to prevent over-generation • IncludeMethod bool → include the mutation type (swap / omit / homoglyph)

These keep the scope tight but make it ergonomic for both CLI and API users.

⸻

🧩 Integration Ideas • 🕵️ Typosquatting / phishing detection pipelines • 🧠 Domain intelligence enrichment • 🧰 Input for recon tools or passive DNS matchers

⸻

🧑‍💻 Contributing

Contributions, homoglyph additions, and performance improvements are welcome! Please open a PR or issue at github.com/pigeonsec/owl.

⸻

🪶 License

MIT © 2025 pigeonsec

⸻

owl — See what others can’t.

The family of "typical owls" (Strigidae) includes 227 species, of which 13 are classified as Endangered and 3 as Critically Endangered, with the major threats being habitat loss, fragmentation and climate changes.