Skip to content

Commit 01d9d2b

Browse files
TMHSDigitalclaude
andcommitted
docs(site): current homepage, generated flag table, share previews
- the hero shows real output: resolved names only, with records - the flag table is generated from the CLI's FlagSet into docs/_includes/flags.md; TestSiteFlagTableUpToDate fails on drift and make docs-flags regenerates it - features and "Why subenum" cover the run-quality report, resolver pool, takeover hints, monitoring and scope; README's Why is updated to match (it still said "one resolver you choose") - GHCR quick start, a Monitoring nav entry, exit codes - og:/twitter:card meta tags and a 1200x630 social preview image - DOCUMENTATION_STRUCTURE.md is excluded and the unused Cayman theme is dropped Fixes #64 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent da46b17 commit 01d9d2b

10 files changed

Lines changed: 186 additions & 52 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
1616
- Run-quality report: `-stats <file>` writes a schema-versioned JSON summary of a run (outcomes per target, DNS queries actually sent, achieved query rate, wildcard fingerprint, candidates skipped by `-max-queries`) with a `complete` / `degraded` / `unreliable` verdict and its reason. `-format jsonl` ends with the same object as its last line. The README documents the schema and how to gate CI on the verdict (#70).
1717

1818
### Changed
19+
- The GitHub Pages site is current: the hero shows real output (resolved names only), the flag table is generated from the CLI's own flags (a test fails when it drifts; `make docs-flags` regenerates it), the features cover the run-quality report, resolver pool, takeover hints, monitoring and scope control, there is a GHCR quick start and a Monitoring page, shared links get `og:`/Twitter preview cards with a new social image, the internal `DOCUMENTATION_STRUCTURE.md` template is no longer published, and the unused Cayman theme is gone. The README's "Why subenum" is updated to match (#64).
1920
- Tests run against a shared, scriptable DNS server, `internal/dnstest`, built on `golang.org/x/net/dns/dnsmessage`. It replaces the two hand-encoded responders, answers per name and type with records, any RCODE, NODATA with SOA, delays, drops or truncation, and counts queries per name and type. New tests cover NODATA, a resolver at an IPv6 address, exact wire queries per record type, and TCP fallback after truncation (#67).
2021
- The minimum Go version is now 1.26 (`go 1.26.0` in go.mod), required by current `golang.org/x/sys` and `golang.org/x/text`; both were bumped and `govulncheck -show verbose` now reports no vulnerable modules. Dependabot also updates indirect modules, and CI lints with errorlint, nilerr, contextcheck, noctx, copyloopvar, usestdlibvars and revive, with errcheck exemptions narrowed to stdout prints (#83).
2122

‎Makefile‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
.PHONY: all build test test-short bench clean lint tidy tui run run-verbose run-custom require-domain \
1+
.PHONY: all build test test-short bench docs-flags clean lint tidy tui run run-verbose run-custom require-domain \
22
simulate simulate-verbose simulate-custom wordlist wordlist-gen docker-build docker-run docker-simulate help
33

44
# Default Go parameters
@@ -41,6 +41,11 @@ test:
4141
test-short:
4242
$(GOTEST) -v ./... -short
4343

44+
# Regenerate the site's flag table (docs/_includes/flags.md) from the CLI's
45+
# flags; a test fails CI when it drifts (#64).
46+
docs-flags:
47+
UPDATE_DOCS=1 $(GOTEST) -run '^TestSiteFlagTableUpToDate$$' -count=1 .
48+
4449
# Dispatcher throughput on a 1M-entry simulated scan; overhead must stay
4550
# linear in wordlist size (#49).
4651
bench:

‎README.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -72,12 +72,14 @@ Or launch the interactive terminal UI with no flags:
7272

7373
## Why subenum
7474

75-
Tools like [puredns](https://github.com/d3mondev/puredns), [shuffledns](https://github.com/projectdiscovery/shuffledns) and [dnsx](https://github.com/projectdiscovery/dnsx) are faster at mass resolution across large resolver pools, and [subfinder](https://github.com/projectdiscovery/subfinder) covers passive sources. subenum is a single static binary that brute-forces against one resolver you choose and focuses on telling you how much to trust the result:
75+
Tools like [puredns](https://github.com/d3mondev/puredns), [shuffledns](https://github.com/projectdiscovery/shuffledns) and [dnsx](https://github.com/projectdiscovery/dnsx) are built for raw mass resolution, and [subfinder](https://github.com/projectdiscovery/subfinder) covers passive sources. subenum is a single static binary focused on telling you how much to trust the result:
7676

77-
- **It accounts for every query.** Each lookup is classified as resolved, nxdomain, timeout, refused or other, and the breakdown is printed after every scan. When more than 20% of queries fail, the scan stops and blames the resolver instead of returning a quietly incomplete list.
78-
- **It handles wildcards.** Wildcard DNS is detected before the scan starts. With `-force`, answers matching the wildcard fingerprint are dropped, and recursive scans skip wildcard branches.
77+
- **It accounts for every query.** Each lookup is classified as resolved, nxdomain, timeout, refused or other. `-stats` writes a versioned JSON report with a `complete` / `degraded` / `unreliable` verdict that CI can gate on, and when more than 20% of queries fail the scan stops and blames the resolver instead of returning a quietly incomplete list.
78+
- **It handles wildcards,** including CDN and load-balancer pools that rotate their answers. With `-force`, answers matching the wildcard fingerprint are dropped, inconclusive wildcard checks are reported rather than read as "no wildcard", and recursive scans skip wildcard branches.
79+
- **Its resolver pool cannot lie to you.** `-r resolvers.txt` spreads queries over many resolvers and benches failing ones, and every hit is re-validated against your trusted `-dns-server` before it is reported.
7980
- **Its rate limit is real.** `-rate` caps DNS packets on the wire, including retries, every record type and wildcard probes, so it can be quoted in rules of engagement.
80-
- **It can be taught and demoed.** `-simulate` produces realistic output with zero network traffic, and `-tui` gives a form-driven interface for people who don't live in a shell.
81+
- **It respects scope.** `-exclude` keeps out-of-scope names from ever being queried.
82+
- **It can be taught and demoed.** `-simulate` produces marked, reproducible output with zero network traffic, and `-tui` gives a form-driven interface for people who don't live in a shell.
8183

8284
<br>
8385

‎docs/ROADMAP.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,6 @@ Planned features that make results more trustworthy and the tool easier to get.
2929
GoReleaser archives, checksums, SBOM and signatures.
3030
- **Package managers** ([#62](https://github.com/TMHSDigital/subenum/issues/62)):
3131
Homebrew, Scoop, AUR, Nix, Kali/BlackArch.
32-
- An up-to-date **Pages site** ([#64](https://github.com/TMHSDigital/subenum/issues/64)).
3332

3433
## Later
3534

‎docs/_config.yml‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,13 @@
1-
theme: jekyll-theme-cayman
21
title: subenum
3-
description: Fast, concurrent subdomain enumeration via DNS brute-forcing - written in pure Go.
2+
description: Subdomain enumeration you can trust - every DNS query accounted for. A single static Go binary.
43
show_downloads: false
54
url: "https://tmhsdigital.github.io"
65
baseurl: "/subenum"
76
repository: TMHSDigital/subenum
7+
# Shown when a page link is shared (og:image / twitter:card).
8+
social_image: /assets/social-preview.png
9+
# Internal templates and local build output are not part of the site.
10+
exclude:
11+
- DOCUMENTATION_STRUCTURE.md
12+
- _preview
13+
- .jekyll-cache

‎docs/_includes/flags.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
<!-- Generated from subenum's flags by `make docs-flags`; do not edit. -->
2+
3+
| Flag | Default | Description |
4+
| :--- | :--- | :--- |
5+
| `-attempts <int>` | - | Total DNS resolution attempts per subdomain, 1 = no retry (default 1) |
6+
| `-dL <string>` | - | File of apex domains to scan, one per line (- for stdin); replaces the &lt;domain&gt; argument |
7+
| `-depth <int>` | 1 | Max recursion depth when -recursive is set (1 = no recursion) |
8+
| `-diff <string>` | - | Previous results file (any -format); report only names added or removed since then, and exit 4 when there are changes |
9+
| `-dns-server <string>` | 8.8.8.8:53 | DNS server to use (format: ip:port) |
10+
| `-exclude <string>` | - | Comma-separated out-of-scope names and \*.parent patterns; never queried or expanded |
11+
| `-exclude-file <string>` | - | File of out-of-scope names and \*.parent patterns, one per line (# comments allowed) |
12+
| `-force` | - | Continue scanning even if wildcard DNS is detected |
13+
| `-format <string>` | text | Output format: text, json, jsonl, or csv |
14+
| `-hit-rate <int>` | 15 | In simulation mode, percentage of names that resolve (1-100) |
15+
| `-max-queries <int>` | - | Max candidate names to test (0 = unlimited); each name sends one query per record type, per attempt |
16+
| `-no-abort` | - | Do not abort when the resolver failure rate exceeds 20% (warning is still emitted) |
17+
| `-o <string>` | - | Write results to file (in addition to stdout) |
18+
| `-progress` | true | Show progress during scanning |
19+
| `-r <string>` | - | File of resolvers (ip or ip:port, one per line) to spread queries over; every hit is re-validated against -dns-server |
20+
| `-rate <int>` | - | Max DNS queries per second on the wire, all workers combined; counts every record type, retry and wildcard probe (0 = unlimited) |
21+
| `-recursive` | - | Recursively enumerate subdomains of discovered subdomains |
22+
| `-retries <int>` | - | Deprecated: use -attempts instead |
23+
| `-seed <uint>` | - | In simulation mode, seed for reproducible results (0 = random; the seed used is printed) |
24+
| `-show-records` | - | In text format, append each result's records (TYPE=value) |
25+
| `-simulate` | - | Run in simulation mode without actual DNS queries (for testing) |
26+
| `-stats <string>` | - | Write a JSON run-quality report (outcomes, queries sent, verdict) to this file |
27+
| `-t <int>` | 100 | Number of concurrent workers |
28+
| `-timeout <int>` | 1000 | DNS lookup timeout in milliseconds |
29+
| `-tui` | - | Launch the interactive terminal UI (all other flags are ignored) |
30+
| `-type <string>` | A,AAAA | Comma-separated DNS record types to look up: A, AAAA, CNAME |
31+
| `-v` | - | Enable verbose output |
32+
| `-version` | - | Show version information |
33+
| `-w <string>` | - | Path to the wordlist file (- for stdin); omitted: the bundled top-5000 list |

‎docs/_layouts/default.html‎

Lines changed: 20 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,22 @@
55
<meta http-equiv="X-UA-Compatible" content="IE=edge">
66
<meta name="viewport" content="width=device-width, initial-scale=1">
77
<title>{% if page.title == "Home" %}{{ site.title }} - {{ site.description }}{% else %}{{ page.title }} - {{ site.title }}{% endif %}</title>
8+
{% assign page_title = site.title | append: " - " | append: site.description %}{% if page.title != "Home" %}{% assign page_title = page.title | append: " - " | append: site.title %}{% endif %}
9+
<meta name="description" content="{{ site.description }}">
10+
<link rel="canonical" href="{{ page.url | absolute_url }}">
11+
<meta property="og:type" content="website">
12+
<meta property="og:site_name" content="{{ site.title }}">
13+
<meta property="og:title" content="{{ page_title }}">
14+
<meta property="og:description" content="{{ site.description }}">
15+
<meta property="og:url" content="{{ page.url | absolute_url }}">
16+
<meta property="og:image" content="{{ site.social_image | absolute_url }}">
17+
<meta property="og:image:width" content="1200">
18+
<meta property="og:image:height" content="630">
19+
<meta property="og:image:alt" content="subenum: subdomain enumeration you can trust">
20+
<meta name="twitter:card" content="summary_large_image">
21+
<meta name="twitter:title" content="{{ page_title }}">
22+
<meta name="twitter:description" content="{{ site.description }}">
23+
<meta name="twitter:image" content="{{ site.social_image | absolute_url }}">
824
<link rel="icon" href="{{ '/assets/favicon.svg' | relative_url }}" type="image/svg+xml">
925
<link rel="preconnect" href="https://fonts.googleapis.com">
1026
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
@@ -21,6 +37,7 @@
2137
<a href="{{ '/ARCHITECTURE.html' | relative_url }}"{% if page.title == 'Architecture' %} class="active"{% endif %}>Architecture</a>
2238
<a href="{{ '/DEVELOPER_GUIDE.html' | relative_url }}"{% if page.title == 'Developer Guide' %} class="active"{% endif %}>Dev Guide</a>
2339
<a href="{{ '/docker.html' | relative_url }}"{% if page.title == 'Docker Usage' %} class="active"{% endif %}>Docker</a>
40+
<a href="{{ '/monitoring.html' | relative_url }}"{% if page.title == 'Monitoring' %} class="active"{% endif %}>Monitoring</a>
2441
</div>
2542
<a class="nav-github" href="https://github.com/TMHSDigital/subenum">GitHub</a>
2643
</nav>
@@ -33,15 +50,13 @@
3350
</div>
3451
<p class="hero-tagline">fast concurrent subdomain enumeration // written in Go</p>
3552

36-
<pre class="hero-commands">$ ./subenum -w wordlist.txt example.com
37-
$ ./subenum -tui
38-
$ ./subenum -simulate -hit-rate 20 -w examples/sample_wordlist.txt example.com</pre>
53+
<pre class="hero-commands">$ subenum -show-records -type A,AAAA,CNAME example.com</pre>
3954

40-
<div class="query-ledger" aria-label="Sample scan output">
41-
<div class="ledger-row nx"><span class="name">www.example.com</span><span class="rr">NXDOMAIN</span><span class="data"></span></div>
55+
<div class="query-ledger" aria-label="Sample scan output: only resolved names are printed">
4256
<div class="ledger-row hit"><span class="name">mail.example.com</span><span class="rr">A</span><span class="data">203.0.113.10</span></div>
4357
<div class="ledger-row hit"><span class="name">api.example.com</span><span class="rr">AAAA</span><span class="data">2001:db8::53</span></div>
4458
<div class="ledger-row hit"><span class="name">staging.example.com</span><span class="rr">CNAME</span><span class="data">api.example.com</span></div>
59+
<div class="ledger-row nx"><span class="name">old.example.com</span><span class="rr">CNAME</span><span class="data">gone.herokuapp.com TAKEOVER?=dangling:heroku</span></div>
4560
</div>
4661

4762
<div class="hero-actions">

‎docs/assets/social-preview.png‎

6.76 KB
Loading

0 commit comments

Comments
 (0)