Skip to content

Commit c200b85

Browse files
TMHSDigitalclaude
andcommitted
feat(scan): mark results that resolve to internal addresses (#218)
A public name answering with a loopback, private, link-local, unspecified or CGNAT address leaks internal addressing, but results did not say so. dns.InternalScope classifies a result's A and AAAA addresses with net/netip (no new dependency) and returns the most notable scope. The scope is scan.Result.Internal: an internal_address field in JSON and JSONL, INTERNAL=<scope> in text with -show-records, a tag in the TUI, and an internal_addresses count in the breakdown and the -stats report. CSV keeps its columns, since each row already holds one address. Simulated results are never marked (their addresses are invented in 10.0.0.0/8). pkg/subenum gains Result.Internal and Stats.Internal. Fixes #218 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent b9d5528 commit c200b85

14 files changed

Lines changed: 237 additions & 3 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
88
## [Unreleased]
99

1010
### Added
11+
- Results whose addresses are not public are marked with the most notable scope: `loopback`, `unspecified`, `link-local`, `private` (RFC 1918, `fc00::/7`) or `cgnat` (`100.64.0.0/10`). A public name answering with one leaks internal addressing. The scope is an `internal_address` field in JSON and JSONL, `INTERNAL=<scope>` in text with `-show-records`, a tag in the TUI, and an `internal_addresses` count in the breakdown and the run-quality report; CSV is unchanged. Simulated results are never marked. `pkg/subenum` gains `Result.Internal` and `Stats.Internal` (#218).
1112
- `-retry-inconclusive` looks up once more, at the end of each scan, every name whose lookup timed out, was refused or failed, against `-dns-server` (never the `-r` pool). An answer replaces the first outcome in the counts, so a scan with a few dropped packets can still end `complete`; a name that resolves is reported like any other, but not expanded by `-recursive`. The pass is skipped after a reliability abort, an interrupt or once `-max-duration` runs out. `-inconclusive <file>` writes the names still without an answer, one per line, to rescan with `-w`. The report gains `retried` and `recovered` counts, and `pkg/subenum` gains `Config.RetryInconclusive` and `Stats.Retried`, `Stats.Recovered` and `Stats.Inconclusive` (#217).
1213
- Takeover hints recognize two more providers: a CNAME to `*.animaapp.io` is marked `provider:anima` and one to `*.trydiscourse.com` is marked `provider:discourse` (#134, thanks @jdotc1).
1314
- `-log-format json` writes the diagnostics on stderr (notices, warnings, errors, `-v` lines) as JSON Lines, one object per line with `time`, `level` (`error`, `warn`, `notice`, `info`, `debug`), `kind` (`message`, `scan`, `verbose`, `progress`, `simulation`, or an engine notice's category such as `wildcard` or `cap`), the `target` being scanned, the `message`, and the `settings` codes an engine message names (`["max_queries"]`). The simulation banner becomes one `simulation` notice, progress is an event with its numbers and only with an explicit `-progress`, and `-silent` keeps its meaning; results on stdout are unchanged. `SUBENUM_LOG_FORMAT` and the config file set it like any flag (#198).

‎README.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -478,6 +478,20 @@ The marker is a `takeover_candidate` field in JSON and JSONL, a `takeover_candid
478478
> [!IMPORTANT]
479479
> Takeover markers are DNS-only hints. subenum makes no HTTP requests; a `provider:` match is often a perfectly healthy service. Verify every candidate by hand, and only against targets you are authorized to test.
480480
481+
### Internal addresses
482+
483+
A public name that answers with an internal address leaks how the network behind it is laid out (and a loopback answer is a DNS rebinding building block). Every real result is checked: when one of its A or AAAA addresses is not public, the result carries the most notable scope:
484+
485+
| Scope | Addresses |
486+
|-------|-----------|
487+
| `loopback` | `127.0.0.0/8`, `::1` |
488+
| `unspecified` | `0.0.0.0`, `::` |
489+
| `link-local` | `169.254.0.0/16`, `fe80::/10` |
490+
| `private` | `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` |
491+
| `cgnat` | `100.64.0.0/10` |
492+
493+
The scope is an `internal_address` field in JSON and JSONL, `INTERNAL=<scope>` in text with `-show-records`, and a count in the breakdown and the run-quality report (`internal_addresses`). CSV is unchanged: each row already holds one address in its `value` column. Simulated results are never marked, since their addresses are invented.
494+
481495
### Run-quality report
482496

483497
Every lookup is accounted for, and subenum says how far the results can be trusted. `-stats run.json` writes a report in any format, and `-format jsonl` ends with the same object as its last line (`"type": "summary"`):

‎docs/library.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ if err != nil {
3030
// stats still hold what was gathered.
3131
}
3232
for _, r := range results {
33-
fmt.Println(r.Name, r.Records, r.Takeover)
33+
fmt.Println(r.Name, r.Records, r.Takeover, r.Internal)
3434
}
3535
```
3636

‎internal/dns/scope.go‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
package dns
2+
3+
import (
4+
"net/netip"
5+
"slices"
6+
)
7+
8+
// Address scopes that AddressScope and InternalScope report (#218). A public
9+
// name that answers with one of them leaks internal addressing.
10+
const (
11+
ScopeLoopback = "loopback" // 127.0.0.0/8, ::1
12+
ScopeUnspecified = "unspecified" // 0.0.0.0, ::
13+
ScopeLinkLocal = "link-local" // 169.254.0.0/16, fe80::/10
14+
ScopePrivate = "private" // RFC 1918, fc00::/7
15+
ScopeCGNAT = "cgnat" // 100.64.0.0/10 (RFC 6598 shared address space)
16+
)
17+
18+
var cgnatPrefix = netip.MustParsePrefix("100.64.0.0/10")
19+
20+
// scopeOrder ranks the scopes, most notable first.
21+
var scopeOrder = []string{ScopeLoopback, ScopeUnspecified, ScopeLinkLocal, ScopePrivate, ScopeCGNAT}
22+
23+
// AddressScope returns the non-public scope of an IPv4 or IPv6 address, or
24+
// "" when it is public or cannot be parsed. IPv4-mapped IPv6 addresses are
25+
// classified as the IPv4 address.
26+
func AddressScope(addr string) string {
27+
a, err := netip.ParseAddr(addr)
28+
if err != nil {
29+
return ""
30+
}
31+
a = a.Unmap()
32+
switch {
33+
case a.IsLoopback():
34+
return ScopeLoopback
35+
case a.IsUnspecified():
36+
return ScopeUnspecified
37+
case a.IsLinkLocalUnicast():
38+
return ScopeLinkLocal
39+
case a.IsPrivate():
40+
return ScopePrivate
41+
case cgnatPrefix.Contains(a):
42+
return ScopeCGNAT
43+
}
44+
return ""
45+
}
46+
47+
// InternalScope returns the most notable non-public scope among the A and
48+
// AAAA records (loopback before unspecified, link-local, private and cgnat),
49+
// or "" when every address is public.
50+
func InternalScope(records []Record) string {
51+
best := len(scopeOrder)
52+
for _, r := range records {
53+
if r.Type != "A" && r.Type != "AAAA" {
54+
continue
55+
}
56+
if i := slices.Index(scopeOrder, AddressScope(r.Value)); i >= 0 && i < best {
57+
best = i
58+
}
59+
}
60+
if best == len(scopeOrder) {
61+
return ""
62+
}
63+
return scopeOrder[best]
64+
}

‎internal/dns/scope_test.go‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
package dns
2+
3+
import "testing"
4+
5+
func TestAddressScope(t *testing.T) {
6+
for _, tc := range []struct{ addr, want string }{
7+
{"127.0.0.1", ScopeLoopback},
8+
{"127.10.0.5", ScopeLoopback},
9+
{"::1", ScopeLoopback},
10+
{"0.0.0.0", ScopeUnspecified},
11+
{"::", ScopeUnspecified},
12+
{"169.254.169.254", ScopeLinkLocal},
13+
{"fe80::1", ScopeLinkLocal},
14+
{"10.0.0.1", ScopePrivate},
15+
{"172.16.0.1", ScopePrivate},
16+
{"172.31.255.255", ScopePrivate},
17+
{"192.168.1.1", ScopePrivate},
18+
{"fd00::1", ScopePrivate},
19+
{"::ffff:192.168.1.1", ScopePrivate},
20+
{"100.64.0.1", ScopeCGNAT},
21+
{"100.127.255.255", ScopeCGNAT},
22+
{"100.128.0.1", ""},
23+
{"172.32.0.1", ""},
24+
{"8.8.8.8", ""},
25+
{"192.0.2.1", ""},
26+
{"2001:db8::1", ""},
27+
{"target.example.com", ""},
28+
{"", ""},
29+
} {
30+
if got := AddressScope(tc.addr); got != tc.want {
31+
t.Errorf("AddressScope(%q) = %q, want %q", tc.addr, got, tc.want)
32+
}
33+
}
34+
}
35+
36+
func TestInternalScope(t *testing.T) {
37+
for _, tc := range []struct {
38+
name string
39+
records []Record
40+
want string
41+
}{
42+
{"none", nil, ""},
43+
{"public", []Record{{Type: "A", Value: "192.0.2.1"}, {Type: "AAAA", Value: "2001:db8::1"}}, ""},
44+
{"private v4", []Record{{Type: "A", Value: "192.0.2.1"}, {Type: "A", Value: "10.1.2.3"}}, ScopePrivate},
45+
{"private v6", []Record{{Type: "AAAA", Value: "fd12::1"}}, ScopePrivate},
46+
{"loopback wins", []Record{{Type: "A", Value: "10.1.2.3"}, {Type: "A", Value: "127.0.0.1"}}, ScopeLoopback},
47+
{"link-local over private", []Record{{Type: "A", Value: "10.1.2.3"}, {Type: "AAAA", Value: "fe80::1"}}, ScopeLinkLocal},
48+
{"cname value ignored", []Record{{Type: "CNAME", Value: "10.0.0.1"}}, ""},
49+
} {
50+
if got := InternalScope(tc.records); got != tc.want {
51+
t.Errorf("%s: InternalScope = %q, want %q", tc.name, got, tc.want)
52+
}
53+
}
54+
}

‎internal/output/summary.go‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,9 @@ type TargetSummary struct {
7171
// (-max-queries) or "duration" (-max-duration, #190). Empty when none did.
7272
StoppedBy string `json:"stopped_by,omitempty"`
7373
Takeover int64 `json:"takeover_candidates,omitempty"` // results with a takeover hint
74+
// Internal counts results with a loopback, private, link-local,
75+
// unspecified or CGNAT address (#218).
76+
Internal int64 `json:"internal_addresses,omitempty"`
7477
// Retried counts the inconclusive names -retry-inconclusive looked up
7578
// again, and Recovered the ones that then got an answer (#217); the
7679
// outcomes already count those under their new outcome.

‎internal/output/writer.go‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -204,6 +204,9 @@ func (w *Writer) writeText(res Result) {
204204
if res.Takeover != "" {
205205
line += " TAKEOVER?=" + res.Takeover
206206
}
207+
if res.Internal != "" {
208+
line += " INTERNAL=" + res.Internal
209+
}
207210
if len(res.PreviousRecords) > 0 {
208211
line += " (was" + formatRecords(res.PreviousRecords) + ")"
209212
}

‎internal/report/report.go‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,7 @@ func target(domain, status, errMsg string, done bool, final scan.Event) output.T
9595
t.StoppedBy = "queries"
9696
}
9797
t.Takeover = st.Takeover
98+
t.Internal = st.Internal
9899
t.Retried, t.Recovered = st.Retried, st.Recovered
99100
t.PoolHits, t.Confirmed, t.Unconfirmed = st.PoolHits, st.Confirmed, st.Unconfirmed
100101
t.Wildcard = st.Wildcard

‎internal/scan/runner.go‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -137,6 +137,7 @@ type Stats struct {
137137
Confirmed int64 // pool hits the trusted resolver confirmed
138138
Unconfirmed int64 // pool hits the trusted resolver said do not exist
139139
Takeover int64 // results flagged as subdomain-takeover candidates
140+
Internal int64 // results with a non-public address (Result.Internal, #218)
140141
// RootDone is the resume point: every wordlist entry before this index
141142
// has been fully looked up (#73). Entries at or after it may also be
142143
// done; resuming repeats at most a worker pool's worth of lookups.
@@ -180,6 +181,7 @@ type counters struct {
180181
confirmed atomic.Int64
181182
unconfirmed atomic.Int64
182183
takeover atomic.Int64
184+
internal atomic.Int64
183185
rootDone atomic.Int64
184186
retried atomic.Int64
185187
recovered atomic.Int64
@@ -264,6 +266,7 @@ func (c *counters) snapshot() Stats {
264266
Confirmed: c.confirmed.Load(),
265267
Unconfirmed: c.unconfirmed.Load(),
266268
Takeover: c.takeover.Load(),
269+
Internal: c.internal.Load(),
267270
RootDone: c.rootDone.Load(),
268271
Retried: c.retried.Load(),
269272
Recovered: c.recovered.Load(),
@@ -506,6 +509,11 @@ type Result struct {
506509
// "provider:<name>" or "dangling:<name>"), see dns.TakeoverHint;
507510
// verify it by hand (#71).
508511
Takeover string `json:"takeover_candidate,omitempty"`
512+
// Internal is the most notable non-public scope among the name's
513+
// addresses ("loopback", "unspecified", "link-local", "private" or
514+
// "cgnat"), see dns.InternalScope; empty when every address is public.
515+
// A public name that answers with one leaks internal addressing (#218).
516+
Internal string `json:"internal_address,omitempty"`
509517
}
510518

511519
// Event is emitted on the events channel during a scan.
@@ -854,7 +862,15 @@ func (s *scanState) report(ctx context.Context, name string, records []dns.Recor
854862
if takeover != "" {
855863
s.stats.takeover.Add(1)
856864
}
857-
s.events <- Event{Kind: EventResult, Result: Result{Subdomain: name, Records: records, Simulated: cfg.Simulate, Takeover: takeover}}
865+
// Simulated addresses are invented (in 10.0.0.0/8), so they say nothing.
866+
internal := ""
867+
if !cfg.Simulate {
868+
internal = dns.InternalScope(records)
869+
}
870+
if internal != "" {
871+
s.stats.internal.Add(1)
872+
}
873+
s.events <- Event{Kind: EventResult, Result: Result{Subdomain: name, Records: records, Simulated: cfg.Simulate, Takeover: takeover, Internal: internal}}
858874
}
859875

860876
// retryPending is the RetryInconclusive pass (#217): once every candidate

‎internal/tui/scan_view.go‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -162,6 +162,9 @@ func (m *scanViewModel) applyEvent(ev scan.Event) {
162162
if ev.Result.Takeover != "" {
163163
line += wildcardStyle.Render(" ⚠ takeover? " + ev.Result.Takeover)
164164
}
165+
if ev.Result.Internal != "" {
166+
line += wildcardStyle.Render(" internal: " + ev.Result.Internal)
167+
}
165168
m.results = append(m.results, line)
166169
if len(m.results) > maxResultLines {
167170
// Evict in chunks so the copy cost is amortized across results.

0 commit comments

Comments
 (0)