Learn Wazuh - External Integration: TheHive, Shuffle, and SOAR

#Introduction

In episode 17 we built custom rules and advanced detection, so the Wazuh in your hands is getting sharper at recognizing anomalies. But great detection means nothing if it isn't responded to quickly and neatly. In episode 18 we close that loop by connecting Wazuh to the SOAR layer.

We'll open three paths at once. First, TheHive for case management so every alert turns into a case that can be tracked to completion. Second, Shuffle for automation orchestration like enrichment and notification. Third, exporting alerts to other systems such as external syslog, Kafka, or another SIEM so Wazuh data can contribute where infrastructure already runs.

Not every lab needs all three on day one. Start from your needs: only need daily email alerts, or are you building a lab SOC with a detection-to-resolution flow. We'll discuss patterns used in the field, so you can extend them yourself.

#SOAR in One Sentence

SOAR stands for Security Orchestration, Automation, and Response. Its job is to unify detection from various sources, then turn it into coordinated action. Wazuh is an excellent detection engine, but it isn't a case management platform. That's where TheHive and Shuffle come in.

A sensible division of work is this:

• Wazuh is responsible for detection and the initial trigger.
• TheHive becomes the home of every case and its investigation timeline.
• Shuffle orchestrates the automation flow between tools, including enrichment and notification.

With this separation, you don't have to force Wazuh to be everything. Each tool keeps doing what it does best, and integration connects them all.

#Setting Up TheHive for Wazuh

TheHive has a REST API that Wazuh can call. The most common approach is custom integration: we write a small script that calls the TheHive API, then register it as an integration on the Wazuh manager. TheHive needs an organization, user, and API key used by Wazuh.

Once the API key is available, create the script in Wazuh's integrations directory, then make sure the Python dependencies it needs are installed:

ls -la /var/ossec/integrations/custom-w2thive.py
/var/ossec/framework/python/bin/python3 -c "import thehive4py"

File permissions also matter. Wazuh runs scripts with a specific user, so make sure the script is readable and executable by that user. Permission errors are the most common cause of integrations silently not working.

#The Alert-to-Case Flow

Once the script is ready, register the integration in ossec.conf. This block tells Wazuh where to forward alerts and at what level:

<integration>
  <name>custom-w2thive</name>
  <group>syscheck,authentication_failures</group>
  <alert_format>json</alert_format>
  <level>7</level>
</integration>

With the configuration above, Wazuh forwards alerts of level 7 and above from the selected groups. TheHive holds them as alerts, and analysts can promote them into cases when warranted.

The full flow becomes: an agent sends an event, the manager evaluates the rule, the alert triggers the integration, the script calls the TheHive API, and a new case is formed. The whole process runs without a human copying logs manually, and that's exactly where its main value lies.

#Orchestration with Shuffle

Shuffle is an open source SOAR that orchestrates automation flows between tools via visual workflows. Wazuh fires at a Shuffle webhook, then the workflow runs the next steps like hash enrichment or case creation in TheHive.

The Wazuh-side configuration is quite short:

<integration>
  <name>shuffle</name>
  <hook_url>http://IP_SHUFFLE:3001/api/v1/hooks/ID_HOOK</hook_url>
  <level>3</level>
  <alert_format>json</alert_format>
</integration>

Shuffle sends all alerts of level 3 and above to the workflow attached to that hook. Inside the workflow, you can add nodes to check IP or hash reputation, create cases in TheHive, up to sending messages to the team.

#Webhook and Email Notifications

Not every notification needs full SOAR. For simple needs, Wazuh has two paths that work out of the box.

Email alerts are configured in the email_alerts section of ossec.conf:

<global>
  <email_notification>yes</email_notification>
  <smtp_server>smtp.contoh.com</smtp_server>
  <email_from>wazuh@soc.contoh.com</email_from>
  <email_to>analis@soc.contoh.com</email_to>
</global>
<alerts>
  <email_alert_level>10</email_alert_level>
</alerts>

Webhooks use a custom-type integration with the destination hook URL:

<integration>
  <name>custom-webhook</name>
  <hook_url>https://hook.contoh.com/terima-alert</hook_url>
  <alert_format>json</alert_format>
  <level>8</level>
</integration>

Choose based on need. Email suits summaries, webhooks suit internal applications that receive JSON directly.

#Exporting Alerts to Other Systems

Sometimes Wazuh alerts must also flow into existing infrastructure. Wazuh provides a syslog output for that need:

<syslog_output>
  <server>10.10.1.50</server>
  <port>514</port>
  <format>json</format>
</syslog_output>

For Kafka or another SIEM, a common pattern is streaming alerts through filebeat or logstash. Wazuh alerts are stored in /var/ossec/logs/alerts/alerts.json in JSON form, and tools like filebeat can pump that file to Kafka or a target Elasticsearch.

#Syncing with Incident Response Playbooks

Exports and notifications become far more useful when connected to a playbook. First define how high-level alerts are handled by humans and automation: who gets the first notification, which isolation steps may run automatically, and when a case is considered closed.

In TheHive, the case status can be the source of truth. When a case is closed, record the summary and the actions taken. Patterns like this make post-mortems easier because the whole timeline is already recorded since the first alert appeared.

#Conclusion

In episode 18 you connected Wazuh with the ecosystem around it:

• SOAR separates the roles of detection, case management, and orchestration.
• TheHive holds alerts as trackable cases.
• Shuffle orchestrates automation flows between tools via workflows.
• Email and webhooks serve simple notifications.
• Syslog output and filebeat export alerts to other systems.
• Playbooks ensure automation and humans work in harmony.

Key takeaways:

• Detection without a response pipeline only adds noise.
• Start from the simplest need, then add complexity gradually.
• API keys and secrets must be managed with strict permissions.
• Level filters determine the volume that enters automation.
• Always connect automation to playbooks and timeline recording.

In episode 19 we talk about something rarely noticed until everything starts slowing down: performance tuning and capacity planning so Wazuh stays healthy as load grows. See you there!