# Hashcat MCP Server

An AI-powered password hash auditing assistant that combines a **local LLM** 
with **Hashcat** through the **Model Context Protocol (MCP)**.

Built for authorized security audits — the LLM autonomously identifies hash 
types, selects attack strategies, escalates through multiple approaches, and 
reports results in plain English. All processing is local — no data leaves 
your machine.

---

## Architecture

```
User (natural language)
        ↓
Local LLM — qwen2.5 via Ollama
  (decides which tools to call and with what arguments)
        ↓
MCP Client — bridges LLM decisions to real tool execution
        ↓
MCP Server — exposes Hashcat as structured tools
        ↓
Hashcat — performs actual password recovery
        ↓
Results logged to results/session_log.json
```

---

## Tools

| Tool | Description |
|---|---|
| `identify_hash` | Identifies hash algorithm from format/length (MD5, NTLM, SHA-1, bcrypt etc.) |
| `list_wordlists` | Lists available wordlists and rule files on the system |
| `run_hashcat` | Cracks a single hash with configurable attack mode and wordlist |
| `crack_batch` | Cracks multiple hashes from a file with automatic escalation |

### Attack Escalation (automatic)
The LLM follows this sequence for every hash automatically:
1. Dictionary attack — `10k-common` wordlist
2. Rule-based attack — `100k-ncsc` + `best66.rule`
3. Hybrid attack — `100k-ncsc` + 4-digit mask (`?d?d?d?d`)
4. Larger wordlist — `000webhost`

---

## Stack

| Component | Version | Purpose |
|---|---|---|
| Hashcat | v7.1.2 | Password recovery engine |
| Ollama | latest | Local LLM runtime |
| qwen2.5 | 7B | Tool-calling capable LLM |
| FastMCP (Python) | latest | MCP server framework |
| WSL2 Ubuntu | 24.x | Linux environment on Windows |

---

## Setup

### Prerequisites
- Windows with WSL2 + Ubuntu
- Ollama installed (`curl -fsSL https://ollama.com/install.sh | sh`)
- Hashcat installed (`sudo apt install hashcat`)
- SecLists cloned (`git clone --depth 1 https://github.com/danielmiessler/SecLists.git ~/SecLists`)

### Install

```bash
git clone https://github.com/YOUR_USERNAME/hashcat-mcp.git
cd hashcat-mcp
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

### Pull the LLM

```bash
ollama pull qwen2.5:latest
```

---

## Usage

### Start the assistant

```bash
cd hashcat-mcp
source venv/bin/activate
python3 mcp_client.py
```

### Crack a single hash

```
You: crack this hash: 482c811da5d5b4bc6d497ffa98491e38
Assistant: [calls identify_hash → MD5 identified]
           [calls run_hashcat → password123 found]
           The password is: password123
```

### Crack a batch file

Create a file with one hash per line, or `username:hash` format:
```
admin:e90664c0af74160644d29e4d6147969b
user1:5f4dcc3b5aa765d61d8327deb882cf99
482c811da5d5b4bc6d497ffa98491e38
```

Then ask:
```
You: crack all hashes in /home/user/hashes.txt — they are MD5
```

Output:
```
==================================================
BATCH CRACK SUMMARY
==================================================
Total hashes:   3
Cracked:        3 (100.0%)
Not cracked:    0
==================================================
RESULTS:
  ✓ admin      → Summer2024
  ✓ user1      → password
  ✓ (hash)     → password123
==================================================
Full results saved to: results/session_log.json
```

---

## Session Logging

Every crack attempt is automatically logged to `results/session_log.json`:

```json
{
  "timestamp": "2026-08-19T19:33:27.932857",
  "username": "admin",
  "hash": "e90664c0af74160644d29e4d6147969b",
  "hash_mode": 0,
  "cracked": true,
  "password": "Summer2024",
  "attack_used": "mode 6 wordlist=100k-ncsc mask=?d?d?d?d"
}
```

---

## Supported Hash Types

| Algorithm | Hashcat Mode | Example Format |
|---|---|---|
| MD5 | `-m 0` | `482c811da5d5b4bc6d497ffa98491e38` |
| NTLM | `-m 1000` | `cc36cf7aa9dc7f2d2c2c43f877c32b0c` |
| SHA-1 | `-m 100` | `cbfdac6008f9cab4083784cbd1874f76618d2a97` |
| SHA-256 | `-m 1400` | `ef92b779...` (64 chars) |
| bcrypt | `-m 3200` | `$2a$10$...` |
| sha512crypt | `-m 1800` | `$6$...` |

---

## Security & Ethics

This tool is designed exclusively for **authorized password security audits**:
- Testing organizational password strength against real-world attack methods
- Identifying weak passwords before attackers do
- Generating evidence for security policy enforcement

**Never use this tool on hashes you do not have explicit authorization to audit.**

---

## Project Structure

```
hashcat-mcp/
├── mcp_server.py        # MCP server — exposes Hashcat as tools
├── mcp_client.py        # MCP client — connects LLM to server
├── prompts/
│   └── system_prompt.txt  # LLM behavior instructions
├── hashes/              # Hash files for testing
├── results/
│   └── session_log.json   # Automatic audit log
└── requirements.txt
```