npm package: @modular-intelligence/hashcat
Description: MCP server wrapping hashcat for password hash analysis and cracking
Latest version: 1.0.2

# Hashcat MCP Server

A Model Context Protocol (MCP) server that wraps the hashcat password hash cracking tool, providing AI assistants with secure access to hash analysis and password recovery capabilities.

## Features

- **Hash Identification**: Automatically identify hash types by analyzing format and structure
- **Performance Benchmarking**: Measure hashcat performance on your hardware
- **Password Cracking**: Support for multiple attack modes (dictionary, brute force, hybrid)
- **Mask Analysis**: Calculate keyspace and time estimates for brute force attacks
- **Rules Management**: List and utilize hashcat rule sets for advanced mutations
- **Cracked Hash Lookup**: Query previously cracked hashes from potfile

## Prerequisites

1. **Hashcat CLI**: Must be installed and available in your system PATH
   ```bash
   # macOS
   brew install hashcat

   # Ubuntu/Debian
   apt-get install hashcat

   # From source
   git clone https://github.com/hashcat/hashcat.git
   cd hashcat
   make
   make install
   ```

2. **Wordlists**: For dictionary attacks, you'll need wordlist files
   ```bash
   # Popular wordlists
   wget https://github.com/brannondorsey/naive-hashcat/releases/download/data/rockyou.txt
   ```

3. **Bun Runtime**: Required for running the MCP server
   ```bash
   curl -fsSL https://bun.sh/install | bash
   ```

## Installation

```bash
cd hashcat
bun install
bun run build
```

## Usage

### Starting the Server

```bash
bun run start
```

The server communicates via stdio and is designed to be used with MCP-compatible AI assistants.

## Available Tools

### 1. hashcat_identify

Identify the type of a password hash by analyzing its format.

**Parameters:**
- `hash_value` (string, required): Hash value to identify

**Example:**
```json
{
  "hash_value": "5f4dcc3b5aa765d61d8327deb882cf99"
}
```

**Returns:**
```json
{
  "hash_value_preview": "5f4dcc3b...882cf99",
  "possible_types": [
    {
      "mode": 0,
      "name": "MD5",
      "category": "Raw Hash",
      "example_hash": "8743b52063cd84097a65d1633f5c74f5"
    }
  ]
}
```

### 2. hashcat_benchmark

Benchmark hashcat performance for specific or all hash modes.

**Parameters:**
- `hash_mode` (number, optional): Specific hash mode to benchmark (0-99999)
- `timeout` (number, default: 120): Max duration in seconds (hard limit: 5 minutes)

**Example:**
```json
{
  "hash_mode": 1000,
  "timeout": 60
}
```

**Returns:**
```json
{
  "device": "NVIDIA GeForce RTX 3080",
  "benchmarks": [
    {
      "hash_mode": 1000,
      "hash_name": "NTLM",
      "speed": "45.2",
      "speed_unit": "GH/s"
    }
  ]
}
```

### 3. hashcat_crack

Crack password hashes using various attack modes. **REQUIRES AUTHORIZATION.**

**Parameters:**
- `hashes` (string, required): Hash value(s) to crack, one per line (max 1MB)
- `hash_mode` (number, required): Hashcat hash mode (e.g., 0=MD5, 1000=NTLM, 1800=sha512crypt)
- `authorized` (boolean, required): Must be set to `true` to confirm authorization
- `attack_mode` (enum, default: "dictionary"): Attack mode
  - `dictionary`: Dictionary attack
  - `combinator`: Combinator attack
  - `brute_force`: Brute force with mask
  - `hybrid_wordlist_mask`: Hybrid wordlist + mask
  - `hybrid_mask_wordlist`: Hybrid mask + wordlist
- `wordlist` (string, optional): Path to wordlist file (required for dictionary attacks)
- `mask` (string, optional): Mask pattern for brute force (e.g., `?u?l?l?l?l?l?d?d`)
- `rules` (string, optional): Path to rules file
- `timeout` (number, default: 120): Max duration in seconds (hard limit: 5 minutes)

**Example:**
```json
{
  "hashes": "5f4dcc3b5aa765d61d8327deb882cf99",
  "hash_mode": 0,
  "authorized": true,
  "attack_mode": "dictionary",
  "wordlist": "/usr/share/wordlists/rockyou.txt",
  "timeout": 300
}
```

**Returns:**
```json
{
  "hashes_loaded": 1,
  "hashes_cracked": 1,
  "results": [
    {
      "hash_preview": "5f4dcc3b...882cf99",
      "plaintext": "password",
      "hash_type": "Mode 0"
    }
  ],
  "status": "Cracked",
  "runtime_seconds": 2
}
```

### 4. hashcat_mask_info

Analyze a hashcat mask pattern to calculate keyspace and time estimates.

**Parameters:**
- `mask` (string, required): Mask pattern (max 256 chars)

**Mask Charsets:**
- `?l` = lowercase (a-z)
- `?u` = uppercase (A-Z)
- `?d` = digits (0-9)
- `?s` = special characters
- `?a` = all printable ASCII
- `?h` = lowercase hex (0-9a-f)
- `?H` = uppercase hex (0-9A-F)

**Example:**
```json
{
  "mask": "?u?l?l?l?l?d?d"
}
```

**Returns:**
```json
{
  "mask": "?u?l?l?l?l?d?d",
  "charsets": {
    "?l": "a-z (26 chars)",
    "?u": "A-Z (26 chars)",
    "?d": "0-9 (10 chars)",
    "?s": "special (33 chars)",
    "?a": "all printable ASCII (95 chars)",
    "?h": "0-9a-f (16 chars)",
    "?H": "0-9A-F (16 chars)"
  },
  "keyspace": "45697600",
  "estimated_time_at_1GH": "45 milliseconds",
  "positions": [
    {"position": 0, "charset": "?u", "possible_chars": 26},
    {"position": 1, "charset": "?l", "possible_chars": 26},
    {"position": 2, "charset": "?l", "possible_chars": 26},
    {"position": 3, "charset": "?l", "possible_chars": 26},
    {"position": 4, "charset": "?l", "possible_chars": 26},
    {"position": 5, "charset": "?d", "possible_chars": 10},
    {"position": 6, "charset": "?d", "possible_chars": 10}
  ]
}
```

### 5. hashcat_rules_list

List available hashcat rule files with descriptions.

**Parameters:** None

**Returns:**
```json
{
  "rules": [
    {
      "name": "best64.rule",
      "path": "/usr/share/hashcat/rules/best64.rule",
      "description": "The most effective 64 rules from the hashcat team",
      "size": 1953
    },
    {
      "name": "rockyou-30000.rule",
      "path": "/usr/share/hashcat/rules/rockyou-30000.rule",
      "description": "Top 30000 rules generated from RockYou dataset analysis",
      "size": 298438
    }
  ]
}
```

### 6. hashcat_show_cracked

Show previously cracked hashes from hashcat's potfile.

**Parameters:**
- `hashes` (string, required): Hash value(s) to check, one per line (max 1MB)
- `hash_mode` (number, required): Hashcat hash mode number

**Example:**
```json
{
  "hashes": "5f4dcc3b5aa765d61d8327deb882cf99",
  "hash_mode": 0
}
```

**Returns:**
```json
{
  "cracked": [
    {
      "hash_preview": "5f4dcc3b...882cf99",
      "plaintext": "password"
    }
  ],
  "total_cracked": 1,
  "total_hashes": 1
}
```

## Security Features

### Authorization Required

The `hashcat_crack` tool requires explicit authorization via the `authorized` parameter. This ensures intentional use of password cracking capabilities.

### Hard Time Limit

All operations have a hard 5-minute (300 second) timeout to prevent resource exhaustion. Requested timeouts exceeding this limit will be capped.

### Input Validation

- **Hash Input**: Maximum 1MB, no null bytes, no shell metacharacters
- **Hash Mode**: Must be integer 0-99999
- **Wordlist Path**: Must be absolute path, no directory traversal
- **Mask Pattern**: Maximum 256 characters, restricted character set

### Blocked Flags

The following hashcat flags are blocked for security:
- `--outfile`, `-o`: Prevent arbitrary file writes
- `--session`: Prevent session manipulation
- `--force`: Prevent bypassing safety checks
- `--potfile-path`: Prevent potfile tampering
- `--restore`: Prevent session restoration attacks
- `--remove`: Prevent automatic hash removal
- `--logfile-disable`: Ensure audit trail
- `--debug-file`: Prevent information disclosure

### Temporary Files

All temporary hash files are:
- Created in isolated directory (`/tmp/mcp-hashcat/`)
- Set to mode 0600 (owner read/write only)
- Automatically cleaned up after use

## Common Hash Modes

| Mode | Hash Type | Example |
|------|-----------|---------|
| 0 | MD5 | `5f4dcc3b5aa765d61d8327deb882cf99` |
| 100 | SHA1 | `5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8` |
| 1000 | NTLM | `8846f7eaee8fb117ad06bdd830b7586c` |
| 1400 | SHA2-256 | `5e884898da28047151d0e56f8dc629...` |
| 1700 | SHA2-512 | `b109f3bbbc244eb82441917ed06d61...` |
| 1800 | sha512crypt | `$6$52450745$k5ka2p8bFuSmoVT1...` |
| 3200 | bcrypt | `$2a$05$LhayLxezLhK1LhWvKxCy...` |
| 5600 | NetNTLMv2 | `admin::N46iSNekpT:08ca45b7d7ea58ee...` |
| 13100 | Kerberos 5 TGS-REP | `$krb5tgs$23$*user$realm$test/spn*$...` |

For a complete list, see: https://hashcat.net/wiki/doku.php?id=example_hashes

## Error Handling

The server provides detailed error messages for:
- Missing or invalid parameters
- Security violations
- Hashcat execution failures
- Timeout conditions
- Invalid hash formats

## Performance Tips

1. **Use GPU**: Hashcat performs best with dedicated GPU hardware
2. **Choose Right Attack**: Start with dictionary, move to hybrid, then brute force
3. **Optimize Masks**: Smaller keyspace = faster cracking
4. **Use Rules**: Apply rules to multiply wordlist effectiveness
5. **Monitor Timeout**: Adjust timeout based on attack complexity

## Limitations

- **Maximum hash input size**: 1MB
- **Hard timeout**: 5 minutes per operation
- **No persistent sessions**: Each crack operation is independent
- **No custom charsets**: Limited to built-in hashcat charsets

## License

This MCP server is provided as-is for authorized security testing and research purposes only.

## Legal Notice

Password cracking should only be performed on hashes you own or have explicit written authorization to test. Unauthorized access to computer systems is illegal. Use responsibly.