npm package: @modular-intelligence/impacket
Description: MCP server wrapping Impacket for Windows protocol assessment and Active Directory enumeration
Latest version: 1.0.2

# Impacket MCP Server

MCP server wrapping [Impacket](https://github.com/fortra/impacket) for Windows protocol assessment and Active Directory enumeration.

## Overview

This server provides secure access to Impacket's suite of Windows and Active Directory security testing tools through the Model Context Protocol (MCP). All tools require explicit authorization and implement security controls to prevent misuse.

## Features

- **Credential Extraction**: DCSync attacks and secret dumping (secretsdump)
- **Kerberos Attacks**: Kerberoasting (GetUserSPNs) and AS-REP Roasting (GetNPUsers)
- **SMB Enumeration**: Share listing and file browsing (smbclient)
- **RPC Discovery**: Endpoint enumeration (rpcdump)
- **NTLM Relay Testing**: SMB signing verification (ntlmrelayx check)
- **SID Enumeration**: Domain user and group discovery (lookupsid)

## Prerequisites

### Install Impacket

```bash
# Install via pip
pip install impacket

# Or install from source
git clone https://github.com/fortra/impacket.git
cd impacket
pip install .
```

Verify installation:
```bash
which impacket-secretsdump
impacket-GetUserSPNs --help
```

### Install MCP Server

```bash
cd impacket
bun install
bun run build
```

## Tools

### 1. impacket_secretsdump

Extract password hashes and secrets from Windows systems.

**Use Cases:**
- DCSync attacks against Domain Controllers
- Local SAM database dumping
- LSA secrets extraction
- Cached credentials recovery

**Parameters:**
- `target` (required): Target host IP or hostname
- `domain` (required): Active Directory domain name
- `username` (required): Username for authentication
- `password` (optional): Password for authentication
- `nt_hash` (optional): NT hash for pass-the-hash
- `authorized` (required): Authorization confirmation
- `just_dc` (default: false): Only use DCSync method
- `timeout` (default: 60): Execution timeout in seconds

**Example:**
```json
{
  "target": "192.168.1.10",
  "domain": "CORP",
  "username": "Administrator",
  "password": "P@ssw0rd",
  "authorized": true,
  "just_dc": true
}
```

**Returns:**
```json
{
  "target": "192.168.1.10",
  "domain": "CORP",
  "secrets": [
    {
      "type": "NTLM",
      "account": "CORP\\Administrator",
      "redacted_hash": "31d6...b4e0"
    }
  ],
  "total": 15,
  "warning": "Credential dumping is a sensitive operation..."
}
```

### 2. impacket_getuserspns

Enumerate Kerberoastable service accounts.

**Use Cases:**
- Identify service accounts with SPNs
- Extract TGS tickets for offline cracking
- Assess service account security posture

**Parameters:**
- `target`, `domain`, `username`, `password`/`nt_hash`, `authorized`, `timeout`
- `request` (default: true): Request TGS tickets

**Example:**
```json
{
  "target": "dc01.corp.local",
  "domain": "CORP",
  "username": "user",
  "password": "pass",
  "authorized": true,
  "request": true
}
```

**Returns:**
```json
{
  "target": "dc01.corp.local",
  "domain": "CORP",
  "spn_accounts": [
    {
      "samaccountname": "svc_sql",
      "memberof": "CN=Service Accounts,DC=corp,DC=local",
      "spn": "MSSQLSvc/sql01.corp.local:1433",
      "password_last_set": "2023-01-15 10:30:00"
    }
  ],
  "total": 3,
  "warning": "Kerberoasting extracts service account credentials..."
}
```

### 3. impacket_getnpusers

Identify AS-REP roastable accounts (no pre-authentication required).

**Parameters:**
- Standard auth parameters
- `no_preauth_users` (optional): Newline-separated list of usernames to test

**Example:**
```json
{
  "target": "dc01.corp.local",
  "domain": "CORP",
  "username": "user",
  "password": "pass",
  "authorized": true,
  "no_preauth_users": "testuser1\ntestuser2\nadmin"
}
```

### 4. impacket_smbclient

Interact with SMB shares (read-only operations).

**Commands:**
- `shares`: List available shares
- `ls`: List files in a share
- `info`: Server information

**Parameters:**
- `command` (default: "shares"): Operation to perform
- `share` (optional): Share name for `ls` command

**Example:**
```json
{
  "target": "fileserver.corp.local",
  "domain": "CORP",
  "username": "user",
  "password": "pass",
  "authorized": true,
  "command": "shares"
}
```

### 5. impacket_rpcdump

Enumerate RPC endpoints and interfaces.

**Parameters:**
- `target`, `authorized`, `timeout`
- `port` (default: 135): RPC endpoint mapper port

**Example:**
```json
{
  "target": "192.168.1.10",
  "authorized": true,
  "port": 135
}
```

### 6. impacket_ntlmrelayx_check

Check SMB signing configuration (read-only security check).

**Parameters:**
- `target`, `authorized`, `timeout`

**Returns:**
```json
{
  "target": "192.168.1.10",
  "smb_signing_required": false,
  "smb_version": "2.1",
  "os_version": "Windows Server 2016",
  "domain": "CORP",
  "vulnerable_to_relay": true,
  "details": "SMB signing is NOT required. This host may be vulnerable..."
}
```

### 7. impacket_lookupsid

Enumerate domain users and groups via SID bruteforcing.

**Parameters:**
- Standard auth parameters
- `max_rid` (default: 4000, range: 500-50000): Maximum RID to enumerate

**Example:**
```json
{
  "target": "dc01.corp.local",
  "domain": "CORP",
  "username": "user",
  "password": "pass",
  "authorized": true,
  "max_rid": 4000
}
```

**Returns:**
```json
{
  "target": "dc01.corp.local",
  "domain": "CORP",
  "domain_sid": "S-1-5-21-1234567890-1234567890-1234567890",
  "sids": [
    {"rid": 500, "name": "Administrator", "type": "SidTypeUser"},
    {"rid": 501, "name": "Guest", "type": "SidTypeUser"}
  ],
  "total": 47
}
```

## Security Features

### Authorization Requirements

All tools require explicit authorization confirmation:
```json
{
  "authorized": true
}
```

Without this, the tool will fail with:
```
Authorization required. You must confirm you have explicit written authorization to perform security testing on this target. Unauthorized testing is illegal and unethical.
```

### Input Validation

- **Target validation**: Only alphanumeric hostnames/IPs
- **Domain validation**: Valid AD domain format
- **Username validation**: Max 128 characters, safe characters only
- **Argument sanitization**: Blocks shell metacharacters (`;`, `&`, `|`, `` ` ``, `$`)

### Blocked Operations

The following flags are blocked to prevent code execution and file transfers:
- `--exec-method`, `-exec`, `--command`, `-c`
- `--upload`, `--download`
- `-x`, `--execute`, `-X`

### Credential Security

- Credentials are passed via temporary files or stdin when possible
- Never exposed in process listings
- Temporary files are created with `0o600` permissions
- Automatic cleanup after use

### Output Redaction

Sensitive hash values are automatically redacted:
```
"redacted_hash": "31d6...b4e0"  // Only first/last 4 characters shown
```

## Configuration

Add to your MCP settings file (e.g., `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "impacket": {
      "command": "bun",
      "args": ["run", "/path/to/mi-mcp-servers/packages/impacket/src/index.ts"]
    }
  }
}
```

## Legal and Ethical Usage

**CRITICAL WARNING:**

This tool provides access to powerful security testing capabilities that can be used for both legitimate security assessments and malicious attacks.

### Legal Requirements

1. **Written Authorization**: You MUST have explicit written authorization from the system owner before testing
2. **Scope Boundaries**: Only test systems explicitly included in your authorization
3. **Legal Compliance**: Ensure compliance with:
   - Computer Fraud and Abuse Act (CFAA) in the US
   - Computer Misuse Act in the UK
   - Local cybersecurity laws in your jurisdiction

### Ethical Guidelines

1. **Permission First**: Never test systems you don't own without permission
2. **Scope Compliance**: Stay within authorized scope and timeframes
3. **Data Handling**: Treat extracted credentials as highly sensitive
4. **Responsible Disclosure**: Report vulnerabilities responsibly
5. **No Harm**: Avoid disrupting production systems

### Professional Use

This tool is designed for:
- Authorized penetration testing engagements
- Red team exercises
- Security research in controlled environments
- Educational purposes in isolated lab environments

## Limitations

### Read-Only Operations

Most tools are configured for read-only operations:
- No file uploads/downloads via SMB
- No command execution
- No modification of AD objects
- No relay attacks (only checking)

### Timeout Constraints

- Default: 60 seconds
- Range: 10-300 seconds
- Large domain enumerations may require higher timeouts

### Credential Requirements

Most tools require valid domain credentials. Some operations require elevated privileges:
- **DCSync**: Domain Admin or equivalent
- **Secretsdump**: Local Admin or Domain Admin
- **SPN enumeration**: Domain user (read-only)
- **RPC enumeration**: No authentication required

## Troubleshooting

### Impacket Not Found

```bash
# Verify installation
which impacket-secretsdump
pip show impacket

# If not found, install
pip install impacket
```

### Authentication Failures

- Verify credentials are correct
- Check domain name format (DOMAIN not DOMAIN.LOCAL for some tools)
- Try pass-the-hash if password auth fails
- Ensure user has required privileges

### Timeout Errors

- Increase timeout parameter
- Check network connectivity
- Verify target is reachable
- Reduce scope (e.g., lower `max_rid` for lookupsid)

### Permission Denied

- Ensure Impacket scripts are executable
- Check Python environment has required libraries
- Verify network access to target ports (135, 445, 389, 88)

## Development

```bash
# Install dependencies
bun install

# Build
bun run build

# Run directly
bun run start

# Test individual tools
bun run src/index.ts
```

## License

This MCP server wrapper is provided as-is for authorized security testing only.

Impacket is licensed under the Apache License 2.0. See https://github.com/fortra/impacket for details.

## Disclaimer

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND. USE AT YOUR OWN RISK. THE AUTHORS ARE NOT RESPONSIBLE FOR ANY MISUSE OR DAMAGE CAUSED BY THIS SOFTWARE. USERS ARE SOLELY RESPONSIBLE FOR ENSURING THEY HAVE PROPER AUTHORIZATION BEFORE USING THESE TOOLS.