SDK options reference

This page provides detailed API documentation for all configuration options available in the Nuclei SDK.

Option types

NucleiSDKOptions

Function signature for SDK options:

type NucleiSDKOptions func(e *NucleiEngine) error

Options are functions that configure the NucleiEngine during initialization.

Template and workflow options

WithTemplatesOrWorkflows

Specifies template and workflow sources.

func WithTemplatesOrWorkflows(sources TemplateSources) NucleiSDKOptions

Parameters:

sources

TemplateSources

required

Template source configuration

TemplateSources structure:

type TemplateSources struct {
	Templates       []string // Local template paths
	Workflows       []string // Local workflow paths
	RemoteTemplates []string // Remote template URLs
	RemoteWorkflows []string // Remote workflow URLs
	TrustedDomains  []string // Trusted domains for remote sources
}

Example:

nuclei.WithTemplatesOrWorkflows(nuclei.TemplateSources{
	Templates: []string{"/path/to/templates"},
	Workflows: []string{"/path/to/workflows"},
	RemoteTemplates: []string{"https://example.com/template.yaml"},
	TrustedDomains: []string{"example.com"},
})

WithTemplateFilters

Filters templates based on criteria.

func WithTemplateFilters(filters TemplateFilters) NucleiSDKOptions

Parameters:

filters

TemplateFilters

required

Template filter configuration

See TemplateFilters API for detailed documentation.

Concurrency options

WithConcurrency

Configures concurrency settings for scanning.

func WithConcurrency(opts Concurrency) NucleiSDKOptions

Parameters:

opts

Concurrency

required

Concurrency configuration

Concurrency structure:

type Concurrency struct {
	TemplateConcurrency           int
	HostConcurrency               int
	HeadlessHostConcurrency       int
	HeadlessTemplateConcurrency   int
	JavascriptTemplateConcurrency int
	TemplatePayloadConcurrency    int
	ProbeConcurrency              int
}

Example:

nuclei.WithConcurrency(nuclei.Concurrency{
	TemplateConcurrency: 25,
	HostConcurrency: 25,
	HeadlessHostConcurrency: 10,
	HeadlessTemplateConcurrency: 10,
	JavascriptTemplateConcurrency: 120,
	TemplatePayloadConcurrency: 25,
	ProbeConcurrency: 50,
})

Validation:

All values must be at least 1
Returns error if any value is ≤ 0

WithGlobalRateLimit

Sets global rate limiting across all targets.

func WithGlobalRateLimit(maxTokens int, duration time.Duration) NucleiSDKOptions

Deprecated: Use WithGlobalRateLimitCtx instead.

Parameters:

maxTokens

int

required

Maximum number of requests per duration

duration

time.Duration

required

Time window for rate limiting

Example:

nuclei.WithGlobalRateLimit(150, time.Second)

WithGlobalRateLimitCtx

Sets global rate limiting with context support.

func WithGlobalRateLimitCtx(ctx context.Context, maxTokens int, duration time.Duration) NucleiSDKOptions

Parameters:

ctx

context.Context

required

Context for rate limiter lifecycle

maxTokens

int

required

Maximum requests per duration

duration

time.Duration

required

Time window for rate limiting

Example:

ctx := context.Background()
nuclei.WithGlobalRateLimitCtx(ctx, 150, time.Second)

Network options

WithNetworkConfig

Configures network-related settings.

func WithNetworkConfig(opts NetworkConfig) NucleiSDKOptions

Parameters:

opts

NetworkConfig

required

Network configuration

NetworkConfig structure:

type NetworkConfig struct {
	DisableMaxHostErr     bool
	Interface             string
	InternalResolversList []string
	LeaveDefaultPorts     bool
	MaxHostError          int
	Retries               int
	SourceIP              string
	SystemResolvers       bool
	Timeout               int
	TrackError            []string
}

Example:

nuclei.WithNetworkConfig(nuclei.NetworkConfig{
	Timeout: 30,
	Retries: 3,
	MaxHostError: 30,
	InternalResolversList: []string{"1.1.1.1", "8.8.8.8"},
})

For ThreadSafeNucleiEngine, this option can only be set during initialization.

WithProxy

Configures HTTP proxy settings.

func WithProxy(proxy []string, proxyInternalRequests bool) NucleiSDKOptions

Parameters:

proxy

[]string

required

List of proxy URLs

proxyInternalRequests

bool

required

Whether to proxy internal requests

Example:

nuclei.WithProxy(
	[]string{"http://proxy.example.com:8080"},
	true,
)

Not supported with ThreadSafeNucleiEngine.

WithResponseReadSize

Sets maximum response body size to read.

func WithResponseReadSize(responseReadSize int) NucleiSDKOptions

Parameters:

responseReadSize

int

required

Maximum size in bytes (0 = unlimited)

Example:

nuclei.WithResponseReadSize(10485760) // 10MB limit

Validation:

Must be non-negative
Returns error if value < 0

Feature flags

EnableCodeTemplates

Enables code protocol templates.

func EnableCodeTemplates() NucleiSDKOptions

Example:

ne, err := nuclei.NewNucleiEngine(
	nuclei.EnableCodeTemplates(),
)

Code templates can execute arbitrary code. Only use with trusted templates.

EnableSelfContainedTemplates

Enables self-contained templates.

func EnableSelfContainedTemplates() NucleiSDKOptions

Example:

nuclei.EnableSelfContainedTemplates()

EnableGlobalMatchersTemplates

Enables global-matchers templates.

func EnableGlobalMatchersTemplates() NucleiSDKOptions

EnableFileTemplates

Enables file protocol templates.

func EnableFileTemplates() NucleiSDKOptions

EnablePassiveMode

Enables passive HTTP response processing.

func EnablePassiveMode() NucleiSDKOptions

Example:

nuclei.EnablePassiveMode()

EnableMatcherStatus

Enables matcher status in results.

func EnableMatcherStatus() NucleiSDKOptions

DisableTemplateCache

Disables template caching.

func DisableTemplateCache() NucleiSDKOptions

SignedTemplatesOnly

Only loads and executes signed templates.

func SignedTemplatesOnly() NucleiSDKOptions

DASTMode

Only runs DAST templates.

func DASTMode() NucleiSDKOptions

Headless options

EnableHeadlessWithOpts

Enables headless browser support.

func EnableHeadlessWithOpts(hopts *HeadlessOpts) NucleiSDKOptions

Parameters:

hopts

*HeadlessOpts

required

Headless configuration

HeadlessOpts structure:

type HeadlessOpts struct {
	PageTimeout     int
	ShowBrowser     bool
	HeadlessOptions []string
	UseChrome       bool
}

Example:

nuclei.EnableHeadlessWithOpts(&nuclei.HeadlessOpts{
	PageTimeout: 20,
	ShowBrowser: false,
	UseChrome: false,
	HeadlessOptions: []string{"--no-sandbox", "--disable-gpu"},
})

Enabling headless mode may open attack surface. Use with caution.

Interactsh options

WithInteractshOptions

Configures Interactsh for OAST detection.

func WithInteractshOptions(opts InteractshOpts) NucleiSDKOptions

Parameters:

opts

InteractshOpts

required

Interactsh configuration

InteractshOpts structure:

type InteractshOpts interactsh.Options

Example:

import "github.com/projectdiscovery/nuclei/v3/pkg/protocols/common/interactsh"

nuclei.WithInteractshOptions(nuclei.InteractshOpts{
	ServerURL: "https://interact.sh",
	CacheSize: 5000,
	Eviction: 60,
	CooldownPeriod: 5,
	PollDuration: 5,
})

For ThreadSafeNucleiEngine, can only be set during initialization.

Stats and monitoring

EnableStatsWithOpts

Enables statistics collection.

func EnableStatsWithOpts(opts StatsOptions) NucleiSDKOptions

Parameters:

opts

StatsOptions

required

Statistics configuration

StatsOptions structure:

type StatsOptions struct {
	Interval         int  // seconds, default: 5
	JSON             bool
	MetricServerPort int
}

Example:

nuclei.EnableStatsWithOpts(nuclei.StatsOptions{
	Interval: 5,
	JSON: true,
	MetricServerPort: 6064,
})

Not supported with ThreadSafeNucleiEngine.

Logging options

WithVerbosity

Configures logging verbosity.

func WithVerbosity(opts VerbosityOptions) NucleiSDKOptions

Parameters:

opts

VerbosityOptions

required

Verbosity configuration

VerbosityOptions structure:

type VerbosityOptions struct {
	Verbose       bool
	Silent        bool
	Debug         bool
	DebugRequest  bool
	DebugResponse bool
	ShowVarDump   bool
}

Example:

nuclei.WithVerbosity(nuclei.VerbosityOptions{
	Verbose: true,
	Debug: false,
	DebugRequest: false,
	DebugResponse: false,
})

Not supported with ThreadSafeNucleiEngine.

WithLogger

Sets a custom logger instance.

func WithLogger(logger *gologger.Logger) NucleiSDKOptions

Parameters:

logger

*gologger.Logger

required

Custom logger instance

Example:

import "github.com/projectdiscovery/gologger"

logger := gologger.NewLogger()
nuclei.WithLogger(logger)

Custom handlers

UseOutputWriter

Sets a custom output writer.

func UseOutputWriter(writer OutputWriter) NucleiSDKOptions

Parameters:

writer

OutputWriter

required

Custom output writer implementation

Example:

type CustomWriter struct{}

func (w *CustomWriter) Write(event *output.ResultEvent) error {
	return nil
}

func (w *CustomWriter) Close() {}

nuclei.UseOutputWriter(&CustomWriter{})

Not supported with ThreadSafeNucleiEngine.

UseStatsWriter

Sets a custom stats writer.

func UseStatsWriter(writer StatsWriter) NucleiSDKOptions

Parameters:

writer

StatsWriter

required

Custom stats writer implementation

Not supported with ThreadSafeNucleiEngine.

WithTemplateUpdateCallback

Sets callback for template updates.

func WithTemplateUpdateCallback(disableTemplatesAutoUpgrade bool, callback func(newVersion string)) NucleiSDKOptions

Parameters:

disableTemplatesAutoUpgrade

bool

required

Whether to disable automatic template upgrades

callback

func(newVersion string)

required

Callback invoked when updates are available

Example:

nuclei.WithTemplateUpdateCallback(
	false,
	func(newVersion string) {
		fmt.Printf("New templates version: %s\n", newVersion)
	},
)

Not supported with ThreadSafeNucleiEngine.

Authentication options

WithAuthProvider

Sets a custom authentication provider.

func WithAuthProvider(provider authprovider.AuthProvider) NucleiSDKOptions

Parameters:

provider

authprovider.AuthProvider

required

Custom authentication provider

LoadSecretsFromFile

Loads secrets from files.

func LoadSecretsFromFile(files []string, prefetch bool) NucleiSDKOptions

Parameters:

files

[]string

required

List of secret file paths

prefetch

bool

required

Whether to prefetch secrets

Example:

nuclei.LoadSecretsFromFile(
	[]string{"/path/to/secrets.yaml"},
	true,
)

WithHeaders

Sets custom headers for all HTTP requests.

func WithHeaders(headers []string) NucleiSDKOptions

Parameters:

headers

[]string

required

List of headers in “key: value” format

Example:

nuclei.WithHeaders([]string{
	"X-Custom-Header: value",
	"Cookie: session=abc123",
	"Authorization: Bearer token",
})

WithVars

Sets custom variables for template context.

func WithVars(vars []string) NucleiSDKOptions

Parameters:

vars

[]string

required

List of variables in “key=value” format

Example:

nuclei.WithVars([]string{
	"api_key=secret123",
	"username=admin",
})

Sandbox options

WithSandboxOptions

Configures sandbox security settings.

func WithSandboxOptions(allowLocalFileAccess bool, restrictLocalNetworkAccess bool) NucleiSDKOptions

Parameters:

allowLocalFileAccess

bool

required

Allow templates to access local files

restrictLocalNetworkAccess

bool

required

Restrict access to local/private networks

Example:

nuclei.WithSandboxOptions(true, false)

Not supported with ThreadSafeNucleiEngine.

Scan strategy

WithScanStrategy

Sets the scanning strategy.

func WithScanStrategy(strategy string) NucleiSDKOptions

Parameters:

strategy

string

required

Scan strategy: “host-spray” or “template-spray”

Example:

nuclei.WithScanStrategy("template-spray")

Advanced options

WithCatalog

Uses a custom catalog instance.

func WithCatalog(cat catalog.Catalog) NucleiSDKOptions

Parameters:

cat

catalog.Catalog

required

Custom catalog implementation

WithOptions

Sets all options at once using types.Options.

func WithOptions(opts *pkgtypes.Options) NucleiSDKOptions

Parameters:

opts

*types.Options

required

Complete Nuclei options

Example:

import "github.com/projectdiscovery/nuclei/v3/pkg/types"

opts := types.DefaultOptions()
opts.TemplateThreads = 50
nuclei.WithOptions(opts)

WithResumeFile

Enables scan resumption.

func WithResumeFile(file string) NucleiSDKOptions

Parameters:

file

string

required

Path to resume configuration file

Example:

nuclei.WithResumeFile("/tmp/nuclei-resume.cfg")

WithTemporaryDirectory

Sets custom temporary directory.

func WithTemporaryDirectory(parentDir string) NucleiSDKOptions

Parameters:

parentDir

string

required

Parent directory for SDK temporary files

Example:

nuclei.WithTemporaryDirectory("/custom/tmp")

DisableUpdateCheck

Disables automatic update checks.

func DisableUpdateCheck() NucleiSDKOptions

Example:

nuclei.DisableUpdateCheck()

Helper functions

GetTargetsFromUncover

Returns targets from Uncover in specified format.

func GetTargetsFromUncover(ctx context.Context, outputFormat string, opts *uncover.Options) (chan string, error)

Parameters:

ctx

context.Context

required

Context for operation

outputFormat

string

required

Format string with [ip,host,port,url] placeholders

opts

*uncover.Options

required

Uncover configuration

GetTargetsFromTemplateMetadata

Returns targets from template metadata (shodan-query, fofa-query, etc.).

func GetTargetsFromTemplateMetadata(ctx context.Context, templates []*templates.Template, outputFormat string, opts *uncover.Options) chan string

Parameters:

ctx

context.Context

required

Context for operation

templates

[]*templates.Template

required

Templates with metadata queries

outputFormat

string

required

Format string with placeholders

opts

*uncover.Options

required

Uncover configuration

Next steps

NucleiEngine API

Explore engine methods

Callbacks

Learn about result callbacks

Library Usage

API Reference

​Option types

​NucleiSDKOptions

​Template and workflow options

​WithTemplatesOrWorkflows

​WithTemplateFilters

​Concurrency options

​WithConcurrency

​WithGlobalRateLimit

​WithGlobalRateLimitCtx

​Network options

​WithNetworkConfig

​WithProxy

​WithResponseReadSize

​Feature flags

​EnableCodeTemplates

​EnableSelfContainedTemplates

​EnableGlobalMatchersTemplates

​EnableFileTemplates

​EnablePassiveMode

​EnableMatcherStatus

​DisableTemplateCache

​SignedTemplatesOnly

​DASTMode

​Headless options

​EnableHeadlessWithOpts

​Interactsh options

​WithInteractshOptions

​Stats and monitoring

​EnableStatsWithOpts

​Logging options

​WithVerbosity

​WithLogger

​Custom handlers

​UseOutputWriter

​UseStatsWriter

​WithTemplateUpdateCallback

​Authentication options

​WithAuthProvider

​LoadSecretsFromFile

​WithHeaders

​WithVars

​Sandbox options

​WithSandboxOptions

​Scan strategy

​WithScanStrategy

​Advanced options

​WithCatalog

​WithOptions

​WithResumeFile

​WithTemporaryDirectory

​DisableUpdateCheck

​Helper functions

​GetTargetsFromUncover

​GetTargetsFromTemplateMetadata

​Next steps

NucleiEngine API

Callbacks

Build docs developers (and LLMs) love

Option types

NucleiSDKOptions

Template and workflow options

WithTemplatesOrWorkflows

WithTemplateFilters

Concurrency options

WithConcurrency

WithGlobalRateLimit

WithGlobalRateLimitCtx

Network options

WithNetworkConfig

WithProxy

WithResponseReadSize

Feature flags

EnableCodeTemplates

EnableSelfContainedTemplates

EnableGlobalMatchersTemplates

EnableFileTemplates

EnablePassiveMode

EnableMatcherStatus

DisableTemplateCache

SignedTemplatesOnly

DASTMode

Headless options

EnableHeadlessWithOpts

Interactsh options

WithInteractshOptions

Stats and monitoring

EnableStatsWithOpts

Logging options

WithVerbosity

WithLogger

Custom handlers

UseOutputWriter

UseStatsWriter

WithTemplateUpdateCallback

Authentication options

WithAuthProvider

LoadSecretsFromFile

WithHeaders

WithVars

Sandbox options

WithSandboxOptions

Scan strategy

WithScanStrategy

Advanced options

WithCatalog

WithOptions

WithResumeFile

WithTemporaryDirectory

DisableUpdateCheck

Helper functions

GetTargetsFromUncover

GetTargetsFromTemplateMetadata

Next steps