Skip to content

README.md

Latest commit

 

History

History
247 lines (187 loc) · 7.54 KB

README.md

File metadata and controls

247 lines (187 loc) · 7.54 KB
Raw

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.