projectdiscovery/subfinder: Fast Passive Subdomain Enumeration in Go

projectdiscovery/subfinder: Fast Passive Subdomain Enumeration in Go

Subdomain enumeration remains one of the most time-consuming reconnaissance tasks in security workflows. Whether you're mapping attack surface for a bug bounty program or auditing infrastructure before a deployment, manually hunting subdomains across dozens of passive sources burns hours that most teams don't have. projectdiscovery/subfinder addresses this directly: a Go-based tool purpose-built for fast, passive subdomain discovery using curated online sources. With 14,022 GitHub stars and active maintenance by the ProjectDiscovery team, it has become a standard component in modern reconnaissance pipelines. This guide covers what subfinder does, how it works, and how to integrate it into your workflow.

What is projectdiscovery/subfinder?

projectdiscovery/subfinder is a subdomain discovery tool maintained by ProjectDiscovery, a team known for open-source security tools including nuclei and httpx. Written in Go and released under the MIT License, subfinder occupies a specific niche: passive subdomain enumeration only. It does not perform active brute-forcing or DNS resolution by default; instead, it queries aggregated passive sources—certificate transparency logs, search engines, archival services, and specialized APIs—to compile subdomain lists without direct interaction with target infrastructure.

The tool's architecture reflects this focused scope. Its modular design separates source implementations, allowing contributors to add or update individual passive sources independently. The README emphasizes compliance: "We have made it to comply with all the used passive source licenses and usage restrictions." This matters for teams operating under strict legal boundaries or responsible disclosure programs.

Subfinder's relevance stems from two documented design priorities: speed and stealth. Passive enumeration avoids the query volume and detectability of active scanning, making it suitable for continuous monitoring and early-phase reconnaissance. The "curated passive sources" approach—selecting sources for coverage quality rather than sheer quantity—distinguishes it from tools that spray queries across every available API regardless of reliability or rate limits.

The project shows healthy maintenance with a last commit dated 2026-07-10 and 1,576 forks indicating active community adoption. Its Go implementation ensures cross-platform portability and efficient concurrency, though the README does not publish specific benchmark figures.

Key Features

Curated passive sources. Rather than maximizing source count, subfinder selects sources for result quality. The -s and -all flags let users choose between targeted and comprehensive enumeration, with -all explicitly marked as "slow" in the help text—honest signaling about the speed/coverage trade-off.

Wildcard elimination. The tool includes resolution modules that filter out wildcard DNS responses, reducing noise in output. This is critical for large-scope enumerations where *.example.com would otherwise generate thousands of false positives.

Multiple output formats. Subfinder supports JSONL (-oJ), plain file output (-o), and stdout streaming. The -collect-sources flag includes provenance metadata in JSON output—useful for triaging which sources found which subdomains and identifying coverage gaps.

STDIN/STDOUT integration. The tool reads domains from stdin and writes subdomains to stdout, enabling Unix-pipeline workflows. This design choice reflects ProjectDiscovery's broader philosophy of composable tools that chain together in larger automation frameworks.

Per-source rate limiting. The -rls flag accepts provider-specific rate limits in key=value format (e.g., -rls "hackertarget=10/s,shodan=15/s"). This granular control prevents account bans or degraded service when using API-keyed sources, a practical concern for production reconnaissance pipelines.

Go library interface. Beyond CLI usage, subfinder exposes a Go SDK with minimal examples available in the repository's examples/main.go. This enables embedding subdomain enumeration directly into custom tools or CI/CD pipelines without shell invocation.

Use Cases

Bug bounty reconnaissance. Passive enumeration fits the legal and operational constraints of bug bounty programs, where explicit authorization may not cover active scanning. Subfinder's speed allows rapid initial mapping of in-scope assets before deeper testing.

Continuous attack surface monitoring. Security teams can schedule periodic subfinder runs against their organization's domains, diffing outputs to detect unauthorized or forgotten subdomains. The JSON output format feeds directly into asset databases or alerting systems.

M&A and third-party risk assessment. During due diligence or vendor review, security teams use subfinder to map a target organization's exposed infrastructure without intrusive scanning that might trigger incident response.

Penetration testing scoping. Testers validate the completeness of client-provided asset lists by cross-referencing with passive enumeration results. The -match and -filter flags help focus on relevant subdomains when dealing with large wildcard scopes.

Automation pipeline integration. The stdin/stdout design and Go library enable embedding subfinder into larger workflows—feeding discovered subdomains into HTTP probing tools like [INTERNAL_LINK: httpx], vulnerability scanners, or certificate transparency monitors.

Installation & Setup

Subfinder requires Go 1.24 for installation from source. The README provides this exact command:

go install -v github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest

The -v flag enables verbose output during compilation, showing package download and build progress. The /v2 path segment reflects Go module versioning for the v2.x release line.

For alternative installation methods—including precompiled binaries, Docker^{↗ Bright Coding Blog}, and package managers—the README directs users to the ProjectDiscovery documentation.

Post-Installation Configuration

Subfinder functions immediately after installation, but many passive sources require API keys for full functionality. The tool uses two configuration files:

• config.yaml: General configuration (default: $CONFIG/subfinder/config.yaml)
• provider-config.yaml: API keys and provider-specific settings (default: $CONFIG/subfinder/provider-config.yaml)

Environment variables override these defaults:

export SUBFINDER_CONFIG=/custom/path/config.yaml
export SUBFINDER_PROVIDER_CONFIG=/custom/path/provider-config.yaml

The README explicitly notes: "many sources required API keys to work." Users should consult the post-install configuration documentation for source-specific setup instructions.

Real Code Examples

The README contains limited executable examples. The following are reproduced directly from the provided documentation, with explanatory context.

Basic Help Display

subfinder -h

This displays all supported flags and their descriptions. The README presents the complete help output as reference documentation rather than narrative examples.

Domain Enumeration

subfinder -d example.com

The -d flag specifies target domain(s). Multiple domains can be passed as comma-separated values or via -dL for file-based input. This is the core invocation pattern for single-target reconnaissance.

JSON Output with Source Collection

subfinder -d example.com -oJ -collect-sources -o results.json

This combination produces JSONL output (-oJ) including which source discovered each subdomain (-collect-sources), written to results.json (-o). The JSONL format enables streaming processing without parsing complete JSON arrays.

Per-Source Rate Limiting

subfinder -d example.com -rls "hackertarget=10/s,shodan=15/s"

The -rls flag demonstrates subfinder's granular rate control. This example limits HackerTarget to 10 requests per second and Shodan to 15, preventing API quota exhaustion during large enumerations.

The README's examples/main.go contains a minimal Go SDK example, though its exact contents are not reproduced in the provided documentation. Users should examine this file directly for library integration patterns.

Advanced Usage & Best Practices

Source selection strategy. The default source set balances speed and coverage. Use -all only when comprehensive enumeration justifies the time cost—typically for high-value targets or final validation passes. The -ls flag lists available sources to inform this decision.

Recursive enumeration. The -recursive flag restricts to sources capable of handling nested subdomains (e.g., subdomain.domain.tld rather than just domain.tld). This is useful for deep infrastructure mapping but reduces source coverage.

Resolver customization. The -r and -rL flags allow specifying custom DNS resolvers. This matters for privacy (avoiding ISP resolvers) or accuracy (using resolvers with specific propagation characteristics).

Active vs. passive distinction. The -active flag filters to subdomains resolvable via DNS, but this transitions from purely passive to active verification. Understand this boundary when operating under scope restrictions that prohibit active interaction.

Output pipeline design. Combine -silent (subdomains only, no banners) with stdout redirection for clean pipeline integration:

subfinder -d example.com -silent | httpx -title -tech-detect

This pattern feeds discovered subdomains directly into HTTP probing without intermediate files.

Comparison with Alternatives

Subfinder's deliberate limitation to passive enumeration is its defining characteristic. Teams needing active brute-forcing or visual relationship mapping should consider Amass. For lightweight, pipeline-friendly passive discovery, subfinder's focused design and Go performance are advantageous. The tool does not claim superiority in all scenarios—its value lies in doing one task efficiently.

FAQ

What Go version does subfinder require? Go 1.24, as specified in the README installation instructions.

Does subfinder perform active DNS brute-forcing? No. It is explicitly designed for passive enumeration only; use -active only for DNS resolution filtering of passively discovered results.

Is subfinder free for commercial use? Yes, under the MIT License. Review the DISCLAIMER.md for usage terms.

How do I add API keys for better source coverage? Configure provider-config.yaml and consult the post-install documentation.

Can subfinder run in CI/CD pipelines? Yes, via the Go library or CLI with environment variable configuration for headless operation.

What output format works best for automation? JSONL (-oJ) with -collect-sources for structured data including provenance metadata.

How current is the project? Last commit dated 2026-07-10 with 14,022 stars and active maintenance by ProjectDiscovery.

Conclusion

projectdiscovery/subfinder occupies a well-defined position in the reconnaissance toolchain: fast, passive subdomain enumeration with minimal resource overhead and maximum pipeline compatibility. It suits security engineers, bug bounty hunters, and DevSecOps teams who need reliable subdomain discovery without the complexity of full-spectrum reconnaissance platforms.

The tool's strengths—curated sources, Go performance, stdin/stdout composability—come with intentional boundaries. It does not brute-force DNS, map network relationships, or perform vulnerability scanning. These limitations are features, not gaps, for workflows where speed and stealth outweigh comprehensive coverage.

For teams already using ProjectDiscovery's ecosystem (nuclei, httpx, naabu), subfinder integrates naturally. For others evaluating reconnaissance tools, its MIT license and active maintenance reduce adoption risk.

Explore the repository, review the installation options, and experiment with your target domains: https://github.com/projectdiscovery/subfinder