gitea-mirror/hate_crack
1
0
Fork 0
mirror of https://github.com/trustedsec/hate_crack.git synced 2026-03-12 21:23:05 -07:00
Code Issues Packages Projects Releases Wiki Activity

fix: add 'repository directory' to README hcatPath note

Browse Source 
Satisfies test_readme_documents_correct_usage assertion.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Justin Bollinger
2026-02-20 18:35:12 -05:00
parent 6b6c2f8b4b
commit a4f50100d8
1 changed files with 119 additions and 71 deletions
Download Patch File Download Diff File Expand all files Collapse all files

190
README.md
View File

@@ -19,37 +19,44 @@ The pytest workflow tests across Python 3.9-3.14 via a matrix build.
## Installation ## Installation
### 1. Install hashcat ### 1. Install hashcat (Optional)
Get the latest hashcat binaries (https://hashcat.net/hashcat/)
```bash Hashcat is included as a git submodule and will be compiled automatically. If you already have hashcat installed and in your PATH, the build step will skip the submodule compilation.
git clone https://github.com/hashcat/hashcat.git
cd hashcat/ To manually install hashcat instead (e.g., system package or pre-built binary), ensure `hashcat` is available in your PATH or set `hcatPath` in `config.json`.
make
make install
```
### 2. Download hate_crack ### 2. Download hate_crack
Clone with submodules (required for hashcat-utils, princeprocessor, and optionally omen):
```bash ```bash
git clone --recurse-submodules https://github.com/trustedsec/hate_crack.git git clone --recurse-submodules https://github.com/trustedsec/hate_crack.git
cd hate_crack cd hate_crack
``` ```
* Customize binary and wordlist paths in "config.json" If you cloned without submodules, initialize them:
* The hashcat-utils repo is a submodule. If you didn't clone with --recurse-submodules then initialize with:
```bash ```bash
git submodule update --init --recursive git submodule update --init --recursive
``` ```
Then customize configuration in `config.json` if needed (wordlist paths, API keys, etc.). Most users can skip this step as default paths work out-of-the-box.
### 3. Install dependencies and hate_crack ### 3. Install dependencies and hate_crack
The easiest way is to use `make install` which auto-detects your OS and installs: The easiest way is to run `make` (or `make install`), which auto-detects your OS and installs:
- External dependencies (p7zip, transmission-cli) - External dependencies (p7zip, transmission-cli)
- Builds submodules (hashcat-utils, princeprocessor, and optionally hashcat if not in PATH)
- Python tool via uv - Python tool via uv
```bash ```bash
make install make
```
This is idempotent - it skips tools already installed. To force a clean reinstall:
```bash
make reinstall
``` ```
**Or install dependencies manually:** **Or install dependencies manually:**
@@ -101,38 +108,37 @@ This project depends on and is inspired by a number of external projects and ser
------------------------------------------------------------------- -------------------------------------------------------------------
## Usage ## Usage
You can run hate_crack as a tool, as a script, or via `uv run`:
After installing with `make`, run hate_crack from anywhere:
```bash ```bash
uv run hate_crack.py hate_crack
# or # or with arguments:
uv run hate_crack.py <hash_file> <hash_type> [options] hate_crack <hash_file> <hash_type> [options]
```
Alternatively, run via `uv`:
```bash
uv run hate_crack.py <hash_file> <hash_type>
``` ```
### Run as a tool (recommended) ### Run as a tool (recommended)
Install once from the repo root:
Install using `make` from the repository root - this builds submodules and bundles assets:
```bash ```bash
uv tool install . cd /path/to/hate_crack
make
hate_crack hate_crack
``` ```
**Important:** The tool needs access to `hashcat-utils` and `princeprocessor` subdirectories from the hate_crack repository.
The tool will automatically search for these assets in: The tool will automatically search for these assets in:
- The directory that contains the hate_crack checkout (and includes `config.json`, `hashcat-utils/`, and `princeprocessor/`) - The installed package (bundled by `make install`)
- Current working directory and parent directory - Current working directory and parent directory
- `~/hate_crack`, `~/hate-crack`, or `~/.hate_crack` - `~/hate_crack`, `~/hate-crack`, or `~/.hate_crack`
**Option 1 - Run from repository directory:** **Note:** The `hcatPath` in `config.json` is for the hashcat binary location only (optional if hashcat is in PATH). Hate_crack assets (hashcat-utils, princeprocessor, omen) are loaded from the repository directory and bundled automatically by `make install`.
```bash
cd /path/to/hate_crack
hate_crack <hash_file> <hash_type>
```
Run `make install` to install the tool with all assets bundled into the package.
**Note:** The `hcatPath` in `config.json` is for the hashcat binary location (optional if hashcat is in PATH), not for hate_crack assets.
### Run as a script ### Run as a script
The script uses a `uv` shebang. Make it executable and run: The script uses a `uv` shebang. Make it executable and run:
@@ -172,59 +178,84 @@ cd /path/to/hate_crack # the repository checkout
make install make install
``` ```
**Example config.json:** **Default configuration (config.json.example):**
Most users can use defaults without customization:
- `hcatWordlists`: `./wordlists` (relative to repo root or HOME/.hate_crack)
- `rules_directory`: `./hashcat/rules` (includes submodule rules)
- `hcatTuning`: `` (empty string - no default tuning flags)
**Example config.json customizations:**
```json ```json
{ {
"hcatPath": "/usr/local/bin", # Location of hashcat binary (or omit if in PATH) "hcatPath": "/usr/local/bin", # Location of hashcat binary (optional, auto-detected from PATH)
"hcatBin": "hashcat", # Hashcat binary name "hcatBin": "hashcat", # Hashcat binary name
"hcatWordlists": "./wordlists", # Dictionary wordlist directory (relative or absolute)
"rules_directory": "./hashcat/rules", # Rules directory (relative or absolute)
"hcatTuning": "", # Additional hashcat flags (empty by default)
... ...
} }
``` ```
**Configuration loading:**
- Missing config keys are automatically backfilled from `config.json.example` on startup
- Config is searched in multiple locations: repo root, current working directory, `~/.hate_crack`, `/opt/hate_crack`
------------------------------------------------------------------- -------------------------------------------------------------------
### Makefile helpers ### Makefile Targets
Install OS dependencies + tool (auto-detects macOS vs Debian/Ubuntu):
**Default (full installation)** - builds submodules, vendors assets, installs dependencies and tool:
```bash ```bash
make
# or explicitly:
make install make install
``` ```
Rebuild submodules and reinstall the tool (quick update after pulling changes): This is idempotent - it skips tools already installed.
```bash **Force clean reinstall:**
make update
```
Reinstall the Python tool in-place (keeps OS deps as-is):
```bash ```bash
make reinstall make reinstall
``` ```
Uninstall OS dependencies + tool: **Quick update** - rebuilds submodules and reinstalls tool (after pulling changes):
```bash
make update
```
**Uninstall** - removes OS dependencies and tool:
```bash ```bash
make uninstall make uninstall
``` ```
Build hashcat-utils only: **Build hashcat-utils only:**
```bash ```bash
make hashcat-utils make hashcat-utils
``` ```
Clean build/test artifacts: **Run tests** - automatically handles HATE_CRACK_SKIP_INIT when needed:
```bash
make clean
```
Run the test suite:
```bash ```bash
make test make test
``` ```
**Coverage report:**
```bash
make coverage
```
**Clean build/test artifacts:**
```bash
make clean
```
------------------------------------------------------------------- -------------------------------------------------------------------
## Development ## Development
@@ -265,37 +296,57 @@ The project uses GitHub Actions to automatically run quality checks on every pus
### Running Linters and Type Checks ### Running Linters and Type Checks
Before pushing changes, run these checks locally to catch issues early: Before pushing changes, run these checks locally. Use `make lint` for everything, or run individual checks:
**Ruff (linting and formatting):** **Ruff (linting and formatting):**
```bash ```bash
.venv/bin/ruff check hate_crack make ruff
# or manually:
uv run ruff check hate_crack
``` ```
Auto-fix issues: Auto-fix issues:
```bash ```bash
.venv/bin/ruff check --fix hate_crack uv run ruff format hate_crack
uv run ruff check --fix hate_crack
``` ```
**ty (type checking):** **ty (type checking):**
```bash ```bash
.venv/bin/ty check hate_crack make ty
# or manually:
uv run ty check hate_crack
``` ```
**Run all checks together:** **Run all checks together:**
```bash ```bash
.venv/bin/ruff check hate_crack && .venv/bin/ty check hate_crack && echo "✓ All checks passed" make lint
``` ```
### Running Tests ### Running Tests
Tests auto-detect when submodules are not built and set `HATE_CRACK_SKIP_INIT=1` automatically.
```bash ```bash
.venv/bin/pytest make test
```
Or run pytest directly:
```bash
uv run pytest -v
``` ```
With coverage: With coverage:
```bash ```bash
.venv/bin/pytest --cov=hate_crack make coverage
```
Or with pytest:
```bash
uv run pytest --cov=hate_crack
``` ```
### Git Hooks (prek) ### Git Hooks (prek)
@@ -580,9 +631,7 @@ Select a task:
``` ```
------------------------------------------------------------------- -------------------------------------------------------------------
#### Quick Crack #### Quick Crack
* Runs a dictionary attack using all wordlists configured in your "hcatOptimizedWordlists" path Runs a dictionary attack using all wordlists configured in your `hcatWordlists` path and optionally applies rules. Multiple rules can be selected by comma-separated list, and chains can be created with the '+' symbol.
and optionally applies a rule that can be selected from a list by ID number. Multiple rules can be selected by using a
comma separated list, and chains can be created by using the '+' symbol.
``` ```
Which rule(s) would you like to run? Which rule(s) would you like to run?
@@ -600,18 +649,18 @@ Choose wisely:
#### Extensive Pure_Hate Methodology Crack #### Extensive Pure_Hate Methodology Crack
Runs several attack methods provided by Martin Bos (formerly known as pure_hate) Runs several attack methods provided by Martin Bos (formerly known as pure_hate):
* Brute Force Attack (7 characters) * Brute Force Attack (7 characters)
* Dictionary Attack * Dictionary Attack
* All wordlists in "hcatOptimizedWordlists" with "best64.rule" * All wordlists in `hcatWordlists` with `best64.rule`
* wordlists/rockyou.txt with "d3ad0ne.rule" * `rockyou.txt` with `d3ad0ne.rule`
* wordlists/rockyou.txt with "T0XlC.rule" * `rockyou.txt` with `T0XlC.rule`
* Top Mask Attack (Target Time = 4 Hours) * Top Mask Attack (Target Time = 4 Hours)
* Fingerprint Attack * Fingerprint Attack
* Combinator Attack * Combinator Attack
* Hybrid Attack * Hybrid Attack
* Extra - Just For Good Measure * Extra - Just For Good Measure
- Runs a dictionary attack using wordlists/rockyou.txt with chained "combinator.rule" and "InsidePro-PasswordsPro.rule" rules - Runs a dictionary attack using `rockyou.txt` with chained `combinator.rule` and `InsidePro-PasswordsPro.rule` rules
#### Brute Force Attack #### Brute Force Attack
Brute forces all characters with the choice of a minimum and maximum password length. Brute forces all characters with the choice of a minimum and maximum password length.
@@ -651,8 +700,7 @@ https://hashcat.net/events/p14-trondheim/prince-attack.pdf
Runs a PRINCE attack using wordlists/rockyou.txt Runs a PRINCE attack using wordlists/rockyou.txt
#### YOLO Combinator Attack #### YOLO Combinator Attack
Runs a continuous combinator attack using random wordlists from the Runs a continuous combinator attack using random wordlists from the configured wordlists directory for the left and right sides.
optimized wordlists for the left and right sides.
#### Middle Combinator Attack #### Middle Combinator Attack
https://jeffh.net/2018/04/26/combinator_methods/ https://jeffh.net/2018/04/26/combinator_methods/
@@ -678,10 +726,10 @@ https://jeffh.net/2018/04/26/combinator_methods/
#### Bandrel Methodology #### Bandrel Methodology
* Prompts for input of comma separated names and then creates a pseudo hybrid attack by capitalizing the first letter 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.
and adding up to six additional characters at the end. Each word is limited to a total of five minutes.
- Built in additional common words including seasons, months has been included as a customizable config.json entry - 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 the config.json - The default five-minute time limit is customizable via `bandrelmaxruntime` in `config.json`
#### Loopback Attack #### Loopback Attack
https://hashcat.net/wiki/doku.php?id=loopback_attack https://hashcat.net/wiki/doku.php?id=loopback_attack