Skip to content

Commit 55c554a

Browse files
committed
Let the scan engine say whether a scan failed (#308)
The CLI, the library, the MCP server and the TUI each worked out from the event stream whether a scan had failed, with their own rules for -no-abort warnings and cancellation. scan.Event gains Fatal (on EventError; false only for the -no-abort reliability warning) and Failed (on EventDone; true after a fatal preflight error or a reliability abort, false when cancelled), and pkg/subenum carries both. The four consumers now read them instead of re-deriving the answer. Output is unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Refs #308
1 parent 38868b2 commit 55c554a

12 files changed

Lines changed: 151 additions & 51 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
88
## [Unreleased]
99

1010
### Added
11+
- Library: a `KindError` event has `Fatal` set when it ends the scan (the reliability guard's warning under `NoAbort` is the one error without it), and `KindDone` has `Failed` set when the scan failed. The CLI, the TUI, `Scan` and `subenum mcp` now read these instead of each working it out from the errors seen and the no-abort setting; exit codes, `Scan` errors and verdicts are unchanged (#308).
1112
- The TUI configuration form includes **Sources** and **Permute** fields for `-sources` and `-permute`. The passive sources named in Sources (`ct`, `wayback`) are asked while the wordlist loads and their names are scanned with the wordlist's; a source that fails is a warning on the scan screen, and none is asked with Simulate on. With Permute on, a permutation pass follows the scan on the same screen, and the finished screen's verdict and counters cover both passes. With either field set, the results file names what proposed each result (`sources`, and `permutation` for a permutation hit) and its summary has the `sources` and `permutation` entries the CLI's report has (#274).
1213
- Each result says what proposed it: a `sources` list in JSON and JSONL and a last `sources` column in CSV (joined with `;`), holding `wordlist`, `ct`, `wayback` and `axfr`, every one that had the name, or `permute` alone for a `-permute` hit. A name found by `-recursive` below another is the wordlist's. The run-quality report counts the results each passive source had proposed (`found` in its `sources` entry) and a zone transfer's (`axfr_found`). Text output, the TUI's files and `subenum mcp` reports are unchanged (#273).
1314
- `subenum mcp`: `scan` and `lab_scan` accept an `offset` that skips that many candidates at the start of the word list (after dedupe), and a report whose `max_queries` left words untested carries `next_offset`, named in its `reason`. An agent can now work through the bundled 5,000-label list in several calls instead of testing the same first `-max-queries` names each time; every call stays within `-max-queries`, `-max-duration` and `-max-calls` (#313).

‎docs/library.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ for ev := range events {
5959
}
6060
```
6161

62-
Read the channel until it closes, or cancel `ctx`. Breaking out of the loop with a deferred `cancel()` is safe: once `ctx` is cancelled the scan stops without waiting for a reader, and its goroutines exit within about a second whether or not the channel is read. A consumer that keeps reading after cancelling still gets `KindDone` with the counts so far. While `ctx` is live, a consumer that stops reading pauses the scan once the buffer fills.
62+
Read the channel until it closes, or cancel `ctx`. Breaking out of the loop with a deferred `cancel()` is safe: once `ctx` is cancelled the scan stops without waiting for a reader, and its goroutines exit within about a second whether or not the channel is read. A consumer that keeps reading after cancelling still gets `KindDone` with the counts so far. A `KindError` event has `Fatal` set when it ends the scan (the `NoAbort` warning is the one that does not), and `KindDone` has `Failed` set when the scan failed, so a consumer does not have to work either out. While `ctx` is live, a consumer that stops reading pauses the scan once the buffer fills.
6363

6464
## Permutations: second-pass candidates
6565

‎internal/cli/cli.go‎

Lines changed: 5 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -726,7 +726,6 @@ func scanTarget(ctx context.Context, s *session, p scanPass, emit func(scan.Even
726726
go scan.Run(ctx, cfg, events)
727727

728728
progressStarted := false
729-
sawError := false
730729
finishProgress := func() {
731730
if progressStarted {
732731
out.ProgressDone()
@@ -747,34 +746,32 @@ func scanTarget(ctx context.Context, s *session, p scanPass, emit func(scan.Even
747746
out.ScanNotice(ev.Notice.String(), ev.Message)
748747
case scan.EventError:
749748
msg := out.ScanError(ev.Message)
750-
if !sawError {
749+
if res.err == "" {
751750
res.err = msg
752751
}
753-
sawError = true
754752
finishProgress()
755753
// Keep draining: EventDone always follows (#99), Stopped after an
756754
// early error such as wildcard detection, with Stats after a
757755
// reliability abort.
758756
case scan.EventDone:
759757
finishProgress()
758+
// The engine says whether the scan failed (#308): a fatal error
759+
// did, the reliability warning under -no-abort did not.
760+
res.failed = ev.Failed
760761
if ev.Stopped {
761762
// Nothing was scanned: the run failed (or was interrupted)
762763
// before the candidates, so it does not count as done.
763764
break
764765
}
765766
res.done = true
766767
res.final = ev
768+
res.resolverAbort = ev.Stats.Aborted
767769
logScanBreakdown(p.domain, ev, out)
768770
if f.verbose {
769771
logVerboseDone(ev, f, s.outWriter, out)
770772
}
771773
}
772774
}
773-
// An error fails the run unless the scan finished under -no-abort.
774-
// The reliability guard is the only error that still lets EventDone
775-
// arrive; without -no-abort it cancelled the scan.
776-
res.resolverAbort = res.done && sawError && !f.noAbort
777-
res.failed = sawError && (!res.done || !f.noAbort)
778775
return res
779776
}
780777

‎internal/cli/mcp.go‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -743,7 +743,9 @@ func runMCPScan(ctx context.Context, cfg subenum.Config, offset int) *mcpReport
743743
case subenum.KindNotice:
744744
report.Notices = append(report.Notices, ev.Message)
745745
case subenum.KindError:
746-
if report.Error == "" {
746+
// Only a fatal error is the report's error; mcpVerdict reads it
747+
// as the scan having failed.
748+
if ev.Fatal && report.Error == "" {
747749
report.Error = ev.Message
748750
}
749751
case subenum.KindDone:

‎internal/scan/runner.go‎

Lines changed: 33 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -513,7 +513,7 @@ const (
513513
EventNotice // informational notice; see Event.Notice
514514
// EventError reports a problem. Usually the scan then stops and its
515515
// EventDone has Stopped set; after the reliability guard (with NoAbort)
516-
// the scan goes on.
516+
// the scan goes on. Event.Fatal tells the two apart.
517517
EventError
518518
// EventDone is always the last event, sent exactly once (#99).
519519
EventDone
@@ -587,6 +587,14 @@ type Event struct {
587587
// preflight or wildcard check, wildcard zone without Force) or when ctx
588588
// was cancelled during those checks. Its Stats cover only the checks.
589589
Stopped bool
590+
// Fatal is set on an EventError that ends the scan. The one error
591+
// without it is the reliability guard's warning under NoAbort (#308).
592+
Fatal bool
593+
// Failed is set on EventDone when the scan failed: a fatal EventError
594+
// was sent, or the reliability guard aborted the scan. A cancelled scan
595+
// has not failed. Consumers read this instead of working it out from
596+
// the errors they saw and their own copy of NoAbort (#308).
597+
Failed bool
590598
}
591599

592600
// Run executes the subdomain scan, sending events to the provided channel.
@@ -625,17 +633,18 @@ func Run(ctx context.Context, cfg Config, events chan<- Event) {
625633
ctx = dns.WithQueryCounter(ctx, &queriesSent)
626634
// Every scan ends with exactly one EventDone (#99): one that stops before
627635
// the candidates sends it here, with Stopped set, before close(events).
628-
doneSent := false
636+
doneSent, failed := false, false
629637
defer func() {
630638
if !doneSent {
631-
events <- Event{Kind: EventDone, Stopped: true, Total: int64(len(cfg.Entries)), Stats: Stats{QueriesSent: queriesSent.Load()}}
639+
events <- Event{Kind: EventDone, Stopped: true, Failed: failed, Total: int64(len(cfg.Entries)), Stats: Stats{QueriesSent: queriesSent.Load()}}
632640
}
633641
}()
634642

635643
cfg.scope = newScope(cfg.Exclude)
636644
cfg.takeover = &dns.TakeoverCache{Providers: cfg.TakeoverProviders}
637-
wildcardRoot, fingerprint, ok := preflight(ctx, &cfg, maxDepth, events)
645+
wildcardRoot, fingerprint, ok, fatal := preflight(ctx, &cfg, maxDepth, events)
638646
if !ok {
647+
failed = fatal
639648
return
640649
}
641650

@@ -705,30 +714,33 @@ func Run(ctx context.Context, cfg Config, events chan<- Event) {
705714
Total: st.total.Load(),
706715
Found: st.found.Load(),
707716
Stats: snap,
717+
// The guard's abort is the one fatal error past the preflight.
718+
Failed: snap.Aborted,
708719
}
709720
}
710721

711722
// preflight runs the checks a scan passes before any candidate is tested:
712723
// the scope of the target (#87), the recursion ceiling, the resolver
713724
// preflight and wildcard detection. It reports whether the root is a
714725
// wildcard zone and the wildcard fingerprint to filter with. On false the
715-
// scan must stop: preflight has sent the EventError explaining why, or ctx
716-
// was cancelled, and Run's deferred EventDone (Stopped) ends the scan.
717-
func preflight(ctx context.Context, cfg *Config, maxDepth int, events chan<- Event) (wildcardRoot bool, fp *fingerprint, ok bool) {
726+
// scan must stop: preflight has sent the fatal EventError explaining why
727+
// (fatal is then set), or ctx was cancelled, and Run's deferred EventDone
728+
// (Stopped) ends the scan.
729+
func preflight(ctx context.Context, cfg *Config, maxDepth int, events chan<- Event) (wildcardRoot bool, fp *fingerprint, ok, fatal bool) {
718730
// Out-of-scope names are never queried (#87). A target that is itself
719731
// out of scope, or whose every candidate would be, is refused outright.
720732
if cfg.scope.excluded(cfg.Domain) || cfg.scope.subtreeExcluded(cfg.Domain) {
721-
events <- Event{Kind: EventError, Message: "refusing to scan " + cfg.Domain + ": it is out of scope ({exclude})"}
722-
return false, nil, false
733+
events <- Event{Kind: EventError, Fatal: true, Message: "refusing to scan " + cfg.Domain + ": it is out of scope ({exclude})"}
734+
return false, nil, false, true
723735
}
724736

725737
if cfg.Recursive {
726738
ceiling := RecursionCeiling(len(cfg.Entries), maxDepth)
727739
if ceiling > recursionRefuseCeiling && cfg.MaxQueries == 0 && !cfg.Force {
728-
events <- Event{Kind: EventError, Message: fmt.Sprintf(
740+
events <- Event{Kind: EventError, Fatal: true, Message: fmt.Sprintf(
729741
"refusing to start: {recursive} {depth} %d with %d entries can generate up to %.1e queries; set {max_queries} or {force}",
730742
maxDepth, len(cfg.Entries), ceiling)}
731-
return false, nil, false
743+
return false, nil, false, true
732744
}
733745
consider := "Consider {max_queries}."
734746
if maxDepth > 1 {
@@ -744,12 +756,12 @@ func preflight(ctx context.Context, cfg *Config, maxDepth int, events chan<- Eve
744756
// scan that -attempts would otherwise complete (#57).
745757
_, outcome := cfg.resolve(ctx, cfg.Domain, nil)
746758
if ctx.Err() != nil {
747-
return false, nil, false // interrupted during preflight: not a resolver failure
759+
return false, nil, false, false // interrupted during preflight: not a resolver failure
748760
}
749761
if outcome != dns.OutcomeFound && outcome != dns.OutcomeNXDomain {
750762
msg := fmt.Sprintf("resolver %s failed preflight for %s: %s after %d attempt(s)", cfg.DNSServer, cfg.Domain, outcome, cfg.Attempts)
751-
events <- Event{Kind: EventError, Message: msg}
752-
return false, nil, false
763+
events <- Event{Kind: EventError, Fatal: true, Message: msg}
764+
return false, nil, false, true
753765
}
754766
// An apex the trusted resolver answers is the first canary for
755767
// checking that pool members do not hide existing names (#105).
@@ -764,14 +776,14 @@ func preflight(ctx context.Context, cfg *Config, maxDepth int, events chan<- Eve
764776
if !cfg.Simulate {
765777
isWildcard, probed, err := cfg.lookup(nil).FingerprintWildcard(ctx, cfg.Domain)
766778
if ctx.Err() != nil {
767-
return false, nil, false // interrupted during wildcard probes
779+
return false, nil, false, false // interrupted during wildcard probes
768780
}
769781
// An inconclusive check is never "no wildcard": under a real wildcard
770782
// every candidate would resolve and flood the results (#47). -force
771783
// scans anyway, but without a fingerprint to filter with.
772784
if err != nil && !cfg.Force {
773-
events <- Event{Kind: EventError, Message: "wildcard detection failed: " + err.Error() + "; results could not be filtered. Use {force} to scan anyway."}
774-
return false, nil, false
785+
events <- Event{Kind: EventError, Fatal: true, Message: "wildcard detection failed: " + err.Error() + "; results could not be filtered. Use {force} to scan anyway."}
786+
return false, nil, false, true
775787
}
776788
if err != nil {
777789
events <- Event{Kind: EventNotice, Notice: NoticeWildcard, Message: "WARNING: wildcard detection failed (" + err.Error() + "); scanning without wildcard filtering because of {force}"}
@@ -782,12 +794,12 @@ func preflight(ctx context.Context, cfg *Config, maxDepth int, events chan<- Eve
782794
msg := "WARNING: Wildcard DNS detected - all subdomains resolve for " + cfg.Domain
783795
events <- Event{Kind: EventNotice, Notice: NoticeWildcard, Message: msg}
784796
if !cfg.Force {
785-
events <- Event{Kind: EventError, Message: "Results would be meaningless. Use {force} to scan anyway."}
786-
return false, nil, false
797+
events <- Event{Kind: EventError, Fatal: true, Message: "Results would be meaningless. Use {force} to scan anyway."}
798+
return false, nil, false, true
787799
}
788800
}
789801
}
790-
return wildcardRoot, fp, true
802+
return wildcardRoot, fp, true, false
791803
}
792804

793805
// startTicker sends an EventProgress every second until ctx is done or the
@@ -1167,7 +1179,7 @@ func (s *scanState) checkReliability(processed int64) {
11671179
}
11681180
msg := fmt.Sprintf("%s: %.0f%% of %d queries failed (timeout/refused/other); likely resolver rate-limiting at {concurrency} %d and {rate} %d",
11691181
verb, rate, processed, cfg.Concurrency, cfg.Rate)
1170-
s.events <- Event{Kind: EventError, Message: msg}
1182+
s.events <- Event{Kind: EventError, Fatal: !cfg.NoAbort, Message: msg}
11711183
if !cfg.NoAbort {
11721184
st.aborted.Store(true)
11731185
s.cancel()

‎internal/scan/runner_test.go‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1399,3 +1399,64 @@ func TestRunAlwaysEndsWithOneDone(t *testing.T) {
13991399
})
14001400
}
14011401
}
1402+
1403+
// TestRunStatesFatalAndFailed covers #308: the engine says on each EventError
1404+
// whether it was fatal and on EventDone whether the scan failed, so the front
1405+
// ends do not work it out from the errors they saw and their own NoAbort.
1406+
func TestRunStatesFatalAndFailed(t *testing.T) {
1407+
failing := func(noAbort bool) Config {
1408+
return Config{
1409+
Domain: "example.com", Entries: makeEntries(reliabilityMinJobs + 50), Concurrency: 4,
1410+
Timeout: time.Second, Simulate: true, Attempts: 1, NoAbort: noAbort,
1411+
resolveHook: hookOutcome(dns.OutcomeTimeout),
1412+
}
1413+
}
1414+
clean := Config{Domain: "example.com", Entries: makeEntries(5), Concurrency: 2, Timeout: time.Second, Simulate: true, HitRate: 50}
1415+
outOfScope := clean
1416+
outOfScope.Exclude = []string{"example.com"}
1417+
1418+
cases := map[string]struct {
1419+
cfg Config
1420+
cancelled bool // ctx is cancelled before the scan starts
1421+
wantErrs bool
1422+
wantFatal bool // of every EventError
1423+
stopped bool
1424+
aborted bool
1425+
failed bool
1426+
}{
1427+
"completed clean": {cfg: clean},
1428+
"stopped before candidates by error": {cfg: outOfScope, wantErrs: true, wantFatal: true, stopped: true, failed: true},
1429+
"reliability abort": {cfg: failing(false), wantErrs: true, wantFatal: true, aborted: true, failed: true},
1430+
"reliability warning under NoAbort": {cfg: failing(true), wantErrs: true},
1431+
"cancelled": {cfg: clean, cancelled: true},
1432+
}
1433+
for name, c := range cases {
1434+
t.Run(name, func(t *testing.T) {
1435+
ctx, cancel := context.WithCancel(context.Background())
1436+
defer cancel()
1437+
if c.cancelled {
1438+
cancel()
1439+
}
1440+
events := make(chan Event, 64)
1441+
go Run(ctx, c.cfg, events)
1442+
done, errs, _ := collect(events)
1443+
if done == nil {
1444+
t.Fatal("no EventDone")
1445+
}
1446+
if (len(errs) > 0) != c.wantErrs {
1447+
t.Fatalf("EventErrors %+v, want any: %v", errs, c.wantErrs)
1448+
}
1449+
for _, e := range errs {
1450+
if e.Fatal != c.wantFatal {
1451+
t.Errorf("EventError %q: Fatal = %v, want %v", e.Message, e.Fatal, c.wantFatal)
1452+
}
1453+
}
1454+
if done.Stopped != c.stopped || done.Stats.Aborted != c.aborted {
1455+
t.Errorf("EventDone: Stopped %v, Aborted %v; want %v, %v", done.Stopped, done.Stats.Aborted, c.stopped, c.aborted)
1456+
}
1457+
if done.Failed != c.failed {
1458+
t.Errorf("EventDone: Failed = %v, want %v", done.Failed, c.failed)
1459+
}
1460+
})
1461+
}
1462+
}

‎internal/tui/model.go‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -269,7 +269,6 @@ func (m Model) beginScan(loaded wordlistLoadedMsg) (tea.Model, tea.Cmd) {
269269

270270
m.state = stateScan
271271
m.scanView = newScanViewModel(m.width, m.height, vals.Simulate)
272-
m.scanView.noAbort = vals.NoAbort
273272
m.scanView.permute = vals.permute
274273
// Same facts the CLI prints: the seed that reproduces a simulation, and
275274
// how many wordlist entries were dropped (#80).

‎internal/tui/model_test.go‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -338,17 +338,17 @@ func TestScanFailureStatusAndExitCode(t *testing.T) {
338338
}
339339

340340
// Preflight failure: error, then the channel closes without EventDone.
341-
sv := update(newScanViewModel(120, 40, false), eventMsg{scan.Event{Kind: scan.EventError, Message: "resolver failed preflight"}}, eventMsg{scan.Event{Kind: scan.EventDone, Stopped: true}})
341+
sv := update(newScanViewModel(120, 40, false), eventMsg{scan.Event{Kind: scan.EventError, Fatal: true, Message: "resolver failed preflight"}}, eventMsg{scan.Event{Kind: scan.EventDone, Stopped: true, Failed: true}})
342342
if !sv.failed() || !strings.Contains(sv.View(), "Failed: resolver failed preflight") || strings.Contains(sv.View(), "Aborted") {
343343
t.Errorf("preflight failure not shown as Failed:\n%s", sv.View())
344344
}
345345
if code := exitCode(Model{scanView: sv}); code != 1 {
346346
t.Errorf("exit code = %d, want 1", code)
347347
}
348348

349-
// Reliability warning under -no-abort with a finished scan is not a failure.
349+
// Reliability warning under -no-abort with a finished scan is not a
350+
// failure: the engine sends it without Fatal, and EventDone without Failed.
350351
nv := newScanViewModel(120, 40, false)
351-
nv.noAbort = true
352352
nv = update(nv, eventMsg{scan.Event{Kind: scan.EventError, Message: "warning: 30% failed"}}, eventMsg{scan.Event{Kind: scan.EventDone, Processed: 5, Total: 5}})
353353
if nv.failed() || exitCode(Model{scanView: nv}) != 0 {
354354
t.Error("-no-abort warning counted as a failure")

‎internal/tui/passes_test.go‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -301,7 +301,9 @@ func TestPermutationPassStates(t *testing.T) {
301301
if m := update(start(func(sv *scanViewModel) { sv.aborted = true }), mainDone); !m.scanView.done || m.scanView.main != nil {
302302
t.Error("an aborted main pass was followed by a permutation pass")
303303
}
304-
if m := update(start(nil), eventMsg{scan.Event{Kind: scan.EventError, Message: "too many failures"}}, mainDone); !m.scanView.done || !m.scanView.failed() {
304+
abortedDone := mainDone
305+
abortedDone.Failed, abortedDone.Stats.Aborted = true, true
306+
if m := update(start(nil), eventMsg{scan.Event{Kind: scan.EventError, Fatal: true, Message: "too many failures"}}, abortedDone); !m.scanView.done || !m.scanView.failed() {
305307
t.Error("a main pass the reliability guard aborted was followed by a permutation pass")
306308
}
307309

0 commit comments

Comments
 (0)