Evidence-first command-line scanner for authorized web targets.
It crawls in-scope pages, inspects forms and query parameters, checks common web posture issues, looks for exposed files, inspects Swagger/GraphQL endpoints, records DNS/TLS details, runs bounded SQLi checks, and can verify access-control behavior when authorized actor accounts are configured.
- HTTP crawler with strict scope controls and bounded concurrency.
- Optional Playwright-assisted discovery and authenticated browser flows.
- Passive web posture checks: security headers, cookies, CORS, redirects, and verbose errors.
- Bounded exposure checks for common backup/debug/config paths.
- Swagger/OpenAPI and GraphQL discovery.
- DNS and TLS inventory.
- Active SQLi and business-logic/access-control checks.
- Auth-aware actor comparison, RBAC verification, replay artifacts, and workflow scenarios.
- JSON and HTML reports, plus SARIF 2.1.0 conversion for security tooling.
- Conservative scan profiles for passive and authorized testing modes.
- CI across Python 3.10, 3.11, and 3.12.
Use this project only on systems you own or have explicit permission to test.
The default configuration is intentionally bounded. Experimental plugins remain disabled by the registry and are not enabled automatically by any scan profile. Authentication checks require test credentials supplied through configuration/environment variables.
Create a virtual environment:
python -m venv .venvWindows:
.\.venv\Scripts\activatemacOS / Linux:
source .venv/bin/activateInstall the project for normal HTTP scanning:
python -m pip install --upgrade pip
python -m pip install -e .For development:
python -m pip install -e .[dev]For browser-assisted scanning:
python -m pip install -e .[browser]
playwright install chromiumThe legacy requirements.txt workflow remains available for compatibility.
The bundled mock target exercises the scanner without contacting a third-party system:
python smoke/run_smoke.pyIt starts a local mock server, runs a scan, and writes reports to smoke_out/.
Installed CLI:
web-vuln-scanner https://target.tld --config config/default_config.yaml --output reportsDirect Python entry point:
python main_v2.py scan https://target.tld --config config/default_config.yaml --output reportsWith API discovery:
web-vuln-scanner https://target.tld \
--config config/default_config.yaml \
--swagger https://target.tld/openapi.json \
--graphql https://target.tld/graphql \
--output reportsmain.py is retained only as a deprecated compatibility shim. New integrations should use web-vuln-scanner or main_v2.py.
Profiles are materialized into a normal YAML configuration, so the scanner keeps one configuration contract and profiles remain easy to audit.
Passive posture assessment:
web-vuln-profile passive --config config/default_config.yaml --output config/passive.generated.yaml
web-vuln-scanner https://target.tld --config config/passive.generated.yaml --output reportsBounded active assessment:
web-vuln-profile safe-active --config config/default_config.yaml --output config/safe-active.generated.yamlAuthorized browser-capable baseline:
web-vuln-profile full-authorized --config config/default_config.yaml --output config/full-authorized.generated.yamlAvailable profiles:
passive- crawler plus passive/posture layers; active plugins disabled.safe-active- enables stable bounded SQLi and business-logic checks; experimental plugins stay disabled.full-authorized- browser-capable authorized baseline with stable plugins; credentials/workflows are still explicitly configured by the operator.
A scan produces:
scan_report.json- complete machine-readable report.scan_report.html- human-readable evidence report.
Convert JSON to SARIF 2.1.0:
web-vuln-sarif reports/scan_report.json --output reports/scan_report.sarifor:
python -m core.sarif reports/scan_report.jsonSARIF results preserve severity, confidence, verification status, category, plugin, scanner mode, target URL, and remediation metadata.
Plugin metadata lives in core/plugin_catalog.py and records maturity, activity type, CWE references, and OWASP mappings.
Stable plugins:
sqlibusiness_logic
Experimental plugins currently blocked by the registry:
xss_reflectedlficmd_injectionopen_redirect
Experimental code must pass dedicated positive/negative tests and verification-quality review before promotion.
0- no reportable findings.1- findings were produced.2- runtime or configuration failure.3- partial or aborted run.
python -m pytestCritical static checks used by CI:
ruff check . --select E9,F63,F7,F82
python -m compileall -q core layers plugins workflows smoke main_v2.pyThe smoke harness is also executed in CI, and its JSON report is converted to SARIF to validate the reporting pipeline.
The Docker image is aligned with Playwright 1.62 and runs the scanner as the non-root pwuser supplied by the Playwright image.
docker build -t web-vuln-scanner .
docker run --rm web-vuln-scanner --helpSee CONTRIBUTING.md before adding scanners or plugins. New checks should be bounded, scope-aware, evidence-driven, false-positive conscious, and tested against local fixtures.