Configuration du proxy sur l'agent serveur

L'agent serveur Kabeen transmet ses données au backend via gRPC sur TLS, vers intake.kabeen.io sur le port sortant 443/TCP uniquement. Lorsque le serveur ne dispose pas d'un accès Internet direct et doit passer par un proxy d'entreprise (Zscaler, Squid, …), trois modes de fonctionnement sont possibles. Cet article décrit chacun d'eux.

Rappel. L'agent relit son fichier config.toml automatiquement toutes les 10 secondes : aucune modification de configuration n'exige de redémarrer le service. Seul l'import d'un certificat dans le magasin de confiance du système nécessite un redémarrage (pour le faire relire au démarrage).

Choisir le bon mode

Mode transparent (interception TLS / MITM)

C'est le mode par défaut de Zscaler ZIA / ZTNA lorsque le trafic est routé au niveau réseau. Aucune configuration proxy n'est requise côté agent.

La seule contrainte est que le certificat racine d'inspection de votre proxy soit présent dans le magasin de confiance du système d'exploitation. L'agent lit ce magasin au démarrage.

Linux (Debian / Ubuntu) :

sudo cp zscaler-root.crt /usr/local/share/ca-certificates/zscaler-root.crt
sudo update-ca-certificates
sudo systemctl restart kabeen-server-agent.service

Linux (RHEL / Rocky / Alma) :

sudo cp zscaler-root.crt /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust
sudo systemctl restart kabeen-server-agent.service

Windows (PowerShell administrateur) :

Import-Certificate -FilePath C:\Temp\zscaler-root.cer `
    -CertStoreLocation Cert:\LocalMachine\Root
Restart-Service KabeenServerAgent

Le redémarrage n'est nécessaire que pour faire relire le magasin de confiance : l'agent ne le relit pas à chaud.

Mode explicite (HTTP CONNECT)

À utiliser lorsque le proxy doit être déclaré explicitement (pas de routage transparent). L'agent ouvre une connexion TCP vers le proxy, envoie une requête HTTP CONNECT intake.kabeen.io:443, puis négocie le TLS de bout en bout dans le tunnel établi.

Renseignez le champ proxy dans le fichier de configuration (/etc/kabeen-server-agent/config.toml sous Linux, C:\ProgramData\Kabeen\Server Agent\config.toml sous Windows) :

api_key = "VOTRE_CLÉ_API_KABEEN"
proxy   = "http://proxy.corp.example:8080"

Contraintes du champ proxy :

Limitations actuelles (non supportées). L'authentification proxy (Basic, NTLM, Kerberos), l'auto-configuration PAC / WPAD et les proxies SOCKS5 ne sont pas pris en charge.

Si votre proxy exige une authentification, deux contournements sont possibles :

1. créer une règle de bypass d'authentification sur le proxy pour l'IP source ou pour la destination intake.kabeen.io ;
2. déployer un proxy auxiliaire local non authentifié qui relaie vers le proxy d'entreprise (par exemple Squid avec cache_peer + login=).

Via les variables d'environnement

À défaut du champ proxy dans config.toml, l'agent respecte les variables d'environnement standard. Le champ config.toml reste prioritaire : s'il est présent, les variables d'environnement sont ignorées (y compris NO_PROXY).

• Les variantes majuscule et minuscule sont toutes deux acceptées.
• Le port peut être omis (80 pour http://, 443 pour https:// sont alors assumés).
• Format NO_PROXY : liste séparée par des virgules. Pour chaque entrée, le match se fait sur l'égalité exacte ou le suffixe — kabeen.io et .kabeen.io correspondent tous deux à intake.kabeen.io. La valeur * désactive le proxy partout.

Linux (systemd) :

sudo systemctl edit kabeen-server-agent.service

Ajouter (le drop-in crée /etc/systemd/system/kabeen-server-agent.service.d/override.conf) :

[Service]
Environment=HTTPS_PROXY=http://proxy.corp:8080
Environment=NO_PROXY=.internal,localhost,127.0.0.1

Puis recharger et redémarrer :

sudo systemctl daemon-reload
sudo systemctl restart kabeen-server-agent.service

Windows (PowerShell administrateur) :

[Environment]::SetEnvironmentVariable('HTTPS_PROXY', 'http://proxy.corp:8080', 'Machine')
[Environment]::SetEnvironmentVariable('NO_PROXY',    '.internal,localhost,127.0.0.1', 'Machine')
Restart-Service KabeenServerAgent

Utiliser obligatoirement la portée Machine. Les variables définies au niveau User ne sont pas visibles par un service qui s'exécute sous LocalSystem ou sous un compte virtuel NT SERVICE\….

Vérification

Après modification, le superviseur prend la nouvelle configuration en compte au tick suivant (≤ 10 s). Inspectez les journaux :

sudo journalctl -u kabeen-server-agent.service -f

Lignes attendues lorsque le proxy est utilisé :

Configuration changed, restarting tasks.
Connected to Kabeen endpoint: https://intake.kabeen.io via proxy http://proxy.corp.example:8080
All tasks running. Agent is operational.

ou, lorsqu'une entrée NO_PROXY correspond et que la connexion se fait en direct :

[proxy] target host 'intake.kabeen.io' matches NO_PROXY='.kabeen.io', going direct
Connected to Kabeen endpoint: https://intake.kabeen.io

Erreurs typiques (à corréler avec les journaux du proxy) :

Pour l'installation initiale et la configuration de la clé d'API, voir Installation manuelle de l'agent serveur.