05. Adding and Managing Wazuh Agents: A Production Guide

Once your Wazuh server is up and running, the next critical step is deploying agents to your endpoints. This is where Wazuh transforms from a theoretical security tool into a practical monitoring solution.

After managing agent deployments across hundreds of systems, I can tell you that agent management is where most organizations struggle. The installation is easy, but proper configuration, troubleshooting, and scaling require real-world experience.

In this comprehensive guide, I'll share everything I've learned about deploying and managing Wazuh agents in production environments (including the mistakes I've made so you don't have to).

What you'll learn:

• Agent deployment strategies that actually work

• Platform-specific installation techniques

• Common configuration mistakes and how to avoid them

• Troubleshooting techniques for when things go wrong

• Scaling strategies for large environments

Let's turn your Wazuh server into a powerful security monitoring platform.

---

🔄 Understanding the Agent Enrollment Process

Here's the thing: Before diving into commands, let me explain how agent enrollment actually works. I've seen too many people get confused by this process.

Critical Success Factors (learn from my mistakes):

1. Network connectivity - Agents must reach the manager on port 1514 (this is the most common issue)

2. Proper authentication - SSL/TLS for production environments (don't skip this)

3. Correct configuration - Wrong settings = failed enrollment (and wasted time)

4. Resource allocation - Agents need minimal but consistent resources

Common Enrollment Failures I've Seen (and how to avoid them):

• Network issues: 60% of failures are network-related (always test connectivity first)

• Configuration errors: 25% are due to wrong settings (double-check your configs)

• Resource constraints: 10% are due to insufficient resources (especially on older systems)

• Authentication problems: 5% are due to SSL/certificate issues (this is usually a pain to troubleshoot)

---

🪟 Windows Agent Deployment - The Enterprise Standard

Here's why Windows agents matter: Most enterprise environments are Windows-heavy. Getting Windows agent deployment right is crucial for success, and honestly, it's where I've seen the most issues.

Method 1: MSI Installation (Recommended for Enterprise)

Step 1: Download and Prepare

# Download the latest agent (run as Administrator)
Invoke-WebRequest -Uri "https://packages.wazuh.com/4.x/windows/wazuh-agent-4.12.0-1.msi" -OutFile "wazuh-agent.msi"

# Verify the download
Get-FileHash wazuh-agent.msi -Algorithm SHA256

Step 2: Silent Installation

# Install with silent mode and pre-configured settings
msiexec /i wazuh-agent.msi /quiet WAZUH_MANAGER="YOUR_WAZUH_MANAGER_IP" WAZUH_REGISTRATION_SERVER="YOUR_WAZUH_MANAGER_IP" WAZUH_REGISTRATION_PASSWORD="YOUR_REGISTRATION_PASSWORD"

Step 3: Verify Installation

# Check if service is running
Get-Service WazuhSvc

# Check agent status
& "C:\Program Files (x86)\ossec-agent\agent_control.exe" -i

# View agent logs
Get-Content "C:\Program Files (x86)\ossec-agent\ossec.log" -Tail 20

Method 2: Group Policy Deployment (Enterprise Scale)

For organizations with 100+ Windows machines:

# Create a deployment script
$script = @"
# Wazuh Agent Deployment Script
$agentUrl = "https://packages.wazuh.com/4.x/windows/wazuh-agent-4.12.0-1.msi"
$agentFile = "$env:TEMP\wazuh-agent.msi"
$managerIP = "YOUR_WAZUH_MANAGER_IP"

# Download and install
Invoke-WebRequest -Uri $agentUrl -OutFile $agentFile
msiexec /i $agentFile /quiet WAZUH_MANAGER=$managerIP WAZUH_REGISTRATION_SERVER=$managerIP
"@

# Save and execute via GPO
$script | Out-File -FilePath "C:\Scripts\Deploy-WazuhAgent.ps1" -Encoding UTF8

Windows Agent Configuration Best Practices

File Integrity Monitoring:

<!-- Add to ossec.conf -->
<syscheck>
  <directories check_all="yes" realtime="yes">C:\Windows\System32</directories>
  <directories check_all="yes" realtime="yes">C:\Program Files</directories>
  <directories check_all="yes" realtime="yes">C:\Program Files (x86)</directories>
  <ignore>C:\Windows\System32\drivers\etc\hosts</ignore>
  <ignore>C:\Windows\System32\drivers\etc\lmhosts</ignore>
</syscheck>

Log Collection:

<!-- Windows Event Logs -->
<localfile>
  <log_format>eventchannel</log_format>
  <location>Microsoft-Windows-Sysmon/Operational</location>
</localfile>

<localfile>
  <log_format>eventchannel</log_format>
  <location>Security</location>
</localfile>

Common Windows Agent Issues (and how to fix them):

1. UAC prompts - Run installation as Administrator (this is the most common issue)

2. Antivirus interference - Add exclusions for Wazuh directories (Windows Defender is particularly aggressive)

3. Windows Defender - May block agent communication (you'll need to add exclusions)

4. Firewall rules - Ensure outbound connections are allowed (this is often overlooked)

---

🐧 Linux Agent Deployment - The DevOps Favorite

Here's why Linux agents are easier: Linux environments typically have better automation and configuration management tools, and honestly, the installation process is much more straightforward.

Ubuntu/Debian Installation

Step 1: Repository Setup

# Add Wazuh repository
curl -s https://packages.wazuh.com/key/GPG-KEY-WAZUH | sudo apt-key add -
echo "deb https://packages.wazuh.com/4.x/apt/ stable main" | sudo tee /etc/apt/sources.list.d/wazuh.list

# Update package list
sudo apt update

Step 2: Agent Installation

# Install Wazuh agent
sudo apt install wazuh-agent -y

# Configure manager IP
sudo sed -i 's/<address>.*<\/address>/<address>YOUR_WAZUH_MANAGER_IP<\/address>/' /var/ossec/etc/ossec.conf

# Start and enable agent
sudo systemctl enable wazuh-agent
sudo systemctl start wazuh-agent

Step 3: Verification

# Check agent status
sudo systemctl status wazuh-agent

# Check agent configuration
sudo /var/ossec/bin/agent_control -l

# View agent logs
sudo tail -f /var/ossec/logs/ossec.log

RHEL/CentOS Installation

# Add Wazuh repository
sudo rpm --import https://packages.wazuh.com/key/GPG-KEY-WAZUH
sudo 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

# Install agent
sudo yum install wazuh-agent -y

# Configure and start
sudo sed -i 's/<address>.*<\/address>/<address>YOUR_WAZUH_MANAGER_IP<\/address>/' /var/ossec/etc/ossec.conf
sudo systemctl enable wazuh-agent
sudo systemctl start wazuh-agent

Linux Agent Configuration Examples

File Integrity Monitoring:

<syscheck>
  <directories check_all="yes" realtime="yes">/etc</directories>
  <directories check_all="yes" realtime="yes">/usr/bin</directories>
  <directories check_all="yes" realtime="yes">/usr/sbin</directories>
  <directories check_all="yes" realtime="yes">/bin</directories>
  <directories check_all="yes" realtime="yes">/sbin</directories>
  <ignore>/etc/ssl/private</ignore>
  <ignore>/etc/ssh/ssh_host_*</ignore>
</syscheck>

Log Collection:

<!-- System logs -->
<localfile>
  <log_format>syslog</log_format>
  <location>/var/log/auth.log</location>
</localfile>

<localfile>
  <log_format>syslog</log_format>
  <location>/var/log/syslog</location>
</localfile>

<!-- Application logs -->
<localfile>
  <log_format>syslog</log_format>
  <location>/var/log/nginx/access.log</location>
</localfile>

---

🍏 macOS Agent Deployment - The Apple Ecosystem

Here's why macOS agents are tricky: Apple's security model and system integrity protection make agent deployment more complex, and honestly, it's where I've seen the most unexpected issues.

Package Installation

Step 1: Download and Install

# Download agent package
curl -O https://packages.wazuh.com/4.x/macos/wazuh-agent-4.12.0-1.pkg

# Install package (requires admin password)
sudo installer -pkg wazuh-agent-4.12.0-1.pkg -target /

Step 2: Configure and Start

# Configure manager
sudo /Library/Ossec/bin/agent-auth -m YOUR_WAZUH_MANAGER_IP

# Start agent service
sudo launchctl load /Library/LaunchDaemons/com.wazuh.agent.plist

# Verify installation
sudo launchctl list | grep wazuh

macOS-Specific Considerations (the gotchas)

System Integrity Protection (SIP):

• May require disabling SIP for certain monitoring features (this is a big deal)

• Test thoroughly before deploying to production (I've seen this cause issues)

Privacy Settings:

• Users may need to grant accessibility permissions (this is often overlooked)

• Full disk access may be required for comprehensive monitoring (and users will complain about this)

Performance Impact:

• Monitor CPU usage on older Macs (it can be significant)

• Consider scheduling intensive scans during off-peak hours (this is crucial)

---

📋 Agent Management via Wazuh Dashboard

Here's the modern way: Wazuh's web interface makes agent management much easier than command-line tools, and honestly, it's where most people should start.

Adding Agents Through the Dashboard

1. Navigate to Agents → Deploy new agent

2. Select Operating System (Windows, Linux, macOS)

3. Copy the generated command

4. Run on target system

5. Verify in Dashboard

Agent Management Features

Real-time Status:

• Agent connection status

• Last check-in time

• Data transmission statistics

• Error logs and alerts

Configuration Management:

• Centralized agent configuration

• Group-based settings

• Remote configuration updates

• Policy enforcement

Monitoring and Alerting:

• Agent health monitoring

• Connection failure alerts

• Performance metrics

• Custom dashboards

---

⚙️ Advanced Agent Configuration

Custom Agent Configuration Example

<ossec_config>
  <client>
    <server>
      <address>YOUR_WAZUH_MANAGER_IP</address>
      <port>1514</port>
      <protocol>tcp</protocol>
    </server>
  </client>

  <!-- File integrity monitoring -->
  <syscheck>
    <disabled>no</disabled>
    <frequency>43200</frequency>
    <scan_on_start>yes</scan_on_start>
    <auto_ignore>no</auto_ignore>
    <directories check_all="yes" realtime="yes">/etc,/usr/bin,/usr/sbin</directories>
    <directories check_all="yes" realtime="yes">/bin,/sbin</directories>
    <ignore>/etc/ssl/private</ignore>
    <ignore>/etc/ssh/ssh_host_*</ignore>
  </syscheck>

  <!-- Log collection -->
  <localfile>
    <log_format>syslog</log_format>
    <location>/var/log/auth.log</location>
  </localfile>

  <localfile>
    <log_format>syslog</log_format>
    <location>/var/log/syslog</location>
  </localfile>

  <!-- Rootcheck -->
  <rootcheck>
    <disabled>no</disabled>
    <check_files>yes</check_files>
    <check_trojans>yes</check_trojans>
    <check_dev>yes</check_dev>
    <check_sys>yes</check_sys>
    <check_pids>yes</check_pids>
    <check_ports>yes</check_ports>
    <check_if>yes</check_if>
  </rootcheck>

  <!-- Wodle modules -->
  <wodle name="cis-cat">
    <disabled>no</disabled>
    <timeout>1800</timeout>
    <interval>1d</interval>
    <scan-on-start>yes</scan-on-start>
  </wodle>

  <wodle name="vulnerability-detector">
    <disabled>no</disabled>
    <interval>5m</interval>
    <ignore_time>6h</ignore_time>
    <run_on_start>yes</run_on_start>
  </wodle>
</ossec_config>

Agent Group Management

Creating Agent Groups:

# Create a group for web servers
curl -k -X POST "https://YOUR_WAZUH_IP:55000/agents/groups" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "web-servers"}'

Assigning Agents to Groups:

# Add agent to group
curl -k -X PUT "https://YOUR_WAZUH_IP:55000/agents/AGENT_ID/groups" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"groups": ["web-servers"]}'

---

🚨 Troubleshooting Common Agent Issues

Agent Connection Problems (the most common issues)

Issue: Agent shows as "Disconnected"

# Check agent status
sudo systemctl status wazuh-agent

# Check network connectivity
telnet YOUR_WAZUH_MANAGER_IP 1514

# Check agent logs
sudo tail -f /var/ossec/logs/ossec.log

# Restart agent
sudo systemctl restart wazuh-agent

Issue: Agent authentication fails

# Check agent key
sudo cat /var/ossec/etc/client.keys

# Re-register agent
sudo /var/ossec/bin/agent-auth -m YOUR_WAZUH_MANAGER_IP

# Check manager logs
sudo tail -f /var/ossec/logs/ossec.log

Performance Issues

Issue: High CPU usage

# Check agent processes
ps aux | grep ossec

# Monitor resource usage
htop

# Check agent configuration
sudo /var/ossec/bin/agent_control -l

Issue: High memory usage

# Check memory usage
free -h

# Check agent logs for errors
sudo tail -f /var/ossec/logs/ossec.log | grep ERROR

# Restart agent
sudo systemctl restart wazuh-agent

Data Collection Issues

Issue: No logs being collected

# Check log file permissions
ls -la /var/log/auth.log

# Check agent configuration
sudo cat /var/ossec/etc/ossec.conf | grep localfile

# Test log collection
sudo /var/ossec/bin/ossec-logtest

Issue: File integrity monitoring not working

# Check syscheck configuration
sudo cat /var/ossec/etc/ossec.conf | grep syscheck

# Check monitored directories
sudo /var/ossec/bin/syscheck_control -l

# Test file monitoring
sudo touch /tmp/test_file
sudo rm /tmp/test_file

---

📊 Monitoring Agent Health

Dashboard Metrics

Key Performance Indicators:

• Agent uptime - Should be 99%+ in production

• Data transmission rate - Monitor for drops

• Error rates - Should be minimal

• Response time - Should be under 1 second

Custom Dashboards:

{
  "title": "Agent Health Overview",
  "panels": [
    {
      "title": "Connected Agents",
      "type": "stat",
      "targets": [
        {
          "query": "agent.status:active"
        }
      ]
    },
    {
      "title": "Agent Response Time",
      "type": "graph",
      "targets": [
        {
          "query": "agent.last_keepalive"
        }
      ]
    }
  ]
}

Automated Monitoring

Health Check Script:

#!/bin/bash
# Agent health check script

AGENTS=$(curl -k -s -u admin:password "https://YOUR_WAZUH_IP:55000/agents" | jq -r '.data.affected_items[].id')

for agent in $AGENTS; do
  status=$(curl -k -s -u admin:password "https://YOUR_WAZUH_IP:55000/agents/$agent" | jq -r '.data.affected_items[0].status')
  if [ "$status" != "active" ]; then
    echo "Agent $agent is not active: $status"
    # Send alert to monitoring system
  fi
done

---

🎯 Best Practices for Production

Security Considerations

1. Use SSL/TLS for all agent communications

2. Implement certificate pinning for enhanced security

3. Regular key rotation for agent authentication

4. Network segmentation to isolate agent traffic

5. Regular security updates for agent software

Performance Optimization

1. Resource monitoring - Monitor CPU, memory, and disk usage

2. Log filtering - Reduce noise by filtering irrelevant logs

3. Scheduled scans - Run intensive scans during off-peak hours

4. Agent grouping - Use groups for efficient management

5. Regular cleanup - Remove old logs and temporary files

Scaling Strategies

Small Environment (< 100 agents):

• Single manager node

• Basic monitoring

• Manual agent management

Medium Environment (100-1000 agents):

• Load-balanced manager nodes

• Automated agent deployment

• Centralized configuration management

Large Environment (1000+ agents):

• Distributed manager architecture

• Automated scaling

• Advanced monitoring and alerting

---

✅ Wrapping Up

By now, you've learned how to deploy and manage Wazuh agents across different platforms. This is the foundation of a successful Wazuh deployment, and honestly, it's where most people get stuck.

What you've accomplished:

• Deployed agents on Windows, Linux, and macOS

• Configured proper monitoring and logging

• Implemented troubleshooting procedures

• Set up monitoring and alerting

Next steps:

1. Scale your deployment - Add more agents gradually (don't try to do everything at once)

2. Fine-tune configurations - Optimize for your environment (this takes time)

3. Set up integrations - Connect with other security tools (this is where it gets interesting)

4. Create custom dashboards - Visualize your security posture (this is actually fun)

Pro tip: Start with a small number of agents and gradually scale up. This allows you to identify and resolve issues before they become problems (and trust me, you'll have issues).

---

🔜 What's Next?

Now that you have agents collecting data, it's time to make sense of all that information. In the next chapter, we'll explore integrating Wazuh with network security tools like pfSense, Suricata, and Zeek.

You'll learn:

• How to integrate network security tools

• Best practices for log correlation

• Advanced threat detection techniques

• Building comprehensive security dashboards