gc-hydra-mcp/readme.md

Model Context Protocol (MCP) server for interacting with Hydra password cracking tool

# Hydra MCP Server

A Model Context Protocol (MCP) server that provides a safe interface to interact with Hydra password cracking tool through Large Language Models.

## ⚠️ Security Warning

This tool interfaces with Hydra, a powerful password auditing tool. It should only be used:
- On systems you own or have explicit permission to test
- In controlled environments for security research or authorized penetration testing
- With full understanding of the legal and ethical implications

**Misuse of this tool may violate laws and regulations. Always ensure you have proper authorization before use.**

## Features

The Hydra MCP server provides the following tools:

- **dictionary-attack**: Perform dictionary attacks against single targets
- **brute-force-attack**: Perform brute force attacks with generated passwords
- **multi-target-attack**: Attack multiple targets from a file
- **credential-pair-attack**: Attack using colon-separated credential pairs
- **http-form-attack**: Attack HTTP login forms (GET or POST)
- **custom-attack**: Execute custom hydra commands
- **list-services**: List all supported services/protocols

## Installation

1. Install the package:
```bash
npm install -g gc-hydra-mcp
```

2. Set the HYDRA_PATH environment variable to point to your hydra executable:
```bash
# Linux/Mac
export HYDRA_PATH="/usr/bin/hydra"

# Windows (if using WSL or Cygwin)
export HYDRA_PATH="/usr/bin/hydra"
```

## Configuration

Add the server to your MCP client configuration:

```json
{
  "hydra": {
    "command": "gc-hydra",
    "env": {
      "HYDRA_PATH": "/usr/bin/hydra"
    }
  }
}
```

## Usage Examples

### Dictionary Attack
```typescript
// Attack SSH service with username/password lists
await use_mcp_tool("hydra", "dictionary-attack", {
  target: "192.168.1.100",
  service: "ssh",
  username_file: "/path/to/usernames.txt",
  password_file: "/path/to/passwords.txt",
  threads: 4
});

// Attack with single username and password list
await use_mcp_tool("hydra", "dictionary-attack", {
  target: "example.com",
  service: "ftp",
  username: "admin",
  password_file: "/path/to/passwords.txt",
  port: 21
});
```

### Brute Force Attack
```typescript
// Brute force SSH with generated passwords
await use_mcp_tool("hydra", "brute-force-attack", {
  target: "192.168.1.100",
  service: "ssh",
  username: "root",
  min_length: 4,
  max_length: 6,
  charset: "a1",  // lowercase letters + digits
  threads: 2
});
```

### HTTP Form Attack
```typescript
// Attack a web login form
await use_mcp_tool("hydra", "http-form-attack", {
  target: "example.com",
  method: "post",
  path: "/login.php",
  form_data: "username=^USER^&password=^PASS^&submit=Login",
  failure_condition: "Invalid username or password",
  username: "admin",
  password_file: "/path/to/passwords.txt",
  use_ssl: true
});
```

### Multiple Targets Attack
```typescript
// Attack multiple SSH servers
await use_mcp_tool("hydra", "multi-target-attack", {
  targets_file: "/path/to/targets.txt",  // Format: ip:port per line
  service: "ssh",
  username: "root",
  password_file: "/path/to/passwords.txt",
  threads_per_target: 4,
  total_threads: 32
});
```

### Credential Pair Attack
```typescript
// Use a file with login:password pairs
await use_mcp_tool("hydra", "credential-pair-attack", {
  target: "192.168.1.100",
  service: "ssh",
  credentials_file: "/path/to/creds.txt",  // Format: username:password per line
  output_file: "/path/to/results.txt"
});
```

### Custom Attack
```typescript
// Execute custom hydra command
await use_mcp_tool("hydra", "custom-attack", {
  hydra_args: ["-l", "admin", "-P", "/path/to/passwords.txt", "-t", "4", "ftp://192.168.1.100"]
});

// Or as a string
await use_mcp_tool("hydra", "custom-attack", {
  hydra_args: "-l admin -P /path/to/passwords.txt -t 4 ftp://192.168.1.100"
});
```

### List Supported Services
```typescript
// Get list of all supported protocols
await use_mcp_tool("hydra", "list-services", {});
```

## Supported Services

Hydra supports many protocols including:
- **Network Services**: ssh, ftp, telnet, rlogin, rsh
- **Web Services**: http, https, http-get, http-post, http-get-form, http-post-form
- **Database Services**: mysql, mssql, postgres, oracle-listener, mongodb
- **Email Services**: pop3, imap, smtp
- **Other Services**: rdp, vnc, smb, ldap, snmp, and many more

## Character Sets for Brute Force

When using brute-force-attack, you can specify character sets:
- `a` - lowercase letters (a-z)
- `A` - uppercase letters (A-Z)
- `1` - digits (0-9)
- `!` - special characters
- Combinations like `aA1` for mixed case + digits

## Output Formats

Hydra can output results in different formats:
- `text` (default) - Human readable format
- `json` - JSON format
- `jsonv1` - JSON v1 format

## Requirements

- Hydra installed on your system
- Appropriate permission files (username lists, password lists)
- Network access to target systems
- Proper authorization for testing

## Development

To build from source:

```bash
# Clone the repository
git clone https://github.com/GH05TCREW/hydra-mcp
cd hydra-mcp

# Install dependencies
npm install

# Build
npm run build
```

## Legal Notice

This tool is provided for educational and authorized security testing purposes only. Users are responsible for complying with applicable laws and regulations. The authors assume no liability for misuse or damage caused by this software.

Hydra is developed by van Hauser/THC & David Maciejak and is licensed under AGPL v3.0.

## License

Apache-2.0

## Author

GhostCrew