<div align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://github.com/eredotpkfr/subscan/blob/main/assets/logo-light.png?raw=true">
<img alt="Subscan Logo" height="105px" src="https://github.com/eredotpkfr/subscan/blob/main/assets/logo-dark.png?raw=true">
</picture>
</div>
<br>
<div align="center">
<a href="https://github.com/eredotpkfr/subscan/actions/workflows/tests.yml">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/github/actions/workflow/status/eredotpkfr/subscan/tests.yml?label=test&logo=Github&labelColor=ff3030&color=e6e6e6">
<img alt="GitHub Actions Test Workflow Status" src="https://img.shields.io/github/actions/workflow/status/eredotpkfr/subscan/tests.yml?label=test&logo=Github&labelColor=42445a&color=e6e6e6">
</picture>
</a>
<a href="https://app.codecov.io/gh/eredotpkfr/subscan">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/codecov/c/gh/eredotpkfr/subscan?labelColor=ff3030&color=e6e6e6&logo=codecov&logoColor=white">
<img alt="Codecov Status" src="https://img.shields.io/codecov/c/gh/eredotpkfr/subscan?labelColor=42445a&color=e6e6e6&logo=codecov&logoColor=white">
</picture>
</a>
<a href="https://crates.io/crates/subscan">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/crates/v/subscan?logoColor=white&color=e6e6e6&labelColor=ff3030">
<img alt="Crates.io" src="https://img.shields.io/crates/v/subscan?labelColor=42445a&color=e6e6e6">
</picture>
</a>
<a href="https://docs.rs/subscan/latest/subscan/">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/docsrs/subscan?logoColor=white&color=e6e6e6&labelColor=ff3030&logo=Rust">
<img alt="Docs.rs" src="https://img.shields.io/docsrs/subscan?labelColor=42445a&color=e6e6e6&logo=Rust">
</picture>
</a>
</div>
<div align="center">
<a href="https://github.com/eredotpkfr/subscan/actions/workflows/docker.yml">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/github/actions/workflow/status/eredotpkfr/subscan/docker.yml?label=docker&logo=Docker&labelColor=ff3030&color=e6e6e6&logoColor=white">
<img alt="GitHub Actions Docker Workflow Status" src="https://img.shields.io/github/actions/workflow/status/eredotpkfr/subscan/docker.yml?label=docker&logo=Docker&labelColor=42445a&color=e6e6e6&logoColor=white">
</picture>
</a>
<a href="https://github.com/eredotpkfr/subscan/actions/workflows/mdbook.yml">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/github/actions/workflow/status/eredotpkfr/subscan/mdbook.yml?label=book&logo=Rust&labelColor=ff3030&color=e6e6e6">
<img alt="GitHub Actions Test Workflow Status" src="https://img.shields.io/github/actions/workflow/status/eredotpkfr/subscan/mdbook.yml?label=book&logo=Rust&labelColor=42445a&color=e6e6e6">
</picture>
</a>
</div>
<div align="center">
<a href="https://pre-commit.com/">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white&color=e6e6e6&labelColor=ff3030">
<img alt="Pre-commit Badge" src="https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white&color=e6e6e6&labelColor=42445a">
</picture>
</a>
<a href="https://gitleaks.io/">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/badge/protected%20by-gitleaks-blue?color=e6e6e6&labelColor=ff3030">
<img alt="Gitleaks Badge" src="https://img.shields.io/badge/protected%20by-gitleaks-blue?color=e6e6e6&labelColor=42445a">
</picture>
</a>
<a href="https://github.com/rust-secure-code/safety-dance/">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/badge/unsafe-forbidden-success.svg?color=e6e6e6&labelColor=ff3030">
<img alt="Unsafe Forbidden" src="https://img.shields.io/badge/unsafe-forbidden-success.svg?color=e6e6e6&labelColor=42445a">
</picture>
</a>
<a href="https://github.com/eredotpkfr/subscan/blob/main/LICENSE">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/github/license/eredotpkfr/subscan?labelColor=ff3030&color=e6e6e6">
<img alt="License Badge" src="https://img.shields.io/github/license/eredotpkfr/subscan?labelColor=42445a&color=e6e6e6">
</picture>
</a>
</div>
<br>
<p align="center">
<a href="https://github.com/eredotpkfr/subscan/?tab=readme-ov-file#install">Install</a> •
<a href="https://github.com/eredotpkfr/subscan/?tab=readme-ov-file#usage">Usage</a> •
<a href="https://docs.rs/subscan/latest/subscan/">Doc</a> •
<a href="https://www.erdoganyoksul.com/subscan/">Book</a> •
<a href="https://github.com/eredotpkfr/subscan/?tab=readme-ov-file#docker">Docker</a> •
<a href="https://github.com/eredotpkfr/subscan/?tab=readme-ov-file#development">Development</a>
</p>
<br>
Subscan is a powerful subdomain enumeration tool built with [Rust](https://www.rust-lang.org/), specifically designed for penetration testing purposes. It combines various discovery techniques into a single, lightweight binary, making subdomain hunting easier and faster for security researchers
## Features
- 🕵️ Smart Discovery Tricks
- Use multiple search engines (`Google`, `Yahoo`, `Bing`, `DuckDuckGo`, etc.)
- Integrate with APIs like `Shodan`, `Censys`, `VirusTotal` and more
- Perform zone transfer checks
- Subdomain brute-forcing with optimized wordlists
- 🔍 Resolve IP addresses for all subdomains
- 📎 Export reports in `CSV`, `HTML`, `JSON`, or `TXT` formats
- 🛠️ Configurable
- Customize HTTP requests (user-agent, timeout, etc.)
- Rotate requests via proxies (`--proxy` argument)
- Fine-tune IP resolver with `--resolver` arguments
- Filter and run specific modules with `--skips` and `--modules`
- 🐳 Docker Friendly
- Native support for `amd64` and `arm64` Linux platforms
- A tiny container that won't eat up your storage — under 1GB and ready to roll 🚀
- 💻 Compatible with multiple platforms and easy to install as a single binary
## Install
🦀 Install the `subscan` tool using Cargo, Rust's package manager. Make sure you have [Rust](https://www.rust-lang.org/) installed on your system. Then, run
```bash
~$ cargo install subscan
```
## Usage
✨ Here's a quick overview of how to use it
```bash
~$ subscan
_
| |
___ _ _| |__ ___ ___ __ _ _ __
/ __| | | | '_ \/ __|/ __/ _` | '_ \
\__ \ |_| | |_) \__ \ (_| (_| | | | |
|___/\__,_|_.__/|___/\___\__,_|_| |_|
Usage: subscan [OPTIONS] <COMMAND>
Commands:
scan Start scan on any domain address
brute Start brute force attack with a given wordlist
module Subcommand to manage implemented modules
help Print this message or the help of the given subcommand(s)
Options:
-v, --verbose... Increase logging verbosity
-q, --quiet... Decrease logging verbosity
-h, --help Print help (see more with '--help')
-V, --version Print version
```
### Start Scan
To scan a domain using all available modules, use the following command
```bash
~$ subscan scan -d example.com
```
You can also choose specific modules to run or skip using the `--skips` and `--modules` arguments. Module names should be provided as a comma-separated list
```bash
~$ # skip the commoncrawl and google modules during the scan
~$ subscan scan -d example.com --skips=commoncrawl,google
```
```bash
~$ # run only the virustotal module
~$ subscan scan -d example.com --modules=virustotal
```
> [!NOTE]
> If a module is included in both the `--skips` and `--modules` arguments, it will be skipped and not executed
### Brute Force
Use the `brute` command to start a brute force attack with a specific wordlist
```bash
~$ subscan brute -d example.com --wordlist file.txt
```
## Environments
All environments are managed by the `.env` file. Subscan can read your environments from this `.env` file. You can refer to the `.env.template` file to see how to create them
> [!TIP]
> Also you can specify your environments from shell
>
> ```bash
> SUBSCAN_VIRUSTOTAL_APIKEY=foo subscan scan -d foo.com --modules=virustotal
> ```
<div align="center">
| `SUBSCAN_CHROME_PATH` | `false` | Specify your Chrome executable. If not specified, the Chrome binary will be fetched automatically by <a href="https://github.com/rust-headless-chrome/rust-headless-chrome/">headless_chrome<a/> based on your system architecture |
| `SUBSCAN_<MODULE_NAME>_HOST` | `false` | Some API integration modules can provide user specific host, for these cases, set module specific host |
| `SUBSCAN_<MODULE_NAME>_APIKEY` | `false` | Some modules may include API integration and require an API key for authentication. Set the API key in these cases |
| `SUBSCAN_<MODULE_NAME>_USERNAME` | `false` | Set the username for a module if it uses HTTP basic authentication |
| `SUBSCAN_<MODULE_NAME>_PASSWORD` | `false` | Set the password for a module if it uses HTTP basic authentication |
</div>
## Docker
🐳 For containerized usage, you can pull the `eredotpkfr/subscan` Docker image directly from [Docker Hub](https://hub.docker.com/)
```bash
~$ docker pull eredotpkfr/subscan:latest
```
After pulling the pre-built image, you can easily run the container to perform subdomain enumeration
```bash
~$ docker run -it --rm eredotpkfr/subscan scan -d example.com
```
Specify environment variable via docker `--env`
```bash
~$ docker run -it --rm \
--env SUBSCAN_VIRUSTOTAL_APIKEY=foo \
eredotpkfr/subscan scan -d example.com --modules=virustotal
```
Saving output reports to host machine, use `/data` folder
```bash
~$ docker run -it --rm \
--volume="$PWD/data:/data" \
eredotpkfr/subscan scan -d example.com
```
To specify wordlist into docker container, use `/data` folder
```bash
~$ docker run -it --rm \
--volume="$PWD/wordlist.txt:/data/wordlist.txt" \
eredotpkfr/subscan brute -d example.com \
-w wordlist.txt --print
```
## Development
📚 You can find all the resources and documentation for developing Subscan in the [Development](https://www.erdoganyoksul.com/subscan/development/index.html) chapter of the project's book page
## Credits
🙏 Parts of the codebase are inspired by
- [subfinder](https://github.com/projectdiscovery/subfinder) - Fast passive subdomain enumeration tool
- [Sublist3r](https://github.com/aboul3la/Sublist3r) - Fast subdomains enumeration tool for penetration testers
- [subbrute](https://github.com/TheRook/subbrute) - A DNS meta-query spider that enumerates DNS records, and subdomains
- [knock](https://github.com/guelfoweb/knock) - Knock subdomain scan
- [dnsrecon](https://github.com/darkoperator/dnsrecon) - DNS enumeration script
## Contributing
📢 All contributors are welcome! Whether you're fixing bugs, adding new features, improving documentation, or sharing ideas, your contributions are highly valued and appreciated
To get started, please check out the [CONTRIBUTING.md](https://github.com/eredotpkfr/subscan/blob/main/.github/CONTRIBUTING.md) file
## Donate
<a href="https://www.buymeacoffee.com/eredotpkfr" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 50px" ></a>
## Contact
Blog - [erdoganyoksul.com](https://www.erdoganyoksul.com)<br>
Mail - <erdoganyoksul3@gmail.com>