Skip to content

internal/engine

import "github.com/nuqs-org/nuqs/internal/engine"

Package engine runs a scan from start to end.

The flow is simple:

  1. ask the HostScanner (Nmap) which hosts and services are up
  2. for every service, pick the checks that apply to it
  3. run those checks in parallel, each with its own timeout
  4. 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