Recon-Scan

ReconScan è uno scanner passivo di riconoscimento open‑source con backend FastAPI, pipeline worker asincrona e frontend a pagina singola. Puoi visitare il sito pubblicato all'indirizzo https://recon-scan.vercel.app/.

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

Cosa Questo Progetto È (E Cosa Non È)

• È un riconoscimento passivo. Non esegue brute‑force su endpoint, fuzzing o logica attiva di sfruttamento.
• È utile per istantanee della postura, triage e reporting.
• Non sostituisce un test di penetrazione completo.

Caratteristiche

• 13 moduli passivi:
  • Security headers
  • SSL/TLS
  • DNS + email auth (SPF/DMARC/MX)
  • WHOIS
  • Robots/sitemap
  • Subdomain enumeration
  • Tech fingerprinting
  • WAF detection
  • CORS checks
  • Cookie security checks
  • JS exposure checks
  • Directory exposure checks
  • Reputation checks
• Esecuzione asincrona con Redis e worker ARQ.
• Fallback all'esecuzione in‑process in background se l'accodamento nella coda fallisce.
• Riepilogo AI opzionale tramite OpenRouter / Anthropic / OpenAI.
• Generazione di report PDF dalla scansione e dal riepilogo AI.
• Frontend servito direttamente da FastAPI (un URL, un'app).

Avvio con un Singolo Comando (Sviluppo Locale)

Se vuoi 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.

Ferma con Ctrl+C.

Avvio con un Singolo Comando (Docker)

./start-docker.sh

Cosa fa:

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

Avvio Manuale con Docker

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 che una scansione è completa, clicca su Download PDF nell'interfaccia utente.

Endpoint backend:

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

Il report include:

• Target e metadati della scansione
• Riepilogo esecutivo AI (versione breve e narrativa completa quando disponibile)
• Tabella riepilogativa della gravità
• Risultati dettagliati modulo per modulo

API

• GET /health
• POST /scans
  • esempio 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: )

Contribuire

I contributi sono benvenuti, specialmente per moduli di riconoscimento passivo, reporting, UX del frontend e copertura dei test.

Leggi le linee guida complete per il contributo prima di aprire una pull request:

Guida per il Contributo

Note

• Se non è configurata alcuna chiave AI esterna, ReconScan memorizza un riepilogo di fallback locale.
• SQLite è il motore di archiviazione predefinito per un uso locale semplice.
• Questo repository è volutamente leggero e progettato per essere auto‑hostato.

Licenza

MIT. Vedi LICENSE.