LabVuln 🔐

Authorized-Lab Vulnerability Scanner

LabVuln is a portfolio-grade cybersecurity project built with Python, FastAPI and SQLAlchemy. It provides authenticated, non-destructive vulnerability assessment workflows for controlled laboratory environments, including scan history, CVSS v3.1 scoring, remediation guidance and downloadable PDF reports.

Authorized use only. Scan only systems you own or have explicit permission to assess.

Highlights

Capability	Implementation
API	FastAPI + OpenAPI
Authentication	JWT bearer tokens + secure HttpOnly dashboard cookie
Password storage	Argon2 via pwdlib
Database	SQLAlchemy; SQLite for labs, PostgreSQL-ready
Scan history	Persistent targets, scans and findings with pagination
Risk rating	CVSS v3.1 base scores + severity bands
Scanner checks	TCP reachability + HTTP security headers
Reports	Server-generated PDF assessment reports
Safety	Private-range default, explicit authorization gate, proxy/redirect protections
Testing	Pytest unit/API/security regression tests
Deployment	Docker + Compose + non-root container

Architecture

Browser / REST API
        |
        v
    FastAPI
 auth / routes / docs
        |
        v
 Service Layer
 scan lifecycle + DB
        |
   +----+----------------+
   |                     |
   v                     v
Scanner Engine       PDF Reporting
 TCP / HTTP          ReportLab
   |
   v
SQLAlchemy Database
users / targets / scans / findings

Security design

The implementation was reviewed for common risks in authenticated web applications and network-scanning services.

Addressed controls

• Authentication required for targets, scans and reports
• Argon2 password hashing
• Strong runtime secret requirements
• Proxy-independent HTTP requests
• HTTP redirect suppression to reduce redirect-based SSRF paths
• Private/local default target policy with explicit authorization for public assets
• Reserved and special-purpose IPv4 rejection
• Bounded scan-history pagination
• Bounded stored evidence and remediation content
• HttpOnly + SameSite dashboard cookies; Secure enabled in production
• Non-root Docker execution

Remaining production hardening

Before Internet exposure, add a reverse proxy/TLS, rate limiting, audit logging, managed secrets, PostgreSQL migrations, CSRF protection for browser state-changing operations, and network-level outbound controls.

Project structure

├── app/
│   ├── auth.py
│   ├── config.py
│   ├── cvss.py
│   ├── database.py
│   ├── main.py
│   ├── migrations.py
│   ├── models.py
│   ├── reports.py
│   ├── schemas.py
│   ├── services.py
│   ├── scanner/
│   │   ├── base.py
│   │   ├── engine.py
│   │   ├── http_checks.py
│   │   ├── safety.py
│   │   └── tcp.py
│   └── templates/
│       ├── dashboard.html
│       └── login.html
├── tests/
├── .github/workflows/
│   └── test.yml
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
├── .env.example
└── SECURITY.md

Quick start

cp .env.example .env
python -c "import secrets; print(secrets.token_urlsafe(48))"
# put the generated value into JWT_SECRET
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload

Open http://127.0.0.1:8000.

Run tests:

pytest -q

Docker

docker compose up --build

API workflow

Login

curl -X POST http://127.0.0.1:8000/api/auth/login \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'username=admin&password=YOUR_PASSWORD'

Register an authorized lab target

curl -X POST http://127.0.0.1:8000/api/targets \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Local Lab","host":"127.0.0.1","port":8000,"authorized":true}'

Start a scan

curl -X POST http://127.0.0.1:8000/api/scans \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"target_id":1}'

Review scan history

curl http://127.0.0.1:8000/api/scans?limit=20 \
  -H "Authorization: Bearer $TOKEN"

Download a PDF report

curl -o scan-report.pdf \
  http://127.0.0.1:8000/api/scans/1/report.pdf \
  -H "Authorization: Bearer $TOKEN"

CVSS

Findings receive a CVSS v3.1 base score and vector. Scores are conservative initial risk signals for the specific checks implemented and should be validated against the real deployment context.

Severity bands: None 0, Low 0.1–3.9, Medium 4.0–6.9, High 7.0–8.9, Critical 9.0–10.0.

Testing

The suite covers authentication, JWT claims, API authorization, safety boundaries, CVSS calculations, PDF creation and security regressions.

Scope and limitations

LabVuln is intentionally non-destructive. It is not a replacement for Nmap, Nessus, Burp Suite, commercial vulnerability management platforms or a professional penetration test.

The project demonstrates secure REST API engineering, vulnerability-scanner architecture, defensive network validation, risk scoring, security testing, containerization and professional reporting.

Portfolio talking points

• Secure REST API development
• JWT authentication and password security
• Vulnerability assessment methodology
• CVSS risk scoring
• SSRF-aware scanner design
• Database-backed security workflows
• Automated security regression testing
• Dockerized deployment
• Security reporting and remediation communication

License

MIT