OSSEC to Wazuh Migration Guide

Wazuh is a fork of OSSEC that adds a scalable architecture, REST API, vulnerability detection, and modern dashboards while maintaining backward compatibility with OSSEC agents and most rule configurations. This guide covers migrating from OSSEC to Wazuh, including agent migration, rule compatibility, configuration mapping, and data preservation.

Prerequisites

OSSEC 3.x or Atomic OSSEC installation
Ubuntu 20.04+/Debian 11+ or CentOS 8+/Rocky Linux 8+ for the Wazuh manager
Root or sudo access on all servers
A maintenance window (brief service interruption expected)

Verify your OSSEC version:

/var/ossec/bin/ossec-control info
cat /var/ossec/etc/ossec.conf | grep -i version

OSSEC vs Wazuh Feature Comparison

Feature	OSSEC	Wazuh
Log analysis	Yes	Yes (improved)
FIM	Yes	Yes (real-time)
Rootkit detection	Yes	Yes
Active response	Yes	Yes (expanded)
Vulnerability detection	No	Yes
REST API	No	Yes
Web dashboard	Basic (Analogi)	Full (OpenSearch Dashboards)
Agent enrollment	Manual	Automated
Compliance dashboards	No	PCI, HIPAA, GDPR, NIST
Cloud monitoring	No	Yes (AWS, Azure, GCP)
Scalability	Single server	Cluster (multi-node)

Pre-Migration Preparation

Before migrating, back up everything:

# On the OSSEC manager
tar czf /backup/ossec-backup-$(date +%Y%m%d).tar.gz /var/ossec/

# What to preserve:
ls -la /var/ossec/etc/     # Configuration
ls -la /var/ossec/rules/   # Custom rules (local_rules.xml)
ls -la /var/ossec/decoder/ # Custom decoders (local_decoder.xml)
ls -la /var/ossec/logs/    # Historical logs and alerts

# Export a list of all agents
/var/ossec/bin/manage_agents -l > /backup/ossec-agents.txt
cat /backup/ossec-agents.txt

Document your OSSEC configuration:

# Key files to review
cat /var/ossec/etc/ossec.conf
cat /var/ossec/rules/local_rules.xml
cat /var/ossec/etc/shared/agent.conf  # Agent-specific config

Installing the Wazuh Manager

Install Wazuh manager alongside or to replace OSSEC:

# Add Wazuh repository
curl -s https://packages.wazuh.com/key/GPG-KEY-WAZUH | \
  gpg --no-default-keyring --keyring gnupg-ring:/usr/share/keyrings/wazuh.gpg \
  --import && chmod 644 /usr/share/keyrings/wazuh.gpg

echo "deb [signed-by=/usr/share/keyrings/wazuh.gpg] \
  https://packages.wazuh.com/4.x/apt/ stable main" | \
  tee -a /etc/apt/sources.list.d/wazuh.list

sudo apt update

# Stop OSSEC before installing Wazuh (they share port 1514)
sudo /var/ossec/bin/ossec-control stop

# Install Wazuh manager
sudo apt install -y wazuh-manager
sudo systemctl enable --now wazuh-manager

For CentOS/Rocky:

cat > /etc/yum.repos.d/wazuh.repo << 'EOF'
[wazuh]
gpgcheck=1
gpgkey=https://packages.wazuh.com/key/GPG-KEY-WAZUH
enabled=1
name=EL-$releasever - Wazuh
baseurl=https://packages.wazuh.com/4.x/yum/
protect=1
EOF

sudo dnf install -y wazuh-manager
sudo systemctl enable --now wazuh-manager

Migrating OSSEC Configuration

Map OSSEC ossec.conf settings to Wazuh equivalents:

# Most ossec.conf settings are directly compatible
# Copy your existing configuration as a starting point

sudo cp /var/ossec/etc/ossec.conf /var/ossec/etc/ossec.conf.backup

Key configuration differences:

OSSEC setting	Wazuh equivalent	Notes
`<email_notification>`	Same	Identical syntax
`<syscheck>`	Same	Wazuh adds real-time support
`<rootcheck>`	Same
`<active-response>`	Same	Wazuh adds more options
`<global>`	Same
`<alerts>`	Same
`<remote>`	Same

Edit /var/ossec/etc/ossec.conf:

<!-- Wazuh ossec.conf - adapted from OSSEC -->
<ossec_config>
  <global>
    <email_notification>no</email_notification>
    <!-- Wazuh-specific additions -->
    <logall>no</logall>
    <logall_json>no</logall_json>
  </global>

  <syscheck>
    <disabled>no</disabled>
    <frequency>21600</frequency>
    <!-- Real-time monitoring (Wazuh feature) -->
    <directories realtime="yes" check_all="yes">/etc,/usr/bin,/usr/sbin</directories>
    <!-- OSSEC-style directories also work -->
    <directories check_all="yes">/bin,/sbin</directories>
  </syscheck>

  <!-- Vulnerability detection (Wazuh-only) -->
  <vulnerability-detection>
    <enabled>yes</enabled>
    <interval>12h</interval>
  </vulnerability-detection>
</ossec_config>

Migrating Custom Rules and Decoders

OSSEC rules and decoders are fully compatible with Wazuh:

# Copy custom rules
sudo cp /backup/ossec/etc/rules/local_rules.xml /var/ossec/etc/rules/local_rules.xml

# Copy custom decoders
sudo cp /backup/ossec/etc/local_decoder.xml /var/ossec/etc/decoders/local_decoder.xml

# Copy custom active response scripts
sudo cp /backup/ossec/active-response/bin/*.sh /var/ossec/active-response/bin/
sudo chmod +x /var/ossec/active-response/bin/*.sh

# Test rule syntax
sudo /var/ossec/bin/wazuh-analysisd -t

# Reload
sudo systemctl restart wazuh-manager

OSSEC rule IDs 0-99999 work in Wazuh. Wazuh reserves 100000-119999 for local rules - if your OSSEC rules use IDs in that range, renumber them:

# Check for conflicting rule IDs
grep 'id=' /var/ossec/etc/rules/local_rules.xml | \
  grep -oP 'id="\d+"' | sort -t'"' -k2 -n

# Wazuh built-in rules use IDs up to 99999
# Local rules should use 100000+
# Renumber any conflicting OSSEC custom rules
sed -i 's/<rule id="\(9[0-9][0-9][0-9][0-9]\)"/<rule id="\1"/g' \
  /var/ossec/etc/rules/local_rules.xml

Migrating OSSEC Agents

OSSEC agents (versions 3.x) can connect to Wazuh manager:

Option 1: Keep OSSEC agents temporarily (compatible)

OSSEC 3.x agents communicate over the same protocol as Wazuh agents. They'll connect to the Wazuh manager and send events, though Wazuh-specific features won't be available until agents are upgraded.

# Register existing OSSEC agents with Wazuh manager
# For each agent, add it with the same key from OSSEC:

# View OSSEC agent keys (on old OSSEC manager)
/var/ossec/bin/manage_agents -e AGENT_ID

# Import the key into Wazuh
echo "AGENT_KEY" | /var/ossec/bin/manage_agents -i

# Or use the Wazuh API to pre-register agents
curl -k -X POST "https://localhost:55000/agents" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "server01", "ip": "192.168.1.50"}'

Option 2: Upgrade agents to Wazuh agents

# On each agent server, install Wazuh agent
curl -s https://packages.wazuh.com/key/GPG-KEY-WAZUH | \
  sudo gpg --import

echo "deb https://packages.wazuh.com/4.x/apt/ stable main" | \
  sudo tee /etc/apt/sources.list.d/wazuh.list

sudo apt update

# Remove OSSEC agent first
sudo /var/ossec/bin/ossec-control stop
sudo dpkg -r ossec-hids-agent 2>/dev/null || \
  sudo rpm -e ossec-hids-agent 2>/dev/null

# Install Wazuh agent
sudo WAZUH_MANAGER="wazuh-manager.yourdomain.com" \
     WAZUH_AGENT_NAME="$(hostname)" \
     apt install -y wazuh-agent

sudo systemctl enable --now wazuh-agent

Mass agent deployment script:

#!/bin/bash
# deploy-wazuh-agent.sh - run on each agent via SSH
MANAGER="wazuh-manager.yourdomain.com"
AGENT_NAME=$(hostname)

# Get enrollment token from manager
TOKEN=$(ssh root@$MANAGER \
  "/var/ossec/bin/manage_agents -a $AGENT_NAME -e" | \
  grep "Agent key:" | cut -d: -f2)

# Stop OSSEC
/var/ossec/bin/ossec-control stop

# Install Wazuh agent
curl -s https://packages.wazuh.com/4.x/apt/pool/main/w/wazuh-agent/\
  wazuh-agent_4.x.x_amd64.deb -O
dpkg -i wazuh-agent_*.deb

# Register agent
echo "$TOKEN" | /var/ossec/bin/manage_agents -i

# Start Wazuh agent
systemctl enable --now wazuh-agent

Data Preservation

OSSEC historical data (alerts, logs) can be preserved:

# OSSEC alert format vs Wazuh alert format is different
# Historical OSSEC alerts can be kept for reference but won't appear in Wazuh dashboards

# Archive OSSEC logs
sudo tar czf /archive/ossec-alerts-$(date +%Y%m%d).tar.gz \
  /var/ossec/logs/alerts/

# For long-term Wazuh storage, configure Filebeat to ship to Elasticsearch/OpenSearch
# This is covered in the Wazuh installation documentation

Post-Migration Validation

# Check all agents are connecting
sudo /var/ossec/bin/agent_control -l
# All agents should show "Active"

# Verify alerts are being generated
sudo tail -f /var/ossec/logs/alerts/alerts.log

# Test rule evaluation
sudo /var/ossec/bin/wazuh-logtest

# Test that active response still works
cscli decisions add --ip 10.0.0.50 --type ban --duration 1m

# Check FIM is working
echo "test" >> /etc/test-fim-file
# Should see FIM alert within the configured frequency

# Verify vulnerability detection
sudo tail -f /var/ossec/logs/ossec.log | grep -i vulner

# Access web dashboard
# Navigate to https://wazuh-manager:443 (if Wazuh Dashboard is installed)

Troubleshooting

Agents not connecting after migration:

# Check manager is listening
ss -tlnp | grep 1514

# Verify agent authentication
sudo /var/ossec/bin/agent_control -i AGENT_ID
sudo tail -f /var/ossec/logs/ossec.log | grep "Agent authenticated"

# Re-register the agent if key mismatch
# On manager: delete and re-add the agent
# On agent: /var/ossec/bin/manage_agents -r 001 && /var/ossec/bin/manage_agents -i

Custom rules not triggering in Wazuh:

# Test rules with wazuh-logtest
sudo /var/ossec/bin/wazuh-logtest

# Check for rule ID conflicts
grep 'id=' /var/ossec/etc/rules/local_rules.xml | sort

# Validate rule XML syntax
xmllint --noout /var/ossec/etc/rules/local_rules.xml

Active response scripts not running:

# Verify script permissions and ownership
ls -la /var/ossec/active-response/bin/

# Check active response log
sudo tail -f /var/ossec/logs/active-responses.log

# Test active response manually
sudo /var/ossec/active-response/bin/your-script.sh

Conclusion

Migrating from OSSEC to Wazuh is typically straightforward because Wazuh maintains backward compatibility with OSSEC agents, rules, and most configuration. The migration unlocks vulnerability detection, a modern REST API, compliance dashboards, and scalable multi-server architecture that OSSEC never offered. Prioritize migrating agents from OSSEC to native Wazuh agents to get access to the full feature set, and use the migration window to audit and update your custom rules to the recommended 100000+ ID range.

OSSEC to Wazuh Migration Guide

On this page

On this page

OSSEC to Wazuh Migration Guide

Prerequisites

OSSEC vs Wazuh Feature Comparison

Pre-Migration Preparation

Installing the Wazuh Manager

Migrating OSSEC Configuration

Migrating Custom Rules and Decoders

Migrating OSSEC Agents

Data Preservation

Post-Migration Validation

Troubleshooting

Conclusion

Latest Video

Get $20 Free Credit