PhishCollector è un framework di ricerca per raccogliere, analizzare e tracciare siti di phishing.
PhishCollector è un framework di ricerca per raccogliere, analizzare e tracciare siti di phishing. È intenzionalmente progettato come punto di partenza: le regole di rilevamento, le firme tecnologiche, le wordlist e i plugin sono tutte strutture dati in chiaro che i ricercatori sono invitati a leggere, estendere e adattare al proprio panorama di minacce.
Invia un URL sospetto e PhishCollector:
Tutti i risultati sono accessibili tramite API REST, dashboard web e CLI.
cp .env.example .env # configure (see below)
docker compose up --build # starts db + app + frontend
| Servizio | URL |
|---|---|
| GUI | http://localhost:3000 |
| Documentazione API | http://localhost:8000/docs |
| DB | localhost:5432 |
Tutte le impostazioni sono variabili d'ambiente con il prefisso PHISH_. Copia .env.example in .env e modifica.
| Variabile | Predefinito | Descrizione |
|---|---|---|
PHISH_DATABASE_URL | postgres://… | DSN PostgreSQL |
PHISH_API_KEY | (vuoto) | Se impostata, tutte le richieste richiedono X-API-Key: <valore> |
PHISH_DATA_DIR | /data | Radice di archiviazione per screenshot, HTML, asset |
PHISH_BROWSER_TIMEOUT | 30000 | Timeout caricamento pagina in ms |
PHISH_REQUEST_TIMEOUT | 15 | Timeout richiesta HTTP secondaria in secondi |
PHISH_MAX_SPIDER_PAGES | 50 | Numero massimo di URL visitati dallo spider per job |
PHISH_MAX_ASSET_SIZE | 10485760 | Dimensione massima file JS/CSS da memorizzare (byte) |
PHISH_PROXY_URL | (vuoto) | Proxy in uscita — vedi sotto |
PHISH_PROXY_SSL_VERIFY | true | Imposta false per proxy intercettanti — vedi sotto |
PHISH_URLHAUS_ENABLED | false | Abilita controllo reputazione URLhaus |
PHISH_VIRUSTOTAL_API_KEY | (vuoto) | Chiave API VirusTotal v3 (lascia vuoto per disabilitare) |
Instradare tutto il traffico in uscita attraverso un proxy mantiene nascosto l'IP dell'analista dal server di phishing.
PHISH_PROXY_URL=socks5://127.0.0.1:9050
PHISH_PROXY_SSL_VERIFY=true # Tor does not intercept TLS
Burp agisce come intermediario TLS e presenta il proprio certificato CA per ogni connessione HTTPS. Senza disabilitare la verifica SSL, ogni richiesta HTTPS attraverso il proxy fallirà.
PHISH_PROXY_URL=http://127.0.0.1:8080
PHISH_PROXY_SSL_VERIFY=false # required for Burp / intercepting proxies
Nota:
PHISH_PROXY_SSL_VERIFY=falseinfluisce solo sulle connessioni HTTPS in uscita effettuate dal backend Python (plugin, fingerprinter, spider). Il browser Playwright opera già conignore_https_errors=trueindipendentemente da questa impostazione.
Attenzione: Non impostare mai
PHISH_PROXY_SSL_VERIFY=falsesenza un proxy configurato — disabiliterà la validazione dei certificati per tutte le chiamate API esterne (URLhaus, VirusTotal).
Percorso base: /api/v1
| Metodo | Percorso | Descrizione |
|---|---|---|
POST | /collections | Invia un URL per la raccolta |
GET | /collections | Elenca tutte le raccolte |
GET | /collections/{id} | Dettagli completi + fingerprint |
GET | /collections/{id}/screenshot | PNG a pagina intera |
GET | /collections/{id}/html | HTML catturato (scaricato come testo semplice) |
GET | /collections/{id}/requests | Registro delle richieste di rete |
GET | /collections/{id}/spider | Risultati dello spider |
GET | /collections/{id}/plugins | Risultati del plugin di threat intelligence |
POST | /collections/{id}/plugins/refresh | Riesegue i plugin (ad es. recupera risultato VT in sospeso) |
POST | /collections/{id}/rescan | Raccoglie nuovamente lo stesso URL (l'originale viene conservato) |
PATCH | /collections/{id} | Aggiorna tag e note |
GET | /collections/{id}/export?format=json|csv | Esporta dati della raccolta |
DELETE | /collections/{id} | Elimina una raccolta e tutti i suoi artefatti |
GET | /search | Cerca fingerprint per IP, hash del favicon, tecnologia, paese, titolo |
Documentazione interattiva completa su /docs (Swagger UI).
curl -X POST http://localhost:8000/api/v1/collections \
-H 'Content-Type: application/json' \
-d '{"url": "https://suspicious-site.example.com", "use_wordlist": true}'
# Install (inside container or local venv with requirements.txt)
pip install -e .
# Invia un URL e attendi il completamento
phishcollector collect https://target.example.com --wait
# Con fuzzing tramite wordlist
phishcollector collect https://target.example.com --wordlist --wait
# Elenca i job recenti
phishcollector list
# Visualizza dettaglio completo
phishcollector detail <job-id>
# Scarica screenshot
phishcollector screenshot <job-id> -o capture.png
# Cerca per stack tecnologico / hash favicon / paese
phishcollector search --tech WordPress --country RU
phishcollector search --favicon-hash -1234567890
Richiede una chiave di autenticazione gratuita da auth.abuse.ch.
PHISH_URLHAUS_ENABLED=true
PHISH_URLHAUS_API_KEY=<your-auth-key>
Richiede una chiave API gratuita o a pagamento da virustotal.com.
PHISH_VIRUSTOTAL_API_KEY=<your-key>
Quando un URL non è ancora stato analizzato da VT, PhishCollector lo invia per la scansione e recupera automaticamente il risultato ogni 30 secondi fino a quando non viene risolto.
Ogni plugin è un singolo file in phishcollector/plugins/ che espone una funzione asincrona:
# phishcollector/plugins/myplugin.py
from . import CheckResult
async def check(url: str, proxy_url=None, ssl_verify=True) -> CheckResult:
# query your feed / API here
return CheckResult(
plugin_name="myplugin",
status="malicious", # malicious | suspicious | clean | unknown | error
score=0.95, # 0.0–1.0, or None
result={"raw": ...}, # stored as JSONB, displayed in the GUI
)
Quindi registralo in phishcollector/plugins/runner.py:
from .myplugin import check as myplugin_check
tasks.append(myplugin_check(url, proxy_url=settings.proxy_url, ssl_verify=settings.proxy_ssl_verify))
Non sono necessarie altre modifiche: il risultato viene automaticamente memorizzato, visualizzato nella dashboard e incluso nel punteggio di minaccia.