Skip to content

Commit e821702

Browse files
TMHSDigitalclaude
andcommitted
Let lab scenarios serve zone transfers, and add Lab 7 (#434)
-axfr was the one discovery feature labs could not practise: -simulate-zone refused it, because a transfer dials the zone's real name servers. axfr.Options gains Server. When set, every transfer and the denial probe go there instead of the name servers' addresses, which are still looked up. In lab mode the CLI sets it to the lab server, so -axfr is no longer refused and nothing leaves the machine. A scenario's $TRANSFER allow makes the lab server answer a transfer of the scanned domain with every name it defines; without it, or for a name below the apex, the transfer is refused. examples/labs/lab7-zone-transfer.zone and a Lab 7 section show an allowed transfer whose names come back with source axfr, and a refused one. Fixes #434 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 100b959 commit e821702

14 files changed

Lines changed: 201 additions & 18 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
1717
- `subenum report -stats run.json [-results results.jsonl] [-changes changes.jsonl] [-limit 50]` prints a run's Markdown summary: the verdict and its reason, a table of the targets, the takeover candidates, and with `-diff` the names added, removed and changed. GitLab CI, cron jobs and a terminal now get the summary the GitHub Action writes to the job page, and the Action calls it instead of building the summary with `jq`. Each list stops at `-limit` entries and ends with `...and N more`, where the Action's lists used to stop at 50 without saying how many were left out (#421).
1818
- `-follow-records` also tests the names under the target that found names' `CNAME`, `MX` and `NS` records point at, such as `lb-7.int.example.com` behind `app.example.com CNAME lb-7.int.example.com`, which no wordlist is likely to hold. Each is tested once, unless it is already a candidate, and its own records are followed in turn. Targets outside the domain or ruled out by `-exclude` are never queried. They count against `-max-queries` and `-max-duration`, their results' `sources` is `records`, the `-stats` report counts them as `records_found`, and a resumed scan queues the targets of the names it restored again. `pkg/subenum` has `Config.FollowRecords`. Off by default, so query counts do not change (#432).
1919
- `-srv` looks up a built-in list of 48 service names (`_sip._tcp`, `_autodiscover._tcp`, `_ldap._tcp`, `_xmpp-server._tcp`, ...) under each target, after the wordlist, and reports the ones with SRV records with `sources: ["srv"]`. It needs `SRV` in `-type`, so the extra query per name is a choice. The names count against `-max-queries`, `-dry-run` counts them, and they do not seed `-permute`. With `SRV` in `-type`, a service whose target host does not exist is a `dangling-srv` takeover candidate, with its own SARIF rule. The result schema's `takeover_candidate` pattern now also allows `dangling-ns`, which it wrongly rejected (#419).
20+
- Lab mode allows `-axfr`: the transfer and its DNSSEC probe go to the lab server, whatever address the scenario gives its name servers, so nothing leaves the machine. A scenario's `$TRANSFER allow` makes the lab server answer a transfer of the scanned domain with every name it defines; without it transfers are refused, as most real servers do. The new Lab 7 (`-simulate-zone lab7`) practises it: names only the transfer gives come back with source `axfr` (#434).
2021

2122
### Changed
2223
- With `-axfr` and passive sources (`-ct`, `-sources`), a target's zone transfer now runs while the sources are asked, instead of after them, so a slow crt.sh answer no longer adds the transfer's time on top. Messages and candidates come in the same order as before (#365).

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -292,7 +292,7 @@ This table describes `main`, which can be ahead of the latest release: a release
292292
| `-simulate` | `false` | Simulation mode: no real DNS queries |
293293
| `-hit-rate <n>` | `15` | Simulated resolution rate, percent (1-100), applied uniformly to every name |
294294
| `-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 |
295-
| `-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) |
295+
| `-simulate-zone <file>` | n/a | Lab mode: answer every query from a scenario file, or a built-in scenario such as `lab1` (`lab1`-`lab7`, 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) |
296296
| **Modes** | | |
297297
| `-tui` | `false` | Launch the interactive Terminal UI |
298298
| `-dry-run` | `false` | Print the plan without scanning: candidates after dedupe and `-exclude`, query and duration estimates (at `-rate`, or `-rate-per-resolver` times the `-r` pool size when that is lower), and the resolver preflight (its only DNS query, also sent once to each `-r` pool resolver, paced by `-rate` and skipped for a target `-exclude` rules out; a failing pool resolver is reported but does not fail the run), then exit; JSON with `-format json` or `jsonl` |
@@ -495,7 +495,7 @@ subenum -axfr -type A,AAAA,CNAME example.com
495495

496496
The same step asks one name server about a name that does not exist, with DNSSEC records requested. A zone signed with plain NSEC proves the absence by naming its neighbours, so anyone can walk the chain to list every name, transfer or not: subenum reports that as `Zone walkable` and records `zone_denial` (`nsec`, `nsec3` or `none`) in the report. It does not walk the zone itself.
497497

498-
The transfers and the probe go straight to the target's name servers, not through `-dns-server`: at most 8 servers and 2 addresses each, one query per address, at most 100,000 names kept (a larger zone is cut there and the cut is reported), plus the NS and address lookups and one denial probe, all counted in the report's `queries_sent` but not paced by `-rate`. Simulation ignores `-axfr`, lab mode refuses it, and a resumed scan reuses the names the interrupted run got.
498+
The transfers and the probe go straight to the target's name servers, not through `-dns-server`: at most 8 servers and 2 addresses each, one query per address, at most 100,000 names kept (a larger zone is cut there and the cut is reported), plus the NS and address lookups and one denial probe, all counted in the report's `queries_sent` but not paced by `-rate`. Simulation ignores `-axfr`, lab mode sends it to the lab server (Lab 7 practises it), and a resumed scan reuses the names the interrupted run got.
499499

500500
</details>
501501

‎docs/_data/unreleased.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ flags:
1414
# new values of a flag that is itself released, as flag=VALUE (#306)
1515
values:
1616
- type=SRV
17+
- simulate-zone=lab7
1718
# action.yml inputs and outputs
1819
action: []
1920
# pkg/subenum identifiers

‎docs/_includes/flags.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@
4242
| `-show-records` | - | In text format, append each result's records (TYPE=value) |
4343
| `-silent` | - | Pipeline mode: bare result names on stdout, and only errors (and a simulation warning) on stderr |
4444
| `-simulate` | - | Run in simulation mode without actual DNS queries (for testing) |
45-
| `-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) |
45+
| `-simulate-zone <string>` | - | Lab mode: answer every query from this scenario file, or a built-in scenario such as lab1 (lab1-lab7), via a local DNS server, so no traffic leaves the machine (see the Labs page) lab7: {% include unreleased.html value="simulate-zone=lab7" %} |
4646
| `-sources <string>` | - | 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 |
4747
| `-srv` {% include unreleased.html flag="srv" %} | - | Also look up a built-in list of about 50 service names (\_sip.\_tcp, \_autodiscover.\_tcp, \_ldap.\_tcp, ...) under each target; needs SRV in -type |
4848
| `-state <string>` | subenum-resume.json | Where a run that was interrupted, ran out of -max-duration or was aborted saves its state for -resume |

‎docs/labs.md‎

Lines changed: 37 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -201,6 +201,38 @@ subenum -simulate-zone lab6 -type AAAA -show-records lab.example
201201

202202
</details>
203203

204+
## Lab 7: a zone transfer{% include unreleased.html value="simulate-zone=lab7" %}
205+
206+
```bash
207+
subenum -simulate-zone lab7 -format jsonl lab.example
208+
subenum -simulate-zone lab7 -axfr -format jsonl lab.example
209+
```
210+
211+
The lab's name server hands its whole zone to anyone who asks, the
212+
misconfiguration `-axfr` looks for. In lab mode the transfer goes to the lab
213+
server, never to the name server's real address.
214+
215+
1. Which names does the second run find that the first does not, and what is
216+
their `sources`?
217+
2. What does the second run print on stderr about the name server?
218+
3. Copy `examples/labs/lab7-zone-transfer.zone`, delete its `$TRANSFER allow`
219+
line and run the copy with `-axfr -v`. What changes?
220+
221+
<details markdown="1">
222+
<summary>Answers</summary>
223+
224+
1. `billing-legacy`, `k8s-ingress-eu2` and `ns1`: no wordlist holds them. Their
225+
`sources` is `["axfr"]`, while `www`, `mail` and `vpn` say
226+
`["wordlist", "axfr"]`. Every transferred name is still looked up, so a
227+
stale entry would not be reported.
228+
2. That `ns1.lab.example` allowed a transfer of `lab.example` and that anyone
229+
can list the zone: a finding to report in itself. `-stats` names the
230+
server under `axfr_allowed`.
231+
3. The server refuses, as most do. The scan is the wordlist's alone, and `-v`
232+
says that no name server allowed a transfer.
233+
234+
</details>
235+
204236
## Writing your own scenario
205237

206238
A scenario is a plain text file. Names are relative to the domain you scan,
@@ -209,6 +241,7 @@ and `#` starts a comment:
209241
```text
210242
$DELAY 20ms # every answer waits this long
211243
$REFUSE-ABOVE 50 # answer REFUSED past 50 queries a second
244+
$TRANSFER allow # answer a zone transfer (-axfr); the default is refuse
212245
@ A 192.0.2.1 # the scanned domain itself
213246
www A 192.0.2.10
214247
www AAAA 2001:db8::10
@@ -241,7 +274,9 @@ lab points at a real host.
241274

242275
Scenarios work with the other flags, such as `-dL` (each listed domain gets
243276
the same zone), `-permute`, `-diff`, `-format json` and `-stats`, which
244-
records the scenario file under `zone`. `-simulate-zone` cannot be combined
245-
with `-simulate`, `-dns-server`, `-r`, `-ct`, `-sources` or `-axfr`, whether they
277+
records the scenario file under `zone`. With `-axfr`, the transfer and its
278+
DNSSEC probe go to the lab server, whatever address the scenario gives its
279+
name servers. `-simulate-zone` cannot be combined
280+
with `-simulate`, `-dns-server`, `-r`, `-ct` or `-sources`, whether they
246281
come from the command line, a `SUBENUM_*` variable or the config file: a lab run refuses to start
247282
rather than send a query off the machine.

‎docs/mcp.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -124,7 +124,7 @@ report's `zone_transfer` lists the name servers that `allowed` one (anyone
124124
can then list the zone, a finding in itself) and the zone's `denial`
125125
(`nsec` means it can be walked). Name servers under `exclude` are not asked.
126126
Without `-axfr`, a call that sets it is refused. `lab_scan` has no
127-
`zone_transfer`: the lab server does not answer transfers.
127+
`zone_transfer` yet; the command line practises transfers in Lab 7.
128128

129129
The caps cannot be turned off: `-rate`, `-max-queries`, `-max-duration`,
130130
`-timeout` and `-max-calls` must be positive. A session is one run of the
Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Lab 7: zone transfer. This zone's name server hands its whole zone to
2+
# anyone who asks, the misconfiguration -axfr looks for, and two hosts are
3+
# names no wordlist holds. Run:
4+
# subenum -simulate-zone lab7 -axfr -format jsonl lab.example
5+
# Then remove the $TRANSFER line from a copy of this file and run it again.
6+
$TRANSFER allow
7+
@ A 192.0.2.1
8+
@ NS ns1
9+
ns1 A 192.0.2.53
10+
www A 192.0.2.10
11+
mail A 192.0.2.20
12+
vpn A 192.0.2.30
13+
billing-legacy A 192.0.2.70
14+
k8s-ingress-eu2 A 10.20.0.7

‎internal/axfr/axfr.go‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,19 @@ type Options struct {
4040
// Skip, when set, reports name server hosts that are out of scope
4141
// (-exclude): they are neither resolved nor contacted (#372).
4242
Skip func(host string) bool
43+
// Server, when set ("host:port"), receives every transfer and the
44+
// denial probe in place of the name servers' addresses, which are still
45+
// looked up: a lab run sends them to its local server, so nothing leaves
46+
// the machine (#434).
47+
Server string
48+
}
49+
50+
// endpoint is where a request meant for a name server address goes.
51+
func (o Options) endpoint(addr string) string {
52+
if o.Server != "" {
53+
return o.Server
54+
}
55+
return net.JoinHostPort(addr, o.Port)
4356
}
4457

4558
// Result is what an attempt found.
@@ -63,7 +76,7 @@ func logf(f func(string, ...any), format string, args ...any) {
6376
// which is reported like an allowed transfer. A failed probe is "" so the
6477
// next address is tried.
6578
func probeDenial(ctx context.Context, o Options, host, addr, target string) dns.Denial {
66-
d, err := dns.ProbeDenial(ctx, net.JoinHostPort(addr, o.Port), target, o.Timeout)
79+
d, err := dns.ProbeDenial(ctx, o.endpoint(addr), target, o.Timeout)
6780
if err != nil {
6881
logf(o.Debug, "-axfr: DNSSEC denial probe to %s (%s): %v", host, addr, err)
6982
return ""
@@ -214,7 +227,7 @@ func (a *attempt) transfer(ctx context.Context, o Options, target string, timeou
214227
return
215228
}
216229
a.tried++
217-
got, err := dns.Transfer(ctx, net.JoinHostPort(addr, o.Port), target, timeout)
230+
got, err := dns.Transfer(ctx, o.endpoint(addr), target, timeout)
218231
if errors.Is(err, dns.ErrTransferTruncated) {
219232
a.allowed, a.got = true, got
220233
a.logf(o.Info, "Zone transfer: %s (%s) allowed AXFR of %s, but it was stopped: %v. Anyone can list this zone; restrict transfers to your secondaries.", a.host, addr, target, err)

‎internal/cli/axfr.go‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,11 @@ func zoneTransfer(ctx context.Context, f cliFlags, port, target string, saved *r
6969
if f.verbose {
7070
opts.Debug = info
7171
}
72+
if f.simZone != "" {
73+
// Lab mode: the lab server answers for every name server, so the
74+
// transfer never leaves the machine (#434).
75+
opts.Server = f.dnsServer
76+
}
7277
r := axfr.Try(ctx, target, opts)
7378
res := targetAXFR{names: r.Names, allowed: r.Allowed, tried: r.Tried, denial: r.Denial, queries: r.Queries, done: true, err: r.Err}
7479
if r.Err != "" {

‎internal/cli/axfr_test.go‎

Lines changed: 31 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -522,16 +522,41 @@ func TestZoneTransferStopsWhenCancelled(t *testing.T) {
522522
}
523523
}
524524

525-
// TestE2ELabRefusesAXFR: a transfer would go to the zone's real name
526-
// servers, so lab mode refuses -axfr; simulation ignores it with a note.
527-
func TestE2ELabRefusesAXFR(t *testing.T) {
525+
// TestE2ELabAXFR covers #434: in lab mode -axfr asks the lab server, so a
526+
// scenario with $TRANSFER allow gives its names with source axfr, and one
527+
// without it refuses the transfer. Lab 7's name server address is in
528+
// TEST-NET, which a transfer sent to it could not reach. Simulation still
529+
// ignores -axfr with a note.
530+
func TestE2ELabAXFR(t *testing.T) {
528531
t.Parallel()
529-
zone := filepath.Join("examples", "labs", "lab1-first-scan.zone")
530-
if code, out := runCLIMerged(t, "-axfr", "-simulate-zone", zone, "lab.example"); code != exitUsage || !strings.Contains(out, "-axfr") {
531-
t.Errorf("lab: exit %d\n%s", code, out)
532+
code, out := runCLIMerged(t, "-axfr", "-simulate-zone", "lab7", "-format", "jsonl", "-progress=false", "lab.example")
533+
got := seenResults(t, lastJSONLines(out))
534+
if code != exitOK || !slices.Equal(got["billing-legacy.lab.example"].Sources, []string{"axfr"}) || !strings.Contains(out, "allowed AXFR of lab.example") {
535+
t.Errorf("lab7: exit %d, results %v\n%s", code, got, out)
536+
}
537+
538+
refusing := writeFile(t, "refuse.zone", "@ NS ns1\nns1 A 192.0.2.53\nwww A 192.0.2.10\nhidden A 192.0.2.11\n")
539+
stats := filepath.Join(t.TempDir(), "run.json")
540+
code, out = runCLIMerged(t, "-axfr", "-simulate-zone", refusing, "-w", writeFile(t, "w.txt", "www\n"), "-stats", stats, "-progress=false", "lab.example")
541+
if code != exitOK || strings.Contains(out, "hidden.lab.example") || strings.Contains(out, "allowed AXFR") {
542+
t.Errorf("without $TRANSFER allow: exit %d\n%s", code, out)
543+
}
544+
if b, err := os.ReadFile(stats); err != nil || strings.Contains(string(b), "axfr_allowed") {
545+
t.Errorf("without $TRANSFER allow the report lists a server that allowed it: %s %v", b, err)
532546
}
533547
wl := writeFile(t, "wl.txt", "www\n")
534548
if code, out := runCLIMerged(t, "-axfr", "-simulate", "-seed", "1", "-progress=false", "-w", wl, "example.com"); code != 0 || !strings.Contains(out, "-axfr is ignored in simulation mode") {
535549
t.Errorf("simulate: exit %d\n%s", code, out)
536550
}
537551
}
552+
553+
// lastJSONLines keeps the lines of merged output that are JSON objects.
554+
func lastJSONLines(out string) string {
555+
var b strings.Builder
556+
for line := range strings.Lines(out) {
557+
if strings.HasPrefix(line, "{") {
558+
b.WriteString(line)
559+
}
560+
}
561+
return b.String()
562+
}

0 commit comments

Comments
 (0)