Déploiement centralisé de l’agent Wazuh sur Windows 10/11 via Active Directory (GPO) : guide complet, scripts et dépannage

Objectif : déployer automatiquement et de façon fiable l’agent Wazuh sur Windows 10/11 via GPO, sans orca.exe, avec des scripts idempotents, une journalisation claire et des pistes de dépannage concrètes.

Déploiement centralisé de l’agent Wazuh sur postes Windows via Active Directory

Vue d’ensemble de la question

Une administratrice AD souhaite installer automatiquement l’agent Wazuh sur des postes Windows 10/11 depuis un contrôleur de domaine 2022, sans recourir à orca.exe. Un script d’initialisation (Startup) placé dans un partage réseau a été testé avec succès en exécution manuelle mais ne se déclenche pas lorsqu’il est déployé par GPO.

Principes clés à retenir

• Les scripts Startup s’exécutent avant l’ouverture de session, sous le compte LocalSystem, et exigent l’accès réseau à SYSVOL ou à un partage UNC lisible par le compte machine (Domain Computers).
• La synchronisation réseau au démarrage doit être forcée pour que l’ordinateur reçoive et applique la GPO (réglage « Always wait for the network… »).
• Utilisez une commande MSI silencieuse (ligne msiexec) plutôt que la transformation MSI (MST) pour injecter les paramètres du manager Wazuh : pas besoin d’orca.exe.
• Privilégiez des scripts idempotents : ils détectent une installation existante, journalisent, et ne réinstallent pas inutilement.

Solutions proposées et bonnes pratiques

Étape	Action essentielle	Détails / Paramètres critiques
1	Créer une OU dédiée	Déplacer toutes les machines cibles dans cette unité d’organisation.
2	Créer un GPO “Déploiement Wazuh”	Conserver l’ID GUID généré automatiquement ; il définit l’arborescence Sysvol où seront stockés scripts et fichiers.
3	Copier le script et le MSI dans Sysvol	Chemin type : \\domaine.tld\SysVol\domaine.tld\Policies\{GUID}\Machine\Scripts\Startup\. Veiller à : • Droits lecture/exec pour « Domain Computers » • Nom de fichier court sans espaces (ex. install_wazuh.cmd).
4	Déclarer le script dans la GPO	Configuration ordinateur ➜ Stratégies ➜ Paramètres Windows ➜ Scripts (Startup/Shutdown) ➜ Startup ➜ Ajouter.
5	Utiliser un appel silencieux de MSI	Exemple de ligne : msiexec /i wazuh-agent-4.7.4.msi /qn WAZUH_MANAGER="10.0.0.5" WAZUH_REGISTRATION_SERVER="10.0.0.5" /norestart /log %SystemRoot%\Temp\wazuh_gpo.log
6	Forcer l’attente réseau au démarrage	Activer : Computer Configuration ➜ Policies ➜ Admin Templates ➜ System ➜ Logon ➜ Always wait for the network... = Enabled.
7	Vérifier l’application	• gpupdate /force puis 2–3 redémarrages • Consulter C:\Windows\Temp\wazuh_gpo.log et l’observateur d’évènements (Event ID = 7035/7036).

Pré-requis techniques

• Contrôleur(s) de domaine Windows Server 2022 (SYSVOL sous DFS-R). Uptime et réplication stables.
• Ports ouverts vers le manager Wazuh : 1514/tcp (événements) et 1515/tcp (enregistrement), ou vos ports personnalisés.
• Droits NTFS sur le dossier de la GPO pour Domain Computers (lecture/exécution).
• Nom de fichier MSI sans espaces ni caractères spéciaux, placé avec le script dans le dossier Startup du GUID de la GPO.
• Éviter les lecteurs mappés (X:, Y:, …) dans un script Startup : utiliser UNC ou %~dp0.

Script Startup idempotent (recommandé)

Le script ci-dessous installe l’agent s’il n’est pas présent, journalise chaque étape, gère les codes de retour MSI et démarre le service. À placer dans Machine\Scripts\Startup du GPO, et à appeler via « Scripts (Startup) ».

@echo off
setlocal enabledelayedexpansion

rem === Paramètres à adapter ===
set "MSI_NAME=wazuh-agent-4.7.4.msi"
set "WAZUH_MANAGER=10.0.0.5"
set "WAZUH_REG_SERVER=10.0.0.5"
rem Optionnel : set "WAZUH_GROUP=Windows"
rem Optionnel : set "WAZUH_REG_PASSWORD=<TOKEN>"

rem === Journalisation ===
set "LOGFILE=%SystemRoot%\Temp\wazuh_gpo.log"
echo ==== [%date% %time%] Démarrage du script Startup Wazuh ==== >> "%LOGFILE%"

rem === Détection du service existant ===
sc query Wazuh >nul 2>&1
if %errorlevel%==0 (
  echo Wazuh déjà présent, sortie sans réinstaller. >> "%LOGFILE%"
  goto :END
)

rem === Résolution du chemin MSI (même dossier que le script) ===
set "SCRIPT_DIR=%~dp0"
set "MSI_PATH=%SCRIPT_DIR%%MSI_NAME%"
if not exist "%MSI_PATH%" (
  echo ERREUR : MSI introuvable : "%MSI_PATH%" >> "%LOGFILE%"
  goto :END
)

rem === Construction de la ligne msiexec silencieuse ===
set "ARGS=/i "%MSI_PATH%" /qn WAZUH_MANAGER="%WAZUH_MANAGER%" WAZUH_REGISTRATION_SERVER="%WAZUH_REG_SERVER%" /norestart /log %SystemRoot%\Temp\wazuh_msi.log"
if defined WAZUH_GROUP set "ARGS=%ARGS% WAZUH_AGENT_GROUP="%WAZUH_GROUP%""
if defined WAZUH_REG_PASSWORD set "ARGS=%ARGS% WAZUH_REGISTRATION_PASSWORD="%WAZUH_REG_PASSWORD%""

echo Exécution : msiexec %ARGS% >> "%LOGFILE%"
start /wait msiexec %ARGS%
set "RC=%ERRORLEVEL%"
echo Code de retour MSI : %RC% >> "%LOGFILE%"

if "%RC%"=="0" (
  echo Installation réussie. >> "%LOGFILE%"
) else if "%RC%"=="3010" (
  echo Installation OK - redémarrage requis (3010). >> "%LOGFILE%"
) else (
  echo ECHEC : msiexec a retourné %RC%. Voir wazuh_msi.log. >> "%LOGFILE%"
  goto :END
)

rem === Mise en automatique et démarrage du service ===
sc config Wazuh start= auto >> "%LOGFILE%" 2>&1
sc start Wazuh >> "%LOGFILE%" 2>&1
timeout /t 5 >nul
sc query Wazuh >> "%LOGFILE%" 2>&1

:END
echo ==== [%date% %time%] Fin du script Startup Wazuh ==== >> "%LOGFILE%"
endlocal

Pourquoi ce script fonctionne-t-il mieux qu’un simple appel MSI ?

• Il est idempotent : aucune réinstallation si le service existe déjà.
• La journalisation distingue l’exécution du script (wazuh_gpo.log) de celle du MSI (wazuh_msi.log).
• %~dp0 garantit un chemin valide sans dépendre d’une lettre de lecteur.
• start /wait force la GPO à attendre la fin de msiexec avant de poursuivre.

Paramètres MSI utiles pour Wazuh

Pas besoin d’orca.exe : tous les paramètres d’enregistrement (adresse du manager, clé d’authentification, labels, groupes) peuvent être passés en ligne de commande MSI, par exemple :

WAZUH_MANAGER="<IP ou FQDN>" WAZUH_AGENT_GROUP="Windows" WAZUH_REGISTRATION_PASSWORD="<TOKEN>"

Bonnes pratiques :

• Utiliser des adresses IP (ou un FQDN résolu par le client via DNS) pour WAZUH_MANAGER et WAZUH_REGISTRATION_SERVER.
• Si un proxy réseau est requis pour l’enregistrement, préparez l’environnement sur le poste (variables système ou configuration locale) avant l’installation.
• Évitez de stocker le token en clair dans des objets « Preferences » GPO (risque d’exposition). Préférez des tokens à durée de vie courte, et faites tourner les secrets.

Renforcer la fiabilité côté GPO

• Traitement synchrone : activez « Always wait for the network… » afin d’éviter le démarrage sans réseau.
• Filtrage de sécurité : appliquez la GPO aux groupes Domain Computers (lecture & appliquer) et à l’OU cible. Retirez les entités inutiles.
• Filtre WMI (optionnel) pour circonscrire aux OS pris en charge : Windows 10/11.

Exemple de filtre WMI (Windows 10/11)

SELECT * FROM Win32_OperatingSystem
WHERE Version LIKE "10.%" OR Version LIKE "11.%"

Vérifications et suivi après déploiement

• Forcer la stratégie : gpupdate /force puis redémarrer 2–3 fois les premières machines pilotes.
• Rapport d’application : gpresult /h %TEMP%\gp.html pour vérifier le lien de la GPO et l’exécution des scripts d’ordinateur.
• Journaux : C:\Windows\Temp\wazuh_gpo.log (script), C:\Windows\Temp\wazuh_msi.log (MSI).
• Event Viewer : « Service Control Manager » (IDs 7035/7036 pour le service Wazuh) et « GroupPolicy/Operational » pour le traitement des scripts d’ordinateur.

Astuces de dépannage

• Accessibilité UNC : ouvrir manuellement \\domaine.tld\SysVol\... depuis un poste client pour valider les droits.
• Format du script : préférer .cmd ou .bat; éviter PowerShell si la stratégie d’exécution n’est pas déjà libérale.
• Connexion au gestionnaire : tester telnet <manager> 1514 (ou le port choisi) pour exclure un blocage pare-feu.
• Journalisation MSI : ajouter /log pour tracer chaque installation.
• Replication SYSVOL : attendez la fin de la réplication DFS-R (sinon, les DC secondaires servent un dossier incomplet). Un simple délai peut expliquer l’échec initial.
• Chemins et noms : bannissez les espaces et caractères accentués dans les noms de scripts/MSI.
• Temps maximum des scripts : si nécessaire, augmentez le délai d’attente des scripts d’ordinateur (stratégies système) pour couvrir des MSI volumineux.
• Contexte d’exécution : souvenez‑vous que LocalSystem n’a pas de profil utilisateur – ne comptez pas sur des variables utilisateur ou sur des lecteurs mappés.

Alternatives si le Startup Script reste inopérant

Méthode	Avantages	Points d’attention
Software Installation GPO (assignation de packages MSI)	Interface graphique, suivi intégré	Fonctionne seulement si le partage Sysvol accepte les gros MSI (> 10 Mo) ; nécessite plusieurs redémarrages.
Intune ou Microsoft Endpoint Configuration Manager	Tableaux de bord et reporting	Environnement sous licence ; latence de réplication cloud.
PowerShell Remoting / PSExec	Contrôle granulaire, logs détaillés	Doit être lancé depuis un poste ayant des droits d’administration sur l’ensemble du parc.
Script de connexion (Logon)	S’exécute à chaque ouverture de session	Ne couvre pas les machines qui restent allumées sans reconnecter d’utilisateur.

Modèle de déploiement « GPP + Script local » (robuste pour gros parcs)

Dans certains environnements, copier d’abord le MSI sur le disque local puis l’installer améliore la stabilité :

1. GPP > Files : copiez wazuh-agent-*.msi depuis SYSVOL vers %ProgramData%\WazuhDeploy\wazuh-agent.msi.
2. GPP > Scheduled Tasks : créez une tâche planifiée « À l’amorçage », s’exécutant sous SYSTEM, qui lance un .cmd local (voir plus bas) si le service « Wazuh » est absent.
3. Item-level targeting : ciblez seulement les postes de l’OU et/ou un groupe AD dédié pour lisser la charge réseau.

Exemple de script local (avec MSI déjà copié)

@echo off
set "MSI_LOCAL=%ProgramData%\WazuhDeploy\wazuh-agent.msi"
if not exist "%MSI_LOCAL%" exit /b 0
sc query Wazuh >nul 2>&1 & if %errorlevel%==0 exit /b 0
msiexec /i "%MSI_LOCAL%" /qn WAZUH_MANAGER="10.0.0.5" WAZUH_REGISTRATION_SERVER="10.0.0.5" /norestart /log %SystemRoot%\Temp\wazuh_local.log

Performance et échelonnage

• Évitez les vagues massives : déployez par sous‑OU, par sites AD ou via un filtrage WMI (ex. machines allumées depuis > 7 jours) pour lisser le trafic.
• Cache local : la copie préalable du MSI (GPP « Files ») puis l’installation locale réduit les aléas réseau.
• Réplication DC : attendez la propagation de la GPO sur tous les contrôleurs avant un déploiement global.

Sécurité

• Hébergez le MSI dans SYSVOL ou un partage DFS-R avec autorisations NTFS en lecture seule pour Domain Computers.
• N’exposez pas des secrets durables (tokens, clés) dans des préférences GPO. Préférez des secrets jetables et renouvelez‑les.
• Consignez l’installation dans %SystemRoot%\Temp (accès administrateur requis) pour éviter de divulguer des informations dans des dossiers ouverts aux utilisateurs.

Mises à jour et maintenance

• Après installation, l’agent Wazuh peut être mis à jour de façon centralisée via le module agent_upgrade du manager, ou par la même méthode GPO avec un nouvel MSI (msiexec /i ... qui fera une mise à niveau).
• Pour un correctif urgent, réutilisez la GPO existante en remplaçant le MSI et en incrémentant le nom (afin d’éviter toute ambiguïté de cache).

Checklist de validation

• La machine cible est dans l’OU associée au GPO.
• La GPO est liée, activée, et non filtrée par un autre héritage.
• Le dossier Machine\Scripts\Startup contient install_wazuh.cmd et le .msi attendu.
• Les droits NTFS sur SYSVOL incluent Domain Computers en lecture/exécution.
• Le paramètre Always wait for the network… est activé.
• Les ports 1514/1515 (ou personnalisés) sont ouverts vers le manager Wazuh.
• wazuh_gpo.log et wazuh_msi.log montrent un return code 0 ou 3010.
• Le service Wazuh est en Running et Automatic.

FAQ rapide

Pourquoi mon script marche en manuel mais pas via GPO ?
Parce qu’en manuel il s’exécute sous le contexte utilisateur, avec ses mappages et son profil. En Startup, il tourne sous LocalSystem avant logon : sans « Always wait for the network… », sans accès UNC valide, ou sans droits machine, il échoue silencieusement.

Faut‑il orca.exe pour paramétrer l’agent ?
Non. Les propriétés MSI (WAZUH_MANAGER, WAZUH_REGISTRATION_SERVER, WAZUH_REGISTRATION_PASSWORD, WAZUH_AGENT_GROUP, etc.) suffisent via msiexec.

Comment cibler uniquement Windows 10/11 ?
Ajoutez un filtre WMI (voir l’exemple ci‑dessus) sur la GPO.

Mon MSI est volumineux, SYSVOL suffit‑il ?
SYSVOL fonctionne mais peut ralentir la réplication. Pour de très gros fichiers, envisagez un partage DFS-R dédié + GPP « Files » pour copier localement puis installer.

Informations complémentaires utiles

• Pas besoin d’orca.exe : tous les paramètres d’enregistrement (adresse du manager, clé d’authentification, labels, groupes) peuvent être passés en ligne de commande MSI, par exemple : WAZUH_MANAGER="<IP>" WAZUH_AGENT_GROUP="Windows" WAZUH_REGISTRATION_PASSWORD="<TOKEN>".
• Sécurité : hébergez le MSI dans un répertoire Sysvol ou un partage DFS-R avec autorisations NTFS en lecture seule pour éviter toute altération malveillante.
• Performances : pour un parc important, décalez l’installation en affectant plusieurs OU avec des GPO identiques mais un filtrage temporel (WMI filter ou item-level targeting) pour lisser la charge réseau.
• Mises à jour : après installation, l’agent Wazuh peut être mis à jour de façon centralisée via le module agent_upgrade du manager ou par la même méthode GPO avec un nouvel MSI.

Résumé exécutable

1. Créez une OU dédiée et déplacez‑y les machines cibles.
2. Créez une GPO “Déploiement Wazuh” et notez son GUID.
3. Copiez install_wazuh.cmd et le .msi dans \\<domaine>\SysVol\<domaine>\Policies\{GUID}\Machine\Scripts\Startup\.
4. Ajoutez le script dans Configuration ordinateur → Scripts (Startup).
5. Activez Always wait for the network….
6. Forcez gpupdate /force, redémarrez plusieurs fois un groupe pilote, validez avec gpresult et les logs.
7. Généralisez par lots (sous‑OU, filtres WMI) pour lisser la charge.

---

Annexe : variante PowerShell (si l’exécution est autorisée)

Si votre stratégie le permet (ExecutionPolicy adaptée via GPO), voici une alternative PowerShell équivalente :

param(
  [string]$Manager = "10.0.0.5",
  [string]$RegServer = "10.0.0.5",
  [string]$MsiName = "wazuh-agent-4.7.4.msi",
  [string]$Group = "Windows",
  [string]$Token = ""
)

\$Log = "\$env\:SystemRoot\Temp\wazuh\_gpo\_ps.log"
"==== \$(Get-Date) Démarrage PS ====" | Out-File -FilePath \$Log -Append -Encoding utf8

\$svc = Get-Service -Name "Wazuh" -ErrorAction SilentlyContinue
if (\$svc) {
"Wazuh déjà présent, sortie." | Out-File \$Log -Append
exit 0
}

\$scriptDir = Split-Path -Parent \$MyInvocation.MyCommand.Path
\$msiPath = Join-Path \$scriptDir \$MsiName
if (-not (Test-Path \$msiPath)) {
"ERREUR : MSI introuvable : \$msiPath" | Out-File \$Log -Append
exit 1
}

\$args = @(
"/i `"$msiPath`"",
"/qn",
"WAZUH\_MANAGER=`"$Manager`"",
"WAZUH\_REGISTRATION\_SERVER=`"$RegServer`"",
"/norestart",
"/log \$env\:SystemRoot\Temp\wazuh\_msi\_ps.log"
)
if (\$Group) { \$args += "WAZUH\_AGENT\_GROUP=`"$Group`"" }
if (\$Token) { \$args += "WAZUH\_REGISTRATION\_PASSWORD=`"$Token`"" }

"Exécution : msiexec \$(\$args -join ' ')" | Out-File \$Log -Append
\$p = Start-Process -FilePath "msiexec.exe" -ArgumentList \$args -Wait -PassThru
"Code de retour : \$(\$p.ExitCode)" | Out-File \$Log -Append

if (\$p.ExitCode -in 0, 3010) {
Set-Service -Name "Wazuh" -StartupType Automatic -ErrorAction SilentlyContinue
Start-Service -Name "Wazuh" -ErrorAction SilentlyContinue
"Installation OK." | Out-File \$Log -Append
} else {
"ECHEC MSI : \$(\$p.ExitCode)" | Out-File \$Log -Append
exit \$p.ExitCode
}

"==== \$(Get-Date) Fin PS ====" | Out-File \$Log -Append 

---

Conclusion

Avec un script Startup idempotent, des paramètres MSI passés en ligne de commande et une GPO correctement structurée (dossier SYSVOL du GUID + « Always wait for the network »), le déploiement centralisé de l’agent Wazuh devient prévisible, reproductible et exempt d’outils annexes. En cas d’aléas (réplication, réseau, restrictions d’exécution), les variantes « GPP + tâche planifiée » ou « Software Installation GPO » fournissent des solutions de secours robustes. Enfin, veillez à la sécurité (droits NTFS, secrets à durée de vie courte) et à la scalabilité (déploiement par vagues, caches locaux) pour accompagner la croissance de votre parc.