Vulnerability Scanner Web App

Deutsch | English

Professionelle defensive Fullstack-Web-App zur sicheren Analyse von Domains oder IPs. Die Anwendung führt ausschliesslich passive oder risikoarme Checks aus, speichert Reports und visualisiert Ergebnisse in einem React-Dashboard.

Welches Problem löst VSW?

Viele kleine Websites haben offensichtliche Sicherheitslücken in der Konfiguration, zum Beispiel fehlende Security Header, unsaubere TLS-Einstellungen oder offen erreichbare Standardports. VSW hilft, solche risikoarmen, passiven Checks lokal nachvollziehbar auszuführen und Reports so darzustellen, dass technische Findings, Evidenz und Empfehlungen schneller verständlich werden.

Wobei hilft es?

• Domains oder IPs defensiv und lokal prüfen
• HTTP Security Header, TLS-Zustand und eine kleine sichere Portliste auswerten
• Reports speichern, vergleichen und exportieren
• Findings mit Risiko, Evidenz und Empfehlung erklären
• Browser-Link-Prüfungen über eine lokale Extension vorbereiten
• ein Fullstack-Security-Projekt für Portfolio und IMS-Recruiting verständlich zeigen

Dokumentation

• Projektarchitektur und Zielbild: docs/architecture-plan.md
• Demo- und User-Guide: docs/demo-guide.md
• Mobile- und PWA-Zielbild: docs/mobile-plan.md
• Backend-Setup und API-Hinweise: backend/README.md
• Mehrsprachige Benutzeranleitungen: EN, DE, HU, SR, RU
• Windows-Launcher für Ein-Klick-Start: launch_vsw_launcher.ps1
• Windows-Shortcut-Installer: install_vsw_launcher.ps1
• Browser-Extension-MVP: extensions/vsw-link-capture

Sicherheits-Hinweis

Dieses Projekt ist bewusst defensiv gebaut.

• Keine Exploits
• Kein Brute Force
• Keine aggressiven Port- oder Service-Scans
• Keine Umgehung von Schutzmechanismen
• Keine Authentifizierungsversuche

Nur eigene Systeme oder Systeme mit ausdrücklicher Erlaubnis prüfen.

Stack

• Backend: FastAPI, SQLAlchemy, PostgreSQL (lokal optional SQLite)
• Frontend: React, TypeScript, Vite
• Infrastruktur: Docker, Docker Compose
• Tests: Pytest, Vitest, Testing Library
• Lokale Bedienung: Windows-Launcher auf Python-Basis
• Browser-Integration: Manifest-V3-Extension für Link-Capture
• Mobile/PWA: installierbares React-Frontend mit Webmanifest, ohne Offline-Scan-Versprechen
• Frontend-Sprachen: Englisch, Deutsch, Ungarisch, Serbisch, Russisch

Aktueller Funktionsumfang

• Target-Eingabe mit Domain-/IP-Validierung
• Warnhinweis zur autorisierten Nutzung
• HTTP Security Header Check
• TLS-/Zertifikatsanalyse
• Sicherer Port-Check auf kleiner Standardliste
• Misconfiguration-Erkennung mit Empfehlungen
• Erweiterte Read-only Checks für unsichere Header-Werte und Cookie-Flags
• Zusätzliche TLS-Read-only Regel bei bald ablaufenden Zertifikaten
• Niedrig gewichteter Härtungshinweis bei nicht bestätigter TLS 1.3 Unterstützung
• Report-Scoring von 0 bis 100
• Persistente Reports mit Detailansicht
• Dashboard-Gruppierung nach Score-Klassen: 75+, 50+, 25+, 0+
• Export von Reports als JSON und CSV
• Verlauf pro Target mit einfacher Trendanzeige
• Erweiterbare Findings-Liste mit Mehr/Weniger-Ansicht
• Guided link checks für same-origin Links mit klickbarer Prüfstrecke
• Windows-Launcher-App für Setup, Start, Browser-Open und Service-Stop ohne Terminal-Jonglage
• Browser-Extension-MVP für Link-Capture zum lokalen Backend
• Live-Capture für normale In-Page-Link-Klicks mit Pre-Scan vor Navigation
• Extension-Settings direkt in der lokalen VSW-App, inklusive Mindestscore für Besuchsfreigabe
• Host-Regeln für regelmässig geprüfte Websites: Minimum-Score ignorieren oder Host vertrauen
• Mobile-taugliches Dashboard für 360px bis 430px Breite mit besser antippbaren Controls
• PWA-Grundlage mit Manifest, Mobile-Meta-Tags, App-Name, Theme-Farbe und vorhandenen Icons
• Sprachumschalter mit Speicherung in localStorage
• Dashboard mit Status, Datum und Score
• Background-Scan-Ausführung im Backend
• Einfache Missbrauchsbremse per Rate-Limit

Was geprüft wird

HTTP Security Header

• Strict-Transport-Security
• Content-Security-Policy
• X-Frame-Options
• X-Content-Type-Options
• Referrer-Policy
• Permissions-Policy

SSL/TLS

• HTTPS erreichbar oder nicht
• Zertifikat vorhanden
• Zertifikat gültig oder abgelaufen
• Ablaufdatum
• Issuer
• Sicher prüfbare TLS-Versionen (TLSv1.2, TLSv1.3)

Sichere Portliste

• 80
• 443
• 22
• 25
• 53
• 3306
• 5432
• 6379
• 8080

Ergebnis pro Port:

• open
• closed
• timeout

Fehlkonfigurationen

Beispiele für abgeleitete Findings:

• HTTPS nicht erreichbar
• Unsichere HTTP-Redirects
• Fehlende Security Header
• Unsichere CSP- oder Referrer-Policy-Werte
• Schwache Strict-Transport-Security max-age-Werte
• Ineffektive X-Content-Type-Options Werte
• Zu breit erlaubende Permissions-Policy Werte
• Fehlende Secure-/HttpOnly-Cookie-Flags
• Offene Datenbankports
• Abgelaufenes TLS-Zertifikat
• Bald ablaufendes TLS-Zertifikat

Report-Logik

• Startwert: 100
• Abzug pro high: 25
• Abzug pro medium: 12
• Abzug pro low: 5
• Untergrenze: 0

Jeder Finding-Eintrag enthält:

• Risikostufe
• technische Beschreibung
• Evidenz
• konkrete Empfehlung

API-Endpunkte

• GET /api/v1/health
• POST /api/v1/scans
• GET /api/v1/scans
• GET /api/v1/scans/{scan_id}
• GET /api/v1/scans/{scan_id}/history
• GET /api/v1/scans/{scan_id}/links?limit=12
• GET /api/v1/scans/{scan_id}/export?format=json
• GET /api/v1/scans/{scan_id}/export?format=csv

Die Snapshot-Metadaten enthalten zusätzlich beobachtete Security Header, Redirect-Ziel und fehlende Header für schnellere Evidenzprüfung.

Benutzerhinweise

• Für Windows ist die Launcher-App der empfohlene Startweg, weil sie Python 3.12+ erkennt, Setup anstosst und Frontend plus Backend gemeinsam startet.
• Export ist aktuell für abgeschlossene Scans gedacht.
• JSON-Export wird lesbar formatiert bereitgestellt.
• Die Verlaufsansicht gruppiert Scans über normalized_target und zeigt neue Einträge zuerst.
• Die Trendanzeige ist bewusst einfach gehalten: verbessert, verschlechtert oder stabil im Vergleich zum vorherigen Score.
• Guided link checks bleiben defensiv: nur same-origin Links, keine Auth-Bypass-Logik, keine aggressiven Crawl-Strategien.
• Die Browser-Extension ist nur ein Trigger für Folge-Scans im lokalen VSW-Backend und enthält keine eigene Scan-Engine.
• Auf Mobile ist VSW zuerst Dashboard, Scanner und Report-Viewer. Globales Link-Blocking wie bei der Desktop-Extension ist dort nicht das Ziel.

Browser-Extension (MVP)

Ordner: extensions/vsw-link-capture

Funktionen:

• Kontextmenü: Scan link with VSW bei Link-Rechtsklick
• Kontextmenü: Scan current tab with VSW
• Popup-Button: Scan current page
• Popup-Feld: Scan and visit target
• Konfigurierbarer Mindestscore vor Weiterleitung
• Live-Capture für normale In-Page-Link-Klicks mit Pre-Scan vor Navigation
• Best-effort passive Navigationserfassung über webNavigation nach dem Laden
• Popup zeigt nur Status und Schnellaktionen; die Visit-Gate-Einstellungen werden in der lokalen VSW-App verwaltet
• Host-Regeln in der lokalen VSW-App für häufig genutzte Websites
• Trigger an lokales Backend: POST http://127.0.0.1:8000/api/v1/scans
• Erfolg: VSW-Detailseite für den neuen Scan wird bei Popup- oder Kontext-Trigger geöffnet
• Runtime-Fallback: Falls die Extension in einem bereits offenen Tab deaktiviert, neu geladen oder entfernt wurde, bleibt die Seite nicht dauerhaft hängen. Nach kurzer Fehlertoleranz wird die Navigation normal fortgesetzt.
• Backend-Health-Check vor Scan-Erstellung: Wenn Backend oder Launcher offline sind, werden keine Phantom-Scans als erstellt angezeigt.
• Popup-Status für Backend Online/Offline mit Retry connection.

Wichtige Opera-/Chrome-Hinweise:

• Nach dem Laden der Extension Developer mode aktiv lassen
• In Details den Website-Zugriff auf Auf allen Websites setzen
• Nach Änderungen oder nach erstem Laden die Zielseite mit Ctrl+F5 neu laden
• Live-Capture mit Scan-vor-Besuch greift nur bei normalen Links im Seiteninhalt
• Adresszeile, Lesezeichenleiste, angeheftete Browser-Links, Tabs, Browser-Buttons und Links aus externen Apps wie WhatsApp, Mail oder Chat-Clients werden vom Browser selbst gesteuert. Manifest V3 erlaubt hier keinen zuverlässigen Block vor dem ersten Laden.
• Solche Browser- oder App-Navigationen können höchstens nach dem Laden passiv erkannt werden, wenn die Extension aktiv ist, die Seite Extension-Zugriff erlaubt und das lokale Backend läuft. Das ist ein Best-effort-Report, kein Schutzversprechen.
• Für echtes Scan-vor-Besuch bei manuell eingegebenen Domains das Popup-Feld Scan and visit target nutzen
• Der Mindestscore wird in der VSW-App unter Visit gate settings angepasst, wenn die Extension geladen ist und Website-Zugriff auf localhost/127.0.0.1 hat
• Im Bereich Website rules können regelmässig gescannte Hosts verwaltet werden. Ignore minimum score scannt weiterhin, blockiert aber nicht wegen dem Score. Trust site erlaubt Navigation für diesen Host ohne Blocking.
• Nach Sleep, Browser-Neustart oder Extension-Reload werden Host-Regeln neu aus dem Storage geladen und normalisiert. www.github.com, github.com und URL-basierte Regeln werden auf denselben Host zurückgeführt.
• Wenn Backend/Frontend nicht laufen, zeigt das Frontend einen Offline-Status und einen Reconnect-Button, statt alte Scan-Daten als live darzustellen.

Release-Hinweis zu Browser-Grenzen

VSW darf nicht so erklärt werden, als könnte die Extension jeden Browser- oder Systemklick vorab kontrollieren. Für den Release gilt diese klare Abgrenzung:

• Zuverlässig: normale Links innerhalb einer geladenen Webseite, Kontextmenü-Aktionen und das Popup-Feld Scan and visit target.
• Best effort: Adresszeile, Lesezeichenleiste, angeheftete Browser-Links und Links aus externen Apps. Diese Aufrufe können je nach Browser erst nach dem Laden erkannt werden.
• Nicht versprochen: vollständiges globales Link-Blocking, Kontrolle über andere Apps oder garantierter Pre-Scan für bereits geöffnete Tabs ohne Reload.

Wenn ein Nutzer eine Domain sicher vor dem Besuch prüfen will, soll er Scan and visit target in der Extension nutzen oder die Domain direkt im VSW-Dashboard scannen.

Score-Gruppen im Dashboard:

• 75+: gute Reports
• 50+: mittlere Reports
• 25+: schwache Reports
• 0+: kritische Reports
• Pending: laufende oder wartende Scans

Installationsanleitung und manuelle Test-Checkliste:

• extensions/vsw-link-capture/README.md

Mobile / PWA

Das Frontend ist für Handy-Breiten vorbereitet und kann als PWA im mobilen Browser installiert werden, wenn der Browser Webmanifest-Installation unterstützt.

Wichtige Punkte:

• Mobile nutzt dieselbe Backend-API wie das Desktop-Frontend.
• Das Backend muss vom Handy erreichbar sein, zum Beispiel über die lokale Netzwerkadresse des Rechners oder einen Server.
• Es gibt bewusst keinen Service Worker und kein Offline-Versprechen.
• Die PWA ersetzt nicht die Desktop-Browser-Extension.
• Globales Link-Blocking ist auf Mobile nicht zuverlässig verfügbar und bleibt nicht Hauptziel.
• Eine APK ist ein möglicher nächster Schritt über Capacitor, aber noch nicht Teil dieser Umsetzung.

Empfohlene Tests:

• Browser DevTools Mobile View mit 360px bis 430px Breite
• echtes Handy im gleichen Netzwerk, wenn Backend-URL und CORS passend konfiguriert sind
• cd frontend && npm run lint
• cd frontend && npm test -- --run
• cd frontend && npm run build

Empfohlener Windows-Start

Launcher-App

Set-Location -LiteralPath "<repo-pfad>"
.\launch_vsw_launcher.ps1

Die Launcher-App ist der bevorzugte Weg für lokale Entwicklung und manuelle Demos unter Windows:

• erkennt Python 3.12+ automatisch
• erstellt bei Bedarf backend/.venv
• installiert fehlende Abhängigkeiten
• startet Backend und Frontend ohne zwei offene Terminal-Fenster
• erkennt bereits belegte Ports 8000 und 5173 und meldet klar, dass ein vorhandener Dienst wiederverwendet wird
• öffnet App und API-Doku direkt aus der GUI
• kann eine Desktop-Verknüpfung für den App-Start anlegen
• kann einen Windows-Autostart-Eintrag anlegen, damit Backend und Frontend nach dem Login automatisch starten
• stoppt beide Services wieder sauber

Desktop-Verknüpfung installieren

Set-Location -LiteralPath "<repo-pfad>"
.\install_vsw_launcher.ps1

Optional mit Startmenü-Eintrag:

.\install_vsw_launcher.ps1 -StartMenu

Optional mit Windows-Autostart:

.\install_vsw_launcher.ps1 -Startup

Der Autostart-Eintrag öffnet nach dem Windows-Login den Launcher, startet Backend und Frontend automatisch und öffnet das lokale Dashboard einmal im Browser. Dadurch muss VSW nach einem Laptop-Neustart nicht mehr manuell mit zwei Terminal-Kommandos gestartet werden.

Autostart wieder entfernen:

.\install_vsw_launcher.ps1 -RemoveStartup

Die Verknüpfung startet die Launcher-App. Der Launcher richtet bei Bedarf Backend und Frontend ein, zeigt Logs an und stoppt nur die Dienste, die er selbst gestartet hat.

Einfache Bedienung für Nicht-Entwickler

Aktuell ist der Windows-Launcher der empfohlene lokale Weg, weil er die vorhandene Backend-/Frontend-Struktur nutzt und keine zweite Scanner-Engine einführt. Für eine spätere Abgabe an Nutzer ohne Python ist Docker Desktop der realistische nächste Schritt. Eine native Desktop-App mit Tauri oder Electron bleibt sinnvoll, ist aber grösser und sollte erst umgesetzt werden, wenn der lokale Scanner-Workflow stabil bleibt.

PowerShell-Fallback

Set-Location -LiteralPath "<repo-pfad>"
.\dev.ps1

Optional ohne erneute Dependency-Installation:

.\dev.ps1 -SkipInstall

Lokales Setup ohne Docker

Backend

cd backend
python3 -m venv .venv
. .venv/bin/activate
pip install -e '.[dev]'
uvicorn app.main:app --reload

Ohne zusätzliche Umgebungsvariablen nutzt das Backend lokal standardmässig sqlite:///./vsw.db.

Standard-URL: http://localhost:8000

Frontend

cd frontend
npm install
npm run dev

Standard-URL: http://localhost:5173

Das Frontend erwartet standardmässig die API unter http://localhost:8000/api/v1.

Grenzen des Scanners

• Keine CVE-Korrelation aus Service-Bannern
• Keine tiefen Fingerprinting-Mechanismen
• Keine Auth- oder Session-Prüfungen
• Keine Content-Audits der Zielapplikation
• Keine externen Asset- oder JS-Dependency-Analysen
• Keine tiefgehende Langzeit-Trendanalyse über viele Zeiträume
• Keine Vollscanner-Extension direkt im Browser, weil die eigentlichen defensiven Checks bewusst im lokalen Backend bleiben
• Browser-Limitation: Bereits injizierte Content Scripts können in offenen Tabs bis zum Reload verbleiben. Der Extension-Fallback verhindert dauerhaft kaputte Tabs, indem er bei Runtime-Verlust nach kurzer Wartezeit weiterleitet.
• Browser-Limitation: Adresszeile, Lesezeichenleiste, angeheftete Browser-Links und externe App-Links lassen sich mit Manifest V3 nicht zuverlässig vor dem ersten Laden blockieren.
• Kein mobiles globales Link-Blocking wie auf Desktop-Browsern mit Extension
• Kein Offline-Scan in der PWA, weil Backend, Netzwerk und Datenbank erreichbar sein müssen

Noch nicht umgesetzt

• PDF-Export für Reports
• Authentifizierung und Team-Workspaces
• Scheduling für regelmässige Scans
• Grössere OWASP-orientierte Read-only Checklisten über die aktuelle v1-Erweiterung hinaus
• Native APK-/Capacitor-Projektstruktur inklusive Android-Build, Signierung und Store-Verteilung

Docker Setup

1. Beispiel-Konfiguration kopieren:

cp .env.example .env

2. Stack starten:

docker compose up --build

3. Services:

• Frontend: http://localhost:8080
• Backend API: http://localhost:8000
• PostgreSQL: localhost:5432

Hinweis: Der Windows-Launcher nutzt im Entwicklungsmodus standardmässig 5173 für das Vite-Frontend. Docker veröffentlicht das gebaute Frontend standardmässig auf 8080. Die Browser-Extension ist auf den Launcher-/Entwicklungsmodus mit 127.0.0.1:8000 und 127.0.0.1:5173 ausgerichtet. Für Docker-Demos ohne Launcher wird das Dashboard über http://localhost:8080 geöffnet; die Extension sollte danach separat auf die aktuelle Release-Konfiguration geprüft werden.

Wichtige Umgebungsvariablen

Siehe .env.example.

• DATABASE_URL
• CORS_ORIGINS
• RATE_LIMIT_MAX_REQUESTS
• RATE_LIMIT_WINDOW_SECONDS
• ENABLE_BACKGROUND_SCANS
• VITE_API_BASE_URL

Tests

Backend

cd backend
. .venv/bin/activate
pytest
ruff check .

Frontend

cd frontend
npm run lint
npm test
npm run build

Browser-Extension

node --check extensions/vsw-link-capture/background.js
node --check extensions/vsw-link-capture/content-script.js
node --check extensions/vsw-link-capture/popup.js
node --check extensions/vsw-link-capture/runtime-fallback.js
node --test extensions/vsw-link-capture/score-gate.test.cjs
node --test extensions/vsw-link-capture/runtime-fallback.test.cjs

Repository-Metadaten Vorschlag

• Description: Defensive fullstack vulnerability scanner for passive website checks, reports and browser-assisted link review.
• Topics: security, fastapi, react, typescript, vulnerability-scanner, passive-scanner, tls, security-headers, portfolio-project

Architekturhinweise

• Scans werden als Datenbankeintrag erstellt und per Background-Runner verarbeitet.
• Findings und Report-Snapshots werden persistiert.
• Das Frontend lädt Listen- und Detaildaten separat.
• CORS ist für lokale Frontend-/Backend-Trennung konfigurierbar.
• Der Windows-Launcher ist eine Bedien-Schicht über dem bestehenden Backend und Frontend, keine alternative Scanner-Engine.

Rollen der Oberflächen

Teil	Rolle
Backend	Scanner-Engine, Datenpersistenz, API und Score-Berechnung
Frontend	Haupt-Dashboard, Reports, Score-Gruppen, Visit-Gate-Einstellungen und Safety-Meldungen
Extension Background	Browser-Gatekeeper für Pre-Scan, Score-Entscheid und Navigation
Content Script	Klick-Abfang, kurze Browser-Toasts und Weiterleitung der Entscheidung
Extension Popup	Mini-Fallback für Schnellscan, manuelle Zielprüfung, Dashboard-Link und Statusübersicht
Windows-Launcher	Lokaler Starter für Setup, Backend, Frontend, App-Link und Logs

Die Extension soll keine zweite Dashboard-Oberfläche sein. Sie schützt den aktuellen Browserfluss und zeigt nur kurze Sofortmeldungen. Die längerfristige Erklärung, Konfiguration und Auswertung bleibt im Frontend.

Zukunftsideen

• PDF-Export mit Layout für Sharing und Audits
• Erweiterte Trendansicht (Zeitreihen, Vergleich mehrerer Scans)
• Weitere OWASP-orientierte Read-only Check-Module
• Optionales, kontrolliertes Scheduling mit klaren Limits
• Rollen-/Rechtemodell für Team-Nutzung
• Browser-Extension-Ausbau mit klarerem Statusbild für aktive Pre-Scans und bekannte Browser-Limitationen
• Capacitor-Schale für Android, sobald API-Basis-URL, CORS, Zertifikate und Signierung geklärt sind