Subdominator Documentation

Findings are automatically saved to a SQLite database at ~/.local/share/subdominator/subdominator.db on every run.

• Custom path: Use --db-path <path> to specify a different location.
• Disable database: Use --no-db to skip saving findings for a specific run.
• Interactive access: Use the --shell command to enter an interactive mode to query and export data from the database.

Note on crtsh: The crtsh provider uses a direct PostgreSQL connection to query the public crt.sh certificate transparency database via asyncpg. This is a read-only query to the external server and does not affect Subdominator's local SQLite storage.

# Run without saving to the local database
subdominator -d example.com --no-db

# Use a custom database path
subdominator -d example.com --db-path ./my_findings.db

Subdominator requires Python 3.13+. You can install it using uv (recommended for speed), pip, or by cloning the source repository.

To enable HTML report generation, install the reports extra.

Recommended (uv):

uv tool install subdominator

Traditional (pip):

pip install --upgrade subdominator

With HTML report support:

pip install "subdominator[reports]"
# or
uv tool install "subdominator[reports]"

From source:

git clone https://github.com/RevoltSecurities/Subdominator.git
cd Subdominator
uv sync

To use the HTML report generation feature in subdominator, you must install the optional reports extra, which includes jinja2.

pip install subdominator[reports]

Pre-built images are available on the GitHub Container Registry (GHCR).

# Pull and scan a domain
docker run --rm -it ghcr.io/revoltsecurities/subdominator:latest -d example.com

# Save output to the current host directory
docker run --rm -it \
  -v $(pwd):/output \
  ghcr.io/revoltsecurities/subdominator:latest \
  -d example.com -o /output/results.txt

# Use a custom provider configuration file
docker run --rm -it \
  -v /path/to/config:/config \
  ghcr.io/revoltsecurities/subdominator:latest \
  -cp /config/provider-config.yaml -d example.com

To build the Subdominator Docker image, run the build command from the project root directory. This creates an image tagged as subdominator using the Dockerfile located in the Docker/ directory.

docker build -t subdominator -f Docker/Dockerfile .

To contribute to Subdominator, clone the repository and use uv for environment management.

# Clone and setup environment
git clone https://github.com/RevoltSecurities/Subdominator.git
cd Subdominator
uv sync --group dev

# Run tests
python -m pytest tests/ -v

# Build distribution
uv build

Subdominator is a high-performance passive subdomain enumeration engine. It can scan a single domain or a list of domains in bulk.

Common Usage Patterns:

Single domain scan:

subdominator -d example.com

Recursive enumeration (depth 2):

subdominator -d example.com -rd 2

Bulk scan from a file with per-domain output:

subdominator -dL domains.txt -oD ./output/

Using specific resources:

# Include only specific sources
subdominator -d example.com -ir shodan,censys,securitytrails

# Exclude specific sources
subdominator -d example.com -er commoncrawl,waybackarchive

# Use all 73 resources (including slow/rate-limited ones)
subdominator -d example.com --all

Custom Google dork:

subdominator -d example.com -ir google -dk site:example.com -inurl:www

Subdominator supports several output formats depending on your workflow:

• Plain text (default): One subdomain per line. Use -o results.txt to save.
• JSONL stream (-j): Newline-delimited JSON, one finding per line. Ideal for piping into jq or grep.
• HTML report (-oh report.html): A standalone HTML report. Requires the jinja2 dependency (pip install "subdominator[reports]").
• Summary (-ss or -srs): --show-summary prints an overview table (total findings, resource counts, duration). --show-resource-stats adds a per-resource breakdown.
• JSON report (-rj report.json): A structured JSON summary of the run, including resource execution metadata.

# Save as JSONL for pipeline processing
subdominator -d example.com -j

# Generate an HTML report (requires [reports] extra)
subdominator -d example.com -oh report.html

When the --save-db flag is used, Subdominator persists findings to a local database. On subsequent runs for the same domain, the engine retrieves historical_findings from the database and merges them with the current scan results.

This allows the tool to distinguish between:

1. Fresh findings: Subdomains discovered in the current run that were not in the database.
2. Historical findings: Subdomains already known from previous runs.
3. New since past data: A metric showing how many subdomains were newly discovered compared to the existing historical set.

You can drive Subdominator settings using environment variables with the SUBDOMINATOR_ prefix. CLI flags take precedence over environment variables.

Note: Standard proxy environment variables (HTTP_PROXY, HTTPS_PROXY, NO_PROXY) are also respected automatically.