Integration with external APIs

The Integrator daemon allows Wazuh to connect to external APIs and alerting tools such as Slack, PagerDuty, VirusTotal, Shuffle, and Maltiverse.

Configuration

The integrations are configured on the Wazuh manager ossec.conf file. You can find this file in the Wazuh installation folder /var/ossec/etc/. To configure an integration, add the following configuration within the <ossec_config> section:

<integration>
  <name> </name>
  <hook_url> </hook_url> <!-- Required for Slack, Shuffle, and Maltiverse -->
  <api_key> </api_key> <!-- Required for PagerDuty, VirusTotal, and Maltiverse -->
  <alert_format>json</alert_format> <!-- Required for Slack, PagerDuty, VirusTotal, Shuffle, and Maltiverse -->

  <!-- Optional filters -->
  <rule_id> </rule_id>
  <level> </level>
  <group> </group>
  <event_location> </event_location>
  <options> </options>
</integration>

After enabling the daemon and configuring the integrations, restart the Wazuh manager to apply the changes:

# systemctl restart wazuh-manager

Optional filters

The Integrator daemon uses the optional filters fields to determine which alerts should be sent to the external platforms. Only the alerts that meet the filter conditions are sent. If no filters are specified, all alerts are sent.

The following considerations must be taken into account when the filters are set:

  • It is possible to specify multiple group names using the <group> field with a comma-separated list. If the alert's group matches any of the groups in the list, the alert is sent. Otherwise, it is ignored.

  • It is possible to specify multiple rule IDs using the <rule_id> field with a comma-separated list. If the alert's rule ID matches any of the IDs in the list, the alert is sent. Otherwise, it is ignored.

  • It is possible to specify the previously described fields together. If both the alert's rule ID and group match any of the IDs and groups in the lists, the alert is sent. Otherwise, it is ignored.

Note

It is recommended to carefully check the groups and rule identifiers mentioned above, as defining them incorrectly will result in expected alerts not being sent to the integration.

The full configuration reference for the Integrator daemon can be found here.

Slack

This integration uses Slack Incoming Webhooks and allows posting Wazuh alerts into a Slack channel.

To set up this integration, follow these steps.

  1. Enable Incoming Webhooks and create one for your Slack channel. Follow the Slack guide on Incoming Webhooks for this.

  2. Edit /var/ossec/etc/ossec.conf in the Wazuh server and include a configuration block such as the following. Replace WEBHOOK_URL with your Incoming Webhook URL.

    <integration>
      <name>slack</name>
      <hook_url>WEBHOOK_URL</hook_url> <!-- Replace with your Slack hook URL -->
      <alert_format>json</alert_format>
    </integration>
    

    Note

    You can set a JSON object with customization fields using the options tag. Visit the Slack API reference for information about available customization fields.

  3. Restart the Wazuh manager to apply the changes.

    # systemctl restart wazuh-manager
    

Once the configuration is complete, alerts start showing in the selected channel.

Alerts in Slack channel

PagerDuty

PagerDuty is a SaaS incident response platform suitable for IT departments. The Pagerduty integration uses the Pagerduty API to forward Wazuh alerts to its Incidents Dashboard.

To set up this integration, do the following.

  1. Get your own Events API v2 integration key by creating a Pagerduty new service.

  2. Edit /var/ossec/etc/ossec.conf in the Wazuh server and include a configuration block such as the following. Replace API_KEY with your Pagerduty integration key. The rule level filter is optional and you can remove it or set another level value for the integration.

    <integration>
      <name>pagerduty</name>
      <api_key>API_KEY</api_key> <!-- Replace with your PagerDuty API key -->
      <level>10</level>
      <alert_format>json</alert_format> <!-- New mandatory parameter since v4.7.0 -->
    </integration>
    

    Note

    You can set a JSON object with customization fields using the options tag. Visit the PagerDuty API reference for information about available customization fields.

  3. Restart the Wazuh manager to apply the changes.

    # systemctl restart wazuh-manager
    

Once the configuration is complete, alerts start showing on the Pagerduty dashboard.

Wazuh alert in the PagerDuty Incidents dashboard

VirusTotal

This integration allows the inspection of malicious files using the VirusTotal database. Find more information about this on the VirusTotal integration page.

To set up this integration, follow these steps.

  1. Get your API key from the Virustotal API key page.

  2. Edit /var/ossec/etc/ossec.conf in the Wazuh server and include a configuration block such as the following. Replace API_KEY with your Virustotal API key.

    <integration>
      <name>virustotal</name>
      <api_key>API_KEY</api_key> <!-- Replace with your VirusTotal API key -->
      <group>syscheck</group>
      <alert_format>json</alert_format>
    </integration>
    
  3. Restart the Wazuh manager to apply the changes.

    # systemctl restart wazuh-manager
    

Shuffle

Shuffle is an Open Source interpretation of SOAR. It transfers data throughout the enterprise with plug-and-play Apps. The Shuffle integration allows forwarding Wazuh alerts into a Shuffle Workflow using a webhook.

To set up this integration, do the following.

  1. Go to Shuffle and make a Workflow using the Email app. Select version 1.0.1 for it.

  2. Set Recipients and Subject in the email configuration. Put $exec in the Body to include the alert information.

  3. Add a webhook to the Workflow.

  4. Start the webhook and copy the webhook URL.

  5. Edit /var/ossec/etc/ossec.conf in the Wazuh server and include a configuration block such as the following. Replace https://shuffler.io/api/v1/hooks/webhook_WEBHOOK_ID with the webhook URL. The rule level filter is optional. You can remove it or set another level value for the integration.

    <integration>
       <name>shuffle</name>
       <hook_url>https://shuffler.io/api/v1/hooks/webhook_WEBHOOK_ID</hook_url> <!-- Replace with your Shuffle hook URL -->
       <level>3</level>
       <alert_format>json</alert_format>
    </integration>
    

    Note

    You can set a JSON object with customization fields using the options tag. Visit the Shuffle API reference for information about available customization fields.

  6. Restart the Wazuh manager to apply the changes.

    # systemctl restart wazuh-manager
    

Once the configuration is complete, alerts start showing in the email inbox.

Shuffle email alert

Maltiverse

Maltiverse is an open and collaborative platform for indexing and searching Indicators of Compromise (IoCs). It works as a broker for Threat intelligence sources. Maltiverse aggregates information from more than a hundred different public, private and community sources.

This integration identifies IoCs in Wazuh alerts via the Maltiverse API. It generates new alerts enriched with Maltiverse data. The Maltiverse data fields are based on the threat taxonomy of the ECS standard (Elastic Common Schema).

To set up this integration, do the following.

  1. Get your API key from the Maltiverse page.

  2. Edit /var/ossec/etc/ossec.conf in the Wazuh server and include a configuration block such as the following. Replace API_KEY with your Maltiverse API key. The rule level filter is optional. You can remove it or set another level value for the integration.

    <integration>
       <name>maltiverse</name>
       <hook_url>https://api.maltiverse.com</hook_url>
       <level>3</level>
       <api_key>API_KEY</api_key> <!-- Replace with your Maltiverse API key -->
       <alert_format>json</alert_format>
    </integration>
    
  3. Restart the Wazuh manager to apply the changes.

    # systemctl restart wazuh-manager
    

Once the configuration is complete, enriched alerts start showing in the Wazuh Dashboard if applicable.

Maltiverse alert

Custom integration

The integrator tool is able to connect Wazuh with other external software. Read the How to integrate external software using Integrator document for more information.

Below, you can find an example of a configuration block in the ossec.conf file for custom integration.

<!--Custom external Integration -->
<integration>
  <name>custom-integration</name>
  <hook_url>WEBHOOK</hook_url>
  <level>10</level>
  <group>multiple_drops,authentication_failures</group>
  <api_key>APIKEY</api_key> <!-- Replace with your external service API key -->
  <alert_format>json</alert_format>
  <options>{"data": "Custom data"}</options> <!-- Replace with your custom JSON object -->
</integration>