Installazione Wazuh Agent via GPO su Windows Server 2022 e Windows 10/11 (senza Orca): guida completa

Vuoi distribuire Wazuh Agent in modo centralizzato su Windows 10/11 partendo da un Domain Controller Windows Server 2022, senza creare trasformazioni MSI con Orca? In questa guida trovi una procedura GPO basata su startup script, robusta, ripetibile e facile da diagnosticare.

Indice

Scenario e obiettivo

Un amministratore dispone di un controller di dominio Windows Server 2022 e di una flotta di endpoint Windows 10/11. L’obiettivo è distribuire Wazuh Agent in silent mode via Group Policy (GPO), evitando di modificare l’MSI con strumenti come orca.exe. È stato tentato un semplice script di avvio posizionato in una share generica, ma l’installazione non parte all’avvio dei client.

La soluzione corretta è affidare completamente l’esecuzione allo Startup Script del GPO e mantenere sia lo script sia (opzionalmente) il pacchetto MSI dentro il percorso SYSVOL del GPO stesso. Così si sfrutta la replica nativa tra DC, si garantisce la sicurezza ACL predefinita e si riducono i problemi di percorso/permessi.

Perché uno startup script su GPO (e non “Software Installation”)

  • Nessuna trasformazione MSI (MST): molte distribuzioni richiedono property MSI. Con gli startup script puoi passarle direttamente a msiexec.exe senza creare file MST con Orca.
  • Idempotenza: puoi costruire logica “installa se non presente / aggiorna se necessario”, evitando reinstallazioni inutili.
  • Diagnostica chiara: log MSI, Event Viewer → GroupPolicy → Operational, e comandi come gpresult forniscono visibilità sul perché uno script non è partito.
  • Allineamento a best practice di dominio: mantenendo file e script sotto SYSVOL replichi e applichi un unico punto di verità.

Prerequisiti

RequisitoDettagli
Active Directory sanoReplica SYSVOL consistente tra i DC; DNS funzionante; clock sincronizzato.
PermessiAmministratore di dominio per creare/linkare GPO e scrivere in SYSVOL.
Connettività verso il ManagerGli endpoint devono raggiungere il Wazuh Manager (es. 1514/UDP, 1515/TCP/UDP a seconda della tua configurazione).
Spazio e I/OAssicurati che i client possano leggere file in \\DOMINIO\SYSVOL con l’account computer (SYSTEM).

Procedura passo‑passo

Organizzare i computer target

  1. Crea (o riutilizza) una OU dedicata, ad es. Workstations‑Wazuh.
  2. Sposta nella OU tutti i PC su cui installare l’agente.

Creare il GPO

  1. Apri Group Policy Management (gpmc.msc).
  2. Crea un nuovo oggetto criteri: Deploy Wazuh.
  3. Prendi nota del GUID del GPO (verrà usato nel percorso SYSVOL):
    \\DOMINIO\SYSVOL\DOMINIO\Policies\{GUID_GPO}\

Copiare lo script (e l’MSI) nella cartella corretta

Posiziona il file .bat o .ps1 (e, se preferisci, anche il file MSI) in:

\\DOMINIO\SYSVOL\DOMINIO\Policies\{GUID_GPO}\Machine\Scripts\Startup

Questo è il punto cruciale: se collochi lo script in una share generica (es. \\fileserver\share\...) l’estensione Scripts del GPO potrebbe non eseguirlo correttamente all’avvio del computer. Lanciare i file direttamente da SYSVOL evita la maggior parte dei blocchi di sicurezza e problemi di path.

Configurare lo Startup Script

  1. Apri il GPO → Computer Configuration → Policies → Windows Settings → Scripts (Startup/Shutdown) → Startup.
  2. Clic su Add… e seleziona lo script (dal percorso SYSVOL indicato sopra).
  3. Se usi PowerShell: nella stessa finestra, scheda PowerShell Scripts, abilita “Run Windows PowerShell scripts first” e “Use 64-bit PowerShell” su sistemi a 64 bit.

Impostazioni GPO consigliate per la rete e l’ordine di esecuzione

  • Always wait for the network at computer startup and logon: Computer Configuration → Policies → Administrative Templates → System → Logon. In questo modo il computer attende la rete prima di processare i criteri e lanciare lo script.
  • Startup scripts run: preferisci synchronous se vuoi assicurarti che lo script completi prima di altri task di avvio, specialmente se l’MSI è grande. (Il settaggio inverso “run asynchronously” può ridurre la latenza percepita ma rende la sequenza meno deterministica.)

Linkare il GPO all’OU

  1. Seleziona la OU Workstations‑Wazuh in Group Policy Management.
  2. Click destro → Link an Existing GPO → seleziona Deploy Wazuh.

Verificare l’applicazione lato client

  1. Su un client: gpupdate /force oppure riavvia.
  2. Dopo 1‑2 riavvii (specie con nuove GPO o se la rete è lenta), controlla Event Viewer → Applications and Services Logs → Microsoft → Windows → GroupPolicy → Operational per errori o conferme di esecuzione.
  3. In alternativa: gpresult /h C:\temp\gpresult.html e verifica che il GPO sia applicato alla Computer Configuration.

Script pronti all’uso

Esempio batch (Deploy-Wazuh-Agent.bat)

Questo esempio è idempotente, logga l’installazione e gestisce i casi di “già presente” e “riavvio richiesto”. Posiziona l’MSI nella stessa cartella dello script in SYSVOL, così %~dp0 funzionerà invariato.

@echo off
setlocal enabledelayedexpansion

REM === Parametri personalizzabili ===
set "WAZUH_MSI=wazuh-agent-4.7.1.msi"
set "WAZUH_MANAGER=10.10.0.5"
set "WAZUHREGPASSWORD="
set "LOG=%SystemRoot%\Temp\WazuhAgentInstall.log"

REM === Rileva servizio per idempotenza ===
sc query "WazuhSvc" >NUL 2>&1
if "%ERRORLEVEL%"=="0" (
echo Wazuh Agent risulta installato. Avvio/riavvio del servizio... >> "%LOG%"
net start WazuhSvc >> "%LOG%" 2>&1
goto :EOF
)

REM === Percorso MSI relativo allo script in SYSVOL ===
set "MSIPATH=%~dp0%WAZUHMSI%"
if not exist "%MSI_PATH%" (
echo ERRORE: MSI non trovato in "%MSI_PATH%". >> "%LOG%"
exit /b 1
)

REM === Installazione silenziosa ===
echo Avvio installazione Wazuh... >> "%LOG%"
start /wait msiexec.exe /i "%MSI_PATH%" /qn /norestart ^
WAZUHMANAGER="%WAZUHMANAGER%" WAZUHREGISTRATIONPASSWORD="%WAZUHREGPASSWORD%" ^
/l*v "%LOG%"

set "RC=%ERRORLEVEL%"
echo msiexec ha restituito codice %RC% >> "%LOG%"

if "%RC%"=="0" goto :SUCCESS
if "%RC%"=="3010" goto :SUCCESS

if "%RC%"=="1638" (
echo Una versione del prodotto e' gia' installata. >> "%LOG%"
goto :SUCCESS
)

echo Installazione fallita con codice %RC%. >> "%LOG%"
exit /b %RC%

:SUCCESS
sc start "WazuhSvc" >> "%LOG%" 2>&1
exit /b 0 </code></pre>

<h3>Esempio PowerShell (<code>Deploy-Wazuh-Agent.ps1</code>)</h3>
<p>Versione equivalente in PowerShell. Ricorda di abilitare l’esecuzione degli script via GPO (<em>Turn on Script Execution → Allow all scripts</em>) o firma il file.</p>
<pre><code class="language-powershell">$ErrorActionPreference = 'Stop'

=== Parametri ===

$MsiName = 'wazuh-agent-4.7.1.msi'
$Manager = '10.10.0.5'
$RegPassword = ''  # opzionale se non usi password di registrazione
$Log = "$env:windir\Temp\WazuhAgentInstall.log"

Idempotenza: se esiste il servizio, limita a (ri)avvio

try {
$svc = Get-Service -Name 'WazuhSvc' -ErrorAction Stop
if ($svc.Status -ne 'Running') { Start-Service -Name 'WazuhSvc' }
exit 0
} catch {}

$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
$MsiPath   = Join-Path $ScriptDir $MsiName
if (-not (Test-Path $MsiPath)) {
"ERRORE: MSI non trovato: $MsiPath" | Out-File -FilePath $Log -Append -Encoding UTF8
exit 1
}

$args = @(
'/i', "`"$MsiPath`"",
'/qn', '/norestart',
"WAZUHMANAGER=`"$Manager`"",
"WAZUHREGISTRATION_PASSWORD=`"$RegPassword`"",
'/l*v', "`"$Log`""
)

$proc = Start-Process -FilePath 'msiexec.exe' -ArgumentList $args -Wait -PassThru
"msiexec ha restituito codice $($proc.ExitCode)" | Out-File -FilePath $Log -Append

switch ($proc.ExitCode) {
0     { Start-Service -Name 'WazuhSvc' -ErrorAction SilentlyContinue; exit 0 }
3010  { Start-Service -Name 'WazuhSvc' -ErrorAction SilentlyContinue; exit 0 } # success with reboot required
1638  { Start-Service -Name 'WazuhSvc' -ErrorAction SilentlyContinue; exit 0 } # another version present
default {
"Installazione fallita con codice $($proc.ExitCode)" | Out-File -FilePath $Log -Append
exit $proc.ExitCode
}
} </code></pre>

<p><strong>Nota</strong>: i nomi esatti delle proprietà MSI possono variare tra release. Nello script sono state usate le varianti più comuni fornite nello scenario (<code>WAZUHMANAGER</code> e <code>WAZUHREGISTRATION_PASSWORD</code>). Adegua i parametri alla tua versione dell’agente qualora differissero.</p>

<hr>

<h2>Controlli rapidi post‑installazione</h2>
<ul>
  <li><strong>Servizio</strong>: <code>Get-Service WazuhSvc</code> oppure <code>sc query WazuhSvc</code> deve mostrare stato <em>RUNNING</em>.</li>
  <li><strong>Firewall</strong>: verifica l’uscita verso il Manager (es. 1514/UDP e/o 1515/TCP). Se necessario, crea una regola:
    <pre><code class="language-powershell">New-NetFirewallRule -DisplayName "Wazuh Outbound" -Direction Outbound -Action Allow -Protocol TCP -RemotePort 1515
</code></pre>
  </li>
  <li><strong>Log MSI</strong>: <code>%windir%\Temp\WazuhAgentInstall.log</code> (o percorso da te scelto) per diagnosticare eventuali errori di <code>msiexec</code>.</li>
  <li><strong>Eventi GPO</strong>: <em>Event Viewer → Microsoft → Windows → GroupPolicy → Operational</em> (cerca ID eventi correlati a script di avvio ed errori di esecuzione).</li>
</ul>

<hr>

<h2>Motivi comuni di fallimento (e come risolverli)</h2>
<table>
  <thead>
    <tr>
      <th>Problema</th>
      <th>Verifica / Rimedio</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Lo script non parte</td>
      <td>
        <ul>
          <li>Assicurati che lo script sia in <code>\\DOMINIO\SYSVOL\DOMINIO\Policies\{GUID_GPO}\Machine\Scripts\Startup</code> e che sia referenziato dal GPO.</li>
          <li>Estensione corretta (<code>.bat</code> o <code>.ps1</code>) e selezione nel GPO (scheda <em>Scripts</em>).</li>
          <li>Abilita “<em>Always wait for the network at computer startup and logon</em>” per garantire la rete prima dell’esecuzione dei criteri.</li>
          <li>Controlla <em>GroupPolicy → Operational</em> per errori di path/permessi.</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td>Diritti di condivisione</td>
      <td>
        <ul>
          <li><em>Authenticated Users</em> deve avere <strong>Lettura</strong> su SYSVOL; lo script gira come <strong>SYSTEM</strong> (account computer).</li>
          <li>Non rimuovere la voce <em>Domain Computers</em> dall’ACL del GPO.</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td>Parametri MSI errati</td>
      <td>
        <ul>
          <li>Esempio tipico di <em>silent install</em>:
            <pre><code>msiexec /i wazuh-agent-4.7.1.msi /qn WAZUHMANAGER="10.10.0.5" WAZUHREGISTRATION_PASSWORD=""
      </li>
      <li>Rispetta le virgolette sulle proprietà, specie per indirizzi FQDN o valori con caratteri speciali.</li>
    </ul>
  </td>
</tr>
<tr>
  <td>Limiti di esecuzione PowerShell</td>
  <td>
    <ul>
      <li>Se usi .ps1, configura via GPO: <em>Turn on Script Execution → Allow all scripts</em>, oppure firma lo script.</li>
      <li>Su OS a 64 bit, spunta “Use 64-bit PowerShell”.</li>
    </ul>
  </td>
</tr>
<tr>
  <td>Sequenza e tempi</td>
  <td>
    <ul>
      <li>Gli script di avvio possono richiedere uno o più riavvii per la prima applicazione. Dopo aver linkato/aggiornato il GPO, testa con gpupdate /force e riavvio.</li>
      <li>Se la rete è lenta, evita l’esecuzione completamente asincrona: rischi che msiexec parta senza aver ancora letto il contenuto da SYSVOL.</li>
    </ul>
  </td>
</tr>
<tr>
  <td>Codici di uscita MSI</td>
  <td>
    <ul>
      <li><strong>0</strong> = successo; <strong>3010</strong> = successo con riavvio richiesto; <strong>1638</strong> = versione già installata.</li>
      <li>Tratta 3010 come successo e pianifica un riavvio; analizza il log MSI per dettagli.</li>
    </ul>
  </td>
</tr>

Diagnostica mirata: cosa controllare, in ordine

  1. Il GPO si applica al computer?
    gpresult /scope computer /v oppure gpresult /h C:\temp\gpresult.html e cerca Deploy Wazuh in Applied GPOs.
  2. Event Log della GPO: filtra gli eventi della sorgente GroupPolicy nel canale Operational cercando “Script” o il nome del tuo file.
  3. Log dell’installer: apri %windir%\Temp\WazuhAgentInstall.log e cerca stringhe come Return value 3 (fallimento in MSI).
  4. Servizio e registro installazioni:
    • Get-Service WazuhSvc deve essere Running.
    • Registro: HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall (e su OS 64 bit anche la chiave WOW6432Node) → voce “Wazuh Agent”.
  5. Connettività verso il Manager: test ICMP/DNS e porte in uscita (1514/1515). Se usi proxy o segmentazioni, valuta una regola firewall specifica.

Hardening e sicurezza dello script

  • Firma dei PowerShell script: se la tua policy esige AllSigned, firma il file con un certificato interno e distribuisci il certificato radice ai client.
  • Permessi su SYSVOL: lascia Authenticated Users in sola lettura. Non concedere scrittura agli oggetti computer.
  • Protezione dei segreti: evita di salvare token o password in chiaro. Se devi usare una registration password, valuta di estrarla da una variabile d’ambiente del computer o da una chiave di registro protetta dal GPO al momento dell’applicazione.

Gestione del ciclo di vita: aggiornare l’agente

Per aggiornare gli endpoint mantenendo la stessa architettura:

  1. Rimpiazza il file MSI nella cartella dello script in SYSVOL con la nuova versione.
  2. Aggiungi al comando di installazione i parametri di reinstall se vuoi forzare l’upgrade anche dove l’agente è già presente: msiexec /i wazuh-agent-x.y.z.msi REINSTALL=ALL REINSTALLMODE=vomus /qn /norestart /l*v %windir%\Temp\WazuhAgentUpgrade.log
  3. In alternativa, incrementa il ProductCode (gestito dal vendor) e lascia che l’installatore effettui un upgrade in-place. Per forzare una reinstallazione “pulita” puoi rimuovere l’agente precedente nello script e poi installare la nuova versione.

Alternative alla GPO + script

  • Wazuh Deployment Service (per AD): semplifica il rollout massivo integrandosi con il dominio.
  • Ansible/WinRM: adatto a orchestrazioni ripetibili e multi‑dominio.
  • SCCM / Microsoft Intune: distribuzione con reporting avanzato, rings di rollout, gestione riavvii e dipendenze.

Checklist operativa

  • OU dedicata e computer spostati correttamente.
  • GPO Deploy Wazuh creato e linkato all’OU corretta.
  • Script e (opzionalmente) MSI copiati in \\DOMINIO\SYSVOL\DOMINIO\Policies\{GUID_GPO}\Machine\Scripts\Startup.
  • Startup Script configurato in Computer Configuration, non in User Configuration.
  • Policy “Always wait for the network…” abilitata; PowerShell abilitato (se usi .ps1); 64‑bit PowerShell su OS 64 bit.
  • Firewall: porte verso il Manager consentite.
  • Verifica: gpupdate /force, Event Viewer → GroupPolicy/Operational, stato del servizio WazuhSvc, log MSI.

FAQ rapida

Posso lasciare l’MSI in una share diversa da SYSVOL?
È possibile, ma sconsigliato: rischi problemi di ACL, latenza e disponibilità all’avvio. Tenere script e pacchetto nel percorso del GPO in SYSVOL è più affidabile.

Meglio .bat o .ps1?
Entrambi vanno bene. PowerShell offre migliore gestione degli errori e logging; .bat è più semplice e non richiede policy aggiuntive se non usi PowerShell.

Perché l’installazione parte solo dopo più riavvii?
Alla prima applicazione alcune dipendenze (replica del GPO, cache CSE, rete) possono non essere pronte. Abilitare “Always wait for the network…” riduce questa evenienza; in ambienti lenti può servire un secondo riavvio.

Come verifico velocemente se l’agente è registrato?
Controlla lo stato del servizio e i log del client; inoltre il Manager dovrebbe mostrare l’endpoint tra gli agenti connessi. Se usi registrazione con password, verifica che il valore sia corretto e che la porta di enrollment sia raggiungibile.


Riepilogo finale

La chiave per distribuire Wazuh Agent con GPO senza toccare l’MSI sta in tre scelte: 1) mettere script (e pacchetto) nel SYSVOL del GPO; 2) impostare correttamente Startup Script e le opzioni di rete/ordine esecuzione; 3) adottare script idempotenti e con logging per avere diagnosi rapide e rollout ripetibili. Seguendo i passaggi e gli esempi forniti, al riavvio ogni endpoint della OU eseguirà lo script, installerà in silenzioso l’agente, lo registrerà presso il Wazuh Manager e avvierà il servizio automaticamente.


Esempio di procedura “one‑page” (copiabile)

  1. Crea OU “Workstations‑Wazuh” e spostaci i PC target.
  2. Crea GPO “Deploy Wazuh” e annota {GUID_GPO}.
  3. Copia Deploy-Wazuh-Agent.bat e wazuh-agent-4.7.1.msi in \\DOMINIO\SYSVOL\DOMINIO\Policies\{GUID_GPO}\Machine\Scripts\Startup.
  4. Nel GPO: Computer Configuration → Windows Settings → Scripts → StartupAdd… → seleziona lo script.
  5. Abilita: Always wait for the network at computer startup and logon.
  6. Linka il GPO all’OU.
  7. Sul client: gpupdate /force e riavvio; conferma in Event Viewer e verifica WazuhSvc.

Appendice: snippet utili

Verificare GPO applicati

gpresult /scope computer /h C:\temp\gpresult.html
start C:\temp\gpresult.html

Controllare stato del servizio agent

Get-Service -Name WazuhSvc | Format-List Name, Status, StartType

Forzare reinstallazione completa (attenzione: sovrascrive l’installazione)

msiexec /i wazuh-agent-x.y.z.msi REINSTALL=ALL REINSTALLMODE=vomus /qn /norestart /l*v %windir%\Temp\WazuhAgentReinstall.log

Creare una regola firewall in uscita (se necessaria)

New-NetFirewallRule -DisplayName "Wazuh Outbound 1514 UDP" -Direction Outbound -Action Allow -Protocol UDP -RemotePort 1514
New-NetFirewallRule -DisplayName "Wazuh Outbound 1515 TCP" -Direction Outbound -Action Allow -Protocol TCP -RemotePort 1515

Conclusione

Con una singola GPO, uno startup script ben scritto e alcune impostazioni mirate (rete, PowerShell, sincronia), la distribuzione di Wazuh Agent diventa un’operazione safe‑by‑default, ripetibile e facilmente monitorabile. Mantieni la stessa struttura anche per gli aggiornamenti: sostituisci l’MSI, aggiorna lo script e lascia che i client facciano il resto al primo riavvio utile.

Indice