Skip to content

Commit aa7920d

Browse files
committed
docs: list every CLI flag in README
Signed-off-by: NekoPaw <152394158+sb123sb123@users.noreply.github.com>
1 parent 08c444d commit aa7920d

2 files changed

Lines changed: 68 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -263,6 +263,7 @@ make help # list all targets
263263
| `-timeout <ms>` | `1000` | DNS timeout in milliseconds, applied to each record-type lookup separately |
264264
| `-dns-server <ip:port>` | `8.8.8.8:53` | DNS server address (validated on startup) |
265265
| `-attempts <n>` | `1` | DNS resolution attempts per subdomain (1 = no retry) |
266+
| `-ct` | `false` | Add names from Certificate Transparency logs (crt.sh; one HTTPS request per target, no API key) as candidates and `-permute` seeds |
266267
| `-force` | `false` | Continue scanning even if wildcard DNS is detected |
267268
| `-no-abort` | `false` | Keep scanning after the 20% resolver failure-rate abort (warning is still emitted) |
268269
| `-max-queries <n>` | `0` | Max candidate names to test (0 = unlimited). Each name sends one query per record type per attempt (`CNAME` costs two) |
@@ -272,6 +273,7 @@ make help # list all targets
272273
| `-rate <qps>` | `0` | Max DNS queries per second on the wire, all workers combined, including every record type, retry, wildcard probe and the preflight (0 = unlimited) |
273274
| `-type <list>` | `A,AAAA` | Comma-separated record types to look up: `A`, `AAAA`, `CNAME` |
274275
| `-recursive` | `false` | Recursively enumerate subdomains of discovered subdomains |
276+
| `-permute` | `false` | After each scan, scan permutations of discovered names (`api` → `api-dev`, `dev-api`, `dev.api`, `api2`, ...) |
275277
| `-depth <n>` | `1` | Max recursion depth when `-recursive` is set (1 = no recursion) |
276278
| `-v` | `false` | Verbose output: IPs, timings, per-query detail (stderr) |
277279
| `-progress` | `true` | Live progress line on stderr. Off by default when stderr is not a terminal; passing `-progress` there prints whole progress lines instead of redrawing one |
@@ -287,8 +289,12 @@ make help # list all targets
287289
| `-stats <file>` | n/a | Write a JSON run-quality report (outcomes, queries sent, verdict); see [Run-quality report](#run-quality-report) |
288290
| `-sarif <file>` | n/a | Write takeover candidates as SARIF 2.1.0 for GitHub code scanning; needs CNAME in `-type` |
289291
| `-tui` | `false` | Launch the interactive Terminal UI |
292+
| `-print-config` | `false` | Print every setting's effective value and source (`flag`, env, config or default), then exit |
290293
| `-version` | n/a | Print version and exit |
291294
| `-retries <n>` | n/a | **Deprecated** - alias for `-attempts`, prints a warning |
295+
| `-resume <file>` | n/a | Resume an interrupted run from its state file; takes no other arguments |
296+
| `-seeds <file>` | n/a | Results file (any `-format`) whose names also seed `-permute`; implies `-permute` |
297+
| `-state <file>` | `subenum-resume.json` | Where an interrupted run saves its state for `-resume` |
292298

293299
<br>
294300

‎main_docs_test.go‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ import (
1212
// siteFlagsFile is the site's flag table, generated from the real FlagSet so
1313
// the docs cannot drift from `subenum -h` (#64).
1414
var siteFlagsFile = filepath.Join("docs", "_includes", "flags.md")
15+
var readmeFlagsFile = "README.md"
1516

1617
// flagsMarkdown renders every flag as a Markdown table, sorted by name.
1718
func flagsMarkdown(fs *flag.FlagSet) string {
@@ -56,3 +57,64 @@ func TestSiteFlagTableUpToDate(t *testing.T) {
5657
t.Fatalf("%s is out of date with the CLI flags; run `make docs-flags`", siteFlagsFile)
5758
}
5859
}
60+
61+
// TestREADMEFlagTableCoversCLI keeps the hand-written README table complete
62+
// when a CLI flag is added. The website table is generated, but the README is
63+
// maintained separately for quick reference (#137).
64+
func TestREADMEFlagTableCoversCLI(t *testing.T) {
65+
contents, err := os.ReadFile(readmeFlagsFile) //nolint:gosec // a docs file
66+
if err != nil {
67+
t.Fatal(err)
68+
}
69+
70+
inTable := false
71+
tableStarted := false
72+
documented := make(map[string]bool)
73+
for _, line := range strings.Split(strings.ReplaceAll(string(contents), "\r\n", "\n"), "\n") {
74+
line = strings.TrimSpace(line)
75+
if line == "### CLI flags" {
76+
inTable = true
77+
continue
78+
}
79+
if !inTable {
80+
continue
81+
}
82+
if !strings.HasPrefix(line, "|") {
83+
if tableStarted {
84+
break
85+
}
86+
continue
87+
}
88+
tableStarted = true
89+
90+
cells := strings.SplitN(line, "|", 3)
91+
if len(cells) < 2 {
92+
continue
93+
}
94+
cell := strings.TrimSpace(cells[1])
95+
if !strings.HasPrefix(cell, "`-") {
96+
continue
97+
}
98+
name := strings.TrimPrefix(cell, "`-")
99+
if end := strings.IndexAny(name, " \t<`"); end >= 0 {
100+
name = name[:end]
101+
}
102+
if name != "" {
103+
documented[name] = true
104+
}
105+
}
106+
if !inTable || !tableStarted {
107+
t.Fatalf("%s has no CLI flags table", readmeFlagsFile)
108+
}
109+
110+
_, _, fs, _ := parseFlags(nil)
111+
var missing []string
112+
fs.VisitAll(func(fl *flag.Flag) {
113+
if !documented[fl.Name] {
114+
missing = append(missing, "-"+fl.Name)
115+
}
116+
})
117+
if len(missing) > 0 {
118+
t.Fatalf("%s CLI flags table is missing flags: %s", readmeFlagsFile, strings.Join(missing, ", "))
119+
}
120+
}

0 commit comments

Comments
 (0)