Wazuh Deployment & Customization Scripts

This repository contains automated deployment scripts for installing Wazuh agents and customizing Wazuh Dashboard branding.

Overview

Wazuh is an open-source security monitoring platform. These scripts automate the deployment of Wazuh agents to endpoints and provide tools for customizing the Wazuh Dashboard with your company branding.

Repository Structure

wazuh-deploy/
├── macos/
│   ├── deploy-wazuh-agent.sh
│   └── README.md
├── debian/
│   ├── deploy-wazuh-agent.sh
│   ├── uninstall-wazuh-agent.sh
│   └── README.md
├── dashboard/
│   ├── customize-wazuh-dashboard.sh
│   ├── rollback-wazuh-dashboard.sh
│   └── README.md
├── intune/
│   └── (coming soon)
└── README.md

Supported Platforms

• ✅ macOS (Intel & Apple Silicon)
• ✅ Debian/Ubuntu (amd64 & arm64)
• 🚧 RHEL/CentOS - Coming soon
• 🚧 Windows via Intune - Coming soon

Features

macOS Deployment Script

• ✅ Automatic architecture detection (ARM64/Intel)
• ✅ Auto-downloads latest Wazuh agent version
• ✅ Intelligent version detection with multiple fallback methods
• ✅ Safe removal of existing installations
• ✅ Configurable manager, agent group, and agent name
• ✅ Comprehensive post-installation verification
• ✅ Detailed logging and error handling

Debian/Ubuntu Deployment Script

• ✅ Installs latest version via apt-get
• ✅ Safe removal of existing installations
• ✅ Automatic repository and GPG key configuration
• ✅ Configurable manager, agent group, and agent name
• ✅ Automatic daily updates (2:00 AM via cron)
• ✅ Comprehensive post-installation verification
• ✅ Detailed logging and error handling
• ✅ Complete uninstall script included

Dashboard Customization Script

• ✅ Replace dashboard header logo
• ✅ Replace login page background
• ✅ Replace favicon
• ✅ Update application title (browser tab)
• ✅ Configure branding URLs via config file
• ✅ Automatic backup of original files
• ✅ Complete rollback capability

Quick Start

macOS Installation

1. Download the script:

   curl -O https://raw.githubusercontent.com/PurpleComputing/wazuh-deploy/main/macos/deploy-wazuh-agent.sh

2. Edit configuration variables (optional):

   nano deploy-wazuh-agent.sh

   Modify these variables at the top of the script:

   export WAZUH_MANAGER='wazuh.example.com'
   export WAZUH_AGENT_GROUP='default'
   export WAZUH_AGENT_NAME='%DeviceName%'

3. Make executable and run:

   chmod +x deploy-wazuh-agent.sh
   sudo ./deploy-wazuh-agent.sh

Debian/Ubuntu Installation

1. Download the script:

   curl -O https://raw.githubusercontent.com/PurpleComputing/wazuh-deploy/main/debian/deploy-wazuh-agent.sh

2. Set environment variables (optional):

   export WAZUH_MANAGER='wazuh.example.com'
   export WAZUH_AGENT_GROUP='production'
   export WAZUH_AGENT_NAME='my-server'

3. Make executable and run:

   chmod +x deploy-wazuh-agent.sh
   sudo -E ./deploy-wazuh-agent.sh

Dashboard Customization

# Download the script
curl -O https://raw.githubusercontent.com/PurpleComputing/wazuh-deploy/main/dashboard/customize-wazuh-dashboard.sh

# Make it executable
chmod +x customize-wazuh-dashboard.sh

# Run with your CDN URLs
sudo BRAND_NAME="Your Company" \
     CDN_LOGO_URL="https://cdn.example.com/logo.svg" \
     CDN_LOGIN_BG_URL="https://cdn.example.com/login-bg.svg" \
     CDN_FAVICON_URL="https://cdn.example.com/favicon.ico" \
     ./customize-wazuh-dashboard.sh

Configuration

Environment Variables

The scripts use the following environment variables for configuration:

Variable	Description	Example
WAZUH_MANAGER	Hostname or IP of your Wazuh manager	wazuh.example.com
WAZUH_AGENT_GROUP	Agent group for organizational purposes	production
WAZUH_AGENT_NAME	Agent name (use %DeviceName% for auto-detection on macOS)	%DeviceName%

Customization

You can customize the deployment by:

1. Editing variables directly in the script before deployment
2. Exporting variables before running:

   export WAZUH_MANAGER='your-manager.domain.com'
   export WAZUH_AGENT_GROUP='your-group'
   export WAZUH_AGENT_NAME='custom-name'
   sudo -E ./deploy-wazuh-agent.sh

How It Works

macOS Script Flow

1. Pre-flight checks

   • Detects system architecture (ARM64 vs Intel)
   • Fetches latest Wazuh version from documentation/GitHub
   • Verifies package availability

2. Removal of existing installation

   • Stops running Wazuh services
   • Removes installation directories (only if they exist)
   • Cleans up launch daemons and startup items
   • Forgets package receipts

3. Installation

   • Downloads appropriate package for architecture
   • Validates download integrity
   • Installs Wazuh agent
   • Configures manager connection

4. Verification

   • Checks running processes
   • Verifies file structure
   • Tests agent status
   • Reviews configuration
   • Displays recent logs

Troubleshooting

Common Issues

Agent not connecting to manager

# Check agent status
sudo /Library/Ossec/bin/wazuh-control status

# View logs
tail -f /Library/Ossec/logs/ossec.log

# Test manager connectivity
sudo /Library/Ossec/bin/agent-auth -m YOUR_MANAGER_ADDRESS

Installation fails

• Verify internet connectivity
• Check that you're running with sudo
• Ensure no firewall is blocking packages.wazuh.com
• Review script output for specific error messages

Version detection fails

The script uses multiple fallback methods:

1. Wazuh documentation page
2. GitHub redirect URL
3. GitHub releases HTML parsing
4. Hardcoded fallback version

If all fail, manually specify a version by editing the fallback in the script.

Manual Agent Registration

If automatic registration fails:

# Register agent manually
sudo /Library/Ossec/bin/agent-auth -m YOUR_MANAGER -A AGENT_NAME -G GROUP_NAME

# Restart agent
sudo /Library/Ossec/bin/wazuh-control restart

Security Considerations

• Scripts require sudo privileges for installation
• Environment variables are exported and written to /tmp/wazuh_envs
• Downloads are verified for integrity before installation
• Only removes existing installations if files are present

Requirements

macOS

• macOS 10.15 (Catalina) or later
• Administrator (sudo) privileges
• Internet connectivity
• curl (pre-installed on macOS)

Debian/Ubuntu

• Debian 10+ or Ubuntu 20.04+
• Root or sudo privileges
• Internet connectivity

RHEL/CentOS (Coming Soon)

• RHEL 8+, CentOS 8+
• Root or sudo privileges
• Internet connectivity

Windows/Intune (Coming Soon)

• Windows 10/11
• Intune enrollment
• PowerShell 5.1+

Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.

Adding New Platforms

When adding scripts for new platforms:

1. Create a new directory for the platform
2. Follow the existing naming convention
3. Include inline documentation
4. Update this README
5. Test thoroughly before submitting PR

Version History

See CHANGELOG.md for detailed version history.

Roadmap

• Linux deployment scripts (Debian/Ubuntu)
• Uninstall scripts (Debian/Ubuntu)
• Auto-update functionality (Debian/Ubuntu)
• Dashboard customization/rebranding scripts
• Linux deployment scripts (RHEL/CentOS)
• Windows Intune deployment package
• Ansible playbooks
• Docker container deployment
• Centralized configuration management
• macOS uninstall script

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues related to:

• These scripts: Open an issue in this repository
• Wazuh itself: Visit Wazuh Documentation
• Wazuh community: Join the Wazuh Slack

Resources

• Wazuh Official Documentation
• Wazuh GitHub Repository
• Wazuh Installation Guide
• Wazuh Agent Configuration

Authors

• Purple Computing IT Team

Acknowledgments

• Wazuh team for the excellent security platform
• Community contributors and testers