# Metasploit MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with secure access to Metasploit Framework functionality through a standardized interface. This server wraps core Metasploit capabilities into MCP tools that can be discovered and used by compatible clients.

## Features

- **🔧 Execute Metasploit commands** - Run raw Metasploit commands with built-in security validation
- **🔍 Search exploits** - Find exploits by name, CVE, or keyword
- **📋 Module information** - Get detailed information about any Metasploit module
- **📦 List modules** - Browse available modules by type (exploits, auxiliaries, payloads, etc.)
- **🌐 Network scanning** - Run Nmap scans through Metasploit's database integration
- **🔒 Vulnerability scanning** - Execute vulnerability scans against target systems
- **ℹ️ Version information** - Check your Metasploit installation details
- **🛡️ Security controls** - Input sanitization and command injection prevention

## Requirements

- **Node.js** 16.0.0 or higher
- **Metasploit Framework** installed and accessible via command line (`msfconsole`)
- **MCP-compatible client** (Claude Desktop, VS Code with MCP extension, etc.)

## Installation

1. **Clone the repository:**
   ```bash
   git clone https://github.com/RobertoDure/metasploit-mcp-server.git
   cd metasploit-mcp-server
   ```

2. **Install dependencies:**
   ```bash
   npm install
   ```

3. **Verify Metasploit installation:**
   ```bash
   msfconsole --version
   ```

## Usage

### Development Mode
```bash
npm run dev
```

### Production Mode
```bash
npm start
```

The server communicates via STDIO transport, making it compatible with any MCP client that supports this transport method.


## Available Tools

The MCP server exposes the following tools through the `@modelcontextprotocol/sdk`:

| Tool Name | Description | Required Parameters | Optional Parameters |
|-----------|-------------|-------------------|-------------------|
| `execute-command` | Execute raw Metasploit commands with security validation | `command` (string) | None |
| `search-exploit` | Search for exploits by name, CVE, or keywords | `query` (string) | None |
| `module-info` | Get detailed information about a specific module | `modulePath` (string) | None |
| `list-modules` | List available modules by type | `type` (exploit\|auxiliary\|post\|payload\|encoder\|nop) | None |
| `get-version` | Get Metasploit Framework version information | None | None |
| `run-nmap-scan` | Execute Nmap scans through Metasploit's database | `target` (string) | `options` (string) |
| `run-vuln-scan` | Run vulnerability scans using auxiliary modules | `target` (string) | None |

### Tool Details

#### `execute-command`
- Executes any valid Metasploit command
- Includes input sanitization to prevent command injection
- Runs in quiet, non-interactive mode for consistent output
- Timeout protection (30 seconds)

#### `search-exploit`
- Searches Metasploit's exploit database
- Supports CVE numbers, exploit names, and keywords
- Returns formatted results with module paths and descriptions

#### `module-info`
- Provides comprehensive module information
- Includes options, targets, payloads, and references
- Works with any module type (exploits, auxiliaries, etc.)

#### `list-modules`
- Lists modules by category with validation
- Supports all major module types
- Returns organized module listings

#### `run-nmap-scan`
- Integrates with Metasploit's database features
- Supports custom Nmap options
- Stores results in Metasploit database for further analysis

#### `run-vuln-scan`
- Uses auxiliary scanner modules
- Currently implements SMB MS17-010 (EternalBlue) scanning
- Can be extended for additional vulnerability checks

## Example Usage

When connected to an MCP-compatible client, you can interact with Metasploit using natural language:

**Searching and Information:**
- "Search for Apache Log4j exploits"
- "Show me details about the EternalBlue exploit (exploit/windows/smb/ms17_010_eternalblue)"
- "List all available Windows payloads"
- "What auxiliary modules are available?"

**Scanning and Reconnaissance:**
- "Run an Nmap scan against 192.168.1.100"
- "Perform a stealth scan on 10.0.0.0/24 with -sS -O options"
- "Check if 192.168.1.50 is vulnerable to MS17-010"

**System Information:**
- "What version of Metasploit am I running?"
- "Execute the 'help' command to see available commands"

### Sample Responses

The server returns structured JSON responses:

```json
{
  "success": true,
  "output": "Metasploit Framework Console Output...",
  "command": "search apache"
}
```

Or in case of errors:

```json
{
  "success": false,
  "output": "Command contains potentially dangerous characters",
  "error": "Security violation"
}
```

## Architecture

The server follows a clean, modular architecture:

```
src/
├── index.js                     # Main MCP server with tool registrations
└── services/
    └── metasploit-service.js    # Metasploit Framework integration layer

tests/
└── metasploit-service.test.js   # Unit tests with Jest
```

### Key Components

- **McpServer**: Uses `@modelcontextprotocol/sdk` for MCP protocol implementation
- **MetasploitService**: Encapsulates all Metasploit interactions with security controls
- **StdioServerTransport**: Handles communication via STDIO for client compatibility
- **Zod Schemas**: Provides runtime type validation for all tool inputs

### Security Features

- **Input Sanitization**: Removes dangerous shell characters (`;&|`$()`)
- **Command Validation**: Ensures commands are non-empty strings
- **Timeout Protection**: 30-second timeout on all command executions
- **Error Handling**: Comprehensive error responses with structured formatting
- **Module Type Validation**: Strict validation for module type parameters

## Configuration

### Package Configuration

The server is configured as an ES module with the following key settings:

```json
{
  "name": "metasploit-mcp-server",
  "version": "1.0.0",
  "type": "module",
  "main": "src/index.js",
  "engines": {
    "node": ">=16.0.0"
  }
}
```

### Dependencies

**Production Dependencies:**
- `@modelcontextprotocol/sdk` (^1.12.0) - MCP protocol implementation
- `zod` (^3.22.4) - Runtime type validation and schema definition

**Development Dependencies:**
- `jest` (^29.7.0) - Testing framework with ES module support
- `eslint` (^8.57.0) - Code linting and style enforcement

### MCP Client Configuration

For **Claude Desktop**, add to your MCP settings:

```json
{
  "mcpServers": {
    "metasploit": {
      "command": "node",
      "args": ["src/index.js"],
      "cwd": "/path/to/metasploit-mcp-server"
    }
  }
}
```

For **VS Code with MCP extension**:

```json
{
  "mcpServers": {
    "metasploit-mcp-server": {
      "command": "npm",
      "args": ["start"],
      "cwd": "/path/to/metasploit-mcp-server"
    }
  }
}
```

## Security Considerations

⚠️ **Important Security Notice**

This MCP server provides direct access to Metasploit Framework capabilities. Please observe these security guidelines:

### 🔒 Access Control
- **No built-in authentication** - Consider adding authentication for production use
- **Local access recommended** - Avoid exposing this server to untrusted networks
- **Principle of least privilege** - Run with minimal required system permissions

### 🛡️ Built-in Security Features
- **Command sanitization** - Prevents command injection attacks
- **Input validation** - All parameters are validated using Zod schemas
- **Timeout protection** - 30-second execution limits prevent hanging processes
- **Error isolation** - Failures are contained and don't crash the server

### ⚖️ Legal and Ethical Considerations
- **Authorization required** - Only use against systems you own or have explicit permission to test
- **Responsible disclosure** - Follow responsible disclosure practices for discovered vulnerabilities
- **Compliance** - Ensure usage complies with local laws and organizational policies
- **Documentation** - Maintain records of authorized testing activities

### 🔧 Recommended Deployment Practices
- Run in isolated/sandboxed environments
- Use dedicated testing networks
- Implement network-level access controls
- Monitor and log all activities
- Regular security updates for dependencies

### 🚨 Risk Awareness
- Commands executed have the same privileges as the user running the server
- Metasploit modules can perform invasive actions on target systems
- Some modules may cause service disruption or system instability
- Always test in non-production environments first

## Development

### Scripts

```bash
# Start in development mode with file watching
npm run dev

# Run production server
npm start

# Run tests with Jest
npm test

# Run tests in watch mode
npm run test:watch

# Lint code with ESLint
npm run lint

# Fix linting issues automatically
npm run lint:fix
```

### Testing

The project includes comprehensive Jest tests:

```bash
# Run all tests
npm test

# Generate coverage report
npm test -- --coverage

# Watch mode for development
npm run test:watch
```

Test coverage includes:
- ✅ Command execution validation
- ✅ Security sanitization
- ✅ Error handling
- ✅ Module type validation
- ✅ Input validation edge cases

### Project Structure

```
metasploit-mcp-server/
├── src/
│   ├── index.js                   # MCP server entry point
│   └── services/
│       └── metasploit-service.js  # Metasploit integration
├── tests/
│   └── metasploit-service.test.js # Unit tests
├── package.json                   # Dependencies and scripts
├── jest.config.json              # Jest testing configuration
└── README.md                     # Documentation
```

## Extending the Server

### Adding New Tools

To add new Metasploit capabilities:

1. **Add a method to MetasploitService**:
   ```javascript
   async myNewFeature(param) {
     return this.executeCommand(`my_command ${param}`);
   }
   ```

2. **Register the tool in index.js**:
   ```javascript
   server.registerTool("my-new-tool", {
     title: "My New Tool",
     description: "Description of what it does",
     inputSchema: {
       param: z.string().describe("Parameter description")
     }
   }, async ({ param }) => {
     const result = await metasploitService.myNewFeature(param);
     return {
       content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
     };
   });
   ```

3. **Add tests**:
   ```javascript
   describe('myNewFeature', () => {
     it('should execute the new feature', async () => {
       // Test implementation
     });
   });
   ```

### Custom Module Integration

For specific module integrations, you can create specialized methods:

```javascript
async scanForWebVulns(target) {
  const commands = [
    `use auxiliary/scanner/http/dir_scanner`,
    `set RHOSTS ${target}`,
    `run`,
    `back`
  ].join('; ');
  
  return this.executeCommand(commands);
}
```

### Error Handling Patterns

Follow the established error handling pattern:

```javascript
if (!param || typeof param !== 'string') {
  return {
    success: false,
    output: 'Invalid parameter',
    error: 'Validation failed'
  };
}
```

## Troubleshooting

### Common Issues

**Metasploit not found:**
```bash
# Ensure Metasploit is in PATH
which msfconsole

# Or check installation
msfconsole --version
```

**Permission errors:**
```bash
# Check file permissions
ls -la src/index.js

# Ensure Node.js has execution rights
chmod +x src/index.js
```

**Module import errors:**
- Verify `"type": "module"` is set in `package.json`
- Use `.js` extensions in all import statements
- Check Node.js version (requires >=16.0.0)

**MCP client connection issues:**
- Verify STDIO transport is being used correctly
- Check that the server starts without errors
- Ensure the client configuration points to the correct path

### Debug Mode

Enable debug logging by setting environment variables:

```bash
DEBUG=mcp* npm start
```

### Performance Tuning

For better performance with large scans:

```javascript
// Increase timeout for long-running operations
const { stdout, stderr } = await execAsync(fullCommand, { 
  timeout: 60000  // 60 seconds
});
```

## License

MIT License - see LICENSE file for details.

## Contributing

Contributions are welcome! Please follow these guidelines:

1. **Fork the repository** and create a feature branch
2. **Write tests** for new functionality
3. **Follow the existing code style** (use ESLint)
4. **Update documentation** as needed
5. **Submit a pull request** with a clear description

### Development Workflow

```bash
# Clone your fork
git clone https://github.com/yourusername/metasploit-mcp-server.git

# Install dependencies
npm install

# Create a feature branch
git checkout -b feature/new-tool

# Make changes and test
npm test
npm run lint

# Commit and push
git commit -m "Add new tool for X"
git push origin feature/new-tool
```

### Code Standards

- Use ES modules (`import`/`export`)
- Follow JSDoc documentation style
- Maintain test coverage above 80%
- Use meaningful variable and function names
- Handle errors gracefully with structured responses

---

**Happy hacking! 🚀🔒**