PhishCollector

PhishCollector es un marco de investigación para recolectar, analizar y rastrear sitios de phishing. Está diseñado intencionalmente como un punto de partida — las reglas de detección, las firmas de tecnología, las listas de palabras y los complementos son todas estructuras de datos simples que se espera que los investigadores lean, extiendan y adapten a su propio panorama de amenazas.

Envía una URL sospechosa y PhishCollector hará lo siguiente:

• Cargará la página en un navegador Chromium sin cabeza (JavaScript habilitado, User-Agent aleatorio, medidas antidetect furtivas)
• Capturará el HTML renderizado por completo, una captura de pantalla de página completa y cada solicitud de red
• Descargará todos los activos JavaScript y CSS enlazados
• Fingerprint el sitio: IP/ASN/geo, certificado TLS, WHOIS, pila tecnológica, hash de favicon (mmh3 compatible con Shodan), análisis de formularios, detección de indicadores de phishing
• Spider los enlaces descubiertos, las rutas de robots.txt y las URLs del sitemap (fuzzing opcional de listas de palabras)
• Consultar URLhaus y/o VirusTotal para reputación de amenazas
• Almacenar todo en PostgreSQL para búsqueda entre colecciones y análisis de tendencias

Todos los resultados son accesibles a través de una API REST, un panel web y una CLI.

---

Screenshots

---

Inicio rápido

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

Servicio	URL
GUI	http://localhost:3000
Documentación API	http://localhost:8000/docs
BD	localhost:5432

---

Configuración

Todas las configuraciones son variables de entorno con el prefijo PHISH_. Copia .env.example a .env y ajústalo.

Variable	Predeterminado	Descripción
PHISH_DATABASE_URL	postgres://…	Cadena de conexión de PostgreSQL
PHISH_API_KEY	(vacío)	Si se establece, todas las solicitudes requieren X-API-Key: <value>
PHISH_DATA_DIR	/data	Directorio raíz para almacenar capturas de pantalla, HTML, activos
PHISH_BROWSER_TIMEOUT	30000	Tiempo de espera de carga de página en ms
PHISH_REQUEST_TIMEOUT	15	Tiempo de espera de solicitud HTTP en segundos
PHISH_MAX_SPIDER_PAGES	50	Máximo de URLs que el spider visita por trabajo
PHISH_MAX_ASSET_SIZE	10485760	Tamaño máximo de archivo JS/CSS a almacenar (bytes)
PHISH_PROXY_URL	(vacío)	Proxy de salida — ver más abajo
PHISH_PROXY_SSL_VERIFY	true	Establecer false para proxies interceptores — ver más abajo
PHISH_URLHAUS_ENABLED	false	Habilitar comprobación de reputación de URLhaus
PHISH_VIRUSTOTAL_API_KEY	(vacío)	Clave API de VirusTotal v3 (dejar vacío para deshabilitar)

---

Configuración de proxy

Enrutar todo el tráfico saliente a través de un proxy mantiene oculta la IP del analista del servidor de phishing.

Tor (anonimización)

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

Burp Suite (inspección de tráfico)

Burp actúa como un intermediario TLS (man-in-the-middle) y presenta su propio certificado CA para cada conexión HTTPS. Sin deshabilitar la verificación SSL, cada solicitud HTTPS a través del proxy fallará.

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 solo afecta las conexiones HTTPS salientes realizadas por el backend de Python (plugins, fingerprint, spider). El navegador Playwright ya opera con ignore_https_errors=true independientemente de esta configuración.

Advertencia: Nunca establezcas PHISH_PROXY_SSL_VERIFY=false sin un proxy configurado — deshabilitaría la validación de certificados para todas las llamadas API externas (URLhaus, VirusTotal).

---

API REST

Ruta base: /api/v1

Método	Ruta	Descripción
POST	/collections	Enviar una URL para su recolección
GET	/collections	Listar todas las colecciones
GET	/collections/{id}	Detalle completo + huella digital
GET	/collections/{id}/screenshot	Captura de pantalla de página completa PNG
GET	/collections/{id}/html	HTML capturado (descargado como texto plano)
GET	/collections/{id}/requests	Registro de solicitudes de red
GET	/collections/{id}/spider	Resultados del spider
GET	/collections/{id}/plugins	Resultados del complemento de inteligencia de amenazas
POST	/collections/{id}/plugins/refresh	Re-ejecutar complementos (ej. obtener resultado VT pendiente)
POST	/collections/{id}/rescan	Recolectar la misma URL (la original se conserva)
PATCH	/collections/{id}	Actualizar etiquetas y notas
GET	/collections/{id}/export?format=json|csv	Exportar datos de la colección
DELETE	/collections/{id}	Eliminar una colección y todos sus artefactos
GET	/search	Buscar huellas digitales por IP, hash de favicon, tecnología, país, título

Documentación interactiva completa en /docs (Swagger UI).

Enviar un escaneo

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 .

# Submit a URL and wait for completion
phishcollector collect https://target.example.com --wait

# With wordlist fuzzing
phishcollector collect https://target.example.com --wordlist --wait

# List recent jobs
phishcollector list

# View full detail
phishcollector detail <job-id>

# Download screenshot
phishcollector screenshot <job-id> -o capture.png

# Search by tech stack / favicon hash / country
phishcollector search --tech WordPress --country RU
phishcollector search --favicon-hash -1234567890

---

Complementos de inteligencia de amenazas

URLhaus (abuse.ch)

Requiere una Auth-Key gratuita de auth.abuse.ch.

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

VirusTotal

Requiere una clave API gratuita o de pago de virustotal.com.

PHISH_VIRUSTOTAL_API_KEY=<your-key>

Cuando una URL aún no ha sido analizada por VT, PhishCollector la envía para su escaneo y automáticamente vuelve a obtener el resultado cada 30 segundos hasta que se resuelve.

Agregando tus propios complementos

Cada complemento es un solo archivo en phishcollector/plugins/ que expone una función async:

# 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
    )

Luego regístralo en 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))