Skip to content

Commit d3274f1

Browse files
TMHSDigitalclaude
andcommitted
feat: lab mode (-simulate-zone) and a Labs docs page
-simulate-zone <file> loads a scenario (names, A/AAAA/CNAME records, wildcards, TIMEOUT/SERVFAIL/REFUSED/NXDOMAIN failures, $DELAY and $REFUSE-ABOVE) and serves it from a DNS server on 127.0.0.1 for the length of the scan. Unlike -simulate, the real resolver, wildcard detection, -rate, takeover hints and the run-quality report all run, deterministically and without traffic leaving the machine. The report gains a "zone" field. The scriptable DNS server moves from internal/dnstest to a new internal/dnsserver package (Listen/Close, ListenTLS) so the binary does not import "testing"; dnstest keeps its API as a thin test wrapper. docs/labs.md has five guided exercises with answers (first scan, wildcard, rate limits, recursion, failures), backed by examples/labs/*.zone and end-to-end tests that check every answer. Fixes #76 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent e96a3d9 commit d3274f1

25 files changed

Lines changed: 1042 additions & 57 deletions

‎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+
- Lab mode: `-simulate-zone <file>` answers every query from a scenario file (names, A/AAAA/CNAME records, wildcards, TIMEOUT/SERVFAIL/REFUSED/NXDOMAIN failures, `$DELAY` and `$REFUSE-ABOVE` rate limiting) through a DNS server on `127.0.0.1`. The real resolver, wildcard detection, `-rate`, takeover hints and the run-quality report run unchanged, deterministically and without traffic leaving the machine. A new [Labs](docs/labs.md) page has five guided exercises with answers, and the scenarios ship in `examples/labs/`. The run-quality report gains a `zone` field (#76).
1112
- Contributor experience: a devcontainer (Go 1.26 plus the CI golangci-lint) with an "Open in Codespaces" badge, YAML issue forms with blank issues disabled and contact links to private vulnerability reporting and Discussions, `FUNDING.yml` and `CITATION.cff` (#75).
1213
- Encrypted DNS transports: `-dns-server tls://host[:853]` (DNS over TLS, with pooled connections) and `-dns-server https://host/path` (DNS over HTTPS, RFC 8484, keep-alive and HTTP/2). Records, outcome classification (including REFUSED and timeouts) and `-rate` accounting are identical to UDP, and the run-quality report gains a `transport` field (#86).
1314
- Resumable scans: an interrupted run (Ctrl+C, SIGTERM) saves its state to `subenum-resume.json` (or `-state <file>`), and `subenum -resume <file>` replays the original command line, checks the input files are unchanged, restores the earlier results and continues from the first wordlist entry not yet fully looked up. The scan engine tracks that low-water mark exactly even though workers finish out of order, so at most a worker pool's worth of lookups is repeated (#73).

‎README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -277,6 +277,7 @@ make help # list all targets
277277
| `-simulate` | `false` | Simulation mode: no real DNS queries |
278278
| `-hit-rate <n>` | `15` | Simulated resolution rate, percent (1-100), applied uniformly to every name |
279279
| `-seed <n>` | `0` | Simulation seed; the same seed reproduces the same results (line order can vary unless `-t 1`). `0` picks a random seed and prints it |
280+
| `-simulate-zone <file>` | n/a | Lab mode: answer every query from a scenario file via a local DNS server on `127.0.0.1`; no traffic leaves the machine. See [Labs](docs/labs.md) |
280281
| `-diff <file>` | n/a | Compare with a previous results file (any format): print only names added (`+`) or removed (`-`), exit `4` when anything changed. See [Monitoring](docs/monitoring.md) |
281282
| `-r <file>` | n/a | Resolver pool: one `ip` or `ip:port` per line. Lookups rotate over the healthy resolvers (a resolver failing over half its recent lookups is benched for 30s), retries go to a different resolver, and every hit is re-validated against `-dns-server`, whose answer is the one reported. Preflight and wildcard checks use `-dns-server` |
282283
| `-exclude <list>` | n/a | Comma-separated out-of-scope names: exact (`vpn.example.com`) or `*.parent` (every name below `parent`, not `parent` itself). Excluded names are never queried, probed or expanded, and are counted as `excluded` |
@@ -294,6 +295,9 @@ make help # list all targets
294295
> [!CAUTION]
295296
> Simulation mode (`-simulate`) generates synthetic results and performs zero network I/O. Do not confuse simulated output with real DNS data. Simulated output marks itself: JSON and JSONL results carry `"simulated": true`, CSV gets a `simulated` column, and `-o` text files start with a `# SIMULATED` comment line. Bare names piped to stdout stay unmarked so they still pipe cleanly.
296297
298+
> [!TIP]
299+
> For teaching, `-simulate-zone lab.zone` goes further than `-simulate`: a scenario file defines exact names, records, wildcards, failures and resolver rate limits, and a DNS server on `127.0.0.1` answers from it. The real resolver, wildcard filtering, `-rate` and the run-quality report all run unchanged, deterministically and with no traffic leaving the machine. [docs/labs.md](docs/labs.md) has five guided exercises with answers, built on the scenarios in `examples/labs/`.
300+
297301
<br>
298302

299303
---

‎docs/DEVELOPER_GUIDE.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -88,8 +88,12 @@ subenum/
8888
│ ├── sample_wordlist.txt # 50-entry starter wordlist
8989
│ ├── sample_domains.txt # Sample domain list for -dL
9090
│ ├── advanced_usage.md # Scripting and integration patterns
91-
│ └── demo.sh # Quick demo script
91+
│ ├── demo.sh # Quick demo script
92+
│ └── labs/ # -simulate-zone scenarios and wordlist for docs/labs.md
9293
├── internal/
94+
│ ├── dnsserver/ # Scriptable loopback DNS server (UDP, TCP, DoT, DoH)
95+
│ ├── dnstest/ # dnsserver for tests: stops on cleanup, fails the test on error
96+
│ ├── labzone/ # -simulate-zone scenario parser and answer logic
9397
│ ├── dns/
9498
│ │ ├── resolver.go # NewResolver, ResolveTypes, ResolveDomainWithRetry, Classify,
9599
│ │ │ # CheckWildcard, FingerprintWildcard, ParseTypes

‎docs/ROADMAP.md‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -34,9 +34,7 @@ Ideas we want, with no date attached.
3434

3535
- A stable Go library API, `pkg/subenum` ([#77](https://github.com/TMHSDigital/subenum/issues/77)).
3636
- Try AXFR and detect NSEC-walkable zones before brute-forcing ([#85](https://github.com/TMHSDigital/subenum/issues/85)).
37-
- A teaching / lab mode built on `-simulate` and the TUI ([#76](https://github.com/TMHSDigital/subenum/issues/76)).
38-
- Community and discoverability: Discussions, devcontainer, demo GIF, launch posts
39-
([#75](https://github.com/TMHSDigital/subenum/issues/75), [#74](https://github.com/TMHSDigital/subenum/issues/74)).
37+
- Discoverability: demo GIF and launch posts ([#74](https://github.com/TMHSDigital/subenum/issues/74)).
4038

4139
## What 1.0 means
4240

‎docs/_includes/flags.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@
2727
| `-seeds <string>` | - | Results file (any -format) whose names also seed -permute; implies -permute |
2828
| `-show-records` | - | In text format, append each result's records (TYPE=value) |
2929
| `-simulate` | - | Run in simulation mode without actual DNS queries (for testing) |
30+
| `-simulate-zone <string>` | - | Lab mode: answer every query from this scenario file via a local DNS server, so no traffic leaves the machine (see the Labs page) |
3031
| `-state <string>` | subenum-resume.json | Where an interrupted run saves its state for -resume |
3132
| `-stats <string>` | - | Write a JSON run-quality report (outcomes, queries sent, verdict) to this file |
3233
| `-t <int>` | 100 | Number of concurrent workers |

‎docs/_includes/page-nav.html‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,5 +4,6 @@
44
<a href="{{ '/DEVELOPER_GUIDE.html' | relative_url }}">Developer Guide</a>
55
<a href="{{ '/docker.html' | relative_url }}">Docker</a>
66
<a href="{{ '/monitoring.html' | relative_url }}">Monitoring</a>
7+
<a href="{{ '/labs.html' | relative_url }}">Labs</a>
78
<a href="{{ '/CONTRIBUTING.html' | relative_url }}">Contributing</a>
89
</div>

‎docs/_layouts/default.html‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@
3838
<a href="{{ '/DEVELOPER_GUIDE.html' | relative_url }}"{% if page.title == 'Developer Guide' %} class="active"{% endif %}>Dev Guide</a>
3939
<a href="{{ '/docker.html' | relative_url }}"{% if page.title == 'Docker Usage' %} class="active"{% endif %}>Docker</a>
4040
<a href="{{ '/monitoring.html' | relative_url }}"{% if page.title == 'Monitoring' %} class="active"{% endif %}>Monitoring</a>
41+
<a href="{{ '/labs.html' | relative_url }}"{% if page.title == 'Labs' %} class="active"{% endif %}>Labs</a>
4142
</div>
4243
<a class="nav-github" href="https://github.com/TMHSDigital/subenum">GitHub</a>
4344
</nav>

‎docs/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -112,6 +112,7 @@ Exit codes: `0` success, `1` failure, `2` invalid arguments, `3` some `-dL` targ
112112
<a href="DEVELOPER_GUIDE.html">Developer Guide</a>
113113
<a href="docker.html">Docker</a>
114114
<a href="monitoring.html">Monitoring</a>
115+
<a href="labs.html">Labs</a>
115116
<a href="CONTRIBUTING.html">Contributing</a>
116117
<a href="ROADMAP.html">Roadmap</a>
117118
<a href="https://github.com/TMHSDigital/subenum/blob/main/examples/advanced_usage.md">Advanced Usage</a>

‎docs/labs.md‎

Lines changed: 197 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
---
2+
layout: default
3+
title: Labs
4+
---
5+
6+
# Labs: DNS enumeration without touching real infrastructure
7+
8+
These exercises teach subdomain enumeration on fictional zones. `-simulate-zone`
9+
loads a scenario file and answers every query from a DNS server that subenum
10+
runs on `127.0.0.1` for the length of the scan. **No DNS traffic leaves your
11+
machine**, so labs are safe in a classroom, a CTF or an air-gapped VM.
12+
13+
Unlike `-simulate`, which invents results from a hit rate, a lab runs the real
14+
resolver against the scenario. Wildcard detection, `-rate` pacing, retries, the
15+
reliability guard and the run-quality report all behave exactly as they would
16+
against a live zone, and the results are the same on every run.
17+
18+
## Setup
19+
20+
You need a subenum binary (see [Installation](https://github.com/TMHSDigital/subenum#installation))
21+
and a copy of the repository for the scenario files. For a zero-install
22+
classroom, [open the repository in GitHub Codespaces](https://codespaces.new/TMHSDigital/subenum):
23+
the container builds `./subenum` for you.
24+
25+
Every lab scans `lab.example` with the short wordlist `examples/labs/words.txt`.
26+
Run the commands from the repository root:
27+
28+
```bash
29+
L=examples/labs
30+
W="-w $L/words.txt"
31+
```
32+
33+
Each lab ends with questions. The answers are folded underneath; try first.
34+
35+
## Lab 1: a first scan
36+
37+
```bash
38+
subenum $W -simulate-zone $L/lab1-first-scan.zone -show-records lab.example
39+
```
40+
41+
`-show-records` prints the records behind each name.
42+
43+
1. How many subdomains did the scan find?
44+
2. Which host has an IPv6 address?
45+
3. `shop` has the same address as `www`. Why?
46+
4. The scenario file defines `blog`, but it is not in the results. Rerun with
47+
`-type A,AAAA,CNAME`. What is `blog`, and why did the default scan miss it?
48+
49+
<details markdown="1">
50+
<summary>Answers</summary>
51+
52+
1. Five: `www`, `mail`, `vpn`, `jenkins` and `shop`.
53+
2. `www` (`2001:db8::10`).
54+
3. `shop` is a CNAME (an alias) for `www`. The resolver follows the alias and
55+
returns `www`'s addresses. The CNAME run shows `CNAME=www.lab.example`.
56+
4. `blog` is a CNAME to `ghost-lab.example.net`, a host that does not exist.
57+
The default lookups (A and AAAA) find no address, so the name looks empty.
58+
With CNAME lookups, subenum shows the alias and flags it
59+
`TAKEOVER?=dangling`: the alias points at a name nobody has registered. If
60+
that were a cloud service, whoever claimed the name would control
61+
`blog.lab.example`. This is how subdomain takeovers start. See
62+
[takeover hints](https://github.com/TMHSDigital/subenum#subdomain-takeover-hints)
63+
in the README.
64+
65+
</details>
66+
67+
## Lab 2: spot the wildcard
68+
69+
```bash
70+
subenum $W -simulate-zone $L/lab2-wildcard.zone lab.example
71+
```
72+
73+
1. What does subenum report, and why does it refuse to continue?
74+
2. Rerun with `-force`. Which names are reported now, and how does subenum tell
75+
them apart from the wildcard?
76+
77+
<details markdown="1">
78+
<summary>Answers</summary>
79+
80+
1. "Wildcard DNS detected": the zone has a `*` record, so every name, even a
81+
random one, resolves to `192.0.2.250`. Without filtering, every word in the
82+
list would be reported as a "finding".
83+
2. `www`, `portal` and `intranet`. Before scanning, subenum queries several
84+
random names to fingerprint the wildcard's answer. With `-force` it then
85+
drops every result that matches that fingerprint; these three have their
86+
own addresses, so they are real hosts. The `wildcard-filtered` line counts
87+
the rest.
88+
89+
</details>
90+
91+
## Lab 3: rate limits
92+
93+
This resolver answers REFUSED once it gets more than 40 queries in a second,
94+
as many public and corporate resolvers do.
95+
96+
```bash
97+
subenum $W -simulate-zone $L/lab3-rate-limit.zone -stats lab3.json lab.example
98+
subenum $W -simulate-zone $L/lab3-rate-limit.zone -stats lab3-paced.json -rate 30 lab.example
99+
```
100+
101+
1. Compare the `refused` counts of the two runs.
102+
2. Open both `-stats` reports. What is each run's `verdict`?
103+
3. Why can the first run still list some real names, and why should you not
104+
trust it anyway?
105+
106+
<details markdown="1">
107+
<summary>Answers</summary>
108+
109+
1. The first run bursts with 100 workers and most of its lookups are refused.
110+
The paced run (`-rate 30`, under the resolver's 40-per-second limit) has
111+
none.
112+
2. `unreliable` for the burst, `complete` for the paced run.
113+
3. The first queries arrived before the limit kicked in, so whatever they
114+
found is real. But a REFUSED name was never actually checked: it might
115+
exist. A run with many refusals says nothing about the names it missed,
116+
which is why the report calls it unreliable. Slower is faster here.
117+
118+
</details>
119+
120+
## Lab 4: recursive discovery
121+
122+
```bash
123+
subenum $W -simulate-zone $L/lab4-recursive.zone lab.example
124+
subenum $W -simulate-zone $L/lab4-recursive.zone -recursive -depth 3 lab.example
125+
```
126+
127+
1. How many names does the flat scan find? How many does the recursive scan
128+
find?
129+
2. Which name needed `-depth 3`?
130+
3. Try the recursive scan with the bundled 5,000-word list (drop `$W`). What
131+
happens, and why?
132+
133+
<details markdown="1">
134+
<summary>Answers</summary>
135+
136+
1. Three (`www`, `dev`, `corp`) against eight. Recursion takes every name it
137+
finds and enumerates the wordlist under it, which turns up `api.dev`,
138+
`git.dev`, `staging.dev` and `vpn.corp`, then `admin.staging.dev`.
139+
2. `admin.staging.dev`, three labels below `lab.example`.
140+
3. subenum refuses to start: with 5,000 words, depth 3 could mean over 100
141+
billion queries. Recursion multiplies the wordlist at every level, so it
142+
asks you to set `-max-queries` (or `-force`) first. Against a real target,
143+
that guard is what keeps a scan from becoming a flood.
144+
145+
</details>
146+
147+
## Lab 5: when lookups fail
148+
149+
```bash
150+
subenum $W -simulate-zone $L/lab5-failures.zone -timeout 300 -stats lab5.json lab.example
151+
```
152+
153+
1. Which outcome lines in the breakdown are non-zero besides `resolved` and
154+
`nxdomain`?
155+
2. What is the run's `verdict` in `lab5.json`, and what does it mean for the
156+
names that failed?
157+
158+
<details markdown="1">
159+
<summary>Answers</summary>
160+
161+
1. `timeout` (`legacy` and `old` never answer), `refused` (`beta`) and `other`
162+
(`backup` answers SERVFAIL).
163+
2. `degraded`: the scan finished, but some names could not be checked. A
164+
failed lookup is not "does not exist". Those names need a retry
165+
(`-attempts`) or a different resolver before you can rule them out.
166+
167+
</details>
168+
169+
## Writing your own scenario
170+
171+
A scenario is a plain text file. Names are relative to the domain you scan,
172+
and `#` starts a comment:
173+
174+
```text
175+
$DELAY 20ms # every answer waits this long
176+
$REFUSE-ABOVE 50 # answer REFUSED past 50 queries a second
177+
@ A 192.0.2.1 # the scanned domain itself
178+
www A 192.0.2.10
179+
www AAAA 2001:db8::10
180+
shop CNAME www # relative target
181+
blog CNAME ghost.example.net. # absolute target (trailing dot)
182+
*.dev A 192.0.2.99 # wildcard under dev
183+
slow TIMEOUT # never answered
184+
broken SERVFAIL # also: REFUSED, NXDOMAIN
185+
```
186+
187+
Names the file does not define are NXDOMAIN. The scenario is the whole world
188+
during a lab, so names outside the scanned domain (such as an external CNAME
189+
target) are NXDOMAIN too. Use the
190+
documentation ranges (`192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`,
191+
`2001:db8::/32`) and reserved names such as `lab.example`, so nothing in a
192+
lab points at a real host.
193+
194+
Scenarios work with every other flag, such as `-dL` (each listed domain gets
195+
the same zone), `-permute`, `-diff`, `-format json` and `-stats`, which
196+
records the scenario file under `zone`. `-simulate-zone` cannot be combined
197+
with `-simulate`, `-dns-server` or `-r`.

‎examples/labs/lab1-first-scan.zone‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Lab 1: first scan. Run:
2+
# subenum -simulate-zone examples/labs/lab1-first-scan.zone -show-records lab.example
3+
@ A 192.0.2.1
4+
www A 192.0.2.10
5+
www AAAA 2001:db8::10
6+
mail A 192.0.2.20
7+
vpn A 192.0.2.30
8+
jenkins A 192.0.2.40
9+
shop CNAME www
10+
blog CNAME ghost-lab.example.net.

0 commit comments

Comments
 (0)