bidi-guard

name	bidi-guard
description	BiDi text validation and Trojan Source attack detection (CVE-2021-42574)
version	1.0.0
author	Mousa Abu Mazin
license	MIT
platforms	["linux","macos"]
prerequisites	{"commands":["bidi-guard"],"env_vars":[]}
metadata	{"hermes":{"tags":["nlp","security","bidi","unicode","arabic"]}}

bidi-guard — حماية من هجمات Bidi

أداة لاكتشاف حروف Unicode الاتجاهية المخفية التي تُستخدم في هجمات Trojan Source.

خلفية الثغرة

CVE-2021-42574 — ثغرة Trojan Source تستغل حروف Unicode الاتجاهية (BiDi control characters) لإخفاء كود خبيث داخل كود يبدو طبيعيا. الحروف الخطيرة:

الحرف	الكود	الخطورة	الوصف
RLO	U+202E	عالية	يعكس اتجاه النص — يخفي كود خبيث
LRO	U+202D	عالية	يفرض اتجاه يسار-يمين
RLI	U+2067	متوسطة	عزل نص من اليمين لليسار
LRI	U+2066	متوسطة	عزل نص من اليسار لليمين
FSI	U+2068	متوسطة	عزل اتجاه تلقائي
PDI	U+2069	منخفضة	إنهاء العزل
PDF	U+202C	منخفضة	إنهاء التجاوز

الأوامر

فحص ملفات

bidi-guard scan PATH

مثال — فحص مشروع كامل:

bidi-guard scan ./src/

النتيجة المتوقعة:

🔍 Scanning ./src/ ...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

⚠️  src/auth/login.js:42
    Found: U+202E (RLO) — Right-to-Left Override
    Context: if (user === "admin‮ ⁦// Check role⁩ ⁦") {
    Risk: HIGH — Code appears different than what executes

⚠️  src/utils/format.py:18
    Found: U+2067 (RLI) — Right-to-Left Isolate
    Context: price = "⁧100⁩ SAR"
    Risk: MEDIUM — May be legitimate Arabic text

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Files scanned: 127
Issues found: 2 (1 HIGH, 1 MEDIUM)

مثال — فحص ملف واحد:

bidi-guard scan ./src/auth/login.js

فحص سريع للحافظة

echo "النص المراد فحصه" | bidi-guard scan -

وضع CI

bidi-guard ci

يرجع exit code غير صفري إذا وجد حروف خطيرة. مناسب لـ GitHub Actions.

مثال GitHub Actions workflow:

name: BiDi Guard
on: [pull_request]
jobs:
  bidi-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install bidi-guard
        run: pipx install bidi-guard
      - name: Scan for BiDi attacks
        run: bidi-guard ci

إصلاح تلقائي

bidi-guard fix PATH

مثال تفاعلي:

bidi-guard fix ./src/

النتيجة المتوقعة:

Found 2 BiDi characters:

1. src/auth/login.js:42 — U+202E (RLO)
   Remove? [y/N/a(ll)] y
   ✓ Removed

2. src/utils/format.py:18 — U+2067 (RLI)
   Remove? [y/N/a(ll)] n
   ⊘ Skipped (legitimate Arabic)

Fixed: 1 | Skipped: 1

إصلاح بدون تأكيد:

bidi-guard fix ./src/ --yes

شرح الهجمة

bidi-guard explain

يوضح كل حرف bidi وكيف يُستغل مع أمثلة حية.

تكامل مع pre-commit hook

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: bidi-guard
        name: BiDi character check
        entry: bidi-guard ci
        language: system
        pass_filenames: false

ملاحظة للمشاريع العربية

المشاريع التي تحتوي نصوص عربية طبيعية ستظهر فيها حروف RLI/FSI بشكل مشروع. استخدم ملف .bidiignore لاستثناء ملفات الترجمة:

# .bidiignore
locales/
i18n/
*.po
*.xliff

متى تستخدم

• المستخدم يفحص كود مفتوح المصدر
• إعداد CI/CD pipeline
• مراجعة pull request يحتوي نص عربي في الكود
• فحص أمني قبل دمج كود من مصدر خارجي
• التحقق من ملفات تهيئة (config) تحتوي نصوص عربية