Skip to content

Commit 0c4d292

Browse files
TMHSDigitalclaude
andcommitted
feat(cli): config file and env defaults, completions, man page
Defaults now come from <user config dir>/subenum/config.json (or $SUBENUM_CONFIG, a JSON object keyed by flag name) and SUBENUM_<FLAG> environment variables, with precedence flag > env > config > built-in. Defaults are applied before parsing without marking flags as given, so explicit-only checks keep working; an unknown key or bad value exits 2. -print-config shows every effective setting and its source. subenum completion bash|zsh|fish|powershell and subenum man generate completions and a man page from the FlagSet. GoReleaser runs the hidden generate-assets subcommand and ships them under completions/ and man/ in every archive; the snapshot CI job syntax-checks each script in its own shell and lints the man page with groff. A TestMain keeps the package's tests hermetic from a developer's real config and SUBENUM_* variables. Fixes #88 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent e36e1d6 commit 0c4d292

11 files changed

Lines changed: 613 additions & 2 deletions

File tree

‎.github/workflows/go.yml‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -143,6 +143,19 @@ jobs:
143143
file "$f" | grep -q 'statically linked'
144144
done
145145
146+
# The archives ship generated completions and a man page (#88); make sure
147+
# each one parses in its own shell, and the man page renders cleanly.
148+
- name: Check completions and man page
149+
shell: bash
150+
run: |
151+
sudo apt-get install -y -qq zsh fish groff >/dev/null
152+
tar -xzf dist/subenum_*_linux_amd64.tar.gz -C "$RUNNER_TEMP"
153+
bash -n "$RUNNER_TEMP/completions/subenum.bash"
154+
zsh -n "$RUNNER_TEMP/completions/_subenum"
155+
fish -n "$RUNNER_TEMP/completions/subenum.fish"
156+
pwsh -NoProfile -Command "\$e = \$null; [void][System.Management.Automation.Language.Parser]::ParseFile('$RUNNER_TEMP/completions/subenum.ps1', [ref]\$null, [ref]\$e); if (\$e) { \$e; exit 1 }"
157+
test -z "$(groff -man -ww -z "$RUNNER_TEMP/man/subenum.1" 2>&1)"
158+
146159
# Builds and publishes a release from a v* tag with GoReleaser (#61):
147160
# static binaries (#46), archives with LICENSE/README/CHANGELOG,
148161
# checksums.txt, SBOMs, a keyless cosign signature over the checksums, and

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,3 +42,4 @@ docs/_preview/
4242

4343
# GoReleaser output
4444
dist/
45+
build/

‎.goreleaser.yaml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@ project_name: subenum
99
before:
1010
hooks:
1111
- go mod verify
12+
# Shell completions and the man page, generated from the flags (#88).
13+
- go run . generate-assets build/assets
1214

1315
builds:
1416
- id: subenum
@@ -44,6 +46,10 @@ archives:
4446
- LICENSE
4547
- README.md
4648
- CHANGELOG.md
49+
- src: build/assets/completions/*
50+
dst: completions
51+
- src: build/assets/man/*
52+
dst: man
4753

4854
checksum:
4955
name_template: checksums.txt

‎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+
- Defaults from a config file and the environment: `config.json` in the user config directory (or `$SUBENUM_CONFIG`) and `SUBENUM_<FLAG>` variables, with precedence flag > env > config > built-in. `-print-config` shows each effective setting and its source. `subenum completion bash|zsh|fish|powershell` and `subenum man` generate shell completions and a man page from the flags, and release archives ship them (#88).
1112
- A useful default wordlist: `-w` is now optional. Without it, subenum uses an embedded list of the 5,000 most common subdomain labels (SecLists `subdomains-top1million-5000.txt`, MIT; the license notice is kept in `data/subdomains-5k.txt`) and says so on stderr. The README gains a "Choosing a wordlist" section on larger lists and their query cost (#63).
1213
- Monitoring mode: `-diff previous` compares with an earlier results file (any format) and prints only names added (`+` / `"change": "added"`) or removed (`-` / `"removed"`), with a `change` CSV column; exit code `4` signals changes. The `-o` file keeps the full current results for the next run. Removals are reported only when the run's verdict is `complete`, and never for `-exclude`d names. The run-quality report gains a `diff` object, and `docs/monitoring.md` has a scheduled GitHub Actions workflow that opens an issue for new names (#84).
1314
- Subdomain takeover hints: results with a CNAME are marked `dangling` (target is NXDOMAIN), `provider:<name>` (target at a takeover-prone service such as S3, GitHub Pages, Heroku or Azure) or `dangling:<name>`. The marker appears in JSON/JSONL (`takeover_candidate`), as a CSV column when CNAME records are requested, in text with `-show-records`, in the TUI, and as a count in the breakdown and report. DNS-only; no HTTP probing (#71).

‎README.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -359,6 +359,26 @@ Press `Ctrl+C` at any time to abort. In-flight queries drain, partial results ar
359359

360360
With `-dL`, each domain is scanned in turn as an independent scan: `-max-queries`, `-rate` and the reliability guard apply per target. A failed target does not stop the others, but a reliability abort (the resolver looks overloaded) skips the remaining targets unless `-no-abort` is set. A per-target status list is printed at the end.
361361

362+
### Defaults, completions and the man page
363+
364+
Settings you repeat on every run can live in a config file or the environment. Precedence, highest first: **command-line flag > `SUBENUM_*` environment variable > config file > built-in default.**
365+
366+
```json
367+
{ "dns-server": "1.1.1.1:53", "rate": 200, "t": 50, "r": "/home/me/resolvers.txt" }
368+
```
369+
370+
- The config file is `config.json` in your user config directory (`~/.config/subenum/` on Linux, `~/Library/Application Support/subenum/` on macOS, `%AppData%\subenum\` on Windows), or the path in `SUBENUM_CONFIG`. Keys are flag names.
371+
- Each flag also reads `SUBENUM_<FLAG>`, upper-cased with dashes as underscores: `SUBENUM_DNS_SERVER`, `SUBENUM_RATE`, `SUBENUM_T`.
372+
- `subenum -print-config` shows every effective setting and where it came from (`flag`, `env`, `config` or `default`).
373+
374+
Shell completions and a man page are generated from the same flags, and release archives include them under `completions/` and `man/`:
375+
376+
```bash
377+
subenum completion bash > /etc/bash_completion.d/subenum # or zsh, fish, powershell
378+
subenum completion zsh > "${fpath[1]}/_subenum"
379+
subenum man > /usr/local/share/man/man1/subenum.1
380+
```
381+
362382
### Choosing a wordlist
363383

364384
Results can only be as good as the wordlist. Without `-w`, subenum uses its bundled top-5000 list (`data/subdomains-5k.txt`, from SecLists' `subdomains-top1million-5000.txt`), a good first pass that takes seconds. For deeper coverage:

‎docs/ROADMAP.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,6 @@ Ideas we want, with no date attached.
3737
- Resume interrupted scans with `-resume` ([#73](https://github.com/TMHSDigital/subenum/issues/73)).
3838
- Try AXFR and detect NSEC-walkable zones before brute-forcing ([#85](https://github.com/TMHSDigital/subenum/issues/85)).
3939
- DNS-over-TLS and DNS-over-HTTPS transports ([#86](https://github.com/TMHSDigital/subenum/issues/86)).
40-
- Shell completions, a man page, and defaults from a config file or `SUBENUM_*` variables ([#88](https://github.com/TMHSDigital/subenum/issues/88)).
4140
- A teaching / lab mode built on `-simulate` and the TUI ([#76](https://github.com/TMHSDigital/subenum/issues/76)).
4241
- Community and discoverability: Discussions, devcontainer, demo GIF, launch posts
4342
([#75](https://github.com/TMHSDigital/subenum/issues/75), [#74](https://github.com/TMHSDigital/subenum/issues/74)).

‎docs/_includes/flags.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
| `-max-queries <int>` | - | Max candidate names to test (0 = unlimited); each name sends one query per record type, per attempt |
1616
| `-no-abort` | - | Do not abort when the resolver failure rate exceeds 20% (warning is still emitted) |
1717
| `-o <string>` | - | Write results to file (in addition to stdout) |
18+
| `-print-config` | - | Print every setting's effective value and its source (flag, env, config or default), then exit |
1819
| `-progress` | true | Show progress during scanning |
1920
| `-r <string>` | - | File of resolvers (ip or ip:port, one per line) to spread queries over; every hit is re-validated against -dns-server |
2021
| `-rate <int>` | - | Max DNS queries per second on the wire, all workers combined; counts every record type, retry and wildcard probe (0 = unlimited) |

‎main.go‎

Lines changed: 30 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -112,6 +112,7 @@ func main() {
112112
// cliFlags holds all parsed command-line flag values.
113113
type cliFlags struct {
114114
tui bool
115+
printConfig bool
115116
wordlistFile string
116117
domainList string
117118
concurrency int
@@ -147,9 +148,17 @@ type cliFlags struct {
147148
// parseFlags parses args (without the program name). Flags may appear before or
148149
// after the domain; the returned positionals are every non-flag argument.
149150
func parseFlags(args []string) (cliFlags, []string, *flag.FlagSet, error) {
151+
return parseFlagsWith(args, nil)
152+
}
153+
154+
// parseFlagsWith is parseFlags with applyDefaults run after the flags are
155+
// defined and before the command line is parsed, so config-file and
156+
// environment defaults sit between built-in defaults and explicit flags (#88).
157+
func parseFlagsWith(args []string, applyDefaults func(*flag.FlagSet) error) (cliFlags, []string, *flag.FlagSet, error) {
150158
var f cliFlags
151159
fs := flag.NewFlagSet(ProgramName, flag.ContinueOnError)
152160
fs.BoolVar(&f.tui, "tui", false, "Launch the interactive terminal UI (all other flags are ignored)")
161+
fs.BoolVar(&f.printConfig, "print-config", false, "Print every setting's effective value and its source (flag, env, config or default), then exit")
153162
fs.StringVar(&f.wordlistFile, "w", "", "Path to the wordlist file (- for stdin); omitted: the bundled top-5000 list")
154163
fs.StringVar(&f.domainList, "dL", "", "File of apex domains to scan, one per line (- for stdin); replaces the <domain> argument")
155164
fs.IntVar(&f.concurrency, "t", 100, "Number of concurrent workers")
@@ -185,6 +194,11 @@ func parseFlags(args []string) (cliFlags, []string, *flag.FlagSet, error) {
185194
fs.PrintDefaults()
186195
_, _ = fmt.Fprint(w, "\n"+exitCodesHelp)
187196
}
197+
if applyDefaults != nil {
198+
if err := applyDefaults(fs); err != nil {
199+
return f, nil, fs, err
200+
}
201+
}
188202
positionals, err := parseInterspersed(fs, args)
189203
return f, positionals, fs, err
190204
}
@@ -467,7 +481,17 @@ func logScanBreakdown(domain string, ev scan.Event, out *output.Writer) {
467481
}
468482

469483
func run() (code int) {
470-
f, positionals, fs, parseErr := parseFlags(os.Args[1:])
484+
// completion, man (#88): handled before flag parsing.
485+
if code, ok := runSubcommand(os.Args[1:], os.Stdout, os.Stderr); ok {
486+
return code
487+
}
488+
489+
defaults := newDefaultsLoader()
490+
f, positionals, fs, parseErr := parseFlagsWith(os.Args[1:], defaults.apply)
491+
if errors.Is(parseErr, errConfig) {
492+
_, _ = fmt.Fprintf(os.Stderr, "Error: %v\n", parseErr)
493+
return exitUsage
494+
}
471495
if parseErr != nil {
472496
// The FlagSet has already printed the error and usage.
473497
if errors.Is(parseErr, flag.ErrHelp) {
@@ -485,6 +509,11 @@ func run() (code int) {
485509
return tui.Start()
486510
}
487511

512+
if f.printConfig {
513+
defaults.printConfig(os.Stdout, fs)
514+
return exitOK
515+
}
516+
488517
// -version answers before anything else prints, banners included (#58).
489518
if f.showVersion {
490519
fmt.Println(formatVersion())

0 commit comments

Comments
 (0)