Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down
27 changes: 27 additions & 0 deletions docs/labs.md
Original file line number Diff line number Diff line change
Expand Up @@ -168,6 +168,33 @@ subenum $W -simulate-zone $L/lab5-failures.zone -timeout 300 -stats lab5.json la

</details>

## 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?

<details markdown="1">
<summary>Answers</summary>

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`).

</details>

## Writing your own scenario

A scenario is a plain text file. Names are relative to the domain you scan,
Expand Down
9 changes: 9 additions & 0 deletions examples/labs/lab6-ipv6.zone
Original file line number Diff line number Diff line change
@@ -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
15 changes: 15 additions & 0 deletions internal/cli/lab_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down
Loading