Skip to content

Commit f9b5003

Browse files
fix: pre-release corrections for v0.7.0
Document -no-abort and -max-queries, generate GitHub release notes, and pin go.mod at 1.24.2. A patchless go 1.24 line makes go build refuse to run because charmbracelet/bubbles requires 1.24.2; make tidy is go mod tidy plus a CI grep that fails on drift. Co-authored-by: Cursor <cursoragent@cursor.com>
1 parent 1793b6b commit f9b5003

9 files changed

Lines changed: 83 additions & 9 deletions

File tree

‎.github/workflows/go.yml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,16 @@ jobs:
3636
- name: Verify dependencies
3737
run: go mod verify
3838

39+
- name: Check go directive
40+
shell: bash
41+
run: |
42+
want='go 1.24.2'
43+
got=$(grep -m1 '^go ' go.mod)
44+
if [ "$got" != "$want" ]; then
45+
echo "go.mod directive drifted: got '$got', want '$want'. Run 'make tidy'."
46+
exit 1
47+
fi
48+
3949
- name: Build
4050
run: go build -v -buildvcs=false -ldflags "-X main.Version=$(git describe --tags --dirty)" ./...
4151

@@ -69,6 +79,7 @@ jobs:
6979
uses: softprops/action-gh-release@v3
7080
with:
7181
draft: true
82+
generate_release_notes: true
7283
env:
7384
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
7485

‎CHANGELOG.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
2828
- TUI form now validates domain syntax and DNS server `ip:port` format up front, matching the CLI. The validators were extracted into a shared `internal/validate` package used by both entry points (previously the form only checked for non-empty values).
2929
- `validate.Domain` now enforces the 63-character per-label limit and accepts punycode TLDs (`xn--...`).
3030
- `Version` is a `var` injected via `-ldflags "-X main.Version=$(git describe --tags --dirty)"`. `-version` writes to stdout.
31-
- `go` directive is `1.24`. golangci-lint CI is pinned to v2.12.2. Docker final stage is distroless static nonroot, with builder and runtime images pinned by digest.
31+
- `go` directive is `1.24.2` (required by charmbracelet/bubbles; a patchless `go 1.24` makes `go build` demand tidy). golangci-lint CI is pinned to v2.12.2. Docker final stage is distroless static nonroot, with builder and runtime images pinned by digest. Tagged releases generate GitHub release notes.
3232

3333
### Removed
3434
- Removed the unused `dns.Resolve` function, superseded by `dns.ResolveTypes`.
@@ -42,7 +42,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
4242
- Refreshed the DEVELOPER_GUIDE: removed "Future Development" items that already shipped, updated the file tree, and corrected `dns` package references.
4343
- Fixed stale references in `DOCUMENTATION_STRUCTURE.md` (changelog path) and README (package blurbs).
4444
- Added `docs/ROADMAP.md` capturing the prioritized review findings and follow-up plan.
45-
- GitHub Pages landing page (`docs/index.md`) refreshed to the 0.6.0 feature set, adding cards for Output Formats (`-format`), Rate Limiting (`-rate`), Record Types (`-type`), and Recursive Enumeration (`-recursive`/`-depth`).
45+
- GitHub Pages landing page (`docs/index.md`) covers the 0.7.0 feature set: scan accounting, `-no-abort`, `-max-queries`, the recursion ceiling, and wildcard fingerprint filtering.
4646
- Normalized em dashes to hyphens across `docs/` for consistency with the no-em-dash convention.
4747
- Documented outcome classification, `EventDone.Stats`, and the reliability guard in ARCHITECTURE.
4848
- Corrected ARCHITECTURE output-format note (TUI file output shipped in P5) and DEVELOPER_GUIDE "CLI-only zero deps" claim.

‎Makefile‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
.PHONY: build test clean lint run tui docker-build docker-run wordlist wordlist-gen simulate simulate-verbose
1+
.PHONY: build test clean lint tidy run tui docker-build docker-run wordlist wordlist-gen simulate simulate-verbose
22

33
# Default Go parameters
44
GOCMD=go
@@ -46,6 +46,10 @@ clean:
4646
lint:
4747
golangci-lint run
4848

49+
# go mod tidy. The go directive must stay go 1.24.2 (bubbles requires it).
50+
tidy:
51+
go mod tidy
52+
4953
# Build wordlist generator
5054
wordlist-gen:
5155
$(GOBUILD) -buildvcs=false -o tools/$(WORDLIST_GEN) tools/wordlist-gen.go
@@ -104,6 +108,7 @@ help:
104108
@echo " make test-short - Run short tests"
105109
@echo " make clean - Clean build artifacts"
106110
@echo " make lint - Run linter"
111+
@echo " make tidy - go mod tidy (keeps go 1.24.2)"
107112
@echo " make tui - Launch the interactive terminal UI (no arguments needed)"
108113
@echo ""
109114
@echo " LIVE MODE (performs real DNS queries):"

‎README.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,9 @@ Or launch the interactive terminal UI with no flags:
7171
| :--- | :--- |
7272
| Worker Pool | Spawn N goroutines for parallel DNS resolution with a configurable concurrency ceiling |
7373
| DNS Engine | Resolve subdomains against any DNS server with per-query timeouts and retry backoff |
74-
| Wildcard Detection | Double-probe check before scanning; aborts early unless `-force` is set |
74+
| Wildcard Detection | Double-probe check before scanning; aborts early unless `-force` is set. With `-force`, answers that match the wildcard fingerprint are dropped |
75+
| Scan Accounting | Every query is counted as resolved, nxdomain, timeout, refused, or other. After 200 queries a >20% infrastructure failure rate aborts unless `-no-abort` is set |
76+
| Query Cap | `-max-queries` stops admitting work. Recursive scans warn about the theoretical ceiling and refuse to start above 1e7 jobs unless `-max-queries` or `-force` is set |
7577
| Graceful Shutdown | Trap SIGINT/SIGTERM, drain in-flight workers, flush partial results |
7678
| Input Validation | RFC-compliant domain syntax and strict `ip:port` format enforcement |
7779
| Wordlist Dedup | Deduplicate wordlist entries in a single pass before scanning begins |
@@ -201,6 +203,8 @@ make help # list all targets
201203
| `-dns-server <ip:port>` | `8.8.8.8:53` | DNS server address (validated on startup) |
202204
| `-attempts <n>` | `1` | DNS resolution attempts per subdomain (1 = no retry) |
203205
| `-force` | `false` | Continue scanning even if wildcard DNS is detected |
206+
| `-no-abort` | `false` | Keep scanning after the 20% resolver failure-rate abort (warning is still emitted) |
207+
| `-max-queries <n>` | `0` | Max DNS lookups to admit (0 = unlimited) |
204208
| `-o <file>` | n/a | Write results to file in addition to stdout |
205209
| `-format <fmt>` | `text` | Output format: `text`, `json`, or `csv` |
206210
| `-rate <qps>` | `0` | Max DNS queries per second across all workers (0 = unlimited) |
@@ -218,7 +222,7 @@ make help # list all targets
218222
<br>
219223

220224
> [!NOTE]
221-
> Wildcard DNS is detected automatically before scanning begins. If the target resolves wildcard records, the tool exits with a warning, since all subdomains would match, making results meaningless. Pass `-force` to override.
225+
> Wildcard DNS is detected automatically before scanning begins. If the target resolves wildcard records, the tool exits with a warning, since all subdomains would match, making results meaningless. Pass `-force` to override. With `-force`, results whose records are a subset of the wildcard fingerprint are still dropped and counted as `wildcard-filtered`. Recursive scans probe each new parent and skip expanding wildcard branches.
222226
223227
> [!CAUTION]
224228
> Simulation mode (`-simulate`) generates synthetic results and performs zero network I/O. Do not confuse simulated output with real DNS data.

‎docs/ARCHITECTURE.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -139,7 +139,7 @@ internal/tui/config.go - Session persistence (load/save ~/.config/subenu
139139

140140
The flow of data through the `subenum` application can be summarized as follows:
141141

142-
1. **Input**: The user provides command-line arguments: the target domain, the path to a wordlist file (`-w`), a concurrency level (`-t`), a DNS timeout (`-timeout`), a DNS server (`-dns-server`), attempts (`-attempts`), output options (`-o`, `-format`), and scan tuning (`-rate`, `-type`, `-recursive`, `-depth`), plus flags for verbose mode (`-v`), progress reporting (`-progress`), and force mode (`-force`). The TUI (`-tui`) gathers the equivalent values from its form instead.
142+
1. **Input**: The user provides command-line arguments: the target domain, the path to a wordlist file (`-w`), a concurrency level (`-t`), a DNS timeout (`-timeout`), a DNS server (`-dns-server`), attempts (`-attempts`), output options (`-o`, `-format`), and scan tuning (`-rate`, `-type`, `-recursive`, `-depth`, `-max-queries`, `-no-abort`), plus flags for verbose mode (`-v`), progress reporting (`-progress`), and force mode (`-force`). The TUI (`-tui`) gathers the equivalent values from its form instead.
143143
2. **Configuration**: These arguments are parsed and validated by the **Argument Parsing** component and assembled into a `scan.Config`, which is the single input to the scan engine.
144144
3. **Preflight and wildcard detection**: Inside `scan.Run` the apex is resolved once; any outcome other than Found or NXDOMAIN emits `EventError` naming the resolver and returns. Then two random subdomains are resolved (skipped in simulation mode). The union of those answers is the wildcard fingerprint. If either resolves, an `EventWildcard` is emitted; the scan aborts unless `-force` is set. With `-force`, later results whose records are a subset of the fingerprint are dropped. In recursive mode the same probe is run against each newly resolved parent before expansion; a wildcard branch is skipped. `-recursive` also computes the job ceiling and refuses to start above 1e7 unless `-max-queries` or `-force` is set.
145145
4. **Wordlist Loading**: `wordlist.LoadWordlist` reads the file in a single pass, sanitizes lines, and deduplicates entries into a slice, which is passed to `scan.Run` via `Config.Entries`.

‎docs/CONTRIBUTING.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,12 @@ See the [Code of Conduct](CODE_OF_CONDUCT.html).
1818
- Make (optional but recommended)
1919
- Docker (optional, for containerized development)
2020

21+
The `go` directive in `go.mod` must stay exactly `go 1.24.2`. CI fails the build
22+
if it drifts. `github.com/charmbracelet/bubbles` declares `go 1.24.2`, so a
23+
patchless `go 1.24` line makes `go build` refuse to run until tidy bumps it.
24+
On PowerShell, unquoted `-go=1.24` is also parsed as `-go=1`. After changing
25+
dependencies run `make tidy`.
26+
2127
### Getting Started
2228

2329
1. **Fork the repository** on GitHub
@@ -47,6 +53,9 @@ make test
4753
# Run linter
4854
make lint
4955

56+
# Tidy modules (keeps the go 1.24.2 pin)
57+
make tidy
58+
5059
# Clean up build artifacts
5160
make clean
5261

‎docs/index.md‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ subenum brute-forces subdomains by resolving a wordlist against a target domain
2929
</div>
3030
<div class="feature-card">
3131
<strong>Wildcard Detection</strong>
32-
<span>Double-probe check before scanning; exits early unless <code>-force</code> is set.</span>
32+
<span>Double-probe check before scanning; exits early unless <code>-force</code> is set. With <code>-force</code>, answers matching the wildcard fingerprint are dropped. Recursive scans skip expanding wildcard branches.</span>
3333
</div>
3434
<div class="feature-card">
3535
<strong>Interactive TUI</strong>
@@ -71,6 +71,14 @@ subenum brute-forces subdomains by resolving a wordlist against a target domain
7171
<strong>Input Validation</strong>
7272
<span>RFC-compliant domain syntax and strict <code>ip:port</code> format enforcement on startup.</span>
7373
</div>
74+
<div class="feature-card">
75+
<strong>Scan Accounting</strong>
76+
<span>Every query is counted as resolved, nxdomain, timeout, refused, or other. After 200 queries a greater than 20% infrastructure failure rate aborts unless <code>-no-abort</code> is set.</span>
77+
</div>
78+
<div class="feature-card">
79+
<strong>Query Cap</strong>
80+
<span><code>-max-queries</code> stops admitting work. Recursive scans warn about the theoretical ceiling and refuse to start above 1e7 jobs unless <code>-max-queries</code> or <code>-force</code> is set.</span>
81+
</div>
7482
</div>
7583

7684
---

‎examples/advanced_usage.md‎

Lines changed: 38 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -191,6 +191,43 @@ Use `-rate` to cap the total number of DNS queries per second across the whole w
191191

192192
The limiter is context-aware, so `Ctrl+C` stays responsive while workers are waiting on it.
193193

194+
## Reliability Guard and `-no-abort`
195+
196+
Every query is classified as resolved, nxdomain, timeout, refused, or other. The
197+
breakdown is printed after every scan. Once 200 queries have completed, if more
198+
than 20% failed as timeout, refused, or other, the scan emits an error naming
199+
the failure rate and likely resolver rate-limiting at the configured `-t` and
200+
`-rate`, then aborts. NXDOMAIN is a definitive negative and is not counted as
201+
a failure.
202+
203+
Pass `-no-abort` to keep the warning but finish the wordlist:
204+
205+
```bash
206+
./subenum -w wordlist.txt -no-abort example.com
207+
```
208+
209+
## Query Cap and Recursion Ceiling
210+
211+
`-max-queries` stops admitting new work once the cap is reached (0 = unlimited).
212+
Recursive scans also compute the theoretical ceiling (`sum n^d` over depth).
213+
A ceiling above 1e7 refuses to start unless `-max-queries` or `-force` is set.
214+
215+
```bash
216+
./subenum -w wordlist.txt -recursive -depth 2 -max-queries 50000 example.com
217+
```
218+
219+
## Wildcard Fingerprint Filter
220+
221+
Wildcard detection keeps the union of both probe answers as a fingerprint.
222+
Without `-force` the scan still exits. With `-force`, later results whose
223+
records are a subset of that fingerprint are dropped and counted as
224+
`wildcard-filtered`. Recursive mode probes each newly resolved parent and
225+
skips expanding a wildcard branch.
226+
227+
```bash
228+
./subenum -w wordlist.txt -force example.com
229+
```
230+
194231
## Output Formats
195232

196233
By default `subenum` prints human-readable `Found:` lines. Use `-format` to emit structured output instead. The `-o` file honors the same format.
@@ -233,7 +270,7 @@ For CI/CD environments, you can use the version flag to ensure the correct versi
233270

234271
```bash
235272
./subenum -version
236-
# Output: subenum v0.6.0
273+
# Output: subenum v0.7.0
237274
```
238275

239276
Use simulation mode in CI pipelines to test the tool's behaviour without network access:

‎go.mod‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
module github.com/TMHSDigital/subenum
22

3-
go 1.24
3+
go 1.24.2
44

55
require (
66
github.com/charmbracelet/bubbles v1.0.0

0 commit comments

Comments
 (0)