Recon-Scan

ReconScan è uno scanner di recon passivo open-source con un backend FastAPI, una pipeline di worker asincrona e un frontend single-page. Puoi consultare il sito distribuito su https://recon-scan.vercel.app/

L'obiettivo è un segnale rapido: esegui una scansione, ottieni risultati modulo per modulo e ottieni un riepilogo AI che ora può essere esportato come report PDF curato.

Nota: la demo non è attiva perché ho esaurito i token AI. Puoi comunque ospitarla autonomamente.

Cos'è Questo Progetto (E Cosa Non È)

• È recon passivo. Non esegue brute force su endpoint, fuzzing o logica di exploit attiva.
• È utile per istantanee di postura, triage e reportistica.
• Non è un sostituto di un penetration testing completo.

Funzionalità

• 13 moduli passivi:
  • Header di sicurezza
  • SSL/TLS
  • DNS + autenticazione email (SPF/DMARC/MX)
  • WHOIS
  • Robots/sitemap
  • Enumerazione sottodomini
  • Fingerprinting tecnologico
  • Rilevamento WAF
  • Controlli CORS
  • Controlli di sicurezza dei cookie
  • Controlli di esposizione JS
  • Controlli di esposizione directory
  • Controlli di reputazione
• Esecuzione asincrona con worker Redis + ARQ.
• Fallback all'esecuzione in background in-process se l'accodamento fallisce.
• Riepilogo AI opzionale tramite OpenRouter / Anthropic / OpenAI.
• Generazione di report PDF da scansione + riepilogo AI.
• Frontend servito direttamente da FastAPI (un URL, un'app).

Avvio con un Solo Comando (Sviluppo Locale)

Se vuoi solo avviarlo rapidamente:

./start.sh

Cosa fa:

• Crea .env da .env.example se mancante.
• Crea .venv se necessario.
• Installa le dipendenze da requirements.txt.
• Avvia FastAPI con hot reload su http://localhost:8000.
• Forza USE_ARQ_QUEUE=false per un avvio locale più semplice senza Redis.

Interrompi con Ctrl+C.

Avvio con un Solo Comando (Docker)

./start-docker.sh

Cosa fa:

• Crea .env da .env.example se mancante.
• Avvia API + worker + Redis con Docker Compose.

Avvio Docker (Manuale)

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

Sviluppo Locale (Senza Docker)

1. Installa le dipendenze:

pip install -r requirements.txt

2. Crea il file env:

cp .env.example .env

3. Avvia l'API:

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

4. Avvia il worker in un altro terminale (consigliato):

arq app.worker.WorkerSettings

5. Apri:

http://localhost:8000

Esecuzione dei Test

Installa le dipendenze di test:

pip install -r requirements-dev.txt

Esegui l'intera suite:

pytest -q

Report PDF

Dopo il completamento di una scansione, clicca Download PDF nell'interfaccia.

Endpoint backend:

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

Il report include:

• Metadati del target e della scansione
• Riepilogo esecutivo AI (breve + narrativa completa quando disponibile)
• Tabella riepilogativa della gravità
• Risultati dettagliati modulo per modulo

API

• GET /health
• POST /scans
  • esempio di body:
    • { "target": "example.com" }
    • { "target": "example.com", "byoapi_key": "...", "byoapi_provider": "your_provider" }
  • note:
    • byoapi_key rifiutato a meno che ALLOW_BYO_API_KEY=true
    • target privati / loopback / riservati sono bloccati
    • user_id è opzionale e mantenuto per compatibilità
• GET /scans/{scan_id}
• GET /scans/{scan_id}/report.pdf

Configurazione

Da .env.example:

• DATABASE_URL (default: sqlite:///./reconscan.db)
• REDIS_URL (default: redis://localhost:6379)
• USE_ARQ_QUEUE (default: true)
• RATE_LIMIT_PER_MINUTE (default: 10)
• RATE_LIMIT_PER_DAY (default: 200)
• ALLOWED_HOSTS (default: localhost,127.0.0.1)
• CORS_ALLOWED_ORIGINS (default: origini di sviluppo locale)
• ALLOW_BYO_API_KEY (default: false)
• OPENROUTER_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY (opzionali)
• VIRUSTOTAL_API_KEY, GOOGLE_SAFE_BROWSING_API_KEY (opzionali)

Contribuire

I contributi sono benvenuti, specialmente per quanto riguarda moduli di recon passivo, reportistica, UX del frontend e copertura dei test.

Leggi le linee guida complete per i contributi prima di aprire una pull request:

Guida ai Contributi

Note

• Se non è configurata alcuna chiave AI esterna, ReconScan memorizza un riepilogo di fallback locale.
• SQLite è il motore di archiviazione predefinito per un facile utilizzo locale.
• Questo repository è intenzionalmente leggero e adatto all'hosting autonomo.

Licenza

MIT. Vedi LICENSE.