AlienVault OTX Integration with Wazuh (Complete Guide)

AlienVault OTX Integration with Wazuh (Complete Guide)

10/22/2025

Portuguese version

Overview

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. The integration makes use of Python scripts and custom rules in Wazuh to query the OTX API whenever specific events are detected.

The integration is especially useful for security teams who want to automate event correlation and Threat Intelligence, improving visibility and incident response.

Prerequisites

Before starting, check if your environment has:

  • Wazuh Manager installed (version 4.x or higher)
  • Python and the OTXv2 module installed in the Wazuh environment
  • Root access or administrative permissions
  • A valid OTX API Key, obtained free of charge from the AlienVault portal (https://otx.alienvault.com)

To install the required module, run:

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

Required Files

To simplify the process, the main files are now available for download directly from the GitHub repository:

In addition to these, you need to download the get_malicious.py file directly from the official OTX SDK repository:

After downloading the files, move them all to the directory:

/var/ossec/integrations/

Permissions and Ownership

To ensure that Wazuh can run scripts correctly, set the appropriate permissions:

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

API Key Configuration

Open the custom-alienvault.py file and replace the line:

API_KEY = 'APIKEY'

For your valid OTX API key. Example:

API_KEY = 'yor_api_key_here'

This key will be used to authenticate queries to the AlienVault API.

Configuring Wazuh (ossec.conf)

Open the Wazuh configuration file:

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

And add the following integration inside the <ossec_config> tag:

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

This configuration indicates that Wazuh should trigger the custom-alienvault.py script whenever an alert from the sysmon_event_22 group is generated (such as DNS query events).

Adding Rules to Wazuh

Copy the rules file alienOTX.xml to the directory:

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

The basic contents of the file are:

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

These rules define Wazuh's behavior when identifying a domain present in the OTX database.

Restarting Wazuh

After all changes, restart the service to apply the settings:

sudo systemctl restart wazuh-manager

Testing the Integration

To test, create a sample alert file:

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

Now run the script manually:

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

If the domain is listed on OTX, you will see the message:

Identified as potentially malicious

Otherwise:

Unknown or not identified as malicious

Checking the Logs

Integration logs can be viewedified in the file:

/var/ossec/logs/integrations.log

Look for entries containing alienvault or OTX to confirm that events are being processed correctly.

Tips and Troubleshooting

  • If the Invalid API Key error appears, generate a new key on the OTX portal.
  • Check if the OTXv2 module is installed within the Wazuh Python environment (/var/ossec/framework/python/bin/python3).
  • Use systemctl status wazuh-manager to check if the service is running.

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 current 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.