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.confEnable 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-managerPhase 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.mstin 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 /forceVerify Deployment
On Wazuh server:
# Check registered agents/var/ossec/bin/agent_control -lExpected 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, ActiveAdvanced 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" -AllIssue 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 20Issue 3: Agent Not Connecting
Verify network connectivity:
# Test Wazuh server connectivityTest-NetConnection -ComputerName <WAZUH_SERVER_IP> -Port 1514Test-NetConnection -ComputerName <WAZUH_SERVER_IP> -Port 1515Deployment 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! 🛡️