Configuration

Learn how to configure SubdomainX using YAML files and CLI options.

Configuration Overview

CLI-First Approach: SubdomainX prioritizes command-line arguments over configuration files. All options can be passed directly via CLI flags.

Optional YAML Config: YAML configuration files are optional and provide default values that can be overridden by CLI arguments.

CLI Overrides YAML: Command-line arguments always take precedence over configuration file settings.

YAML Configuration

Default Configuration File

Create a configuration file at configs/default.yaml:

# SubdomainX Configuration File
# All options are optional and can be overridden via CLI
 
# Input configuration
wildcard_file: "" # Path to domains file (required via CLI)
 
# Output configuration
unique_name: "scan"
output_format: "json" # json, txt, html
output_dir: "output"
 
# Performance settings
threads: 10
retries: 3
timeout: 30
rate_limit: 100
 
# Filter settings
filters:
  status_code: "" # Filter by HTTP status codes (e.g., "200,301,302")
  ports: "" # Filter by ports (e.g., "80,443,8080")
 
# Tool selection (enumeration tools enabled by default, APIs and scanners disabled)
tools:
  subfinder: true
  findomain: true
  assetfinder: true
  amass: true
  sublist3r: true
  knockpy: true
  dnsrecon: true
  fierce: true
  massdns: true
  altdns: true
  securitytrails: false
  virustotal: false
  censys: false
  waybackurls: false
  linkheader: false
 
# Scanning tools
scanners:
  httpx: false
  smap: false

Configuration Parameters

Input Configuration

Output Configuration

Performance Configuration

Filter Configuration

Note: Filter options work with HTTP scanning (--httpx) and port scanning (--smap) results.

Tool Configuration

Tool selection is primarily controlled via CLI flags. YAML configuration provides default states. By default, enumeration tools are enabled while API tools and scanners are disabled:

Enumeration Tools

• subfinder → --subfinder
• amass → --amass
• findomain → --findomain
• assetfinder → --assetfinder
• sublist3r → --sublist3r
• knockpy → --knockpy
• dnsrecon → --dnsrecon
• fierce → --fierce
• massdns → --massdns
• altdns → --altdns
• waybackurls → --waybackurls
• linkheader → --linkheader

API Tools

• securitytrails → --securitytrails
• virustotal → --virustotal
• censys → --censys
• crtsh → --crtsh
• urlscan → --urlscan
• threatcrowd → --threatcrowd
• hackertarget → --hackertarget

Scanning Tools

• httpx → --httpx
• smap → --smap

Usage Examples

Use Default Configuration

Run with default settings from config file:

Single domain:

subdomainx example.com

Multiple domains:

subdomainx --wildcard domains.txt

Override Configuration

Override specific settings via CLI:

Single domain:

subdomainx --threads 20 --format html --max-http-targets 500 example.com

Multiple domains:

subdomainx --wildcard domains.txt --threads 20 --format html --max-http-targets 200

Custom Config File

Use a custom configuration file:

Single domain:

subdomainx --config my-config.yaml example.com

Multiple domains:

subdomainx --wildcard domains.txt --config my-config.yaml

CLI Only

Ignore config file and use only CLI arguments:

Single domain:

subdomainx --subfinder --httpx --format json example.com

Multiple domains:

subdomainx --wildcard domains.txt --subfinder --httpx --format json

API Configuration

Configure API tools using environment variables:

Single domain:

# Set API keys
export SECURITYTRAILS_API_KEY="your_key"
export VIRUSTOTAL_API_KEY="your_key"
export CENSYS_API_ID="your_id"
export CENSYS_SECRET="your_secret"
export URLSCAN_API_KEY="your_key"
export HACKERTARGET_API_KEY="your_key"
 
# Use APIs
subdomainx --securitytrails --virustotal --censys --crtsh --urlscan --threatcrowd --hackertarget example.com

Multiple domains:

# Set API keys
export SECURITYTRAILS_API_KEY="your_key"
export VIRUSTOTAL_API_KEY="your_key"
export CENSYS_API_ID="your_id"
export CENSYS_SECRET="your_secret"
export URLSCAN_API_KEY="your_key"
export HACKERTARGET_API_KEY="your_key"
 
# Use APIs
subdomainx --wildcard domains.txt --securitytrails --virustotal --censys --crtsh --urlscan --threatcrowd --hackertarget

Wordlist Configuration

Custom wordlists can be used with tools that support brute-forcing:

Single domain:

# Use custom wordlist
subdomainx --wordlist /path/to/wordlist.txt example.com
 
# Wordlist should contain one subdomain per line
# Example wordlist content:
# www
# mail
# ftp
# admin
# api
# dev
# test

Multiple domains:

subdomainx --wildcard domains.txt --wordlist /path/to/wordlist.txt

Supported tools for custom wordlists:

• subfinder - Uses -w flag for custom wordlists
• amass - Uses -w flag for custom wordlists
• massdns - Uses custom wordlist for DNS brute-forcing
• altdns - Uses custom wordlist for subdomain permutations

With Filters

Use filters to focus on specific results:

Single domain:

subdomainx --httpx --smap --status-codes 200,301,302 --ports 80,443,8080 example.com

Multiple domains:

subdomainx --wildcard domains.txt --httpx --smap --status-codes 200,301,302 --ports 80,443,8080

Configuration Tips

Tip:

• CLI arguments always override YAML configuration
• Use YAML for default settings and CLI for specific overrides
• Configuration files are optional - you can use CLI only
• Keep configuration files in version control for team consistency
• Use environment variables for sensitive configuration (API keys)
• Filter options help focus on relevant results and reduce noise
• API tools require environment variables for authentication