PhishCollector

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:

• Caricherà la pagina in un browser Chromium headless (JavaScript abilitato, User-Agent casuale, misure anti-bot stealth)
• Catturerà l'HTML completamente renderizzato, uno screenshot a pagina intera e ogni richiesta di rete
• Scaricherà tutte le risorse JavaScript e CSS collegate
• Fingerprinting del sito: IP/ASN/geo, certificato TLS, WHOIS, stack tecnologico, hash del favicon (mmh3 compatibile con Shodan), analisi dei form, rilevamento di indicatori di phishing
• Spider dei link scoperti, percorsi robots.txt e URL della sitemap (fuzzing opzionale con wordlist)
• Interrogherà URLhaus e/o VirusTotal per la reputazione delle minacce
• Salverà tutto in PostgreSQL per ricerche incrociate e analisi delle tendenze

Tutti i risultati sono accessibili tramite API REST, dashboard web e CLI.

Schermate

Avvio rapido

cp .env.example .env          # configure (see below)
docker compose up --build     # starts db + app + frontend

Configurazione

Tutte le impostazioni sono variabili d'ambiente con il prefisso PHISH_. Copia .env.example in .env e modifica.

Configurazione proxy

Instradare tutto il traffico in uscita attraverso un proxy mantiene nascosto l'IP dell'analista dal server di phishing.

Tor (anonimizzazione)

PHISH_PROXY_URL=socks5://127.0.0.1:9050
PHISH_PROXY_SSL_VERIFY=true   # Tor does not intercept TLS

Burp Suite (ispezione del traffico)

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=false influisce solo sulle connessioni HTTPS in uscita effettuate dal backend Python (plugin, fingerprinter, spider). Il browser Playwright opera già con ignore_https_errors=true indipendentemente da questa impostazione.

Attenzione: Non impostare mai PHISH_PROXY_SSL_VERIFY=false senza un proxy configurato — disabiliterà la validazione dei certificati per tutte le chiamate API esterne (URLhaus, VirusTotal).

API REST

Percorso base: /api/v1

Documentazione interattiva completa su /docs (Swagger UI).

Invia una scansione

curl -X POST http://localhost:8000/api/v1/collections \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://suspicious-site.example.com", "use_wordlist": true}'

CLI

# 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

Plugin di threat intelligence

URLhaus (abuse.ch)

Richiede una chiave di autenticazione gratuita da auth.abuse.ch.

PHISH_URLHAUS_ENABLED=true
PHISH_URLHAUS_API_KEY=<your-auth-key>

VirusTotal

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.

Aggiungere i propri plugin

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.

Personalizzazione degli indicatori di phishing

Il motore di rilevamento è intenzionalmente mantenuto come dati semplici e leggibili in modo che i ricercatori possano adattarlo ai kit e alle campagne che stanno tracciando. Tutto risiede in un unico file:

phishcollector/collector/fingerprint.py

PHISHING_PATTERNS — regole regex scansionate sull'HTML + JS renderizzato

Ogni voce è una tupla (regex, etichetta_leggibile) raggruppata in categorie. Una corrispondenza in qualsiasi categoria viene visualizzata nella scheda Indicatori e contribuisce al punteggio di minaccia.

PHISHING_PATTERNS: dict[str, list[tuple[str, str]]] = {

    "credential_harvest": [
        (r"document\.getElementById\(['\"]password['\"]", "JS reads password field by ID"),
        (r"btoa\s*\(.*password", "Base64-encoding a password"),
        # add your own rules here …
    ],

    "obfuscation": [
        (r"\beval\s*\(", "eval() usage"),
        (r"atob\s*\(", "Base64 decoding at runtime"),
    ],

    "exfiltration": [
        (r"api\.telegram\.org/bot", "Telegram bot exfiltration"),
        (r"@(?:gmail|yahoo|hotmail|outlook)\.com", "Freemail address in code"),
    ],

    "antibot": [
        (r"navigator\.webdriver", "WebDriver property check"),
        (r"ipqualityscore|ipqs\.com", "IPQS anti-bot service"),
    ],

    "kit_indicators": [
        (r"office365|microsoft365", "Office 365 phishing theme"),
        (r"paypal.*limit|limit.*paypal", "PayPal limitation theme"),
        # brand-new kit you spotted? add a rule here:
        (r"docusign.*sign|e.?sign.*document", "DocuSign lure"),
        (r"(?:dhl|fedex|ups).*track", "Parcel delivery lure"),
    ],
}

Per aggiungere una regola: aggiungi una tupla alla lista della categoria pertinente. Per aggiungere una categoria: aggiungi una nuova chiave — il nome della categoria appare automaticamente come intestazione di sezione nella scheda Indicatori.

# Example: track a newly discovered kit's fingerprint
"my_campaign_2024": [
    (r"panel\.php\?cmd=send", "Known C2 panel path"),
    (r"X-Mailer:\s*PHPMailer\s*5\.2\.1", "Specific PHPMailer version used by kit"),
],

TECH_SIGNATURES — rilevamento tecnologia

Firme confrontate con HTML, intestazioni delle risposte, cookie e URL finale. Le tecnologie rilevate appaiono nel pannello Tecnologie e sono ricercabili in tutte le raccolte.

TECH_SIGNATURES: dict[str, dict] = {
    "WordPress": {
        "html":    [r"wp-content", r"wp-includes"],
        "url":     [r"/wp-login\.php"],
        "cookies": ["wordpress_"],
    },
    # Add anything you want to track:
    "GoPhish": {
        "html": [r"rid=[a-zA-Z0-9]{20}"],
        "url":  [r"/track\?rid="],
    },
    "Evilginx": {
        "url":  [r"phishlets"],
        "html": [r"__utmz.*evilginx"],
    },
}

Ogni chiave della firma (il nome della tecnologia) diventa una stringa ricercabile tramite GET /search?technology=GoPhish.

Wordlist

La wordlist predefinita dello spider si trova in wordlists/phishing_paths.txt — un percorso per riga, # per i commenti. Contiene percorsi comuni dei kit di phishing (gate.php, send.php, result.php, pannelli admin, ecc.). Aggiungi percorsi per i kit che incontri regolarmente:

# Newly observed kit paths
/panel/send.php
/b374k.php
/uploads/gate.php

Note di sicurezza

• Gli URL di phishing non vengono mai renderizzati come link cliccabili nella GUI — ogni URL è testo semplice con solo un pulsante di copia.
• L'HTML catturato viene servito con Content-Type: text/plain e Content-Disposition: attachment — il browser lo scarica invece di renderizzarlo.
• Tutte le connessioni in uscita verso i server di phishing possono essere instradate attraverso un proxy in modo che l'IP reale dell'analista non venga mai esposto.
• Il confronto della chiave API utilizza hmac.compare_digest per prevenire attacchi temporali.
• nginx serve una Content Security Policy, X-Frame-Options: DENY e Referrer-Policy: no-referrer.
• L'eliminazione di una raccolta rimuove tutti gli artefatti su disco (screenshot, HTML, asset) e i record del database.

Archiviazione dati

Gli artefatti vengono scritti in PHISH_DATA_DIR (predefinito /data, volume montato in Docker):

/data/
  screenshots/   <collection-id>.png
  html/          <collection-id>.html
  assets/
    <collection-id>/
      <sha256-prefix>.js
      <sha256-prefix>.css

Tutto il resto (fingerprint, log HTTP, risultati dello spider, risultati dei plugin, tag, note) risiede in PostgreSQL.

Struttura del progetto

phishcollector/
  collector/
    browser.py        # Playwright capture, stealth JS, UA rotation
    fingerprint.py    # All fingerprinting probes + PHISHING_PATTERNS + TECH_SIGNATURES
    spider.py         # Link extraction, robots.txt, sitemap, wordlist fuzzing
    orchestrator.py   # Job lifecycle: ties all modules together
  plugins/
    __init__.py       # CheckResult dataclass
    urlhaus.py        # abuse.ch URLhaus plugin
    virustotal.py     # VirusTotal v3 plugin
    runner.py         # Runs enabled plugins concurrently
  api/
    routes.py         # FastAPI endpoints
  main.py             # App entry point, CORS, auth middleware
  models.py           # SQLAlchemy ORM models
  config.py           # Pydantic settings (env vars)
  database.py         # Engine, session factory, schema migrations
frontend/
  app.js              # Vanilla JS SPA
  style.css           # Cyber terminal UI
  nginx.conf          # Reverse proxy + security headers
wordlists/
  phishing_paths.txt  # Default spider wordlist

Sviluppo

# Start only the database
docker compose up db -d

# Run the API locally
pip install -r requirements.txt
playwright install chromium
uvicorn phishcollector.main:app --reload

# Run tests (if present)
pytest