WVS is a full-stack web security scanning framework that pairs a Python FastAPI backend with a Next.js + Tailwind frontend to deliver real-time, extensible vulnerability detection.
It helps developers and security teams identify common injection flaws, misconfigurations, and logic issues in modern web applications using safe-by-default, low-impact modules.
- Key Features
- Architecture
- Screenshots
- Quickstart
- Environment Variables (Backend)
- Docker (Backend)
- API Usage
- AI Explanation
- Testing
- Contributing
- Code of Conduct
- Security Policy
- Support
- Roadmap
- License
- Acknowledgements
- Injection checks: SQLi, SSTI (benign heuristics)
- XSS: Reflected, DOM-based (static sink heuristics)
- Misconfigurations: CORS, Clickjacking, Security headers, Cookie flags, TLS checks
- Recon and info: Ping/connectivity, Domain scan, IP identification, Tech fingerprinting
- GraphQL: Introspection detection
- Protocols/headers: Host header reflection checks
- Orchestrator: Concurrent module execution with consistent result schema
- AI Explain: One-click “AI Explain” to turn findings into a detailed remediation report (Gemini)
Note: Several advanced modules are present in the codebase and will be expanded over time. Safety comes first; most implemented modules are passive or low-impact.
- backend/ — FastAPI service, scanning engine, and vulnerability modules
- frontend/ — Next.js App Router UI for starting scans and viewing results
- Dashboard: start scans and view findings (severity, confidence, evidence)
- Login: obtain an access token to interact with the API
- About, Developers, Careers pages for project info and contribution paths
Add screenshots under docs/screenshots and link them here.
- Create a virtual environment and install dependencies
python -m venv .venv
source .venv/bin/activate
pip install -r backend/requirements.txt- Set environment and run the API
export JWT_SECRET=change_me_for_dev
uvicorn backend.app.main:app --reload- Health check
curl -s http://127.0.0.1:8000/health | jq .- Start the dev server
cd frontend
npm run dev- Visit the app
- Login: http://localhost:3000/login
- Dashboard: http://localhost:3000/dashboard
- About: http://localhost:3000/about
- Developers: http://localhost:3000/developers
- Careers: http://localhost:3000/careers
The frontend proxies to the backend via /api/backend (configured in the app). Ensure the backend is running on http://127.0.0.1:8000.
- JWT_SECRET: secret for signing tokens (required for stable auth)
- JWT_ALG: token algorithm (default HS256)
- JWT_EXPIRE_MINUTES: token lifetime (default 60)
- GEMINI_API_KEY: API key for Gemini to enable AI explanations (optional)
- GEMINI_MODEL: Gemini model name (default: gemini-1.5-flash)
Build and run the backend API with Docker:
docker build -t wvs-backend -f backend/Dockerfile .
docker run --rm -p 8000:8000 -e JWT_SECRET=change_me wvs-backendCheck health:
curl -s http://127.0.0.1:8000/health | jq .Authenticate and run a scan (authorized testing only):
TOKEN=$(curl -s -X POST http://127.0.0.1:8000/api/auth/login \
-H 'Content-Type: application/json' \
-d '{"email":"user@example.com","password":"pw"}' | jq -r .access_token)
curl -s -X POST "http://127.0.0.1:8000/api/scan?verbose=true" \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"target":"https://example.com","modules":["headers","cookies","tls_checks","clickjacking","cors_misconfig","sqli","xss_reflected","xss_dom","ssti","ping","domain_scan","ip_identification","graphql_introspection","host_header_injection"]}' | jq .Enable Gemini on the backend and generate a detailed markdown report from findings.
- Configure environment (do not paste secrets in commands; set them in your shell):
export GEMINI_API_KEY={{GEMINI_API_KEY}}
export GEMINI_MODEL=gemini-1.5-flash # optional- Call the AI endpoint:
TOKEN=$(curl -s -X POST http://127.0.0.1:8000/api/auth/login \
-H 'Content-Type: application/json' \
-d '{"email":"user@example.com","password":"pw"}' | jq -r .access_token)
curl -s -X POST http://127.0.0.1:8000/api/ai/explain \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"target": "https://example.com",
"findings": [{"module":"headers","severity":"low","title":"Missing Security Header: X-Frame-Options","confidence":"high","evidence":{"header":"x-frame-options"}}],
"tone": "detailed",
"language": "en"
}' | jq .UI integration: In the Dashboard, after a scan returns findings, click “AI Explain” to fetch and render the explanation.
Run the backend tests:
. .venv/bin/activate
pytest -q backend/testsPlease read CONTRIBUTING.md for guidelines on proposing changes, branching, commit messages, and pull requests. To add a module, create a file under backend/scanner/modules/ that defines:
- MODULE: string module name
- async def scan(target: str, context: dict | None) -> list[dict]
The engine auto-discovers modules and runs them concurrently.
We follow the Contributor Covenant. See CODE_OF_CONDUCT.md for expected behavior and reporting.
Please report vulnerabilities responsibly as described in SECURITY.md. Only test systems you own or have explicit permission to test.
Open a GitHub issue for bugs and feature requests. For general questions, use GitHub Discussions (if enabled). We aim to respond within a few business days.
- Expand module coverage (SSRF advanced checks, NoSQLi, JSONi, XXE, HTTP Smuggling)
- Add linting/formatting (ruff, black) and CI workflows
- Enhance result presentation and filtering in the UI
- Add rate limiting and concurrency controls for production safety
This project is licensed under the MIT License — see LICENSE for details.
Only scan systems you own or have explicit written permission to test. Unauthorized scanning may be illegal. Use responsibly.
Developed by INSA Teams