🐛 BugScanner

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 (by ~80%) and bypass modern Web Application Firewalls (WAFs) through adaptive rate limiting and jitter control.

The framework is built entirely on asyncio and httpx for maximum concurrency, with a modern React + FastAPI web dashboard for real-time scan monitoring.

• 9+ Vulnerability Modules — XSS, SQLi (error + time-based), CORS, SSRF, Open Redirect, JWT, IDOR, Information Disclosure, Business Logic
• False-Positive Reduction Engine — 5-rule verification pipeline eliminating ~80% of noise
• SPA-Aware Scanning — Detects Single Page Application fallbacks to eliminate fake findings
• WAF Evasion — Detects Cloudflare, Akamai, AWS WAF, Imperva and adapts strategies
• Adaptive Rate Limiter — Token bucket that responds to 429/503 with backoff
• Authenticated Scanning — Full support for cookies, headers, and Bearer tokens
• Modern HTML Reports — Dark/light theme, sidebar, bento KPIs, filters, live search, JSON export
• SARIF Export — GitHub Security tab integration
• Scan Diff Engine — Compare two scans to see what changed
• Structured Logging — JSON logs via structlog
• Docker Ready — One-command deployment with docker-compose
• Test Suite — 35 tests passing with pytest, respx, pytest-asyncio

• Subdomain Enumeration — Dual-engine discovery using Certificate Transparency Logs (crt.sh) for passive reconnaissance and Async DNS Bruteforcing (120+ wordlist) for active discovery. Uses an isolated HTTP client so enumeration never stalls behind the target's rate limiter.

• TCP Port Scanner — High-speed asynchronous TCP connect scanning with banner grabbing. Supports three ranges:

  • common — 19 most common ports
  • extended — ~30 additional ports
  • full — 1-65535 with chunked processing (memory bounded to ~80 MB vs 800 MB)

• Technology Fingerprinting — Identifies web servers, CMSs, backend frameworks, and frontend libraries via HTTP Response Headers, HTML DOM patterns, and Session Cookies (nginx, Apache, PHP, WordPress, Drupal, React, Angular, Next.js, Vue.js, Laravel, Django, FastAPI, and more).

• Endpoint Discovery — Async path bruteforce across 200+ common administration, API (/graphql, /swagger), auth, debug, and backup endpoints. Includes SPA-specific endpoints (/api/Users, /rest/products/search, etc.) and sensitive file candidates (.env, .git/HEAD, actuator/heapdump).

• Reflected XSS Scanner — Evaluates parameter reflection in text/html contexts with execution-aware payload sets (script tags, HTML5 event handlers, filter bypasses, polyglots, template literals). Uses a unique marker (xsstest7731) to detect partial reflections.

• SQL Injection Scanner — Two-stage verification:

  • Error-Based — 30+ regex patterns covering MySQL, PostgreSQL, MSSQL, Oracle, SQLite
  • Time-Based Blind — Multi-DB payloads (SLEEP(), WAITFOR DELAY, pg_sleep(), BENCHMARK()) with 3-request double-check to eliminate network latency false positives

• CORS Misconfiguration Auditor — Tests 7 different origin patterns: wildcard, null, arbitrary reflection, subdomain bypass, suffix/prefix bypass. Combines Allow-Credentials: true detection with auto-generated JavaScript PoC exploits.

• SSRF & Open Redirect — Tests cloud metadata endpoints (AWS IMDSv1, GCP, Azure), decimal/hex IP bypasses (2130706433, 0x7f000001), file:// protocol leaks, DNS rebinding hints, and location-header redirection validation.

• JWT Security Auditor — Automates alg: none bypass, weak secret brute-forcing (20+ common secrets), algorithm confusion (RS256 → HS256), missing exp claim, and sensitive payload data detection.

• IDOR & Path Tampering — Evaluates parameter/path numerical shifts, UUID mutations, and HTTP Method Swapping (DELETE/PUT/PATCH) with SPA-aware false-positive protection and real-DELETE verification.

• Sensitive Data Exposure — Regex-based scanning for leaked AWS keys, Private RSA keys, GitHub/Stripe/Slack/SendGrid/Google API tokens, JWT tokens, database passwords, .git repository exposures, and Directory Listing.

• Business Logic Scanner (optional) — Tests mass assignment, price manipulation, rate-limit bypass via header rotation, password reset vulnerabilities (Host header injection), and response manipulation flaws. Recommended for authenticated scans.

• Nuclei Integration — Wraps ProjectDiscovery's nuclei engine (if installed) to execute 9000+ CVE and misconfiguration templates.

• Adaptive Token-Bucket Rate Limiter — Per-domain buckets that respond dynamically:

  • 429 Too Many Requests → halve RPS
  • 503 Service Unavailable → 30-second pause
  • 20 successful requests → 20% RPS increase
  • Configurable min/max RPS bounds

• WAF Detection & Jitter Engine — Signature-based detection for Cloudflare, Akamai, AWS WAF, Imperva/Incapsula, Sucuri, F5 BIG-IP, Barracuda, ModSecurity, and Nginx WAF. Applies per-WAF evasion strategies (RPS reduction, User-Agent rotation, bypass headers).

• HTTP Response Caching — Per-domain request cache (TTL configurable) that reduces requests by ~30-40% during follow-up scans.

• Automatic Retry — Exponential backoff on 5xx/429 responses using tenacity.

• Structured Logging — JSON logs via structlog for SIEM integration (ELK, Splunk, Datadog), plus human-readable console output.

BugScanner v2.1.1 introduces a 5-rule verification pipeline that reduces false positives by approximately 80% — the most common source of frustration in automated scanning.

Finding a file with HTTP 200 is not enough. BugScanner verifies actual content:

If a file returns HTML content (<!DOCTYPE html>, <div id="root">), it is immediately flagged as a false positive.

For Single Page Applications, every route returns HTTP 200 with the same index.html body. BugScanner detects this by:

1. Requesting the base URL
2. Requesting a random non-existent path (/__bs_probe_abc123)
3. Comparing status codes, body sizes, and SHA-256 hashes

If the fake path returns the same content as the base URL → SPA detected → route-based findings are filtered with high confidence.

Admin panels are only reported if the response body contains login-form DOM signals:

• Strong signals: <input type="password">, wp-login.php, phpmyadmin, admin panel
• Weak signals (need 3+): username, password, sign in, log in, dashboard, forgot password

A page returning HTTP 200 without these markers is not reported as an admin panel.

A vulnerability is only marked as Confirmed if it has:

• A payload_used or a curl_poc
• An evidence string of at least 10 characters
• Successful active re-validation (for XSS, SQLi time-based, CORS, redirects, disclosure)

Otherwise, it is flagged as Suspicious and filtered from the final report.

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 (context-aware)
            │   └── discovery.py         # Endpoint Bruteforce (SPA/API-aware)
            ├── vulns/
            │   ├── xss.py               # Reflected XSS Engine
            │   ├── sqli.py              # Error + Time-Based (multi-DB)
            │   ├── cors.py              # Origin Reflection (context-aware)
            │   ├── 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        # Content Signature Verification
            │   ├── 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 (retry + cache)
                ├── models.py            # Dataclasses & CVSS Scoring
                ├── validator.py         # Active False-Positive Validator
                ├── fp_filter.py         # ✨ 5-Rule FP Reduction Engine
                ├── waf_detector.py      # WAF Signature Engine
                ├── differ.py            # Scan Diff Engine
                ├── sarif_reporter.py    # SARIF 2.1.0 Export
                ├── logger.py            # Structured Logging (structlog)
                └── reporter.py          # JSON / HTML / SARIF Generator

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

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

tests/
            ├── conftest.py              # Shared fixtures
            ├── test_models.py           # Dataclass & CVSS tests
            ├── test_rate_limiter.py     # Token bucket tests
            ├── test_http_client.py      # Retry & cache tests
            ├── test_validator.py        # FP validator tests
            └── test_idor_spa.py         # SPA-aware IDOR tests

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

# 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.1
Bug Bounty Automation Tool
Authorized use only

# macOS
brew install nuclei

# Linux
curl -sSL https://raw.githubusercontent.com/projectdiscovery/nuclei/main/scripts/install.sh | bash

# Or with Go
go install -v github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest

# Update templates
nuclei -update-templates

# 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

# Export to SARIF (GitHub Security tab)
python cli.py scan https://target.com --format sarif

# Disable HTTP cache (always re-request)
python cli.py scan https://target.com --no-cache

# 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

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

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

# 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"

# Diff two previous scans
python cli.py diff reports/old.json reports/new.json

# Show version
python cli.py version

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

The dashboard provides:

• Live scan progress via WebSocket
• Interactive vulnerability browser with severity filters
• Chip-based severity filter + live search
• Historical scan comparison
• Direct report download (JSON, HTML, SARIF)
• Dark theme optimized for long sessions

BugScanner's v2.1.1 HTML report features a completely redesigned 2026-era interface:

• 🌗 Dark / Light Theme — Toggleable, persists via localStorage
• 📊 Bento-Grid KPIs — Risk score ring (SVG animated), vulnerability distribution bars, recon surface, scan duration
• 🧭 Sidebar Navigation — Auto-highlights current section while scrolling (IntersectionObserver)
• 🔎 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
• 🎯 FP Breakdown — Shows filtered false positives categorized by rule (SPA, no-signature, no-admin-DOM, no-PoC, downgraded)
• 📱 Responsive — Works on tablet and mobile devices
• 🔒 Self-Contained — No external CDN dependencies, works offline

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.1)"
  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", "sarif"]
  reports_dir: "./reports"

BugScanner includes a comprehensive test suite built with pytest, pytest-asyncio, and respx (HTTP mocking).

pytest -v

pytest --cov=core --cov=modules --cov-report=term-missing

pytest --cov=core --cov=modules --cov-report=html
start htmlcov/index.html    # Windows
open htmlcov/index.html     # macOS
xdg-open htmlcov/index.html # Linux

Total: 35 tests passing

# Build and start
docker-compose up -d

# View logs
docker-compose logs -f

# Stop
docker-compose down

The container exposes the FastAPI backend + frontend on http://localhost:8000.

Create a .env file:

BUGSCANNER_API_KEY=your-long-random-api-key
BUGSCANNER_LOG_LEVEL=INFO
BUGSCANNER_CORS=http://localhost:5173,http://localhost:8000

docker exec -it bugscanner python cli.py scan https://target.com

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Write tests for new functionality
4. Ensure all tests pass: pytest
5. Update CHANGELOG.md under the [Unreleased] section
6. Commit using Conventional Commits:
   • feat: add new scanner
   • fix: correct rate limiter
   • docs: update README
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request with a clear description

• Line length: 100 characters max
• Type hints: Required for public functions
• Docstrings: Google style for public APIs
• Formatting: black and isort

pip install black isort
black core modules cli.py app.py
isort core modules cli.py app.py

• ✅ Authenticated Scope Scanning — --cookie and --header session preservation
• ✅ Modern Report UI — Dark/light theme, interactive filters
• ✅ False-Positive Reduction Engine — 5-rule verification pipeline (~80% noise reduction)
• ✅ SPA-Aware Detection — Multi-layer false-positive protection
• ✅ Chunked Port Scanning — Full 1–65535 range without memory blowup
• ✅ Structured Logging — JSON logs via structlog
• ✅ SARIF Export — GitHub Security tab integration
• ✅ Scan Diff Engine — Compare two scans
• ✅ Docker Compose — One-command deployment
• ⬜ Headless DOM Analysis — Playwright integration for Blind XSS and SPA route extraction
• ⬜ Multi-Role IDOR Diff Engine — Automated differential testing between User A and User B session tokens
• ⬜ PyPI Package Release — pip install bugscanner
• ⬜ Plugin System — User-defined scanner modules
• ⬜ Postgres Backend — Persistent scan history and comparison
• ⬜ GraphQL Introspection Scanner — Full schema dump and query abuse detection
• ⬜ Web Cache Deception — Automated testing for CDN/cache poisoning

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

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.

By using BugScanner, you agree to:

• Only scan systems you own or have explicit permission to test
• Respect rate limits and avoid denial-of-service conditions
• Report vulnerabilities responsibly to the affected party
• Never use findings for malicious purposes

• Kali Linux — Community and inspiration
• ProjectDiscovery — Nuclei template engine
• PortSwigger — Web Security Academy reference material
• OWASP — Vulnerability classification standards
• httpx — Excellent async HTTP library
• rich — Beautiful terminal output