You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 70a023f
Browse filesBrowse the repository at this point in the historyBrowse files
Accept the built-in lab scenarios in -simulate-zone (#354)
Every binary embeds the lab scenarios for subenum mcp, but -simulate-zone
only opened a file, so release, container and go install users had to
clone the repository to run the labs. A value with no path separator that
is not an existing file now names a built-in scenario (lab1,
lab1-first-scan or lab1-first-scan.zone), and without -w such a run uses
the labs' embedded wordlist; -w "" still picks the bundled list. Paths
keep loading from disk, an unknown name lists the built-in scenarios, and
-resume skips the compiled-in scenario when fingerprinting input files.
The Labs page now runs every exercise as -simulate-zone labN.
Fixes#354
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Copy file name to clipboardExpand all lines: CHANGELOG.md
+1Lines changed: 1 addition & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
8
8
## [Unreleased]
9
9
10
10
### Added
11
+
-`-simulate-zone` accepts the lab scenarios built into every binary by name, so release, container and `go install` users run the labs without cloning the repository: `subenum -simulate-zone lab1 lab.example` works from any directory (`lab1`, `lab1-first-scan` and `lab1-first-scan.zone` all name it), and without `-w` the scan uses the labs' own wordlist (`-w ""` keeps the bundled 5,000-word list). A path, or a file that exists under the given name, is still read from disk, and an unknown name lists the built-in scenarios (#354).
11
12
-`pkg/subenum`: `Result.Sources` names what proposed each result, as the CLI's `sources` field does: `wordlist`, and each `Config.Sources` entry that returned it, named by a `Name()` method when it has one (`ct`, `wayback`, `axfr` for the built-in sources) or as `Sources[i]` (#273).
12
13
-`-o` can be given more than once, and a format prefix gives a file its own format: `-o names.txt -o jsonl:results.jsonl` writes bare names for the next tool and JSONL with the run-quality report in one run, where a pipeline used to scan twice or extract names with `jq`. A file without a prefix uses `-format`, as before. Every file gets the full current results, also under `-diff`; on a run stopped with state for `-resume`, only an `-o` file that is also the `-diff` file is left unchanged. The same path given twice is a usage error, and `-tui` takes the first file (#334).
13
14
- The TUI's finished screen can save the results of a scan run without an Output file: `s` asks for a path (starting from the Output file, or `subenum-<domain>` with the Format's extension), and the file is written as the Output file would have been, in the format its extension names (`.txt`, `.json`, `.jsonl`, `.csv`, otherwise the form's Format). With a filter on, only the results it shows are saved. `v` toggles each result's records under it, during or after the scan, and a text file saved while they are shown carries them, as with `-show-records`. Results past the view's 10,000 are not kept and cannot be saved (#332).
Copy file name to clipboardExpand all lines: README.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -287,7 +287,7 @@ This table describes `main`, which can be ahead of the latest release: a release
287
287
|`-simulate`|`false`| Simulation mode: no real DNS queries |
288
288
|`-hit-rate <n>`|`15`| Simulated resolution rate, percent (1-100), applied uniformly to every name |
289
289
|`-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 |
290
-
|`-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)|
290
+
|`-simulate-zone <file>`| n/a | Lab mode: answer every query from a scenario file, or a built-in scenario such as `lab1` (`lab1`-`lab6`, with their own wordlist when `-w` is not given), via a local DNS server on `127.0.0.1`; no traffic leaves the machine. See [Labs](docs/labs.md)|
291
291
|**Modes**|||
292
292
|`-tui`|`false`| Launch the interactive Terminal UI |
293
293
|`-dry-run`|`false`| Print the plan without scanning: candidates after dedupe and `-exclude`, query and duration estimates, and the resolver preflight (its only DNS query), then exit; JSON with `-format json` or `jsonl`|
@@ -303,7 +303,7 @@ This table describes `main`, which can be ahead of the latest release: a release
303
303
> 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.
304
304
305
305
> [!TIP]
306
-
> 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 six guided exercises with answers, built on the scenarios in `examples/labs/`.
306
+
> 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 six guided exercises with answers, built on the scenarios in `examples/labs/`, which every binary carries: `subenum -simulate-zone lab1 lab.example` runs the first one from any directory.
Copy file name to clipboardExpand all lines: docs/ARCHITECTURE.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -346,7 +346,7 @@ With `-ct`, `ct.Client.Names` makes one HTTPS request per target to crt.sh (no A
346
346
347
347
### 5.6. Lab Mode
348
348
349
-
`-simulate-zone <file>` loads a scenario with `labzone.Load` (exact names, records, `*.name` wildcards, and `TIMEOUT`, `SERVFAIL`, `REFUSED` or `NXDOMAIN` entries, plus `$DELAY` and `$REFUSE-ABOVE` directives), serves it with `dnsserver.Listen` on a loopback port and points `-dns-server` at it (`startLabZone`). Unlike `-simulate`, the scan then runs the real resolver, wildcard detection, `-rate` pacing and reliability guard, and no traffic leaves the machine. The same `internal/dnsserver` backs the hermetic tests through `internal/dnstest`.
349
+
`-simulate-zone <file>` loads a scenario with `labzone.Load`, or, for a name such as `lab1` that is not a file, the scenario compiled in from `examples/labs` with its wordlist as the `-w` default (`builtinLab`) (exact names, records, `*.name` wildcards, and `TIMEOUT`, `SERVFAIL`, `REFUSED` or `NXDOMAIN` entries, plus `$DELAY` and `$REFUSE-ABOVE` directives), serves it with `dnsserver.Listen` on a loopback port and points `-dns-server` at it (`startLabZone`). Unlike `-simulate`, the scan then runs the real resolver, wildcard detection, `-rate` pacing and reliability guard, and no traffic leaves the machine. The same `internal/dnsserver` backs the hermetic tests through `internal/dnstest`.
Copy file name to clipboardExpand all lines: docs/_includes/flags.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -39,7 +39,7 @@
39
39
|`-show-records`| - | In text format, append each result's records (TYPE=value) |
40
40
|`-silent`| - | Pipeline mode: bare result names on stdout, and only errors (and a simulation warning) on stderr |
41
41
|`-simulate`| - | Run in simulation mode without actual DNS queries (for testing) |
42
-
|`-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) |
42
+
|`-simulate-zone <string>`| - | Lab mode: answer every query from this scenario file, or a built-in scenario such as lab1 (lab1-lab6), via a local DNS server, so no traffic leaves the machine (see the Labs page) |
43
43
|`-sources <string>` {% include unreleased.html flag="sources" %} | - | Comma-separated keyless passive sources whose names become candidates and -permute seeds: ct (Certificate Transparency, crt.sh), wayback (Wayback Machine); one HTTPS request per source and target |
44
44
|`-state <string>`| subenum-resume.json | Where a run that was interrupted, ran out of -max-duration or was aborted saves its state for -resume |
45
45
|`-stats <string>`| - | Write a JSON run-quality report (outcomes, queries sent, verdict) to this file |
Copy file name to clipboardExpand all lines: docs/labs.md
+20-21Lines changed: 20 additions & 21 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -18,19 +18,18 @@ against a live zone, and the results are the same on every run.
18
18
19
19
## Setup
20
20
21
-
You need a subenum binary (see [Installation](https://github.com/TMHSDigital/subenum#installation))
22
-
and a copy of the repository for the scenario files. For a zero-install
23
-
classroom, [open the labs in GitHub Codespaces](https://codespaces.new/TMHSDigital/subenum?devcontainer_path=.devcontainer/labs/devcontainer.json&quickstart=1):
21
+
You need a subenum binary (see [Installation](https://github.com/TMHSDigital/subenum#installation)).
22
+
The scenarios and their wordlist are built into it, so the labs run from any
23
+
directory: `-simulate-zone lab1` (or `lab1-first-scan`) picks the built-in
24
+
scenario, and without `-w` the scan uses the labs' short wordlist. For a
25
+
zero-install classroom, [open the labs in GitHub Codespaces](https://codespaces.new/TMHSDigital/subenum?devcontainer_path=.devcontainer/labs/devcontainer.json&quickstart=1):
24
26
the container builds `./subenum`, opens this page and the first scenario, and
25
27
prints the lab 1 command.
26
28
27
-
Every lab scans `lab.example` with the short wordlist `examples/labs/words.txt`.
28
-
Run the commands from the repository root:
29
-
30
-
```bash
31
-
L=examples/labs
32
-
W="-w $L/words.txt"
33
-
```
29
+
Every lab scans `lab.example`. To edit a scenario or write your own, copy one
30
+
from [`examples/labs`](https://github.com/TMHSDigital/subenum/tree/main/examples/labs)
31
+
and pass its path instead, for example `-simulate-zone ./my-lab.zone`; a path
32
+
uses the bundled 5,000-word list unless you add `-w`.
34
33
35
34
Labs run from the command line. Combining `-tui` with an active `-simulate-zone`
36
35
setting (including `SUBENUM_SIMULATE_ZONE` or a config-file value) exits with
@@ -41,7 +40,7 @@ Each lab ends with questions. The answers are folded underneath; try first.
fs.BoolVar(&f.testMode, "simulate", false, "Run in simulation mode without actual DNS queries (for testing)")
232
232
fs.IntVar(&f.testHitRate, "hit-rate", scan.DefaultHitRate, "In simulation mode, percentage of names that resolve (1-100)")
233
233
fs.Uint64Var(&f.seed, "seed", 0, "In simulation mode, seed for reproducible results (0 = random; the seed used is printed)")
234
-
fs.StringVar(&f.simZone, "simulate-zone", "", "Lab mode: answer every query from this scenario file via a local DNS server, so no traffic leaves the machine (see the Labs page)")
234
+
fs.StringVar(&f.simZone, "simulate-zone", "", "Lab mode: answer every query from this scenario file, or a built-in scenario such as lab1 (lab1-lab6), via a local DNS server, so no traffic leaves the machine (see the Labs page)")
235
235
fs.Var(&f.outputs, "o", "Write results to `file` (in addition to stdout); repeat for several files, each in -format or in the format named as a prefix, format:path (jsonl:results.jsonl)")
236
236
fs.IntVar(&f.attempts, "attempts", 0, "Total DNS resolution attempts per subdomain, 1 = no retry (default 1)")
237
237
fs.IntVar(&f.retries, "retries", 0, "Deprecated: use -attempts instead")
0 commit comments