modules

type ActiveModule ¶

type ActiveModule interface {
	Module

	// AllowedInsertionPointTypes returns which insertion point types this module supports.
	// Return AllInsertionPointTypes to accept all types.
	AllowedInsertionPointTypes() InsertionPointTypeSet

	// ScanPerInsertionPoint performs scanning for a specific insertion point.
	ScanPerInsertionPoint(
		ctx *httpmsg.HttpRequestResponse,
		ip httpmsg.InsertionPoint,
		httpClient *http.Requester,
		scanCtx *ScanContext,
	) ([]*output.ResultEvent, error)

	// ScanPerRequest performs scanning once per unique request.
	ScanPerRequest(
		ctx *httpmsg.HttpRequestResponse,
		httpClient *http.Requester,
		scanCtx *ScanContext,
	) ([]*output.ResultEvent, error)

	// ScanPerHost performs scanning once per unique host.
	ScanPerHost(
		ctx *httpmsg.HttpRequestResponse,
		httpClient *http.Requester,
		scanCtx *ScanContext,
	) ([]*output.ResultEvent, error)
}

ActiveModule is the interface for active scanning modules. Active modules send HTTP requests to detect vulnerabilities.

Implementations must be thread-safe as scan methods will be called concurrently from multiple scanner goroutines.

func GetActiveModules() []ActiveModule

func GetActiveModulesByIDs(ids []string) []ActiveModule

type BaseActiveModule ¶

type BaseActiveModule = modkit.BaseActiveModule

type BaseModule ¶

type BaseModule = modkit.BaseModule

Re-export base types

type BasePassiveModule ¶

type BasePassiveModule = modkit.BasePassiveModule

type BatchFlusher ¶

type BatchFlusher interface {
	FlushFindings(scanCtx *ScanContext) ([]*output.ResultEvent, error)
}

BatchFlusher is an optional interface for passive modules that buffer data and produce deferred findings at end-of-scan. Unlike Flusher (side-effects only), BatchFlusher returns result events that the executor emits through the normal result pipeline (post-hooks, DB storage, callbacks).

type BodyDifferentialConfirmable ¶

type BodyDifferentialConfirmable interface {
	ConfirmsByBodyDifferential() bool
}

BodyDifferentialConfirmable is an optional interface for active modules whose findings should be re-confirmed by the executor's safety net before being reported. When a module implementing it returns true, the executor replays the finding's payload-applied request and compares it against a clean (no-payload) baseline (the pre-scan baseline already on the item, plus one fresh fetch), requiring a reproducible, payload-driven in-band difference and rejecting status flips and dynamic-noise diffs (via modkit.ConfirmBodyDifferential).

Only modules whose true-positive signal IS an in-band body/header difference should opt in. Modules whose signal is out-of-band (OAST), timing-based, a small error string, or whose payload mutates server state (and so must not be replayed) must NOT implement this — they keep their own confirmation.

type ContentClassAware ¶

type ContentClassAware interface {
	RequiredContentClasses() []string
}

ContentClassAware is implemented by modules whose findings structurally require a specific response body class (the canonical names mirror modkit.ContentClass: "html", "json", "xml", "text", "binary"). The executor skips such a module on a record whose response is a confirmed *different* structured class (it fails open on unknown / text). A module that does not implement this interface — and carries none of the content-class tags below — runs against every content type.

This gate is applied to PASSIVE modules only: a passive analyzer that cannot parse the body shape it was given produces nothing, so skipping it can never hide a finding it could otherwise have made. Active modules are intentionally not gated this way — many probe a host independently of the triggering record's body, where content-class gating would cause false negatives.

type ContextualActiveModule ¶

type ContextualActiveModule interface {
	ScanPerInsertionPointContext(
		ctx context.Context,
		item *httpmsg.HttpRequestResponse,
		ip httpmsg.InsertionPoint,
		httpClient *http.Requester,
		scanCtx *ScanContext,
	) ([]*output.ResultEvent, error)

	ScanPerRequestContext(
		ctx context.Context,
		item *httpmsg.HttpRequestResponse,
		httpClient *http.Requester,
		scanCtx *ScanContext,
	) ([]*output.ResultEvent, error)

	ScanPerHostContext(
		ctx context.Context,
		item *httpmsg.HttpRequestResponse,
		httpClient *http.Requester,
		scanCtx *ScanContext,
	) ([]*output.ResultEvent, error)
}

ContextualActiveModule is an optional interface for active modules that support cancellation and timeout propagation through context. The executor prefers these methods when a module implements them, passing the per-call timeout/cancellation context so the module can thread it into cancellable HTTP requests (http.Requester.ExecuteContext). Modules can adopt this incrementally without breaking the legacy ActiveModule interface.

type ContextualPassiveModule ¶

type ContextualPassiveModule interface {
	ScanPerRequestContext(ctx context.Context, item *httpmsg.HttpRequestResponse, scanCtx *ScanContext) ([]*output.ResultEvent, error)
	ScanPerHostContext(ctx context.Context, item *httpmsg.HttpRequestResponse, scanCtx *ScanContext) ([]*output.ResultEvent, error)
}

ContextualPassiveModule is an optional interface for passive modules that support cancellation and timeout propagation through context. Modules can implement this incrementally without breaking the legacy PassiveModule interface.

type Flusher ¶

type Flusher interface {
	Flush(scanCtx *ScanContext)
}

Flusher is an optional interface for passive modules that buffer data and need end-of-scan finalization. The executor calls Flush after all workers have finished processing.

type InsertionPointTypeSet ¶

type InsertionPointTypeSet = modkit.InsertionPointTypeSet

type Module ¶

type Module interface {
	// ID returns unique identifier for the module (e.g., "sqli-error-based").
	ID() string

	// Name returns human-readable name (e.g., "SQLi Error Based Scanner").
	Name() string

	// Description returns detailed description (may contain markdown).
	Description() string

	// ShortDescription returns one-line summary for listings.
	ShortDescription() string

	// ConfirmationCriteria returns a description of how this module confirms a finding.
	ConfirmationCriteria() string

	// Severity returns the severity of issues found by this module.
	Severity() severity.Severity

	// Confidence returns the confidence level of findings produced by this module.
	Confidence() severity.Confidence

	// ScanScopes returns bitmask of supported scan scopes.
	// Must return at least one of: ScanScopeInsertionPoint, ScanScopeRequest, ScanScopeHost.
	ScanScopes() ScanScope

	// Tags returns classification tags for this module (e.g., "xss", "spring", "light").
	// Used for filtering modules via --module-tag flag.
	Tags() []string

	// CanProcess returns true if this module can process the given request.
	// Default implementations skip media files and certain HTTP methods.
	// Modules with special needs (like proxy_escape_detection) can override this.
	CanProcess(ctx *httpmsg.HttpRequestResponse) bool
}

Module is the base interface for all scanner modules. All modules must be thread-safe as scan methods will be called concurrently.

type PassiveModule ¶

type PassiveModule interface {
	Module

	// Scope returns what parts of the HTTP transaction to analyze.
	Scope() PassiveScanScope

	// ScanPerRequest performs passive analysis on each request/response.
	ScanPerRequest(ctx *httpmsg.HttpRequestResponse, scanCtx *ScanContext) ([]*output.ResultEvent, error)

	// ScanPerHost performs passive analysis once per unique host.
	ScanPerHost(ctx *httpmsg.HttpRequestResponse, scanCtx *ScanContext) ([]*output.ResultEvent, error)
}

PassiveModule is the interface for passive scanning modules. Passive modules analyze existing HTTP traffic without sending additional requests.

Implementations must be thread-safe as scan methods will be called concurrently from multiple goroutines.

func GetPassiveModules() []PassiveModule

func GetPassiveModulesByIDs(ids []string) []PassiveModule

type PassiveScanScope ¶

type PassiveScanScope = modkit.PassiveScanScope

type PerScanModule ¶

type PerScanModule interface {
	Fresh() any
}

PerScanModule is an optional interface for active modules that carry mutable state meaningful only within ONE scan (per-host dedup maps, per-scan budgets, compare clients, discovery maps). The registry stores a single shared singleton of each module, so without isolation that state bleeds across concurrent server-mode scans. The runner replaces such a module with a fresh instance for each scan (see freshenPerScanModules); modules whose per-scan state is already isolated via dedup.Lazy(scanCtx.DedupMgr()) or ScanContext need not implement it.

Fresh returns a new instance with zeroed per-scan state. It is typed `any` rather than ActiveModule so a module package can implement it without importing pkg/modules — which would form an import cycle with the registry; the runner asserts the result back to ActiveModule. Implementations are one line:

func (m *Module) Fresh() any { return New() }

type Prioritized ¶

type Prioritized interface {
	Priority() int
}

Prioritized is an optional interface for modules that declare execution priority. Lower values indicate higher priority (0 = highest). Modules without this interface default to DefaultModulePriority (100). Higher priority modules are spawned first, getting earlier access to rate-limit slots.

type Registry ¶

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

Registry manages all scanner modules. Thread-safe for concurrent access.

func NewRegistry() *Registry

func (r *Registry) ActiveModuleCount() int

func (r *Registry) GetActiveModules() []ActiveModule

func (r *Registry) GetActiveModulesByIDs(ids []string) []ActiveModule

func (r *Registry) GetActiveModulesID() []string

func (r *Registry) GetPassiveModules() []PassiveModule

func (r *Registry) GetPassiveModulesByIDs(ids []string) []PassiveModule

func (r *Registry) GetPassiveModulesID() []string

func (r *Registry) PassiveModuleCount() int

func (r *Registry) RegisterActive(m ActiveModule) *Registry

func (r *Registry) RegisterPassive(m PassiveModule) *Registry

func (r *Registry) ResolveModulePatterns(patterns []string) []string

func (r *Registry) ResolveModuleTags(tags []string) []string

type ScanContext ¶

type ScanContext = modkit.ScanContext

Re-export ScanContext

type ScanScope ¶

type ScanScope = modkit.ScanScope

type ScopeAwareModule ¶

type ScopeAwareModule interface {
	ScopeAware() bool
}

ScopeAwareModule is an optional interface for passive modules that should only run on in-scope records. Modules returning true will be skipped when the current item is out of scope. Default behavior (not implementing this interface) is to run on all records regardless of scope.

type TechAware ¶

type TechAware interface {
	RequiredTechs() []string
}

TechAware is an optional interface for modules that only make sense against certain technology stacks. Implement it on framework-specific modules (e.g. Spring, Rails, Django) to skip them on incompatible targets.

Semantics (allowlist):

• Return an empty slice (or do not implement) → module always runs.
• Return ["spring", "java"] → module runs only if the request's host has at least one of those tech tags detected by the *_fingerprint passive modules earlier in the same scan.
• If no tech has been detected for the host yet, the executor fails open and runs the module anyway, so first-request scans aren't pruned.

Tech tags are lowercase strings that match the tag used by fingerprint modules (e.g. "spring", "rails", "django", "laravel", "express", "nextjs", "aspnet", "php", "wordpress").

type TimeoutHinter ¶

type TimeoutHinter interface {
	TimeoutHint() time.Duration
}

TimeoutHinter is an optional interface for active or passive modules that need more time than the global per-module timeout (PassiveModuleTimeout for passive modules, ActiveModuleTimeout for active modules). The executor only honors the hint when it exceeds the applicable default; modules that do not implement this interface use the executor's default timeout.

type VulnClassifier ¶

type VulnClassifier interface {
	VulnClass() string // e.g., "xss", "sqli", "ssti"
}

VulnClassifier is an optional interface for modules that declare their vulnerability class for cross-module deduplication. When a module reports a finding, the executor marks the (URL, param, vuln_class) as found. Other modules with the same vuln class can check and skip redundant scanning.