huntglyph — Detect homograph attacks

Homograph attacks leverage the visual similarity of characters from different writing systems (e.g., Latin 'a' vs. Cyrillic 'а') to spoof domain names, filenames, or other identifiers, tricking users into believing they are interacting with a legitimate source.

huntglyph provides a detection solution for identifying these deceptive practices, ensuring digital security and clarity.

Usage

huntglyph provides several commands to analyze strings and files.

`text`: Analyze a raw text string

Analyzes a raw text string for homoglyphs, mixed scripts and invisible characters (potential source for steganography). Input can be provided as a command argument or via stdin.

eg. 1 - Analyze a literal string containing homoglyphs, mixed scripts

$ huntglyph text "gооgle.com"
Original:   gооgle.com
Indicator:   ↑↑
Cleaned:    google.com
--------------------------------------------------------------------------------------------------------------------------------
Details:
  - Pos 2: 'о' (U+00043E, Cyrillic) is a homoglyph of 'o' (U+00006F, Latin).
  - Pos 3: 'о' (U+00043E, Cyrillic) is a homoglyph of 'o' (U+00006F, Latin).

Warning: Mixed scripts detected: Latin, Cyrillic
Warning: Confusable characters detected.

Overall Risk: HIGH (Score: 75)

eg. 2 - Analyze a literal string containing a zero-width space

$ huntglyph text "helloworld"
Original:   helloworld
Indicator:       ↑
Cleaned:    hello world
--------------------------------------------------------------------------------------------------------------------------------
Details:
  - Pos 6: Invisible Character '' (U+00200B)

Warning: Invisible characters detected.

Overall Risk: MODERATE (Score: 25)

eg. 3 - Use pipes (input from stdin)

$ cat demo/suspicious.txt | huntglyph text

eg. 4 - Output only the normalized risk score (0.0-1.0) for a literal string

$ huntglyph text "gооgle.com" --risk-score-only
0.75

`inspect`: Detailed character-by-character breakdown

Provides a detailed table view of each character in a string or file, including its code point, name, script, and any suspicious properties.

eg. 1 - Full inspection. Contains homoglyphs, mixed scripts

$ huntglyph inspect "аррӏе.com"
┌─────┬──────┬────────────┬──────────┬────────────────────────────────┬────────────────────────────────────┐
│ POS │ CHAR │ CODE POINT │ SCRIPT   │ NAME                           │ DETAILS                            │
├─────┼──────┼────────────┼──────────┼────────────────────────────────┼────────────────────────────────────┤
│   1 │ а    │ U+000430   │ Cyrillic │ CYRILLIC SMALL LETTER A        │ Homoglyph of 'a' (in word 'аррӏе') │
│   2 │ р    │ U+000440   │ Cyrillic │ CYRILLIC SMALL LETTER ER       │ Homoglyph of 'p' (in word 'аррӏе') │
│   3 │ р    │ U+000440   │ Cyrillic │ CYRILLIC SMALL LETTER ER       │ Homoglyph of 'p' (in word 'аррӏе') │
│   4 │ ӏ    │ U+0004CF   │ Cyrillic │ CYRILLIC SMALL LETTER PALOCHKA │ Homoglyph of 'l' (in word 'аррӏе') │
│   5 │ е    │ U+000435   │ Cyrillic │ CYRILLIC SMALL LETTER IE       │ Homoglyph of 'e' (in word 'аррӏе') │
│   6 │ .    │ U+00002E   │ Common   │ FULL STOP                      │                                    │
│   7 │ c    │ U+000063   │ Latin    │ LATIN SMALL LETTER C           │                                    │
│   8 │ o    │ U+00006F   │ Latin    │ LATIN SMALL LETTER O           │                                    │
│   9 │ m    │ U+00006D   │ Latin    │ LATIN SMALL LETTER M           │                                    │
└─────┴──────┴────────────┴──────────┴────────────────────────────────┴────────────────────────────────────┘

Warning: Mixed scripts detected: Cyrillic, Latin
Warning: Confusable characters detected.

Overall Risk: HIGH (Score: 75)

eg. 2 - Constrains results to suspicious characters

$ huntglyph inspect --suspicious-only "helloworld"
┌─────┬──────┬────────────┬────────┬──────────────────┬───────────┐
│ POS │ CHAR │ CODE POINT │ SCRIPT │ NAME             │ DETAILS   │
├─────┼──────┼────────────┼────────┼──────────────────┼───────────┤
│   6 │      │ U+00200B   │ Common │ ZERO WIDTH SPACE │ Invisible │
└─────┴──────┴────────────┴────────┴──────────────────┴───────────┘

Warning: Invisible characters detected.

Overall Risk: MODERATE (Score: 25)

`scan`: Scan files or directories

Scans files or directories for suspicious characters, analyzing text files in parallel. eg. 1 - Scan a file

$ huntglyph scan demo/suspicious.txt
File: demo/suspicious.txt
Risk Level: HIGH (Score: 100)
Scripts: Latin, Cyrillic

Line 1:
Original:   This file contains a suspicious url: gооgle.com
Indicator:                                        ↑↑       ↑
Cleaned:    This file contains a suspicious url: google.com 
--------------------------------------------------------------------------------------------------------------------------------
Details:
  - Pos 39: 'о' (U+00043E, Cyrillic) is a homoglyph of 'o' (U+00006F, Latin).
  - Pos 40: 'о' (U+00043E, Cyrillic) is a homoglyph of 'o' (U+00006F, Latin).
  - Pos 48: Invisible Character '' (U+00200B)

eg. 2 - Scans a directory (and sets 4 workers for performance)

$ huntglyph scan --workers 4 demo

eg. 3 - Output only the maximum cumulative risk score (0.0-1.0) for a directory

$ huntglyph scan demo --risk-score-only
1.00

`review`: Interactively review suspicious files

Scans files or directories and provides an interactive prompt for each suspicious file found, allowing for detailed inspection or skipping.

$ huntglyph review demo

Command Reference

Installation

This command will download and install huntglyph to a standard location for your system.

Recommended (User-level): Installs to $HOME/.local/bin (Linux/macOS) or a user-specific bin directory (Windows).

curl -sSfL https://raw.githubusercontent.com/gregory-chatelier/huntglyph/main/install.sh | sh

System-wide (Requires sudo): Installs to /usr/local/bin.

sudo curl -sSfL https://raw.githubusercontent.com/gregory-chatelier/huntglyph/main/install.sh | sh

Custom Directory: Use the INSTALL_DIR environment variable to specify a custom path.

curl -sSfL https://raw.githubusercontent.com/gregory-chatelier/huntglyph/main/install.sh | INSTALL_DIR=$HOME/bin sh

Note

This tool has been validated against a subset of the RAID Dataset, confirming its effectiveness in identifying homoglyphs and zero-width space manipulations.

License

This project is licensed under the MIT License - see the LICENSE file for details.

`--format (default, json)`	Output format.	`text`, `inspect`
`--workers N`	Number of worker to use for scanning.	`scan`
`--suspicious-only`	Only show suspicious characters in the output table.	`inspect`
`--full`	Show full details for invisible characters (escaped form).	`inspect`
`--risk-score-only`	Output only the normalized risk score (0.0-1.0). This score is cumulative (max 100) based on mixed scripts (25), confusables (50), invisibles (25), and hidden payloads (100). For 'text', it's the score of the input. For 'scan', it's the maximum score among all scanned files.	`text`, `scan`
`--version`	Print version info.	All commands

huntglyph

Most Popular