Recon-Scan

ReconScan ist ein Open-Source-Scanner für passive Reconnaissance mit einem FastAPI-Backend, einer asynchronen Worker-Pipeline und einem Single-Page-Frontend. Die bereitgestellte Website kannst du unter https://recon-scan.vercel.app/ ansehen.

Es geht um schnelle Ergebnisse: Führe einen Scan aus, erhalte modulweise Befunde und eine KI-Zusammenfassung, die jetzt als ausgefeilter PDF-Bericht exportiert werden kann.

Was dieses Projekt ist (und was nicht)

• Es ist passive Reconnaissance. Es führt keine Brute-Force-Angriffe auf Endpunkte durch, kein Fuzzing und keine aktive Exploit-Logik aus.
• Es eignet sich gut für Sicherheitslagebilder, Triage und Berichterstattung.
• Es ist kein Ersatz für einen vollständigen Penetrationstest.

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-Expositionsprüfungen
  • Verzeichnis-Expositionsprüfungen
  • Reputationsprüfungen
• Asynchrone Ausführung mit Redis + ARQ-Worker.
• Fallback auf prozessinterne Hintergrundausführung, falls das Einreihen in die Warteschlange fehlschlägt.
• Optionale KI-Zusammenfassung über OpenRouter / Anthropic / OpenAI.
• PDF-Berichtserstellung aus Scan + KI-Zusammenfassung.
• Frontend wird direkt von FastAPI bereitgestellt (eine URL, eine App).

Start mit einem Befehl (lokale Entwicklung)

Wenn du es einfach schnell zum Laufen bringen willst:

./start.sh

Was dabei passiert:

• Erstellt .env aus .env.example, falls fehlend.
• Erstellt bei Bedarf .venv.
• Installiert Abhängigkeiten aus requirements.txt.
• Startet FastAPI mit Hot Reload unter http://localhost:8000.
• Erzwingt USE_ARQ_QUEUE=false für einen einfacheren lokalen Start ohne Redis.

Stoppen mit Ctrl+C.

Start mit einem Befehl (Docker)

./start-docker.sh

Was dabei passiert:

• Erstellt .env aus .env.example, falls fehlend.
• 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

Testabhängigkeiten installieren:

pip install -r requirements-dev.txt

Gesamte Testsuite ausführen:

pytest -q

PDF-Berichte

Nach Abschluss eines Scans klicke in der Benutzeroberfläche auf Download PDF.

Backend-Endpunkt:

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

Der Bericht enthält:

• Ziel- und Scan-Metadaten
• KI-Executive-Summary (kurz + vollständige Beschreibung, sofern verfügbar)
• Tabelle mit Schweregrad-Übersicht
• Detaillierte modulweise Befunde

API

• GET /health
• POST /scans
  • Beispiel für den Request-Body:
    • { "target": "example.com" }
    • { "target": "example.com", "byoapi_key": "...", "byoapi_provider": "your_provider" }
  • Hinweise:
    • byoapi_key wird abgelehnt, außer ALLOW_BYO_API_KEY=true
    • private / Loopback / reservierte Ziele sind blockiert
    • user_id ist optional und bleibt aus Kompatibilitätsgründen erhalten
• 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: Origins der lokalen Entwicklung)
• ALLOW_BYO_API_KEY (Standard: )

Mitwirken

Beiträge sind willkommen, insbesondere im Bereich passiver Recon-Module, Berichterstattung, Frontend-UX und Testabdeckung.

Bitte lies vor dem Eröffnen eines Pull-Requests die vollständigen Beitragsrichtlinien:

Beitragsleitfaden

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 Repository ist bewusst leichtgewichtig und selbsthosting-freundlich.

Lizenz

MIT. Siehe LICENSE.