IOC Collector

Um coletor de IOCs caseiro para homelab, com foco em origens open source, saída padronizada e integração com ferramentas de bloqueio self-hosted.

Visão geral

Este projeto coleta indicadores de comprometimento de múltiplas fontes abertas, padroniza os dados e os envia para mecanismos de bloqueio self-hosted. O projeto ainda está em desenvolvimento e a maior parte da arquitetura é piloto: apenas o main.py executa um fluxo funcional hoje, e ele ainda está fora do padrão completo de arquitetura limpa.

O que está implementado hoje

• app/domain/ports.py
  • DomainProviderPort: interface para provedores de domínios/IOCs
  • BlocklistPort: interface para destinos de bloqueio
• app/application/hauss_api.py
  • Implementa DomainProviderPort
  • Busca domínios de urlhaus-api.abuse.ch
  • Normaliza a saída removendo comentários e linhas vazias
• app/application/pihole_api.py
  • Implementa BlocklistPort
  • Autentica no Pi-hole e adiciona domínios à blocklist via API
• main.py
  • Composição de dependências
  • Orquestra a coleta de domínios e a submissão para o Pi-hole
  • Observação: este é o único fluxo funcional atualmente e ainda não segue totalmente a arquitetura desejada
• app/application/virustotal_api.py
  • Estrutura de placeholder para futura integração com VirusTotal
• app/application/abuseipdb_api.py
  • Classe existente para AbuseIPDB, ainda ampla e passível de adaptação aos ports

Arquitetura e boas práticas

DDD

O projeto já apresenta uma separação inicial de camadas:

• app/domain/ — contratos e possíveis objetos de domínio
• app/application/ — adaptadores e serviços de aplicação
• main.py — composição e orquestração

Esse modelo facilita manter o domínio estável enquanto novas origens e destinos são acrescentados.

SOLID

• Single Responsibility Principle: cada classe tem uma responsabilidade clara (HaussApi lê domínios, PiHoleApi escreve na blocklist).
• Open/Closed Principle: novas integrações podem ser adicionadas implementando DomainProviderPort ou BlocklistPort, sem modificar o pipeline principal.
• Liskov Substitution Principle: implementações substituem os contratos de porta sem alterar o fluxo de uso.
• Interface Segregation Principle: separação clara entre provedores de IOCs e destinos de bloqueio.
• Dependency Inversion Principle: o fluxo do projeto depende de abstrações de domínio, não de detalhes concretos.

Object Calisthenics

O código atual segue preocupações de design leve:

• classes pequenas e focadas
• métodos curtos e diretos
• baixo acoplamento entre componentes
• cada adaptação (HaussApi, PiHoleApi) encapsula seu comportamento específico

Como usar

1. Crie um ambiente virtual Python:

python -m venv .venv
.\.venv\Scripts\activate

2. Instale as dependências:

pip install -r requirements.txt

3. Copie .env.example para .env e preencha as variáveis necessárias:

• API_KEY_HAUSS
• API_KEY_PIHOLE
• URL_PIHOLE_AUTH
• URL_PIHOLE_BLOCK_DOMAIN

4. Execute o coletor:

python main.py

Variáveis de ambiente

O projeto já inclui suporte para várias integrações, mesmo que algumas ainda não estejam totalmente implementadas:

• API_KEY_ABUSEIPDB
• URL_ABUSEIPDB_BLACKLIST
• API_KEY_VIRUSTOTAL
• API_KEY_OPENVAULT
• API_KEY_PIHOLE
• URL_PIHOLE_BLOCK_DOMAIN
• URL_PIHOLE_AUTH
• API_KEY_HAUSS

Estrutura de projeto

• main.py — entrypoint de composição e execução
• app/application/ — adaptadores de APIs e integrações
• app/domain/ — contratos de domínio e objetos de modelo
• tests/ — testes unitários existentes

Expansão recomendada para homelab

Atualmente você já tem uma integração funcionando com Pi-hole. Para aumentar o valor do coletor de IOCs e expandir seu homelab, considere adicionar saídas ou fontes para:

1. AdGuard Home

   • DNS resolver/self-hosted com suporte a listas de bloqueio personalizadas.
   • Pode receber domínios do mesmo coletor e aplicar filtragem DNS.

2. OPNsense / pfSense + pfBlockerNG

   • Permite importar blocklists e aplicar regras de DNS e IP.
   • Ideal para centralizar IOCs em nível de rede.

3. Suricata

   • IDS/IPS capaz de consumir regras e alertar bloqueios ativos.
   • Use listas de URLs/domínios extraídas para gerar regras ou sinalizar tráfego malicioso.

4. Zeek / Bro

   • Análise de tráfego de rede profunda.
   • Pode alimentar deteções com IOCs coletados e ajudar a correlacionar eventos.

5. Wazuh / Elastic Stack

   • Plataforma de monitoramento/alerta que aceita listas e regras customizadas.
   • Bom para centralizar visibilidade e gerar alertas sobre conexões a domínios bloqueados.

6. OpenWrt / dnsmasq

   • Routers self-hosted podem consumir blocklists locais.
   • Use o coletor para gerar arquivos de bloqueio que o OpenWrt distribui internamente.

Próximos passos

• Transformar abuseipdb_api e virustotal_api em implementações reais de DomainProviderPort
• Criar adaptadores BlocklistPort para AdGuard Home e OPNsense/pfSense
• Adicionar testes para HaussApi e PiHoleApi
• Introduzir um serviço de composição para permitir múltiplos provedores e múltiplos destinos em paralelo

Observação

Este projeto já está bem posicionado para evoluir em um padrão de arquitetura limpa. Com o uso contínuo de ports e adapters, você poderá expandir o coletor para suportar novos formatos e destinos sem comprometer o domínio.