Deploying Wazuh Agents Using Windows Group Policy Objects (GPO)
Introduction
Managing security agent deployment across hundreds or thousands of Windows endpoints can be a daunting task. Manual installation is time-consuming, error-prone, and doesn’t scale well. This is where Windows Group Policy Objects (GPO) come to the rescue, enabling centralized, automated deployment of the Wazuh agent across your entire Active Directory infrastructure.
By leveraging GPO for Wazuh agent deployment, organizations can achieve:
- 🚀 Automated Deployment: Push agents to all domain-joined machines
- 🎯 Centralized Management: Control deployments from a single location
- 🔧 Consistent Configuration: Ensure uniform agent settings
- 📊 Scalable Operations: Deploy to thousands of endpoints effortlessly
- 🔄 Easy Updates: Manage agent versions through policy updates
Understanding the Components
Group Policy Objects (GPO)
GPOs are collections of policy settings in Microsoft Windows that allow administrators to:
- Configure operating system settings
- Deploy software packages
- Enforce security policies
- Manage user and computer configurations
MSI and MST Files
- MSI (Microsoft Software Installer): Package format for Windows installations
- MST (Microsoft Transform): Customization file that modifies MSI behavior
- Orca: Microsoft tool for creating and editing MSI/MST files
Architecture Overview
flowchart TB subgraph "Active Directory Infrastructure" DC[Domain Controller<br/>GPO Management] AD[Active Directory] GPO1[Wazuh Agent<br/>Deployment GPO] GPO2[Wazuh Service<br/>Activation GPO] end
subgraph "Shared Resources" SF[Network Share<br/>\\Win-0aeqj5brr86\dc] MSI[Wazuh Agent MSI] MST[Custom.mst File] end
subgraph "Target Endpoints" OU[Wazuh OU] W1[Windows 11<br/>Endpoint 1] W2[Windows 11<br/>Endpoint 2] W3[Windows 11<br/>Endpoint N] end
subgraph "Wazuh Infrastructure" WS[Wazuh Server] WD[Wazuh Dashboard] end
DC --> GPO1 DC --> GPO2 GPO1 --> SF SF --> MSI SF --> MST GPO1 --> OU GPO2 --> OU OU --> W1 OU --> W2 OU --> W3 W1 -.->|Register| WS W2 -.->|Register| WS W3 -.->|Register| WS WS --> WD
style DC fill:#ffd43b style WS fill:#51cf66 style GPO1 fill:#4dabf7 style GPO2 fill:#4dabf7
Infrastructure Requirements
- Wazuh Server: Pre-built OVA 4.7.3 with all core components
- Domain Controller: Windows Server 2019+ hosting Active Directory
- Target Endpoints: Windows 11 domain-joined machines
- Administrative Account: Domain admin privileges for GPO creation
Implementation Guide
Phase 1: Configure Wazuh Server
Enable password-based agent enrollment for automated deployment:
# Edit the Wazuh configurationvi /var/ossec/etc/ossec.conf
Enable password authentication:
<auth> <use_password>yes</use_password></auth>
Create and secure the password file:
# Set enrollment passwordecho "BlueWolf" > /var/ossec/etc/authd.pass
# Secure the password filechmod 640 /var/ossec/etc/authd.passchown root:wazuh /var/ossec/etc/authd.pass
# Restart Wazuh managersystemctl restart wazuh-manager
Phase 2: Create MST File with Orca
Install Orca
- Download Windows SDK Components for Windows Installer Developers
- Install Orca from:
C:\Program Files (x86)\Windows Kits\10\bin\10.0.22621.0\x86\Orca-x86_en-us.msi
Configure Wazuh Agent Installer
- Launch Orca and open the Wazuh agent MSI file
- Navigate to the Property table
- Create a new transform: Transform > New Transform
- Add deployment parameters:
ADDRESS = <WAZUH_SERVER_IP>AUTHD_SERVER = <WAZUH_SERVER_IP>PROTOCOL = TCPPASSWORD = BlueWolf
- Save as
custom.mst
: Transform > Generate Transform
MST Configuration Details
flowchart LR subgraph "MSI Package" MP[Original MSI<br/>Parameters] end
subgraph "MST Transform" T1[ADDRESS] T2[AUTHD_SERVER] T3[PROTOCOL] T4[PASSWORD] end
subgraph "Installation" I1[Modified<br/>Installation] end
MP --> T1 MP --> T2 MP --> T3 MP --> T4 T1 --> I1 T2 --> I1 T3 --> I1 T4 --> I1
style T1 fill:#51cf66 style T2 fill:#51cf66 style T3 fill:#51cf66 style T4 fill:#51cf66
Phase 3: Create Network Share
Set up a shared folder for GPO deployment:
# Create shared folderNew-Item -Path "C:\Users\$env:USERNAME\Desktop\DC" -ItemType Directory
# Share with authenticated users$sharePath = "C:\Users\$env:USERNAME\Desktop\DC"New-SmbShare -Name "DC" -Path $sharePath -ReadAccess "Authenticated Users"
Copy the Wazuh MSI and custom.mst files to the shared folder.
Phase 4: Configure Group Policy Objects
Create Organizational Unit
- Open Active Directory Users and Computers
- Right-click domain → New → Organizational Unit
- Name it “Wazuh”
- Move target computers to this OU
Create Deployment GPO
- Open Group Policy Management (
gpmc.msc
) - Create new GPO: “Wazuh agent deployment”
- Edit GPO:
- Navigate to: Computer Configuration → Policies → Software Settings → Software installation
- Right-click → New → Package
- Select MSI from network share
- Choose Advanced deployment
- Add
custom.mst
in Modifications tab
Create Service Activation GPO
- Create new GPO: “Wazuh agent activate”
- Edit GPO:
- Navigate to: Computer Configuration → Preferences → Control Panel Settings → Services
- Create new service:
- Service name:
WazuhSvc
- Service action:
Start service
- Recovery: Set all to
Restart the Service
- Service name:
Phase 5: Apply and Test Deployment
Link GPOs to OU
# Link GPOs to Wazuh OUNew-GPLink -Name "Wazuh agent deployment" -Target "OU=Wazuh,DC=wazuhtests,DC=com"New-GPLink -Name "Wazuh agent activate" -Target "OU=Wazuh,DC=wazuhtests,DC=com"
Force Policy Update
On target endpoints, run with administrative privileges:
# Interactive updategpupdate /force
# Non-interactive updateecho N | gpupdate /force
Verify Deployment
On Wazuh server:
# Check registered agents/var/ossec/bin/agent_control -l
Expected output:
Wazuh agent_control. List of available agents: ID: 000, Name: wazuh-server (server), IP: 127.0.0.1, Active/Local ID: 001, Name: Windows11, IP: any, Active
Advanced Configuration
Customizing Deployment Parameters
Create different MST files for various scenarios:
# Development environment MST$devParams = @{ ADDRESS = "10.0.1.100" AUTHD_SERVER = "10.0.1.100" PROTOCOL = "TCP" PASSWORD = "DevPassword" AGENT_NAME = "DEV-%COMPUTERNAME%"}
# Production environment MST$prodParams = @{ ADDRESS = "10.0.2.100" AUTHD_SERVER = "10.0.2.100" PROTOCOL = "TCP" PASSWORD = "ProdPassword" AGENT_NAME = "PROD-%COMPUTERNAME%"}
Targeting Specific Computer Groups
Use WMI filters for granular deployment:
-- Deploy only to Windows 11 workstationsSELECT * FROM Win32_OperatingSystemWHERE Version LIKE "10.0.22%"AND ProductType = "1"
-- Deploy only to serversSELECT * FROM Win32_OperatingSystemWHERE ProductType != "1"
Monitoring Deployment Progress
Create a PowerShell script for deployment monitoring:
$computers = Get-ADComputer -Filter * -SearchBase "OU=Wazuh,DC=wazuhtests,DC=com"
foreach ($computer in $computers) { $result = Test-Connection -ComputerName $computer.Name -Count 1 -Quiet if ($result) { $service = Get-Service -Name "WazuhSvc" -ComputerName $computer.Name -ErrorAction SilentlyContinue if ($service) { Write-Host "$($computer.Name): Wazuh installed - Status: $($service.Status)" -ForegroundColor Green } else { Write-Host "$($computer.Name): Wazuh not installed" -ForegroundColor Red } } else { Write-Host "$($computer.Name): Offline" -ForegroundColor Yellow }}
Troubleshooting
Common Issues and Solutions
Issue 1: GPO Not Applying
Symptoms: Agent not installing after gpupdate
Solutions:
# Check GPO applicationgpresult /h gpreport.html
# Verify computer is in correct OUGet-ADComputer -Identity "ComputerName" | Select DistinguishedName
# Check GPO permissionsGet-GPPermission -Name "Wazuh agent deployment" -All
Issue 2: Installation Fails
Check Windows Event Logs:
# Check application logsGet-EventLog -LogName Application -Source MsiInstaller -Newest 20
# Check system logsGet-EventLog -LogName System -Source GroupPolicy -Newest 20
Issue 3: Agent Not Connecting
Verify network connectivity:
# Test Wazuh server connectivityTest-NetConnection -ComputerName <WAZUH_SERVER_IP> -Port 1514Test-NetConnection -ComputerName <WAZUH_SERVER_IP> -Port 1515
Deployment Validation Script
param( [string]$WazuhServer = "192.168.1.100", [string]$ExpectedVersion = "4.7.3")
function Test-WazuhDeployment { $results = @()
# Check if Wazuh is installed $installed = Get-WmiObject -Class Win32_Product | Where-Object {$_.Name -like "*Wazuh*"}
if ($installed) { $results += "✓ Wazuh installed: $($installed.Version)"
# Check service status $service = Get-Service -Name "WazuhSvc" -ErrorAction SilentlyContinue if ($service) { $results += "✓ Wazuh service status: $($service.Status)" } else { $results += "✗ Wazuh service not found" }
# Check configuration $configPath = "C:\Program Files (x86)\ossec-agent\ossec.conf" if (Test-Path $configPath) { $config = Get-Content $configPath if ($config -match $WazuhServer) { $results += "✓ Correct server configured: $WazuhServer" } else { $results += "✗ Incorrect server configuration" } }
# Check connectivity if (Test-NetConnection -ComputerName $WazuhServer -Port 1514 -InformationLevel Quiet) { $results += "✓ Can reach Wazuh server" } else { $results += "✗ Cannot reach Wazuh server" } } else { $results += "✗ Wazuh not installed" }
return $results}
# Run validation$validation = Test-WazuhDeployment$validation | ForEach-Object { Write-Host $_ }
Best Practices
1. Phased Deployment
flowchart LR subgraph "Phase 1" P1[Test OU<br/>5-10 machines] end
subgraph "Phase 2" P2[Pilot OU<br/>50-100 machines] end
subgraph "Phase 3" P3[Department OUs<br/>500+ machines] end
subgraph "Phase 4" P4[Enterprise-wide<br/>All machines] end
P1 -->|Validate| P2 P2 -->|Monitor| P3 P3 -->|Scale| P4
style P1 fill:#51cf66 style P2 fill:#4dabf7 style P3 fill:#ffd43b style P4 fill:#ff6b6b
2. Security Considerations
- Password Protection: Use strong, unique passwords for agent enrollment
- Network Security: Restrict share access to authenticated users only
- MST Security: Protect MST files from unauthorized modification
- GPO Permissions: Limit who can modify deployment GPOs
3. Maintenance Strategy
# Automated agent version check$targetVersion = "4.7.3"$outdatedComputers = @()
Get-ADComputer -Filter * -SearchBase "OU=Wazuh,DC=wazuhtests,DC=com" | ForEach-Object { $version = Invoke-Command -ComputerName $_.Name -ScriptBlock { (Get-ItemProperty "HKLM:\Software\Microsoft\Windows\CurrentVersion\Uninstall\*" | Where-Object {$_.DisplayName -like "*Wazuh*"}).DisplayVersion } -ErrorAction SilentlyContinue
if ($version -ne $targetVersion) { $outdatedComputers += $_.Name }}
# Report outdated installationsif ($outdatedComputers.Count -gt 0) { Write-Host "Computers needing update:" -ForegroundColor Yellow $outdatedComputers | ForEach-Object { Write-Host " - $_" }}
Scaling Considerations
Large Enterprise Deployments
For organizations with thousands of endpoints:
- Stagger Deployments: Use multiple GPOs with different schedules
- Regional Distribution: Create regional file shares for MSI distribution
- Bandwidth Management: Implement BITS for package distribution
- Load Balancing: Deploy multiple Wazuh servers behind a load balancer
Performance Optimization
<!-- Optimize GPO processing --><GPO> <Computer> <ExtensionSettings> <Extension> <CSE>{42B5FAAE-6536-11d2-AE5A-0000F87571E3}</CSE> <Mode>Replace</Mode> <Policy> <SlowLinkThreshold>500</SlowLinkThreshold> <BackgroundPriority>Low</BackgroundPriority> </Policy> </Extension> </ExtensionSettings> </Computer></GPO>
Integration with SCCM/ConfigMgr
For organizations using System Center Configuration Manager:
# Create SCCM application for Wazuh$app = New-CMApplication ` -Name "Wazuh Agent 4.7.3" ` -Publisher "Wazuh Inc" ` -SoftwareVersion "4.7.3"
# Add deployment typeAdd-CMDeploymentType ` -ApplicationName "Wazuh Agent 4.7.3" ` -DeploymentTypeName "MSI Installer" ` -InstallCommand "msiexec /i wazuh-agent.msi TRANSFORMS=custom.mst /qn" ` -DetectionMethod {Get-Service -Name WazuhSvc}
Conclusion
Deploying Wazuh agents through Group Policy Objects transforms a potentially complex, time-consuming task into an automated, scalable solution. This approach ensures:
- ✅ Consistent deployment across all domain-joined machines
- 🚀 Rapid rollout to thousands of endpoints
- 🔧 Centralized management of agent configurations
- 📊 Easy monitoring of deployment status
- 🔄 Simplified updates through policy modifications
By following this guide, organizations can achieve comprehensive endpoint security coverage while minimizing administrative overhead.
Key Takeaways
- Plan Thoroughly: Test MST configurations before mass deployment
- Phase Rollouts: Start small and scale gradually
- Monitor Progress: Use scripts to track deployment success
- Document Everything: Maintain records of GPO configurations
- Regular Updates: Plan for agent version management
Resources
- Wazuh Agent Installation Documentation
- Group Policy Overview
- Orca.exe Documentation
- Windows Installer Guide
Automate security at scale. Deploy once, protect everywhere! 🛡️