hate_crack

```
  ___ ___         __             _________                       __
 /   |   \_____ _/  |_  ____     \_   ___ \____________    ____ |  | __
/    ~    \__  \\   __\/ __ \    /    \  \/\_  __ \__  \ _/ ___\|  |/ /
\    Y    // __ \|  | \  ___/    \     \____|  | \// __ \\  \___|    <
 \___|_  /(____  /__|  \___  >____\______  /|__|  (____  /\___  >__|_ \
       \/      \/          \/_____/      \/            \/     \/     \/
```

## التثبيت

التثبيت من المصدر هو المسار الوحيد المدعوم. hate_crack **ليس**
موزعًا على PyPI: الأمر `pip install hate-crack` يُحل إلى عنصر نائب بإصدار `0.0.0`
يفشل عن قصد ويشير إلى هنا. الاسم محجوز فقط حتى لا يتمكن أي شخص آخر من نشر منتج مشابه تحت هذا الاسم — راجع
[`packaging/pypi-placeholder/`](https://github.com/trustedsec/hate_crack/blob/main/packaging/pypi-placeholder).

### 1. تثبيت hashcat

يجب تثبيت Hashcat وأن يكون متاحًا في PATH الخاص بك:

Ubuntu/Kali:
```bash
sudo apt-get install -y hashcat
```

macOS (Homebrew):
```bash
brew install hashcat
```

أو قم بتنزيل ملف ثنائي جاهز من https://hashcat.net/hashcat/ واضبط `hcatPath` في `config.json` على موقعه.

### 2. تنزيل hate_crack

استنسخ مع الوحدات الفرعية (مطلوب لـ hashcat-utils وprinceprocessor وpcfg_cracker وCorporate_Masks واختياريًا omen):

```bash
git clone --recurse-submodules https://github.com/trustedsec/hate_crack.git
cd hate_crack
```

إذا قمت بالاستنساخ بدون الوحدات الفرعية، فقم بتهيئتها:

```bash
git submodule update --init --recursive
```

ثم خصّص الإعدادات إذا لزم الأمر. يستخدم hate_crack ملفَّي إعدادات، لكلٍّ منهما مجموعة مميزة من الإعدادات:

- **`config.json`** — مسارات قوائم الكلمات، والأقنعة، والقواعد، والضبط الدقيق، وملف potfile، ومسار hashcat، وحدود المرشّحات، ومفاتيح الإشعارات، وإعدادات CLI الافتراضية المفضّلة (35 إعدادًا).
- **`.env`** — إعدادات تكامل الطرف الثالث فقط: بيانات اعتماد Hashview وHashmob، وبيانات اعتماد Pushover، وOllama، وpipal (14 إعدادًا). غير متتبَّع بواسطة git، ويُنشأ بوضعية `0600`.

يقع هذا الخط الفاصل لسبب واحد: `.env` هو الملف الذي قد يحتوي على أسرار. بيانات الاعتماد الخاصة بخدمات الطرف الثالث وإعداداتها توضع في الملف غير المتتبَّع ذي الوضعية `0600`؛ وكل ما يفعله hate_crack محليًا يبقى في `config.json`، وهو آمن للمشاركة والمقارنة والتدوين في ملاحظاتك الخاصة. ولهذا أيضًا توجد *بيانات اعتماد* Pushover في `.env` بينما توجد *مفاتيح* تشغيل/إيقاف Pushover في `config.json` — فالمفاتيح تفضيلات محلية وليست أسرارًا.

لكل مفتاح موطن واحد بالضبط. المفتاح الموضوع في الملف الآخر يُتجاهَل، ويطبع hate_crack تحذيرًا يسمّي الملف الذي ينتمي إليه. ومع ذلك يمكن تجاوز أي مفتاح لتشغيل واحد عبر تصدير متغيّر بيئته. يمكن لمعظم المستخدمين تخطّي هذه الخطوة لأن المسارات الافتراضية تعمل مباشرةً.

`config.json` دائم ومن الدرجة الأولى — فهو غير مهجور ولا يوجد جدول زمني لإزالته. إعدادات التكامل فقط هي التي انتقلت.

**هل ترقّي من `config.json` واحد؟** يقوم hate_crack بترحيله نيابةً عنك عند أول تشغيل: تُنسخ إعدادات التكامل إلى ملف `.env` جديد بوضعية `0600`، ثم تُزال من `config.json` حتى لا يدّعيها الملفان معًا. ويطبع المفاتيح التي انتقلت (وليس قيمها أبدًا)، ويحفظ نسختك الأصلية باسم `config.json.pre-split.bak` قبل المساس بها. ويُترك كل ما تبقّى في `config.json` كما كان تمامًا، بما في ذلك ترتيب المفاتيح.

**أول تشغيل:** يُنشئ hate_crack كلا الملفين نيابةً عنك، فلا يوجد ما تفعله. لإعداد `.env` يدويًا بدلًا من ذلك، انسخ القالب المتتبَّع:

```bash
cp .env.example .env
chmod 600 .env
```

`.env.example` مُلتزَم به ويُشحن مع كل مفتاح بيانات اعتماد فارغ. يجب **ألا** يُلتزم بـ `.env` نفسه أبدًا — فهو مُتجاهَل بواسطة git، إلى جانب تهجئات النسخ الاحتياطي المعتادة له، ويقوم hate_crack دائمًا بإنشائه بوضع `0600` (قراءة/كتابة للمالك فقط). يتم توليد `.env.example` من المخطط؛ أعد توليده بعد تغيير `hate_crack/config_schema.py` باستخدام `uv run python -m hate_crack.config_writer`.

### 3. تثبيت التبعيات و hate_crack

أسهل طريقة هي تشغيل `make` (أو `make install`)، والذي يكتشف نظام التشغيل الخاص بك تلقائيًا ويثبّت:
- التبعيات الخارجية (p7zip، transmission-daemon / transmission-remote)
- يبني الوحدات الفرعية (hashcat-utils، princeprocessor، pcfg_cracker، واختياريًا omen) ويسحب مجموعة الأقنعة Corporate_Masks الخاصة بالبيانات فقط
- تبعيات Python عبر uv وواجهة CLI في `~/.local/bin/hate_crack`

```bash
make
```

هذا الإجراء عديم الأثر الجانبي - يتخطى الأدوات المثبتة مسبقًا. لفرض إعادة تثبيت نظيفة:

```bash
make reinstall
```

**أو قم بتثبيت التبعيات يدويًا:**

### التبعيات الخارجية
هذه مطلوبة لبعض عمليات التنزيل/الاستخراج:

- `7z`/`7za` (p7zip) — يُستخدم لاستخراج أرشيفات `.7z`.
- `transmission-daemon` / `transmission-remote` — يُستخدم لتنزيل ملفات torrent الخاصة بـ Weakpass.

أوامر التثبيت اليدوي:

Ubuntu/Kali:
```bash
sudo apt-get update
sudo apt-get install -y p7zip-full transmission-daemon
```

macOS (Homebrew):
```bash
brew install p7zip transmission-cli  # provides transmission-daemon and transmission-remote
```

ثم قم بتثبيت تبعيات Python وواجهة CLI:
```bash
uv sync
mkdir -p ~/.local/bin
printf '#!/usr/bin/env bash\nset -euo pipefail\nexec uv run --directory %s python -m hate_crack "$@"\n' "$(pwd)" > ~/.local/bin/hate_crack
chmod +x ~/.local/bin/hate_crack
```

-------------------------------------------------------------------
## بنية المشروع
تم تقسيم المنطق الأساسي الآن إلى وحدات تحت `hate_crack/`:

- `hate_crack/cli.py`: مساعدات argparse وتجاوزات الإعدادات.
- `hate_crack/api.py`: تكاملات Hashview وWeakpass وHashmob (التنزيلات/القوائم/المساعدات).
- `hate_crack/attacks.py`: معالجات هجمات القائمة.
- `hate_crack/corpus_stats.py`: إحصاءات كلمات المرور للمجموعة الكاملة المستخدمة لوصف مجموعة بيانات إلى LLM.
- `hate_crack/plaintext.py`: يستعيد كلمة المرور من سطر مجموعة البيانات (إزالة بادئة التجزئة، فك ترميز `$HEX[...]`); مشترك بين أوضاع LLM وcorpus_stats وrulegen.
- `hate_crack/llm.py`: توليد مرشحات LLM منظمة (JSON) عبر Atomic Agents.
- `hate_crack/menu.py`: عارض القائمة المشترك، بما في ذلك التنقل الاختياري بمفاتيح الأسهم.
- `hate_crack/noninteractive.py`: موزّع أوامر الهجوم النصية الفرعية.
- `hate_crack/notify/`: حزمة الإشعارات (خلفية Pushover، متتبع لكل عملية كسر).
- `hate_crack/username_detect.py`: يكتشف ملفات الإدخال `username:hash` لتحديد خيار `--username` في hashcat.
- `hate_crack/formatting.py`، `hate_crack/progress.py`: مساعدات تنسيق الإخراج وعرض التقدم.
- `hate_crack/main.py`: التنفيذ الرئيسي لواجهة سطر الأوامر.

يبقى `hate_crack.py` في المستوى الأعلى نقطة الدخول الرئيسية وينسّق هذه الوحدات.

-------------------------------------------------------------------
## المراجع والشكر

يعتمد هذا المشروع على عدد من المشاريع والخدمات الخارجية ويستلهم منها. شكراً لـ:

- Hashview (http://github.com/hashview/)
- Weakpass (https://weakpass.com)
- Hashmob (https://hashmob.net)

-------------------------------------------------------------------
## الاستخدام

بعد التثبيت باستخدام `make`، شغّل hate_crack من أي مكان:

```bash
hate_crack
# or with arguments:
hate_crack <hash_file> <hash_type> [options]
```

بدلاً من ذلك، شغّله عبر `uv`:

```bash
uv run hate_crack.py <hash_file> <hash_type>
```

### التشغيل كأداة (موصى به)

التثبيت باستخدام `make` من جذر المستودع - يقوم هذا ببناء الوحدات الفرعية وتجميع الأصول:

```bash
cd /path/to/hate_crack
make
hate_crack
```

يقوم أمر `make install` بإنشاء bash shim في `~/.local/bin/hate_crack` يعمل من دليل المستودع، لذا يتم العثور على الإعدادات والأصول دائمًا بغض النظر عن دليل العمل الحالي.

يتم أيضًا البحث عن الإعدادات في:
- جذر المستودع ودليل الحزمة
- `~/.hate_crack`

**ملاحظة:** `hcatPath` في `config.json` مخصص لموقع ملف hashcat الثنائي فقط (اختياري إذا كان hashcat في PATH). يتم تحميل أصول Hate_crack (hashcat-utils، princeprocessor، pcfg_cracker، Corporate_Masks، omen) من دليل المستودع ويتم تجميعها تلقائيًا بواسطة `make install`.

### التشغيل كسكربت
يستخدم السكربت shebang الخاص بـ `uv`. اجعله قابلًا للتنفيذ وشغّله:

```bash
chmod +x hate_crack.py
./hate_crack.py
```

يمكنك أيضًا استخدام Python مباشرةً:

```bash
python hate_crack.py
```

### الاستخدام غير التفاعلي / البرمجي

للأتمتة يمكنك تشغيل هجوم واحد مباشرةً، متجاوزًا القائمة. اسم الهجوم هو الوسيط الأول، يليه ملف التجزئة ونوع تجزئة hashcat. تقبل مطالبات المعالجة المسبقة (تصفية حسابات الكمبيوتر، القوة الغاشمة LM-first، إزالة تكرار الحسابات المكررة) إعداداتها الافتراضية تلقائيًا في هذا الوضع. تنتهي العملية بـ `0` عند النجاح وبقيمة غير صفرية عند الخطأ (ملف تجزئة مفقود، نوع تجزئة غير رقمي، قائمة كلمات مفقودة، أو اسم قاعدة غير معروف).

```bash
# Quick crack: one wordlist + optional rule(s) from the rules directory
hate_crack quick hashes.txt 1000 --wordlist rockyou.txt --rules best64.rule

# Chain two rules in a single run
hate_crack quick hashes.txt 1000 --wordlist rockyou.txt --rules best64.rule+d3ad0ne.rule

# Run two rules as two separate passes
hate_crack quick hashes.txt 1000 --wordlist rockyou.txt --rules best64.rule d3ad0ne.rule

# Canned dictionary methodology (uses your configured wordlists)
hate_crack dict hashes.txt 1000

# Brute force lengths 1-8
hate_crack brute hashes.txt 1000 --min 1 --max 8

# Top-mask attack targeting ~4 hours
hate_crack topmask hashes.txt 1000 --target-time 4
```

معظم هجمات القائمة متاحة بنفس الطريقة. لا تحتاج هذه إلى أي شيء
بخلاف ملف التجزئة ونوع التجزئة:

```bash
hate_crack fingerprint hashes.txt 1000
hate_crack pathwell    hashes.txt 1000
hate_crack prince      hashes.txt 1000
hate_crack pcfg        hashes.txt 1000
hate_crack princeling  hashes.txt 1000
hate_crack smartmask   hashes.txt 1000
hate_crack corporate   hashes.txt 1000
hate_crack combinator  hashes.txt 1000     # configured wordlists
hate_crack hybrid      hashes.txt 1000     # configured wordlists
```

كل منها يقبل أيضًا الإعدادات التي يطلبها مدخل القائمة الخاص به:

```bash
# Fingerprint, tuned: escalate to 24-character fragments and cap the keyspace
hate_crack fingerprint hashes.txt 1000 --max-expander-len 24 \
    --run-hybrid-on-expanded --keyspace-limit 50000000000

# Skip the fragment/wordlist combination step entirely
hate_crack fingerprint hashes.txt 1000 --no-dictionary-wordlist

# Override the configured wordlists (combinator needs at least two).
# Two wordlists use combinator, three use combinator3, more -- or any
# --separator -- use combinatorX, matching what the menu does.
hate_crack combinator hashes.txt 1000 --wordlist first.txt second.txt
hate_crack combinator hashes.txt 1000 --wordlist a.txt b.txt c.txt
hate_crack combinator hashes.txt 1000 --wordlist a.txt b.txt --separator -
hate_crack hybrid     hashes.txt 1000 --wordlist rockyou.txt

# Corporate masks, lengths 8-12 only
hate_crack corporate hashes.txt 1000 --min 8 --max 12

# Smart mask, skipping templates over 10 billion candidates
hate_crack smartmask hashes.txt 1000 --keyspace-limit 10000000000
```

الباقي يأخذ المدخل الواحد الذي يطلبه إدخال القائمة الخاص به:

```bash
# Bandrel methodology (comma-separate multiple companies)
hate_crack bandrel hashes.txt 1000 --company "Acme,Acme Corp"

# Permutation attack over a short targeted wordlist
hate_crack permute hashes.txt 1000 --wordlist names.txt

# Ad-hoc mask -- a literal mask or a .hcmask file, optionally incrementing
hate_crack adhocmask hashes.txt 1000 --mask '?u?l?l?l?d?d'
hate_crack adhocmask hashes.txt 1000 --mask masks/corporate.hcmask
hate_crack adhocmask hashes.txt 1000 --mask '?a?a?a?a?a?a?a?a' \
    --increment-min 4 --increment-max 8
hate_crack adhocmask hashes.txt 1000 --mask '?a?a?a?a' --increment

# N-gram candidates from a corpus
hate_crack ngram hashes.txt 1000 --corpus corpus.txt --group-size 3

# Combipow passphrases (wordlist capped at 63 lines: it generates 2^n-1)
hate_crack combipow hashes.txt 1000 --wordlist words.txt
hate_crack combipow hashes.txt 1000 --wordlist words.txt --no-spaces

# Spoonman: basewords and rules derived from a corpus of known passwords
hate_crack spoonman hashes.txt 1000 --corpus previous-engagement.txt
hate_crack spoonman hashes.txt 1000 --corpus previous.txt --rule-coverage 95
# --rule-coverage accepts 50, 75, 95 or 99 -- the only capped rule files
# derived. Omit it for the full rule set.

# OMEN -- requires a model trained beforehand from the interactive menu
hate_crack omen hashes.txt 1000 --max-candidates 1000000

# Loopback: re-run rules against the plaintexts already cracked
hate_crack loopback hashes.txt 1000 --rules best64.rule
```

`fingerprint` هو الأمر الوحيد الذي لا يكون شكله المجرّد مطابقًا لمدخله في القائمة: الخيار 5 في القائمة يشغّل دائمًا تمريرات hybrid على fragments الموسّعة، بينما الأمر الفرعي يعتمد افتراضيًا على الإعداد الافتراضي لـ `hcatFingerprint` وهو الإيقاف. مرّر `--run-hybrid-on-expanded` لمطابقة القائمة.

لا تزال خمسة مدخلات في القائمة تفاعلية فقط، لأنها تحتاج إلى مدخلات لا يمكن أن يحملها علم واحد: Markov brute force، وRandom Rules، وهجوم Rosetta، وهجوم LLM، ومنهجية Extensive Pure_Hate (منسّق فوق الآخرين بدلًا من كونه هجومًا واحدًا).

#### رموز الخروج

| الرمز | المعنى |
|---|---|
| `0` | تم تشغيل الهجوم |
| `1` | مدخلات خاطئة — ملف hash أو wordlist مفقود، نوع hash غير رقمي، اسم ملف قاعدة غير معروف، وسيط خارج النطاق |
| `2` | أمر فرعي غير معروف — هذه النسخة من hate_crack لا تحتويه |
| `3` | فقط مع `--exit-code-on-skip`: كانت التغطية قد رأت كل تمريرة بالفعل، لذا لم يُشغَّل شيء |

رمزا الخروج `2` و`3` هما ما يتيح لبرنامج تشغيل نصي التمييز بين "هذه النسخة لا تستطيع تشغيل ذلك الهجوم" و"كان زائدًا عن الحاجة" من جهة، و"شُغِّل ولم يجد شيئًا" من جهة أخرى. `--exit-code-on-skip` اختياري حتى لا يبدأ تفعيل التغطية في إفشال أدوات الاختبار التي سبقته.

-------------------------------------------------------------------
## استكشاف الأخطاء وإصلاحها

### خطأ: "would clobber existing tag" عند التحديث

قد ترفض نسخة مستنسخة أقدم التحديث، مطبوعةً قائمة طويلة من الأسطر مثل:

```
 ! [rejected]        v2.5.0     -> v2.5.0  (would clobber existing tag)
```

يؤثر هذا على النسخ المستنسخة التي أُنشئت قبل يوليو 2026. أُعيد كتابة السجل المنشور آنذاك لإزالة بعض الملفات التي ما كان ينبغي إيداعها قط، مما منح كل إيداع معرّفًا جديدًا؛ لذا تشير وسوم النسخة الأقدم إلى كائنات لم يعد هذا المستودع يحتوي عليها، ويرفض git نقل وسم يمتلكه بالفعل. لا يوجد خطب في نسختك المحلية ولا أي بيانات كسر معرّضة للخطر.

استعد بواسطة إعادة تعيين لمرة واحدة. يؤدي هذا إلى تجاهل الإيداعات والتعديلات المحلية في نسختك المحلية، لذا إذا كنت قد خصّصت أي شيء يتتبعه git (على عكس `config.json`، الذي لا يُتتبع)، فأودعه في فرع أولًا:

```bash
cd /path/to/hate_crack
git fetch --tags --force origin
git checkout -B main origin/main
make install
```

`--force` هنا يقوم فقط بتحديث الوسوم؛ لا يمكنه المساس بالـ commits الخاصة بك. بعد ذلك يعمل
المُحدِّث المدمج بشكل طبيعي. الإصدارات قبل 2.18 لم تكن قادرة على إجراء هذا
الاسترداد بنفسها، ولهذا السبب يجب القيام به يدويًا مرة واحدة.

### خطأ: دليل البناء غير موجود

إذا رأيت خطأً مثل:
```
Error: Build directory /opt/hashcat/hashcat-utils does not exist.
Expected to find expander at /opt/hashcat/hashcat-utils/bin/expander.
```

هذا يعني أن أصول hate_crack لم يتم تضمينها في الحزمة المثبتة.

**فهم المسارات:**
- `hcatPath` في config.json → يشير إلى **موقع ملف hashcat الثنائي** (اختياري، يمكن أن يكون في PATH)
- `hashcat-utils/` و `princeprocessor/` → يتم تضمينهما في الحزمة بواسطة `make install`

**الحل:**
أعد التثبيت باستخدام Makefile، الذي يبني الوحدات الفرعية ويثبت الأداة:
```bash
cd /path/to/hate_crack  # the repository checkout
make install
```

**الإعداد الافتراضي (config.json.example):**

يمكن لمعظم المستخدمين استخدام الإعدادات الافتراضية دون تخصيص:
- `hcatWordlists`: `./wordlists` (نسبةً إلى جذر المستودع أو HOME/.hate_crack)
- `hcatOptimizedWordlists`: `./optimized_wordlists` (الدليل المستخدم بواسطة Quick Crack؛ يعود إلى `hcatWordlists` إذا لم يتم العثور عليه)
- `rules_directory`: `./hashcat/rules` (يتضمن قواعد الوحدة الفرعية)
- `hcatTuning`: `` (سلسلة فارغة - لا توجد أعلام ضبط افتراضية)

**أمثلة على تخصيصات config.json:**
```json
{
  "hcatPath": "/usr/local/bin",          # Location of hashcat binary (optional, auto-detected from PATH)
  "hcatBin": "hashcat",                  # Hashcat binary name
  "hcatWordlists": "./wordlists",        # Dictionary wordlist directory (relative or absolute)
  "rules_directory": "./hashcat/rules",  # Rules directory (relative or absolute)
  "hcatTuning": "",                      # Additional hashcat flags (empty by default)
  ...
}
```

**تحميل الإعدادات:**
- الأولوية لكل مفتاح: `os.environ` > ملف المنزل الخاص بذلك المفتاح (`.env` أو `config.json`) > الإعداد الافتراضي المدمج
- المفاتيح المفقودة تعود إلى الإعدادات الافتراضية المدمجة؛ يوثّق `config.json.example` كل مفتاح في `config.json`
- يتم البحث في كلا الملفين، بشكل مستقل عن بعضهما البعض، بهذا الترتيب: **جذر المستودع**، ثم **دليل الحزمة المثبّتة**، ثم **`~/.hate_crack`**. أول تطابق يفوز؛ من الطبيعي أن يأتي الملفان من دليلين مختلفين.
- عند التشغيل الأول، يتم إنشاء كليهما — `config.json` من `config.json.example`، و`.env` من الإعدادات الافتراضية المدمجة. إذا كان `config.json` أقدم لا يزال يحتوي على مفاتيح التكامل، يتم نسخها إلى `.env` الجديد ويخبرك hate_crack بالمفاتيح التي يجب حذفها من `config.json`؛ وهو لا يعدّل ذلك الملف بنفسه أبدًا.
- في كل تشغيل، يطبع hate_crack الملفين اللذين حمّلهما فعليًا:

  ```
  [*] config.json: /home/you/.hate_crack/config.json
  [*] .env:        /home/you/.hate_crack/.env
  ```

  اقرأ هذين السطرين قبل تصحيح إعداد "لا يسري مفعوله". هما موجودان بسبب فخّين في ترتيب البحث:

  - **نسخة مستخرجة تتقدّم على دليل منزلك.** يُبحث في جذر المستودع أولاً، لذا فإن ملف `.env` أو `config.json` الموجود في *أي* نسخة مستخرجة تشغّل الأداة منها يتغلّب على الموجود في `~/.hate_crack` — وتشغيل الأداة من نسخة مستخرجة هو بالضبط ما ينشئ تلك الملفات هناك في المقام الأول. إذا حجب هذا يومًا إعداد `~/.hate_crack` حقيقيًا، فإن hate_crack الآن يصرّح بذلك عبر سطر `[!]` ثالث يسمّي كلا المسارين — تعامل مع ذلك السطر على أنه "الملف أدناه يتم تجاهله"، وليس كإعداد ثانٍ مكافئ في صلاحيته.
  - **دليل العمل الحالي لا يُبحث فيه أبدًا.** يتم تجاهل ملف `.env` الموجود في الدليل الذي تصادف وقوفك فيه، عن قصد: أدلة المهام مليئة بملفات لم يقصد أحد أن تكون إعدادات. ضعه في جذر المستودع أو في `~/.hate_crack`.

### خطأ: merge with ref 'refs/heads/master' but no such ref was fetched

إذا رأيت:
```
Your configuration specifies to merge with the ref 'refs/heads/master'
from the remote, but no such ref was fetched.
```

تمت إعادة تسمية الفرع الافتراضي من `master` إلى `main`. أصلح ذلك باستخدام:
```bash
git remote set-head origin -a
git branch -m master main
git branch --set-upstream-to=origin/main main
git pull
```

-------------------------------------------------------------------
### أهداف Makefile

**الافتراضي (التثبيت الكامل)** - يبني الوحدات الفرعية، ويثبّت التبعيات، ويثبّت الأداة:

```bash
make
# or explicitly:
make install
```

هذا غير متكرر الأثر - يتخطى الأدوات المثبتة بالفعل.

**إعادة تثبيت نظيفة قسرية:**

```bash
make reinstall
```

**تحديث سريع** - يعيد بناء الوحدات الفرعية ويعيد تثبيت الأداة (بعد سحب التغييرات):

```bash
make update
```

**إلغاء التثبيت** - يزيل تبعيات نظام التشغيل والأداة:

```bash
make uninstall
```

**بناء hashcat-utils فقط:**

```bash
make hashcat-utils
```

**تشغيل الاختبارات** - يتعامل تلقائيًا مع HATE_CRACK_SKIP_INIT عند الحاجة:

```bash
make test
```

**تقرير التغطية:**

```bash
make coverage
```

**تنظيف مخرجات البناء/الاختبار:**

```bash
make clean
```

## التطوير

### إعداد بيئة التطوير

قم بتثبيت المشروع مع تبعيات التطوير الاختيارية (تشمل أدوات الفحص والاختبار):

```bash
make dev-install
```

### تشغيل أدوات الفحص والتحقق من الأنواع

قبل دفع التغييرات، شغّل هذه الفحوصات محليًا. استخدم `make lint` لكل شيء، أو شغّل الفحوصات الفردية:

**Ruff (الفحص والتنسيق):**
```bash
make ruff
# or manually:
uv run ruff check hate_crack tests tools packaging hate_crack.py
```

إصلاح المشكلات تلقائيًا:
```bash
uv run ruff format hate_crack tests tools packaging hate_crack.py
uv run ruff check --fix hate_crack tests tools packaging hate_crack.py
```

**ty (فحص الأنواع):**
```bash
make ty
# or manually:
uv run ty check hate_crack
```

**تشغيل جميع الفحوصات معًا:**
```bash
make lint
```

### تشغيل الاختبارات

تكتشف الاختبارات تلقائيًا عندما لا تكون الوحدات الفرعية مبنية وتضبط `HATE_CRACK_SKIP_INIT=1` تلقائيًا.

```bash
make test
```

أو شغّل pytest مباشرةً:

```bash
uv run pytest -v
```

مع التغطية:

```bash
make coverage
```

أو باستخدام pytest:

```bash
uv run pytest --cov=hate_crack
```

### Git Hooks (prek)

تُدار Git hooks بواسطة [prek](https://github.com/j178/prek) (v0.3.3+). ثبّت الـ hooks باستخدام:

```bash
prek install --hook-type pre-push --hook-type pre-commit
```

هذا يثبّت الخطافات المعرّفة في `prek.toml` باستخدام مخطط TOML الخاص بالمستودع المحلي pre-commit:
- **pre-push** (خطافات محلية): ruff، ruff-format، ty، pytest، pytest-lima، bandit
- **pre-commit** (من `pre-commit/pre-commit-hooks`): trailing-whitespace،
  end-of-file-fixer، check-yaml، check-merge-conflict، check-added-large-files،
  detect-private-key

تقوم أدوات الإصلاح التلقائي في pre-commit بإعادة كتابة الملفات في مكانها، لذا أعد التجهيز وأجرِ الالتزام مرة أخرى بعد تشغيلها.

ملاحظة: يتوقع prek 0.3.3 وجود `repos = [...]` في المستوى الأعلى. الصيغة القديمة `[hooks.<stage>] commands = [...]` غير مدعومة.

### التنقل في القوائم بمفاتيح الأسهم

تستخدم القوائم افتراضيًا الاختيار الكلاسيكي المرقّم عبر `print()` + `input()`، والذي
يقبل المفاتيح الكاملة متعددة الأرقام.

لتفعيل التنقل بمفاتيح الأسهم عبر `simple-term-menu`، اضبط
`HATE_CRACK_ARROW_MENU=1`. في هذا الوضع يمكنك إما التحرك بمفاتيح
الأسهم أو كتابة رقم الخيار (بما في ذلك الأرقام متعددة الخانات مثل `99`) والضغط على Enter. كتابة أي شيء آخر تُرشّح القائمة. يتطلب وضع مفاتيح الأسهم أيضًا وجود TTY، لذا يبقى معطّلًا عندما يتم توجيه الإخراج عبر أنبوب.

أدوات الاختيار التي تطبع قائمة ثم تأخذ إدخالًا مكتوبًا (قوائم الكلمات، القواعد،
قائمة Weakpass، معرّفات قائمة كلمات وقواعد Hashview) تقبل Up/Down على كل الواجهات الخلفية،
بدون `HATE_CRACK_ARROW_MENU`. يملأ Up آخر مفتاح مُدرج، و Up مرة أخرى الذي قبله، و Down يعود للخلف؛ يمكنك مع ذلك كتابة رقم أو مسار أو قائمة
مثل `1,3` بدلًا من ذلك. عند كتابة `,` أو `+` أو `-` مباشرة بعد مفتاح
مملوء بالسهم فإنه يمتدّه. تحت الواجهتين الخلفيتين `plain` و `rich` يعمل هذا عبر تحميل
المفاتيح المُدرجة في سجل readline لذلك الطلب الواحد، لذا يُعاد سجلك الخاص
بعد ذلك ولا يمكن الوصول إليه من داخل طلب قائمة.

### تبعيات التطوير

تتضمن المجموعة الاختيارية `[dev]`:
- **ty** - مدقّق أنواع ثابت
- **ruff** - أداة linting وتنسيق سريعة لـ Python
- **pytest** - إطار اختبار
- **pytest-cov** - تقارير التغطية

-------------------------------------------------------------------
الخيارات الشائعة:
- `--download-hashview`: تنزيل التجزئات من Hashview قبل الكسر.
- `--hashview`: قائمة Hashview التفاعلية لإدارة التجزئات وقوائم الكلمات والمهام.
- `--hashview --help`: عرض خيارات سطر أوامر Hashview.
- `--weakpass`: تنزيل قوائم الكلمات من Weakpass.
- `--rank`: عرض قوائم كلمات Weakpass ذات فئة محددة فقط (0=الكل، -1=فئات S/A/B). الفئات: 7=S، 6=A، 5=B، 4=C، 3=D، 2=E، 1=F.
- `--hashmob`: تنزيل قوائم الكلمات من Hashmob.net.
- `--hashmob-masks`: تنزيل الأقنعة من Hashmob.net.
- `--download-torrent <FILENAME>`: تنزيل ملف torrent محدد من Weakpass.
- `--download-all-torrents`: تنزيل كل ملفات torrent المتاحة من Weakpass من الذاكرة المؤقتة.
- `--wordlists-dir <PATH>` / `--optimized-wordlists-dir <PATH>`: تجاوز أدلة قوائم الكلمات.
- `--pipal-path <PATH>`: تجاوز مسار pipal.
- `--restore-potfile`: إعادة بناء `<hashfile>.out` من ملف POT الخاص بـ hashcat عند بدء التشغيل، مع استبدال أي محتوى موجود، ثم المتابعة إلى القائمة العادية. بدون هذا الخيار يعمل البحث في POT فقط عندما لا يكون `.out` موجودًا بالفعل. يقوم خيار القائمة 93 بالشيء نفسه عند الطلب، مع طلب تأكيد.
- `--maxruntime <SECONDS>`: تجاوز الحد الأقصى لوقت التشغيل.
- `--bandrel-basewords <PATH>`: تجاوز ملف الكلمات الأساسية bandrel.
- `--update`: التحديث إلى أحدث إصدار وإعادة التثبيت. يبدّل نسخة الشيك آوت إلى `main` إذا كانت على فرع آخر، لأن وسوم الإصدارات توجد هناك.

---

[Read more](https://github.com/trustedsec/hate_crack)