subfinder is a fast, modular subdomain discovery tool from projectdiscovery that harvests valid subdomains from passive online sources for authorized penetration tests and bug bounty work.

subfinder is the flagship subdomain discovery tool from the projectdiscovery team, a group that has effectively built the modern open-source reconnaissance toolkit. With roughly 14.4k stars on GitHub, an MIT license, and a codebase written in Go, it sits alongside nuclei and httpx as one of the de facto standards in external reconnaissance. The project's stated philosophy is deliberately narrow: it is built for doing one thing only — passive subdomain enumeration — and the README repeats that constraint as a feature rather than a limitation. That single-purpose discipline is worth appreciating, because it is exactly what makes subfinder reliable as a composable stage in a larger pipeline rather than a monolithic scanner that tries to do everything poorly.

The core mechanism is passive source aggregation. Instead of sending DNS queries or HTTP requests directly at the target domain, subfinder queries a curated set of online data sources — certificate transparency logs, search APIs, and OSINT datasets — that have already observed subdomains passively. The README emphasizes that the team has made it comply with all of the used passive sources' licenses and usage restrictions, which is a meaningful engineering commitment; it means the tool respects per-provider terms and rate limits rather than scraping indiscriminately. The result is enumeration that is both fast and stealthy from the target's perspective, since the target organization's own infrastructure observes nothing at all during the collection phase.

Architecturally, the README describes a simple, modular design optimized for speed. Each passive source is implemented as an independent module, and you can inspect and control them granularly. The -ls flag lists all available sources, -s restricts enumeration to specific ones (the README's example is -s crtsh,github), and -es excludes sources you do not want to touch, such as -es alienvault,zoomeyeapi. The -recursive flag limits the run to sources capable of handling nested subdomains like subdomain.domain.tld rather than just the apex. This source-level granularity matters operationally: when a provider is down, rate-limited, or out of API credits, you can surgically disable it instead of watching the whole run degrade.

Input handling is straightforward and pipeline-friendly. Domains come in either via -d for one or more targets or via -dL pointing at a file containing a list of domains, with -oD directing per-domain output into a directory when batching. The -all flag widens the run to every available source at the cost of speed, which the README candidly labels as slow. There is also -mr (-max-results) to cap results per source, honored by paginating sources, which is a useful throttle when a provider like a certificate log aggregator would otherwise return enormous result sets for a large apex domain.

Filtering and rate limiting are where the tool shows its production maturity. The -m/-match and -f/-filter flags accept comma-separated lists or files of subdomains, letting you scope results precisely — invaluable in bug bounty contexts where only certain patterns are in scope. On the throttling side, -rl sets a global maximum of HTTP requests per second toward passive sources, while the more granular -rls accepts per-provider limits in key=value form, with the README giving the example -rls "hackertarget=10/s,shodan=15/s". This per-provider awareness is what keeps subfinder inside the good graces of the free API tiers that most independent researchers rely on.

Output is equally composable. Beyond plain text to stdout or -o to a file, the -oJ flag emits JSONL — one JSON object per line — which is the lingua franca of the projectdiscovery ecosystem and makes it trivial to pipe results into httpx, dnsx, or nuclei. The -cs flag (-collect-sources) enriches that JSON with the source attribution for each discovered host, which is excellent for auditability: you can show exactly which passive source produced a given finding. When combined with -nW (-active), the tool will resolve discovered names and -oI will attach the host IP to output — note that -active is the one mode that does generate observable DNS resolution traffic, and the concurrency of that resolution is controlled by the -t flag, defaulting to 10 goroutines.

Configuration lives in config.yaml and provider-config.yaml, by default under $CONFIG/subfinder/, with the paths overridable via the SUBFINDER_CONFIG and SUBFINDER_PROVIDER_CONFIG environment variables. The README is upfront that while the tool runs immediately after installation, many passive sources require API keys configured post-install to function fully. This is honest and worth internalizing: a bare subfinder install with no provider configuration will underperform dramatically compared to one with a populated provider-config.yaml, so budgeting time for API key signup across sources like crtsh, shodan, and others is part of real-world setup, not an optional extra.

Installation requires go1.26 and follows the standard one-liner: go install -v github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest. Invocation is similarly minimal — subfinder -h displays the full flag surface reproduced in the README, and a basic run is as simple as subfinder -d example[.]com. The README also points at additional installation methods in the projectdiscovery documentation, and the tool self-updates via -up unless disabled with -duc. For teams embedding reconnaissance into Go applications rather than shell pipelines, subfinder doubles as an SDK, with a minimal usage example shipped in examples/main.go — a design choice that reflects how deeply it has been absorbed into other tooling across the ecosystem.

From a defensive standpoint, subfinder is just as interesting read in reverse. Blue teams and attack-surface management programs can use it to enumerate their own organization's externally visible subdomains and reconcile them against asset inventories, surfacing forgotten development hosts, shadow IT, and stale DNS entries that attackers would find through the same passive sources. Its own telemetry footprint on the target is effectively zero in passive mode — the queries hit third-party aggregators, not the target — so defenders should understand that the absence of reconnaissance traffic in their logs does not mean enumeration has not happened. Certificate transparency monitoring and periodic self-enumeration are the practical countermeasures.

The engineering details scattered through the flag reference reward close reading. The -timeout default of 30 seconds per source, -max-time capping a full enumeration at 10 minutes, and -rsr limiting how many bytes of response body are read from passive sources all indicate a tool hardened against the pathological cases of querying flaky external APIs at scale. Proxy support via -proxy, custom resolver lists via -r and -rL, and -ei to exclude IPs from domain results round out a configuration surface clearly shaped by real operational use rather than feature-list padding.

Community-wise, the project carries the hacktoberfest topic, welcomes contributions, maintains a THANKS.md crediting contributors, and runs an active Discord alongside projectdiscovery's other tools. It is licensed under MIT, developed on the dev branch, and backed by a commercial entity that keeps the open-source core free. The README's disclaimer file and its explicit invitation to contact the team for API removal further signal a project that takes the legal and ethical boundaries of passive collection seriously.

In sum, subfinder earns its place as the default first stage of external reconnaissance in authorized engagements. Its refusal to sprawl — no port scanning, no content probing, just passive name discovery done fast and done politely — combined with JSONL output, per-provider rate controls, and a Go SDK, makes it the component you build workflows around rather than the workflow itself. For penetration testers, bug bounty hunters working within program scope, and defenders mapping their own exposure, it remains the reference implementation of what passive subdomain enumeration should look like.

Educational analysis for authorized security professionals. Use only in controlled, authorized environments.