Extract and chain Hashcat-compatible rules from wordlists using OpenCL GPU acceleration.

• Overview
• Scripts
  • rulest.py — v1 (BFS, Legacy)
  • rulest_v2.py — v2 (Recommended)
• Why v2 Supersedes v1
• Requirements
• Installation
• Usage
  • rulest_v2.py — Full Reference
• Architecture (v2)
• Rule Categories
• GPU Command Support
• Configuration Constants
• Output Format
• Performance Tuning
• Examples

This toolkit analyzes two wordlists — a base (source) wordlist and a target (dictionary) wordlist — and reverse-engineers the Hashcat rules that transform words from the base into words in the target. Rules are discovered via GPU-parallel transformation and validated for direct compatibility with Hashcat's GPU engine.

The result is a .rule file you can load directly into Hashcat (-r rules.txt), ordered by effectiveness (hit count).

A first-generation implementation using a Breadth-First Search (BFS) chaining strategy executed on the GPU via a monolithic OpenCL kernel.

Approach:

• Generates a static, hard-coded rule set (simple rules, T/D positional, s-substitution, Group A)
• Chains rules across depths using temporary disk files to pass state between BFS layers
• No rule validation against Hashcat's GPU compatibility specification
• No Bloom filter — lookups performed directly against a Python set
• Single device selection (first available platform/device)
• No hit counting or frequency-based ranking
• Fixed batch size; halves on MemoryError

When to use: Historical reference only. v2 is strictly superior in every dimension.

A complete redesign built around GPU efficiency, Hashcat compatibility, and intelligent search strategy.

Key capabilities:

• ✅ Full Hashcat GPU rule validation (max 255 ops, correct argument types)
• ✅ Bloom filter on-GPU for fast membership testing with configurable false-positive rate
• ✅ Two-phase extraction: single-rule sweep → informed chain generation
• ✅ Dynamic VRAM-aware batch and budget sizing (scales with available VRAM; baseline 8 GB)
• ✅ Hot-rule biased chain generation using Phase 1 results (60% hot-rule bias, configurable via HOT_RULE_RATIO)
• ✅ Seed rules support to guide chain exploration (30% budget allocated to extending seeds)
• ✅ Per-depth chain budget overrides (depths 2–10)
• ✅ Unlimited result cap (no global ceiling)
• ✅ Full hit counting and frequency-ranked output
• ✅ Multi-device listing and explicit device selection by index or name substring
• ✅ Color-coded terminal output with live progress bars
• ✅ Configurable verbosity via VERBOSE flag

The core algorithmic difference matters at scale:

v1 BFS: Every word × every rule at each depth level. At depth 2 with 2,700 rules and 100,000 base words: 270 million combinations per depth, with no prioritization. State must be written to disk between depths, creating an I/O bottleneck. Rules that never produce hits are retried at every depth.

v2 Informed Generation: Phase 1 identifies which individual rules ("hot rules") actually hit the target dictionary. Phase 2 then generates chains biased 60% toward hot rules (configurable via HOT_RULE_RATIO). An additional 30% of the budget extends known-good seed chains. This dramatically reduces wasted GPU cycles and finds effective multi-rule sequences far faster than exhaustive BFS.

Python >= 3.8 numpy pyopencl tqdm 

An OpenCL-capable GPU (NVIDIA, AMD, or Intel) is required. CPU fallback via OpenCL is supported but will be slow.

# Clone the repository git clone https://github.com/A113L/rulest.git cd rulest # Install dependencies pip install numpy pyopencl tqdm # Verify OpenCL is available python -c "import pyopencl; print(pyopencl.get_platforms())"

Windows users: Install the appropriate OpenCL runtime for your GPU vendor. NVIDIA users typically have this via the CUDA toolkit or standard driver. AMD users should install ROCm or the AMD APP SDK.

usage: rulest_v2.py [options] base_wordlist target_wordlist 

usage: rulest.py -w WORDLIST [-b BASE_WORDLIST] [-d CHAIN_DEPTH] [--batch-size N] [-o OUTPUT] [-r RULES_FILE] 

┌─────────────────────────────────────────────────────┐ │ GPUExtractor │ │ ┌───────────────┐ ┌─────────────────────────┐ │ │ │ Rules │ │ Dynamic Parameters │ │ │ │ Generator │────▶│ (VRAM-aware sizing) │ │ │ └───────────────┘ └────────────┬────────────┘ │ │ │ │ │ ┌──────────────────────────────────▼────────────┐ │ │ │ GPUEngine │ │ │ │ │ │ │ │ ┌─────────────┐ ┌───────────────────────┐ │ │ │ │ │ Bloom Filter│ │ OpenCL Kernel │ │ │ │ │ │ (16–64 MB │ │ ┌─────────────────┐ │ │ │ │ │ │ VRAM) │ │ │find_single_rules│ │ │ │ │ │ └─────────────┘ │ ├─────────────────┤ │ │ │ │ │ │ │find_rule_chains │ │ │ │ │ │ Phase 1 ────────▶ │ └─────────────────┘ │ │ │ │ │ (all words × └───────────────────────┘ │ │ │ │ single rules) │ │ │ │ │ │ │ │ Phase 2 ────────▶ Informed chain generation │ │ │ │ (hot-biased, + seed extension │ │ │ │ VRAM-budgeted) │ │ │ └───────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────┘ │ ▼ HashcatRuleValidator → GPU-safe output (.rule file) 

Phase 1 — Single Rule Sweep All base words are processed against every GPU-compatible single rule in parallel. The Bloom filter (built from the entire target wordlist and uploaded once) allows near-zero-cost hit detection on-device using FNV-1a hashing with 4 independent hash functions. Results feed a Counter of rule → hit frequency.

Phase 2 — Informed Chain Generation Using Phase 1 hit data, chains are generated with a bias toward rules that already demonstrated effectiveness:

• 60% of generated chains use hot rules from Phase 1 (HOT_RULE_RATIO = 0.6)
• 30% of the budget extends known-good seed chains (EXTENSION_RATIO = 0.3)
• 10% is allocated to random exploration

The remaining time budget (total --target-hours minus Phase 1 duration) is split evenly across requested depths. Seed rules from --seed-rules are extended to deeper depths automatically.

The on-GPU Bloom filter uses FNV-1a hashing with two seeds (0xDEADBEEF and 0xCAFEBABE) and 4 hash functions, sized between 16 MB (low-VRAM devices < 4 GB) and 64 MB (default max). Size scales logarithmically with combined wordlist size.

Free VRAM is estimated as 55% of total global memory (VRAM_USAGE_FACTOR = 0.55). All batch sizes, Bloom filter allocation, and chain budgets scale proportionally based on this estimate relative to an 8 GB baseline. Devices with fewer than 4 GB cap the Bloom filter at 32 MB; the batch floor prevents starvation on very constrained hardware.

GPUCompatibleRulesGenerator generates rules across 9 categories, all pre-validated by HashcatRuleValidator:

The identity rule (:) is always included and written first in the output for Hashcat compatibility.

The following commands are not supported on Hashcat's GPU engine and are automatically excluded during validation:

Any rule exceeding 255 operations is also rejected regardless of individual command validity.

These constants are defined at the top of rulest_v2.py and can be tuned for advanced use:

rulest_output.txt (or your specified -o path):

# Generated by GPU rules engine (full kernel) # Total unique rules: 4821 # Total hits: 2193047 : c $1 u l $1 c $! sa@ $0 ... 

• The identity rule (:) is always written first for Hashcat compatibility
• Rules are sorted by hit frequency (descending), then alphabetically
• All rules are guaranteed GPU-valid (max 255 ops, correct argument syntax)
• Encoding is latin-1 to preserve byte-level fidelity with Hashcat's expected input

Basic single-depth extraction:

python rulest_v2.py rockyou.txt target_hashes_plain.txt -d 1 -o single_rules.txt

Deep chain search with a 2-hour budget:

python rulest_v2.py rockyou.txt target.txt -d 4 --target-hours 2.0 -o chains_deep.txt

Use a specific GPU and seed from a previous run:

python rulest_v2.py base.txt target.txt \ --device "RTX 3080" \ --seed-rules single_rules.txt \ -d 3 --target-hours 1.0 \ -o refined_chains.txt

List available OpenCL devices:

python rulest_v2.py --list-devices

Override chain budget for specific depths:

python rulest_v2.py base.txt target.txt -d 5 \ --depth2-chains 200000 \ --depth3-chains 100000 \ --depth4-chains 30000 \ --depth5-chains 5000 \ -o custom_budget.txt

Iterative refinement workflow:

# Pass 1 — fast sweep for single rules python rulest_v2.py rockyou.txt target.txt -d 1 --target-hours 0.25 -o pass1.txt # Pass 2 — chain from pass 1 results python rulest_v2.py rockyou.txt target.txt -d 3 --target-hours 1.0 \ --seed-rules pass1.txt -o pass2.txt # Pass 3 — deep dive seeded from pass 2 python rulest_v2.py rockyou.txt target.txt -d 5 --target-hours 4.0 \ --seed-rules pass2.txt -o pass3_final.txt

MIT

https://github.com/synacktiv/rulesfinder