Skip to content

Commit 2f372fa

Browse files
authored
docs(labs): add an IPv6-only discovery exercise (#389)
1 parent 42f8b87 commit 2f372fa

4 files changed

Lines changed: 53 additions & 2 deletions

File tree

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@ Tools like [puredns](https://github.com/d3mondev/puredns), [shuffledns](https://
7272
| **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`) |
7373
| **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`) |
7474
| **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 |
75-
| **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) |
75+
| **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) |
7676

7777
## How it works
7878

@@ -283,7 +283,7 @@ This table describes `main`, which can be ahead of the latest release: a release
283283
> 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.
284284
285285
> [!TIP]
286-
> 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/`.
286+
> 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/`.
287287
288288
### Defaults, completions and the man page
289289

‎docs/labs.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -168,6 +168,33 @@ subenum $W -simulate-zone $L/lab5-failures.zone -timeout 300 -stats lab5.json la
168168

169169
</details>
170170

171+
## Lab 6: IPv6-only services
172+
173+
```bash
174+
subenum $W -simulate-zone $L/lab6-ipv6.zone -show-records lab.example
175+
subenum $W -simulate-zone $L/lab6-ipv6.zone -type A -show-records lab.example
176+
subenum $W -simulate-zone $L/lab6-ipv6.zone -type AAAA -show-records lab.example
177+
```
178+
179+
1. Which three names does the default scan find, and which address families
180+
does each have?
181+
2. Which name disappears with `-type A`? Does that mean the service is absent?
182+
3. Which name disappears with `-type AAAA`? Why does the default scan find both?
183+
184+
<details markdown="1">
185+
<summary>Answers</summary>
186+
187+
1. `www` has both `A=192.0.2.10` and `AAAA=2001:db8::10`; `api` has only
188+
`AAAA=2001:db8::20`; `legacy` has only `A=192.0.2.30`.
189+
2. `api` disappears. It exists but has no IPv4 address: an A-only lookup
190+
cannot discover an IPv6-only service.
191+
3. `legacy` disappears because it has no IPv6 address. The default types are
192+
`A,AAAA`, and a record of either type is enough to report a name. Querying
193+
both families does not require the machine to have IPv6 connectivity:
194+
this lab's DNS server still answers on IPv4 loopback (`127.0.0.1`).
195+
196+
</details>
197+
171198
## Writing your own scenario
172199

173200
A scenario is a plain text file. Names are relative to the domain you scan,

‎examples/labs/lab6-ipv6.zone‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Lab 6: IPv6-only services. Compare A and AAAA lookups to see which
2+
# services a scan of only one address family misses. Run:
3+
# subenum -w examples/labs/words.txt -simulate-zone examples/labs/lab6-ipv6.zone -show-records lab.example
4+
@ A 192.0.2.1
5+
@ AAAA 2001:db8::1
6+
www A 192.0.2.10
7+
www AAAA 2001:db8::10
8+
api AAAA 2001:db8::20
9+
legacy A 192.0.2.30

‎internal/cli/lab_test.go‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,21 @@ func TestE2ELabs(t *testing.T) {
6969
args: []string{"-simulate-zone", lab("lab4-recursive.zone"), "-recursive", "-depth", "3", "lab.example"},
7070
want: []string{"admin.staging.dev", "api.dev", "corp", "dev", "git.dev", "staging.dev", "vpn.corp", "www"},
7171
},
72+
{
73+
name: "lab6 default finds both address families",
74+
args: []string{"-simulate-zone", lab("lab6-ipv6.zone"), "lab.example"},
75+
want: []string{"api", "legacy", "www"},
76+
},
77+
{
78+
name: "lab6 A misses the IPv6-only service",
79+
args: []string{"-simulate-zone", lab("lab6-ipv6.zone"), "-type", "A", "lab.example"},
80+
want: []string{"legacy", "www"},
81+
},
82+
{
83+
name: "lab6 AAAA misses the IPv4-only service",
84+
args: []string{"-simulate-zone", lab("lab6-ipv6.zone"), "-type", "AAAA", "lab.example"},
85+
want: []string{"api", "www"},
86+
},
7287
}
7388
for _, c := range cases {
7489
t.Run(c.name, func(t *testing.T) {

0 commit comments

Comments
 (0)