Why This Exists

Invisible Unicode bidirectional characters can make source code display differently than it executes. This is CVE-2021-42574 — the Trojan Source attack.

An attacker embeds characters that reverse text direction. In a code review, you see:

access_level = "admin"

But the compiler sees:

access_level = "user"

The characters are invisible. Your editor won't show them. Your reviewer won't catch them. bidi-guard will.

Install

pip install bidi-guard

Quick Start

# Scan current directory recursively
bidi-guard scan .

# Scan a specific file
bidi-guard scan src/auth.py

Finds all bidirectional Unicode characters, shows their exact position, context, and severity.

Commands

CI Integration

GitHub Action

name: BiDi Guard
on: [push, pull_request]
jobs:
  bidi-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - run: pip install bidi-guard
      - run: bidi-guard ci .

Pre-commit

Add to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/Moshe-ship/bidi-guard
    rev: v0.1.0
    hooks:
      - id: bidi-guard

Detected Characters

All 16 Unicode bidirectional control characters:

Characters marked High or Critical can actively reorder displayed text — these are the ones used in Trojan Source attacks.

As a Library

from bidi_guard import scan_file, Finding

findings = scan_file("src/auth.py")
for f in findings:
    print(f"{f.char_name} at line {f.line}:{f.col} — severity: {f.severity}")

Why Not Just grep?

These characters are invisible. Literally invisible:

grep "RLO" file.py    # finds nothing
cat file.py            # looks completely normal

bidi-guard shows you what grep cannot: the exact character, its position, surrounding context, severity level, and what it does. It can also auto-fix by stripping them out.

License

MIT — Musa the Carpenter