nuclei

package
v3.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 30, 2023 License: MIT Imports: 43 Imported by: 9

README

Using Nuclei as Library

Nuclei was primarily built as a CLI tool, but with increasing choice of users wanting to use nuclei as library in their own automation, we have added a simplified Library/SDK of nuclei in v3

Installation

To add nuclei as a library to your go project, you can use the following command:

go get -u github.com/projectdiscovery/nuclei/v3/lib

Or add below import to your go file and let IDE handle the rest:

import nuclei "github.com/projectdiscovery/nuclei/v3/lib"

Basic Example of using Nuclei Library/SDK

// create nuclei engine with options
	ne, err := nuclei.NewNucleiEngine(
		nuclei.WithTemplateFilters(nuclei.TemplateFilters{Severity: "critical"}), // run critical severity templates only
	)
	if err != nil {
		panic(err)
	}
	// load targets and optionally probe non http/https targets
	ne.LoadTargets([]string{"scanme.sh"}, false)
	err = ne.ExecuteWithCallback(nil)
	if err != nil {
		panic(err)
	}
	defer ne.Close()

Advanced Example of using Nuclei Library/SDK

For Various use cases like batching etc you might want to run nuclei in goroutines this can be done by using nuclei.NewThreadSafeNucleiEngine

// create nuclei engine with options
	ne, err := nuclei.NewThreadSafeNucleiEngine()
	if err != nil{
        panic(err)
    }
	// setup waitgroup to handle concurrency
	wg := &sync.WaitGroup{}

	// scan 1 = run dns templates on scanme.sh
	wg.Add(1)
	go func() {
		defer wg.Done()
		err = ne.ExecuteNucleiWithOpts([]string{"scanme.sh"}, nuclei.WithTemplateFilters(nuclei.TemplateFilters{ProtocolTypes: "http"}))
		if err != nil {
            panic(err)
        }
	}()

	// scan 2 = run http templates on honey.scanme.sh
	wg.Add(1)
	go func() {
		defer wg.Done()
		err = ne.ExecuteNucleiWithOpts([]string{"honey.scanme.sh"}, nuclei.WithTemplateFilters(nuclei.TemplateFilters{ProtocolTypes: "dns"}))
		if err != nil {
            panic(err)
        }
	}()

	// wait for all scans to finish
	wg.Wait()
	defer ne.Close()

More Documentation

For complete documentation of nuclei library, please refer to godoc which contains all available options and methods.

Note

❗ Disclaimer
This project is in active development. Expect breaking changes with releases. Review the release changelog before updating.
This project was primarily built to be used as a standalone CLI tool. Running nuclei as a service may pose security risks. It's recommended to use with caution and additional security measures.

Documentation

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	// ErrNotImplemented is returned when a feature is not implemented
	ErrNotImplemented = errorutil.New("Not implemented")
	// ErrNoTemplatesAvailable is returned when no templates are available to execute
	ErrNoTemplatesAvailable = errorutil.New("No templates available")
	// ErrNoTargetsAvailable is returned when no targets are available to scan
	ErrNoTargetsAvailable = errorutil.New("No targets available")
	// ErrOptionsNotSupported is returned when an option is not supported in thread safe mode
	ErrOptionsNotSupported = errorutil.NewWithFmt("Option %v not supported in thread safe mode")
)
View Source 
var DefaultConfig *config.Config

DefaultConfig is instance of default nuclei configs any mutations to this config will be reflected in all nuclei instances (saves some config to disk)

Functions

func GetTargetsFromTemplateMetadata 

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

GetTargetsFromTemplateMetadata returns all targets by querying engine metadata (ex: fofo-query,shodan-query) etc from given templates . supported formats are any string with [ip,host,port,url] placeholders

func GetTargetsFromUncover 

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

GetTargetsFromUncover returns targets from uncover in given format . supported formats are any string with [ip,host,port,url] placeholders

Types

type Concurrency 

type Concurrency struct {
	TemplateConcurrency         int // number of templates to run concurrently (per host in host-spray mode)
	HostConcurrency             int // number of hosts to scan concurrently  (per template in template-spray mode)
	HeadlessHostConcurrency     int // number of hosts to scan concurrently for headless templates  (per template in template-spray mode)
	HeadlessTemplateConcurrency int // number of templates to run concurrently for headless templates (per host in host-spray mode)
}

Concurrency options

type HeadlessOpts 

type HeadlessOpts struct {
	PageTimeout     int // timeout for page load
	ShowBrowser     bool
	HeadlessOptions []string
	UseChrome       bool
}

HeadlessOpts contains options for headless templates

type InteractshOpts 

type InteractshOpts interactsh.Options

InteractshOpts contains options for interactsh

type NetworkConfig 

type NetworkConfig struct {
	Timeout           int      // Timeout in seconds
	Retries           int      // Number of retries
	LeaveDefaultPorts bool     // Leave default ports for http/https
	MaxHostError      int      // Maximum number of host errors to allow before skipping that host
	TrackError        []string // Adds given errors to max host error watchlist
	DisableMaxHostErr bool     // Disable max host error optimization (Hosts are not skipped even if they are not responding)
}

NetworkConfig contains network config options ex: retries , httpx probe , timeout etc

type NucleiEngine 

type NucleiEngine struct {
	// contains filtered or unexported fields
}

NucleiEngine is the Engine/Client for nuclei which runs scans using templates and returns results

Example

A very simple example on how to use nuclei engine 

package main

import (
	nuclei "github.com/projectdiscovery/nuclei/v3/lib"
)

func main() {
	// create nuclei engine with options
	ne, err := nuclei.NewNucleiEngine(
		nuclei.WithTemplateFilters(nuclei.TemplateFilters{IDs: []string{"self-signed-ssl"}}), // only run self-signed-ssl template
	)
	if err != nil {
		panic(err)
	}
	// load targets and optionally probe non http/https targets
	ne.LoadTargets([]string{"scanme.sh"}, false)
	// when callback is nil it nuclei will print JSON output to stdout
	err = ne.ExecuteWithCallback(nil)
	if err != nil {
		panic(err)
	}
	defer ne.Close()

}

Output:

[self-signed-ssl] scanme.sh:443

func NewNucleiEngine 

func NewNucleiEngine(options ...NucleiSDKOptions) (*NucleiEngine, error)

NewNucleiEngine creates a new nuclei engine instance

func (*NucleiEngine) Close 

func (e *NucleiEngine) Close()

Close all resources used by nuclei engine

func (*NucleiEngine) ExecuteWithCallback 

func (e *NucleiEngine) ExecuteWithCallback(callback ...func(event *output.ResultEvent)) error

ExecuteWithCallback executes templates on targets and calls callback on each result(only if results are found)

func (*NucleiEngine) GetExecuterOptions added in v3.0.3 

func (e *NucleiEngine) GetExecuterOptions() *protocols.ExecutorOptions

GetExecuterOptions returns the nuclei executor options

func (*NucleiEngine) GetTemplates 

func (e *NucleiEngine) GetTemplates() []*templates.Template

GetTemplates returns all nuclei templates that are loaded

func (*NucleiEngine) LoadAllTemplates 

func (e *NucleiEngine) LoadAllTemplates() error

LoadAllTemplates loads all nuclei template based on given options

func (*NucleiEngine) LoadTargets 

func (e *NucleiEngine) LoadTargets(targets []string, probeNonHttp bool)

LoadTargets(urls/domains/ips only) adds targets to the nuclei engine

func (*NucleiEngine) LoadTargetsFromReader 

func (e *NucleiEngine) LoadTargetsFromReader(reader io.Reader, probeNonHttp bool)

LoadTargetsFromReader adds targets(urls/domains/ips only) from reader to the nuclei engine

func (*NucleiEngine) ParseTemplate added in v3.0.3 

func (e *NucleiEngine) ParseTemplate(data []byte) (*templates.Template, error)

ParseTemplate parses a template from given data template verification status can be accessed from template.Verified

func (*NucleiEngine) SignTemplate added in v3.0.3 

func (e *NucleiEngine) SignTemplate(tmplSigner *signer.TemplateSigner, data []byte) ([]byte, error)

SignTemplate signs the tempalate using given signer

type NucleiSDKOptions 

type NucleiSDKOptions func(e *NucleiEngine) error

NucleiSDKOptions contains options for nuclei SDK

func EnableCodeTemplates added in v3.0.4 

func EnableCodeTemplates() NucleiSDKOptions

EnableCodeTemplates allows loading/executing code protocol templates

func EnableHeadlessWithOpts 

func EnableHeadlessWithOpts(hopts *HeadlessOpts) NucleiSDKOptions

EnableHeadless allows execution of headless templates *Use With Caution*: Enabling headless mode may open up attack surface due to browser usage and can be prone to exploitation by custom unverified templates if not properly configured

func EnableStatsWithOpts 

func EnableStatsWithOpts(opts StatsOptions) NucleiSDKOptions

EnableStats enables Stats collection with defined interval(in sec) and callback Note: callback is executed in a separate goroutine

func UseOutputWriter 

func UseOutputWriter(writer OutputWriter) NucleiSDKOptions

UseWriter allows setting custom output writer by default a mock writer is used with user defined callback if outputWriter is used callback will be ignored

func UseStatsWriter 

func UseStatsWriter(writer StatsWriter) NucleiSDKOptions

UseStatsWriter allows setting a custom stats writer which can be used to write stats somewhere (ex: send to webserver etc)

func WithConcurrency 

func WithConcurrency(opts Concurrency) NucleiSDKOptions

WithConcurrency sets concurrency options

func WithGlobalRateLimit 

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

WithGlobalRateLimit sets global rate (i.e all hosts combined) limit options

func WithInteractshOptions 

func WithInteractshOptions(opts InteractshOpts) NucleiSDKOptions

WithInteractshOptions sets interactsh options

func WithNetworkConfig 

func WithNetworkConfig(opts NetworkConfig) NucleiSDKOptions

WithNetworkConfig allows setting network config options

func WithProxy 

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

WithProxy allows setting proxy options

func WithSandboxOptions 

func WithSandboxOptions(allowLocalFileAccess bool, restrictLocalNetworkAccess bool) NucleiSDKOptions

WithSandboxOptions allows setting supported sandbox options

func WithScanStrategy 

func WithScanStrategy(strategy string) NucleiSDKOptions

WithScanStrategy allows setting scan strategy options

func WithTemplateFilters 

func WithTemplateFilters(filters TemplateFilters) NucleiSDKOptions

WithTemplateFilters sets template filters and only templates matching the filters will be loaded and executed

func WithTemplateUpdateCallback 

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

WithTemplateUpdateCallback allows setting a callback which will be called when nuclei templates are outdated Note: Nuclei-templates are crucial part of nuclei and using outdated templates or nuclei sdk is not recommended as it may cause unexpected results due to compatibility issues

func WithTemplatesOrWorkflows 

func WithTemplatesOrWorkflows(sources TemplateSources) NucleiSDKOptions

WithTemplatesOrWorkflows sets templates / workflows to use /load

func WithVerbosity 

func WithVerbosity(opts VerbosityOptions) NucleiSDKOptions

WithVerbosity allows setting verbosity options of (internal) nuclei engine and does not affect SDK output

type OutputWriter 

type OutputWriter output.Writer

OutputWriter

type StatsOptions 

type StatsOptions struct {
	Interval         int
	JSON             bool
	MetricServerPort int
}

StatsOptions

type StatsWriter 

type StatsWriter progress.Progress

StatsWriter

type TemplateFilters 

type TemplateFilters struct {
	Severity             string   // filter by severities (accepts CSV values of info, low, medium, high, critical)
	ExcludeSeverities    string   // filter by excluding severities (accepts CSV values of info, low, medium, high, critical)
	ProtocolTypes        string   // filter by protocol types
	ExcludeProtocolTypes string   // filter by excluding protocol types
	Authors              []string // fiter by author
	Tags                 []string // filter by tags present in template
	ExcludeTags          []string // filter by excluding tags present in template
	IncludeTags          []string // filter by including tags present in template
	IDs                  []string // filter by template IDs
	ExcludeIDs           []string // filter by excluding template IDs
	TemplateCondition    []string // DSL condition/ expression
}

config contains all SDK configuration options

type TemplateSources 

type TemplateSources struct {
	Templates       []string // template file/directory paths
	Workflows       []string // workflow file/directory paths
	RemoteTemplates []string // remote template urls
	RemoteWorkflows []string // remote workflow urls
	TrustedDomains  []string // trusted domains for remote templates/workflows
}

TemplateSources contains template sources which define where to load templates from

type ThreadSafeNucleiEngine 

type ThreadSafeNucleiEngine struct {
	// contains filtered or unexported fields
}

ThreadSafeNucleiEngine is a tweaked version of nuclei.Engine whose methods are thread-safe and can be used concurrently. Non-thread-safe methods start with Global prefix

Example 
package main

import (
	nuclei "github.com/projectdiscovery/nuclei/v3/lib"
	"github.com/remeh/sizedwaitgroup"
)

func main() {
	// create nuclei engine with options
	ne, err := nuclei.NewThreadSafeNucleiEngine()
	if err != nil {
		panic(err)
	}
	// setup sizedWaitgroup to handle concurrency
	// here we are using sizedWaitgroup to limit concurrency to 1
	// but can be anything in general
	sg := sizedwaitgroup.New(1)

	// scan 1 = run dns templates on scanme.sh
	sg.Add()
	go func() {
		defer sg.Done()
		err = ne.ExecuteNucleiWithOpts([]string{"scanme.sh"},
			nuclei.WithTemplateFilters(nuclei.TemplateFilters{IDs: []string{"nameserver-fingerprint"}}), // only run self-signed-ssl template
		)
		if err != nil {
			panic(err)
		}
	}()

	// scan 2 = run dns templates on honey.scanme.sh
	sg.Add()
	go func() {
		defer sg.Done()
		err = ne.ExecuteNucleiWithOpts([]string{"honey.scanme.sh"}, nuclei.WithTemplateFilters(nuclei.TemplateFilters{ProtocolTypes: "dns"}))
		if err != nil {
			panic(err)
		}
	}()

	// wait for all scans to finish
	sg.Wait()
	defer ne.Close()

}

Output:

[nameserver-fingerprint] scanme.sh
[caa-fingerprint] honey.scanme.sh

func NewThreadSafeNucleiEngine 

func NewThreadSafeNucleiEngine(opts ...NucleiSDKOptions) (*ThreadSafeNucleiEngine, error)

NewThreadSafeNucleiEngine creates a new nuclei engine with given options whose methods are thread-safe and can be used concurrently Note: Non-thread-safe methods start with Global prefix

func (*ThreadSafeNucleiEngine) Close 

func (e *ThreadSafeNucleiEngine) Close()

Close all resources used by nuclei engine

func (*ThreadSafeNucleiEngine) ExecuteNucleiWithOpts 

func (e *ThreadSafeNucleiEngine) ExecuteNucleiWithOpts(targets []string, opts ...NucleiSDKOptions) error

ExecuteWithCallback executes templates on targets and calls callback on each result(only if results are found) This method can be called concurrently and it will use some global resources but can be runned parllely by invoking this method with different options and targets Note: Not all options are thread-safe. this method will throw error if you try to use non-thread-safe options

func (*ThreadSafeNucleiEngine) GlobalLoadAllTemplates 

func (e *ThreadSafeNucleiEngine) GlobalLoadAllTemplates() error

GlobalLoadAllTemplates loads all templates from nuclei-templates repo This method will load all templates based on filters given at the time of nuclei engine creation in opts

func (*ThreadSafeNucleiEngine) GlobalResultCallback 

func (e *ThreadSafeNucleiEngine) GlobalResultCallback(callback func(event *output.ResultEvent))

GlobalResultCallback sets a callback function which will be called for each result

type VerbosityOptions 

type VerbosityOptions struct {
	Verbose       bool // show verbose output
	Silent        bool // show only results
	Debug         bool // show debug output
	DebugRequest  bool // show request in debug output
	DebugResponse bool // show response in debug output
	ShowVarDump   bool // show variable dumps in output
}

VerbosityOptions

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.