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

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

하위 모듈 없이 클론한 경우, 초기화하세요:```bash
git submodule update --init --recursive

`.env.example`은 커밋되어 있으며 모든 자격 증명 키가 비어 있는 상태로 제공됩니다. `.env` 자체는 **절대** 커밋되어서는 안 됩니다 — gitignore 처리되어 있으며, 일반적인 백업 표기법도 함께 무시되고, hate_crack은 항상 모드 `0600`(소유자 읽기/쓰기 전용)으로 이를 생성합니다. `.env.example`은 스키마에서 생성됩니다. `hate_crack/config_schema.py`를 변경한 후 `uv run python -m hate_crack.config_writer`로 재생성하세요.

### 3. 의존성 및 hate_crack 설치

가장 쉬운 방법은 `make`(또는 `make install`)를 실행하는 것으로, 이는 OS를 자동 감지하고 다음을 설치합니다:
- 외부 의존성 (p7zip, transmission-daemon / transmission-remote)
- 서브모듈 빌드 (hashcat-utils, princeprocessor, pcfg_cracker, 선택적으로 omen) 및 데이터 전용 Corporate_Masks 마스크 세트 체크아웃
- uv를 통한 Python 의존성 및 `~/.local/bin/hate_crack`에 CLI 심(shim) 생성```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 shim을 설치하세요:```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을 생성하며, 이는 저장소 디렉터리에서 실행되므로 현재 작업 디렉터리와 관계없이 config와 assets를 항상 찾을 수 있습니다.

Config는 다음 위치에서도 검색됩니다:
- 저장소 루트 및 패키지 디렉터리
- `~/.hate_crack`

**참고:** `config.json`의 `hcatPath`는 hashcat 바이너리 위치 전용입니다(hashcat이 PATH에 있으면 선택 사항). Hate_crack assets(hashcat-utils, princeprocessor, pcfg_cracker, Corporate_Masks, omen)는 저장소 디렉터리에서 로드되며 `make install`에 의해 자동으로 번들됩니다.

### 스크립트로 실행
스크립트는 `uv` shebang을 사용합니다. 실행 권한을 부여하고 실행하세요:```bash
chmod +x hate_crack.py
./hate_crack.py

### 비대화형 / 스크립트 사용

자동화를 위해 메뉴를 건너뛰고 단일 공격을 직접 실행할 수 있습니다. 공격 이름이 첫 번째 인수이고, 그 뒤에 해시 파일과 hashcat 해시 유형이 옵니다. 전처리 프롬프트(컴퓨터 계정 필터링, LM 우선 브루트 포스, 중복 계정 중복 제거)는 이 모드에서 기본값을 자동으로 수락합니다. 프로세스는 성공 시 `0`, 오류(해시 파일 누락, 숫자가 아닌 해시 유형, 워드리스트 누락 또는 알 수 없는 규칙 파일 이름) 시 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` 키를 문서화합니다
- 두 파일 모두 서로 독립적으로 다음 순서로 검색됩니다: **repo 루트**, 그다음 **설치된 패키지 디렉터리**, 그다음 **`~/.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

**제거** - OS 종속성과 도구를 제거합니다:```bash
make uninstall

**테스트 실행** - 필요할 때 HATE_CRACK_SKIP_INIT를 자동으로 처리합니다:```bash
make test

**빌드/테스트 아티팩트 정리:**```bash
make clean

### 린터 및 타입 검사 실행

변경 사항을 푸시하기 전에 로컬에서 다음 검사를 실행하세요. 모든 검사를 실행하려면 `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 vs 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 토큰을 차지하므로, 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` 이름이 아닌) 목적지는 목적지로 거부되며, 이 검사가 확인할 수 없는 호스트명도 거부됩니다, fail-closed 방식으로, 검증할 수 없는 목적지를 통과시키지 않습니다. 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. **Wordlist** — 샘플 wordlist에서 basewords를 도출합니다.
3. **Cracked passwords** — 이 세션에서 이미 복구된 평문(`<hashfile>.out`)을 모델에 다시 입력하여 대상 조직 고유의 비밀번호 관례(basewords, 계절, 연도, 접미사, leetspeak)를 추론하고 동일한 스타일의 *새로운* 후보를 생성하도록 합니다. 이 옵션은 최소 하나의 해시가 크랙된 후에만 표시되며, 전체 파일은 Wordlist 모드와 정확히 동일하게 통계적으로 분석됩니다(위의 `ollamaMaxSampleLines` 참조).

#### PCFG 구성

PCFG Attack(옵션 20)과 PRINCE-LING Attack(옵션 21)은 `pcfg_cracker` 서브모듈을 사용합니다. `config.json`에서 구성하십시오:```json
{
"pcfgRuleset": "DEFAULT",
"pcfgMaxCandidates": 50000000,
"pcfgPrinceLingMaxCandidates": 10000000
}

`Y`를 입력하면 hate_crack이 아직 시도하지 않은 항목만 담은 임시 규칙 파일을 만들고, `n`을 입력하면 그대로 전체를 실행합니다. *모든* 항목이 반복 항목이라면 공격 자체를 건너뛸지 묻기 때문에, 이미 수행한 범위를 일부러 다시 실행할 때도 도구를 재시작할 필요가 없습니다.

필터링되지 않는 공격도 실행된 것으로 기록되며, 이를 통해 "이 대상에 PRINCE를 이미 실행했는가?"에 답할 수 있습니다.

여러 규칙 파일을 한 번에 선택하는 공격(Quick Crack, Loopback)은 hashcat 호출 전에 **배치 전체에 대해 한 번, 미리** 건너뛰기 질문을 합니다. 이 질문은 의도적으로 가볍게 설계되었습니다 — 선택된 규칙 파일을 읽거나 해시하지 않는데, YOLO 배치는 수백만 줄에 달할 수 있어 예/아니오에 답하기 위해 기다리게 해서는 안 되기 때문입니다. 이 질문은 이 공격이 **이 wordlist 중 하나로** 이 해시 파일에 대해 이미 실행된 적이 있는지만 저장소에 묻습니다. 항목별 비교는 여전히 규칙 파일 하나씩 지연 수행되며, 실제로 무엇을 건너뛸지 결정합니다. 따라서 새로운 코퍼스는 결코 플래그되지 않습니다. 그 규칙들이 모두 다른 코퍼스에 대해 실행된 적이 있더라도 마찬가지입니다.

세 가지 의도적인 제한:

- **커버리지는 hashcat이 keyspace를 소진했을 때만(종료 코드 1) 기록됩니다.** ctrl-C나 오류는 아무것도 기록하지 않으며, 종료 코드 0도 마찬가지입니다 — 이는 모든 해시가 크랙되었음을 의미하는데, hashcat은 keyspace를 끝내지 *않고* 이를 보고하며, "모든 해시가 potfile 항목으로 발견됨"이라는 퇴화된 경우에는 단일 후보도 시도하지 않고 보고합니다. 과소 기록은 나중에 중복 실행 비용만 발생시킵니다.
- **동적 후보 생성기는 결코 필터링되지 않습니다.** PRINCE, PCFG, OMEN, Markov 브루트 포스, LLM 모드는 비교할 고정 집합이 없으므로 실행된 것으로 기록되고 그 외에는 그대로 둡니다. 연쇄 규칙 파일(`-r a -r b`)은 항목별이 아니라 단일 단위로 추적되는데, hashcat이 두 파일의 *카테시안 곱*을 적용하기 때문에 개별 줄을 제거하면 그 줄이 참여한 모든 조합이 조용히 사라지기 때문입니다.
- **`--loopback` 실행은 기록되지만 결코 필터링되지 않습니다.** hashcat은 새로 크랙된 평문을 *추가* 후보로 다시 투입하므로, 이러한 실행은 전체 wordlist와 규칙 집합에 더해 재활용된 평문이 도달하는 모든 것을 시도합니다. 이로 인해 두 방향이 비대칭이 됩니다: 기록하는 것은 타당하므로, 나중에 같은 wordlist와 규칙의 일반 실행은 반복으로 올바르게 인식되지만, 두 번째 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은 *아무것도* 실행되지 않았음을 의미한다. 부분적으로 필터링된 패스 — 일부 항목은 건너뛰고 일부는 시도함 — 는 여전히 `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을 활성화하지 않는다 — 제외가 항상 우선한다.

**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` (서버가 `.ldmp`/`.admp` 덤프를 디스크에 쓰는 빈도에 대한 hashcat 자체 설정, 최소 60초, 기본값 `300`), 그리고 `brain_modes_force` / `brain_modes_exclude` (hashcat 자체의 느림/빠름 판정을 재정의하는 쉼표로 구분된 해시 모드 번호, 제외가 우선).

**자동 생성된 서버에는 유휴 타임아웃이 전혀 없다.** `brain_server_timer`는 서버가 얼마나 오래 유지되는지를 제어하지 않는다 — 아무것도 제어하지 않는다; 서버를 생성한 프로세스의 수명 동안 실행되며(또는 `shutdown()`/`atexit`이 중지할 때까지) 세션의 모든 공격에서 재사용된다. 기본값 `300`에서 이는 hate_crack이 실행되는 동안 5분마다 `~/.hate_crack/brain/`에 덤프를 쓴다는 의미이다.

여덟 번째 키인 `BRAIN_PASSWORD`는 brain이 서드파티 통합이기 때문이 아니라 공유 비밀이기 때문에 `config.json` 대신 `.env`에 있다 — 이미 실행 중인 원격 brain 서버에 연결할 때만 사용되며; 자동 생성된 로컬 서버는 세션마다 자체 무작위 비밀번호를 생성하므로 구성이 필요 없다.

**brain 비밀번호는 hashcat 실행이 지속되는 동안 `ps`에 노출된다,** hashcat이 이를 명령줄 인수로만 받아들이기 때문이다 — 환경 변수 형태는 없다. 로컬 자동 생성 서버의 경우 이는 작은 창이다: 비밀번호는 무작위이고 해당 세션에만 범위가 지정되므로, 다른 로컬 사용자는 공격이 실제로 실행 중일 때만 볼 수 있으며 세션이 끝나면 쓸모가 없다. 공유 원격 brain 서버의 비밀번호에는 그러한 완화가 없다 — 모든 호출에서 동일한 값이며, 해당 서버에 대한 hate_crack 실행이 진행 중인 동안 머신의 다른 로컬 사용자에게 보인다. 공유 또는 멀티테넌트 하드웨어에서는 그에 맞게 취급하라.

`brain_enabled`와 관계없이 단일 실행에 대해 brain을 비활성화하려면 `--no-brain`을 전달하거나, `config.json`에서 `brain_enabled`를 `false`로 설정하여 모든 곳에서 끄라.

**Brain은 `~/.hate_crack/brain/`에 상태를 유지한다** — hashcat 버전별 hashcat 자체의 느림/빠름 판정을 담은 작은 `slow_modes.json` 캐시, 그리고 자동 생성된 서버의 경우 `.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:` 푸터는 기능으로 간주되는데, 자동 major는 잘못 입력된 제목 한 줄로 되돌릴 수 없는 공개 릴리스가 될 수 있기 때문입니다. major는 명시적인 인간의 행위입니다: 직접 태그하고 푸시하십시오.

정책은 `tools/next_version.py`에 있으며, 두 태깅 워크플로에서 공유되고 `tests/test_next_version.py`에서 단위 테스트됩니다.

시작 확인은 릴리스만 제안합니다. nightly 빌드는 GitHub 릴리스를 전혀 게시하지 않고 확인은 GitHub의 "latest release" 엔드포인트를 읽기 때문입니다 — 따라서 `check_for_updates`를 활성화해도 nightly로 끌려가지 않습니다. 이제 두 가지가 채널을 분리합니다: 그것과, 후보가 진정한 PEP 440 사전 릴리스라는 사실, 즉 원시 버전 번호를 순위 매기는 도구도 후보를 그것이 되려는 릴리스보다 오래된 것으로 취급합니다.

어느 플래그든 먼저 체크아웃을 해당 브랜치로 전환합니다 (그리고 커밋되지 않은 변경 사항이 있으면 전환을 거부합니다). nightly를 실행 중이고 릴리스된 코드로 돌아가고 싶다면 `--update`가 `main`으로 되돌립니다.

#### 자동 발견 해시 병합 (Download Left Only)

left 해시(크랙되지 않은 해시)를 다운로드할 때 hate_crack은 자동으로:
1. 보조 작업으로 Hashview에서 발견된(크랙된) 해시를 다운로드하려고 시도합니다
2. 발견된 해시를 로컬 `.out` 파일과 병합합니다 (예: pwdump 형식의 경우 `left_1_123.txt.out` 또는 `left_1_123.nt.txt.out`)
3. 중복 항목을 제거합니다
4. 병합 후 임시 분할 파일을 정리합니다

이렇게 하면 크랙되지 않은 해시를 다룰 때 로컬 크래킹 결과가 Hashview의 중앙 집중식 데이터베이스와 동기화된 상태로 유지됩니다.

**참고:** download-found 옵션은 참조 목적으로 이미 크랙된 해시를 별도로 다운로드하며, 병합을 수행하거나 크래킹을 요청하지 않습니다.

<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

테스트 VM은 모든 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).