subenum v0.11.0

Guides

Go library

pkg/subenum embeds the same engine the command line runs, so a recon pipeline or a custom tool can use it without shelling out. Wildcard filtering, rate limiting, retries, takeover hints, the reliability guard and the per-outcome accounting are all the same code.

go get github.com/TMHSDigital/subenum/pkg/subenum

The package follows semantic versioning from v1.0.0. Until then it may change between minor releases, while the CLI stays stable. The full API reference, with runnable examples, is on pkg.go.dev.

Scan: a finished run

Scan runs to completion and returns every result in the order the names resolved, plus the final Stats:

results, stats, err := subenum.Scan(ctx, subenum.Config{
    Domain: "example.com",            // URLs, ports and IDNs are normalized
    Rate:   100,                      // queries per second on the wire
    Types:  []string{"A", "AAAA", "CNAME"},
})
if err != nil {
    // Partial: cancelled, a wildcard zone without Force, a failed resolver
    // preflight, or the reliability guard stopped the scan. results and
    // stats still hold what was gathered.
}
for _, r := range results {
    fmt.Println(r.Name, r.Records, r.Takeover)
}

Takeover is a lead to check by hand: dangling, provider:<name> or dangling:<name> for a CNAME, or dangling-ns for a delegation to a name server that does not resolve. With NS in Types, a name whose lookup ends SERVFAIL (a subzone whose every name server is gone) is asked of the zone’s own name servers without recursion, and reported with dangling-ns when the name servers they delegate it to do not exist; Stats.ParentChecksunreleased and Stats.ParentQueries count those checks and their queries, which Rate paces and MaxQueries caps. Internal names the non-public scope (private, loopback, link-local, cgnat, unspecified) of an address a public name answers with, and is empty when every address is public. Sources names what proposed the result: wordlist for Words, and each source in Config.Sources that returned it, by its Name() method when it has one (ct, wayback, axfr for the built-in ones) or else as Sources[i], its index in Config.Sources.

Every zero value in Config takes the same default as the CLI, so Config{Domain: "example.com"} is a complete configuration that uses the bundled 5,000-word list.

Run: a stream of events

Run returns a channel that streams results, notices and progress as they happen. It always ends with exactly one KindDone event carrying the final Stats, and then closes:

events, err := subenum.Run(ctx, subenum.Config{Domain: "example.com"})
if err != nil {
    return err // the Config itself was invalid; no scan started
}
for ev := range events {
    switch ev.Kind {
    case subenum.KindResult:
        fmt.Println(ev.Result.Name)
    case subenum.KindNotice, subenum.KindError:
        log.Println(ev.Message)
    case subenum.KindDone:
        fmt.Printf("found %d, %d timeouts\n", ev.Stats.Found, ev.Stats.Timeout)
    }
}

Read the channel until it closes, or cancel ctx. Breaking out of the loop with a deferred cancel() is safe: once ctx is cancelled the scan stops without waiting for a reader, and its goroutines exit within about a second whether or not the channel is read. A consumer that keeps reading after cancelling still gets KindDone with the counts so far. A KindError event has Fatal set when it ends the scan (the NoAbort warning is the one that does not), and KindDone has Failed set when the scan failed, so a consumer does not have to work either out. While ctx is live, a consumer that stops reading pauses the scan once the buffer fills.

Permutations: second-pass candidates

Permutations makes the candidates the CLI’s -permute tries: from names a scan already found, the variants most likely to sit next to them (api suggests api-dev, dev-api, dev.api, api2 and so on). Seeds and results are relative to the apex, like Words, so the output feeds a second scan directly. Pass nil words for the CLI’s built-in list of environment, version and role names. It sends no DNS queries:

seeds := []string{"api", "mail"} // api.example.com and mail.example.com were found
more, _, err := subenum.Scan(ctx, subenum.Config{
    Domain: "example.com",
    Words:  subenum.Permutations(seeds, nil),
})

The result is sorted and duplicate-free, and names that are not valid in DNS are left out.

Diff: what changed since last time

Diff compares two sets of results the way the CLI’s -diff and -diff-records do: names added, names missing, and names whose records changed. Pass the record types both scans looked up. When a CNAME is involved only its target counts, so a re-pointed alias is a change and the rotating addresses behind a CDN are not. It sends no DNS queries:

changes := subenum.Diff(lastWeek, today, []string{"A", "AAAA", "CNAME"})
for _, c := range changes.Changed {
    fmt.Println(c.Name, c.Previous, "->", c.Current)
}

Removed lists previous names the new results lack, which is not proof they are gone: they may not have been candidates this time, or their lookup failed. The CLI reports a name removed only after a fresh NXDOMAIN on a complete run, so look them up again before acting on them.

ProbeZone: zone transfers

ProbeZone does what the CLI’s -axfr does before a scan, with the same code and limits. It looks up the domain’s name servers through ZoneOptions.Resolver (default 8.8.8.8:53), asks at most 8 of them, on at most 2 addresses each, for a full zone transfer (AXFR), and asks one how the zone proves a name does not exist:

info, err := subenum.ProbeZone(ctx, "example.com", subenum.ZoneOptions{})
if err != nil {
    return err // a bad domain or option, or the name server lookup failed
}
fmt.Println(info.TransferAllowed) // name servers that allowed a transfer
fmt.Println(info.Names)           // the names they gave, relative to the domain
if info.Denial == "nsec" {
    fmt.Println("plain NSEC: anyone can list the zone by walking it")
}

Most name servers refuse transfers, which is the correct configuration and not an error. Denial is nsec, nsec3, none (no DNSSEC), or empty when no name server answered the probe. To scan the transferred names, pass ZoneTransfer(opts) in Config.Sources: its names are looked up like any other, so only names that still resolve are reported.

With ZoneOptions.WalkNSEC, ProbeZone also walks a zone signed with plain NSEC, as the CLI’s -nsec-walk does, and lists its names in info.Walked; info.WalkStop says why a walk stopped early or did not run. The walk asks the name server that answered the probe, one query per name, paced by ZoneOptions.Rate and capped by ZoneOptions.MaxQueries (10,000 by default). NSECWalk(opts)unreleased is the matching Config.Sources entry: it walks without asking for a transfer, labels its results nsec, and leaves out the names Config.Exclude rules out.

These queries go to the domain’s own name servers, not to Resolver, and they are not paced by Rate, just as the CLI’s -axfr is not: at most 34 queries in all (the name server lookup, two address lookups and up to two transfers per name server, and one DNSSEC probe). ZoneOptions.Timeout (default 1s) bounds each lookup; a transfer gets at least 10 seconds.

Configuration

Field Default What it does
Domain required Apex to enumerate under.
Words DefaultWords() Labels to try, or dotted paths such as api.eu.
Resolver 8.8.8.8:53 Trusted server: ip:port, tls://host, or https://host/path.
ResolverPool none Extra plain-UDP resolvers. Every hit is re-checked against Resolver.
RatePerResolver unlimited Queries per second to each ResolverPool member. Rate still caps the total, so the stricter limit wins.
Concurrency 100 Workers looking up names at once.
Timeout 1s Bound on one lookup of one record type.
Attempts 1 Tries per name. Only failures are retried, never NXDOMAIN.
Rate unlimited Queries per second on the wire, counting every type, retry and probe.
Types A, AAAA Record types: A, AAAA, CNAME, NS, MX, TXT, SRVunreleased and HTTPSunreleased. CNAME, NS, SRV and HTTPS (an AliasMode target) populate Result.Takeover.
Recursive, Depth off, 1 Enumerate again under each name found.
MaxQueries unlimited Cap on candidate names tested.
MaxDuration unlimited Time budget from the start of Run, not counting the preflight and wildcard probes sent before the first candidate lookup, so Run can take longer. Then no new names are tested and the rest are counted in Stats.Skipped, with Stats.Expired set.
AutoRate false When over a fifth of the last 200 lookups fail, halve the rate and keep going (a NoticeRate event says so), and raise it again once lookups succeed. It halves up to six times and not below 5 per second; only when it can slow down no further does the reliability guard apply. Stats.RateBackoffs and Stats.FinalRate report it.
TakeoverProviders built-in list Extra takeover-prone services ({Suffix: ".example-cdn.net", Name: "example-cdn"}) for provider: hints, added to the built-in list; a Name of - removes a suffix. TakeoverProvidersOnly uses them alone.
RetryInconclusive false Once every candidate is tried, look up each name that timed out, was refused or failed once more against Resolver. Names it resolves are reported but not expanded by Recursive. Stats.Retried and Stats.Recovered count the pass; Stats.Inconclusive lists the names still without an answer.
Sources none Passive sources whose names are added after Words and looked up like them: CertificateTransparency(), WaybackMachine(), ZoneTransfer(opts) (see Zone transfers), or your own Source (one Names(ctx, domain) method). A source that fails sends a NoticeSource event and the scan goes on. Ignored with Simulate.
Exclude none Out-of-scope names and *.parent branches, never queried. A Domain it rules out gets no Sources lookup, and ZoneTransfer() skips the name servers it rules out.
Force off Scan a wildcard zone, dropping answers that match its fingerprint.
NoAbort off Keep going when more than a fifth of lookups fail. Run still sends the warning as a KindError event; Scan returns no error for a scan that finished.
Simulate, HitRate, Seed off, 15, random Synthetic results with no DNS traffic, for tests and demos.
Verbose, Logf off, stderr Log every lookup. Lines go to Logf, or to standard error when it is nil.

cfg.Validate() returns the configuration error Run would return without starting a scan or sending queries. Call it before Run or Scan when a form or pipeline needs to check a Config first. If the word list has no usable entries, the error matches ErrNoWords; use errors.Is(err, subenum.ErrNoWords) to identify that case.

Accounting

Stats puts each candidate name into exactly one outcome: Found, NXDomain, Timeout, Refused, Other or WildcardFiltered. Alongside are QueriesSent, Skipped (left untested by MaxQueries or MaxDuration, with Expired set for the latter), Excluded, the result counters Takeover and Internal, and the resolver-pool counters PoolHits, Confirmed and Unconfirmed. Aborted means the reliability guard stopped the scan, so the negatives mean nothing. Wildcard and WildcardFingerprint describe a wildcard zone. RetryInconclusive fills Retried, Recovered and Inconclusive (the names still without an answer), and AutoRate fills RateBackoffs and FinalRate. Total() sums the outcomes. Verdict(interrupted) applies the CLI run-quality report’s rules: VerdictComplete, VerdictDegraded or VerdictUnreliable, with the reason in plain words (naming Config fields such as MaxQueries).

Testing your integration

Set Simulate in tests and examples. It exercises the full pipeline with no DNS queries, and a fixed Seed makes the results reproducible:

results, _, err := subenum.Scan(ctx, subenum.Config{
    Domain:   "example.com",
    Words:    []string{"www", "api", "mail", "dev"},
    Simulate: true,
    HitRate:  50,
    Seed:     42,
})

Authorized use only. Only enumerate domains you own or have permission to test.