VIPRecon - Professional Web Reconnaissance Tool

Developed by viphacker100 (Aryan Ahirwar)

A comprehensive web application reconnaissance and security testing tool designed for ethical security professionals. VIPRecon provides automated scanning capabilities to identify technologies, vulnerabilities, and security misconfigurations in web applications.

🐛 Bug Fixes & Updates

Latest Updates (v1.1.0):

• New: Advanced usage documentation with real-world examples
• New: GitHub Actions CI/CD pipeline with multi-Python version testing
• New: Enhanced Docker support with Python 3.13 and security improvements
• New: Complete pyproject.toml with proper packaging metadata
• Fixed RateLimiter implementation with proper token bucket algorithm
• Improved path traversal detection in URL validation
• Enhanced HTTP client error handling and type safety
• All unit tests now passing (15/15)
• Improved resilience with checkpoint/resume functionality

⚠️ Legal Disclaimer

IMPORTANT: This tool is designed for authorized security testing only. Unauthorized access to computer systems is illegal. Users must:

• Have explicit written permission to test target systems
• Comply with all applicable laws and regulations
• Use this tool responsibly and ethically
• Not use this tool for malicious purposes

The developers assume no liability for misuse of this tool.

🚀 Features

VIPRecon includes 11 major reconnaissance and security testing modules:

Reconnaissance Modules

1. Basic Information Gathering - HTTP headers, WHOIS, DNS records, SSL certificate info
2. Advanced Fingerprinting - Technology detection (CMS, frameworks, libraries, servers)
3. Subdomain Enumeration - DNS brute-force, certificate transparency, search engine discovery
4. WAF Detection - Identify web application firewalls (Cloudflare, AWS WAF, etc.)
5. API Endpoint Discovery - Find REST APIs, GraphQL endpoints, Swagger/OpenAPI specs

🛡️ Security Testing

• Port Scanner: identifies open services and potential entry points.
• Directory Discovery: Brute-forces common paths to find hidden files and panels.
• Vulnerability Scanner: XSS, SQLi, Open Redirects, Path Traversal.
• CORS Checker: Misconfiguration detection.
• JS Analyzer: Sensitive data extraction (API keys, endpoints).
• Security Headers: Audit of security configurations.

🚀 Advanced Features

• Checkpoint & Resume: Mission-critical resilience; resume any scan exactly where it left off.
• Webhooks: Notify completion to Slack or Discord.
• Diff Tool: Compare scan results over time.
• Interactive Shell: Post-scan result exploration.

📋 Requirements

• Python 3.8+ or Python 3.13+ (recommended)
• pip (Python package manager)
• Internet connection (for external lookups)
• Windows/Linux/Mac OS support

🔧 Installation

Quick Install

# Clone the repository
git clone https://github.com/VIPHACKER100/VIPRecon.git
cd VIPRecon

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On Windows:
venv\Scripts\activate
# On Linux/Mac:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Docker Installation

# Build Docker image
docker build -t viprecon .

# Run with Docker
docker run -v $(pwd)/output:/app/output viprecon -t https://example.com

🎯 Quick Start

Basic Scan

# Full scan with reports
python main.py -t https://example.com -o ./results -f both

This will:

• Run all modules against the target
• Generate both JSON and HTML reports
• Save results to ./output/ directory

Scan Specific Modules

python main.py -t example.com -m fingerprint,subdomain_enum,vuln_scan

Custom Rate Limit

python main.py -t example.com --rate-limit 0.5

Using a Proxy

python main.py -t example.com --proxy http://127.0.0.1:8080

Checkpoint & Resume Usage

VIPRecon automatically saves progress after each module completes. If a scan is interrupted, you can resume exactly where it left off:

# Resume using the target domain
python main.py -t example.com --resume example.com

# Resume using a specific checkpoint file
python main.py -t example.com --resume ./output/checkpoint_example.com.json

Features:

• Automatic checkpoint creation after each module
• Resume from any interruption (network issues, crashes, user cancel)
• Checkpoint cleanup on successful completion
• JSON-based checkpoint format for easy inspection

Notification and Diff Usage

# Enable Slack notifications
python main.py -t example.com --webhook SLACK_URL --webhook-service slack

# Compare two previous scan results
python main.py --diff results/scan1.json,results/scan2.json

# Interactive mode
python main.py -t example.com --interactive

🚀 Advanced Usage Commands

Comprehensive Security Assessment

Perform a full security audit with all features enabled:

# Full scan with authentication, custom wordlist, and notifications
python main.py -t https://example.com \
  --auth-type bearer \
  --auth-token "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  --wordlist custom_wordlist.txt \
  --rate-limit 2 \
  --timeout 45 \
  --proxy http://127.0.0.1:8080 \
  -o ./security_audit \
  -f both \
  --webhook https://hooks.slack.com/services/YOUR/WEBHOOK/URL \
  --webhook-service slack

Integration with Security Tools

Burp Suite Professional Integration

# Route traffic through Burp Suite for manual analysis
python main.py -t example.com \
  --proxy http://127.0.0.1:8080 \
  --no-verify-ssl \
  -m basic_info,fingerprint,api_discovery \
  -o ./burp_analysis

OWASP ZAP Integration

# Scan with ZAP as proxy for active scanning
python main.py -t example.com \
  --proxy http://localhost:8090 \
  --rate-limit 0.5 \
  -v

Stealth and Evasion Techniques

# Slow, stealthy scan with custom user agent
python main.py -t example.com \
  --rate-limit 0.2 \
  --timeout 60 \
  --user-agent "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36" \
  --no-verify-ssl \
  -o ./stealth_scan

# Scan with randomized delays (implement via config)
python main.py -t example.com \
  --rate-limit 0.1 \
  --timeout 90

Targeted Module Combinations

API Security Testing

# Focus on API discovery and testing
python main.py -t api.example.com \
  -m api_discovery,vuln_scan,cors_check,security_headers \
  --auth-type bearer \
  --auth-token "Bearer YOUR_API_TOKEN" \
  -o ./api_security

Infrastructure Reconnaissance

# Deep infrastructure analysis
python main.py -t example.com \
  -m basic_info,subdomain_enum,port_scan,waf_detect,fingerprint \
  --wordlist large_subdomains.txt \
  -o ./infrastructure

Web Application Penetration Testing

# Comprehensive web app testing
python main.py -t example.com \
  -m fingerprint,vuln_scan,cors_check,js_analysis,security_headers,dir_brute \
  --wordlist common_paths.txt \
  --rate-limit 1.5 \
  -o ./webapp_test

Batch Scanning Multiple Targets

# Create a targets file
cat targets.txt
https://target1.com
https://target2.com
https://target3.com

# Scan each target (using bash loop)
while read target; do
  python main.py -t "$target" \
    -o "./results/$(echo $target | sed 's/[^a-zA-Z0-9]/_/g')" \
    --rate-limit 1
done < targets.txt

Advanced Diff and Comparison

# Compare scans from different dates
python main.py --diff \
  ./results/scan_2024-01-01.json,./results/scan_2024-02-01.json \
  -o ./diff_report

# Track changes over time with automated naming
python main.py -t example.com \
  -o "./results/$(date +%Y-%m-%d)_scan" \
  --webhook SLACK_URL

Docker Advanced Usage

# Run with mounted volume for persistent output
docker run -it --rm \
  -v $(pwd)/output:/app/output \
  -v $(pwd)/wordlists:/app/wordlists \
  viprecon:latest \
  -t example.com \
  --wordlist /app/wordlists/custom.txt \
  -o /app/output/scan_results

# Run with custom config
docker run -it --rm \
  -v $(pwd)/config:/app/config \
  -v $(pwd)/output:/app/output \
  viprecon:latest \
  -t example.com \
  --config /app/config/custom_config.yaml

Performance Optimization

# Fast scan for large scope (increase rate limit cautiously)
python main.py -t example.com \
  --rate-limit 5 \
  --timeout 15 \
  --max-retries 1 \
  -m basic_info,fingerprint \
  -o ./quick_scan

# Distributed scanning (multiple instances with different modules)
# Terminal 1: Infrastructure
python main.py -t example.com -m subdomain_enum,port_scan -o ./infra &

# Terminal 2: Web Application
python main.py -t example.com -m vuln_scan,js_analysis -o ./webapp &

# Terminal 3: API Testing
python main.py -t example.com -m api_discovery,cors_check -o ./api &

wait

Automated Reporting and Analysis

# Generate report and auto-open
generate_report() {
  python main.py -t "$1" -o "$2" -f both
  echo "Scan complete. Reports generated at $2"
  # Auto-open HTML report (macOS)
  open "$2/report.html"
  # For Linux: xdg-open "$2/report.html"
  # For Windows: start "$2\report.html"
}

generate_report "example.com" "./results/$(date +%Y%m%d_%H%M%S)"

CI/CD Pipeline Integration

# Example for GitHub Actions
python main.py -t "$TARGET_URL" \
  -o ./security_scan \
  --rate-limit 2 \
  -f json

# Check for critical vulnerabilities
if grep -q "CRITICAL" ./security_scan/scan_results.json; then
  echo "Critical vulnerabilities found!"
  exit 1
fi

Result Processing with jq

# Extract all high/critical vulnerabilities
python main.py -t example.com -o ./scan -f json
cat ./scan/scan_results.json | jq '.vulnerabilities[] | select(.severity == "HIGH" or .severity == "CRITICAL")'

# Count vulnerabilities by severity
cat ./scan/scan_results.json | jq '[.vulnerabilities[].severity] | group_by(.) | map({severity: .[0], count: length})'

# Extract discovered subdomains
cat ./scan/scan_results.json | jq '.subdomains[].name'

📖 Usage

Command-Line Options

usage: main.py [-h] -t TARGET [-m MODULES] [-o OUTPUT] [-f FORMAT] [-v]
               [--rate-limit RATE_LIMIT] [--timeout TIMEOUT] [--interactive]
               [--proxy PROXY] [--user-agent USER_AGENT] [--wordlist WORDLIST]

VIPRecon - Web Application Reconnaissance Tool

required arguments:
  -t, --target TARGET          Target URL or domain

optional arguments:
  -h, --help                   Show this help message and exit
  -m, --modules MODULES        Comma-separated list of modules to run
                               (default: all)
  -o, --output OUTPUT          Output directory (default: ./output)
  -f, --format FORMAT          Output format: json, html, both (default: both)
  -v, --verbose                Enable verbose logging
  --rate-limit RATE_LIMIT      Requests per second (default: 1)
  --timeout TIMEOUT            Request timeout in seconds (default: 30)
  --interactive                Launch interactive mode after scan
  --proxy PROXY                Proxy URL (e.g., http://127.0.0.1:8080)
  --user-agent USER_AGENT      Custom User-Agent string
  --wordlist WORDLIST          Path to custom wordlist

Available Modules

• basic_info - Basic information gathering
• fingerprint - Technology fingerprinting
• subdomain_enum - Subdomain enumeration
• waf_detect - WAF detection
• api_discovery - API endpoint discovery
• vuln_scan - Vulnerability scanning
• cors_check - CORS misconfiguration check
• js_analysis - JavaScript analysis
• security_headers - Security headers audit
• port_scan - Network port scanning
• dir_brute - Directory discovery

📊 Output Formats

JSON Report

Machine-readable format for integration with other tools:

{
  "scan_metadata": {
    "target": "https://example.com",
    "start_time": "2026-02-12T12:00:00",
    "duration_seconds": 45.2
  },
  "technologies": [...],
  "vulnerabilities": [...],
  "subdomains": [...]
}

HTML Report

Professional, human-readable report with:

• Executive summary
• Vulnerability breakdown by severity
• Technology stack visualization
• Detailed findings with remediation advice

⚙️ Configuration

Edit config/default_config.yaml to customize:

• HTTP client settings (timeout, retries, user-agent)
• Rate limiting parameters
• Module-specific settings
• Output preferences
• Logging configuration

Example configuration:

http:
  timeout: 30
  max_retries: 3
  user_agent: "VIPRecon/1.0"

rate_limit:
  requests_per_second: 1.0

modules:
  vulnerability_scanner:
    check_xss: true
    check_sqli: true

🔐 Authentication

VIPRecon supports scanning authenticated sections:

# Basic Authentication
python -m src.main -t example.com --auth-type basic --auth-username user --auth-password pass

# Bearer Token
python -m src.main -t example.com --auth-type bearer --auth-token YOUR_TOKEN

# Cookie Authentication
python -m src.main -t example.com --auth-type cookie --auth-cookie "session=abc123"

🧪 Testing

Run the test suite:

# Install test dependencies
pip install pytest pytest-asyncio pytest-cov

# Run all tests
pytest

# Run with coverage
pytest --cov=src tests/

# Run specific test file
pytest tests/core/test_http_client.py

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow PEP 8 style guide
• Add tests for new features
• Update documentation as needed
• Ensure all tests pass before submitting PR

📝 License

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

🙏 Acknowledgments

• Lead Developer: viphacker100 (Aryan Ahirwar)
• Built with Python and asyncio for high performance
• Uses industry-standard security testing methodologies
• Inspired by tools like Nmap, Nikto, and OWASP ZAP

📧 Contact

For questions, issues, or feature requests:

• Open an issue on GitHub
• Reach out to viphacker100 (Aryan Ahirwar)
• Email: viphacker.100.org@gmail.com

🗺️ Roadmap

Planned features for future releases:

• Machine learning-based anomaly detection
• GraphQL security testing
• WebSocket vulnerability scanning
• CI/CD pipeline integration
• Centralized dashboard for multiple scans
• Compliance reporting (OWASP Top 10, PCI DSS)

📝 Changelog

v1.1.0 (2026-02-14)

• New: Comprehensive advanced usage examples and documentation
• New: GitHub Actions CI/CD pipeline with automated testing
• New: Docker support with Python 3.13 and security hardening
• New: Professional packaging with pyproject.toml
• New: Code quality tools integration (black, flake8, mypy)
• Improved: Enhanced error handling with contextual tips
• Improved: Diff tool implementation for scan comparison
• Improved: Results display with formatted output
• Improved: Checkpoint saving on interrupt (Ctrl+C)

v1.0.1 (2026-02-13)

• Fixed: RateLimiter token bucket algorithm implementation
• Fixed: Path traversal detection in URL validator
• Fixed: Type safety issues in orchestrator module
• Fixed: HTTP client null reference checks
• Fixed: All unit tests passing (15/15)
• Improved: Checkpoint/resume reliability
• Improved: Error handling across all modules

v1.0.0 (2026-02-12)

• Initial release
• 11 reconnaissance and security testing modules
• JSON and HTML report generation
• Checkpoint and resume functionality
• Webhook notifications (Slack, Discord)
• Interactive shell mode
• Diff tool for comparing scans

---

Remember: Always obtain proper authorization before testing any system you don't own!