SubScope - Advanced Subdomain Enumeration Tool

SubScope is an enterprise-grade subdomain enumeration tool that combines multiple discovery techniques with intelligent filtering and stealth capabilities for comprehensive reconnaissance.

Features

• Multi-Source Discovery: Integrates passive enumeration, certificate transparency, dynamic wordlist generation, and active probing
• Intelligent Filtering: Wildcard detection and filtering to eliminate false positives
• Enhanced DNS Analysis: Collects CNAME, SOA records with automatic cloud service detection
• Geographic DNS Resolution: Queries from multiple global regions to catch geo-specific subdomains
• Organization Intelligence: RDAP integration for IP ownership data from all major RIRs
• Cloud Infrastructure Mapping: Identifies AWS, Azure, GCP, and CDN services automatically
• Domain Persistence: Track new domains across scans with built-in history
• Stealth Capabilities: User-agent rotation, request jitter, and rate limiting
• Multiple Output Formats: JSON, CSV, massdns, dnsx, Aquatone, and EyeWitness formats for tool chaining
• Input Domain Support: Load domains from files for iterative scanning workflows
• Progress Indicators: Real-time progress bars for long-running operations
• Rate Limit Profiles: Stealth, normal, and aggressive scanning modes
• Go Install Support: Easy installation and distribution

Installation

Using Go Install

go install -v github.com/resistanceisuseless/subscope/cmd/subscope@latest

Building from Source

git clone https://github.com/resistanceisuseless/subscope
cd subscope

# Simple build (dev version)
go build -o subscope cmd/subscope/*.go

# Or use the build script with version injection
./build.sh

# Build with custom version
./build.sh 1.2.3

Dependencies

SubScope integrates with these tools (install separately):

• subfinder - Passive subdomain enumeration
• httpx - HTTP/HTTPS probing
• shuffledns - Fast DNS resolution (recommended)
• alterx - Dynamic wordlist generation (optional, use with -all flag)

# Install core dependencies
go install -v github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest
go install -v github.com/projectdiscovery/httpx/cmd/httpx@latest
go install -v github.com/projectdiscovery/shuffledns/cmd/shuffledns@latest

# Optional dependency for -all flag
go install -v github.com/projectdiscovery/alterx/cmd/alterx@latest

Usage

SubScope supports both short and long flag options following standard Unix conventions.

Basic Enumeration

# Default optimized pipeline (passive, zone-transfer, http, rdns)
subscope -d example.com
subscope --domain example.com

# Complete pipeline with all phases
subscope -d example.com -a
subscope --domain example.com --all

# Geographic DNS analysis only
subscope -d example.com -g
subscope --domain example.com --geo

Modular Feature Selection (NEW)

SubScope now supports granular control over which enumeration modules to run:

# Run only passive enumeration
subscope -d example.com --passive

# Combine specific features (short flags)
subscope -d example.com -p -h
subscope -d example.com -p -g -r

# Run DNS brute forcing only
subscope -d example.com -b

# Custom security testing workflow  
subscope -d example.com -p -z --ct

Flag Options

Target

• -d, --domain: Target domain to enumerate (required)

Input

• -c, --config: Configuration file path
• -i, --input: File containing additional domains to scan
• -m, --merge: Merge input domains with discovered domains

Output

• -o, --output: Output file path (default: results.json, use '-' for stdout)
• -f, --format: Output format (json, csv, massdns, dnsx, aquatone, eyewitness)

Enumeration Features

• -p, --passive: Passive enumeration via subfinder
• -z, --zone: DNS zone transfer attempts
• -h, --http: HTTP/HTTPS analysis via httpx
• -b, --brute: DNS brute force via alterx
• -g, --geo: Geographic DNS analysis
• -r, --rdns: Reverse DNS lookups
• --ct: Certificate transparency logs
• --arin: ARIN/RDAP organization data
• --persist: Domain history tracking

Control

• -a, --all: Enable all enumeration features
• --profile: Rate limit profile (stealth, normal, aggressive)
• -v, --verbose: Verbose output
• --progress: Show progress bars

ProxyHawk Integration

• --proxyhawk-url URL: ProxyHawk server URL for enhanced geographic DNS
• --proxyhawk-regions REGIONS: Comma-separated list of regions to query
• --proxyhawk-realtime: Enable real-time monitoring features (experimental)

Tool Integration & Execution Mode

• --exec-mode: Force external tool execution instead of library integration
• --subfinder-args ARGS: Custom arguments for subfinder executable
• --httpx-args ARGS: Custom arguments for httpx executable
• --alterx-args ARGS: Custom arguments for alterx executable
• --shuffledns-args ARGS: Custom arguments for shuffledns executable

Utility

• --init: Create default config file
• -s, --stats: Show domain statistics
• -n, --new: Show new domains since date (YYYY-MM-DD)
• --version: Show version information

Feature Selection Logic

Important: When using feature flags, SubScope follows these rules:

1. If no feature flags are specified, default features are used (passive, zone-transfer, http-analysis, rdns)
2. If any feature flags are specified, ONLY those features are enabled
3. The -a/--all flag overrides everything and enables all features

Examples:

# Uses defaults (passive, zone-transfer, http-analysis, rdns)
subscope -d example.com

# Only runs passive enumeration
subscope -d example.com --passive

# Only runs passive + geographic DNS
subscope -d example.com --passive --geo-dns

# Runs everything
subscope -d example.com -a

Output Formats

# JSON output (default)
subscope -d example.com -o results.json

# CSV format
subscope -d example.com --format csv --output results.csv

# massdns format
subscope -d example.com -f massdns -o domains.txt

# dnsx format
subscope -d example.com --format dnsx --output dnsx-input.txt

# Aquatone format (domain,ip,port)
subscope -d example.com -f aquatone -o aquatone-input.txt

# EyeWitness format (URL list)
subscope -d example.com --format eyewitness --output eyewitness-urls.txt

Input Domain Support

# Load domains from file and scan them instead of discovered domains
subscope -d example.com --input-domains domains.txt

# Merge input domains with discovered domains
subscope -d example.com --input-domains domains.txt --merge

# Iterative scanning example
subscope -d example.com -o round1.json
# Extract domains from previous scan results and scan them
subscope -d example.com --input-domains extracted-domains.txt -o round2.json

Geographic DNS Analysis

# Geographic analysis only (faster than --all)
subscope -d example.com --geo

# Geographic analysis with verbose output
subscope -d example.com -g -v

# Combined with custom output format
subscope -d example.com -g -f csv -o geo-results.csv

ProxyHawk Integration (Enhanced Geographic DNS)

SubScope integrates with ProxyHawk for advanced geographic DNS analysis with real proxy endpoints worldwide.

ProxyHawk Server Setup

First, set up ProxyHawk server to provide proxy endpoints:

# Install ProxyHawk server
go install -v github.com/resistanceisuseless/proxyhawk/cmd/proxyhawk-server@latest

# Start ProxyHawk server (default: localhost:8080)
proxyhawk-server

# Start on custom port
proxyhawk-server -port 9090

# Start with specific proxy regions
proxyhawk-server -regions "us-east,us-west,eu-west,asia-pacific"

ProxyHawk Client Usage with SubScope

# Enable ProxyHawk integration for geographic DNS
subscope -d example.com --geo --proxyhawk-url http://localhost:8080

# Use custom ProxyHawk server
subscope -d example.com -g --proxyhawk-url https://proxyhawk.company.com

# Specify custom regions (comma-separated)
subscope -d example.com --geo \
  --proxyhawk-url http://localhost:8080 \
  --proxyhawk-regions "us-east,us-west,eu-west"

# Enable real-time monitoring (experimental)
subscope -d example.com -g \
  --proxyhawk-url http://localhost:8080 \
  --proxyhawk-realtime

# Combined with verbose output
subscope -d example.com -g -v \
  --proxyhawk-url http://localhost:8080 \
  --proxyhawk-regions "us-east,eu-west,asia-pacific"

Tool Integration & Custom Arguments

SubScope integrates with external tools using both library mode (default) and exec mode (fallback/custom args).

# Force exec mode with default arguments
subscope -d example.com --exec-mode

# Exec mode with custom subfinder arguments
subscope -d example.com --exec-mode \
  --subfinder-args "-timeout 60 -sources crtsh,virustotal"

# Exec mode with custom httpx arguments
subscope -d example.com --exec-mode \
  --httpx-args "-threads 50 -timeout 15 -screenshot"

# Exec mode with custom alterx arguments  
subscope -d example.com --exec-mode \
  --alterx-args "-enrich -limit 5000 -p custom-patterns.txt"

# Exec mode with custom shuffledns arguments
subscope -d example.com --exec-mode \
  --shuffledns-args "-t 100 -retries 3"

# Combined custom arguments
subscope -d example.com --exec-mode \
  --subfinder-args "-sources shodan,censys" \
  --httpx-args "-screenshot -tech-detect" \
  --alterx-args "-enrich -limit 10000"

ProxyHawk Flags

• --proxyhawk-url URL: ProxyHawk server URL (e.g., http://localhost:8080)
• --proxyhawk-regions REGIONS: Comma-separated list of regions to query
• --proxyhawk-realtime: Enable real-time monitoring features (experimental)

ProxyHawk Benefits

• Real Proxy Endpoints: Uses actual proxy servers worldwide vs. EDNS simulation
• Enhanced Accuracy: More reliable geographic DNS resolution detection
• Comparison Mode: Automatically compares traditional EDNS vs. ProxyHawk methods
• Custom Regions: Specify exact geographic regions for testing
• Scalable Infrastructure: Supports distributed proxy server deployments

Example ProxyHawk Output

subscope -d example.com -g -v --proxyhawk-url http://localhost:8080

# Output includes ProxyHawk comparison:
ProxyHawk integration enabled: http://localhost:8080
ProxyHawk regions configured: [us-east, us-west, eu-west, asia-pacific]
Geographic DNS resolver status: {ProxyHawkAvailable:true Regions:4 TraditionalMethod:true}

[Geographic Analysis - example.com]
Traditional method: 12 domains, ProxyHawk method: 15 domains
Differences found: 2
  - cdn-proxy-us.example.com (found via ProxyHawk us-east)
  - api-regional-eu.example.com (found via ProxyHawk eu-west)
Recommendation: ProxyHawk method provides more comprehensive results

ProxyHawk Architecture

┌─────────────┐    HTTP/WebSocket    ┌─────────────────┐
│   SubScope  │ ◄──────────────────► │ ProxyHawk Server│
└─────────────┘                      └─────────────────┘
                                              │
                                              ▼
                                     ┌─────────────────┐
                                     │   Proxy Pool    │
                                     │ ┌─────┬─────────┤
                                     │ │US-E │ US-W    │
                                     │ │EU-W │ ASIA-P  │
                                     │ └─────┴─────────┤
                                     └─────────────────┘

Progress Indicators

# Show progress bars for long-running operations
subscope -d example.com --progress

# Works with all modes
subscope -d example.com -a --progress  # All phases with progress
subscope -d example.com -g --progress  # Geographic analysis with progress

Rate Limit Profiles

# Stealth mode - minimal footprint (5 req/sec, delays, jitter)
subscope -d example.com --profile stealth

# Normal mode - balanced performance (20 req/sec)
subscope -d example.com --profile normal

# Aggressive mode - maximum speed (100 req/sec, no delays)
subscope -d example.com --profile aggressive

# Combine with other options
subscope -d example.com --profile stealth -g --progress

Configuration

Create a default configuration file:

subscope -create-config

This creates ~/.config/subscope/config.yaml with customizable settings:

• Rate limiting and jitter
• Stealth options (user agents, delays)
• Tool-specific configurations
• Output preferences

Domain History & Tracking

View domain statistics:

subscope -d example.com -s
subscope --domain example.com --stats

Show new domains discovered since a specific date:

subscope -d example.com --new-since 2024-01-01

Enumeration Pipeline

Default Pipeline (Optimized)

By default, SubScope runs these phases for faster results:

1. Wildcard Detection: Tests for wildcard DNS to prevent false positives
2. Passive Enumeration: Uses subfinder to query multiple data sources (includes CT logs)
3. HTTP/HTTPS Analysis: Probes with httpx to discover from headers, SSL certs, and redirects
4. DNS Resolution: Uses shuffledns for fast multi-threaded resolution (falls back to built-in if not installed)
5. RDNS Analysis: Performs reverse lookups on resolved IPs
6. Wildcard Filtering: Removes false positives from wildcard responses

Complete Pipeline (-a/--all flag)

Use -a or --all flag to enable all phases including:

1-6. All default phases above, plus: 7. Certificate Transparency: Additional CT log queries (temporarily disabled) 8. Dynamic Wordlist: Generates permutations using alterx (after HTTP discovery) 9. Enhanced RDNS: IP range scanning for additional subdomain discovery 10. Geographic DNS Analysis: Multi-region queries to detect geo-specific subdomains 11. Organization Data: Queries RDAP APIs for IP ownership information 12. Persistence Tracking: Marks new domains and maintains history

Output Format

JSON Output Structure

SubScope now organizes results into three distinct categories for better clarity:

{
  "metadata": {
    "version": "1.0",
    "timestamp": "2025-01-25T10:30:00Z",
    "tool": {
      "name": "SubScope",
      "version": "0.1.0"
    },
    "target": "example.com",
    "scan_type": "passive+zone_transfer+httpx+rdns+geodns+resolution"
  },
  "statistics": {
    "domains_resolved": 45,
    "domains_discovered": 12,
    "domains_generated_failed": 234,
    "execution_time": "5m30s",
    "sources": ["subfinder", "zone_transfer", "httpx", "rdns", "geodns"]
  },
  "resolved_domains": [
    {
      "domain": "api.example.com",
      "status": "resolved",
      "dns_records": {
        "A": "192.0.2.1",
        "A_ALL": "192.0.2.1,192.0.2.2",
        "CNAME": "api-prod.cloudfront.net",
        "TXT": "v=spf1 include:_spf.google.com ~all",
        "SOA": "ns-123.awsdns-12.com awsdns-hostmaster.amazon.com 1 7200 900 1209600 86400",
        "CLOUD_SERVICE": "AWS-CloudFront",
        "CLOUD_DNS": "AWS-Route53"
      },
      "source": "subfinder",
      "timestamp": "2025-01-25T10:25:00Z"
    }
  ],
  "discovered_domains": [
    {
      "domain": "old-api.example.com",
      "status": "failed",
      "source": "subfinder",
      "timestamp": "2025-01-25T10:25:00Z"
    }
  ],
  "failed_generated": [
    {
      "domain": "api-dev-staging-test.example.com",
      "status": "failed",
      "source": "alterx",
      "timestamp": "2025-01-25T10:25:00Z"
    }
  ]
}

Result Categories

• resolved_domains: Successfully resolved domains with complete DNS information (IP addresses, CNAME, TXT, SOA records when present)
• discovered_domains: Real domains found through legitimate enumeration sources but failed to resolve or have no A records (could be temporarily down or misconfigured)
• failed_generated: AlterX-generated permutations that failed to resolve (likely non-existent domains created by wordlist generation)

Domain Status Values

• discovered: Found but not yet resolved
• resolved: Successfully resolved to IP address
• wildcard: Matches wildcard DNS pattern
• failed: DNS resolution failed
• new_resolved: Newly discovered and resolved (with persistence enabled)

Discovery Sources

• subfinder: Passive enumeration
• zone_transfer: DNS zone transfer (AXFR) attempts
• alterx: Dynamic wordlist/bruteforcing
• httpx: HTTP headers, SSL certificates, redirects
• rdns: Reverse DNS lookup
• rdns_range: IP range scanning for reverse DNS
• geodns: Geographic DNS resolution differences

Output Parsing & Tool Chaining

SubScope provides multiple output formats and easy parsing options for integrating with other tools in your workflow.

Quick Parsing Examples

Extract All Resolved Domains

# Using jq (recommended for JSON)
subscope -d example.com -o results.json
cat results.json | jq -r '.resolved_domains[].domain' > domains.txt

# One-liner
subscope -d example.com -o - | jq -r '.resolved_domains[].domain'

Extract All IP Addresses

# Extract all A records
cat results.json | jq -r '.resolved_domains[].dns_records.A' | grep -v null > ips.txt

# Extract all IPs including multiple A records
cat results.json | jq -r '.resolved_domains[].dns_records.A_ALL' | grep -v null | tr ',' '\n' | sort -u > all_ips.txt

# Extract IPs with their domains
cat results.json | jq -r '.resolved_domains[] | select(.dns_records.A != null) | "\(.domain),\(.dns_records.A)"' > domain_ip_mapping.csv

Filter by Source

# Get only domains from passive enumeration
cat results.json | jq -r '.resolved_domains[] | select(.source == "subfinder") | .domain'

# Get domains discovered by HTTP analysis
cat results.json | jq -r '.resolved_domains[] | select(.source == "httpx") | .domain'

# Get domains from geographic DNS
cat results.json | jq -r '.resolved_domains[] | select(.source == "geodns") | .domain'

Filter by Cloud Provider

# Get all AWS-hosted domains
cat results.json | jq -r '.resolved_domains[] | select(.dns_records.CLOUD_SERVICE != null and (.dns_records.CLOUD_SERVICE | contains("AWS"))) | .domain'

# Get all Cloudflare domains
cat results.json | jq -r '.resolved_domains[] | select(.dns_records.CLOUD_SERVICE == "Cloudflare") | .domain'

# Export cloud services mapping
cat results.json | jq -r '.resolved_domains[] | select(.dns_records.CLOUD_SERVICE != null) | "\(.domain),\(.dns_records.CLOUD_SERVICE)"' > cloud_services.csv

Tool Chaining Examples

Send to Nuclei for Vulnerability Scanning

# All resolved domains
subscope -d example.com -o - | jq -r '.resolved_domains[].domain' | nuclei -silent

# Only cloud-hosted domains (higher priority targets)
subscope -d example.com -o - | jq -r '.resolved_domains[] | select(.dns_records.CLOUD_SERVICE != null) | .domain' | nuclei -tags cloud -silent

Send to httpx for HTTP Probing

# Probe all domains (SubScope already did basic HTTP analysis)
subscope -d example.com -o - | jq -r '.resolved_domains[].domain' | httpx -title -tech-detect -status-code

# Probe only newly discovered domains
subscope -d example.com --new-since 2024-01-01 -o - | jq -r '.resolved_domains[].domain' | httpx -screenshot

Send to nmap for Port Scanning

# Scan all unique IPs
subscope -d example.com -o - | jq -r '.resolved_domains[].dns_records.A' | grep -v null | sort -u | nmap -iL - -Pn -sV

# Scan specific cloud provider IPs
subscope -d example.com -o - | jq -r '.resolved_domains[] | select(.dns_records.CLOUD_SERVICE | contains("AWS")) | .dns_records.A' | grep -v null | sort -u > aws_ips.txt
nmap -iL aws_ips.txt -p 80,443,8080,8443 -sV

Send to waybackurls for Historical Data

# Get historical URLs for all domains
subscope -d example.com -o - | jq -r '.resolved_domains[].domain' | waybackurls

# Focus on API endpoints
subscope -d example.com -o - | jq -r '.resolved_domains[] | select(.domain | contains("api")) | .domain' | waybackurls | grep -E '\.json|api/v'

Alternative Output Formats

CSV Format (-f csv)

subscope -d example.com -f csv -o results.csv
# Columns: domain,ip,source,cloud_service,dns_provider,first_seen

# Parse with standard tools
cut -d',' -f1 results.csv | tail -n +2 > domains.txt  # domains only
cut -d',' -f2 results.csv | tail -n +2 | sort -u > ips.txt  # IPs only

Aquatone Format (-f aquatone)

# Direct pipe to aquatone
subscope -d example.com -f aquatone -o - | aquatone

# Save for later
subscope -d example.com -f aquatone -o aquatone_urls.txt
cat aquatone_urls.txt | aquatone -out aquatone_results

massdns Format (-f massdns)

# Use for further DNS enumeration
subscope -d example.com -f massdns -o massdns_input.txt
massdns -r resolvers.txt -o S massdns_input.txt

dnsx Format (-f dnsx)

# Chain with dnsx for additional DNS queries
subscope -d example.com -f dnsx -o - | dnsx -a -aaaa -cname -mx -txt -resp

Advanced Parsing Techniques

Geographic DNS Analysis Results

# Extract domains found only in specific regions
cat results.json | jq -r '.resolved_domains[] | select(.geodns != null and (.geodns.found_in_regions | contains(["Europe-West"]))) | .domain'

# Find geo-distributed domains (found in all regions)
cat results.json | jq -r '.resolved_domains[] | select(.geodns != null and (.geodns.found_in_regions | length) >= 6) | .domain'

# Extract region-specific IPs
cat results.json | jq -r '.resolved_domains[] | select(.geodns != null) | .geodns.regional_records | to_entries[] | "\(.key),\(.value.a[])"' 2>/dev/null | grep -v null

Monitoring & Alerting

# Check for new domains since last scan
subscope -d example.com --new-since $(date -d '1 week ago' +%Y-%m-%d) -o - | jq -r '.resolved_domains[].domain' | while read domain; do
    echo "ALERT: New subdomain discovered: $domain"
    # Send to Slack, email, etc.
done

# Monitor specific patterns
subscope -d example.com -o - | jq -r '.resolved_domains[] | select(.domain | test("qa|dev|test|staging")) | .domain' > dev_environments.txt

Combine Multiple Scans

# Merge results from multiple domains
for domain in example.com example.org example.net; do
    subscope -d $domain -o ${domain}_results.json
done
jq -s '.[0].resolved_domains + .[1].resolved_domains + .[2].resolved_domains | unique_by(.domain)' *_results.json > combined.json

Performance Tips

1. Use streaming (-o -) to pipe directly to other tools without writing to disk
2. Pre-filter with jq before sending to slow tools like nmap
3. Use parallel processing for multiple domains:

   cat domains.txt | parallel -j 5 'subscope -d {} -o {}_results.json'

4. Cache results and use --new-since for incremental scans

Common Use Cases

Bug Bounty Workflow

# Initial recon
subscope -d target.com -a -o target_full.json

# Extract high-value targets
cat target_full.json | jq -r '.resolved_domains[] | select(.domain | test("api|admin|internal|dev")) | .domain' > priority_targets.txt

# Scan priority targets
cat priority_targets.txt | nuclei -t exposures,misconfigurations -silent

Security Monitoring

# Daily subdomain monitoring
subscope -d company.com --persistence -o daily_scan.json

# Alert on new domains
subscope -d company.com --new-since $(date -d yesterday +%Y-%m-%d) -o - | jq -r '.resolved_domains[].domain' | mail -s "New Subdomains Found" [email protected]

Infrastructure Mapping

# Map cloud infrastructure
subscope -d company.com -o - | jq -r '.resolved_domains[] | select(.dns_records.CLOUD_SERVICE != null) | [.domain, .dns_records.CLOUD_SERVICE, .dns_records.A] | @csv' > cloud_infrastructure.csv

# Identify CDN endpoints
subscope -d company.com -o - | jq -r '.resolved_domains[] | select(.dns_records.CLOUD_SERVICE | test("CloudFront|Cloudflare|Akamai|Fastly")) | .domain' > cdn_endpoints.txt

Advanced Features

Enhanced DNS Analysis

SubScope automatically collects comprehensive DNS records for each resolved domain:

DNS Records Collected

• A/AAAA: IP addresses (IPv4/IPv6)
• CNAME: Canonical name records with automatic cloud service detection
• SOA: Start of Authority records for DNS provider identification

Automatic Cloud Service Detection

SubScope identifies cloud services and infrastructure automatically:

Supported Cloud Providers:

• AWS: CloudFront, ELB, S3, Global Accelerator, Lambda, etc.
• Azure: Static Web Apps, App Service, CDN, Traffic Manager, Front Door
• Google Cloud: Cloud Storage, App Engine, Cloud Run, Cloud Functions
• CDN Providers: Cloudflare, Fastly, Akamai, KeyCDN
• Platforms: GitHub Pages, Netlify, Vercel, Heroku

Example Output:

{
  "domain": "api.example.com",
  "dns_records": {
    "CNAME": "d123abc.cloudfront.net",
    "CLOUD_SERVICE": "AWS-CloudFront",
    "CLOUD_DNS": "AWS-Route53"
  }
}

Geographic DNS Resolution

SubScope can detect geo-specific subdomains that only resolve from certain geographic regions - a capability unique among subdomain enumeration tools.

How It Works

1. EDNS Client Subnet: Uses RFC 7871 extension to simulate queries from different geographic locations
2. HTTP DNS APIs: Leverages Google DNS API with geographic IP simulation
3. Multi-Region Analysis: Compares responses across 6 global regions
4. Difference Detection: Identifies subdomains that resolve differently by region

Supported Regions

• US West Coast (California) - 8.8.8.8
• US East Coast (New York) - 4.2.2.2
• Western Europe (Amsterdam) - 85.10.10.10
• Eastern Europe (Warsaw) - 195.46.39.39
• Asia Pacific (Singapore) - 180.76.76.76
• East Asia (Hong Kong) - 114.114.114.114

Technical Implementation

# Example: Geographic DNS query simulation
# From US West Coast perspective
curl "https://dns.google/resolve?name=cdn.example.com&edns_client_subnet=8.8.8.8/24"
# Returns: us-west-1.cloudfront.net

# From Europe perspective  
curl "https://dns.google/resolve?name=cdn.example.com&edns_client_subnet=85.10.10.10/24"
# Returns: eu-west-1.cloudfront.net

Usage

Geographic DNS analysis can be enabled with the dedicated -g/--geo flag or as part of the complete analysis with -a/--all:

# Enable geographic analysis only (faster)
subscope -d example.com -g
subscope --domain example.com --geo

# Enable geographic analysis as part of complete pipeline
subscope -d example.com -a
subscope --domain example.com --all

# Output includes geographic differences:
# Phase 2.8: Geographic DNS analysis...
# Querying example.com from US-West (US West Coast)...
# Querying example.com from Europe-West (Western Europe)...
# 
# ============================================================
#                 GEOGRAPHIC DNS ANALYSIS
# ============================================================
# 
# 🌍 Results by Region:
#    US-West             : 15 domains
#    Europe-West         : 12 domains
#    Asia-Pacific        : 18 domains
# 
# 🎯 Geographic Differences Detected:
#    cdn-eu.example.com     : [Europe-West, Asia-Pacific]
#    api-us.example.com     : [US-West, US-East]

Benefits

• Complete Coverage: Catches CDN edge domains specific to regions
• Geo-blocked Content: Discovers region-restricted subdomains
• CDN Intelligence: Maps global CDN distribution patterns
• Security Testing: Identifies region-specific attack surfaces

ProxyHawk Enhanced Geographic DNS

SubScope integrates with ProxyHawk for next-generation geographic DNS analysis using real proxy endpoints worldwide instead of EDNS simulation.

Traditional vs ProxyHawk Comparison

Traditional EDNS Method:

• Uses RFC 7871 EDNS Client Subnet extension
• Simulates geographic location via IP subnet hints
• Limited to DNS provider support for EDNS
• May not accurately reflect real-world routing

ProxyHawk Method:

• Uses actual proxy servers in different regions
• Performs real DNS queries from each geographic location
• Bypasses EDNS limitations and DNS provider restrictions
• Provides authentic geographic DNS behavior

ProxyHawk Setup & Deployment

Single Server Setup

# Install ProxyHawk server
go install -v github.com/resistanceisuseless/proxyhawk/cmd/proxyhawk-server@latest

# Basic server startup
proxyhawk-server -port 8080

# Server with specific proxy regions
proxyhawk-server -port 8080 -regions "us-east,us-west,eu-west,asia-pacific"

# Server with custom proxy configuration
proxyhawk-server -config /path/to/proxyhawk-config.yaml

Enterprise Deployment

# Deploy ProxyHawk server with high availability
docker run -d --name proxyhawk-server \
  -p 8080:8080 \
  -e PROXYHAWK_REGIONS="us-east,us-west,eu-west,eu-east,asia-pacific,asia-east" \
  -e PROXYHAWK_PROXY_TIMEOUT=30s \
  resistanceisuseless/proxyhawk:latest

# Load balancer configuration for multiple ProxyHawk instances
# (Configure your load balancer to distribute across multiple ProxyHawk servers)

Advanced ProxyHawk Usage

Custom Region Testing

# Test specific geographic regions only
subscope -d example.com --geo \
  --proxyhawk-url http://proxyhawk.company.com \
  --proxyhawk-regions "us-east,eu-west" \
  --verbose

# Enterprise multi-region analysis  
subscope -d company.com --geo \
  --proxyhawk-url https://proxyhawk-lb.company.com \
  --proxyhawk-regions "us-east,us-west,eu-west,eu-east,asia-pacific,asia-east"

Comparison Analysis

# Run both traditional and ProxyHawk methods for comparison
subscope -d example.com --geo --verbose \
  --proxyhawk-url http://localhost:8080

# Example output:
# [Geographic Analysis - example.com]
# Traditional method: 8 domains, ProxyHawk method: 12 domains  
# Differences found: 3
#   - cdn-us-east.example.com (found via ProxyHawk us-east)
#   - api-eu-central.example.com (found via ProxyHawk eu-west)
#   - cache-asia.example.com (found via ProxyHawk asia-pacific)
# Recommendation: ProxyHawk method provides more comprehensive results

Real-Time Monitoring (Experimental)

# Enable real-time geographic DNS monitoring
subscope -d example.com --geo \
  --proxyhawk-url http://localhost:8080 \
  --proxyhawk-realtime \
  --verbose

# Real-time features (when implemented):
# - Continuous monitoring of geographic DNS changes
# - WebSocket connection for live updates  
# - Alert on new region-specific subdomains
# - Historical tracking of geographic DNS patterns

ProxyHawk Configuration

Client Configuration

ProxyHawk settings can be configured via flags or configuration file:

# ~/.config/subscope/config.yaml
proxyhawk:
  server_url: "http://localhost:8080"
  default_regions: ["us-east", "us-west", "eu-west", "asia-pacific"]
  timeout: 30s
  enable_comparison: true
  realtime_monitoring: false

Server Configuration

ProxyHawk server configuration example:

# /etc/proxyhawk/config.yaml
server:
  port: 8080
  host: "0.0.0.0"

proxy_regions:
  us-east:
    proxy_url: "http://proxy-us-east.company.com:8080"
    location: "US East Coast (Virginia)"
  us-west:
    proxy_url: "http://proxy-us-west.company.com:8080" 
    location: "US West Coast (California)"
  eu-west:
    proxy_url: "http://proxy-eu-west.company.com:8080"
    location: "Europe West (Ireland)"

timeouts:
  dns_query: 10s
  proxy_connect: 5s
  total_request: 30s

ProxyHawk Benefits for Security Testing

1. Bypass Geographic Restrictions: Access region-locked content and subdomains
2. CDN Edge Discovery: Find CDN edge servers in specific regions
3. Infrastructure Mapping: Map global infrastructure distribution
4. Compliance Testing: Verify geographic data residency requirements
5. Security Assessment: Test region-specific attack surfaces
6. Monitoring & Alerting: Detect new geographic deployments

ProxyHawk Use Cases

Bug Bounty & Penetration Testing

# Comprehensive geographic reconnaissance  
subscope -d target.com --all \
  --proxyhawk-url http://proxyhawk-server.local:8080 \
  --proxyhawk-regions "us-east,us-west,eu-west,asia-pacific" \
  --output target_geographic_analysis.json

# Extract region-specific targets
cat target_geographic_analysis.json | \
  jq -r '.resolved_domains[] | select(.geodns.found_in_regions | length < 6) | .domain' \
  > region_specific_targets.txt

Infrastructure Monitoring

# Monitor geographic DNS changes
subscope -d company.com --geo \
  --proxyhawk-url https://internal-proxyhawk.company.com \
  --persistence \
  --new-since $(date -d '1 day ago' +%Y-%m-%d)

# Alert on new geographic subdomains
subscope -d company.com --geo \
  --proxyhawk-url https://internal-proxyhawk.company.com \
  --output - | \
  jq -r '.resolved_domains[] | select(.geodns.found_in_regions | length == 1) | 
    "ALERT: Region-specific subdomain detected: \(.domain) in \(.geodns.found_in_regions[])"'

Performance Optimization

# Identify CDN distribution gaps
subscope -d company.com --geo \
  --proxyhawk-url https://proxyhawk.company.com \
  --output cdn_analysis.json

# Extract missing regions for CDN optimization  
cat cdn_analysis.json | \
  jq -r '.resolved_domains[] | select(.domain | contains("cdn")) | 
    {domain: .domain, missing_regions: .geodns.missing_in_regions} | 
    select(.missing_regions | length > 0)'

Rate Limit Profiles

SubScope includes three built-in rate limit profiles to balance speed and stealth:

Stealth Profile (--profile stealth)

• Rate: 5 requests/second with jitter
• Delays: 1-3 second random delays between requests
• Use Case: Sensitive targets, avoid detection
• Features: User-agent rotation, request jitter, conservative timeouts

Normal Profile (--profile normal)

• Rate: 20 requests/second
• Delays: 100-500ms random delays
• Use Case: Standard authorized testing
• Features: Balanced performance and respect for target infrastructure

Aggressive Profile (--profile aggressive)

• Rate: 100 requests/second with burst capability
• Delays: No artificial delays
• Use Case: Internal testing, authorized high-speed scans
• Features: Maximum concurrency, shorter timeouts

# Example usage
subscope -d example.com --profile stealth --progress
subscope -d example.com --profile aggressive -a

DNS Zone Transfer Detection

SubScope attempts DNS zone transfers (AXFR) early in the enumeration process:

# Example successful zone transfer
Phase 1.1: Zone transfer (AXFR) attempt...
Attempting zone transfer (AXFR) for zonetransfer.me...
Found 2 name servers for zonetransfer.me
Zone transfer successful from nsztm2.digi.ninja - found 35 domains

Features:

• Tests all authoritative name servers
• Proper error handling for REFUSED responses
• Rate limiting integration
• Early detection in enumeration pipeline

Rate Limiting

Configure global rate limits in the config file:

rate_limit:
  global: 10  # requests per second
  jitter: true

Stealth Options

stealth:
  user_agents:
    - "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36..."
    - "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36..."
  random_delay_ms: 100
  request_jitter: true

AlterX Configuration

alterx:
  max_permutations: 10000
  enable_enrichment: true
  patterns:
    - "{{word}}-api"
    - "{{word}}-dev"

Security Considerations

• SubScope is designed for authorized security testing only
• Always ensure you have permission to test target domains
• The tool implements rate limiting and delays to be respectful to target infrastructure
• User-agent rotation helps avoid detection but should not be used for malicious purposes

Version Management

SubScope follows semantic versioning (SemVer):

Version Format: MAJOR.MINOR.PATCH

• MAJOR: Breaking changes, incompatible API changes
• MINOR: New features, backwards compatible
• PATCH: Bug fixes, backwards compatible

Checking Version

subscope --version

Version Information

• Development builds show: 1.0.0 (dev build)
• Release builds show: 1.0.0 (abc1234, built 2025-01-31T10:30:00Z)
• JSON output includes version in metadata for automation

Building with Version Information

# Use build script for proper version injection
./build.sh

# Or specify custom version
./build.sh 1.2.3

# Manual build with version injection
go build -ldflags "-X main.Version=1.2.3 -X main.BuildDate=$(date -u +%Y-%m-%dT%H:%M:%SZ) -X main.GitCommit=$(git rev-parse --short HEAD)" -o subscope cmd/subscope/*.go

Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.

Version Updates: When submitting changes, update the version in:

• cmd/subscope/version.go (primary source)
• internal/output/output.go (keep in sync)
• VERSION file (for build script)

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built on top of excellent tools from ProjectDiscovery
• Inspired by the need for comprehensive subdomain enumeration with intelligent filtering
• Thanks to the security community for feedback and suggestions