VulnHawk

An inspectable web security scanner built with Python, asyncio, and Flask.

VulnHawk explores the engineering behind web vulnerability detection: discovering pages and parameters, coordinating modular checks, preserving finding evidence, and exporting results for review. It includes a command-line scanner, a deliberately vulnerable local application, and experimental analysis components.

This repository is a development project for controlled security labs. The command-line workflow is the primary entry point; the web interface and deployment files have incomplete dependencies described below. Use it only with applications you own or are explicitly authorized to test. Active checks submit payloads and may change application state.

Engineering focus

• Asynchronous request handling: an aiohttp client, connection limits, configurable delays, and a crawler with depth and page budgets.
• Modular detection: shared finding structures and separate passive checks and active parameter tests.
• Reviewable findings: fields for URL, parameter, method, payload, evidence, confidence, severity, and remediation.
• Structured output: command-line JSON export with scan status and severity totals.
• Analysis experiments: rule-based classification and correlation, plus optional external language-model adapters for explanatory analysis.

Detection signals need manual validation. A reflected payload, a missing token, or a suspicious response pattern does not by itself establish exploitability.

Local setup

Python 3.11 is the reference version used by the supplied Dockerfile. The requirements file specifies minimum versions rather than a tested dependency lock.

git clone https://github.com/MGpromax/VulnHawk.git
cd VulnHawk
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
python run.py --help
python run.py scan --help

On Windows PowerShell, activate the environment with .venv\Scripts\Activate.ps1.

The CLI scan command does not require database initialization or a model-provider API key. Dependencies are shared with the Flask application, so install the complete requirements file.

Scan the local demo

In the first terminal, activate the virtual environment and start the intentionally vulnerable application on loopback:

python run.py demo

In a second terminal, activate the same environment and run a small scan:

python run.py scan http://127.0.0.1:5001 \
  --depth 1 --pages 10 \
  -m xss -m sqli \
  -o demo-report.json -f json -v

Stop the demo with Ctrl+C when finished. Keep this application on a disposable local environment; it deliberately contains insecure behavior and runs with Flask debugging enabled.

The command syntax is verified against run.py. These examples are a reproduction workflow, not a claim that detection correctness has been established.

CLI options

Option	Behavior
-m, --modules	Repeat to select modules. Without it, the CLI selects the eight basic families listed below.
--depth	Maximum crawl depth; default 5.
--pages	Maximum crawl page budget; default 100.
-o, --output	Path for the output file.
-f, --format	Select json. HTML and PDF choices exist in the parser but are incomplete.
-v, --verbose	Print progress messages.

Detection paths

The standard engine currently dispatches these checks. This table describes code integration, not measured coverage or accuracy.

Module	Implementation approach
xss	Active payload reflection checks on discovered parameters.
sqli	Error, boolean-response, and timing heuristics.
lfi	File-inclusion and traversal payloads with response-pattern checks.
open_redirect	Redirect-oriented parameter testing.
headers	Response header and cookie checks.
csrf	Form and token heuristics.
info_disclosure	Response and parsed-content pattern checks.
ssl	HTTPS certificate and TLS-related checks.

Additional source modules cover DOM XSS, IDOR, JWT, mass assignment, SSRF, and SSTI. They are listed in the standard engine's loader, but its scan phases do not invoke them. Selecting a module name therefore does not guarantee that it runs. A separate turbo engine also exists; the default CLI uses ScannerEngine, not TurboScannerEngine.

Architecture

run.py scan
  -> ScannerEngine / ScanConfig
  -> AsyncRequester + AsyncCrawler
  -> HTMLParser: links, forms, parameters
  -> passive checks + active parameter tests
  -> finding callbacks + JSON output

Flask application
  -> web routes + /api/v1 routes
  -> SQLAlchemy users, scans, and findings
  -> optional analysis components

Source	Responsibility
run.py	Click commands and CLI report assembly.
app/scanner/core	Request lifecycle, crawling, parsing, orchestration, and progress.
app/scanner/modules	Detection implementations and the shared finding model.
app/models	Database-backed users, scans, and vulnerabilities.
app/api/routes.py	Scan lifecycle, result retrieval, progress, and analysis routes.
app/ai	Heuristic analysis and optional provider adapters.
tests	Vulnerable demo and a manual detection exercise.

Validation and current limits

Python syntax and CLI help can be checked without starting a server or sending scan traffic. See the validation notes for commands and the limits of the existing test script.

• No accuracy benchmark: the repository does not establish precision, recall, a false-positive reduction percentage, or complete OWASP coverage. Several manual checks return success without proving detection.
• Result propagation needs review: the standard engine initializes active-testing statistics after passive checks, while its finding callback path accesses those statistics. CLI callback results can therefore diverge from the engine's accumulated findings.
• Incomplete web assets: routes reference templates under app/web/templates, which are absent from this snapshot.
• Incomplete exports: app/reports is absent; CLI HTML imports a missing module, and PDF output is a placeholder. Use JSON for development.
• Deployment gaps: the Docker health check uses /api/health, but the application registers /api/v1/health. The Compose worker references an absent app.celery_worker module. The supplied containers are reference configuration, not a validated deployment.
• Analysis is advisory: the classifier uses patterns and heuristics, not a trained model distributed with this repository. Optional provider integrations require separately installed SDKs and credentials; model output is not verified finding evidence.

Documentation

• Local walkthrough: setup, demo workflow, and reading findings.
• Technical notes: component boundaries, interface behavior, validation, and development priorities.
• Engineering discussion guide: source-backed design decisions and tradeoffs.

For a contribution, include a minimal local fixture, the expected behavior, and a check that fails when that behavior regresses. For detector changes, include both vulnerable and benign cases. Keep credentials and real target data out of example outputs.