Recon-Scan

ReconScan ist ein quelloffener passiver Recon-Scanner mit einem FastAPI-Backend, einer asynchronen Worker-Pipeline und einem Single-Page-Frontend. Die bereitgestellte Seite kannst du unter https://recon-scan.vercel.app/ aufrufen.

Der Punkt ist schnelles Signal: Starte einen Scan, erhalte modulweise Ergebnisse und erhalte eine KI-Zusammenfassung, die jetzt als ausgefeilter PDF-Bericht exportiert werden kann.

Hinweis: Die Demo ist nicht live, weil mir die KI-Tokens ausgegangen sind. Du kannst sie trotzdem selbst hosten.

Was dieses Projekt ist (und was nicht)

• Es ist passive Recon. Es führt kein Brute-Forcing von Endpunkten, kein Fuzzing und keine aktive Exploit-Logik aus.
• Es eignet sich für Posture-Snapshots, Triage und Reporting.
• Es ist kein Ersatz für vollständige Penetrationstests.

Funktionen

• 13 passive Module:
  • Security-Header
  • SSL/TLS
  • DNS + E-Mail-Authentifizierung (SPF/DMARC/MX)
  • WHOIS
  • Robots/Sitemap
  • Subdomain-Enumeration
  • Tech-Fingerprinting
  • WAF-Erkennung
  • CORS-Prüfungen
  • Cookie-Sicherheitsprüfungen
  • JS-Exposure-Prüfungen
  • Directory-Exposure-Prüfungen
  • Reputationsprüfungen
• Asynchrone Ausführung mit Redis + ARQ-Worker.
• Fallback auf In-Process-Hintergrundausführung, wenn das Einreihen in die Queue fehlschlägt.
• Optionale KI-Zusammenfassung über OpenRouter / Anthropic / OpenAI.
• PDF-Berichtsgenerierung aus Scan + KI-Zusammenfassung.
• Frontend direkt von FastAPI bereitgestellt (eine URL, eine App).

Ein-Befehl-Start (lokale Entwicklung)

Wenn du es nur schnell zum Laufen bringen willst:

./start.sh

Was das macht:

• Erstellt .env aus .env.example, falls nicht vorhanden.
• Erstellt .venv, falls nötig.
• Installiert Abhängigkeiten aus requirements.txt.
• Startet FastAPI mit Hot Reload auf http://localhost:8000.
• Erzwingt USE_ARQ_QUEUE=false für einen einfacheren lokalen Start ohne Redis.

Beenden mit Ctrl+C.

Ein-Befehl-Start (Docker)

./start-docker.sh

Was das macht:

• Erstellt .env aus .env.example, falls nicht vorhanden.
• Startet API + Worker + Redis mit Docker Compose.

Docker-Start (manuell)

cp .env.example .env
docker compose up --build

Lokale Entwicklung (ohne Docker)

1. Abhängigkeiten installieren:

pip install -r requirements.txt

2. Env-Datei erstellen:

cp .env.example .env

3. API starten:

uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

4. Worker in einem anderen Terminal starten (empfohlen):

arq app.worker.WorkerSettings

5. Öffnen:

http://localhost:8000

Tests ausführen

Test-Abhängigkeiten installieren:

pip install -r requirements-dev.txt

Die vollständige Suite ausführen:

pytest -q

PDF-Berichte

Nach Abschluss eines Scans klicke in der UI auf Download PDF.

Backend-Endpunkt:

• GET /scans/{scan_id}/report.pdf

Der Bericht enthält:

• Ziel- und Scan-Metadaten
• KI-Zusammenfassung für die Geschäftsleitung (kurz + vollständige Erzählung, falls verfügbar)
• Severity-Snapshot-Tabelle
• Detaillierte modulweise Ergebnisse

API

• GET /health
• POST /scans
  • Body-Beispiel:
    • { "target": "example.com" }
    • { "target": "example.com", "byoapi_key": "...", "byoapi_provider": "your_provider" }
  • Hinweise:
    • byoapi_key wird abgelehnt, es sei denn ALLOW_BYO_API_KEY=true
    • private / Loopback- / reservierte Ziele werden blockiert
    • user_id ist optional und wird aus Kompatibilitätsgründen beibehalten
• GET /scans/{scan_id}
• GET /scans/{scan_id}/report.pdf

Konfiguration

Aus .env.example:

• DATABASE_URL (Standard: sqlite:///./reconscan.db)
• REDIS_URL (Standard: redis://localhost:6379)
• USE_ARQ_QUEUE (Standard: true)
• RATE_LIMIT_PER_MINUTE (Standard: 10)
• RATE_LIMIT_PER_DAY (Standard: 200)
• ALLOWED_HOSTS (Standard: localhost,127.0.0.1)
• CORS_ALLOWED_ORIGINS (Standard: lokale Entwicklungs-Origins)
• ALLOW_BYO_API_KEY (Standard: false)
• OPENROUTER_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY (optional)
• VIRUSTOTAL_API_KEY, GOOGLE_SAFE_BROWSING_API_KEY (optional)

Mitwirken

Beiträge sind willkommen, insbesondere zu passiven Recon-Modulen, Reporting, Frontend-UX und Testabdeckung.

Bitte lies die vollständigen Beitragsrichtlinien, bevor du einen Pull Request öffnest:

Contributing Guide

Hinweise

• Wenn kein externer KI-Schlüssel konfiguriert ist, speichert ReconScan eine lokale Fallback-Zusammenfassung.
• SQLite ist die Standard-Speicher-Engine für eine einfache lokale Nutzung.
• Dieses Repo ist bewusst leichtgewichtig und self-host-freundlich.

Lizenz

MIT. Siehe LICENSE.