drive

type Masscan struct {
	// Args are masscan arguments placed before the target specs (e.g. "-p1-65535", "--rate=10000").
	Args []string
	// BinaryPath overrides the masscan binary location; empty uses $PATH.
	BinaryPath string
}

type Nmap struct {
	// Args are nmap arguments placed before the target specs (e.g. "-sV", "-p1-1000").
	Args []string
	// BinaryPath overrides the nmap binary location; empty uses $PATH.
	BinaryPath string
}

type Nuclei struct {
	// Args are nuclei arguments placed before the target specs (e.g. "-severity", "high").
	Args []string
	// BinaryPath overrides the nuclei binary location; empty uses $PATH.
	BinaryPath string
}

type Scanner interface {
	// Scan runs the tool against targets (plus any extra tool arguments) and returns four
	// channels plus a launch error:
	//   - results:  Results to fold (Run.AddResult), closed when the scan ends;
	//   - progress: TaskProgress to display, closed when the scan ends;
	//   - warnings: the tool's live, non-fatal notices (nmap stderr lines such as "giving up on
	//               port ... retransmission cap hit") as they are emitted, closed when the scan ends.
	//               Best-effort and raw: classification/typing is the caller's concern (a long scan
	//               that is plainly busy should not look silent). A driver with no live notice stream
	//               returns an already-closed channel.
	//   - errc:     the scan's TERMINAL outcome — at most one value then closed. nil means the
	//               tool completed cleanly; a non-nil error is a failure the tool signalled AFTER
	//               launch (e.g. nmap "requires root privileges. QUITTING!", a resolve failure, a
	//               non-zero exit). Drain it AFTER results/progress close.
	//   - err:      a synchronous LAUNCH error (bad args, binary missing) — the scan never started,
	//               and results/progress/warnings/errc are all nil.
	//
	// Splitting launch (err) from terminal (errc) is the whole point: a tool that starts and then
	// dies mid-flight had, until now, nowhere to report that — so the run was misread as a success.
	Scan(ctx context.Context, targets []*scanpb.Target, args ...string) (
		results <-chan *scanpb.Result,
		progress <-chan *scanpb.TaskProgress,
		warnings <-chan string,
		errc <-chan error,
		err error,
	)
}