npm package: @modular-intelligence/nuclei-scanner
Description: MCP server wrapping nuclei for vulnerability scanning
Latest version: 1.0.2

# Nuclei Scanner MCP Server

A comprehensive vulnerability scanning service that integrates with Nuclei, a powerful open-source vulnerability scanner. This MCP (Model Context Protocol) server enables Claude to perform security assessments on web applications and services using templates for detecting CVEs, misconfigurations, and other security issues.

## Overview

This server provides access to Nuclei's vulnerability scanning capabilities through a unified interface:

- **Nuclei Scanning** - Execute vulnerability scans against target URLs with flexible filtering options
- **Template Management** - List and search available vulnerability templates from Nuclei's repository
- **Template Validation** - Validate custom Nuclei template files for correctness and syntax

Perfect for security research, penetration testing, vulnerability assessments, and continuous security scanning.

## Tools

| Tool | Description |
|------|-------------|
| `nuclei_scan` | Execute vulnerability scan on a target URL with optional filtering |
| `nuclei_templates_list` | List available vulnerability templates with filtering by category and severity |
| `nuclei_templates_search` | Search templates by keyword (CVE ID, vulnerability name, etc.) |
| `nuclei_validate_template` | Validate a custom Nuclei template file for syntax and structure |

### Nuclei Scan

Execute a vulnerability scan on a target URL using Nuclei templates with optional filtering by severity, tags, and template category.

**Input Parameters:**
```typescript
{
  target: string                    // Target URL (http:// or https:// only)
  severity?: string                 // Filter by severity: info, low, medium, high, critical
  tags?: string[]                   // Array of tags to filter templates
  template_category?: string        // Template category (e.g., 'cve', 'vulnerabilities')
  timeout?: number                  // Timeout in seconds (default: 600)
}
```

**Example Request:**
```json
{
  "target": "https://example.com",
  "severity": "high",
  "tags": ["cve"],
  "timeout": 300
}
```

**Example Output:**
```json
{
  "findings": [
    {
      "template_id": "http/cves/2024/CVE-2024-1234",
      "name": "CVE-2024-1234 Remote Code Execution",
      "severity": "critical",
      "type": "http",
      "host": "https://example.com",
      "matched_at": "https://example.com/vulnerable-endpoint",
      "extracted_results": [
        "PHP Version: 7.4.3"
      ],
      "description": "A remote code execution vulnerability in the vulnerable application",
      "reference": [
        "https://nvd.nist.gov/vuln/detail/CVE-2024-1234"
      ],
      "tags": ["rce", "owasp-top10"]
    },
    {
      "template_id": "http/vulnerabilities/exposed-admin-panel",
      "name": "Exposed Admin Panel",
      "severity": "high",
      "type": "http",
      "host": "https://example.com",
      "matched_at": "https://example.com/admin",
      "extracted_results": [],
      "description": "An unauthenticated admin panel was discovered",
      "reference": [],
      "tags": ["misconfig", "exposure"]
    }
  ],
  "count": 2
}
```

### Nuclei Templates List

List all available Nuclei templates with optional filtering by category and severity level.

**Input Parameters:**
```typescript
{
  category?: string  // Filter templates by category (e.g., 'cve', 'vulnerabilities')
  severity?: string  // Filter by severity: info, low, medium, high, critical
}
```

**Example Request:**
```json
{
  "category": "cve",
  "severity": "critical"
}
```

**Example Output:**
```json
{
  "templates": [
    {
      "id": "http/cves/2024/CVE-2024-1234",
      "name": "CVE-2024-1234",
      "severity": "critical",
      "tags": ["rce", "critical"]
    },
    {
      "id": "http/cves/2024/CVE-2024-5678",
      "name": "CVE-2024-5678",
      "severity": "critical",
      "tags": ["ssrf", "critical"]
    },
    {
      "id": "http/cves/2023/CVE-2023-9999",
      "name": "CVE-2023-9999",
      "severity": "critical",
      "tags": ["authentication-bypass"]
    }
  ],
  "count": 3
}
```

### Nuclei Templates Search

Search for vulnerability templates by keyword, such as CVE ID or vulnerability name.

**Input Parameters:**
```typescript
{
  keyword: string      // Keyword to search for in template names
  max_results?: number // Maximum number of results to return (default: 20)
}
```

**Example Request:**
```json
{
  "keyword": "CVE-2024-1234",
  "max_results": 10
}
```

**Example Output:**
```json
{
  "templates": [
    {
      "id": "http/cves/2024/CVE-2024-1234",
      "name": "CVE-2024-1234",
      "severity": "critical"
    }
  ],
  "count": 1,
  "keyword": "CVE-2024-1234"
}
```

### Nuclei Validate Template

Validate a custom Nuclei template file to ensure it has correct syntax and structure.

**Input Parameters:**
```typescript
{
  template_path: string  // Path to the template file to validate
}
```

**Example Request:**
```json
{
  "template_path": "/path/to/custom-template.yaml"
}
```

**Example Output:**
```json
{
  "valid": true,
  "template_path": "/path/to/custom-template.yaml",
  "message": "Template is valid"
}
```

**Example Error Output:**
```json
{
  "valid": false,
  "template_path": "/path/to/custom-template.yaml",
  "errors": "template syntax error: invalid field name 'unknown_field' at line 5"
}
```

## Configuration

### Environment Variables

This server has optional environment variable support for API keys (for enhanced Nuclei functionality):

```bash
export NUCLEI_API_KEY="your-nuclei-api-key"
```

## Prerequisites

- Bun runtime (version 1.x or later) or Node.js 18+
- Nuclei must be installed and available in your PATH

### Installing Nuclei

Visit the official Nuclei installation guide: https://nuclei.projectdiscovery.io/

**macOS (using Homebrew):**
```bash
brew install nuclei
```

**Linux (using apt, for Debian/Ubuntu):**
```bash
sudo apt update && sudo apt install nuclei
```

**Using Go:**
```bash
go install -v github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest
```

**Docker:**
```bash
docker pull projectdiscovery/nuclei:latest
```

Verify installation:
```bash
nuclei -version
```

## Installation

### Steps

1. Clone or download this repository:
```bash
git clone <repo-url>
cd nuclei-scanner
```

2. Install dependencies:
```bash
bun install
```

3. Build the project:
```bash
bun run build
```

4. (Optional) Set environment variables:
```bash
export NUCLEI_API_KEY="your-nuclei-api-key"
```

5. Run the server:
```bash
bun run start
```

The server will start listening on stdio transport.

## Usage

### Running the Server

Start the server with Bun:

```bash
bun run src/index.ts
```

The server implements the Model Context Protocol (MCP) and communicates via stdio transport. It can be integrated with Claude or other MCP clients.

### Claude Desktop Configuration

Add the server to your Claude Desktop configuration at `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "nuclei-scanner": {
      "command": "bun",
      "args": [
        "run",
        "/path/to/nuclei-scanner/src/index.ts"
      ],
      "env": {
        "NUCLEI_API_KEY": "your-nuclei-api-key"
      }
    }
  }
}
```

### Claude Code MCP Settings

Configure the server in Claude Code's MCP settings (typically in `.mcp.json` or via settings UI):

```json
{
  "servers": {
    "nuclei-scanner": {
      "transport": "stdio",
      "command": "bun",
      "args": ["run", "/path/to/nuclei-scanner/src/index.ts"],
      "env": {
        "NUCLEI_API_KEY": "your-nuclei-api-key"
      }
    }
  }
}
```

### Example Usage in Claude

Once configured, you can use the tools directly in conversations with Claude:

**Request:**
"Scan https://example.com for critical vulnerabilities"

**Claude will call:**
```json
{
  "tool": "nuclei_scan",
  "input": {
    "target": "https://example.com",
    "severity": "critical"
  }
}
```

**Request:**
"Search for CVE-2024-1234 templates in Nuclei"

**Claude will call:**
```json
{
  "tool": "nuclei_templates_search",
  "input": {
    "keyword": "CVE-2024-1234",
    "max_results": 10
  }
}
```

**Request:**
"List all high severity vulnerability templates"

**Claude will call:**
```json
{
  "tool": "nuclei_templates_list",
  "input": {
    "severity": "high"
  }
}
```

**Request:**
"Validate my custom template at /home/user/my-template.yaml"

**Claude will call:**
```json
{
  "tool": "nuclei_validate_template",
  "input": {
    "template_path": "/home/user/my-template.yaml"
  }
}
```

## Security

This server implements comprehensive security measures to prevent misuse and protect against scanning unauthorized targets:

### Input Validation

**Target URL Validation**
- Only HTTP and HTTPS protocols are allowed
- Invalid URL formats are rejected
- Non-web protocols (FTP, file, custom) are blocked
- URLs are validated against Node.js URL parser

**Severity Filter Validation**
- Accepts only valid severity levels: info, low, medium, high, critical
- Invalid severity values are rejected by Zod schema

**Template Category Validation**
- Validates template category names
- Dangerous categories are explicitly blocked (see below)

### What Gets Blocked

The server rejects:
- Non-HTTP/HTTPS protocols
- Private IP addresses and localhost (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 127.0.0.0/8, 0.0.0.0/8)
- Localhost variations (localhost, ::1)
- Dangerous template categories: dos, fuzzing, headless
- Invalid severity levels
- Missing or malformed URL inputs

### Dangerous Template Categories

The following template categories are blocked for security and ethical reasons:

- **dos** - Denial of Service templates that could impact service availability
- **fuzzing** - Fuzzing templates that could cause instability
- **headless** - Headless browser templates that could consume excessive resources

### Error Handling

- Invalid inputs return descriptive error messages
- Nuclei execution errors are caught and reported
- Timeout errors are handled gracefully with a 600-second default timeout
- Template validation errors are presented with details

## License

ISC License - see LICENSE file for details