Nuclei Template Engine for Vesper

Powerful Nuclei vulnerability scanner integration with 11,000+ community templates, automated scanning, template management, and custom scan profiles.

Features

✅ 11,000+ Templates - Massive community-maintained vulnerability database
✅ 8 Scan Profiles - Pre-configured for different use cases
✅ Template Management - Auto-update, search, and filter templates
✅ Real-Time Results - Stream findings as they're discovered
✅ Multi-Target Scanning - Scan multiple targets efficiently
✅ CVE Detection - Scan for known CVE vulnerabilities
✅ Export Formats - JSON, CSV, Markdown reports
✅ High Performance - Configurable rate limiting and concurrency

What is Nuclei?

Nuclei is a fast, customizable vulnerability scanner based on simple YAML templates. It's used by security researchers and penetration testers worldwide to:

• Detect misconfigurations
• Find exposed panels and services
• Scan for known CVEs
• Identify web application vulnerabilities
• Perform technology detection

This module integrates Nuclei with Vesper for seamless automated vulnerability scanning.

Prerequisites

• Nuclei - Installed and in PATH
• Python 3.9+

Installation

Install Nuclei

Using Go:

go install -v github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest

Or download binary:

• https://github.com/projectdiscovery/nuclei/releases

Verify installation:

nuclei -version

Download Templates

nuclei -update-templates

This downloads 11,000+ templates to ~/nuclei-templates/

Install Module

# From GitHub (when published)
vesper module install https://github.com/cgutierrez1145/nuclei-engine

# Or install locally
cd /home/cag1145/vesper/vesper-hydra/desktop
vesper module install ./nuclei-engine --type local

Quick Start

1. Basic Scan

from main import NucleiScanner, Severity

# Create scanner
scanner = NucleiScanner()

# Run quick scan
results = scanner.scan_sync(
    targets=["https://example.com"],
    severities=[Severity.CRITICAL, Severity.HIGH]
)

# Process results
for result in results:
    print(f"[{result.severity.value.upper()}] {result.template_name}")
    print(f"  URL: {result.matched_at}")
    if result.cve_ids:
        print(f"  CVEs: {', '.join(result.cve_ids)}")

2. Profile-Based Scan

from main import ScanSession

# Create session
session = ScanSession()
session.add_targets([
    "https://example.com",
    "https://api.example.com"
])

# Run with profile
results = session.run(profile="standard")

# Get summary
summary = session.get_summary()
print(f"Found {summary['findings_count']} issues")
print(f"Critical: {summary['by_severity'].get('critical', 0)}")

Scan Profiles

The module includes 8 pre-configured scan profiles:

Profile	Use Case	Severity	Speed
quick	Initial assessment	Critical, High	Fastest (150 req/s)
standard	Regular testing	Critical, High, Medium	Balanced (100 req/s)
thorough	Comprehensive audit	All severities	Slower (50 req/s)
cve-focused	Known vulnerabilities	CVE-tagged only	Fast (100 req/s)
web-full	Web app pentesting	XSS, SQLi, RCE, etc.	Medium (75 req/s)
exposed-panels	Admin interfaces	Panel, login, dashboard	Fast (150 req/s)
misconfig	Security configs	Misconfig, exposure	Medium (100 req/s)
tech-detect	Fingerprinting	Info only	Very fast (200 req/s)

Profile Usage

# Quick scan
results = session.run(profile="quick")

# CVE-focused
results = session.run(profile="cve-focused")

# Full web scan
results = session.run(profile="web-full")

# Override profile settings
results = session.run(
    profile="standard",
    rate_limit=200,  # Faster
    concurrency=30
)

Usage Examples

Example 1: Single Target Scan

from main import NucleiScanner, Severity

scanner = NucleiScanner()

# Scan with custom filters
results = scanner.scan_sync(
    targets=["https://example.com"],
    severities=[Severity.CRITICAL, Severity.HIGH],
    tags=["xss", "sqli"],  # Only XSS and SQLi templates
    rate_limit=150,
    concurrency=25,
    timeout=5
)

print(f"Found {len(results)} vulnerabilities")

Example 2: Multi-Target Batch Scan

from main import ScanSession

session = ScanSession()

# Add targets
session.add_targets([
    "https://target1.com",
    "https://target2.com",
    "https://target3.com"
])

# Or from file
session.add_targets_from_file("targets.txt")

# Run scan
results = session.run(profile="thorough")

# Export results
session.export_results("scan_results.json", format="json")
session.export_results("scan_report.md", format="markdown")

Example 3: CVE Scanning

from main import NucleiScanner

scanner = NucleiScanner()

# Scan for known CVEs
results = scanner.scan_sync(
    targets=["https://example.com"],
    tags=["cve"]
)

# Check for specific CVEs
log4j = [r for r in results if "CVE-2021-44228" in r.cve_ids]
if log4j:
    print("⚠ Log4Shell detected!")

spring4shell = [r for r in results if "CVE-2022-22965" in r.cve_ids]
if spring4shell:
    print("⚠ Spring4Shell detected!")

Example 4: Real-Time Streaming

from main import NucleiScanner, Severity

scanner = NucleiScanner()

# Stream results as they're found
print("Scanning...")
for result in scanner.scan(
    targets=["https://example.com"],
    severities=[Severity.CRITICAL, Severity.HIGH]
):
    print(f"[FOUND] {result.template_name} at {result.matched_at}")

    # Take immediate action
    if result.severity == Severity.CRITICAL:
        # Alert, export, or remediate immediately
        pass

Example 5: Custom Templates

from main import NucleiScanner, TemplateManager

scanner = NucleiScanner()
tm = scanner.template_manager

# Find specific templates
wordpress_templates = tm.find_templates(pattern="wordpress")
jira_templates = tm.find_templates(pattern="jira")

# Scan with custom templates
results = scanner.scan_sync(
    targets=["https://example.com"],
    templates=wordpress_templates
)

Example 6: Template Management

from main import TemplateManager

tm = TemplateManager()

# Update templates
success, message = tm.update_templates()
print(message)

# Get statistics
stats = tm.get_stats()
print(f"Total templates: {stats['total']}")
print(f"Directory: {stats['directory']}")

# By category
for category, count in stats["by_category"].items():
    print(f"  {category}: {count}")

API Reference

NucleiScanner

scan(targets, severities, tags, templates, rate_limit, concurrency, timeout, output_file)

Stream scan results in real-time.

scan_sync(targets, **kwargs)

Run synchronous scan and return all results.

ScanSession

add_targets(targets: List[str])

Add targets to scan queue.

add_targets_from_file(file_path: str)

Load targets from file.

run(profile: str = "standard", **kwargs)

Run scan with profile.

get_summary()

Get scan statistics.

export_results(output_file, format)

Export to JSON/CSV/Markdown.

TemplateManager

update_templates()

Update templates to latest version.

find_templates(pattern, severity, tags)

Find templates matching criteria.

get_stats()

Get template statistics.

NucleiResult

Result object with:

• template_id: Template identifier
• template_name: Human-readable name
• severity: Severity level (Enum)
• matched_at: Target URL
• cve_ids: List of CVE IDs
• cwe_ids: List of CWE IDs
• tags: Template tags
• description: Vulnerability description
• reference: Reference links

Severity Levels

from main import Severity

Severity.CRITICAL  # Remote code execution, auth bypass
Severity.HIGH      # SQL injection, XSS with impact
Severity.MEDIUM    # CSRF, information disclosure
Severity.LOW       # Minor misconfigurations
Severity.INFO      # Informational findings

Performance Tuning

Rate Limiting

# Fast (may trigger WAF)
results = scanner.scan_sync(targets, rate_limit=200)

# Medium (recommended)
results = scanner.scan_sync(targets, rate_limit=100)

# Slow (stealthy)
results = scanner.scan_sync(targets, rate_limit=25)

Concurrency

# High concurrency (fast, more resources)
results = scanner.scan_sync(targets, concurrency=50)

# Low concurrency (slower, less noisy)
results = scanner.scan_sync(targets, concurrency=5)

Timeout

# Short timeout (for fast targets)
results = scanner.scan_sync(targets, timeout=3)

# Long timeout (for slow targets)
results = scanner.scan_sync(targets, timeout=15)

Export Formats

JSON

session.export_results("results.json", format="json")

Output: Structured JSON array with all fields

CSV

session.export_results("results.csv", format="csv")

Output: Spreadsheet-compatible CSV

Markdown

session.export_results("report.md", format="markdown")

Output: Human-readable markdown report grouped by severity

Troubleshooting

Nuclei Not Found

Error: Nuclei not found. Install from: https://github.com/projectdiscovery/nuclei

Solution:

go install -v github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest

Ensure ~/go/bin is in your PATH.

No Templates Found

Issue: Module reports 0 templates

Solution:

nuclei -update-templates

Templates are downloaded to ~/nuclei-templates/

Slow Scans

Issue: Scans taking too long

Solutions:

1. Use faster profile: profile="quick"
2. Increase rate limit: rate_limit=200
3. Filter by severity: severities=[Severity.CRITICAL, Severity.HIGH]
4. Use specific tags instead of scanning all templates

Rate Limiting/WAF

Issue: Getting rate limited or blocked

Solutions:

1. Reduce rate limit: rate_limit=50
2. Reduce concurrency: concurrency=10
3. Increase timeout: timeout=15
4. Add delays between targets

Best Practices

1. Start with Quick Scan - Run quick profile first to find critical issues
2. Filter by Tags - Use tags to focus on specific vulnerability types
3. Export Results - Always export to JSON for further analysis
4. Update Templates Regularly - Run update_templates() weekly
5. Respect Rate Limits - Don't overwhelm targets
6. Use Test Accounts - Only scan systems you have permission to test

Security Considerations

• Authorization Required - Only scan systems you own or have permission to test
• Rate Limiting - Respect server resources, don't DOS
• False Positives - Verify findings before reporting
• Private Data - Don't include sensitive data in exports

Contributing

Ideas for enhancement:

• Custom template creation
• Parallel target scanning
• Vulnerability deduplication
• Integration with CVE databases
• Custom severity mappings
• Scheduled scans

License

MIT License - See LICENSE file

Author

Crystal Gutierrez
Email: cgutierrez1145@gmail.com
GitHub: @cgutierrez1145

Links

• Nuclei
• Nuclei Templates
• Vesper Hydra

Changelog

v1.0.0 (2024-12-30)

• Initial release
• 8 scan profiles
• Template management
• Real-time streaming
• Multi-target support
• Export to JSON/CSV/Markdown
• CVE detection
• Comprehensive documentation