Skip to main content
The NucleiEngine is the core component of the Nuclei SDK that orchestrates vulnerability scanning.

​
Types

​
NucleiEngine

Main engine instance for running Nuclei scans. 
type NucleiEngine struct {
	// Contains filtered or unexported fields
}

​
ThreadSafeNucleiEngine

Thread-safe variant for concurrent scanning. 
type ThreadSafeNucleiEngine struct {
	// Contains filtered or unexported fields
}

​
Constructors

​
NewNucleiEngine

Creates a new Nuclei engine instance. 
func NewNucleiEngine(options ...NucleiSDKOptions) (*NucleiEngine, error)
​
options
...NucleiSDKOptions
Variable number of configuration options
​
return
*NucleiEngine, error
Returns a new NucleiEngine instance or an error
Example: 
ne, err := nuclei.NewNucleiEngine(
	nuclei.WithTemplateFilters(nuclei.TemplateFilters{Severity: "critical"}),
)
if err != nil {
	panic(err)
}
defer ne.Close()
This function uses context.Background() internally. Use NewNucleiEngineCtx for custom context.

​
NewNucleiEngineCtx

Creates a new Nuclei engine instance with a custom context. 
func NewNucleiEngineCtx(ctx context.Context, options ...NucleiSDKOptions) (*NucleiEngine, error)
​
ctx
context.Context
required
Context for controlling engine lifecycle
​
options
...NucleiSDKOptions
Variable number of configuration options
​
return
*NucleiEngine, error
Returns a new NucleiEngine instance or an error
Example: 
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Minute)
defer cancel()

ne, err := nuclei.NewNucleiEngineCtx(ctx,
	nuclei.WithTemplateFilters(nuclei.TemplateFilters{Tags: []string{"oast"}}),
)

​
NewThreadSafeNucleiEngine

Creates a thread-safe Nuclei engine for concurrent scanning. 
func NewThreadSafeNucleiEngine(options ...NucleiSDKOptions) (*ThreadSafeNucleiEngine, error)
​
options
...NucleiSDKOptions
Variable number of configuration options
​
return
*ThreadSafeNucleiEngine, error
Returns a new ThreadSafeNucleiEngine instance or an error
Example: 
ne, err := nuclei.NewThreadSafeNucleiEngine()
if err != nil {
	panic(err)
}
defer ne.Close()
Deprecated: Use NewThreadSafeNucleiEngineCtx instead.

​
NewThreadSafeNucleiEngineCtx

Creates a thread-safe Nuclei engine with a custom context. 
func NewThreadSafeNucleiEngineCtx(ctx context.Context, options ...NucleiSDKOptions) (*ThreadSafeNucleiEngine, error)
​
ctx
context.Context
required
Context for controlling engine lifecycle
​
options
...NucleiSDKOptions
Variable number of configuration options
​
return
*ThreadSafeNucleiEngine, error
Returns a new ThreadSafeNucleiEngine instance or an error
Example: 
ctx := context.Background()
ne, err := nuclei.NewThreadSafeNucleiEngineCtx(ctx)

​
Core methods

​
LoadTargets

Loads target URLs, domains, or IPs into the engine. 
func (e *NucleiEngine) LoadTargets(targets []string, probeNonHttp bool)
​
targets
[]string
required
List of target URLs, domains, or IP addresses
​
probeNonHttp
bool
required
Whether to probe non-HTTP/HTTPS targets to detect web services
Example: 
// Load without probing
ne.LoadTargets([]string{"scanme.sh", "example.com"}, false)

// Load with HTTP probing
ne.LoadTargets([]string{"192.168.1.1", "example.com"}, true)

​
LoadTargetsFromReader

Loads targets from an io.Reader (e.g., file). 
func (e *NucleiEngine) LoadTargetsFromReader(reader io.Reader, probeNonHttp bool)
​
reader
io.Reader
required
Reader containing targets (one per line)
​
probeNonHttp
bool
required
Whether to probe non-HTTP/HTTPS targets
Example: 
file, _ := os.Open("targets.txt")
defer file.Close()
ne.LoadTargetsFromReader(file, false)

​
LoadTargetsWithHttpData

Loads targets with HTTP request data from various file formats. 
func (e *NucleiEngine) LoadTargetsWithHttpData(filePath string, filemode string) error
​
filePath
string
required
Path to the file containing HTTP data
​
filemode
string
required
File format: “burp”, “openapi”, “swagger”, or “proxify”
​
return
error
Returns error if file cannot be loaded
Example: 
err := ne.LoadTargetsWithHttpData("burp-export.xml", "burp")
err := ne.LoadTargetsWithHttpData("api.yaml", "openapi")
This method is mutually exclusive with LoadTargets and LoadTargetsFromReader.

​
ExecuteWithCallback

Executes templates against loaded targets with an optional callback. 
func (e *NucleiEngine) ExecuteWithCallback(callback ...func(event *output.ResultEvent)) error
​
callback
...func(event *output.ResultEvent)
Optional callback functions invoked for each result
​
return
error
Returns error if execution fails
Example: 
// No callback - outputs JSON to stdout
err := ne.ExecuteWithCallback(nil)

// With callback
err := ne.ExecuteWithCallback(func(event *output.ResultEvent) {
	fmt.Printf("[%s] %s\n", event.TemplateID, event.Host)
})

// Multiple callbacks
err := ne.ExecuteWithCallback(callback1, callback2)
Deprecated: Use ExecuteCallbackWithCtx for better context control.

​
ExecuteCallbackWithCtx

Executes templates with context support and callbacks. 
func (e *NucleiEngine) ExecuteCallbackWithCtx(ctx context.Context, callback ...func(event *output.ResultEvent)) error
​
ctx
context.Context
required
Context for controlling execution lifecycle
​
callback
...func(event *output.ResultEvent)
Optional callback functions invoked for each result
​
return
error
Returns error if execution fails or context is cancelled
Example: 
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
defer cancel()

err := ne.ExecuteCallbackWithCtx(ctx, func(event *output.ResultEvent) {
	fmt.Printf("Found: %s\n", event.TemplateID)
})

​
Close

Closes the engine and releases all resources. 
func (e *NucleiEngine) Close()
Example: 
ne, _ := nuclei.NewNucleiEngine()
defer ne.Close() // Always defer Close
Always call Close() to prevent resource leaks.

​
Template methods

​
LoadAllTemplates

Loads all templates based on configured filters. 
func (e *NucleiEngine) LoadAllTemplates() error
​
return
error
Returns error if templates cannot be loaded
Example: 
err := ne.LoadAllTemplates()
if err != nil {
	panic(err)
}
Templates are automatically loaded on execution if not manually loaded.

​
GetTemplates

Returns all loaded templates. 
func (e *NucleiEngine) GetTemplates() []*templates.Template
​
return
[]*templates.Template
Slice of loaded template objects
Example: 
templates := ne.GetTemplates()
fmt.Printf("Loaded %d templates\n", len(templates))

​
GetWorkflows

Returns all loaded workflows. 
func (e *NucleiEngine) GetWorkflows() []*templates.Template
​
return
[]*templates.Template
Slice of loaded workflow objects
Example: 
workflows := ne.GetWorkflows()
fmt.Printf("Loaded %d workflows\n", len(workflows))

​
ParseTemplate

Parses a template from raw YAML data. 
func (e *NucleiEngine) ParseTemplate(data []byte) (*templates.Template, error)
​
data
[]byte
required
Raw YAML template data
​
return
*templates.Template, error
Parsed template or error
Example: 
templateData := []byte(`
id: custom-template
info:
  name: Custom Template
  severity: high
http:
  - method: GET
    path:
      - "{{BaseURL}}"
`)

tmpl, err := ne.ParseTemplate(templateData)
if err != nil {
	panic(err)
}
fmt.Printf("Template verified: %v\n", tmpl.Verified)

​
SignTemplate

Signs a template using the provided signer. 
func (e *NucleiEngine) SignTemplate(tmplSigner *signer.TemplateSigner, data []byte) ([]byte, error)
​
tmplSigner
*signer.TemplateSigner
required
Template signer instance
​
data
[]byte
required
Raw template data to sign
​
return
[]byte, error
Signed template data or error
Example: 
import "github.com/projectdiscovery/nuclei/v3/pkg/templates/signer"

tmplSigner := &signer.TemplateSigner{}
signedData, err := ne.SignTemplate(tmplSigner, templateData)

​
Accessor methods

​
GetExecuterOptions

Returns the executor options used by the engine. 
func (e *NucleiEngine) GetExecuterOptions() *protocols.ExecutorOptions
​
return
*protocols.ExecutorOptions
Executor options instance
Example: 
execOpts := ne.GetExecuterOptions()
fmt.Printf("Rate limit: %d\n", execOpts.RateLimiter.GetLimit())

​
Options

Returns the Nuclei type options. 
func (e *NucleiEngine) Options() *types.Options
​
return
*types.Options
Nuclei options instance
Example: 
opts := ne.Options()
fmt.Printf("Template threads: %d\n", opts.TemplateThreads)

​
Engine

Returns the core execution engine. 
func (e *NucleiEngine) Engine() *core.Engine
​
return
*core.Engine
Core engine instance
Example: 
engine := ne.Engine()
workPool := engine.GetWorkPool()

​
Store

Returns the template store. 
func (e *NucleiEngine) Store() *loader.Store
​
return
*loader.Store
Template store instance

​
GetParser

Returns the template parser with cache. 
func (e *NucleiEngine) GetParser() *templates.Parser
​
return
*templates.Parser
Template parser instance

​
Cluster methods

​
GetClusterTemplateIDs

Returns template IDs for a given cluster ID. 
func (e *NucleiEngine) GetClusterTemplateIDs(clusterID string) []string
​
clusterID
string
required
Cluster identifier
​
return
[]string
Template IDs in the cluster, or nil if cluster doesn’t exist
Example: 
templateIDs := ne.GetClusterTemplateIDs("http-get")
fmt.Printf("Templates in cluster: %v\n", templateIDs)

​
GetAllClusterMappings

Returns all cluster mappings. 
func (e *NucleiEngine) GetAllClusterMappings() map[string][]string
​
return
map[string][]string
Map of cluster IDs to template IDs, or nil if engine hasn’t executed
Example: 
mappings := ne.GetAllClusterMappings()
for clusterID, templateIDs := range mappings {
	fmt.Printf("Cluster %s: %v\n", clusterID, templateIDs)
}

​
ThreadSafeNucleiEngine methods

​
GlobalLoadAllTemplates

Loads all templates (thread-safe version). 
func (e *ThreadSafeNucleiEngine) GlobalLoadAllTemplates() error
​
return
error
Returns error if templates cannot be loaded

​
GlobalResultCallback

Sets a global callback for all scan results. 
func (e *ThreadSafeNucleiEngine) GlobalResultCallback(callback func(event *output.ResultEvent))
​
callback
func(event *output.ResultEvent)
required
Callback function invoked for each result
Example: 
ne.GlobalResultCallback(func(event *output.ResultEvent) {
	fmt.Printf("[%s] %s\n", event.TemplateID, event.Host)
})

​
ExecuteNucleiWithOpts

Executes scan with per-scan options (thread-safe). 
func (e *ThreadSafeNucleiEngine) ExecuteNucleiWithOpts(targets []string, opts ...NucleiSDKOptions) error
​
targets
[]string
required
List of targets to scan
​
opts
...NucleiSDKOptions
Options specific to this scan
​
return
error
Returns error if execution fails
Example: 
err := ne.ExecuteNucleiWithOpts(
	[]string{"scanme.sh"},
	nuclei.WithTemplateFilters(nuclei.TemplateFilters{ProtocolTypes: "dns"}),
	nuclei.WithHeaders([]string{"X-Custom: value"}),
)
Deprecated: Use ExecuteNucleiWithOptsCtx for better context control.

​
ExecuteNucleiWithOptsCtx

Executes scan with context and per-scan options (thread-safe). 
func (e *ThreadSafeNucleiEngine) ExecuteNucleiWithOptsCtx(ctx context.Context, targets []string, opts ...NucleiSDKOptions) error
​
ctx
context.Context
required
Context for controlling execution
​
targets
[]string
required
List of targets to scan
​
opts
...NucleiSDKOptions
Options specific to this scan
​
return
error
Returns error if execution fails or context is cancelled
Example: 
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
defer cancel()

err := ne.ExecuteNucleiWithOptsCtx(
	ctx,
	[]string{"scanme.sh"},
	nuclei.WithTemplateFilters(nuclei.TemplateFilters{ProtocolTypes: "dns"}),
)

​
Close (ThreadSafeNucleiEngine)

Closes the thread-safe engine and releases resources. 
func (e *ThreadSafeNucleiEngine) Close()

​
Error types

​
ErrNotImplemented

var ErrNotImplemented = errkit.New("Not implemented")
Returned when a feature is not implemented.

​
ErrNoTemplatesAvailable

var ErrNoTemplatesAvailable = errkit.New("No templates available")
Returned when no templates match the configured filters.

​
ErrNoTargetsAvailable

var ErrNoTargetsAvailable = errkit.New("No targets available")
Returned when no targets are loaded for scanning.

​
ErrOptionsNotSupported

var ErrOptionsNotSupported = errkit.New("Option not supported in thread safe mode")
Returned when using unsupported options with ThreadSafeNucleiEngine.

​
Next steps

Template filters

Learn about template filtering options

Callbacks

Understand callback functions

Build docs developers (and LLMs) love

Get started for freeTalk to us