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

macOS（Homebrew）：```bash
brew install hashcat

如果您克隆时未包含子模块，请初始化它们：```bash
git submodule update --init --recursive

`.env.example` 已提交，且每个凭据键均为空。`.env` 本身**绝不能**被提交——它已被 gitignore，连同其常见的备份拼写形式，并且 hate_crack 始终以 `0600` 模式（仅所有者可读写）创建它。`.env.example` 由 schema 生成；在修改 `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 掩码集
- 通过 uv 安装 Python 依赖，并在 `~/.local/bin/hate_crack` 处创建 CLI 垫片```bash
make

**或手动安装依赖：**

### 外部依赖
这些是某些下载/解压流程所必需的：

- `7z`/`7za` (p7zip) — 用于解压 `.7z` 归档文件。
- `transmission-daemon` / `transmission-remote` — 用于下载 Weakpass 种子文件。

手动安装命令：

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

然后安装 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

或者，通过 `uv` 运行：```bash
uv run hate_crack.py <hash_file> <hash_type>

`make install` 命令会在 `~/.local/bin/hate_crack` 创建一个 bash shim，该 shim 从仓库目录运行，因此无论当前工作目录是什么，配置和资源始终能被找到。

配置还会在以下位置搜索：
- 仓库根目录和包目录
- `~/.hate_crack`

**注意：** `config.json` 中的 `hcatPath` 仅用于指定 hashcat 二进制文件的位置（如果 hashcat 已在 PATH 中，则此项可选）。Hate_crack 资源（hashcat-utils、princeprocessor、pcfg_cracker、Corporate_Masks、omen）从仓库目录加载，并由 `make install` 自动打包。

### 作为脚本运行
该脚本使用 `uv` shebang。使其可执行并运行：```bash
chmod +x hate_crack.py
./hate_crack.py

### 非交互式 / 脚本化使用

对于自动化场景，你可以直接启动单次攻击，绕过菜单。攻击名称是第一个参数，后面跟着哈希文件和 hashcat 哈希类型。预处理提示（计算机账户过滤、LM 优先暴力破解、重复账户去重）在此模式下自动接受其默认值。进程在成功时退出码为 `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

这会影响在 2026 年 7 月之前创建的克隆。当时已发布的历史被重写，以移除一些本不应被提交的文件，这导致每个提交都获得了新的 ID；因此，较旧克隆中的标签指向了本仓库不再包含的对象，而 git 拒绝移动它已经拥有的标签。你的检出没有任何问题，也没有任何破解数据面临风险。

通过一次性重置来恢复。这会丢弃检出中的本地提交和编辑，因此如果你对任何受 git 跟踪的内容（与 `config.json` 不同，后者不受跟踪）进行了自定义，请先将其提交到一个分支：```bash
cd /path/to/hate_crack
git fetch --tags --force origin
git checkout -B main origin/main
make install

这意味着 hate_crack 资源并未打包到已安装的软件包中。

**理解路径：**
- config.json 中的 `hcatPath` → 指向 **hashcat 二进制文件位置**（可选，可以位于 PATH 中）
- `hashcat-utils/` 和 `princeprocessor/` → 由 `make install` 打包到软件包中

**解决方案：**
使用 Makefile 重新安装，它会构建子模块并安装该工具：```bash
cd /path/to/hate_crack  # the repository checkout
make install

**配置加载：**
- 每个键的优先级：`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

默认分支已从 `master` 重命名为 `main`。使用以下命令修复：```bash
git remote set-head origin -a
git branch -m master main
git branch --set-upstream-to=origin/main main
git pull

这是幂等的——它会跳过已安装的工具。

**强制清理并重新安装：**```bash
make reinstall

**卸载** - 移除操作系统依赖项和工具：```bash
make uninstall

**运行测试** - 在需要时自动处理 HATE_CRACK_SKIP_INIT：```bash
make test

**清理构建/测试产物：**```bash
make clean

### 运行 Linter 和类型检查

在推送更改之前，请在本地运行这些检查。使用 `make lint` 运行所有检查，或单独运行各项检查：

**Ruff（代码检查与格式化）：**```bash
make ruff
# or manually:
uv run ruff check hate_crack tests tools packaging hate_crack.py

**ty（类型检查）：**```bash
make ty
# or manually:
uv run ty check hate_crack

### 运行测试

当子模块未构建时，测试会自动检测并自动设置 `HATE_CRACK_SKIP_INIT=1`。```bash
make test

带覆盖率：```bash
make coverage

### 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

菜单选项：
- **(1) Upload Cracked Hashes** - 将当前会话中已破解的结果上传到 Hashview
- **(2) Upload Wordlist** - 将字典文件上传到 Hashview
- **(3) Download Wordlist** - 从 Hashview 下载字典
- **Download Rule** - 从 Hashview 下载规则文件（解压为明文，可直接用于 `hashcat -r`）。在规则 ID 提示符处输入 `a`（或 `all`）可下载列出的所有规则，而非仅下载一个
- **Download All Rules** - 一次性下载 Hashview 列出的所有规则文件；单个规则失败会报告错误，但不会中止其余下载
- **(4) Download Left Hashes** - 下载剩余的未破解哈希（会提示是否切换以进行破解）
- **(5) Download Found Hashes** - 下载已破解的哈希及其明文密码（用于参考/分析）
- **(6) Upload Hashfile and Create Job** - 上传新的哈希文件并创建破解任务
- **(99) Back to Main Menu** - 返回主菜单

**重要：Download Found 与 Download Left 的区别**
- **Download Left Hashes (4)**：下载需要破解的未破解哈希。如果存在已找到的哈希，会自动合并，并提示是否切换到此哈希文件进行破解。
- **Download Found Hashes (5)**：以 hash:cleartext 格式下载已破解的哈希。这些仅用于参考，无法进一步破解。不会显示切换提示。

#### 命令行界面

Hashview 操作也可以通过命令行执行：

上传已破解的哈希：```bash
hate_crack.py --hashview upload-cracked --file <output_file>.out --hash-type 1000

下载规则文件（已解压保存，可直接用于 `hashcat -r`）：```bash
hate_crack.py --hashview download-rules --rules-id 4 --output best64.rule

下载已找到的哈希（已破解的哈希及其明文）：```bash
hate_crack.py --hashview download-found --customer-id 1 --hashfile-id 123

#### 配置

在 `.env` 中设置 Hashview 凭据（它们是集成设置，因此不存放在 `config.json` 中）：```
HASHVIEW_URL=https://hashview.example.com
HASHVIEW_API_KEY=your-api-key-here
HASHVIEW_VERIFY_TLS=true

**下面的 `OLLAMA_*` 键适用于所有后端，而不仅仅是 Ollama。** 它们保留该前缀是因为 `OLLAMA_HOST` 与 Ollama 自身 CLI 读取的是同一个变量，重命名它们会破坏所有现有的 `.env` 文件，却没有任何功能上的收益——vLLM 或 OpenAI 兼容服务器也需要相同的主机、模型、超时、上下文和采样参数，且名称相同。`LLM_BACKEND` 只选择请求的构造方式。

- **`OLLAMA_MODEL`** — 用于候选生成的 Ollama 模型（默认：`qwen3:4b-instruct`）。LLM 攻击使用结构化（JSON）输出，因此请选择具有良好工具/JSON 支持的模型。
- **`OLLAMA_NUM_CTX`** — 模型的上下文窗口大小（默认：`8192`）。在引入语料库统计之前，该值为 `2048`，太小而无法容纳所给的提示：500 个采样明文在系统提示和响应之前大约就有 2,000–3,500 个 token，因此 Ollama 会静默截断采样器精心分散在文件中的部分样本。
- **`OLLAMA_TIMEOUT`** — 在放弃之前等待生成响应的秒数（默认：`300`）。如果大型模型在首次请求时仍在加载到 VRAM 中，可以调高此值，否则可能会超过超时时间；当超时触发时，hate_crack 会打印经过的超时时间和此设置的名称。
- **`OLLAMA_MAX_SAMPLE_LINES`** — 低于此阈值时，LLM 模式还会将字面明文粘贴到提示中（默认：`500`）。值 ≤ 0 会被视为 500。

  基于语料库的模式（**Wordlist**、**Cracked passwords**、**Pattern rules**）始终以统计方式描述*整个*语料库——基础词占比、掩码、大小写、长度、末尾数字和符号、年份——而不是粘贴其中一部分。聚合是有界的，因此 120,000 个密码的转储与 500 行的转储占用的提示空间大致相同。当整个语料库低于此阈值时，原始明文也会被包含在内，因为向模型隐藏一个小语料库没有任何好处。

  这取代了之前粘贴最多 `ollamaMaxSampleLines` 个均匀间隔密码样本的行为。大型转储的样本完全无法传达频率信息：模型无法区分被组织 8% 的人使用的基础词和被单个人使用的基础词，而这恰恰是使一次猜测值得运行的信号。
- **`OLLAMA_NO_CLOUD`** — 当为 `true` 时，拒绝将任何内容发送到本机之外，适用于三种 LLM 后端（Ollama、vLLM 或通用 OpenAI 兼容服务器）中的任何一种。两项检查由这一个设置控制：Ollama 会将带有 `-cloud` 标签的模型（`gpt-oss:120b-cloud`、`deepseek-v3.1:671b-cloud`）通过本地模型使用的同一本地端点代理到 ollama.com，因此请求看起来没有任何不同——这会按模型名称被拒绝。配置的后端 URL 也会被检查：不是环回、私有或链路本地（也不是 `localhost` 或 `.local`/`.internal`/`.lan`/`.localdomain` 名称）的目标会按目标被拒绝，而此检查无法解析的主机名也会被拒绝，采用故障关闭策略，而不是让无法验证的目标通过。hate_crack 的提示包含恢复的明文、语料库统计信息以及客户的名称、行业和位置，因此任一检查触发都意味着请求在构建之前就被拒绝。默认为 `false`，因此有意配置的云模型或远程服务器可以继续工作；在客户数据不得离开本机的项目中请将其打开。
- **`OLLAMA_AUTO_RESEARCH`** — 当为 `true`（默认）时，**Target info** 模式会在你输入公司名称后立即要求本地模型建议行业、位置和母公司/收购历史，并将它们作为可编辑的提示默认值提供。设置为 `false` 则始终得到空白提示（在模型较慢时有用，因为研究会在攻击开始前多花费一次往返）。
- **`OLLAMA_HOST`** — 配置的后端正在监听的位置。接受裸 `host:port`（`theplague.lan:11434`）或带协议的完整 URL（`https://ollama.example.com`）；无论哪种方式，基础 URL 在使用前都会被规范化。默认为 `localhost:11434`，即 Ollama 的端口——vLLM 或 OpenAI 兼容服务器需要将其设置为自己的端口（vLLM 通常监听 `:8000`）。在 `.env` 中设置它，或将其导出为真实环境变量以在单次运行中覆盖该值——它与 Ollama 自身 CLI 读取的变量名相同。
- **`LLM_BACKEND`** — 要与之通信的 OpenAI 兼容服务器：`ollama`（默认）、`vllm`，或用于通用服务器的 `openai`。每个后端都使用相同的 `/v1` 聊天补全 API，因此这仅选择它们不同的两个请求构造细节：`ollama` 获得 `options.num_ctx`，而 `vllm` 获得 `chat_template_kwargs={"thinking": false}`——否则运行推理解析器的 vLLM 服务器会将整个结构化响应路由到 `message.reasoning`，使 `message.content` 为空，并破坏 JSON 解析。`openai` 两者都不发送，因为 `num_ctx` 在那里没有等价物。它**不会**改变主机、模型、超时、上下文或采样设置的来源——对于所有三者来说，这些都是上面的 `OLLAMA_*` 键。
- **`LLM_API_KEY`** — 发送到配置后端的凭据。默认为字面量 `ollama`，即 Ollama 自身服务器忽略的占位符，因此现有安装的请求保持不变；空值会回退到同一占位符，因为 OpenAI SDK 拒绝 `api_key=""`。如果服务器强制要求，请将其设置为真实值——使用 `--api-key` 启动的 vLLM 服务器否则会返回 401。
- 在使用 LLM Attack 之前，确保 Ollama 正在运行且模型已拉取（`ollama pull qwen3:4b-instruct`）——hate_crack 不再自动拉取缺失的模型。

该攻击提供三种生成模式：

1. **Target info** — 公司/行业/位置/母公司；模型根据这些细节推导候选。

   在你输入公司名称后，hate_crack 会向同一个本地模型询问它对该组织已有的了解，并用答案预填 **Industry**、**Location** 和 **Parent Company** 提示，答案显示在括号中：   ```
   Company name: Acme Rail Services

   [!] The values in parentheses below are the local model's GUESSES, not verified OSINT.
       Press Enter to accept, or type your own value to override.
   Industry (freight rail maintenance):
   Location (Omaha, Nebraska):
   Parent company / acquired by:

研究失败——超时、Ollama 未运行、回答为空——绝不会阻断攻击；它只会回退到空白提示。将 `ollamaAutoResearch` 设为 `false` 可完全跳过研究。
2. **词表** — 从样本词表推导基础词。
3. **已破解密码** — 将本次会话中已恢复的明文（`<hashfile>.out`）反馈给模型，使其能够推断目标组织自身的密码习惯（基础词、季节、年份、后缀、leet 变体），并生成相同风格的*新*候选密码。此选项仅在至少破解出一个哈希后才会列出；整个文件会像词表模式一样进行统计分析（参见上文 `ollamaMaxSampleLines`）。

#### PCFG 配置

PCFG 攻击（选项 20）和 PRINCE-LING 攻击（选项 21）使用 `pcfg_cracker` 子模块。在 `config.json` 中配置它们：```json
{
"pcfgRuleset": "DEFAULT",
"pcfgMaxCandidates": 50000000,
"pcfgPrinceLingMaxCandidates": 10000000
}

回答 `Y`，hate_crack 会构建一个临时规则文件，其中仅包含尚未尝试过的条目；回答 `n` 则无论如何都运行整个内容。如果*每个*条目都是重复的，系统会询问你是否直接跳过该攻击，因此有意重新运行已覆盖的内容永远不需要重启工具。

从未被过滤的攻击仍会被记录为已运行，这正是让你能够回答“我是否已经针对此目标运行过 PRINCE？”的原因。

一次选择多个规则文件的攻击（Quick Crack、Loopback）会在任何 hashcat 调用之前，**一次性针对整个批次**提出跳过问题。这个问题被有意设计得很轻量——它不会读取或哈希任何选定的规则文件，因为一个 YOLO 批次可能运行到数百万行，你不应该为了回答一个是/否问题而等待那么久。它只向存储询问此攻击是否已经针对此哈希文件**使用这些词表之一**运行过；逐条目的差异仍然延迟进行，一次一个规则文件，并决定实际跳过什么。因此，全新的语料库永远不会被标记，即使其上的规则都已针对另一个语料库运行过。

三个有意的限制：

- **仅当 hashcat 穷尽密钥空间时才会记录覆盖情况**（退出码 1）。ctrl-C 或错误不会记录任何内容，退出码 0 也不会——那意味着所有哈希都已破解，hashcat 报告此情况时*并未*完成密钥空间，并且在退化的“所有哈希都作为 potfile 条目找到”的情况下，甚至没有尝试任何一个候选。记录不足只会导致以后多一次冗余运行。
- **动态候选生成器永远不会被过滤。** PRINCE、PCFG、OMEN、Markov 暴力破解和 LLM 模式没有固定的集合可供差异比较，因此它们会被记录为已运行，除此之外不做处理。链式规则文件（`-r a -r b`）作为单个单元进行跟踪，而不是逐条目跟踪，因为 hashcat 会应用两个文件的*笛卡尔积*，丢弃单独一行会静默地移除它所参与的每一个组合。
- **`--loopback` 运行会被记录，但永远不会被过滤。** hashcat 会将新破解的明文作为*额外*候选反馈回去，因此这样的运行会尝试完整的词表和规则集，再加上那些回收明文所能触及的内容。这使得两个方向不对称：记录它是合理的，因此之后对同一词表和规则的普通运行会被正确识别为重复，但第二次 loopback 运行有更多破解需要回收，因此永远不会被跳过。

在 `config.json` 中将 `coverage_enabled` 设置为 `false` 可关闭此功能，或为单次运行传递 `--no-coverage`——它既不查询也不更新存储。

#### 检查与重置覆盖情况

主菜单选项 **85 — Attack Coverage** 显示已针对加载的哈希文件运行过什么、其运行历史，并可以清除它。同样的三个操作也可脚本化：```bash
# What has already been run against this hash file?
hate_crack coverage status --hashfile hashes.txt

# Every attack that has run against it, oldest first
hate_crack coverage history --hashfile hashes.txt

# Start over for this hash file only (prompts unless --yes)
hate_crack coverage forget --hashfile hashes.txt --yes

Exit 3 表示*什么都没*运行。一个被部分过滤的 pass —— 有些条目被跳过，有些被尝试 —— 仍然以 `0` 退出，因为攻击确实做了工作。

### hashcat brain 支持（`brain_enabled`）

hashcat 本身自带一个 "brain" —— 一个小型服务器，运行中的 hashcat 实例将候选密码流式传输给它，这样针对同一目标的第二次运行就可以跳过第一次已经尝试过的候选密码。hate_crack 会自动启用它，无需任何菜单步骤：每当它准备对 hashcat 报告为慢速的哈希模式（bcrypt、scrypt 以及其他基于 KDF 的模式，这些模式下哈希本身而非候选密码生成才是瓶颈）发起攻击时，它会启动或复用一个本地 brain 服务器，并为你向 hashcat 调用添加 `--brain-*` 标志。快速模式不会被处理，除非其模式编号列在 `brain_modes_force` 中；而列在 `brain_modes_exclude` 中的模式无论 hashcat 自己的判定如何都绝不会启用 brain —— exclude 始终优先。

**Brain 与攻击覆盖率不是一回事，两者是互补的而非冗余的。** 覆盖率（上文）在整条规则、掩码行和字典的层面进行去重 —— 它决定最初要启动什么，在 hashcat 运行之前就已完成。Brain 在单个候选密码的层面进行去重，并且它通过一个比任何单次 hashcat 调用都更持久的服务器来实现，因此它能捕获覆盖率看不到的重叠：同一次运行中通过两条不同规则或两个不同字典可达的候选密码，以及 —— 正如 `tests/e2e/test_brain_e2e.py` 中的往返测试所演示的 —— 在针对同一目标的第二次独立 hashcat 运行中重新发送的相同候选密码。两者可以同时启用，互不冲突。

`config.json` 中有七个键控制它，全部位于 `brain_*` 前缀下：`brain_enabled`（主开关，默认开启）、`brain_host`（为空表示 hate_crack 在回环地址上管理一个本地服务器；有值表示仅连接到该主机 —— hate_crack 绝不会生成一个它未被要求管理的服务器）、`brain_port`（默认 `6863`）、`brain_client_features`（`1` 哈希密码，`2` 攻击位置，`3` 两者 —— `3` 去重最多，但服务器每看到一个候选密码大约消耗 12 字节 RAM）、`brain_server_timer`（hashcat 自身设置，控制服务器将 `.ldmp`/`.admp` 转储写入磁盘的频率，最小 60 秒，默认 `300`），以及 `brain_modes_force` / `brain_modes_exclude`（逗号分隔的哈希模式编号，用于覆盖 hashcat 自身的慢速/快速判定，exclude 优先）。

**自动生成的服务器完全没有空闲超时。** `brain_server_timer` 并不控制它保持运行多久 —— 没有任何东西控制；它会在生成它的进程的整个生命周期内运行（或直到 `shutdown()`/`atexit` 停止它），并在会话中的每次攻击中复用。在默认值 `300` 下，这意味着只要 hate_crack 在运行，每五分钟就会向 `~/.hate_crack/brain/` 写入一次转储。

第八个键 `BRAIN_PASSWORD` 位于 `.env` 而非 `config.json` 中，因为它是共享密钥，而不是因为 brain 是第三方集成 —— 它仅在你连接到已自行运行的远程 brain 服务器时使用；自动生成的本地服务器会为每个会话生成自己的随机密码，无需配置。

**brain 密码在 hashcat 运行的整个生命周期内对 `ps` 可见，** 因为 hashcat 只接受它作为命令行参数 —— 没有环境变量形式。对于本地自动生成的服务器，这是一个很小的窗口：密码是随机的且仅限该会话，因此其他本地用户只有在攻击实际运行时才能看到它，而会话结束后它就无用了。共享远程 brain 服务器的密码没有这样的缓解措施 —— 它在每次调用中都是相同的值，只要针对该服务器的任何 hate_crack 运行正在进行，机器上的任何其他本地用户都能看到它。在共享或多租户硬件上请相应对待。

传入 `--no-brain` 可在单次运行中禁用 brain，无论 `brain_enabled` 如何；或在 `config.json` 中将 `brain_enabled` 设为 `false` 以在所有地方关闭它。

**Brain 将状态保存在 `~/.hate_crack/brain/` 中** —— 一个小的 `slow_modes.json` 缓存，记录 hashcat 自身按 hashcat 版本划分的慢速/快速判定，另外对于自动生成的服务器，还有其 `.ldmp`/`.admp` 转储文件。这些转储是源自候选密码的材料：它们让新服务器在恢复时知道针对某个目标已经尝试过什么，这在一次渗透中意味着客户衍生的数据会在操作员的主目录中不断累积，只要 brain 曾在那里运行过。与上面的覆盖率存储一样，删除该目录会重置 brain —— 之前被拒绝的候选密码不再被记住，代价是失去该转储所代表的去重能力。如果 brain 看起来跳过了它不该跳过的工作（来自之前不同范围运行的陈旧转储），这就是解决办法。

**删除 `~/.hate_crack/brain/` 不会清除孤立的服务器。** 自动生成的服务器在自己的会话中运行（`start_new_session=True`），因此它能在终端关闭或 SIGHUP 后存活 —— 只有显式 kill，或生成它的进程干净退出并运行其 `atexit` 处理器，才能停止它。孤立的服务器会继续占用回环端口。在默认空 `BRAIN_PASSWORD` 下，你会在每次慢速模式攻击时注意到它表现为 `"[!] ... no brain server could be reached; running without candidate de-duplication"`：孤立服务器的密码是临时的，随生成它的进程一起消亡，因此 hate_crack 拒绝采用它所占据的端口，而不是去猜测一个无法验证的密码。找到并停止它：```bash
pgrep -f 'hashcat --brain-server'
kill <pid>

- **`check_for_updates`** — 启动时启用自动版本检查（默认：`true`）。
- 启用后，hate_crack 会从 GitHub 获取最新发布信息，并在有可用更新时显示通知。
- 该检查异步运行，不会阻塞启动。网络错误会被静默忽略。

##### 更新通道

| 通道 | 标志 | 来源 | 你将获得 |
|---------|------|--------|--------------|
| Release | `--update` | `main` | 最新的正式发布版本。这是默认选项，也是启动检查所提供的。 |
| Nightly | `--nightly` | `nightly-dev` | 已通过 CI 但尚未发布的工作。 |

版本遵循常规 semver，版本号的递增取决于批次中实际包含的内容。第二个组成部分**仅在功能变更时**递增：包含任何 `feat` 提交的周期将走向 `X.(Y+1).0`，而仅包含修复、文档和杂务的周期将走向 `X.Y.(Z+1)`。

`nightly-dev` 为批次所指向的版本打上候选发布标签——`v2.20.1rc1`、`v2.20.1rc2`、……——合并到 `main` 后会将同一目标提升为最终发布版本。候选版本是真正的 PEP 440 预发布版本，因此在两端都能正确排序：

    2.20.0  <  2.20.1rc1  <  2.20.1rc2  <  2.20.1  <  2.21.0rc1  <  2.21.0

目标可以在周期中途改变：第一个落地的 `feat` 会将其从 `X.Y.(Z+1)` 移至 `X.(Y+1).0`，候选编号会为新目标重新开始。该编号始终表示该批次在今天会以什么版本发布。

主版本号永远不会自动递增——`!` 主题或 `BREAKING CHANGE:` 页脚会被视为功能变更，因为自动主版本递增只需一个打错的主题行，就可能导致不可逆的已发布版本。主版本递增是明确的人工操作：手动打标签并推送。

该策略位于 `tools/next_version.py`，由两个打标签工作流共享，并在 `tests/test_next_version.py` 中进行单元测试。

启动检查只会提供正式发布版本，因为 nightly 构建根本不发布 GitHub release，而该检查读取的是 GitHub 的“latest release”端点——因此启用 `check_for_updates` 永远不会将你拉到 nightly 上。现在有两件事将通道区分开来：这一点，以及候选版本是真正的 PEP 440 预发布版本，因此即使是对原始版本号进行排序的工具也会将其视为比它最终成为的正式版本更旧。

任一标志都会先将你的检出切换到对应分支（如果有未提交的更改则拒绝执行）。如果你正在运行 nightly 并想回到已发布的代码，`--update` 会将你移回 `main`。

#### 自动合并已找到的哈希（仅下载未破解哈希）

当下载左侧哈希（未破解哈希）时，hate_crack 会自动：
1. 尝试从 Hashview 下载任何已找到（已破解）的哈希作为辅助操作
2. 将已找到的哈希与本地 `.out` 文件合并（例如，对于 pwdump 格式为 `left_1_123.txt.out` 或 `left_1_123.nt.txt.out`）
3. 移除重复条目
4. 合并后清理临时拆分文件

这确保你在处理未破解哈希时，本地破解结果与 Hashview 的集中式数据库保持同步。

**注意：** 下载已找到哈希的选项会单独下载已破解的哈希以供参考，不执行任何合并，也不会提示进行破解。

<hash_type> 通过运行 `hashcat --help` 获得

示例哈希：http://hashcat.net/wiki/doku.php?id=example_hashes```
$ hashcat --help |grep -i ntlm
   5500 | NetNTLMv1                                        | Network protocols
   5500 | NetNTLMv1 + ESS                                  | Network protocols
   5600 | NetNTLMv2                                        | Network protocols
   1000 | NTLM                                             | Operating-Systems

-------------------------------------------------------------------
## 测试

测试套件主要离线运行，使用 mock/fixture。实时网络检查和系统依赖检查通过环境变量选择启用。

### 本地运行测试```bash
# Run all tests
uv run pytest -v

# Run specific test
uv run pytest tests/test_hashview.py -v

### 针对本地 Docker 栈的实时 Hashview 测试

无需将实时测试指向远程 Hashview 服务器，你可以让测试套件启动一个本地 [Hashview](https://github.com/hashview/hashview) Docker 栈，对其进行初始化，针对其运行实时测试，然后将其拆除。设置 `HASHVIEW_TEST_LOCAL=1` 并将 `HASHVIEW_REPO` 指向 Hashview 检出目录：```bash
HASHVIEW_TEST_LOCAL=1 HASHVIEW_REPO=~/projects/hashview \
  HATE_CRACK_SKIP_INIT=1 uv run pytest tests/test_hashview_cli_subcommands_subprocess.py -v

基于 Docker 的端到端安装/运行（通过 `Dockerfile.test` 缓存）：```bash
HATE_CRACK_RUN_DOCKER_TESTS=1 uv run pytest tests/test_docker_script_install.py -v

测试虚拟机会自动配置所有 Linux 依赖项（hashcat、build-essential、curl、git、gzip、p7zip-full、transmission-daemon、ocl-icd-libopencl1、pocl-opencl-icd、uv）。```bash
HATE_CRACK_RUN_LIMA_TESTS=1 uv run pytest tests/test_lima_vm_install.py -v

你想运行哪条（些）规则？
(1) best64.rule
(2) d3ad0ne.rule
(3) T0XlC.rule
(4) dive.rule
(99) YOLO...运行所有规则
输入你想运行的规则的逗号分隔列表。要链式运行规则，请使用 + 符号。
例如，1+1 将链式运行 best64.rule 两次，而 1,2 将依次运行 best64.rule，然后运行 d3ad0ne.rule。
明智地选择：```




#### Extensive Pure_Hate Methodology Crack
Runs several attack methods provided by Martin Bos (formerly known as pure_hate):
  * Brute Force Attack (7 characters)
  * Dictionary Attack
    * All wordlists in `hcatWordlists` with `best64.rule`
    * `rockyou.txt` with `d3ad0ne.rule`
    * `rockyou.txt` with `T0XlC.rule`
  * Top Mask Attack (Target Time = 4 Hours)
  * Fingerprint Attack
  * Smart Mask Attack
  * Combinator Attack
  * Hybrid Attack
  * Extra - Just For Good Measure
    - Runs a dictionary attack using `rockyou.txt` with chained `combinator.rule` and `InsidePro-PasswordsPro.rule` rules

#### Brute Force Attack
Brute forces all characters with the choice of a minimum and maximum password length.

#### Top Mask Attack
Uses StatsGen and MaskGen from PACK (https://thesprawl.org/projects/pack/) to perform a top mask attack using passwords already cracked for the current session.
Presents the user a choice of target cracking time to spend (default 4 hours).

#### Fingerprint Attack
https://hashcat.net/wiki/doku.php?id=fingerprint_attack

Runs a fingerprint attack using passwords already cracked for the current session. Expander substring length escalates automatically (7, 14, 21, ... up to the chosen ceiling), and an optional wordlist can be combined against the expanded fragments in addition to self-combination. Set `hcatFingerprintWordlist` in `config.json` to a default wordlist path so the prompt offers it instead of asking for a path every time; leave it as `""` to always ask (or skip).

#### Smart Mask Attack
Looks for literal "skeleton" patterns shared by 3+ already-cracked passwords for the current session -- e.g. a fixed stem like `CrawlingHorse` followed by a run of digits, or `ChangeMe2day` followed by digits and symbols drawn from a consistent charset. Every qualifying pattern runs against the full remaining hash list, so other accounts sharing a stem get swept up even though brute-forcing the stem itself was never tried.

Patterns with a fixed run at either end -- nearly all of them -- are grouped by mask and run as hybrid attacks (`-a 6` when the mask trails the stem, `-a 7` when it leads), with every pattern's literal stem a line in that group's wordlist. Dozens of patterns that vary the same way therefore become one hashcat pass over one wordlist rather than one mask line each. Whatever cannot be grouped that way -- variation at *both* ends, which leaves no fixed run to seed a wordlist with -- falls back to a single `-a 3` mask file, and has its charsets widened (up to `?a`) to compensate, as far as the guardrail below allows.

Prompts once, before the attack starts, for an optional per-pattern candidate-count guardrail (default 50,000,000,000; 0 disables it) that excludes any individual pattern whose keyspace is too large without blocking the rest.

#### Combinator Attack
https://hashcat.net/wiki/doku.php?id=combinator_attack

Runs a combinator attack using the "rockyou.txt" wordlist.

#### Hybrid Attack
https://hashcat.net/wiki/doku.php?id=hybrid_attack

* Runs sixteen hybrid passes per wordlist, cheapest first. Each mask length
  from 1 to 4 is tried appended and then prepended, first over `?s?d` and then
  over `?a`, and a single ctrl-C abandons the whole attack rather than only the
  current pass.
  - Hybrid Wordlist + Mask - ?s?d wordlists/rockyou.txt ?1
  - Hybrid Mask + Wordlist - ?s?d ?1 wordlists/rockyou.txt
  - ... the same for ?1?1, ?1?1?1 and ?1?1?1?1
  - Hybrid Wordlist + Mask - wordlists/rockyou.txt ?a
  - Hybrid Mask + Wordlist - ?a wordlists/rockyou.txt
  - ... the same for ?a?a, ?a?a?a and ?a?a?a?a

  `?a` is every printable character, so the second group is a superset of the
  first plus letters and roughly 24x the work at the longest mask — over
  rockyou.txt those passes alone are ~1.2e15 candidates, about ten hours for
  NTLM on hardware doing 32 GH/s. That is why the cheap `?s?d` group runs first
  and why the attack as a whole is time-bounded:

  - `hcatHybridMaxRuntime` in `config.json`, in seconds, default `3600`, is the
    time the **whole attack** may spend — not the time one pass may spend. All
    sixteen passes share one deadline, and each is handed whatever is left of it
    as hashcat's `--runtime`. Any pass the budget does not reach is reported
    rather than skipped quietly. Set it to `0` for no limit, which runs every
    pass to exhaustion.

  Within each group the order is by mask length across every wordlist rather
  than all lengths of one wordlist and then the next, so a budget that runs out
  has still given every wordlist its cheap passes.

  Each pass declares what it covers to the attack-coverage store, so a repeat
  hybrid against the same hash file offers to skip the passes already run. A
  pass that runs out of budget is not recorded, so it will be retried.
  Wordlist entries may be glob patterns or directories; both are expanded
  before hashcat runs, a directory into the wordlists directly inside it.
  Subdirectories are not searched, matching hashcat's own behaviour, and
  dot-files and `.7z`/`.torrent`/`.out` files are skipped — a Weakpass
  download leaves archives in the wordlists directory and hashcat would
  otherwise try to read them.

#### Pathwell Top 100 Mask Brute Force Crack
Runs a brute force attack using the top 100 masks from KoreLogic:
https://blog.korelogic.com/blog/2014/04/04/pathwell_topologies

#### PRINCE Attack
https://hashcat.net/events/p14-trondheim/prince-attack.pdf

Runs a PRINCE attack using wordlists/rockyou.txt

#### YOLO Combinator Attack
Runs a continuous combinator attack using random wordlists from the configured wordlists directory for the left and right sides.

#### Middle Combinator Attack
https://jeffh.net/2018/04/26/combinator_methods/

Runs a modified combinator attack adding a middle character mask:
wordlists/rockyou.txt + masks + worklists/rockyou.txt

Where the masks are some of the most commonly used separator characters:
2 4 <space> - _ , + . &

#### Thorough Combinator Attack
https://jeffh.net/2018/04/26/combinator_methods/

* Runs many rounds of different combinator attacks with the rockyou list.
  - Standard Combinator attack: rockyou.txt + rockyou.txt
  - Middle Combinator attack: rockyou.txt + ?n + rockyou.txt
  - Middle Combinator attack: rockyou.txt + ?s + rockyou.txt
  - End Combinator attack: rockyou.txt + rockyou.txt + ?n
  - End Combinator attack: rockyou.txt + rockyou.txt + ?s
  - Hybrid middle/end attack: rockyou.txt + ?n + rockyou.txt + ?n
  - Hybrid middle/end attack: rockyou.txt + ?s + rockyou.txt + ?s


#### Bandrel Methodology

Prompts for comma-separated names and creates a pseudo hybrid attack by capitalizing the first letter and adding up to six additional characters at the end. Each word is limited to a total of five minutes.

  - Built-in common words (seasons, months) included as a customizable `config.json` entry (`bandrel_common_basedwords`)
  - The default five-minute time limit is customizable via `bandrelmaxruntime` in `config.json`

#### Loopback Attack
https://hashcat.net/wiki/doku.php?id=loopback_attack

Uses hashcat's loopback mode to feed cracked passwords from the current session back into the attack pipeline with rules applied. This generates new password candidates based on variations of already-cracked passwords, which is particularly effective for finding related passwords that follow similar patterns.

* Prompts for rule selection to apply to the loopback candidates
* Uses an empty wordlist with the --loopback flag to process previously cracked passwords
* Automatically downloads Hashmob rules if no rules are available locally

#### LLM Attack
Uses a local LLM — Ollama by default, or a vLLM / OpenAI-compatible server via `LLM_BACKEND` — to generate password candidates for a capture-the-flag scenario. Prompts for the fake company name, industry, location, and parent company / acquisition history, then sends these details to the configured LLM model to produce likely password candidates using industry terms and company name permutations. The generated candidates are fed into a hashcat wordlist+rules attack.

* Requires a running server at `OLLAMA_HOST` (default: `http://localhost:11434`, Ollama's port; override in `.env` or the environment) already serving the model — hate_crack does not auto-pull
* Candidate generation uses structured (JSON) output via Atomic Agents, so pick a model with good schema adherence (default: `qwen3:4b-instruct`)
* Configurable backend, model, context window, request timeout, and sample size via `.env` (see [LLM Configuration](#llm-configuration))
* Prompts for target company name, industry, location, and parent company / acquisition history. The industry, location, and parent company prompts are pre-filled with the local model's guesses about the named organization (editable, and clearly labelled as guesses rather than verified OSINT); disable with `ollamaAutoResearch: false`
* Alternatively derives basewords from a sample **wordlist**, or from the **cracked passwords** of the current session (`<hashfile>.out`) so the model mirrors the target organization's own password conventions and produces new candidates in that style (only offered once something has been cracked)
* A live spinner with an elapsed-seconds counter runs during generation, and requests are bounded by `ollamaTimeout` so a model stuck loading into VRAM reports a timeout instead of hanging

**Pattern rules mode** (option 4 in the LLM submenu) takes the same shape as the [Spoonman Attack](#spoonman-attack) — a baseword list run through a rule file, both derived from one corpus — but infers each side with the model instead of extracting it. Spoonman is exact and therefore bounded: its basewords all appear in the corpus and its rules only reproduce transformations the corpus already shows. This asks the model to generalize on both axes, so it can name the *word families* behind a sample (the company and its products, site names, local sports teams, seasons, mascots) and write decorations the corpus does not contain.

* Pattern source is either the current session's cracked passwords (offered first, and only once something has been cracked, since those reveal the target's real conventions) or a sample wordlist
* **You are not asked to pick a rule file.** The model writes one, from the same corpus statistics — a stock rule file encodes the internet's habits, and the point of spending a model round trip is to encode *this* organization's
* Basewords are normalized to lowercase letters only, discarding anything under 3 characters, so the generated rules supply case, digits, and punctuation exactly once
* Generated rules are validated before hashcat sees them, and anything using an op hashcat does not have, a position argument outside `0-9A-Z`, more than 31 functions, or a stray comment or non-ASCII character is discarded. hashcat drops an invalid rule *silently* when valid rules share the file, so an unscreened line would become missing coverage rather than an error. The op table was established by testing hashcat itself, not from its rule documentation, which lists ops hashcat will not actually run
* Local-model yield varies a lot run to run, so a thin answer is asked again once and the two rounds are merged — a handful of rules would waste the pass they are spent on
* If no rule survives validation the basewords still run, unmutated, rather than throwing away the expensive half of the run
* Output lands in `<hashfile>.llm_patterns/` as `basewords.txt` and `rules.rule` — per-run scratch, laid out like `.spoonman/` and removed on exit

#### OMEN Attack
Uses the Ordered Markov ENumerator (OMEN) to train a statistical password model from a wordlist and generate password candidates. This attack learns patterns from known passwords and generates new candidates based on those patterns.

* Requires OMEN binaries (createNG and enumNG) to be built from the omen submodule
* Interactive menu: use existing model, train new model, or cancel
* Training wordlist picker shows available wordlists from configured directory or accepts a custom path
* Validates all 5 required model files (createConfig, CP/IP/EP/LN.level) before running
* Captures and reports enumNG errors instead of failing silently
* Generates up to a specified number of password candidates (configurable via `omenMaxCandidates`)
* Pipes generated candidates directly into hashcat for cracking
* Model files and metadata are stored in `~/.hate_crack/omen/` for persistence across sessions

#### Combinator Attacks Submenu
Opens an interactive submenu with six combinator attack variants (formerly at menu keys 10-12). Consolidates related attacks for cleaner menu organization:
- Combinator Attack - combines two wordlists
- YOLO Combinator Attack - combines all permutations of multiple wordlists
- Middle Combinator Attack - combines wordlists with an extra word in the middle
- Thorough Combinator Attack - comprehensive combination of wordlists with rules
- Combinator3 Attack - combines exactly 3 wordlists using `combinator3.bin`, generating all `word1+word2+word3` combinations piped to hashcat
- CombinatorX Attack - combines 2-8 wordlists using `combinatorX.bin` with optional `--sepFill` separator character between word segments

#### Ad-hoc Mask Attack
Runs hashcat mask attack (mode 3) with a user-specified custom mask string. Allows fine-grained control over character-set brute forcing.

* Opens with a choice between typing a mask and selecting a mask file
* Prompts for a hashcat mask (e.g., `?u?l?l?l?d?d` for uppercase + lowercase + lowercase + lowercase + digit + digit)
* Supports custom character sets for specialized character combinations: `-1` through `-4` on any hashcat, plus `-5` through `-8` on hashcat 7 and newer. A mask using `?5`–`?8` against an older hashcat is flagged before the run rather than failing inside it; if the version cannot be read, the mask is passed through and hashcat decides
* Only prompts for the custom slots the mask actually references — `?1?3?d` asks about `-1` and `-3` and nothing else, and a mask with no custom tokens is never asked at all. Detection is token-aware, so the escaped `??1` is a literal `?1` and prompts for nothing. A slot left blank is still skipped, with a warning that hashcat will reject a mask whose charset is undefined
* Mask files (`.hcmask`) can be selected with tab completion, defaulting to the bundled `masks/` directory; hashcat runs every mask in the file in order. Because a mask file defines its own charsets inline, the `-1` through `-4` prompts are skipped when one is chosen
* Optionally runs the mask incrementally (`--increment`), trying shorter lengths before the full mask. Answering yes prompts for an increment minimum and maximum; either can be left blank, and leaving both blank increments over the mask's full keyspace with hashcat choosing the bounds. Offered for typed masks and mask files alike
* Useful for targeted brute forcing when you know password structure patterns

#### Markov Brute Force Attack
Generates password candidates using Markov chain statistical models. Similar to OMEN but simpler and faster.

* Checks for existing `.hcstat2` Markov table from previous sessions (with option to reuse, regenerate, or cancel)
* Generates table from training source if needed:
  - Can use cracked passwords from current session (`.out` file) as training data
  - Or select any wordlist from configured directory or custom path
* Interactive menu: choose minimum and maximum password length
* Uses `--increment` flag to test lengths in sequence
* Markov table persists with hash file (filename.out.hcstat2) for fast subsequent runs
* Faster than OMEN for general-purpose brute forcing

#### N-gram Attack
Generates n-gram candidates from a corpus file using `ngramX.bin` from hashcat-utils and pipes them into hashcat.

* Prompts for a corpus file with tab completion, defaulting to the configured wordlist directory
* Prompts for an n-gram group size (default 3)
* Gzip-compressed corpus files are auto-detected and decompressed on the fly
* Useful when you have target-relevant prose (scraped site copy, leaked documents, internal wiki exports) rather than a password list

#### Permutation Attack
Generates all character permutations of each word in a targeted wordlist and pipes them to hashcat via `permute.bin` from hashcat-utils.

* Prompts for a single wordlist file (not a directory)
* Effective against short targeted wordlists where the character set is known but the order is not (company abbreviations, name fragments, known tokens)
* WARNING: Scales as N! per word - an 8-character word produces 40,320 permutations. Only practical for words up to ~8 characters.
* Uses `permute.bin < wordlist | hashcat` pipeline pattern

#### Random Rules Attack
Generates a set of random hashcat mutation rules using `generate-rules.bin`, writes them to a temporary file, then runs hashcat against a chosen wordlist with those rules.

* Prompts for rule count (default 65536)
* Prompts for wordlist path with tab-completion and numbered selection
* Temporary rules file is cleaned up after the run regardless of outcome
* Useful when known rule sets are exhausted - explores random rule-space for additional cracks

#### Combipow Passphrase Attack
Generates all unique non-empty subset combinations from a short wordlist using `combipow.bin` and pipes them into hashcat. Designed for passphrase cracking when you know the pool of words a password was built from.

* Prompts for a wordlist file (max 63 lines - combipow generates up to 2^n-1 combinations)
* Optional space separator (`-s` flag) to insert spaces between words in each combination
* Warns if the wordlist exceeds 20 lines (output volume may be large)
* Aborts with a clear message if the wordlist exceeds 63 lines (hard limit)
* Candidates are piped directly to hashcat stdin

#### PCFG Attack
Uses [pcfg_cracker](https://github.com/lakiw/pcfg_cracker) to generate candidates from a Probabilistic Context-Free Grammar, piping `pcfg_guesser.py` output directly into hashcat's stdin mode. A PCFG models password *structure* (baseword + digits + symbol, capitalization habits, keyboard walks) with learned probabilities, so candidates come out roughly in descending likelihood order.

* Requires the `pcfg_cracker` submodule. Presence is checked at startup and reported non-fatally: if it is missing, the PCFG attacks are simply unavailable. Run `make` to fetch it.
* Uses the trained grammar named by `pcfgRuleset` in `config.json` (default `DEFAULT`), read from `pcfg_cracker/Rules/<name>/`
* Candidate count is capped by `pcfgMaxCandidates` (default 50,000,000)
* hate_crack does not wrap grammar training. To build a grammar from a target-specific password set, run pcfg_cracker's own `trainer.py` and point `pcfgRuleset` at the resulting ruleset name

#### PRINCE-LING Attack
Uses pcfg_cracker's `prince_ling.py` to derive an optimized PRINCE base wordlist from a trained grammar, then hands it to the existing PRINCE attack. PRINCE-LING picks base words the grammar says are actually productive, so the PRINCE combination space is far less wasteful than pointing PRINCE at a generic wordlist.

* Requires the `pcfg_cracker` submodule and a trained ruleset directory, same as the PCFG attack
* The generated wordlist is cached at `<hcatOptimizedWordlists>/pcfg_prince_ling_<ruleset>.txt` and reused across sessions
* Regenerates only when the ruleset directory is newer than the cached wordlist, so retraining a grammar invalidates the cache automatically
* Generation is written to a temporary file and atomically moved into place; a failed or interrupted run cleans up its partial file and leaves any existing cache intact
* Base wordlist size is capped by `pcfgPrinceLingMaxCandidates` (default 10,000,000)

#### Spoonman Attack
Derives a baseword list and a hashcat rule file from a corpus of known plaintext passwords — a previous engagement's cracked output, a leak dump, or any password list — such that the baseword x rule cross product reconstructs the corpus exactly (see the memory bound below for the one case where it does not). Contributed as issue #169 by @Spoonman1091.

Each password is split into its letters-only lowercased core (the baseword) plus a rule that rebuilds the original from it, using `l`/`u`/`c` for casing, `T{p}` toggles, `${x}`/`^{x}` for trailing and leading characters, and `i{p}{x}` for interior ones.

* When the current session already has cracked plaintexts (`<hash file>.out` exists and is non-empty), a picker offers those as the corpus ahead of a free-form path — the target's own recovered passwords derive rules describing that target's actual conventions, which is exactly what you want to fire back at the remaining uncracked hashes. Deriving from `.out` and then cracking the same hash file appends new plaintexts to that same file, growing the corpus for the next run; that is the intended feedback loop, not corruption. Sessions with no cracked output yet see no picker at all — just today's path prompt
* Prompts for the corpus, then for how much of the rule file to run: top 50% coverage (listed first and recommended), top 75%, top 95%, top 99%, or the full set
* Rules are sorted by how many passwords each one rebuilds, so a truncated file keeps the most productive rules. Coverage is extremely long-tailed: on a 98.2M-password sample, 50% coverage needed 4,120 rules while 95% needed 16,119,661 and 100% needed 21,029,696 — the last few percent typically costs orders of magnitude more rules than the first half, which is why the smallest tier is listed first and is usually the right choice
* Output is written beside the hash file in `<hash file>.spoonman/`, alongside the other ephemeral wordlists: `basewords.txt`, `rules.full.rule`, the capped rule files, and `coverage.txt` with per-milestone rule counts. Derivation is skipped on later runs of the same hash file unless the corpus has been modified since, and the directory is removed on exit by the temp-file cleanup
* Derivation is bounded in memory. Both counters would otherwise grow for the whole read with nothing written until the end, so a corpus large enough to exhaust RAM lost the entire pass to an OOM kill and produced no output; a measured run against a 31 GB corpus reached 14.1 GB resident at 11% of the file and was still accelerating. Each counter is now capped at 20 million distinct keys (about 1.6 GB apiece), and the lowest-frequency keys are discarded once it is exceeded. If that happens, the run says so on the console and in `coverage.txt`, the output reconstructs the retained keys rather than 100% of the corpus, and the coverage percentages are relative to those. Corpora below the cap are unaffected
* Passwords that cannot be expressed as a rule are written verbatim as their own baseword with a `:` no-op, so coverage stays complete. This covers two hashcat limits: rule positions cannot address past index 35, and hashcat rejects any rule with more than 31 functions — silently, when valid rules share the file
* A password carrying a literal CR or LF (which arrives hex-wrapped, as `$HEX[...0a]`) cannot go in a baseword at all, because a wordlist line has no escape syntax for one. The break is lifted out into an insert op instead, spelled `\x0a`/`\x0d` in the rule, which hashcat decodes to the byte. When the break sits past addressable index 35 the rule reverses the word first, inserts from the other end, and reverses back. One frame has to hold every break in the password, so what is still skipped is a password with one break outside the first 36 characters *and* another outside the last 36, or one needing more inserts than the 31-function cap leaves room for. Those are counted as `unwritable basewords` in `coverage.txt` and reported, never dropped silently
* The derivation self-checks every password by reconstructing it in-process, and reports any failures rather than reporting success
* Corpus lines may carry a hash in front of the password, as cracked output does. A leading field is dropped only when it has the shape of a hash (a hex digest at a known length, or a crypt-style `$id$` string), so `hash:salt:plain` is handled while a plaintext or wordlist entry containing a colon survives intact. `$HEX[...]` plaintexts are decoded. If most lines look like an uncracked dump rather than cracked output, `coverage.txt` records the count and the attack warns — the derived basewords and rules would otherwise be meaningless without any error being raised

#### Rosetta Attack
Mines hashcat `--debug-mode 5` logs for the basewords and rules that already cracked something, then runs their full cross product. Powered by [HashcatRosetta](https://github.com/bandrel/HashcatRosetta), the same library behind [Analyze Hashcat Rules](#analyze-hashcat-rules-rule-file-tools-option-5).

No setup is needed to feed it: `_add_debug_mode_for_rules` appends `--debug-mode 5 --debug-file` to every rule-based hashcat invocation hate_crack makes, so the logs accumulate in `hcatDebugLogPath` (`~/.hate_crack/hashcat_debug` by default, one file per session) as a side effect of normal use. A mode 5 log records only candidates that cracked a hash, in the form `baseword:rule:candidate:wordlist`, which is what makes both halves known-productive against this target population; the trailing wordlist field also shows which list is earning its keep on a multi-wordlist run. HashcatRosetta parses mode 4 and mode 5 alike, so logs written before the switch are still read.

The value is in the cross product rather than the recorded pairs. A pair present in a log has already cracked its hash and will not crack another, but a rule that worked on one baseword has usually never been tried against the others — so N basewords and M rules yield close to N x M untried candidates.

The menu first asks how to rank rules — choices 1-3 below, plus a fourth, unrelated mode:

* Rules can be ranked by application frequency, by how many distinct basewords each one worked on, or by how many unique candidates each one generated. Frequency is the default; baseword spread is the better choice when the goal is a rule set that generalizes past the specific words it was learned from
* Only after one of those three is picked does hate_crack list the logs found in `hcatDebugLogPath` newest-first with their sizes; pick one, pick all of them (up to 20), or type a path to a log from elsewhere
* Prompts for how many top rules to keep and how many top basewords. Both default to all — a blank answer keeps every winning rule the logs contain, and zero means the same thing. Enter a number to cap either. The keyspace is the product of the two and is printed before hashcat starts
* Output is written beside the hash file in `<hash file>.rosetta/` as `basewords.txt` and `rules.rule`, alongside the other ephemeral wordlists, and the directory is removed on exit by the temp-file cleanup
* Reading stops at 1,000,000 debug lines, since the analyzer needs the whole batch in memory at once. Truncation is reported on the console rather than assumed harmless — logs from a long run routinely exceed this, in which case the newest log is the one worth selecting
* **LLM Mask Attack** (4) - a different mode entirely, and the only one that needs no debug logs. Prompts for a natural-language description of the passwords you expect (length, character patterns, symbols, etc.), sends it to the locally configured Ollama model, writes the returned masks to `<hash file>.hcmask`, and runs a `-a 3` hashcat mask attack against them

#### Corporate Masks Brute Force
Statistical masks (8-14 characters) derived from analysis of 3.2M NTLM hashes cracked on real engagements. Powered by [Corporate_Masks](https://github.com/golem445/Corporate_Masks), these masks encode realistic password patterns from successful penetration tests.

* Prompts for minimum and maximum mask length (default 8-10)
* Longer lengths cost exponentially more keyspace—start with 8-10 for speed, or 8-12 for thoroughness
* Each mask file is run as a separate hashcat invocation in ascending length order
* Gracefully handles missing mask files (skips them) and absent submodule (prints warning and returns)
* Supports optimized kernels (`-O` flag) for faster cracking
* Ctrl-C during one length aborts remaining lengths

#### Wordlist Tools (option 80)
A submenu of wordlist preprocessing utilities using hashcat-utils binaries. All tools read from and write to files on disk. All file and directory path prompts support tab completion.

| Key | Tool | Description |
|-----|------|-------------|
| 1 | Filter by Length | Keep only words between a min and max length (`len.bin`) |
| 2 | Require Char Classes | Keep words that include all char classes in mask (`req-include.bin`). Mask: 1=lower, 2=upper, 4=digit, 8=symbol (additive) |
| 3 | Exclude Char Classes | Remove words containing any char class in mask (`req-exclude.bin`). Same mask encoding |
| 4 | Extract Substring | Cut bytes from each word at a given offset and optional length (`cutb.bin`) |
| 5 | Split by Length | Create per-length files in an output directory (`splitlen.bin`) |
| 6 | Subtract Wordlist | Remove lines from a wordlist that appear in one or more remove files. Mode 1 uses `rli2.bin` (single file); mode 2 uses `rli.bin` (multiple files) |
| 7 | Shard Wordlist | Split a wordlist into N equal, interleaved parts in one run, written as `base.001`…`base.00N` for distributed cracking (`gate.bin`) |
| 8 | Optimize Wordlists | Dedupe and split the selected wordlists into per-length files under an output directory |
| 9 | Download from Hashmob.net | Browse and download wordlists from Hashmob.net into the configured wordlist directory |
| 10 | Download from Weakpass | Browse and download Weakpass wordlist torrents, with automatic extraction |
| 11 | Hashmob Downloads | Access a submenu for downloading Hashmob archives (yearly full-found corpora) and combined-left lists (per-mode uncracked hashes) |

All binaries are in `hate_crack/hashcat-utils/bin/`.

#### Rule File Tools (option 81)
Preprocesses hashcat rule files using `cleanup-rules.bin` and `rules_optimize.bin` from hashcat-utils, and downloads rule files from Hashmob.net.

* **Clean** (1) - removes invalid syntax and duplicate rules using `cleanup-rules.bin`. Useful after combining rule files or downloading rules from external sources.
* **Optimize** (2) - consolidates redundant operations using `rules_optimize.bin`. Reduces rule file size and improves cracking speed.
* **Clean and optimize** (3) - runs both operations in sequence via a temporary file, then writes the final result.
* **Download rules from Hashmob.net** (4) - fetches rule files into the configured `rulesDirectory`.
* **Analyze Hashcat rules** (5) - opcode frequency analysis of a rule file, powered by HashcatRosetta.

The three preprocessing operations read from an input file and write to a separate output file (original is never modified).

#### Download Rules from Hashmob.net (Rule File Tools option 4)
Downloads the latest rule files from Hashmob.net's rule repository. These rules are curated and optimized for password cracking and can be used with the Quick Crack and Loopback Attack modes.

* Downloads rule sets in parallel using a thread pool (up to 4 concurrent downloads)
* Skips rules already downloaded locally
* Reports download summary with success/failure counts
* Stores rules in the configured rules directory

#### Analyze Hashcat Rules (Rule File Tools option 5)
Powered by HashcatRosetta (https://github.com/bandrel/HashcatRosetta), this feature analyzes hashcat rule files to provide detailed insights into rule composition and complexity.

* Prompts for a rule file path
* Displays frequency analysis of rule opcodes (operations)
* Helps understand what transformations a rule set performs
* Useful for rule debugging and optimization

#### Mask Tools (option 83)
Downloads mask files from Hashmob.net. This is a minimal submenu today — masks
have no local file-tooling counterpart to the rule/wordlist cleanup and
optimization utilities, only a download capability.

* **Download masks from Hashmob.net** (1) - fetches mask files into the hate_crack masks directory.

#### Download Masks from Hashmob.net (Mask Tools option 1)
Downloads mask files from Hashmob.net's mask repository into the hate_crack masks directory for use with mask-based attacks.

* Downloads mask sets in parallel using a thread pool (up to 4 concurrent downloads)
* Skips masks already downloaded locally
* Reports download summary with success/failure counts
* Stores masks in the configured masks directory used by the Ad-hoc Mask Attack
* Supports interactive listing, range selection, and browsing of available mask files

#### Download Wordlists from Hashmob.net (Wordlist Tools option 9)
Downloads wordlists from Hashmob.net's collection of cracked passwords and commonly used wordlists.

* Interactive menu for browsing available wordlists
* Progress tracking for large downloads
* Stores wordlists in configured wordlist directory

#### Weakpass Wordlist Menu (Wordlist Tools option 10)
Interactive menu for downloading and managing wordlists from Weakpass.com via BitTorrent.

* Browse available Weakpass wordlist torrents
* Download specific wordlists or entire collections
* Automatic extraction of compressed archives
* Progress tracking for torrent downloads

#### Hashmob Downloads (Wordlist Tools option 11)
Access a submenu for downloading large-scale password corpora and specialized wordlists from Hashmob.net.

**Archives** - Downloads yearly full-found password corpora (multi-GB archives containing all cracked passwords from a given year)
* Requires confirmation before downloading -- these archives are large (the listing may show "(unknown size)" since Hashmob's API doesn't currently report a file size per archive)
* Lists all available archives across every year as one globally-numbered list to browse and pick from by index, rather than a per-year picker
* Accepts `a` (or `all`) at the selection prompt to download every listed archive, one at a time. A single confirmation naming the archive count and the summed size covers the whole batch; an archive already on disk at its listed size is skipped, one whose size does not match is re-downloaded, and a failure is counted rather than aborting the rest
* Stores archives in the configured wordlist directory for extraction and use

**Combined Left Lists** - Downloads per-hashcat-mode combined lists of uncracked ("left") hashes from Hashmob.net
* Each list is a set of hashes, not plaintexts, still awaiting a crack for that hashcat mode
* Useful for spotting overlap between your own hash list and hashes the community hasn't cracked yet
* Supports mode selection from the listed hash counts per algorithm

-------------------------------------------------------------------
### Version History

The full, per-release changelog now lives in [CHANGELOG.md](https://github.com/trustedsec/hate_crack/blob/main/CHANGELOG.md).