Skip to content

Commit 0c838e4

Browse files
committed
Keep the -diff baseline when a stopped run shares it with -o (#297)
With -diff X -o X, a run that was interrupted or stopped by a budget committed its partial results over X, so the resumed run compared against its own partial output and reported known names as added. When such a run saves a resume state, the -o file is now left unchanged and an info line says so; the partial results live in the state file. If no state could be saved the partial file is committed as before. The -diff file is also recorded in the state's input digests when it is the -o file, so -resume refuses if it changed in between. Co-Authored-By: Claude Mythos 5.2 <noreply@anthropic.com> Fixes #297
1 parent 3af2a17 commit 0c838e4

5 files changed

Lines changed: 113 additions & 16 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
5252
- Tests no longer flake under load: lab end-to-end runs use a 5 s timeout with 3 attempts and fail with a clear message if the lab 2 wildcard probe times out, the resolver-pool spread test counts lookups per member instead of timing the scan (the timing view is now `BenchmarkPoolSpreadsLoad`), and CI runs tests in shuffled order (#167).
5353

5454
### Fixed
55+
- A run with `-diff` and `-o` on the same file that is interrupted (or stopped by `-max-duration` or the reliability guard) and saves a resume state now leaves that file as it was, instead of replacing it with its partial results. The resumed run compared against the partial file, so it reported names that were already known as added, exited 4 with nothing changed and could not report removals. The partial results are in the resume state, and the resumed run writes the full file; `-resume` now also refuses to continue if that file changed in between (#297).
5556
- A resumed `-recursive` scan checks each name found before the interrupt for wildcard DNS before expanding it, as a live scan does. A wildcard subzone, or one whose check was inconclusive, is skipped with the same notice instead of reporting every wordlist entry under it as a result, so an interrupted-then-resumed scan reports the same names as an uninterrupted one (#296).
5657
- The TUI no longer requires a wordlist file: an empty **Wordlist** field scans with the bundled top-5000 list, as a missing `-w` does on the command line, and the scan view says which list ran. The field no longer pre-fills `examples/sample_wordlist.txt`, which only exists inside a checkout, so `subenum -tui` from an installed binary works on the first run (#288).
5758
- On Windows, `-o NUL`, `-stats NUL` and `-sarif NUL` no longer fail with "Incorrect function" and exit 1: device and pipe targets are opened without truncation (#208, thanks @bfs2021).

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -378,7 +378,7 @@ Press `Ctrl+C` at any time to abort. In-flight queries drain, partial results ar
378378
subenum -resume subenum-resume.json
379379
```
380380

381-
The resumed run refuses to start if an input file, the wordlist (including the bundled one, which changes with the binary) or an effective setting (for example a `SUBENUM_*` variable or the config file) changed. It re-emits the earlier results (so `-o` and JSON output end up complete), skips targets that had finished, and continues the interrupted one from the first wordlist entry not yet fully looked up; a `-permute` pass resumes from its own position. At most about one worker pool's worth (`-t`) of lookups is repeated, and `-max-queries` covers the whole scan, so a resumed run only gets what is left of it. In recursive mode, names found before the interrupt have their children re-scanned. A resumed run that finishes deletes its state file. A run that `-max-duration` stopped with names untested, or that the reliability guard aborted, saves the same state (its exit code does not change), so `-resume` continues it too: a scheduled job with a time budget can work through a large wordlist over several runs. Runs that read the wordlist or domain list from stdin cannot be resumed.
381+
The resumed run refuses to start if an input file, the wordlist (including the bundled one, which changes with the binary) or an effective setting (for example a `SUBENUM_*` variable or the config file) changed. It re-emits the earlier results (so `-o` and JSON output end up complete), skips targets that had finished, and continues the interrupted one from the first wordlist entry not yet fully looked up; a `-permute` pass resumes from its own position. At most about one worker pool's worth (`-t`) of lookups is repeated, and `-max-queries` covers the whole scan, so a resumed run only gets what is left of it. In recursive mode, names found before the interrupt have their children re-scanned. A resumed run that finishes deletes its state file. A run that `-max-duration` stopped with names untested, or that the reliability guard aborted, saves the same state (its exit code does not change), so `-resume` continues it too: a scheduled job with a time budget can work through a large wordlist over several runs. When `-diff` and `-o` name the same file, a run that saves a resume state leaves that file unchanged, so the resumed run compares against the same baseline and then writes the full results. Runs that read the wordlist or domain list from stdin cannot be resumed.
382382

383383
**Exit codes**
384384

‎internal/cli/resume.go‎

Lines changed: 11 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -228,16 +228,12 @@ func fileDigest(path string) (string, error) {
228228
return hex.EncodeToString(sum[:]), nil
229229
}
230230

231-
// inputDigests fingerprints the inputs a resume must find unchanged. The
232-
// -diff file is left out when it is also the -o file, which an interrupted
233-
// run rewrites with its partial results.
231+
// inputDigests fingerprints the inputs a resume must find unchanged. That
232+
// includes a -diff file that is also the -o file: a run that saves a resume
233+
// state leaves it as it was (#297).
234234
func inputDigests(f cliFlags) (map[string]string, error) {
235235
out := map[string]string{}
236-
diff := f.diff
237-
if diff == f.outputFile {
238-
diff = ""
239-
}
240-
paths := append(slices.Clone(f.wordlists.paths), f.domainList, f.excludeFile, f.resolvers, f.simZone, f.seedsFile, diff)
236+
paths := append(slices.Clone(f.wordlists.paths), f.domainList, f.excludeFile, f.resolvers, f.simZone, f.seedsFile, f.diff)
241237
for _, p := range paths {
242238
d, err := fileDigest(p)
243239
if err != nil {
@@ -353,17 +349,18 @@ func savedSources(sources []targetSource) map[string][]string {
353349
// how to continue. Runs that read stdin cannot be replayed. prev is the
354350
// state this run resumed from, if any: a target interrupted again before its
355351
// scan reported progress keeps the earlier resume point (#109), and one this
356-
// run never reached keeps its saved state unchanged.
357-
func saveResumeState(s *session) {
352+
// run never reached keeps its saved state unchanged. It reports whether the
353+
// state was saved.
354+
func saveResumeState(s *session) bool {
358355
f, out, prev := s.f, s.out, s.resume
359356
if f.wordlists.readsStdin() || f.domainList == "-" {
360357
out.Info("Not saving resume state: the wordlist or domain list came from stdin")
361-
return
358+
return false
362359
}
363360
inputs, err := inputDigests(f)
364361
if err != nil {
365362
out.Error("saving resume state: %v", err)
366-
return
363+
return false
367364
}
368365
st := resumeState{Version: resumeStateVersion, Args: withSeed(s.args, f), Inputs: inputs, Settings: s.settings}
369366
for i, domain := range s.targets {
@@ -399,9 +396,10 @@ func saveResumeState(s *session) {
399396
}
400397
if err := writeResumeState(f.stateFile, st); err != nil {
401398
out.Error("saving resume state: %v", err)
402-
return
399+
return false
403400
}
404401
out.Info("Saved resume state to %s; continue with: subenum -resume %s", f.stateFile, f.stateFile)
402+
return true
405403
}
406404

407405
// writeResumeState saves where an interrupted run stopped.

‎internal/cli/resume_test.go‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ import (
99
"os"
1010
"path/filepath"
1111
"reflect"
12+
"slices"
1213
"strings"
1314
"sync/atomic"
1415
"testing"
@@ -303,6 +304,96 @@ func TestE2EMaxDurationSavesResumeState(t *testing.T) {
303304
}
304305
}
305306

307+
// TestE2EResumeDiffOntoOutputFile covers #297: with -diff and -o on one
308+
// file, a run that stops and saves a resume state leaves the file alone, so
309+
// the resumed run reports the same diff and exit code as an uninterrupted
310+
// one, and then writes the full results.
311+
func TestE2EResumeDiffOntoOutputFile(t *testing.T) {
312+
t.Parallel()
313+
dir := t.TempDir()
314+
const n = 120
315+
var words strings.Builder
316+
for i := 0; i < n; i++ {
317+
fmt.Fprintf(&words, "host%d\n", i)
318+
}
319+
base := []string{"-simulate", "-seed", "3", "-hit-rate", "50", "-progress=false", "-t", "2", "-format", "jsonl",
320+
"-w", writeFile(t, "wl.txt", words.String())}
321+
run := func(extra ...string) (int, string) {
322+
return runCLIMerged(t, append(append(slices.Clone(base), extra...), "example.com")...)
323+
}
324+
names := func(path string) []string {
325+
t.Helper()
326+
data, err := os.ReadFile(path)
327+
if err != nil {
328+
t.Fatal(err)
329+
}
330+
results, _ := jsonlRecords(t, string(data))
331+
var out []string
332+
for _, r := range results {
333+
out = append(out, r.Subdomain)
334+
}
335+
slices.Sort(out)
336+
return out
337+
}
338+
diffOf := func(path string) output.DiffSummary {
339+
t.Helper()
340+
var summary output.Summary
341+
if data, err := os.ReadFile(path); err != nil || json.Unmarshal(data, &summary) != nil || summary.Diff == nil {
342+
t.Fatalf("reading the diff summary in %s: %v", path, err)
343+
}
344+
d := *summary.Diff
345+
d.Previous = ""
346+
return d
347+
}
348+
349+
full := filepath.Join(dir, "full.jsonl")
350+
if code, out := run("-o", full); code != 0 {
351+
t.Fatalf("baseline run: exit %d\n%s", code, out)
352+
}
353+
all := names(full)
354+
if len(all) < 10 {
355+
t.Fatalf("the simulation found %d names, want at least 10", len(all))
356+
}
357+
// The baseline lacks one name the scan finds and has one it cannot find.
358+
baseline := strings.Join(all[1:], "\n") + "\ngone.example.com\n"
359+
360+
// The uninterrupted run.
361+
stats := filepath.Join(dir, "stats.json")
362+
wantCode, out := run("-diff", writeFile(t, "prev.txt", baseline), "-o", filepath.Join(dir, "cur.jsonl"), "-stats", stats)
363+
want := diffOf(stats)
364+
if wantCode != 4 || want.Added != 1 {
365+
t.Fatalf("uninterrupted run: exit %d, diff %+v; want exit 4 with 1 added\n%s", wantCode, want, out)
366+
}
367+
368+
// -rate 50 with 120 words needs about 2.4 s, so a 1 s budget stops the run.
369+
results, state := writeFile(t, "results.txt", baseline), filepath.Join(dir, "state.json")
370+
code, out := run("-diff", results, "-o", results, "-stats", stats, "-rate", "50", "-max-duration", "1s", "-state", state)
371+
if _, err := os.Stat(state); err != nil {
372+
t.Fatalf("the stopped run (exit %d) saved no resume state: %v\n%s", code, err, out)
373+
}
374+
if data, err := os.ReadFile(results); err != nil || string(data) != baseline {
375+
t.Fatalf("the stopped run changed its -diff baseline (err %v):\n%s", err, data)
376+
}
377+
for i := 0; ; i++ {
378+
if i == 20 {
379+
t.Fatal("the scan did not finish in 20 resumed runs")
380+
}
381+
code, out = runCLIMerged(t, "-resume", state)
382+
if _, err := os.Stat(state); err != nil {
383+
break // the run that finished removed its state
384+
}
385+
if data, err := os.ReadFile(results); err != nil || string(data) != baseline {
386+
t.Fatalf("resumed run %d changed its -diff baseline (err %v):\n%s", i, err, data)
387+
}
388+
}
389+
if got := diffOf(stats); code != wantCode || got != want {
390+
t.Errorf("resumed run: exit %d, diff %+v; want exit %d, diff %+v as uninterrupted\n%s", code, got, wantCode, want, out)
391+
}
392+
if got := names(results); !slices.Equal(got, all) {
393+
t.Errorf("-o holds %d names after the resumed run, want all %d", len(got), len(all))
394+
}
395+
}
396+
306397
// TestE2EAbortSavesResumeState covers #294: a scan the reliability guard
307398
// aborts fails as before, but saves a resume state, and the resumed run
308399
// tests the rest once the resolver answers again.

‎internal/cli/session.go‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,7 @@ type session struct {
6262
anyDone bool
6363
anyFailed bool
6464
fileErr bool // a file write error was reported
65+
keepBaseline bool // -o is also the -diff file and a resume needs it unchanged
6566
started time.Time
6667
signalCode atomic.Int32 // 128+signum once a signal arrives
6768
}
@@ -120,7 +121,7 @@ func runWith(a runArgs) (code int) {
120121
// successful exit into a failure (#30). bufio errors are sticky, so a
121122
// failure already reported by Finish is not printed twice.
122123
defer func() {
123-
if err := s.outFile.Close(s.anyDone); err != nil {
124+
if err := s.outFile.Close(s.anyDone && !s.keepBaseline); err != nil {
124125
if !s.fileErr {
125126
s.out.Error("writing output file: %v", err)
126127
}
@@ -790,7 +791,13 @@ func (s *session) finish(ctx context.Context) int {
790791
logPoolHealth(s.in.pool, out)
791792

792793
if s.signalCode.Load() != 0 || s.stoppedEarly() {
793-
saveResumeState(s)
794+
// With -diff and -o on one file, the partial results must not replace
795+
// the baseline the resumed run compares against; the saved state holds
796+
// them, and the resumed run writes them to the -o file (#297).
797+
if saveResumeState(s) && f.diff != "" && f.diff == f.outputFile {
798+
s.keepBaseline = true
799+
out.Info("Leaving %s unchanged: it is the -diff baseline for the resumed run, which writes the full results", f.outputFile)
800+
}
794801
} else if s.resume != nil && !s.anyFailed {
795802
// The resumed run finished: its state file is spent (#109).
796803
if err := os.Remove(s.resume.path); err == nil {

0 commit comments

Comments
 (0)