PhishCollector é um framework de pesquisa para coletar, analisar e rastrear sites de phishing.
PhishCollector é um framework de pesquisa para coletar, analisar e rastrear sites de phishing. Ele é propositadamente projetado como um ponto de partida — as regras de detecção, assinaturas de tecnologia, listas de palavras e plugins são todas estruturas de dados simples que os pesquisadores devem ler, estender e adaptar ao seu próprio cenário de ameaças.
Envie uma URL suspeita e o PhishCollector irá:
Todos os resultados são acessíveis via uma API REST, um painel web e uma CLI.
cp .env.example .env # configure (veja abaixo)
docker compose up --build # inicia db + app + frontend
| Serviço | URL |
|---|---|
| GUI | http://localhost:3000 |
| Documentação da API | http://localhost:8000/docs |
| BD | localhost:5432 |
Todas as configurações são variáveis de ambiente com o prefixo PHISH_. Copie .env.example para .env e ajuste.
| Variável | Padrão | Descrição |
|---|---|---|
PHISH_DATABASE_URL | postgres://… | DSN do PostgreSQL |
PHISH_API_KEY | (vazio) | Se definido, todas as requisições exigem X-API-Key: <valor> |
PHISH_DATA_DIR | /data | Raiz de armazenamento para screenshots, HTML, ativos |
PHISH_BROWSER_TIMEOUT | 30000 | Timeout de carregamento de página em ms |
PHISH_REQUEST_TIMEOUT | 15 | Timeout de sub-requisição HTTP em segundos |
PHISH_MAX_SPIDER_PAGES | 50 | Máximo de URLs que o spider visita por job |
PHISH_MAX_ASSET_SIZE | 10485760 | Tamanho máximo de arquivo JS/CSS a armazenar (bytes) |
PHISH_PROXY_URL | (vazio) | Proxy de saída — veja abaixo |
PHISH_PROXY_SSL_VERIFY | true | Defina false para proxies interceptadores — veja abaixo |
PHISH_URLHAUS_ENABLED | false | Habilita verificação de reputação URLhaus |
PHISH_VIRUSTOTAL_API_KEY | (vazio) | Chave de API do VirusTotal v3 (deixe vazio para desabilitar) |
Roteando todo o tráfego de saída através de um proxy mantém o IP do analista oculto do servidor de phishing.
PHISH_PROXY_URL=socks5://127.0.0.1:9050
PHISH_PROXY_SSL_VERIFY=true # Tor não intercepta TLS
O Burp atua como um intermediário TLS e apresenta seu próprio certificado CA para cada conexão HTTPS. Sem desabilitar a verificação SSL, toda requisição HTTPS através do proxy falhará.
PHISH_PROXY_URL=http://127.0.0.1:8080
PHISH_PROXY_SSL_VERIFY=false # necessário para Burp / proxies interceptadores
Nota:
PHISH_PROXY_SSL_VERIFY=falseafeta apenas as conexões HTTPS de saída feitas pelo backend Python (plugins, fingerprinter, spider). O navegador Playwright já opera comignore_https_errors=trueindependentemente desta configuração.
Aviso: Nunca defina
PHISH_PROXY_SSL_VERIFY=falsesem um proxy configurado — isso desabilitaria a validação de certificado para todas as chamadas de API externas (URLhaus, VirusTotal).
Caminho base: /api/v1
| Método | Caminho | Descrição |
|---|---|---|
POST | /collections | Enviar uma URL para coleta |
GET | /collections | Listar todas as coleções |
GET | /collections/{id} | Detalhe completo + fingerprint |
GET | /collections/{id}/screenshot | PNG da página inteira |
GET | /collections/{id}/html | HTML capturado (baixado como texto simples) |
GET | /collections/{id}/requests | Log de requisições de rede |
GET | /collections/{id}/spider | Resultados do spider |
GET | /collections/{id}/plugins | Resultados dos plugins de inteligência de ameaças |
POST | /collections/{id}/plugins/refresh | Reexecutar plugins (ex.: buscar resultado pendente do VT) |
POST | /collections/{id}/rescan | Recoletar a mesma URL (o original é preservado) |
PATCH | /collections/{id} | Atualizar tags e notas |
GET | /collections/{id}/export?format=json|csv | Exportar dados da coleção |
DELETE | /collections/{id} | Deletar uma coleção e todos os seus artefatos |
GET | /search | Buscar fingerprints por IP, hash de favicon, tecnologia, país, título |
Documentação interativa completa em /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}'
# Instalar (dentro do container ou venv local com requirements.txt)
pip install -e .
# Enviar uma URL e aguardar conclusão
phishcollector collect https://target.example.com --wait
# Com fuzzing de wordlist
phishcollector collect https://target.example.com --wordlist --wait
# Listar jobs recentes
phishcollector list
# Ver detalhe completo
phishcollector detail <job-id>
# Baixar screenshot
phishcollector screenshot <job-id> -o capture.png
# Buscar por stack tecnológico / hash de favicon / país
phishcollector search --tech WordPress --country RU
phishcollector search --favicon-hash -1234567890
Requer uma Auth-Key gratuita de auth.abuse.ch.
PHISH_URLHAUS_ENABLED=true
PHISH_URLHAUS_API_KEY=<sua-chave-de-autenticação>
Requer uma chave de API gratuita ou paga de virustotal.com.
PHISH_VIRUSTOTAL_API_KEY=<sua-chave>
Quando uma URL ainda não foi analisada pelo VT, o PhishCollector a envia para varredura e automaticamente busca novamente o resultado a cada 30 segundos até que seja resolvido.
Cada plugin é um único arquivo em phishcollector/plugins/ que expõe uma função assíncrona:
# phishcollector/plugins/myplugin.py
from . import CheckResult
async def check(url: str, proxy_url=None, ssl_verify=True) -> CheckResult:
# consulte seu feed / API aqui
return CheckResult(
plugin_name="myplugin",
status="malicious", # malicious | suspicious | clean | unknown | error
score=0.95, # 0.0–1.0, ou None
result={"raw": ...}, # armazenado como JSONB, exibido na GUI
)
Em seguida, registre-o em 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))
Nenhuma outra alteração é necessária — o resultado é automaticamente armazenado, exibido no painel e considerado na pontuação de ameaça.