Skip to content

Commit a8c869c

Browse files
committed
Small refactors: state keys, live mode, status type, atomic writes (#331)
Four of the five items in #331, with no change in behaviour: - scan.Stats has explicit JSON tags spelling today's names, so renaming a field cannot silently change the -resume state; a test pins every key path of the state file. - Config.live() replaces the seven "neither simulated nor stubbed" checks; the two that test only Simulate say why. - report.Status names the target statuses, with Label and Value for the two renderings of "not run", replacing string literals in six places. - output.WriteFile does the temp-file-and-rename write once, for the names, summary, SARIF and resume-state files. The Options/Config duplication is left for its own change. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Refs #331
1 parent cc44385 commit a8c869c

18 files changed

Lines changed: 296 additions & 113 deletions

‎docs/ARCHITECTURE.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -90,12 +90,12 @@ internal/dns/takeover.go - TakeoverProvider, TakeoverHint, HintsTakeover (
9090
internal/dns/scope.go - AddressScope, InternalScope: non-public address scopes (private, loopback, cgnat, ...)
9191
internal/dns/simulate.go - Simulation.Resolve (seeded synthetic DNS)
9292
internal/output/writer.go - Thread-safe Writer (results to stdout, diagnostics to stderr)
93-
internal/output/file.go - File: atomically replaced -o results file
93+
internal/output/file.go - File: atomically replaced -o results file; WriteFile for the side files
9494
internal/output/summary.go - Summary / TargetSummary, WriteSummaryFile
9595
internal/output/sarif.go - WriteSARIF: takeover candidates as SARIF 2.1.0
9696
internal/output/eta.go - ETA: progress estimate over a sliding window, FormatETA
9797
internal/output/log.go - -log-format: text or JSON diagnostics on stderr (ParseLogFormat, SetLogFormat)
98-
internal/report/report.go - New, Target, Finish: the run-quality report
98+
internal/report/report.go - New, Target, Finish: the run-quality report; Status, a target's status
9999
internal/permute/permute.go - Generate: permutations of found names
100100
internal/diff/diff.go - Name, RecordsChanged: the comparison behind -diff-records and subenum.Diff
101101
internal/ct/ct.go - Client.Names: crt.sh lookup

‎docs/DEVELOPER_GUIDE.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -257,7 +257,7 @@ func TestGuideResolveOutcomes(t *testing.T) {
257257
}
258258
```
259259

260-
Scan-engine tests in `internal/scan` can avoid DNS entirely by setting the unexported `resolveHook` field of `scan.Config`, or by running with `Simulate` set; see `runner_test.go`.
260+
Scan-engine tests in `internal/scan` can avoid DNS entirely by setting the unexported `resolveHook` field of `scan.Config`, or by running with `Simulate` set; see `runner_test.go`. The hook replaces candidate lookups only: wildcard probes still go to `Resolver`, so a hooked test also sets `Simulate` or points the resolver at a local server (`Config.live` reports whether a scan sends real lookups).
261261

262262
## Debugging Tips
263263

‎internal/cli/mcp_test.go‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -526,9 +526,9 @@ func TestMCPVerdictMatchesReport(t *testing.T) {
526526
c := tc.c
527527
pub := subenum.Stats{Found: c.found, NXDomain: c.nx, Timeout: c.timeout, Skipped: c.skipped, Expired: c.expired, Aborted: c.aborted, Wildcard: c.wildcard}
528528
eng := scan.Stats{Found: c.found, NXDomain: c.nx, Timeout: c.timeout, Skipped: c.skipped, Expired: c.expired, Aborted: c.aborted, Wildcard: c.wildcard}
529-
status := "ok"
529+
status := report.StatusOK
530530
if tc.interrupted {
531-
status = "interrupted"
531+
status = report.StatusInterrupted
532532
}
533533
rep := report.Target("x.example", status, "", true, scan.Event{Kind: scan.EventDone, Stats: eng}, scan.FieldName)
534534
want := tc.want

‎internal/cli/resume.go‎

Lines changed: 4 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ import (
1313
"strings"
1414

1515
"github.com/TMHSDigital/subenum/internal/output"
16+
"github.com/TMHSDigital/subenum/internal/report"
1617
"github.com/TMHSDigital/subenum/internal/scan"
1718
)
1819

@@ -436,7 +437,7 @@ func saveResumeState(s *session) bool {
436437
saved := prev.target(domain)
437438
// A target finished before the interrupt was not scanned again, so
438439
// its saved state, sources and zone transfer included, stands (#315).
439-
if saved != nil && (s.status[i] == "" || s.status[i] == "skipped" || saved.Done) {
440+
if saved != nil && (s.status[i] == report.StatusNotRun || s.status[i] == report.StatusSkipped || saved.Done) {
440441
st.Targets = append(st.Targets, *saved)
441442
continue
442443
}
@@ -469,7 +470,7 @@ func saveResumeState(s *session) bool {
469470
}
470471
// A target is finished only if its scan (and any -permute pass)
471472
// completed before the interrupt, with nothing left by -max-duration.
472-
t.Done = s.status[i] == "ok" && res.done && !res.unfinished() &&
473+
t.Done = s.status[i] == report.StatusOK && res.done && !res.unfinished() &&
473474
(res.permutation == nil || res.permutation.candidates == 0 || (res.permutation.pass.done && !res.permutation.pass.unfinished()))
474475
st.Targets = append(st.Targets, t)
475476
}
@@ -487,13 +488,5 @@ func writeResumeState(path string, st resumeState) error {
487488
if err != nil {
488489
return err
489490
}
490-
f, err := output.CreateFile(path)
491-
if err != nil {
492-
return err
493-
}
494-
_, werr := f.Write(append(data, '\n'))
495-
if cerr := f.Close(werr == nil); werr == nil {
496-
werr = cerr
497-
}
498-
return werr
491+
return output.WriteFile(path, append(data, '\n'))
499492
}

‎internal/cli/resume_test.go‎

Lines changed: 114 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ import (
2121
"github.com/TMHSDigital/subenum/internal/dnsserver"
2222
"github.com/TMHSDigital/subenum/internal/dnstest"
2323
"github.com/TMHSDigital/subenum/internal/output"
24+
"github.com/TMHSDigital/subenum/internal/report"
2425
"github.com/TMHSDigital/subenum/internal/scan"
2526
"github.com/TMHSDigital/subenum/internal/wordlist"
2627
)
@@ -655,7 +656,7 @@ func TestSaveResumeStateKeepsEarlierPosition(t *testing.T) {
655656
saveResumeState(&session{
656657
f: f, out: out, resume: prev,
657658
targets: []string{"a.example", "b.example", "c.example"},
658-
status: []string{"interrupted", "", "ok"},
659+
status: []report.Status{report.StatusInterrupted, report.StatusNotRun, report.StatusOK},
659660
entryDigests: []string{"d1", "", "d3"},
660661
results: []targetResult{{}, {}, {done: true}},
661662
runs: []resultLog{{names: []string{"x.a.example"}}, {}, {}},
@@ -689,7 +690,7 @@ func TestSaveResumeStateKeepsFailedSources(t *testing.T) {
689690
saveResumeState(&session{
690691
f: f, out: output.New(nil, false, output.FormatText),
691692
targets: []string{"a.example"},
692-
status: []string{"interrupted"},
693+
status: []report.Status{report.StatusInterrupted},
693694
entryDigests: []string{"d1"},
694695
results: []targetResult{{done: true, sources: []targetSource{
695696
{source: "ct", err: "crt.sh: 502 Bad Gateway"},
@@ -741,7 +742,7 @@ func TestSaveResumeStateRetriesLookupsCutShort(t *testing.T) {
741742
saveResumeState(&session{
742743
f: f, out: output.New(nil, false, output.FormatText), resume: tc.prev,
743744
targets: []string{"a.example"},
744-
status: []string{"interrupted"},
745+
status: []report.Status{report.StatusInterrupted},
745746
entryDigests: []string{"d1"},
746747
results: []targetResult{tc.res},
747748
runs: []resultLog{{}},
@@ -838,7 +839,7 @@ func TestSaveResumeStateRecordsFinishedPermutePass(t *testing.T) {
838839
saveResumeState(&session{
839840
f: f, out: output.New(nil, false, output.FormatText),
840841
targets: []string{"a.example"},
841-
status: []string{"interrupted"},
842+
status: []report.Status{report.StatusInterrupted},
842843
entryDigests: []string{"d1"},
843844
results: []targetResult{{
844845
done: true,
@@ -918,6 +919,115 @@ func TestPermutationCandidatesRespectNameLength(t *testing.T) {
918919
}
919920
}
920921

922+
// TestResumeStateKeys pins the state file's JSON keys (#331): renaming a
923+
// field of resumeState, or of a type it stores such as scan.Stats, changes
924+
// the format a newer binary reads back. A change here needs a
925+
// resumeStateVersion bump, or a tag that keeps the old key.
926+
func TestResumeStateKeys(t *testing.T) {
927+
var stats scan.Stats
928+
sv := reflect.ValueOf(&stats).Elem()
929+
for i := range sv.NumField() {
930+
switch v := sv.Field(i); v.Kind() {
931+
case reflect.Int64:
932+
v.SetInt(1)
933+
case reflect.Bool:
934+
v.SetBool(true)
935+
case reflect.Slice:
936+
if v.Type().Elem().Kind() == reflect.String {
937+
v.Set(reflect.ValueOf([]string{"a.example.com"}))
938+
} else {
939+
v.Set(reflect.ValueOf([]dns.Record{{Type: "A", Value: "192.0.2.1"}}))
940+
}
941+
default:
942+
t.Fatalf("scan.Stats.%s: unhandled kind %s", sv.Type().Field(i).Name, v.Kind())
943+
}
944+
}
945+
st := resumeState{
946+
Version: resumeStateVersion,
947+
Args: []string{"example.com"},
948+
Inputs: map[string]string{"words.txt": "00"},
949+
Settings: map[string]string{"t": "100"},
950+
Targets: []resumeTarget{{
951+
Domain: "example.com", Done: true, RootDone: 1, Stats: stats, Processed: 1, Total: 1,
952+
Results: []output.Result{{
953+
Result: scan.Result{Subdomain: "a.example.com", Records: []dns.Record{{Type: "A", Value: "192.0.2.1"}},
954+
Simulated: true, Takeover: "dangling", Internal: "private"},
955+
Change: "changed", PreviousRecords: []dns.Record{{Type: "A", Value: "192.0.2.2"}},
956+
Permutation: true, Sources: []string{"wordlist"},
957+
}},
958+
Entries: "00",
959+
Permute: &resumePass{RootDone: 1, Stats: stats, Processed: 1, Total: 1, Found: 1},
960+
CT: []string{"a"},
961+
CTFetched: true,
962+
Sources: map[string][]string{"crtsh": {"a"}},
963+
AXFR: []string{"a"},
964+
AXFRServers: []string{"ns"},
965+
AXFRDone: true,
966+
Denial: "nsec",
967+
}},
968+
}
969+
data, err := json.Marshal(st)
970+
if err != nil {
971+
t.Fatal(err)
972+
}
973+
var doc any
974+
if err := json.Unmarshal(data, &doc); err != nil {
975+
t.Fatal(err)
976+
}
977+
// Keys of the maps that hold user data (file names, settings, sources)
978+
// are values, not format; only their position is recorded.
979+
dataMaps := map[string]bool{"inputs": true, "settings": true, "targets.sources": true}
980+
var keys []string
981+
var walk func(path string, v any)
982+
walk = func(path string, v any) {
983+
switch v := v.(type) {
984+
case map[string]any:
985+
if dataMaps[path] {
986+
keys = append(keys, path+".*")
987+
return
988+
}
989+
for k, e := range v {
990+
p := k
991+
if path != "" {
992+
p = path + "." + k
993+
}
994+
keys = append(keys, p)
995+
walk(p, e)
996+
}
997+
case []any:
998+
for _, e := range v {
999+
walk(path, e)
1000+
}
1001+
}
1002+
}
1003+
walk("", doc)
1004+
slices.Sort(keys)
1005+
keys = slices.Compact(keys)
1006+
want := strings.Fields(`args inputs inputs.* settings settings.* version
1007+
targets targets.axfr targets.axfr_done targets.axfr_servers targets.ct targets.ct_fetched
1008+
targets.denial targets.domain targets.done targets.entries targets.processed targets.root_done
1009+
targets.sources targets.sources.* targets.total targets.stats
1010+
targets.permute targets.permute.found targets.permute.processed targets.permute.root_done
1011+
targets.permute.total targets.permute.stats
1012+
targets.results targets.results.change targets.results.internal_address targets.results.permutation
1013+
targets.results.previous_records targets.results.previous_records.type targets.results.previous_records.value
1014+
targets.results.records targets.results.records.type targets.results.records.value
1015+
targets.results.simulated targets.results.sources targets.results.subdomain targets.results.takeover_candidate`)
1016+
// scan.Stats is stored twice, for the target and for its -permute pass.
1017+
statsKeys := strings.Fields(`Aborted Confirmed Excluded Expired FinalRate Fingerprint Fingerprint.type
1018+
Fingerprint.value Found Inconclusive Internal NXDomain Other PoolHits QueriesSent RateBackoffs
1019+
Recovered Refused Retried RootDone Skipped Takeover Timeout Unconfirmed Wildcard WildcardFiltered`)
1020+
for _, prefix := range []string{"targets.stats.", "targets.permute.stats."} {
1021+
for _, k := range statsKeys {
1022+
want = append(want, prefix+k)
1023+
}
1024+
}
1025+
slices.Sort(want)
1026+
if !slices.Equal(keys, want) {
1027+
t.Errorf("resume state keys changed; bump resumeStateVersion or keep the old keys.\ngot: %q\nwant: %q", keys, want)
1028+
}
1029+
}
1030+
9211031
// TestMergeStatsCoversEveryField is the drift guard of #162: a field added to
9221032
// scan.Stats that mergeStats drops fails here. Each field set in either the
9231033
// saved or the resumed run must survive the merge; RootDone, and Aborted and

‎internal/cli/session.go‎

Lines changed: 10 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ import (
1919
"github.com/TMHSDigital/subenum/internal/dns"
2020
"github.com/TMHSDigital/subenum/internal/output"
2121
"github.com/TMHSDigital/subenum/internal/passive"
22+
"github.com/TMHSDigital/subenum/internal/report"
2223
"github.com/TMHSDigital/subenum/internal/scan"
2324
"github.com/TMHSDigital/subenum/internal/tui"
2425
"github.com/TMHSDigital/subenum/internal/wordlist"
@@ -56,7 +57,7 @@ type session struct {
5657
restored map[string]bool // names re-emitted from a -resume state
5758
refound int // restored names a resumed pass found again (#156)
5859

59-
status []string
60+
status []report.Status
6061
results []targetResult
6162
runs []resultLog // results per target, for -resume state
6263
entryDigests []string // per target, for -resume state
@@ -577,7 +578,7 @@ func (s *session) emitPermutation(ev scan.Event) { s.emitResult(ev, true) }
577578
// array and CSV has a single header.
578579
func (s *session) scanAll(ctx context.Context) {
579580
n := len(s.targets)
580-
s.status = make([]string, n)
581+
s.status = make([]report.Status, n)
581582
s.results = make([]targetResult, n)
582583
s.runs = make([]resultLog, n)
583584
s.entryDigests = make([]string, n)
@@ -595,11 +596,7 @@ func (s *session) scanAll(ctx context.Context) {
595596
if n > 1 {
596597
s.out.Info("Targets:")
597598
for i, target := range s.targets {
598-
st := s.status[i]
599-
if st == "" {
600-
st = "not run"
601-
}
602-
s.out.Info(" %-8s %s", st, target)
599+
s.out.Info(" %-8s %s", s.status[i].Label(), target)
603600
}
604601
}
605602
}
@@ -628,7 +625,7 @@ func (s *session) scanOneTarget(ctx context.Context, i int, target string) (next
628625
if len(entries) == 0 {
629626
out.Error("no valid wordlist entries for %s", target)
630627
s.anyFailed = true
631-
s.status[i] = "failed"
628+
s.status[i] = report.StatusFailed
632629
s.results[i] = targetResult{failed: true, err: "no valid wordlist entries"}
633630
s.failedTargets++
634631
return true
@@ -677,7 +674,7 @@ func (s *session) scanOneTarget(ctx context.Context, i int, target string) (next
677674
s.results[i] = res
678675
s.runs[i] = s.targetResults
679676
s.anyDone = true
680-
s.status[i] = "ok"
677+
s.status[i] = report.StatusOK
681678
return true
682679
}
683680
pass.resumeFrom, pass.resumeNames = saved.RootDone, s.targetResults.mainPassNames()
@@ -752,18 +749,18 @@ func (s *session) recordTarget(i int, res targetResult) (next bool) {
752749
s.runs[i] = s.targetResults
753750
s.anyDone = s.anyDone || res.done
754751
s.anyFailed = s.anyFailed || res.failed
755-
s.status[i] = "ok"
752+
s.status[i] = report.StatusOK
756753
switch {
757754
case res.failed:
758-
s.status[i] = "failed"
755+
s.status[i] = report.StatusFailed
759756
s.failedTargets++
760757
case s.signalCode.Load() != 0:
761-
s.status[i] = "interrupted"
758+
s.status[i] = report.StatusInterrupted
762759
}
763760
if res.resolverAbort && i < len(s.targets)-1 {
764761
s.out.Error("resolver %s looks overloaded; skipping the %d remaining targets (use -no-abort to continue)", s.f.dnsServer, len(s.targets)-1-i)
765762
for j := i + 1; j < len(s.targets); j++ {
766-
s.status[j] = "skipped"
763+
s.status[j] = report.StatusSkipped
767764
s.failedTargets++
768765
}
769766
return false

‎internal/cli/summary.go‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ func buildSummary(s *session, elapsed time.Duration) output.Summary {
3232
return sum
3333
}
3434

35-
func targetSummary(domain, status string, res targetResult) output.TargetSummary {
35+
func targetSummary(domain string, status report.Status, res targetResult) output.TargetSummary {
3636
t := report.Target(domain, status, res.err, res.done, res.final, scan.FlagName)
3737
ct := sourceByName(res.sources, "ct")
3838
t.CTNames, t.CTError = len(ct.names), ct.err
@@ -43,13 +43,13 @@ func targetSummary(domain, status string, res targetResult) output.TargetSummary
4343
t.AXFRFound = res.foundBy[sourceAXFR]
4444
t.ZoneDenial = string(res.axfr.denial)
4545
t.QueriesSent += res.axfr.queries // the NS and address lookups and the transfers (#85)
46-
if p := res.permutation; p != nil && res.done && status != "" && status != "skipped" {
46+
if p := res.permutation; p != nil && res.done && status != report.StatusNotRun && status != report.StatusSkipped {
4747
t.Permutation = &output.PermutationSummary{Seeds: p.seeds, Candidates: p.candidates, Found: p.found}
4848
if p.pass.done {
4949
// The pass is part of the target's scan: its queries count, and a
5050
// worse verdict than the main pass's becomes the target's (#298).
5151
final := p.pass.final
52-
verdict, reason := final.Stats.Verdict(status == "interrupted")
52+
verdict, reason := final.Stats.Verdict(status == report.StatusInterrupted)
5353
t.Permutation.Verdict = verdict
5454
t.Permutation.Processed, t.Permutation.QueriesSent = final.Processed, final.Stats.QueriesSent
5555
t.QueriesSent += final.Stats.QueriesSent

‎internal/output/file.go‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,20 @@ func CreateFile(path string) (*File, error) {
5757
return &File{Writer: bufio.NewWriter(f), path: path, f: f, tmp: true}, nil
5858
}
5959

60+
// WriteFile writes data to path the way CreateFile does: atomically, so a
61+
// failed write leaves an existing file unchanged (#331).
62+
func WriteFile(path string, data []byte) error {
63+
f, err := CreateFile(path)
64+
if err != nil {
65+
return err
66+
}
67+
_, werr := f.Write(data)
68+
if cerr := f.Close(werr == nil); werr == nil {
69+
werr = cerr
70+
}
71+
return werr
72+
}
73+
6074
// createTemp is os.CreateTemp with mode 0666, so the umask applies the way
6175
// it does to os.Create; os.CreateTemp always creates 0600.
6276
func createTemp(dir, prefix string) (*os.File, error) {

‎internal/output/lifecycle_test.go‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,28 @@ func TestFileDiscardKeepsTarget(t *testing.T) {
9090
noTempFiles(t, dir)
9191
}
9292

93+
// TestWriteFile covers the helper the side files share (#331): it replaces
94+
// an existing file without leaving a temporary file, and fails cleanly when
95+
// the file cannot be created.
96+
func TestWriteFile(t *testing.T) {
97+
dir := t.TempDir()
98+
path := filepath.Join(dir, "state.json")
99+
if err := os.WriteFile(path, []byte("old\n"), 0o600); err != nil {
100+
t.Fatal(err)
101+
}
102+
if err := WriteFile(path, []byte("new\n")); err != nil {
103+
t.Fatal(err)
104+
}
105+
if got, _ := os.ReadFile(path); string(got) != "new\n" {
106+
t.Fatalf("file after WriteFile = %q", got)
107+
}
108+
noTempFiles(t, dir)
109+
if err := WriteFile(filepath.Join(dir, "missing", "state.json"), []byte("x")); err == nil {
110+
t.Fatal("WriteFile in a missing directory succeeded")
111+
}
112+
noTempFiles(t, dir)
113+
}
114+
93115
func TestCreateFileMissingDirectory(t *testing.T) {
94116
if _, err := CreateFile(filepath.Join(t.TempDir(), "missing", "results.txt")); err == nil {
95117
t.Fatal("CreateFile in a missing directory succeeded")

0 commit comments

Comments
 (0)