internal/engine¶
import "github.com/nuqs-org/nuqs/internal/engine"
Package engine runs a scan from start to end.
The flow is simple:
- ask the HostScanner (Nmap) which hosts and services are up
- for every service, pick the checks that apply to it
- run those checks in parallel, each with its own timeout
- collect findings and errors into a Report
One bad check can never break the scan. Errors, timeouts and even panics are caught and reported, and the other checks keep going.
Constants¶
Defaults used when the Engine fields are left at zero.
const (
DefaultWorkers = 10
DefaultCheckTimeout = 30 * time.Second
)
Defined in internal/engine/engine.go:29
Types¶
CheckError¶
CheckError records a check that couldn't finish. It is not a finding.
type CheckError struct {
CheckID string `json:"check_id"`
Host string `json:"host"`
Port int `json:"port"`
Error string `json:"error"`
}
Defined in internal/engine/engine.go:63
Engine¶
Engine holds the scan setup. The zero value is not usable, Scanner must be set.
type Engine struct {
Scanner HostScanner
Checks []check.Check
Workers int // how many checks run at once, 0 means DefaultWorkers
CheckTimeout time.Duration // max time for one check, 0 means DefaultCheckTimeout
OnEvent func(Event) // optional, called one event at a time
}
Defined in internal/engine/engine.go:81
Engine.Run¶
Run scans the targets. Targets must already be validated (see package target).
If ctx is cancelled the scan stops early and Run returns what it has so far together with ctx's error.
func (e *Engine) Run(ctx context.Context, targets []string) (*Report, error)
Defined in internal/engine/engine.go:98
Event¶
Event is sent to OnEvent so the CLI (and later the API) can show progress.
type Event struct {
Kind EventKind
Host string
Port int
CheckID string
Count int
Err error // set on CheckDone when the check failed
}
Defined in internal/engine/engine.go:53
EventKind¶
EventKind says what happened during a scan.
type EventKind string
Defined in internal/engine/engine.go:41
Event kinds, in the order they happen.
const (
DiscoveryStarted EventKind = "discovery_started"
DiscoveryDone EventKind = "discovery_done" // Count = hosts found
ChecksStarted EventKind = "checks_started" // Count = checks to run
CheckDone EventKind = "check_done" // one check finished on one service
ScanDone EventKind = "scan_done"
)
Defined in internal/engine/engine.go:44
HostScanner¶
HostScanner finds live hosts and their services. In real scans this is nmap.Scanner, in tests it's a fake.
type HostScanner interface {
Scan(ctx context.Context, targets []string) ([]model.Host, error)
}
Defined in internal/engine/engine.go:36
Report¶
Report is everything a scan produced.
type Report struct {
Targets []string `json:"targets"`
Started time.Time `json:"started"`
Finished time.Time `json:"finished"`
Hosts []model.Host `json:"hosts"`
Findings []model.Finding `json:"findings"`
Errors []CheckError `json:"errors"`
}
Defined in internal/engine/engine.go:71