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.

Screenshot Configuration

Note: --screenshot automatically enables --httpx. Requires Chrome or Chromium installed on the system.

Technology Fingerprinting Configuration

Note: --tech automatically enables --httpx. --tech-filter implies --tech.

Subdomain Takeover Configuration

Note: --takeover-only implies --takeover. Use with --httpx for enhanced body-based detection.

TUI Dashboard Configuration

Note: When TUI mode is enabled, the standard CLI banner and log output are replaced by a full-screen interactive dashboard. All scan results are displayed in real time across three tabs: Dashboard, Results, and Logs.

Diff/Monitoring Configuration

Note: Scan history is automatically stored in {output_dir}/.scan_history.json. The --baseline flag implies --diff.

Notification Configuration

Important: All notification credentials must be set via environment variables — they are never stored in config files or passed via CLI flags. See CLI Reference for the full list of environment variables.

REST API Server Configuration

Note: Server mode is started with subdomainx serve. Server-specific flags are separate from scan flags.

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
• 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 --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 --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