Recon-Scan

ReconScan est un scanner de reconnaissance passive open-source avec un backend FastAPI, un pipeline de workers asynchrone et un frontend single-page. Vous pouvez consulter le site déployé sur https://recon-scan.vercel.app/

L'objectif est d'obtenir un signal rapide : lancez un scan, obtenez des résultats module par module, et obtenez un résumé IA qui peut désormais être exporté sous forme de rapport PDF soigné.

Note : la démo n'est pas en ligne car j'ai épuisé mes jetons IA. Vous pouvez toujours l'auto-héberger.

Ce que ce projet est (et n'est pas)

• C'est de la reconnaissance passive. Il ne force pas les endpoints, ne fait pas de fuzzing et n'exécute pas de logique d'exploitation active.
• Il est adapté aux instantanés de posture, au triage et au reporting.
• Il ne remplace pas un test d'intrusion complet.

Fonctionnalités

• 13 modules passifs :
  • En-têtes de sécurité
  • SSL/TLS
  • DNS + authentification email (SPF/DMARC/MX)
  • WHOIS
  • Robots/sitemap
  • Énumération de sous-domaines
  • Empreinte technologique
  • Détection de WAF
  • Vérifications CORS
  • Vérifications de sécurité des cookies
  • Vérifications d'exposition JS
  • Vérifications d'exposition de répertoires
  • Vérifications de réputation
• Exécution asynchrone avec Redis + worker ARQ.
• Repli vers une exécution en arrière-plan dans le processus si la mise en file d'attente échoue.
• Résumé IA optionnel via OpenRouter / Anthropic / OpenAI.
• Génération de rapport PDF à partir du scan + résumé IA.
• Frontend servi directement par FastAPI (une URL, une application).

Démarrage en une commande (développement local)

Si vous voulez simplement le lancer rapidement :

./start.sh

Ce que cela fait :

• Crée .env à partir de .env.example s'il est absent.
• Crée .venv si nécessaire.
• Installe les dépendances depuis requirements.txt.
• Démarre FastAPI avec rechargement à chaud sur http://localhost:8000.
• Force USE_ARQ_QUEUE=false pour un démarrage local sans Redis plus simple.

Arrêtez avec Ctrl+C.

Démarrage en une commande (Docker)

./start-docker.sh

Ce que cela fait :

• Crée .env à partir de .env.example s'il est absent.
• Démarre l'API + le worker + Redis avec Docker Compose.

Démarrage Docker (manuel)

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

Développement local (sans Docker)

1. Installez les dépendances :

pip install -r requirements.txt

2. Créez le fichier d'environnement :

cp .env.example .env

3. Démarrez l'API :

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

4. Démarrez le worker dans un autre terminal (recommandé) :

arq app.worker.WorkerSettings

5. Ouvrez :

http://localhost:8000

Exécution des tests

Installez les dépendances de test :

pip install -r requirements-dev.txt

Lancez la suite complète :

pytest -q

Rapports PDF

Une fois un scan terminé, cliquez sur Download PDF dans l'interface.

Endpoint backend :

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

Le rapport inclut :

• Les métadonnées de la cible et du scan
• Le résumé exécutif IA (version courte + narration complète lorsqu'elle est disponible)
• Un tableau de synthèse des sévérités
• Les résultats détaillés module par module

API

• GET /health
• POST /scans
  • exemple de corps :
    • { "target": "example.com" }
    • { "target": "example.com", "byoapi_key": "...", "byoapi_provider": "your_provider" }
  • remarques :
    • byoapi_key est rejeté sauf si ALLOW_BYO_API_KEY=true
    • les cibles privées / loopback / réservées sont bloquées
    • user_id est optionnel et conservé pour compatibilité
• GET /scans/{scan_id}
• GET /scans/{scan_id}/report.pdf

Configuration

Depuis .env.example :

• DATABASE_URL (par défaut : sqlite:///./reconscan.db)
• REDIS_URL (par défaut : redis://localhost:6379)
• USE_ARQ_QUEUE (par défaut : true)
• RATE_LIMIT_PER_MINUTE (par défaut : 10)
• RATE_LIMIT_PER_DAY (par défaut : 200)
• ALLOWED_HOSTS (par défaut : localhost,127.0.0.1)
• CORS_ALLOWED_ORIGINS (par défaut : origines de développement local)
• ALLOW_BYO_API_KEY (par défaut : false)
• OPENROUTER_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY (optionnel)
• VIRUSTOTAL_API_KEY, GOOGLE_SAFE_BROWSING_API_KEY (optionnel)

Contribution

Les contributions sont les bienvenues, en particulier autour des modules de reconnaissance passive, du reporting, de l'UX du frontend et de la couverture de tests.

Veuillez lire les directives de contribution complètes avant d'ouvrir une pull request :

Guide de contribution

Remarques

• Si aucune clé IA externe n'est configurée, ReconScan stocke un résumé de repli local.
• SQLite est le moteur de stockage par défaut pour un usage local facile.
• Ce dépôt est volontairement léger et adapté à l'auto-hébergement.

Licence

MIT. Voir LICENSE.