openSquat Core

📑 Índice

• O que é openSquat?
• Destaques
• Modelo Open-Core
• Principais Recursos
• Início Rápido
• Requisitos
• Uso
• Modos Premium e API
• Configuração
• Automação
• Referência da CLI
• Contribuindo
• Autor
• Licença

🎯 O que é openSquat?

openSquat é uma ferramenta de segurança Open Source Intelligence (OSINT) que identifica ameaças de cybersquatting direcionadas à sua marca ou domínios:

🌟 Destaques

"Um canivete suíço poderoso para proteção de marca" — WhoisXML API Blog, Agosto de 2022

"Uma ferramenta com poder insano para combater typosquatting e todos os tipos de travessuras cibernéticas relacionadas." — WhoisXML API Blog, Agosto de 2022

"Uma ferramenta útil para coletar informações sobre domínios recém-registrados." — Classificada entre as 5 principais ferramentas de detecção de phishing — SOCRadar Blog, Julho de 2022

"O openSquat fornece proteção essencial contra ataques de squatting e phishing por meio de monitoramento e detecção automatizados." — Prince Yadav, TutorialsPoint, Março de 2026

Citação Acadêmica

"O OpenSquat identificou 103 domínios de squatting, 960 sites de phishing ativos e 53 domínios com certificados suspeitos." — Sharma et al., Journal of Information Security and Cybercrimes Research (JISCR), Vol. 7, Edição 1, Junho de 2024

🔓 Modelo Open-Core

O openSquat segue um modelo open-core:

• Mecanismo de detecção principal — Código aberto e orientado pela comunidade
• Capacidades avançadas — Entregues por meio de serviços de inteligência comercial

Esse modelo permite transparência e colaboração da comunidade, ao mesmo tempo que suporta os requisitos de escala, confiabilidade e operação corporativa.

✨ Principais Recursos

• 📅 Feeds diários de NRD — Atualizações automáticas de domínios recém-registrados
• 🔍 Detecção de similaridade — Algoritmo de distância Levenshtein
• 🔓 Três modos de operação — Comunidade (feed gratuito), Feed Premium (feed pago, mesmo pipeline local) ou API Premium (serviço de similares hospedado). Os dois modos Premium compartilham uma única chave API openSquat — veja Modos Premium e API.
• 🛡️ Integração com VirusTotal — Verifique a reputação do domínio
• 🌐 Validação DNS Quad9 — Identifique domínios maliciosos
• 📜 Transparência de Certificados — Monitore certificados SSL/TLS
• 📊 Múltiplos formatos de saída — TXT, JSON, CSV

🚀 Início Rápido

Instalar via pip (recomendado)

pip install opensquat
opensquat -k keywords.txt

Ou clonar o repositório

git clone https://github.com/atenreiro/opensquat
cd opensquat
pip install -r requirements.txt
python3 opensquat.py -k keywords.txt

Usuários do repositório: em todos os exemplos abaixo, substitua opensquat por python3 opensquat.py para executar a partir do checkout clonado.

📦 Requisitos

• Python 3.10+
• Dependências: confusable_homoglyphs, homoglyphs, colorama, requests, dnspython, beautifulsoup4

📖 Uso

Comandos Básicos

# Execução padrão
opensquat

# Mostrar todas as opções
opensquat -h

# Usar arquivo de palavras-chave personalizado
opensquat -k my_keywords.txt

Opções de Validação

# Validação DNS via Quad9
opensquat --dns

# Verificar logs de Transparência de Certificados
opensquat --ct

# Escanear portas abertas (80/443)
opensquat --portcheck

# Cruzar referências com bancos de dados de phishing
opensquat --phishing results.txt

Formatos de Saída

# Salvar como JSON
opensquat -o results.json -t json

# Salvar como CSV
opensquat -o results.csv -t csv

Níveis de Confiança

Nota: No lado da API (--api), os cinco níveis de confiança correspondem a quatro valores de difusão (exact, low, auto, high) — -c 3 e -c 4 ambos mapeiam para high. Veja Modos Premium e API para o mapeamento completo e como sobrescrever com --api-fuzziness.

💎 Modos Premium e API

O openSquat suporta três modos. O padrão (Comunidade) não muda — usuários existentes não precisam de nenhuma bandeira. Os dois modos Premium compartilham uma única chave API openSquat; escolha Feed Premium se quiser o mesmo pipeline de detecção local com um feed maior, ou API Premium se quiser detecção no lado do servidor sem baixar o feed local.

Obter uma chave API

Cadastre-se em opensquat.com para obter uma chave. A mesma chave funciona tanto para Feed Premium (--premium) quanto para API Premium (--api).

Fornecer a chave API (ordem de prioridade)

1. --api-key SUA_CHAVE na linha de comando
2. Variável de ambiente OPENSQUAT_API_KEY
3. api_key.txt no diretório atual (uma chave por arquivo, comentários # permitidos)

A bandeira CLI é visível na saída do ps. Prefira a variável de ambiente ou o arquivo de chave em ambientes compartilhados.

Exemplos

# Modo Feed Premium — mesmo pipeline local, feed maior
export OPENSQUAT_API_KEY=os_xxxxxxxxxxxx
opensquat -k keywords.txt --premium

# Modo API Premium — detecção no servidor por palavra-chave
opensquat -k keywords.txt --api

# API Premium + verificação de reputação DNS em cada domínio retornado
opensquat -k keywords.txt --api --dns

# API Premium com saída JSON agrupada por palavra-chave
opensquat -k keywords.txt --api -t json -o results.json

# Ajustar a pesquisa da API Premium
opensquat -k keywords.txt --api --api-fuzziness high --api-history-days 7 --api-max-results 200

Quando --premium ou --api carregam uma chave com sucesso, a CLI imprime uma linha de confirmação mascarada para que você possa verificar qual chave foi captada sem vazá-la:

[*] Chave API carregada: os_gL...L5Mb

No modo API Premium, o resumo da execução informa o modo ativo, o número de chamadas de API feitas e seu saldo restante com o delta de uso (por exemplo, 4972 (usou 4 de 4976 nesta execução)). Linhas de progresso por palavra-chave aparecem na mesma ordem do seu arquivo de palavras-chave, mesmo que as chamadas sejam executadas em paralelo. A exaustão de cota (HTTP 429) retorna resultados parciais de forma graciosa; erros de autenticação (401) e erros de plano (403) abortam com uma mensagem clara.

Se o backend limitar sua requisição (HTTP 429 com cabeçalho Retry-After), a ferramenta distingue isso da exaustão de cota: você verá um aviso amarelo [!] Limite de taxa atingido (repetir em Ns) em vez da mensagem vermelha cota esgotada, resultados parciais ainda são retornados, e o resumo preserva seu saldo real da API para que você veja exatamente quantos créditos realmente usou. Para evitar disparar limites de taxa em varreduras grandes, passe --api-rate-limit N para limitar requisições de saída por segundo em todos os workers. Um valor de 8 é um ponto de partida seguro para a maioria dos backends.

# Limitar a 8 requisições/segundo em todos os workers
opensquat -k keywords.txt --api --api-rate-limit 8

Recomendação de formato de saída

JSON é o formato de saída recomendado para o modo API Premium porque a API retorna metadados por domínio que os outros formatos não conseguem transportar tão claramente: o TLD registrado, a data da primeira aparição no NRD, uma bandeira de homógrafo IDN e a renderização unicode do homógrafo quando o domínio é um.

opensquat -k keywords.txt --api -t json -o results.json

Exemplo da saída mais rica no modo API Premium (truncado):

[
  {
    "keyword": "microsoft",
    "domains": [
      {"domain": "securite-microsoft.fr", "tld": "fr", "date": "09-04-2026", "idn": false},
      {"domain": "xn--mirosoft-hw7c.com", "tld": "com", "date": "09-04-2026", "idn": true, "unicode": "miᴄrosoft.com"}
    ]
  }
]

A bandeira idn mais a renderização unicode permitem ver rapidamente que xn--mirosoft-hw7c.com é na verdade ᴄ (Letra Latina Minúscula C maiúscula) se passando pelo c em "microsoft" — informação que uma string punycode simples esconde completamente.

A saída CSV também é suportada e produz uma linha por domínio com as mesmas colunas de metadados, adequada para analistas trabalhando em Excel ou pandas:

opensquat -k keywords.txt --api -t csv -o results.csv

O CSV é escrito com um BOM UTF-8 para que o Excel no Windows renderize corretamente a coluna unicode de homógrafos.

Os modos Comunidade e Feed Premium emitem a mesma forma JSON de alto nível para consistência entre modos, mas apenas com o campo domain preenchido por entrada — o feed NRD não carrega os metadados por domínio que apenas a API hospedada possui:

[
  {
    "keyword": "microsoft",
    "domains": [
      {"domain": "mirosoft.com"},
      {"domain": "mcrosoft.net"}
    ]
  }
]

Se você passar --api-key sem também selecionar --premium ou --api, a CLI imprime uma dica de uma linha informando que a chave será ignorada no modo Comunidade (sem troca silenciosa de modo).

No modo API Premium, -c/--confidence é mapeado automaticamente para difusão da API (0→exact, 1→low, 2→auto, 3→high, 4→high). Use --api-fuzziness para sobrescrever.

A API Premium (--api) é incompatível com --doppelganger e -d/--domains.

⚙️ Configuração

Arquivo de Palavras-chave (keywords.txt)

# Linhas começando com # são comentários
mycompany
mybrand
myproduct

Chave API do VirusTotal (vt_key.txt)

Para usar --vt ou --subdomains, adicione sua chave API:

# Obtenha sua chave API gratuita em https://www.virustotal.com
sua_chave_api_aqui

Chave API do openSquat (api_key.txt)

Necessária para --premium e --api. Crie um arquivo api_key.txt no diretório de trabalho:

# Obtenha sua chave em https://opensquat.com
# Linhas começando com # são ignoradas; a primeira linha não comentada é usada.
os_sua_chave_aqui

A CLI resolve a chave nesta ordem: bandeira --api-key → variável de ambiente $OPENSQUAT_API_KEY → arquivo api_key.txt. Os métodos de variável de ambiente e arquivo são preferíveis à bandeira CLI em ambientes compartilhados, pois argumentos CLI são visíveis via ps.

🤖 Automação

Execute diariamente via crontab:

# Instalado via pip (recomendado) — todos os dias às 8h, feeds atualizam ~7h30 UTC
0 8 * * * cd /caminho/para/dir-de-trabalho && opensquat -k keywords.txt -o results.json -t json

# Checkout do repositório — invoque opensquat.py diretamente com python3
0 8 * * * cd /caminho/para/opensquat && python3 opensquat.py -k keywords.txt -o results.json -t json

O cd para um diretório de trabalho é importante se você depende de api_key.txt (resolvido a partir do diretório atual) ou deseja que results.json seja escrito em um local específico.

📋 Referência da CLI

🤝 Contribuindo

Aceitamos contribuições! Veja nosso Guia de Contribuição para detalhes.

• 🐛 Reporte bugs via GitHub Issues
• 💡 Solicite funcionalidades abrindo uma issue
• 🔧 Envie PRs para correções de bugs ou melhorias
• 📝 Notas de versão — veja o CHANGELOG para as novidades de cada versão

👤 Autor

Andre Tenreiro — LinkedIn · Chave PGP

📜 Licença

Este projeto está licenciado sob a GNU GPL v3.