VulnScanner 🛡️

⚠️ Disclaimer: This tool is for educational and authorized security testing purposes only. Using this tool against systems without explicit written permission is illegal and unethical. The authors assume no liability for misuse.

---

A production-grade, modular Web Application Vulnerability Scanner targeting OWASP Top 10 vulnerabilities, with primary focus on SQL Injection (SQLi) and Cross-Site Scripting (XSS).

Built with clean architecture, thread-based concurrency, configurable depth, and professional-quality reporting.

---

Features

Feature	Details
🕷️ Recursive Crawler	BFS crawling with domain scope enforcement and depth limits
🎯 Attack Surface Detection	Forms (GET/POST), URL query parameters, textarea/select inputs
💉 SQLi Detection	Error-based (MySQL/PostgreSQL/MSSQL/SQLite/Oracle), boolean-based
🔍 XSS Detection	Reflected payload detection with contextual marker analysis
⚡ Concurrent Scanning	Thread-pool-based injection with configurable worker count
🚦 Rate Limiting	Token-bucket algorithm to avoid overwhelming targets
📊 Dual Reports	JSON (machine-readable) + HTML (styled dashboard) output
🔧 Extensible Design	Plugin-style payload registry for adding new vuln categories
🐳 Docker Support	Non-root containerized execution
📝 Structured Logging	INFO/DEBUG/WARNING/ERROR levels, file + console output

---

Architecture

scanner/
│── main.py          ← CLI entry point & pipeline orchestrator
│── config.py        ← Global settings, constants, defaults
│── crawler.py       ← BFS URL discovery engine
│── extractor.py     ← Form & query parameter surface extraction
│── payloads.py      ← Centralized, extensible payload registry
│── injector.py      ← Concurrent payload injection engine
│── analyzer.py      ← Response analysis & vulnerability classification
│── reporter.py      ← JSON + HTML report generation
│── utils.py         ← Shared: logging, HTTP session, rate limiter, URL utils
│── requirements.txt
Dockerfile
README.md

Data Flow

[Target URL]
     │
     ▼
[Crawler] ──── BFS, domain-scoped ────► [URL List]
     │
     ▼
[SurfaceExtractor] ── HTML parse ─────► [Forms + Query Params]
     │
     ▼
[Injector] ──── Thread Pool ──────────► [Baseline + Injected Responses]
     │
     ▼
[ResponseAnalyzer] ── Pattern Match ──► [Vulnerability Findings]
     │
     ▼
[ReportGenerator] ────────────────────► [JSON Report] + [HTML Dashboard]

---

Setup & Installation

Prerequisites

• Python 3.9+
• pip

Install

git clone https://github.com/yourusername/vulnscanner.git
cd vulnscanner

# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate        # Linux/macOS
venv\Scripts\activate           # Windows

# Install dependencies
pip install -r scanner/requirements.txt

---

Usage

Basic Scan

python scanner/main.py --url http://testphp.vulnweb.com --depth 2

Full Options

python scanner/main.py \
  --url http://testphp.vulnweb.com \
  --depth 3 \
  --output my_report \
  --format html \
  --threads 8 \
  --rate-limit 5 \
  --timeout 10

CLI Reference

Flag	Default	Description
--url URL	(required)	Target base URL
--depth N	2	Crawl depth from seed URL
--output PATH	scan_report	Output file path (no extension)
--format {html,json,both}	html	Report format
--threads N	8	Concurrent injection workers
--rate-limit RPS	5.0	Max requests per second
--timeout SEC	10	Per-request timeout
--no-sqli	—	Disable SQL injection scanning
--no-xss	—	Disable XSS scanning
--cookie NAME=VALUE	—	Add session cookie (repeatable)
--header NAME:VALUE	—	Add HTTP header (repeatable)
-v, --verbose	—	Enable DEBUG logging

With Authentication Cookie

python scanner/main.py \
  --url http://target.com \
  --cookie "PHPSESSID=abc123def456" \
  --depth 2

Docker

# Build
docker build -t vulnscanner .

# Run
docker run --rm vulnscanner \
  --url http://testphp.vulnweb.com \
  --depth 2 \
  --format both

---

Adding New Vulnerability Modules (Plugin System)

The payload registry supports runtime extension:

from scanner.payloads import PayloadStore, Payload

store = PayloadStore()

# Register a new category
store.register_category("xxe", [
    Payload(
        value='<?xml version="1.0"?><!DOCTYPE foo [<!ENTITY xxe SYSTEM "file:///etc/passwd">]><foo>&xxe;</foo>',
        category="xxe",
        technique="file_read",
        description="XXE file read probe",
    )
])

---

Sample Output

 ___    _____               ___
|   |  /      \            /
|___|  |      |  ___  ___  |___
|   \  |      | /   \/   \      |
|    \ \______/ \___/\___/ \____/
  VulnScanner v1.0.0

=== Phase 1: Crawling ===
Discovered 24 URL(s).

=== Phase 2: Extracting Attack Surfaces ===
Found injectable surfaces in 8 URL(s).

=== Phase 3: Injection & Analysis ===
[SQLi/error_based] MySQL DB error detected at http://testphp.vulnweb.com/listproducts.php (param: cat)
[XSS/reflected] Payload reflected at http://testphp.vulnweb.com/search.php (param: searchFor)

=== Phase 4: Generating Report ===
  → HTML Report: /path/to/scan_report.html
  → JSON Report: /path/to/scan_report.json

───────────────────────────────────────────────────────
              SCAN SUMMARY
───────────────────────────────────────────────────────
  Target           : http://testphp.vulnweb.com
  URLs Scanned     : 24
  Duration         : 18.4s
  Total Findings   : 5
  High Severity    : 3
  Medium Severity  : 2
───────────────────────────────────────────────────────

---

Vulnerability Coverage

Vulnerability	OWASP Category	Severity	Techniques
SQL Injection	A03:2021	HIGH	Error-based, Boolean-based, Time-based
Reflected XSS	A03:2021	MEDIUM	Reflection, Marker detection

Additional modules (CSRF, IDOR, SSRF, XXE) can be added via the plugin system.

---

Technical Design Decisions

• No monolithic script: Each concern (crawl/extract/inject/analyze/report) is a separate module with a well-defined interface.
• Typed dataclasses: AttackSurface, Vulnerability, BaselineResponse carry structured data instead of raw dicts.
• Baseline comparison: Every injected request is compared against a cached baseline to detect boolean-based SQLi and reduce false positives.
• Token-bucket rate limiter: Thread-safe implementation prevents accidental DoS of the target.
• Structured logging: All modules use logging.getLogger(__name__) — configurable at the root level from main.py.

---

License

MIT License — see LICENSE for details.

Built by Rushabh Ahire | Aspiring Python developer Engineer

---

Built for educational use, security research, and authorized penetration testing. Always obtain written permission before scanning any system you do not own.