🔍 ExpertRecon v2

ExpertRecon is a professional-grade attack surface management toolkit designed for security assessments, penetration testing, and threat intelligence gathering. It provides a modular, extensible framework for comprehensive reconnaissance.

---

✨ Features

🔌 Reconnaissance Modules

• Nmap Integration - Service detection, version scanning, and script scanning
• Subdomain Enumeration - via crt.sh, subfinder, and Certificate Transparency
• SSL/TLS Analysis - Certificate validation, expiry checks, TLS version detection
• HTTP Headers Analysis - Security headers grading, fingerprinting, recommendations
• Technology Detection - Wappalyzer-style CMS/framework identification
• WHOIS Lookup - Domain registration and ownership data
• Web Screenshots - Headless browser captures via Playwright
• theHarvester - Email and host discovery
• DNSRecon - DNS enumeration and zone transfer detection

🌐 OSINT API Integrations

• Shodan - Internet-wide scanning data
• Censys - Certificate and host intelligence
• SecurityTrails - DNS history and subdomain discovery
• VirusTotal - Domain/IP reputation and threat data
• AlienVault OTX - Threat intelligence pulses
• Hunter.io - Email discovery and verification
• FOFA - Chinese cyber asset search
• Driftnet - Asset intelligence

🛡️ CVE Correlation

• Enhanced CVE Matching - CPE-based correlation with confidence scoring
• NVD Integration - Official NIST vulnerability data with CVSS 3.1
• ExploitDB Lookup - Known exploit and PoC detection
• Severity Classification - Critical/High/Medium/Low filtering

📊 Reporting

• Interactive HTML Reports - Modern, responsive design with charts
• Markdown Reports - GitHub-compatible documentation
• STIX 2.1 Export - Threat intelligence sharing format
• JSON/CSV Export - Structured data output

⚡ Scan Profiles

Profile	Description	Use Case
quick	Fast surface scan	Initial assessment
full	Comprehensive deep scan	Complete audit
stealth	Passive reconnaissance	Covert OSINT
web	Web application focused	Web app testing
osint	OSINT-only, no active scans	Intelligence gathering
vuln	Vulnerability focused	CVE hunting
minimal	Essential modules only	Quick check

---

🚀 Installation

Prerequisites

• Python 3.9 or higher
• Nmap installed and in PATH
• Optional: theHarvester, dnsrecon, subfinder

Quick Install

# Clone the repository
git clone https://github.com/Masriyan/ExpertRecon.git
cd ExpertRecon

# Install dependencies
pip install -r requirements.txt

# Optional: Install Playwright for screenshots
playwright install chromium

# Verify installation
python -m expertrecon --version

Configuration

1. Copy the example configuration:

cp config.example.yaml config.yaml

2. Add your API keys in config.yaml:

api_keys:
  shodan_key: "your-shodan-api-key"
  virustotal_key: "your-vt-api-key"
  # ... more keys

Or set them as environment variables:

export SHODAN_KEY="your-shodan-api-key"
export VIRUSTOTAL_KEY="your-vt-api-key"

---

📖 Usage

Basic Scans

# Quick scan
python -m expertrecon example.com

# Full comprehensive scan
python -m expertrecon example.com --profile full

# Web-focused scan with HTML report
python -m expertrecon example.com --profile web --html

# OSINT-only (passive) scan
python -m expertrecon example.com --profile osint

Module Selection

# Enable specific modules
python -m expertrecon example.com --modules nmap subdomain ssl

# Enable OSINT APIs
python -m expertrecon example.com --shodan --virustotal

# Enable all configured OSINT APIs
python -m expertrecon example.com --all-osint

Reports

# Generate HTML report
python -m expertrecon example.com --html

# Generate Markdown report
python -m expertrecon example.com --markdown

# Export as STIX 2.1
python -m expertrecon example.com --stix

# All report formats
python -m expertrecon example.com --html --markdown --stix

Multi-Target Scanning

# Scan from file (one target per line)
python -m expertrecon targets.txt --profile quick --parallel 10

CLI Options

python -m expertrecon --help

Option	Description
--profile, -p	Use predefined scan profile
--modules	Enable specific modules
--parallel, -j	Parallel targets (default: 5)
--timeout	Default timeout in seconds
--export-dir, -o	Output directory
--config, -c	YAML configuration file
--html	Generate HTML report
--markdown, --md	Generate Markdown report
--stix	Export as STIX 2.1
--shodan, --censys, etc.	Enable specific OSINT APIs
--all-osint	Enable all configured APIs
--nvd	Use NVD for enhanced CVE data
--exploitdb	Check ExploitDB for exploits
--debug	Enable debug logging
--quiet, -q	Minimal output

---

📁 Output Structure

exports/
└── example.com/
    ├── results.json        # Full structured results
    ├── summary.csv         # Service summary
    ├── report.html         # Interactive HTML report
    ├── report.md           # Markdown report
    ├── findings.stix.json  # STIX 2.1 bundle
    └── screenshot.png      # Web screenshot (if captured)

---

🏗️ Architecture

expertrecon/
├── __init__.py         # Package exports
├── __main__.py         # Entry point
├── cli.py              # Command-line interface
├── config.py           # Configuration management
├── core/
│   ├── engine.py       # Reconnaissance orchestrator
│   ├── session.py      # HTTP session manager
│   └── utils.py        # Utility functions
├── modules/
│   ├── base.py         # Abstract module class
│   ├── nmap.py         # Nmap integration
│   ├── subdomain.py    # Subdomain enumeration
│   ├── ssl_analyzer.py # SSL/TLS analysis
│   ├── headers.py      # HTTP headers analysis
│   ├── tech_detect.py  # Technology detection
│   ├── whois_lookup.py # WHOIS lookups
│   ├── screenshot.py   # Web screenshots
│   ├── harvester.py    # theHarvester integration
│   └── dnsrecon.py     # DNSRecon integration
├── osint/
│   ├── shodan.py       # Shodan API
│   ├── censys.py       # Censys API
│   ├── virustotal.py   # VirusTotal API
│   ├── securitytrails.py
│   ├── alienvault.py   # AlienVault OTX
│   ├── hunter.py       # Hunter.io
│   ├── fofa.py         # FOFA API
│   └── driftnet.py     # Driftnet API
├── correlation/
│   ├── cve_matcher.py  # CVE correlation engine
│   ├── nvd.py          # NVD API
│   └── exploitdb.py    # ExploitDB integration
├── reporting/
│   ├── html_report.py  # HTML report generator
│   ├── markdown_report.py
│   └── stix_export.py  # STIX 2.1 exporter
└── profiles/
    └── scan_profiles.py # Predefined scan profiles

---

🔒 Security & Ethics

⚠️ Important: ExpertRecon is designed for authorized security testing only.

• Always obtain proper authorization before scanning
• Respect rate limits on external APIs
• Follow responsible disclosure practices
• Safe mode is enabled by default

---

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Submit a pull request

---

📜 License

MIT License - See LICENSE for details.

---

🙏 Credits

Built with ❤️ by sudo3rs

Special thanks to the developers of:

• Nmap, theHarvester, dnsrecon, subfinder
• Shodan, Censys, VirusTotal, SecurityTrails, AlienVault OTX
• The open-source security community

---

⭐ Star this repo if you find it useful!