🐛 BugScanner

An Advanced, Context-Aware Recon & Automated Web Vulnerability Assessment Framework

Key Features • Architecture • Installation • Usage • Report Preview • Configuration • Roadmap

---

📌 Overview

BugScanner is a modular, high-performance web vulnerability scanner and reconnaissance framework engineered specifically for Bug Bounty Hunters, Red Teams, and Penetration Testers.

Unlike standard passive scanners, BugScanner combines deep subdomain discovery, active TCP service fingerprinting, and a Context-Aware Vulnerability Verification Engine designed to minimize false positives and bypass modern Web Application Firewalls (WAFs) through adaptive rate limiting and jitter control.

🎯 What's New in v2.0

• 🎨 Modern Report UI — Dark/light theme, sidebar navigation, bento-grid KPIs, interactive filters
• 🛡️ SPA-Aware Detection — Detects Single Page Application fallbacks to eliminate false positives
• ⚡ Chunked Port Scanning — Full-range scans with bounded memory (800 MB → 80 MB)
• 🔒 Authenticated Scanning — Native --cookie and --header session preservation
• 🧠 Business Logic Scanner — Mass assignment, price manipulation, rate-limit bypass
• 📊 CVSS v3.1 Scoring — Every finding rated with industry-standard severity
• 🌍 English Interface — Fully internationalized CLI and UI

---

🔥 Key Features

🔍 Phase 1 — Reconnaissance & Discovery

• Subdomain Enumeration — Dual-engine discovery using Certificate Transparency Logs (crt.sh) for passive reconnaissance and Async DNS Bruteforcing (120+ wordlist) for active discovery. Isolated HTTP client prevents the shared rate limiter from stalling enumeration.
• TCP Port Scanner — High-speed asynchronous TCP connect scanning across custom ranges (common, extended, full). Chunked processing keeps memory bounded even on 65K-port scans. Features banner grabbing for service version extraction and security hints.
• Technology Fingerprinting — Identifies web servers, CMSs, backend frameworks, and frontend libraries via HTTP Response Headers, HTML DOM patterns, and Session Cookies.
• Endpoint Discovery — Async path discovery covering 200+ common administration, API (/graphql, /swagger), auth, debug, and backup endpoints (.env, .git/HEAD, actuator/heapdump).

🛡️ Phase 2 — Vulnerability Assessment Engine

• Reflected XSS Scanner — Evaluates parameter reflection in text/html contexts with execution-aware payload sets, lowering noise and false positives.
• SQL Injection (SQLi) Verification — Error-Based detection across 30+ database error patterns (MySQL, PostgreSQL, MSSQL, Oracle, SQLite) and Time-Based Double-Check Verification supporting SLEEP(), WAITFOR DELAY, pg_sleep(), and BENCHMARK() to eliminate network latency false positives.
• CORS Misconfiguration Auditor — Identifies wildcard origins, arbitrary origin reflection, null origin bypass, trusted subdomain bypass, and dangerous Access-Control-Allow-Credentials: true combinations with auto-generated PoC exploits.
• SSRF & Open Redirect — Tests for Cloud Metadata exposure (AWS IMDSv1, GCP, Azure), protocol handler leaks (file://), decimal/hex IP bypasses, and location-header redirection validation.
• JWT Security Auditor — Automates alg: none bypass checks, signature verification, algorithm confusion (RS256 → HS256), weak secret brute-forcing, and payload sensitive-data analysis.
• IDOR & Path Tampering — Evaluates parameter/path numerical shifts, UUID mutations, and HTTP Method Swapping (DELETE/PUT verb tampering) with SPA-aware false positive protection.
• Sensitive Data Exposure — Scans responses for leaked AWS keys, Private RSA keys, GitHub/Stripe/Slack tokens, .git repository exposures, and Directory Listing.
• Nuclei Integration — Seamlessly wraps ProjectDiscovery's nuclei engine (if installed) to execute 9000+ CVE and misconfiguration templates directly into the consolidated report.

🎯 False-Positive Reduction Engine

BugScanner v2.0 introduces a multi-layer verification pipeline to eliminate the most common source of false positives in automated scanning:

Layer	Technique	Problem Solved
SPA Fallback Detection	Probe random nonexistent path; if 200 OK with same body → SPA shell	Every route returns 200 in SPA apps
Body Similarity Check	Compare response bodies (length + prefix) against baseline	Static responses flagged as dynamic data
Fake-404 Baseline	Establish soft-404 fingerprint; filter matching responses	Custom error pages returning 200
Content-Type Sanity	Reject text/html on API endpoints expecting JSON	Fallback page served instead of API data
Real DELETE Verification	Re-fetch after DELETE 200; if resource still exists → false positive	Servers accepting DELETE but not acting
Time-Based Double-Check	3 baseline + 3 payload requests, averaged and threshold-checked	Network latency misread as SQLi delay
Reflection Triple-Check	3 XSS re-checks, minimum 2 must confirm	Cache/CDN inconsistencies

⚡ Resilience & Evasion Capabilities

• Adaptive Token-Bucket Rate Limiter — Dynamically adjusts RPS upon receiving 429 Too Many Requests or 503 Service Unavailable, preventing WAF IP bans.
• WAF Detection & Jitter Engine — Detects Cloudflare, Akamai, AWS WAF, Imperva, Sucuri, F5 BIG-IP, Barracuda, ModSecurity signatures and applies per-WAF evasion strategies (RPS reduction, UA rotation, bypass headers).
• Dynamic Reporting — Generates structured JSON alongside interactive, dark/light-themed HTML reports featuring CVSS v3.1 severity scoring, animated risk metrics, and ready-to-use exploit PoCs.

---

🏗 Architecture

BugScanner uses a modular, asynchronous architecture built on top of asyncio and httpx:

cli.py ──> scanner.py (Orchestrator)
            ├── recon/
            │   ├── subdomain.py         # crt.sh + Async DNS (isolated HTTP client)
            │   ├── portscan.py          # TCP Connect & Banner Grab (chunked)
            │   ├── fingerprint.py       # Headers, DOM & Cookies
            │   └── discovery.py         # Endpoint Bruteforce
            ├── vulns/
            │   ├── xss.py               # Reflected XSS Engine
            │   ├── sqli.py              # Error + Time-Based (multi-DB)
            │   ├── cors.py              # Origin Reflection & Credentials
            │   ├── ssrf.py              # Metadata & Protocol Leaks
            │   ├── redirect.py          # Open Redirect Auditor
            │   ├── jwt.py               # Alg None, Confusion & Weak Secret
            │   ├── idor.py              # Parameter & Verb Tampering (SPA-aware)
            │   ├── disclosure.py        # Token & Key RegEx Extractor
            │   ├── business_logic.py    # Mass Assignment, Price Manipulation
            │   └── nuclei_wrapper.py    # Native Nuclei CLI Wrapper
            └── core/
                ├── rate_limiter.py      # Adaptive RPS & Jitter
                ├── http_client.py       # Async HTTP Wrapper (auth + proxy)
                ├── models.py            # Dataclasses & CVSS Scoring
                ├── validator.py         # False-Positive Validator
                ├── waf_detector.py      # WAF Signature Engine
                └── reporter.py          # JSON & Jinja2 HTML Generator

frontend/                            # React + Vite dashboard
            ├── src/
            │   ├── App.jsx              # Main shell + tab navigation
            │   └── components/
            │       ├── Scanner.jsx      # Scan configuration form
            │       ├── Results.jsx      # Live results with WebSocket
            │       └── History.jsx      # Past scan browser

reports/
            ├── template.html            # Main HTML report
            ├── _styles.html             # Embedded CSS
            └── _scripts.html            # Embedded JS

---

🚀 Installation

Prerequisites

• Python 3.11+ — download
• Git — download
• (Optional) Nuclei for CVE template scanning — install guide
• (Optional) Node.js 20+ for the web dashboard — download

Setup

# 1. Clone the repository
git clone https://github.com/eldarshiraliyev/BugScanner.git
cd BugScanner

# 2. Create and activate a virtual environment
python -m venv venv

# Windows (PowerShell)
.\venv\Scripts\Activate.ps1

# macOS / Linux
source venv/bin/activate

# 3. Install dependencies
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

# 4. Verify installation
python cli.py version

Expected output:

BugScanner v2.0
Bug Bounty Automation Tool
Authorized use only

---

🚀 Usage

CLI — Basic Scans

# Full comprehensive scan (recon + vulnerabilities)
python cli.py scan https://target.com

# Reconnaissance only
python cli.py scan https://target.com --mode recon

# Vulnerability audit only (skip recon)
python cli.py scan https://target.com --mode vulns

# Custom port scan without subdomain enumeration
python cli.py scan https://target.com --no-subdomains --ports extended

# Adjust adaptive rate limit
python cli.py scan https://target.com --rps 5

# Export to JSON only
python cli.py scan https://target.com --format json

CLI — Authenticated Scans

# Session cookie authentication
python cli.py scan https://target.com \
  --cookie "session=abc123" \
  --cookie "csrf=xyz789"

# Bearer token
python cli.py scan https://target.com \
  --header "Authorization: Bearer eyJhbGciOi..."

# Burp Suite proxy + business logic scan
python cli.py scan https://target.com \
  --cookie "session=abc123" \
  --proxy http://127.0.0.1:8080 \
  --business-logic

CLI — Fast / Careful Scans

# Fast scan — disable FP validation, higher RPS
python cli.py scan https://target.com \
  --no-subdomains \
  --no-fp-validation \
  --rps 20

# WAF-protected target — slow and careful
python cli.py scan https://target.com \
  --rps 3 \
  --no-subdomains \
  --ports common

CLI — Specialized Commands

# Recon only
python cli.py recon https://target.com --ports extended

# Vulnerability scan only (with auth)
python cli.py vulnscan https://target.com --cookie "session=abc123"

# Business logic scan only
python cli.py bizlogic https://target.com --cookie "session=abc123"

# Show version
python cli.py version

Web Dashboard

# Backend API + frontend
python app.py
# Open http://localhost:8000

The dashboard provides:

• Live scan progress via WebSocket
• Interactive vulnerability browser with severity filters
• Historical scan comparison
• Direct report download

---

📊 CLI Reference

Option	Description	Default
target	Target URL (e.g., https://target.com)	Required
--mode, -m	Scan mode: all, recon, vulns	all
--ports, -p	Port scan range: common, extended, full	common
--rps	Initial Requests Per Second limit	10
--no-subdomains	Skip subdomain enumeration	False
--no-fp-validation	Disable false-positive validation	False
--no-nuclei	Skip Nuclei scan	False
--business-logic	Enable business logic scan	False
--cookie, -c	Session cookie (name=value, repeatable)	—
--header, -H	Custom header (Name: Value, repeatable)	—
--proxy	HTTP proxy (e.g., Burp Suite)	—
--output, -o	Report output directory	./reports
--format, -f	Report format: all, json, html	all

---

🎨 Report Preview

The v2.0 HTML report features a completely redesigned 2026-era interface:

• 🌗 Dark / Light Theme — Toggleable, persists via localStorage
• 📊 Bento-Grid KPIs — Risk score ring, vulnerability bars, recon surface, scan duration
• 🧭 Sidebar Navigation — Auto-highlights current section while scrolling
• 🔎 Live Search & Filters — Chip-based severity filter + text search across title, URL, CWE
• ⚡ Copy-to-Clipboard PoCs — One-click copy for every curl proof-of-concept
• 🖨️ Print Stylesheet — Clean printable output (expands all collapsed sections)
• 📥 JSON Export — Download the raw scan data directly from the report

The report is fully self-contained — no external CDN dependencies, works completely offline.

---

⚙️ Configuration

The settings.yaml file at the project root controls global behavior:

rate_limiting:
  default_rps: 10           # requests per second
  min_rps: 1
  max_rps: 50
  backoff_multiplier: 2
  pause_on_503: 30          # seconds

scanning:
  timeout: 10               # seconds per request
  max_redirects: 5
  user_agent: "Mozilla/5.0 (compatible; BugScanner/2.0)"
  verify_ssl: false

ports:
  common: [21, 22, 23, 25, 53, 80, 110, 143, 443, 445, 3306, 3389, 5432, 6379, 8080, 8443, 8888, 9200, 27017]
  extended: [20, 21, 22, 23, 25, 53, 80, 110, 111, 135, 139, 143, 443, 445, 993, 995, 1723, 3306, 3389, 5432, 5900, 6379, 8080, 8443, 8888, 9200, 27017]

nuclei:
  enabled: true
  templates_path: "~/.local/nuclei-templates"
  severity: ["critical", "high", "medium", "low"]
  rate_limit: 150

output:
  default_format: ["terminal", "json", "html"]
  reports_dir: "./reports"

Risk Assessment

Findings are rated using the CVSS v3.1 framework:

Severity	CVSS Score	Example Vulnerabilities
🔴 CRITICAL	9.0 – 10.0	SQLi, RCE, SSRF with Cloud Metadata, Weak JWT Secret
🟠 HIGH	7.0 – 8.9	Reflected XSS, Unauthenticated IDOR, CORS with Credentials, .git Exposure
🟡 MEDIUM	4.0 – 6.9	Reflected XSS (Restricted), Open Redirect, Wildcard CORS
🔵 LOW	1.0 – 3.9	Missing Security Headers, Server Version Disclosure
⚪ INFO	0.0 – 0.9	Technology Fingerprint, Port Banner Discovery

---

🗺 Roadmap

• ✅ Authenticated Scope Scanning — --cookie and --header session preservation
• ✅ Modern Report UI — Dark/light theme, interactive filters
• ✅ SPA-Aware IDOR Detection — Multi-layer false-positive reduction
• ✅ Chunked Port Scanning — Full 1–65535 range without memory blowup
• ⬜ Multi-Role IDOR Diff Engine — Automated differential testing between User A and User B session tokens
• ⬜ Headless DOM Analysis — Playwright integration for Blind XSS and SPA route extraction
• ⬜ PyPI Package Release — pip install bugscanner
• ⬜ Docker Compose — One-command deployment with optional Nuclei bundled
• ⬜ SARIF Export — GitHub Security tab integration
• ⬜ Plugin System — User-defined scanner modules

---

🤝 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 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please follow the existing code style and include tests for new features.

---

📜 License

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

---

⚠️ Disclaimer

IMPORTANT: This tool is developed for educational purposes, defensive auditing, and authorized penetration testing / bug bounty activities only.

Scanning targets without prior explicit consent is illegal and punishable by law. The developer assumes no liability and is not responsible for any misuse or damage caused by this program.

Authorized Use Only — Always obtain written permission before scanning any system you do not own.

---

🐛 Built with ❤️ for the security community

Report a Bug • Request a Feature • Star the Project