Integração do AlienVault OTX com o Wazuh (Guia Completo)

Integração do AlienVault OTX com o Wazuh (Guia Completo)

22/10/2025

Versão em Português

Visão Geral

Este guia detalhado explica passo a passo como integrar o AlienVault OTX (Open Threat Exchange) com o Wazuh, permitindo que seu ambiente de monitoramento detecte automaticamente domínios e endereços IP maliciosos conhecidos. A integração faz uso de scripts Python e regras customizadas no Wazuh para consultar a API do OTX sempre que eventos específicos forem detectados.

A integração é especialmente útil para equipes de segurança que desejam automatizar a correlação de eventos e inteligência de ameaças (Threat Intelligence), melhorando a visibilidade e a resposta a incidentes.

Pré-requisitos

Antes de iniciar, verifique se o seu ambiente possui:

  • Wazuh Manager instalado (versão 4.x ou superior)
  • Python e o módulo OTXv2 instalados no ambiente do Wazuh
  • Acesso root ou permissões administrativas
  • Uma API Key válida do OTX, obtida gratuitamente no portal do AlienVault (https://otx.alienvault.com)

Para instalar o módulo necessário, execute:

sudo /var/ossec/framework/python/bin/python3 -m pip install OTXv2

Arquivos Necessários

Para simplificar o processo, os principais arquivos já estão disponíveis para download direto do repositório GitHub:

Além desses, é necessário baixar o arquivo get_malicious.py diretamente do repositório oficial do OTX SDK:

Após baixar os arquivos, mova todos eles para o diretório:

/var/ossec/integrations/

Permissões e Propriedade

Para garantir que o Wazuh consiga executar os scripts corretamente, defina as permissões adequadas:

chown root:wazuh custom-alienvault custom-alienvault.py get_malicious.py
chmod 750 custom-alienvault custom-alienvault.py get_malicious.py

Configuração da API Key

Abra o arquivo custom-alienvault.py e substitua a linha:

API_KEY = 'APIKEY'

Pela sua chave de API válida do OTX. Exemplo:

API_KEY = 'yor_api_key_aqui'

Essa chave será usada para autenticar as consultas à API do AlienVault.

Configurando o Wazuh (ossec.conf)

Abra o arquivo de configuração do Wazuh:

sudo nano /var/ossec/etc/ossec.conf

E adicione a seguinte integração dentro da tag <ossec_config>:

<integration>
    <name>custom-alienvault</name>
    <group>sysmon_event_22</group>
    <alert_format>json</alert_format>
</integration>

Essa configuração indica que o Wazuh deve acionar o script custom-alienvault.py sempre que for gerado um alerta do grupo sysmon_event_22 (como eventos de consultas DNS).

Adicionando Regras no Wazuh

Copie o arquivo de regras alienOTX.xml para o diretório:

sudo cp alienOTX.xml /var/ossec/etc/rules/

O conteúdo básico do arquivo é:

<group name="alienvault_alert,">
  <rule id="100010" level="12">
    <field name="integration">alienvault</field>
    <description>AlienVault - OTX DOMAIN Found</description>
    <options>no_full_log</options>
  </rule>
</group>

Essas regras definem o comportamento do Wazuh ao identificar um domínio presente na base de dados do OTX.

Reiniciando o Wazuh

Após todas as alterações, reinicie o serviço para aplicar as configurações:

sudo systemctl restart wazuh-manager

Testando a Integração

Para testar, crie um arquivo de alerta de exemplo:

cat >/tmp/test_alert.json <<'JSON'
{
  "agent": { "id": "001", "name": "test-agent", "ip": "127.0.0.1" },
  "data": {
    "win": {
      "eventdata": {
        "queryName": "fact-pendientes.com"
      }
    }
  }
}
JSON

Agora execute o script manualmente:

sudo /var/ossec/integrations/custom-alienvault /tmp/test_alert.json

Se o domínio estiver listado no OTX, você verá a mensagem:

Identified as potentially malicious

Caso contrário:

Unknown or not identified as malicious

Verificando os Logs

Os logs da integração podem ser verificados no arquivo:

/var/ossec/logs/integrations.log

Procure por entradas contendo alienvault ou OTX para confirmar que os eventos estão sendo processados corretamente.

Dicas e Soluções de Problemas

  • Se aparecer o erro Invalid API Key, gere uma nova chave no portal do OTX.
  • Verifique se o módulo OTXv2 está instalado dentro do ambiente Python do Wazuh (/var/ossec/framework/python/bin/python3).
  • Use systemctl status wazuh-manager para verificar se o serviço está em execução.

English Version

Overview

This complete guide explains step-by-step how to integrate AlienVault OTX (Open Threat Exchange) with Wazuh, allowing your monitoring environment to automatically detect known malicious domains and IP addresses. The integration leverages Python scripts and custom Wazuh rules to query the OTX API whenever specific events are triggered.

This setup is particularly useful for security teams that want to automate threat intelligence correlation and event detection, improving both visibility and response time.

Requirements

Before starting, make sure you have:

  • Wazuh Manager (version 4.x or higher)
  • Python and OTXv2 module installed
  • Root or administrative privileges
  • A valid OTX API Key, available for free from https://otx.alienvault.com

To install the required module:

sudo /var/ossec/framework/python/bin/python3 -m pip install OTXv2

Required Files

Download the main integration files from the GitHub repository:

Additionally, download the get_malicious.py script from the official OTX SDK:

Move all these files to:

/var/ossec/integrations/

Setting Permissions

chown root:wazuh custom-alienvault custom-alienvault.py get_malicious.py
chmod 750 custom-alienvault custom-alienvault.py get_malicious.py

Configuring the API Key

Edit custom-alienvault.py and replace:

API_KEY = 'APIKEY'

with your actual API key, for example:

API_KEY = 'yor_api_key_here'

This key is required for authentication with the OTX API.

Editing the Wazuh Configuration

In /var/ossec/etc/ossec.conf, add:

<integration>
    <name>custom-alienvault</name>
    <group>sysmon_event_22</group>
    <alert_format>json</alert_format>
</integration>

Adding Rules

Copy the alienOTX.xml file to /var/ossec/etc/rules/.

Restarting Wazuh

sudo systemctl restart wazuh-manager

Testing the Integration

cat >/tmp/test_alert.json <<'JSON'
{
  "agent": { "id": "001", "name": "test-agent", "ip": "127.0.0.1" },
  "data": { "win": { "eventdata": { "queryName": "fact-pendientes.com" } } }
}
JSON

sudo /var/ossec/integrations/custom-alienvault /tmp/test_alert.json

If malicious → Identified as potentially malicious If safe → Unknown or not identified as malicious

Checking Logs

Check integration logs:

cat /var/ossec/logs/integrations.log | grep alienvault

Final Notes

If you receive an Invalid API Key error, verify your key or regenerate a new one at the OTX portal. Always ensure your Python environment inside Wazuh has the OTXv2 library installed.