___ ___         __             _________                       __
 /   |   \_____ _/  |_  ____     \_   ___ \____________    ____ |  | __
/    ~    \__  \\   __\/ __ \    /    \  \/\_  __ \__  \ _/ ___\|  |/ /
\    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)
- 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을 생성하며, 이 shim은 리포지토리 디렉토리에서 실행되므로 현재 작업 디렉토리와 관계없이 구성(config) 및 자산(assets)을 항상 찾을 수 있습니다.

구성(config)은 다음 위치에서도 검색됩니다:
- 리포지토리 루트 및 패키지 디렉토리
- `~/.hate_crack`

**참고:** `config.json`의 `hcatPath`는 hashcat 바이너리 위치만을 위한 것입니다 (hashcat이 PATH에 있으면 선택 사항). Hate_crack 자산(hashcat-utils, princeprocessor, pcfg_cracker, 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

This means the hate_crack assets were not bundled into the installed package.

**경로 이해하기:**
- `hcatPath` in config.json → **hashcat 바이너리 위치**를 가리킵니다 (선택 사항, PATH에 있을 수 있음)
- `hashcat-utils/` 및 `princeprocessor/` → `make install`로 패키지에 번들됩니다.

**해결 방법:**
Makefile을 사용하여 다시 설치하세요. 이 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은 해당 파일을 직접 편집하지 않습니다.
- 매 실행마다 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 훅은 [prek](https://github.com/j178/prek) (v0.3.3+)으로 관리됩니다. 다음 명령으로 훅을 설치하세요:```bash
prek install --hook-type pre-push --hook-type pre-commit

메뉴 옵션:
- **(1) 크랙된 해시 업로드** - 현재 세션의 크랙된 결과를 Hashview에 업로드
- **(2) 워드리스트 업로드** - 워드리스트 파일을 Hashview에 업로드
- **(3) 워드리스트 다운로드** - Hashview에서 워드리스트 다운로드
- **룰 다운로드** - Hashview에서 룰 파일 다운로드 (일반 텍스트로 압축 해제되어 `hashcat -r`에 사용 가능)
- **(4) 남은 해시 다운로드** - 크랙되지 않은 남은 해시 다운로드 (크랙을 위해 전환할지 묻는 메시지 표시)
- **(5) 발견된 해시 다운로드** - 이미 크랙된 해시와 평문 비밀번호 다운로드 (참고/분석용)
- **(6) 해시파일 업로드 및 작업 생성** - 새 해시파일을 업로드하고 크랙 작업 생성
- **(99) 메인 메뉴로 돌아가기** - 메인 메뉴로 돌아가기

**중요: 발견된 해시 다운로드 vs 남은 해시 다운로드**
- **남은 해시 다운로드 (4)**: 크랙이 필요한 크랙되지 않은 해시를 다운로드합니다. 사용 가능한 발견된 해시가 있으면 자동으로 병합하고, 크랙을 위해 이 해시파일로 전환할지 묻는 메시지를 표시합니다.
- **발견된 해시 다운로드 (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

- **`OLLAMA_MODEL`** — 후보 생성에 사용되는 Ollama 모델(기본값: `qwen2.5:32b`). 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`으로 취급됩니다.

  코퍼스 기반 모드(**단어 목록**, **크랙된 비밀번호**, **패턴 규칙**)는 항상 *전체* 코퍼스를 통계적으로 설명합니다 — 기본 단어 비중, 마스크, 대소문자, 길이, 끝자리 숫자와 기호, 연도 — 그중 일부만 붙여넣는 대신. 집계에는 상한이 있으므로 120,000개 비밀번호 덤프도 500줄 덤프와 거의 같은 프롬프트 공간을 차지합니다. 전체 코퍼스가 이 임계값 이하이면 원본 평문도 함께 포함됩니다. 작은 코퍼스를 모델에게 숨겨봐야 얻을 이점이 없기 때문입니다.

  이는 최대 `ollamaMaxSampleLines`개의 비밀번호를 균등한 간격으로 샘플링하여 붙여넣던 이전 동작을 대체합니다. 대형 덤프의 샘플은 빈도 정보를 전혀 전달하지 못했습니다. 모델은 조직의 8%가 사용하는 기본 단어와 한 사람만 사용하는 기본 단어를 구분할 수 없기 때문인데, 바로 그 신호가 추측을 실행할 가치가 있게 만드는 요소입니다.
- **`OLLAMA_NO_CLOUD`** — `true`이면 Ollama *클라우드* 모델에 무엇이든 보내기를 거부합니다. Ollama는 `-cloud` 태그가 붙은 모델(`gpt-oss:120b-cloud`, `deepseek-v3.1:671b-cloud`)을 로컬 모델이 사용하는 것과 동일한 로컬 엔드포인트를 통해 ollama.com으로 프록시하므로 요청이 전혀 다르게 보이지 않습니다 — 하지만 hate_crack의 프롬프트에는 복구된 평문, 코퍼스 통계, 고객사 이름, 산업, 위치가 포함됩니다. 이 값을 설정하면 요청이 구성되기 전에 클라우드 모델 이름이 거부됩니다. 기본값은 `false`이므로 의도적으로 구성된 클라우드 모델은 계속 작동합니다. 클라이언트 데이터가 호스트를 벗어나면 안 되는 작업에서는 이 옵션을 켜세요.
- **`OLLAMA_AUTO_RESEARCH`** — `true`(기본값)일 때 **대상 정보** 모드는 회사 이름을 입력하는 즉시 로컬 모델에게 산업과 위치를 추천하도록 요청하고, 이를 편집 가능한 프롬프트 기본값으로 제공합니다. `false`로 설정하면 항상 빈 프롬프트가 나타납니다(모델이 느릴 때 유용합니다. 공격이 시작되기 전에 조사에 필요한 왕복 요청이 한 번 더 발생하기 때문입니다).
- **`OLLAMA_HOST`** — Ollama가 수신 대기하는 위치입니다. 스킴 없는 `host:port`(`theplague.lan:11434`) 또는 스킴이 포함된 전체 URL(`https://ollama.example.com`)을 허용합니다. 어느 쪽이든 기본 URL은 사용 전에 정규화됩니다. 기본값은 `localhost:11434`입니다. `.env`에 설정하거나 실제 환경 변수로 내보내면 단일 실행에서 해당 값을 덮어쓸 수 있습니다 — 이것은 Ollama 자체 CLI가 읽는 것과 동일한 변수 이름입니다.
- LLM 공격을 사용하기 전에 Ollama가 실행 중이고 모델이 내려받아져 있는지 확인하세요(`ollama pull qwen2.5:32b`) — hate_crack은 더 이상 누락된 모델을 자동으로 내려받지 않습니다.

이 공격은 세 가지 생성 모드를 제공합니다:

1. **대상 정보** — 회사 / 산업 / 위치; 모델은 이러한 세부 정보에서 후보를 도출합니다.

   회사 이름을 입력하면 hate_crack은 동일한 로컬 모델에게 해당 조직에 대해 이미 알고 있는 내용을 묻고, **산업** 및 **위치** 프롬프트에 답변을 미리 채웁니다. 답변은 괄호 안에 표시됩니다:   ```
   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):

연구 실패 — 시간 초과, Ollama가 실행 중이 아님, 빈 응답 — 는 공격을 차단하지 않습니다. 단지 빈 프롬프트로 대체될 뿐입니다. 연구를 완전히 건너뛰려면 `ollamaAutoResearch`를 `false`로 설정하세요.
2. **Wordlist** — 샘플 워드리스트에서 기본 단어를 도출합니다.
3. **크래킹된 비밀번호** — 이 세션에서 이미 복구된 평문(`<hashfile>.out`)을 모델에 다시 공급하여 대상 조직의 자체 비밀번호 규칙(기본 단어, 계절, 연도, 접미사, leetspeak)을 추론하고 동일한 스타일의 *새* 후보를 생성하도록 합니다. 이 옵션은 하나 이상의 해시가 크래킹된 후에만 표시됩니다. 전체 파일은 Wordlist 모드와 똑같이 통계적으로 분석됩니다(위의 `ollamaMaxSampleLines` 참조).

#### PCFG 구성

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

- **`check_for_updates`** — 시작 시 자동 버전 확인을 활성화합니다(기본값: `true`).
- 활성화하면 hate_crack이 GitHub에서 최신 릴리스 정보를 가져와 업데이트가 있으면 공지를 표시합니다.
- 이 확인은 비동기적으로 실행되며 시작을 차단하지 않습니다. 네트워크 오류는 조용히 무시됩니다.

##### 업데이트 채널

| 채널 | 플래그 | 소스 | 받는 내용 |
|---------|------|--------|--------------|
| 릴리스 | `--update` | `main` | 최신 정식 릴리스입니다. 기본값이며 시작 시 확인에서 제공하는 항목입니다. |
| 나이틀리 | `--nightly` | `nightly-dev` | CI를 통과했지만 아직 릴리스되지 않은 작업입니다. |

버전은 일반적인 semver 규칙을 따르며, 버전 상향은 배치에 실제로 포함된 내용에 따라 결정됩니다.
두 번째 구성 요소는 **기능에 대해서만** 변경됩니다. `feat` 커밋이 포함된 사이클은 `X.(Y+1).0`을 향하고, 수정(fix), 문서(docs), 잡일(chore)만 있는 사이클은 `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`에서 단위 테스트됩니다.

시작 시 확인은 항상 릴리스만 제공합니다. 나이틀리 빌드는 GitHub 릴리스를 전혀 게시하지 않고, 확인은 GitHub의 "latest release" 엔드포인트를 읽기 때문입니다. 따라서 `check_for_updates`를 활성화해도 나이틀리로 전환되지 않습니다. 현재 채널을 구분하는 두 가지 요소는 그것과, 후보가 실제 PEP 440 사전 릴리스이므로 원시 버전 번호를 비교하는 도구에서도 릴리스보다 이전 버전으로 취급된다는 점입니다.

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

#### 자동 발견 해시 병합(왼쪽 해시 다운로드 전용)

왼쪽 해시(크랙되지 않은 해시)를 다운로드할 때 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

## 테스팅

테스트 스위트는 대부분 오프라인이며 목(mocks)/픽스처(fixtures)를 사용합니다. 실시간 네트워크 검사 및 시스템 종속성 검사는 환경 변수를 통해 옵트인 방식으로 활성화됩니다.

### 로컬에서 테스트 실행하기```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 스택을 시작하고, 시드(seed)한 다음, 그에 대해 라이브 테스트를 실행하고, 종료하도록 할 수 있습니다. `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

The test 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
  * 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.

#### 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 several hybrid attacks using the "rockyou.txt" wordlists.
  - Hybrid Wordlist + Mask - ?s?d wordlists/rockyou.txt ?1?1
  - Hybrid Wordlist + Mask - ?s?d wordlists/rockyou.txt ?1?1?1
  - Hybrid Wordlist + Mask - ?s?d wordlists/rockyou.txt ?1?1?1?1
  - Hybrid Mask + Wordlist - ?s?d ?1?1 wordlists/rockyou.txt
  - Hybrid Mask + Wordlist - ?s?d ?1?1?1 wordlists/rockyou.txt
  - Hybrid Mask + Wordlist - ?s?d ?1?1?1?1 wordlists/rockyou.txt

#### 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 Ollama instance to generate password candidates for a capture-the-flag scenario. Prompts for the fake company name, industry, and location, 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 Ollama instance (default: `http://localhost:11434`, override with `OLLAMA_HOST` in `.env` or the environment) with the model already pulled — hate_crack does not auto-pull
* Candidate generation uses structured (JSON) output via Atomic Agents, so pick a model with good schema adherence (default: `qwen2.5:32b`)
* Configurable model, context window, request timeout, and sample size via `.env` (see Ollama Configuration below)
* Prompts for target company name, industry, and location. The industry and location 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 (`-1`, `-2`, `-3`, `-4`) for specialized character combinations
* Interactive charset entry with early exit on blank input
* 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
* 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
* 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 (default 100) and how many top basewords (default all). Zero means unlimited for 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

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

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

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

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

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