Subfinder is a fast and reliable tool for passive subdomain enumeration. Developed by ProjectDiscovery, it’s a favorite among security professionals and penetration testers for gathering subdomain information without actively probing the target, making it stealthy and efficient. It leverages multiple sources to discover subdomains associated with a given domain, which can be useful for mapping an organization’s public-facing infrastructure during reconnaissance.
This guide covers the installation, configuration, and usage of Subfinder, including tips for API integration, output formats, and practical examples.
1、Table of Contents
2、What is Subfinder?
3、System Requirements
- Installation
- Linux Installation
- Windows Installation
4、macOS Installation
5、Configuration and API Integration
6、Basic Usage
Advanced Usage and Options
- Customizing Data Sources
- Filtering Results by Status
- Output Formatting
7、Automating with Subfinder
8、Tips for Optimal Use
9、Troubleshooting
10、Conclusion
1. What is Subfinder?
Subfinder is a passive subdomain discovery tool that uses third-party services (such as search engines, DNS APIs, and data aggregators) to find subdomains. Unlike brute-force or active scanning, passive enumeration techniques provide fast results without directly interacting with the target domain's infrastructure, which helps in avoiding detection by security systems.
Key Features:
Passive Enumeration: No direct interaction with the target domain.
Multiple Sources: Supports over 20 data sources, including Shodan, Censys, and VirusTotal.
Flexible Output: Allows exporting results in multiple formats.
API Key Support: Integrates with APIs for higher rate limits and more detailed data.
2. System Requirements
Before you install Subfinder, make sure your system meets these basic requirements:
Operating System: Linux, macOS, or Windows (via WSL)
Go Language: Subfinder is built in Go, so having Go installed is required
Memory: At least 512 MB of RAM
Disk Space: 100 MB free disk space
3. Installation
Subfinder installation steps vary by platform, so follow the steps according to your operating system.
3.1 Linux Installation
Install Go: If you don’t have Go installed, you can install it as follows:
sudo apt update
sudo apt install golang-go
Install Subfinder: Clone the repository and install Subfinder via Go:
git clone
https://github.com/projectdiscovery/subfinder.git
cd subfinder/v2/cmd/subfinder
go build
sudo mv subfinder /usr/local/bin/
Verify Installation: To confirm Subfinder is installed, run:
subfinder -h
3.2 Windows Installation (Using WSL)
Install WSL: Follow the official WSL installation guide to set up Ubuntu or another Linux distribution on Windows.
Install Go and Subfinder: Follow the same steps as Linux Installation within the WSL terminal.
Verify Installation: Run the subfinder -h command to check if Subfinder was installed successfully.
3.3 macOS Installation
Install Go (if not already installed):
brew install go
Install Subfinder:
go install -v github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest
Verify Installation: Run subfinder -h to verify the installation.
4. Configuration and API Integration
Subfinder relies on various data sources that require API keys for access. You can configure these API keys to increase Subfinder’s effectiveness.
Create a Configuration File: After running Subfinder for the first time, a configuration file named .config/subfinder/config.yaml is generated.
Add API Keys: Open config.yaml and insert API keys for each data source as follows:
yaml
virustotal:
api_key: "YOUR_VIRUSTOTAL_API_KEY"
shodan:
api_key: "YOUR_SHODAN_API_KEY"
censys:
id: "YOUR_CENSYS_API_ID"
secret: "YOUR_CENSYS_API_SECRET"
Ensure you replace "YOUR_API_KEY" with your actual API keys.
Save and Close: Save the file and close it. Subfinder will now use these keys to access more data and increase the rate limits for specific services.
5. Basic Usage
Subfinder's syntax is straightforward, with only a few options necessary to get started.
Basic Command
To perform a basic subdomain search on a domain (e.g., example.com), use:
subfinder -d example.com
This command will retrieve all discovered subdomains for example.com using the default data sources configured in the config.yaml.
6. Advanced Usage and Options
Subfinder offers several advanced options for customization and optimization.
6.1 Customizing Data Sources
You can specify which sources to use with the -s option. For example:
subfinder -d example.com -s virustotal,shodan
This command restricts the enumeration to virustotal and shodan data sources only.
6.2 Filtering Results by Status
To filter live subdomains, combine Subfinder with httpx (another tool from ProjectDiscovery) for real-time validation:
subfinder -d example.com | httpx -silent
This command uses httpx to check each discovered subdomain to determine if it’s active.
6.3 Output Formatting
Subfinder supports different output formats for easy integration with other tools.
JSON Output:
subfinder -d example.com -o results.json -oJ
CSV Output:
subfinder -d example.com -o results.csv -oC
These output files can be used in post-processing scripts, other tools, or for documentation.
7. Automating with Subfinder
To automate Subfinder for repeated scans or large-scale assessments, create a simple script. Here’s an example of a Bash script that runs Subfinder on a list of domains:
#!/bin/bash
for domain in $(cat domains.txt); do
echo "Running Subfinder on $domain"
subfinder -d $domain -o $domain.txt
done
This script will save subdomain results for each domain in the domains.txt file.
8. Tips for Optimal Use
API Rate Limits: Ensure you have configured API keys for as many sources as possible to avoid rate limits and increase the data available.
Combine Tools: For enhanced results, combine Subfinder with tools like httpx and dnsx to verify active domains.
Use Proxies: If you’re running Subfinder in high-frequency environments, consider using proxies to avoid IP-based rate limiting.
Adjust Output: Use JSON or CSV output for easy integration with reporting and data analysis tools.
9. Troubleshooting
Common Issues and Solutions
No Subdomains Found:
Verify your API keys are correct and active.
Try additional data sources by adding more APIs or adjusting the configuration file.
Rate Limiting:
Rate limiting issues often arise from data sources. Ensure you have added your API keys to reduce these limitations.
Alternatively, use Subfinder with a lower frequency or use proxies.
API Key Errors:
Double-check your config.yaml file for any syntax errors.
Ensure the API keys are up-to-date and correctly formatted.
10. Conclusion
Subfinder is a valuable tool for performing passive subdomain enumeration quickly and efficiently. Its integration with multiple APIs, support for various output formats, and ease of use make it an essential tool in any security researcher’s toolkit.
By following this guide, you should now be able to:
Install and configure Subfinder on various operating systems.
Set up API keys for expanded data source support.
Use Subfinder for basic and advanced subdomain enumeration.
Export and automate Subfinder processes for larger-scale assessments.
With Subfinder, you can gain comprehensive visibility into the external footprint of target domains, providing crucial insights during security assessments.
