From b1e01b09107f02c757f4e2f552ddfa7db445dd81 Mon Sep 17 00:00:00 2001 From: Asahi Arataki Date: Mon, 16 Nov 2026 23:45:04 +0800 Subject: [PATCH] docs(labs): add an IPv6-only discovery exercise --- README.md | 4 ++-- docs/labs.md | 27 +++++++++++++++++++++++++++ examples/labs/lab6-ipv6.zone | 9 +++++++++ internal/cli/lab_test.go | 15 +++++++++++++++ 4 files changed, 53 insertions(+), 2 deletions(-) create mode 100644 examples/labs/lab6-ipv6.zone diff --git a/README.md b/README.md index c688000..6c57d6a 100644 --- a/README.md +++ b/README.md @@ -72,7 +72,7 @@ Tools like [puredns](https://github.com/d3mondev/puredns), [shuffledns](https:// | **Trust the output** | Multi-probe wildcard fingerprinting · per-outcome accounting and a run-quality verdict (`-stats`) · reliability guard · retry of inconclusive names (`-retry-inconclusive`) · resumable runs (`-resume`) | | **Spot problems** | Dangling CNAME and NS takeover hints, with a provider list you can extend · internal addresses leaked into public DNS · SARIF for GitHub code scanning (`-sarif`) | | **Fit your workflow** | `text`, `json`, streaming `jsonl` and `csv` · pipe-clean stdout (`-silent`) · `-diff` monitoring and a GitHub Action · interactive TUI · Go library · MCP server for AI agents | -| **Teach and test** | `-simulate` with zero network I/O · lab scenarios served by a local DNS server (`-simulate-zone`), with [five guided exercises](docs/labs.md) | +| **Teach and test** | `-simulate` with zero network I/O · lab scenarios served by a local DNS server (`-simulate-zone`), with [six guided exercises](docs/labs.md) | ## How it works @@ -283,7 +283,7 @@ This table describes `main`, which can be ahead of the latest release: a release > 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. > [!TIP] -> 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/`. +> 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/`. ### Defaults, completions and the man page diff --git a/docs/labs.md b/docs/labs.md index d1f6770..bf34655 100644 --- a/docs/labs.md +++ b/docs/labs.md @@ -168,6 +168,33 @@ subenum $W -simulate-zone $L/lab5-failures.zone -timeout 300 -stats lab5.json la +## Lab 6: IPv6-only services + +```bash +subenum $W -simulate-zone $L/lab6-ipv6.zone -show-records lab.example +subenum $W -simulate-zone $L/lab6-ipv6.zone -type A -show-records lab.example +subenum $W -simulate-zone $L/lab6-ipv6.zone -type AAAA -show-records lab.example +``` + +1. Which three names does the default scan find, and which address families + does each have? +2. Which name disappears with `-type A`? Does that mean the service is absent? +3. Which name disappears with `-type AAAA`? Why does the default scan find both? + +
+Answers + +1. `www` has both `A=192.0.2.10` and `AAAA=2001:db8::10`; `api` has only + `AAAA=2001:db8::20`; `legacy` has only `A=192.0.2.30`. +2. `api` disappears. It exists but has no IPv4 address: an A-only lookup + cannot discover an IPv6-only service. +3. `legacy` disappears because it has no IPv6 address. The default types are + `A,AAAA`, and a record of either type is enough to report a name. Querying + both families does not require the machine to have IPv6 connectivity: + this lab's DNS server still answers on IPv4 loopback (`127.0.0.1`). + +
+ ## Writing your own scenario A scenario is a plain text file. Names are relative to the domain you scan, diff --git a/examples/labs/lab6-ipv6.zone b/examples/labs/lab6-ipv6.zone new file mode 100644 index 0000000..a029f22 --- /dev/null +++ b/examples/labs/lab6-ipv6.zone @@ -0,0 +1,9 @@ +# Lab 6: IPv6-only services. Compare A and AAAA lookups to see which +# services a scan of only one address family misses. Run: +# subenum -w examples/labs/words.txt -simulate-zone examples/labs/lab6-ipv6.zone -show-records lab.example +@ A 192.0.2.1 +@ AAAA 2001:db8::1 +www A 192.0.2.10 +www AAAA 2001:db8::10 +api AAAA 2001:db8::20 +legacy A 192.0.2.30 diff --git a/internal/cli/lab_test.go b/internal/cli/lab_test.go index 83b897e..5d55ae0 100644 --- a/internal/cli/lab_test.go +++ b/internal/cli/lab_test.go @@ -69,6 +69,21 @@ func TestE2ELabs(t *testing.T) { args: []string{"-simulate-zone", lab("lab4-recursive.zone"), "-recursive", "-depth", "3", "lab.example"}, want: []string{"admin.staging.dev", "api.dev", "corp", "dev", "git.dev", "staging.dev", "vpn.corp", "www"}, }, + { + name: "lab6 default finds both address families", + args: []string{"-simulate-zone", lab("lab6-ipv6.zone"), "lab.example"}, + want: []string{"api", "legacy", "www"}, + }, + { + name: "lab6 A misses the IPv6-only service", + args: []string{"-simulate-zone", lab("lab6-ipv6.zone"), "-type", "A", "lab.example"}, + want: []string{"legacy", "www"}, + }, + { + name: "lab6 AAAA misses the IPv4-only service", + args: []string{"-simulate-zone", lab("lab6-ipv6.zone"), "-type", "AAAA", "lab.example"}, + want: []string{"api", "www"}, + }, } for _, c := range cases { t.Run(c.name, func(t *testing.T) {