confusable_homoglyphs

confusable_homoglyphs is a Python library that flags strings containing Unicode characters visually confusable with characters from other scripts — the technique behind lookalike-username and IDN-homograph phishing attacks (e.g. registering ΑlaskaJazz to impersonate AlaskaJazz, or www.microsпt.com to impersonate microsoft.com). It builds its confusable matrix directly from the Unicode Consortium’s own confusables.txt and Scripts.txt data files, caching them locally as JSON so lookups are fast and always traceable to an authoritative source.

The library exposes both a is_dangerous() check and lower-level script/category introspection, letting an application either outright reject mixed-script usernames or apply a custom policy (e.g. allow non-confusable mixed-script strings while blocking ones that could be mistaken for a preferred script such as Latin).

What You Get

• is_dangerous(string) for a one-call check of whether a string mixes scripts in a way that enables impersonation
• is_confusable(string) returning the specific confusable characters and which scripts they could be mistaken for
• Automatic download and local JSON caching of the Unicode Consortium’s confusables.txt and Scripts.txt reference data
• Configurable preferred-script aliases so an app can allow characters from its own alphabet while still flagging cross-script confusables
• Pure-Python implementation with no compiled dependencies, compatible with both Python 2 and 3 codebases

Common Use Cases

• Rejecting usernames or display names at signup that visually impersonate an existing account via mixed-script homoglyphs
• Validating domain names or email local-parts against IDN-homograph phishing patterns before allowing registration
• Flagging suspicious mixed-script strings in user-generated content moderation pipelines
• Auditing existing datasets of usernames/handles for potential impersonation collisions

Under The Hood

Architecture - The library ships two data-generation modules that fetch and parse the Unicode Consortium’s Scripts.txt and confusables.txt files into categories.json and confusables.json on first use (or on demand if deleted), then a small confusable_homoglyphs.py module that indexes those JSON tables per-character and exposes is_confusable/is_dangerous as pure functions over that index.

Tech Stack - Pure Python 2/3-compatible standard-library code with no compiled extensions; data is stored as flat JSON rather than a database, keeping the dependency footprint at zero beyond requests-style HTTP fetching for the initial data download.

Code Quality - The project includes a tests module with unit coverage for the confusable-detection logic and category parsing; maintenance moved off GitHub to SourceHut in January 2024 and the GitHub mirror has seen no commits since, so the version indexed here reflects the last GitHub-hosted state rather than active upstream development.

API Design - The public surface is two functions (is_confusable, is_dangerous) plus a preferred_aliases parameter, which keeps integration to a single import and function call; the tradeoff is that the underlying confusables/categories JSON files are fetched and cached as a side effect of import, which can surprise callers in network-restricted environments.