Skip to main content
This guide helps you migrate from Nuclei v2 to v3, covering breaking changes, new features, and migration steps.

​
Overview

Nuclei v3 introduces significant improvements in performance, template execution, and protocol support. While most templates are backward compatible, some changes require attention.

​
Breaking changes

​
Template execution

Nuclei v3 changes how templates are executed and may affect custom templates and workflows.
v2 behavior:
  • Templates executed requests sequentially
  • Limited control over execution flow
v3 behavior:
  • Introduces flow field for explicit execution control
  • More flexible multi-step template execution
  • Backward compatible (sequential execution if no flow specified)
Migration:
# v2 - implicit sequential execution
http:
  - method: GET
    path:
      - "{{BaseURL}}/step1"
  - method: GET
    path:
      - "{{BaseURL}}/step2"

# v3 - explicit flow control
flow: |
  http(0)
  http(1)

http:
  - method: GET
    path:
      - "{{BaseURL}}/step1"
  - method: GET
    path:
      - "{{BaseURL}}/step2"
Renamed protocols:
  • network → tcp (network still works but is deprecated)
  • requests → http (requests still works but is deprecated)
Migration:
# v2
requests:
  - method: GET
    path:
      - "{{BaseURL}}"

network:
  - host:
      - "{{Hostname}}"

# v3 (preferred)
http:
  - method: GET
    path:
      - "{{BaseURL}}"

tcp:
  - host:
      - "{{Hostname}}"
v3 introduces native JavaScript support:
javascript:
  - code: |
      let c = require('net');
      let conn = c.Open('tcp', Host + ':' + Port);
      conn.Send('test');
      let resp = conn.RecvString();
      Export({response: resp});

    args:
      Host: "{{Host}}"
      Port: "22"
This enables protocol scanning beyond HTTP/DNS/TCP.
v3 adds code protocol for advanced use cases:
# Requires -code flag to execute
code:
  - engine:
      - sh
    source: |
      echo "Custom code execution"
Code templates require -code flag and should be used with caution.

​
Command-line flags

v2 Flagv3 FlagNotes
-fuzz-dastFuzzing renamed to DAST
-rlm (rate-limit-minute)-rl (rate-limit)Simplified rate limiting
-irr (include-rr)-omit-rawInverted logic for clarity
-cup (cloud-upload)-dashboardRenamed for clarity
Migration:
# v2
nuclei -u target.com -fuzz -rlm 100 -cup

# v3
nuclei -u target.com -dast -rl 100 -dashboard

​
Configuration

v3 uses versioned configuration:
# ~/.config/nuclei/config.yaml

# v2 config may need updates
# Run to migrate:
nuclei -version  # Auto-migrates config if needed
New configuration options:
  • dast instead of fuzz
  • dashboard instead of cloud-upload
  • Updated rate limiting configuration

​
New features

​
Multi-protocol templates

v3 allows multiple protocols in one template:
id: multi-protocol-check

info:
  name: Multi-protocol vulnerability check
  author: pdteam
  severity: high

flow: |
  http(0)
  dns(0)
  ssl(0)

http:
  - method: GET
    path:
      - "{{BaseURL}}"

dns:
  - name: "{{FQDN}}"
    type: A

ssl:
  - address: "{{Host}}:{{Port}}"

​
Enhanced flow control

# Conditional execution
flow: |
  http(0)
  if (http_status_code == 200) {
    http(1)
  }

# Loops and iterations
flow: |
  for (let region of regions) {
    http(0)
  }

# Complex workflows
flow: |
  http(0)
  dns(0)
  if (dns_contains_ip("1.2.3.4")) {
    http(1)
    ssl(0)
  }

​
Performance improvements

v3 improvements:
  • Smarter request deduplication
  • Better connection pooling
  • Optimized template compilation
  • Reduced memory footprint
Results:
  • 30-50% faster scanning on average
  • Lower resource consumption
  • Better concurrency handling

​
DAST capabilities

# Enable DAST mode for fuzzing
nuclei -u https://example.com -dast

# Configure fuzzing aggression
nuclei -u https://example.com -dast -fa high

# DAST server mode for live fuzzing
nuclei -dast-server -dast-server-address localhost:9055

​
Migration steps

1

Backup v2 configuration

# Backup v2 config
cp ~/.config/nuclei/config.yaml ~/.config/nuclei/config.yaml.v2.backup

# Backup custom templates
cp -r ~/custom-templates ~/custom-templates.v2.backup
2

Install Nuclei v3

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

# Verify version
nuclei -version
3

Update templates

# Update to v3 templates
nuclei -update-templates

# Verify template version
nuclei -templates-version
4

Test custom templates

# Validate custom templates
nuclei -validate -t ~/custom-templates/

# Test execution
nuclei -u https://test-target.com -t ~/custom-templates/ -debug
5

Update automation scripts

Update CI/CD pipelines and automation scripts:
# Update flag names
# -fuzz → -dast
# -cup → -dashboard
# -rlm → -rl

# Example:
# OLD: nuclei -list targets.txt -fuzz -cup
# NEW: nuclei -list targets.txt -dast -dashboard
6

Review and test

  • Test scans against known targets
  • Verify output formats are compatible
  • Check integrations (Jira, Slack, etc.)
  • Monitor performance and resource usage

​
Template migration

​
Update deprecated syntax

# Before (v2)
id: example-template

info:
  name: Example
  author: pdteam
  severity: high

requests:  # Deprecated
  - method: GET
    path:
      - "{{BaseURL}}/api"

# After (v3)
id: example-template

info:
  name: Example
  author: pdteam
  severity: high

http:  # Preferred
  - method: GET
    path:
      - "{{BaseURL}}/api"

​
Add flow control (optional)

# Explicit flow for multi-step templates
flow: |
  http(0)
  if (http_status_code == 200) {
    http(1)
  }

http:
  - method: GET
    path:
      - "{{BaseURL}}/step1"
  - method: GET
    path:
      - "{{BaseURL}}/step2"

​
Troubleshooting

Issue: Custom templates fail validation in v3.Solution:
# Check specific errors
nuclei -validate -t template.yaml -v

# Disable strict syntax temporarily
nuclei -u target.com -t template.yaml -nss

# Update template syntax
# Replace deprecated fields (requests → http, network → tcp)
Issue: Scans slower in v3.Solution:
# Ensure template clustering is enabled (default)
nuclei -u target.com -t templates/

# Increase concurrency if needed
nuclei -u target.com -c 50 -rl 200

# Check for inefficient custom templates
nuclei -validate -t custom-templates/ -v
Issue: v2 config file not working.Solution:
# Reset config (backs up automatically)
nuclei -reset

# Or manually update deprecated settings
# Edit ~/.config/nuclei/config.yaml
# Update: fuzz→dast, cloud-upload→dashboard, etc.
Issue: Integrations (Jira, Slack) not working.Solution:
  • Update reporting config file syntax
  • Verify API tokens/credentials still valid
  • Check output format compatibility
  • Review integration logs with -v

​
Version-specific notes

​
v3.0.x

Major changes:
  • Flow-based template execution
  • JavaScript protocol support
  • Code protocol (requires -code flag)
  • Enhanced DAST capabilities
  • Renamed protocols and flags
  • Performance optimizations
Known issues:
  • Some v2 templates may need minor adjustments
  • Custom workflows may require flow definitions

​
Getting help

Migration issues

Ask on GitHub Discussions

Discord community

Get real-time help

Report bugs

File issues on GitHub

Documentation

Browse full documentation

​
Additional resources

Build docs developers (and LLMs) love

Get started for freeTalk to us