Skip to content

bolaji-ai/sectools

BranchesTags

Repository files navigation

Subrecon - Comprehensive Domain Security Scanner

Subrecon is a powerful Go-based reconnaissance and vulnerability assessment tool that helps security teams discover and analyze their attack surface. It's designed to solve the critical problem of "what you don't know can hurt you" by systematically mapping out all digital assets associated with your domains and identifying potential security risks.

What Problem Does This Solve?

Modern organizations often lose track of their digital footprint. Old subdomains, forgotten staging environments, and abandoned services create security blind spots that attackers love to exploit. Subrecon addresses several critical security challenges:

  • Shadow IT Discovery: Finds forgotten subdomains and services that your team might not even know exist
  • Subdomain Takeover Prevention: Identifies abandoned subdomains pointing to services you no longer control
  • Attack Surface Mapping: Creates a comprehensive inventory of all discoverable assets
  • Vulnerability Assessment: Scans discovered assets for common security issues
  • Compliance Reporting: Provides detailed reports for security audits and compliance requirements

What Vulnerabilities Does It Catch?

Subrecon is designed to identify the most common and dangerous web application security issues:

Critical Vulnerabilities

  • Subdomain Takeovers: Detects domains pointing to services you no longer control (AWS S3, Azure, Heroku, etc.)
  • Dangling DNS Records: Finds DNS entries pointing to non-existent or expired services
  • Certificate Issues: Identifies expired, self-signed, or misconfigured SSL certificates

High-Risk Issues

  • Open Ports: Discovers exposed services that shouldn't be public
  • Technology Stack Exposure: Identifies outdated or vulnerable software versions
  • HTTP Security Headers: Missing security headers that protect against common attacks
  • SSL/TLS Vulnerabilities: Weak encryption, outdated protocols, and certificate problems

Medium-Risk Findings

  • Information Disclosure: Exposed configuration files, backups, or sensitive data
  • Directory Listings: Web servers showing file listings instead of proper pages
  • Default Credentials: Services running with default passwords or configurations
  • CORS Misconfigurations: Cross-origin resource sharing issues

How It Works - The Complete Process

Subrecon follows a systematic approach to domain security assessment:

1. Subdomain Discovery Phase

The scanner starts by gathering subdomains using multiple techniques:

  • Passive DNS: Queries public DNS databases and certificate transparency logs
  • Bruteforce: Tests common subdomain patterns against the target domain
  • Certificate Scraping: Extracts subdomains from SSL certificates
  • Search Engine Dorking: Uses search engines to find indexed subdomains

2. Asset Validation Phase

Once subdomains are discovered, Subrecon validates each one:

  • DNS Resolution: Confirms the subdomain resolves to an IP address
  • HTTP Probing: Tests if web services are running on standard ports
  • Port Scanning: Discovers what services are actually running
  • Technology Detection: Identifies web servers, frameworks, and platforms

3. Vulnerability Assessment Phase

For each validated asset, the scanner performs security checks:

  • Subdomain Takeover Tests: Checks if domains point to unclaimed services
  • SSL Certificate Analysis: Examines certificate validity and configuration
  • HTTP Security Analysis: Tests for missing security headers and configurations
  • Nuclei Template Scanning: Runs community vulnerability templates

4. Reporting and Analysis Phase

Finally, Subrecon compiles all findings into actionable reports:

  • Risk Scoring: Assigns severity levels based on exploitability and impact
  • Executive Summary: High-level overview for management and stakeholders
  • Technical Details: Detailed findings for security teams to act on
  • Remediation Guidance: Step-by-step instructions to fix identified issues

Core Components and Architecture

The Enumeration Engine (internal/enumeration/)

This is the heart of subdomain discovery. It orchestrates multiple subdomain enumeration tools:

  • Subfinder Integration: Leverages 40+ passive sources for subdomain discovery
  • Custom Algorithms: Implements additional discovery methods for comprehensive coverage

The Validation System (internal/validation/)

Ensures discovered assets are real and reachable:

  • DNS Validation: Confirms subdomains resolve to valid IP addresses
  • HTTP Verification: Tests web service availability and response codes
  • Certificate Extraction: Pulls SSL certificate details for analysis

The Detection Framework (internal/detection/)

Identifies security vulnerabilities in discovered assets:

  • Dangling DNS Detection: Finds domains pointing to non-existent services
  • HTTP Security Analysis: Checks for missing security headers and misconfigurations
  • Pattern Matching: Uses signature-based detection for known vulnerability patterns

The Integration Layer (internal/integrations/)

Provides seamless integration with external security tools:

  • Nuclei Wrapper: Executes community vulnerability templates
  • Subjack Integration: Specialized subdomain takeover detection
  • SSLScan Integration: Comprehensive SSL/TLS security analysis
  • Nmap SSL Scripts: Fast SSL/TLS vulnerability detection

The Scanning Orchestrator (internal/scanner/)

Coordinates the entire scanning process:

  • Multi-domain Support: Efficiently handles scanning multiple domains simultaneously
  • Resource Management: Controls memory usage and concurrent operations
  • Progress Tracking: Provides real-time feedback on scan progress
  • Error Handling: Gracefully handles failures and network issues

The Reporting Engine (internal/reporting/)

Transforms raw scan data into useful reports:

  • JSON Reports: Machine-readable output for automation and integration
  • HTML Executive Reports: Beautiful, stakeholder-friendly summaries
  • Risk Assessment: Intelligent scoring based on vulnerability type and context
  • Remediation Guidance: Actionable steps to fix identified issues

How Everything Ties Together

The magic happens in how these components work together seamlessly:

  1. The CLI (cmd/subrecon/) receives your command and validates the input
  2. The Configuration System loads settings and prepares the scanning environment
  3. The Scanner Orchestrator creates a scanning plan and coordinates all components
  4. The Enumeration Engine discovers all subdomains using multiple techniques
  5. The Validation System confirms which assets are real and accessible
  6. The Integration Layer runs specialized tools against validated assets
  7. The Detection Framework analyzes results to identify vulnerabilities
  8. The Reporting Engine compiles everything into useful reports

This orchestrated approach ensures comprehensive coverage while maintaining performance and reliability. Each component is designed to work independently but contributes to a greater whole - giving you complete visibility into your domain's security posture.

Real-World Example: What You'll See

When you run Subrecon against a domain, here's what happens behind the scenes:

./subrecon scan example.com --full --verbose

Discovery Phase: The tool finds subdomains like:

  • api.example.com (Active API endpoint)
  • staging.example.com (Forgotten staging environment)
  • old-blog.example.com (Abandoned WordPress site)
  • admin.example.com (Management interface)

Validation Phase: It checks which ones are actually live:

  • api.example.com ✅ Responds on port 443
  • staging.example.com ✅ Responds on port 80 and 443
  • old-blog.example.com ❌ DNS points to non-existent AWS S3 bucket
  • admin.example.com ✅ Responds but shows login page

Vulnerability Assessment: The scanner identifies issues:

  • old-blog.example.com 🚨 CRITICAL: Subdomain takeover possible (can be hijacked)
  • staging.example.com ⚠️ HIGH: Exposed staging environment with debug info
  • admin.example.com ⚠️ MEDIUM: Admin interface accessible without rate limiting
  • api.example.com ✅ LOW: Minor SSL configuration issue

Report Generation: You get actionable reports showing:

  • Executive summary for your CISO
  • Technical details for your security team
  • Step-by-step remediation instructions
  • Risk scores and business impact assessments

Features

  • Complete Asset Discovery: Enumerates subdomains, ports, services, and certificates
  • Multi-Vector Vulnerability Detection: Uses proven OSS tools (Subfinder, Subjack, Nuclei)
  • Business-Ready Reports: JSON and HTML reports with remediation guidance
  • Automation-Friendly: Non-zero exit codes for CI/CD integration
  • Performance Optimized: Memory-efficient processing for enterprise-scale scans

Quick Start

Prerequisites

Install the required external tools:

# Subfinder for subdomain enumeration
go install -v github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest

# Subjack for subdomain takeover detection
go install github.com/haccer/subjack@latest

# Optional: Additional tools for enhanced scanning
go install -v github.com/projectdiscovery/nuclei/v2/cmd/nuclei@latest

Installation

# Clone the repository
git clone https://github.com/cohere-ai/bolaji-s-redteam-tools.git
cd bolaji-s-redteam-tools

# Build the binary
go build -o subrecon ./cmd/subrecon

# Or install directly
go install ./cmd/subrecon

Basic Usage

# Scan a single domain
./subrecon scan example.com

# Scan multiple domains
./subrecon scan example.com test.com

# Scan with custom configuration
./subrecon scan example.com --workers 100 --format json --verbose

# Full scan with all features
./subrecon scan example.com --full --nuclei --sslscan --nmap

Advanced Usage Examples

# Quick DNS-only scan
./subrecon scan example.com --no-port-scan --no-tech-stack

# Comprehensive security audit
./subrecon scan example.com --full --min-severity LOW --verbose

# CI/CD integration
./subrecon scan example.com --format json --output-dir ./security-reports

Configuration

Create a configuration file at ~/.subrecon/subrecon.yaml:

# Scan settings
timeout: 30m
max_memory_mb: 4096
workers: 50
output_dir: "./results"

# Feature flags
enable_port_scan: true
enable_dns_sec: true
enable_tech_stack: true

# DNS configuration
dns:
  resolvers: ["1.1.1.1", "8.8.8.8", "9.9.9.9"]
  retries: 3
  timeout: 5s

# Rate limiting
rate_limit:
  dns_queries_per_second: 100
  http_requests_per_second: 50

# Reporting
reporting:
  format: "both" # json, html, both
  min_severity: "MEDIUM"

Output Examples

Exit Codes

  • 0: No critical vulnerabilities found
  • 1: Critical vulnerabilities detected (subdomain takeovers)
  • 2: High-risk vulnerabilities found
  • 3: Configuration or runtime errors

JSON Report Structure

{
  "scan_metadata": {
    "tool_version": "1.0.0",
    "scan_date": "2025-01-15T10:30:00Z",
    "domains_scanned": ["example.com"],
    "total_assets": 1250,
    "scan_duration": "5m32s"
  },
  "executive_summary": {
    "overall_risk_level": "HIGH",
    "critical_findings": 2,
    "high_findings": 5,
    "business_risk_score": 8.5,
    "estimated_financial_risk": "$10K-100K"
  },
  "findings": {
    "critical": [
      {
        "domain": "admin.example.com",
        "type": "subdomain-takeover",
        "service": "aws-s3",
        "confidence": 0.95,
        "remediation": {
          "steps": ["Remove CNAME record", "Verify resolution"],
          "timeline": "IMMEDIATE",
          "responsible_team": "DevOps"
        }
      }
    ]
  }
}

Architecture

subrecon/
├── cmd/subrecon/           # CLI entry point
├── internal/
│   ├── enumeration/        # Subdomain discovery
│   ├── validation/         # DNS validation
│   ├── detection/          # Vulnerability detection
│   ├── integrations/       # OSS tool wrappers
│   ├── reporting/          # Report generation
│   └── scanner/            # Main orchestrator
├── pkg/models/             # Data structures
└── config/                 # Configuration files

Development

Running Tests

# Unit tests
go test ./...

# Integration tests (requires external tools)
go test ./test/integration/...

# With coverage
go test -cover ./...

Building

# Development build
go build -o subrecon ./cmd/subrecon

# Production build with optimizations
go build -ldflags="-s -w" -o subrecon ./cmd/subrecon

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

License

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

Support

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages