god-eye/internal/module/module.go

// Package module defines the Module interface and Registry used by God's Eye v2
// to organize discovery, enrichment, analysis, and reporting units of work.
//
// A Module is any unit of the pipeline that subscribes to zero-or-more event
// types, produces zero-or-more event types, and optionally performs a bounded
// amount of work on startup (e.g. a passive source fetches once and publishes).
//
// Modules are decoupled: they do not call each other directly. Ordering emerges
// from the event-driven dependency graph, not from phase barriers. The Phase
// label is metadata used for grouping in progress UIs and logs, not a scheduling
// primitive.
package module

import (
	"context"

	"god-eye/internal/eventbus"
	"god-eye/internal/store"
)

// Phase groups modules at similar pipeline stages for presentation. Modules at
// different phases may still run concurrently; the scanner does not enforce
// phase barriers.
type Phase string

const (
	PhaseSetup      Phase = "setup"      // load DBs, wordlists, validate config
	PhaseDiscovery  Phase = "discovery"  // subdomain sources (passive, CT, brute, recursive)
	PhaseResolution Phase = "resolution" // DNS resolve, CNAME, PTR, IP info, wildcard filter
	PhaseEnrichment Phase = "enrichment" // HTTP probe, tech fingerprint, TLS analyze
	PhaseAnalysis   Phase = "analysis"   // security checks, takeover, secrets, AI, CVE match
	PhaseReporting  Phase = "reporting"  // output writers, report generation
)

// Context bundles everything a module needs to run.
//
// The Ctx field carries cancellation — every long-running module must select
// on Ctx.Done() to exit cleanly when the user interrupts.
type Context struct {
	Ctx     context.Context
	Bus     *eventbus.Bus
	Store   store.Store
	Config  ConfigView
	Target  string // primary target domain
	Profile string // active profile name (bugbounty, pentest, stealth-max, ...)
}

// ConfigView is a narrow read-only interface over the scan config, exposed to
// modules so they cannot mutate global state. Implementations live in the
// config package.
type ConfigView interface {
	// Profile returns the active profile name ("" when none is selected).
	Profile() string
	// Bool reads a boolean config key, returning fallback if unset.
	Bool(key string, fallback bool) bool
	// Int reads an int key, returning fallback if unset.
	Int(key string, fallback int) int
	// String reads a string key, returning fallback if unset.
	String(key string, fallback string) string
	// Strings reads a string-slice key.
	Strings(key string) []string
	// ModuleEnabled lets the user disable a module by name. Registry honors
	// this during selection.
	ModuleEnabled(moduleName string) bool
}

// Module is the unit of work registered in the pipeline.
//
// Implementations should:
//   - be cheap to construct (no I/O in the Module value itself)
//   - do all setup/teardown inside Run so lifecycle is explicit
//   - subscribe to events via mctx.Bus.Subscribe in Run
//   - return promptly when mctx.Ctx is canceled OR when their work is complete
type Module interface {
	// Name uniquely identifies the module. Use dotted notation grouping by
	// concern: "sources.crtsh", "dns.resolver", "http.probe", "security.cors",
	// "ai.cascade". The registry rejects duplicate names.
	Name() string

	// Phase groups the module in pipeline UIs. See Phase constants.
	Phase() Phase

	// Consumes lists event types the module subscribes to. Empty means the
	// module is a pure producer (e.g. a passive source). Used by tooling to
	// visualize the event graph; the bus itself is queried via Subscribe.
	Consumes() []eventbus.EventType

	// Produces lists event types the module publishes. Empty means the module
	// only side-effects (e.g. reporting). Used for tooling and dep docs.
	Produces() []eventbus.EventType

	// DefaultEnabled returns whether this module runs when config does not
	// explicitly enable/disable it. Passive sources typically default true;
	// aggressive/experimental modules typically default false.
	DefaultEnabled() bool

	// Run executes the module. Must be non-blocking on setup and must return
	// when its work is complete OR mctx.Ctx is canceled. Errors returned are
	// logged via ModuleError events by the scanner.
	Run(mctx Context) error
}