Update README.md
This commit is contained in:
Shaheer Yasir
GitHub
parent
caef2c0846
commit
cbb00d5310
345
README.md
345
README.md
|
|
@ -1,161 +1,200 @@
|
||||||
About Sublist3r
|
# Sublist3r  [](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html) [](https://github.com/aboul3la/Sublist3r/stargazers)
|
||||||
Sublist3r is a Python tool designed to enumerate subdomains of websites using OSINT. It helps penetration testers and bug hunters collect and gather subdomains for the domain they are targeting. Sublist3r enumerates subdomains using many search engines such as Google, Yahoo, Bing, Baidu, and Ask. Sublist3r also enumerates subdomains using Netcraft, VirusTotal, ThreatCrowd, DNSdumpster, ReverseDNS, BufferOverRun, and CertSpotter.
|
|
||||||
subbrute was integrated with Sublist3r to increase the possibility of finding more subdomains using bruteforce with an improved wordlist. The credit goes to TheRook who is the author of subbrute.
|
|
||||||
Enhanced to v3.0 by Shaheer Yasir (2025): Full Python 3 support, new passive engines (CertSpotter for CT logs, BufferOverRun for DNS intel), JSON output, improved performance, and VirusTotal API v3 integration.
|
|
||||||
Screenshots
|
> **Sublist3r** is a fast and powerful Python tool designed for OSINT-based subdomain enumeration. It helps penetration testers, bug bounty hunters, and security researchers discover hidden subdomains for targeted domains. Sublist3r leverages multiple search engines (Google, Yahoo, Bing, Baidu, Ask) and passive sources (Netcraft, VirusTotal, ThreatCrowd, DNSdumpster, ReverseDNS, BufferOverRun, CertSpotter) to build comprehensive subdomain lists.
|
||||||
<image-card alt="Sublist3r" src="http://www.secgeek.net/images/Sublist3r.png "Sublist3r in action"" >
|
|
||||||
Installation
|
**Enhanced to v3.0 by [Shaheer Yasir](https://github.com/shaheeryasir) (2025):** Full Python 3 support, new passive engines (CertSpotter for Certificate Transparency logs, BufferOverRun for DNS intel), JSON output, improved performance, and VirusTotal API v3 integration.
|
||||||
textgit clone https://github.com/aboul3la/Sublist3r.git
|
|
||||||
cd Sublist3r
|
## 🚀 Features
|
||||||
pip install -r requirements.txt
|
- **Multi-Engine Enumeration:** Supports 12+ search engines and passive sources for broad coverage.
|
||||||
Recommended Python Version:
|
- **Brute-Force Integration:** Powered by [SubBrute](https://github.com/TheRook/subbrute) (v1.3) with optimized wordlists.
|
||||||
Sublist3r v3.0 supports Python 3 only (Python 2 deprecated).
|
- **Output Flexibility:** Text or JSON export; verbose real-time results.
|
||||||
|
- **Port Scanning:** Built-in TCP port checks on discovered subdomains.
|
||||||
The recommended version is 3.6+ (tested up to 3.12).
|
- **Modular Design:** Easy to import as a Python library.
|
||||||
|
- **Cross-Platform:** Works on Linux, macOS, and Windows (with colorama for enhanced output).
|
||||||
Dependencies:
|
- **Rate-Limited & Stealthy:** Configurable threads, sleeps, and proxies to avoid detection.
|
||||||
Sublist3r depends on the requests, dnspython, and colorama Python modules.
|
|
||||||
These dependencies can be installed using the requirements file:
|
## 📦 Installation
|
||||||
|
|
||||||
Installation on any OS:
|
1. **Clone the Repository:**
|
||||||
|
```
|
||||||
textpip install -r requirements.txt
|
git clone https://github.com/aboul3la/Sublist3r.git
|
||||||
Alternatively, each module can be installed independently.
|
cd Sublist3r
|
||||||
Requests Module
|
```
|
||||||
|
|
||||||
Install using pip:
|
2. **Install Dependencies:**
|
||||||
|
```
|
||||||
textpip install requests>=2.25.0
|
pip install -r requirements.txt
|
||||||
dnspython Module
|
```
|
||||||
|
(Includes `requests>=2.25.0`, `dnspython>=2.0.0`, `colorama>=0.4.4`)
|
||||||
Install using pip:
|
|
||||||
|
3. **Optional: VirusTotal API Key:**
|
||||||
textpip install dnspython>=2.0.0
|
For unlimited scans, set `export VT_API_KEY=your_key_here`.
|
||||||
colorama Module
|
|
||||||
|
> **Note:** Python 3.6+ required (tested up to 3.12). No Python 2 support.
|
||||||
Install using pip:
|
|
||||||
|
## 🔧 Usage
|
||||||
textpip install colorama>=0.4.4
|
|
||||||
For enhanced VirusTotal support (optional): Set environment variable export VT_API_KEY=your_key for higher rate limits.
|
| Short Form | Long Form | Description |
|
||||||
Usage
|
|------------|-----------------|-------------|
|
||||||
|
| `-d` | `--domain` | Domain name to enumerate subdomains of |
|
||||||
|
| `-b` | `--bruteforce` | Enable the SubBrute bruteforce module |
|
||||||
|
| `-p` | `--ports` | Scan found subdomains against specific TCP ports |
|
||||||
|
| `-v` | `--verbose` | Enable verbose mode and display results in realtime |
|
||||||
|
| `-t` | `--threads` | Number of threads for SubBrute bruteforce (default: 30) |
|
||||||
|
| `-e` | `--engines` | Comma-separated list of search engines |
|
||||||
|
| `-o` | `--output` | Save results to text file |
|
||||||
|
| `-j` | `--json` | Save results to JSON file |
|
||||||
|
| `-n` | `--no-color` | Output without color |
|
||||||
|
| `-h` | `--help` | Show the help message and exit |
|
||||||
|
|
||||||
|
### Examples
|
||||||
|
|
||||||
|
* **Basic Enumeration:**
|
||||||
|
```
|
||||||
|
python sublist3r.py -d example.com
|
||||||
|
```
|
||||||
|
|
||||||
|
* **With Port Scanning (80, 443):**
|
||||||
|
```
|
||||||
|
python sublist3r.py -d example.com -p 80,443
|
||||||
|
```
|
||||||
|
|
||||||
|
* **Verbose Real-Time Results:**
|
||||||
|
```
|
||||||
|
python sublist3r.py -v -d example.com
|
||||||
|
```
|
||||||
|
|
||||||
|
* **Enable Bruteforce:**
|
||||||
|
```
|
||||||
|
python sublist3r.py -b -d example.com
|
||||||
|
```
|
||||||
|
|
||||||
|
* **Specific Engines (Google, Yahoo, VirusTotal):**
|
||||||
|
```
|
||||||
|
python sublist3r.py -e google,yahoo,virustotal -d example.com
|
||||||
|
```
|
||||||
|
|
||||||
|
* **Full Scan with JSON Output:**
|
||||||
|
```
|
||||||
|
python sublist3r.py -d example.com -b -v -j -o output.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
## 📚 Using Sublist3r as a Module
|
||||||
|
|
||||||
|
Import Sublist3r into your Python scripts for automated workflows.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Short FormLong FormDescription-d--domainDomain name to enumerate subdomains of-b--bruteforceEnable the subbrute bruteforce module-p--portsScan the found subdomains against specific tcp ports-v--verboseEnable the verbose mode and display results in realtime-t--threadsNumber of threads to use for subbrute bruteforce-e--enginesSpecify a comma-separated list of search engines-o--outputSave the results to text file-j--jsonSave the results to JSON file-n--no-colorOutput without color-h--helpshow the help message and exit
|
|
||||||
Examples
|
|
||||||
|
|
||||||
To list all the basic options and switches use -h switch:
|
|
||||||
|
|
||||||
python* To enumerate subdomains of specific domain:
|
|
||||||
|
|
||||||
``python sublist3r.py -d example.com``
|
|
||||||
|
|
||||||
* To enumerate subdomains of specific domain and show only subdomains which have open ports 80 and 443 :
|
|
||||||
|
|
||||||
``python sublist3r.py -d example.com -p 80,443``
|
|
||||||
|
|
||||||
* To enumerate subdomains of specific domain and show the results in realtime:
|
|
||||||
|
|
||||||
``python sublist3r.py -v -d example.com``
|
|
||||||
|
|
||||||
* To enumerate subdomains and enable the bruteforce module:
|
|
||||||
|
|
||||||
``python sublist3r.py -b -d example.com``
|
|
||||||
|
|
||||||
* To enumerate subdomains and use specific engines such Google, Yahoo and Virustotal engines
|
|
||||||
|
|
||||||
``python sublist3r.py -e google,yahoo,virustotal -d example.com``
|
|
||||||
|
|
||||||
## Using Sublist3r as a module in your python scripts
|
|
||||||
|
|
||||||
**Example**
|
|
||||||
|
|
||||||
```python
|
```python
|
||||||
import sublist3r
|
import sublist3r
|
||||||
subdomains = sublist3r.main(domain, no_threads, savefile, ports, silent, verbose, enable_bruteforce, engines)
|
|
||||||
The main function will return a set of unique subdomains found by Sublist3r
|
# Enumerate subdomains
|
||||||
Function Usage:
|
subdomains = sublist3r.main(
|
||||||
|
domain='yahoo.com',
|
||||||
|
no_threads=40, # Threads for bruteforce
|
||||||
|
savefile='yahoo_subdomains.txt', # Output file
|
||||||
|
ports=None, # Ports to scan
|
||||||
|
silent=False, # Silent mode
|
||||||
|
verbose=False, # Real-time output
|
||||||
|
enable_bruteforce=False, # Enable bruteforce
|
||||||
|
engines=None # Specific engines
|
||||||
|
)
|
||||||
|
|
||||||
|
print(f"Found {len(subdomains)} subdomains: {subdomains}")
|
||||||
|
```
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
- `domain`: Target domain.
|
||||||
|
- `savefile`: Optional output file.
|
||||||
|
- `ports`: Comma-separated TCP ports.
|
||||||
|
- `silent`: Suppress noise.
|
||||||
|
- `verbose`: Real-time display.
|
||||||
|
- `enable_bruteforce`: Use SubBrute.
|
||||||
|
- `engines`: Optional comma-separated engines (e.g., 'google,bing').
|
||||||
|
|
||||||
|
## 🖼️ Screenshots
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
## 🤝 Credits
|
||||||
|
|
||||||
|
- **[Ahmed Aboul-Ela](https://twitter.com/aboul3la)**: Original author.
|
||||||
|
- **[TheRook](https://github.com/TheRook)**: SubBrute bruteforce module.
|
||||||
|
- **[Bitquark](https://github.com/bitquark)**: SubBrute wordlist based on **dnspop** research.
|
||||||
|
- **[Shaheer Yasir](https://github.com/shaheeryasir)**: v3.0 enhancements (Python 3, new engines, JSON output, performance).
|
||||||
|
- **Special Thanks:** [Ibrahim Mosaad](https://twitter.com/ibrahim_mosaad) for foundational contributions.
|
||||||
|
|
||||||
|
## 📄 License
|
||||||
|
|
||||||
|
Sublist3r is licensed under the [GNU GPL v2](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html). See [LICENSE](LICENSE) for details.
|
||||||
|
|
||||||
|
## 🙌 Contributing
|
||||||
|
|
||||||
|
We welcome contributions! Fork the repo, create a feature branch, and submit a PR. For issues or questions, open a ticket on GitHub.
|
||||||
|
|
||||||
|
- Report bugs: [Issues](https://github.com/aboul3la/Sublist3r/issues)
|
||||||
|
- Suggest features: [Discussions](https://github.com/aboul3la/Sublist3r/discussions)
|
||||||
|
|
||||||
|
## 📈 Version
|
||||||
|
|
||||||
|
**Current version: 3.0** (October 01, 2025)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
⭐ **Star this repo** if Sublist3r helps your recon workflow! Follow [@aboul3la](https://twitter.com/aboul3la) for updates. Happy hunting! 🔍
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
domain: The domain you want to enumerate subdomains of.
|
|
||||||
savefile: save the output into text file.
|
|
||||||
ports: specify a comma-sperated list of the tcp ports to scan.
|
|
||||||
silent: set sublist3r to work in silent mode during the execution (helpful when you don't need a lot of noise).
|
|
||||||
verbose: display the found subdomains in real time.
|
|
||||||
enable_bruteforce: enable the bruteforce module.
|
|
||||||
engines: (Optional) to choose specific engines.
|
|
||||||
|
|
||||||
Example to enumerate subdomains of Yahoo.com:
|
|
||||||
pythonimport sublist3r
|
|
||||||
subdomains = sublist3r.main('yahoo.com', 40, 'yahoo_subdomains.txt', ports= None, silent=False, verbose= False, enable_bruteforce= False, engines=None)
|
|
||||||
License
|
|
||||||
Sublist3r is licensed under the GNU GPL license. take a look at the LICENSE for more information.
|
|
||||||
Credits
|
|
||||||
|
|
||||||
TheRook - The bruteforce module was based on his script subbrute.
|
|
||||||
Bitquark - The Subbrute's wordlist was based on his research dnspop.
|
|
||||||
Shaheer Yasir - Enhanced to v3.0 with Python 3 support, new engines (CertSpotter, BufferOverRun), JSON output, and performance improvements.
|
|
||||||
|
|
||||||
Thanks
|
|
||||||
|
|
||||||
Special Thanks to Ibrahim Mosaad for his great contributions that helped in improving the tool.
|
|
||||||
Thanks to the open-source community for ongoing feedback and contributions.
|
|
||||||
|
|
||||||
Version
|
|
||||||
Current version is 3.0
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue