Déployer la découverte

Nécessite @openlatch/client 0.11.12 ou une version ultérieure

Déployez la découverte une fois sur les machines que gère votre outil de gestion de parc. Chaque machine analyse ensuite dans la session de chaque utilisateur et, quand elle trouve un agent IA qu’OpenLatch connaît, installe et inscrit le client pour cet utilisateur. Découverte explique ce que fait une analyse et ce qu’elle enregistre.

Avant de commencer, vérifiez ces éléments :

#	Élément	D’où il vient
1	Une clé d’organisation créée depuis Host enrollment, conservée dans votre coffre de secrets	Settings › API keys, ou Generate key and fill dans Settings › Discovery, en tant qu’admin ou owner
2	Le slug ou l’identifiant de votre organisation	Settings › Discovery l’affiche quand il remplit la commande
3	Un outil de gestion de parc qui exécute un script avec le privilège système : Intune, Configuration Manager, Jamf Pro, Ansible, Salt ou équivalent	Votre équipe postes de travail
4	macOS, Linux avec systemd, ou Windows avec PowerShell 5.1 ou ultérieur	Les machines
5	Les flux sortants approuvés pour le client	Exigences réseau
6	Une notice à vos employés, là où vos représentants du personnel ou vos règles de protection des données en demandent une	La notice pour vos employés

Créer la clé de découverte

Ouvrez Settings › Discovery en tant qu’admin ou owner, et appuyez sur Generate key and fill.

Attendu : la commande affiche une nouvelle clé d’organisation et votre organisation, une seule fois. La clé porte la date du jour et ne peut rien faire d’autre qu’inscrire des hôtes.
Copiez la clé dans votre coffre de secrets avant de quitter la page. La page l’oublie quand vous la quittez ; la clé reste listée dans Settings › API keys, où vous pouvez la supprimer.

Vous pouvez aussi créer la clé vous-même dans Settings › API keys, depuis le préréglage Host enrollment. Une machine n’a besoin de la clé que pour s’inscrire : le client l’échange contre l’identifiant d’hôte propre à la machine et ne la stocke jamais, si bien que faire tourner ou supprimer la clé plus tard ne déconnecte aucune machine inscrite.

La clé sur chaque machine

La découverte écrit la clé et l’organisation dans un fichier de clé sur chaque machine, pour que l’analyse de chaque utilisateur puisse inscrire le client de cet utilisateur. Chaque utilisateur de la machine peut lire ce fichier, car chaque analyse s’exécute au nom de son utilisateur. Qui le lit peut inscrire des hôtes dans votre organisation, et rien d’autre : la clé ne détient aucune autre permission, ne lit aucune donnée et ne peut pas agir sur un agent. Considérez-la comme partagée au sein de la machine, donnez à la découverte une clé qui lui est propre, et faites-la tourner quand une personne qui la détenait s’en va.

Essayer sur une machine

Exécutez la commande de Settings › Discovery sur une machine de chaque système d’exploitation avant de déployer une vague. Avec sudo, ou dans un PowerShell élevé, la commande déploie la découverte pour chaque utilisateur de cette machine.

Sous macOS et Linux :

curl -LsSf https://openlatch.ai/discover.sh | sudo OPENLATCH_API_KEY=<api-key> OPENLATCH_ORG=<org> sh

Sous Windows, dans un PowerShell élevé, saisissez la clé et l’organisation dans la session, puis exécutez le script :

$env:OPENLATCH_API_KEY='<api-key>'; $env:OPENLATCH_ORG='<org>'
irm https://openlatch.ai/discover.ps1 | iex

Sans sudo ni élévation, la même commande déploie la découverte pour l’utilisateur courant seulement, sans droits d’administrateur. Cela convient pour un essai sur votre propre machine :

curl -LsSf https://openlatch.ai/discover.sh | OPENLATCH_API_KEY=<api-key> OPENLATCH_ORG=<org> sh

$env:OPENLATCH_API_KEY='<api-key>'; $env:OPENLATCH_ORG='<org>'
powershell -ExecutionPolicy Bypass -c "irm https://openlatch.ai/discover.ps1 | iex"

Un déploiement par tube télécharge à nouveau son propre fichier de version et installe cette copie. Sous macOS et Linux, il compare d’abord la copie au SHA-256 publié et n’installe rien quand ils diffèrent. Pour voir ce que l’analyse trouverait sans rien installer, ajoutez —dry-run au script, ou -DryRun sous Windows.

Vérifier le script avant de le déployer

Les deux scripts sont du texte brut, servis pour être lus. Pour le script macOS et Linux, OpenLatch publie le SHA-256 de chaque version. Vérifiez le fichier que vous déployez :

curl -LsSfO https://openlatch.ai/discover.sh
curl -LsSf https://openlatch.ai/discover.sh.sha256 | shasum -a 256 -c -

Sous Linux, sha256sum -c fonctionne de la même façon. Un fichier qui ne correspond pas n’est pas celui qu’OpenLatch a publié : ne le déployez pas. Aucune empreinte n’est publiée pour le script Windows.

Ce que le déploiement change sur une machine

Le déploiement copie le script, écrit le fichier de clé et enregistre une planification. Il n’analyse jamais et n’écrit jamais dans le dossier personnel d’un utilisateur.

Élément	Linux	macOS	Windows
Copie locale du script, dans un dossier que seuls les administrateurs peuvent modifier	/usr/local/lib/openlatch/discovery/discover.sh	/Library/Application Support/OpenLatch/Discovery/discover.sh	C:\Program Files\OpenLatch\Discovery\discover.ps1
Fichier de clé, lisible par les utilisateurs de la machine	/etc/openlatch/discovery.key	/Library/Application Support/OpenLatch/Discovery/discovery.key	C:\ProgramData\OpenLatch\Discovery\discovery.key
Planification, une pour tous les utilisateurs	Le minuteur utilisateur systemd openlatch-discovery.timer, activé pour chaque utilisateur	Le LaunchAgent ai.openlatch.discovery	La tâche planifiée OpenLatch Discovery, exécutée pour le groupe Users
Résultats d’analyse et journal de chaque utilisateur	~/.local/share/openlatch-discovery/	~/Library/Application Support/OpenLatch Discovery/	%LOCALAPPDATA%\OpenLatch\Discovery\

Un déploiement pour l’utilisateur seul conserve sa copie, son fichier de clé et sa planification dans le dossier de découverte de cet utilisateur.

Le script accepte ces options. Les formes pour l’outil de gestion de parc passent la clé et l’organisation par l’environnement ou un fichier de clé, jamais en ligne de commande :

sh discover.sh [--api-key-file <path>] [--interval <seconds>] [--dry-run] [--uninstall] [--scan-once]
powershell.exe -NoProfile -ExecutionPolicy Bypass -File discover.ps1 [-ApiKeyFile <path>] [-Interval <seconds>] [-DryRun] [-Uninstall] [-ScanOnce]

Option	Effet
—api-key-file, -ApiKeyFile	Un fichier qui contient la clé et l’organisation, une ligne chacune : OPENLATCH_API_KEY=… et OPENLATCH_ORG=…
—interval, -Interval	L’intervalle d’analyse en secondes, 86400 par défaut. Changez-le en déployant à nouveau avec une autre valeur
—dry-run, -DryRun	Détecter et journaliser seulement : ne rien installer, inscrire ni enregistrer
—uninstall, -Uninstall	Retirer la planification, la copie locale et le fichier de clé. Chaque client inscrit reste
—scan-once, -ScanOnce	Une analyse dans le contexte courant, sans planification : pour les conteneurs et les tests

Déployer sur un parc

Ces recettes déploient la découverte. Pour installer vous-même le client sur chaque machine, utilisez plutôt les recettes de Déployer le client.

Chaque recette suit les mêmes règles :

Règle	Ce qu’elle signifie
Exécuter avec le privilège système	En root sous macOS et Linux, en SYSTEM sous Windows. Le déploiement enregistre la planification pour chaque utilisateur ; les analyses elles-mêmes s’exécutent au nom de chaque utilisateur
Déployer le fichier du script	Le garder exactement tel que publié, sans jamais l’envelopper ni le modifier
Prendre la clé d’un canal secret	La clé atteint le script par l’environnement ou un fichier de clé, jamais par une ligne de commande ni par un corps de script que votre outil montre à d’autres
Lire le rapport d’exécution	Le rapport de chaque exécution de votre outil de gestion de parc est l’endroit où vous voyez les machines qui ont exécuté le script sans rien trouver

Essayez chaque recette sur un appareil avant la vague. Déployez-la ensuite à nouveau chaque fois que vous voulez changer l’intervalle ou livrer une nouvelle version du script : d’ici là, la planification continue d’exécuter la copie déjà présente sur la machine.

Microsoft Intune

Ajoutez un script de plateforme qui s’exécute en SYSTEM. Il télécharge le script, écrit un fichier de clé depuis votre coffre de secrets, puis déploie :

# Intune platform script, run as SYSTEM.
$ErrorActionPreference = "Stop"

$dir = Join-Path $env:ProgramData "OpenLatch\Deploy"
New-Item -ItemType Directory -Path $dir -Force | Out-Null
$script = Join-Path $dir "discover.ps1"
Invoke-WebRequest -UseBasicParsing -Uri "https://openlatch.ai/discover.ps1" -OutFile $script

# Replace this call with the one your secret store provides.
$key = Get-DiscoveryKeyFromSecretStore
$keyFile = Join-Path $dir "discovery.key"
Set-Content -Path $keyFile -Value @("OPENLATCH_API_KEY=$key", "OPENLATCH_ORG=<org>")

powershell.exe -NoProfile -ExecutionPolicy Bypass -File $script -ApiKeyFile $keyFile
$status = $LASTEXITCODE
Remove-Item $keyFile -ErrorAction SilentlyContinue
exit $status

Paramètre	Valeur
Run this script using the logged on credentials	No, pour qu’il s’exécute en SYSTEM
Enforce script signature check	No
Run script in 64 bit PowerShell Host	Yes
Affectation	Un groupe d’appareils

Le corps du script est lisible par quiconque peut lire la stratégie, c’est pourquoi il va chercher la clé au lieu de la contenir.

Microsoft Configuration Manager

Enregistrez le script Intune ci-dessus sous le nom deploy-discovery.ps1, faites-en le contenu d’un package ou d’une application, et déployez-le avec ces paramètres :

Paramètre	Valeur
Ligne de commande	powershell.exe -NoProfile -ExecutionPolicy Bypass -File deploy-discovery.ps1
Exécution	Qu’un utilisateur soit connecté ou non, avec des droits d’administration
Déploiement	Obligatoire, vers un regroupement d’appareils

L’état du déploiement de chaque appareil est votre rapport d’exécution.

Jamf Pro

Une stratégie Jamf exécute ses scripts en root, ce dont le déploiement a besoin. Le script récupère la clé dans votre coffre de secrets et l’écrit dans un fichier de clé que seul root peut lire. Ne passez jamais la clé en paramètre de la stratégie : Jamf transmet les paramètres au script sur sa ligne de commande.

#!/bin/zsh
# Jamf Pro policy script, run as root.
set -eu

work=$(mktemp -d /tmp/openlatch-discovery.XXXXXX)
trap 'rm -rf "$work"' EXIT
cd "$work"

curl -LsSfO https://openlatch.ai/discover.sh
curl -LsSf https://openlatch.ai/discover.sh.sha256 | shasum -a 256 -c -

# Replace this call with the one your secret store provides.
key=$(get-discovery-key-from-secret-store)

umask 077
print -r -- "OPENLATCH_API_KEY=$key" > discovery.key
print -r -- "OPENLATCH_ORG=<org>" >> discovery.key

sh discover.sh --api-key-file "$work/discovery.key"

Réglez l’Execution Frequency de la stratégie sur Once per computer, et exécutez-la à nouveau quand vous changez l’intervalle ou le script.

Sous macOS 13 et ultérieur, un nouvel élément d’arrière-plan amène le système à demander à l’utilisateur de l’approuver. Pour éviter la demande, ajoutez un profil de configuration avec une charge utile Managed Login Items contenant une règle : Rule Type Label, Rule Value ai.openlatch.discovery. Avec cette charge utile, l’élément est approuvé et l’utilisateur peut voir une notice indiquant que des éléments gérés ont été ajoutés ; déployer la charge utile est votre choix. Sans elle, l’utilisateur voit la notice Background Items Added du système.

Les dossiers du catalogue se trouvent hors des dossiers que protègent les contrôles de confidentialité de macOS, si bien que l’analyse n’a besoin d’aucun profil de préférences de confidentialité (PPPC). Une vérification que macOS refuse compte comme non concluante, jamais comme une absence.

Ansible, Salt et autres outils

Suivez les mêmes étapes que le script Jamf avec le privilège root : téléchargez le script, vérifiez son SHA-256, écrivez le fichier de clé depuis votre coffre avec des permissions que seul root peut lire, et exécutez-le avec —api-key-file.

Conteneurs

Étape	Commande	Effet
Construction de l’image	sh discover.sh —scan-once —dry-run	Détecte et enregistre, n’inscrit jamais
Démarrage du conteneur	sh discover.sh —scan-once	Détecte et inscrit, avec la clé et l’organisation issues d’un secret d’exécution

N’intégrez jamais la clé dans une image et ne la passez jamais comme argument de construction. Chaque démarrage de conteneur qui inscrit est un nouvel hôte pour les licences. Sur les images musl ou BusyBox, l’analyse détecte seulement, et enregistre que l’installation n’y est pas prise en charge.

Windows : règles de détection des postes

La tâche planifiée exécute cette action, avec le chemin de la copie locale :

conhost.exe --headless powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "C:\Program Files\OpenLatch\Discovery\discover.ps1"

conhost.exe —headless évite que l’analyse affiche une fenêtre. Microsoft documente cette option comme non prise en charge, et des règles de détection standard pour les fenêtres masquées, comme les règles Sigma pour MITRE ATT&CK T1564.003, peuvent la repérer. Si votre détection des postes signale la tâche, autorisez cette ligne de commande pour le chemin de la copie locale. Comme l’option masque le code de sortie, l’analyse écrit son propre résultat dans son journal et dans son fichier de dernière analyse.

Quand la planification démarre

Situation	Quand la première analyse s’exécute
Un utilisateur se connecte après le déploiement	À cette connexion, puis à chaque intervalle
Une session déjà ouverte au déploiement, sous macOS, sous Windows, ou sous Linux avec systemd 248 ou ultérieur	Tout de suite
Une session déjà ouverte, sous Linux avant systemd 248	À la prochaine connexion de cet utilisateur
Une session déjà ouverte sous Windows que le déploiement ne peut pas atteindre	À la prochaine ouverture de session de cet utilisateur
Linux sans systemd	Jamais : le déploiement s’arrête avec OL-2203

Retirer la découverte ou en exclure une machine

Pour retirer la découverte d’une machine, déployez à nouveau le script avec —uninstall, ou -Uninstall sous Windows. La planification, la copie locale et le fichier de clé disparaissent ; chaque client inscrit reste, avec son inscription. Pour retirer aussi le client, utilisez sa propre désinstallation : voir Désinstaller.

Pour que la découverte continue d’analyser une machine sans rien inscrire, placez un fichier vide nommé opt-out dans le dossier de la découverte. Les analyses détectent et enregistrent alors seulement.

Déploiement	Emplacement du fichier opt-out
Pour chaque utilisateur, sous Linux	/usr/local/lib/openlatch/discovery/opt-out
Pour chaque utilisateur, sous macOS	/Library/Application Support/OpenLatch/Discovery/opt-out
Pour chaque utilisateur, sous Windows	C:\Program Files\OpenLatch\Discovery\opt-out
Pour l’utilisateur actuel seulement	opt-out à la racine du dossier de découverte de cet utilisateur, à côté de son fichier de clé, pas dans son dossier bin

Pour tenir une machine hors de votre organisation, désinscrivez-la dans la console : voir Gérer les hôtes découverts.

Faire tourner la clé de découverte

Faites tourner la clé quand une personne qui la détenait s’en va, ou selon votre propre calendrier. Les machines inscrites détiennent leur propre identifiant d’hôte, si bien qu’une rotation n’en déconnecte aucune.

Créez une nouvelle clé depuis Host enrollment dans Settings › API keys, ou avec Generate key and fill, et conservez-la dans votre coffre de secrets.
Déployez à nouveau le script avec la nouvelle clé, pour que le fichier de clé de chaque machine la contienne.
Supprimez l’ancienne clé dans Settings › API keys une fois la vague passée. Une machine qui détient encore l’ancien fichier de clé ne peut pas inscrire un nouvel utilisateur tant qu’elle n’a pas reçu le nouveau.

Codes affichés par les scripts

Les scripts affichent un code à côté de chaque échec, puis l’étape suivante sur la ligne d’après. L’installation que l’analyse lance quand elle trouve un agent garde les codes OL-21xx des scripts d’installation.

Code	Ce qui s’est passé	Que faire ensuite
OL-2200	Aucune clé ou aucune organisation n’a été fournie, dans l’environnement ou un fichier de clé. Lors d’un déploiement rien ne change ; lors d’une analyse le fichier de clé manque et rien ne s’installe	Fournissez la clé et l’organisation depuis votre coffre de secrets et déployez à nouveau
OL-2201	Une option n’a pas été reconnue, ou l’intervalle n’est pas un nombre entier de secondes supérieur à zéro	Utilisez les options listées plus haut ; l’intervalle est en secondes
OL-2202	Le script ne s’exécute pas sur ce système d’exploitation	Utilisez discover.sh sous macOS et Linux, discover.ps1 sous Windows
OL-2203	Cette machine Linux n’exécute pas systemd, dont la planification a besoin	Exécutez le script avec —scan-once depuis le planificateur de tâches de la machine, ou utilisez le script d’installation
OL-2204	L’étape demande le privilège système, par exemple pour retirer un déploiement fait pour tous les utilisateurs	Exécutez la même commande par votre outil de gestion de parc, ou avec sudo ou un PowerShell élevé
OL-2205	Un déploiement par tube n’a pas pu télécharger son fichier de version ou son empreinte	Vérifiez que la machine atteint openlatch.ai et déployez à nouveau, ou déployez le fichier du script
OL-2206	Un déploiement par tube a téléchargé son fichier de version et son SHA-256 ne correspond pas à l’empreinte publiée	Déployez à nouveau ; si l’échec persiste, déployez le fichier du script après avoir vérifié son empreinte
OL-2207	Un déploiement par tube a téléchargé le script Windows et celui-ci porte une signature qui n’est pas valide	Déployez à nouveau ; si l’échec persiste, déployez le fichier du script
OL-2208	La copie locale, son empreinte ou le fichier de clé n’ont pas pu être écrits	Vérifiez que le dossier de découverte est accessible en écriture au compte qui exécute le déploiement, puis déployez à nouveau
OL-2209	La planification n’a pas pu être enregistrée	Déployez à nouveau ; le message nomme l’étape que le système d’exploitation a refusée
OL-2210	La planification est enregistrée, mais son démarrage dans une session ouverte a échoué	Rien : les analyses de cet utilisateur démarrent à sa prochaine connexion
OL-2211	Le retrait de la découverte a laissé la planification, la copie locale ou le fichier de clé	Relancez le retrait par votre outil de gestion de parc ; le message nomme ce qui reste
OL-2212	Une inscription était déjà en cours pour cet utilisateur, et cette analyse a donc sauté la sienne	Rien : l’analyse suivante réessaie

Quand une analyse inscrit un client, l’inscription du client répond elle-même, et l’analyse agit selon la réponse :

Code	Ce qu’il signifie	Ce que fait l’analyse
OL-1201	La plateforme a refusé la clé	Cesse d’inscrire après trois refus consécutifs, jusqu’à ce que le fichier de clé change. Les analyses continuent de détecter. Remplacez le fichier de clé par une clé valide
OL-1612	La clé appartient à une autre organisation que celle nommée	Cesse d’inscrire après trois refus consécutifs, jusqu’à ce que le fichier de clé change. Les analyses continuent de détecter
OL-1613	La plateforme n’a pas pu être jointe pour confirmer l’organisation	Réessaie à l’analyse suivante
OL-1614	L’installation de cet utilisateur est inscrite dans une autre organisation	Laisse cette installation inchangée
OL-1624	Un administrateur a désinscrit cet hôte	Détecte et enregistre seulement, jusqu’à ce qu’un administrateur appuie sur Re-enrol
OL-1626	Un administrateur a coupé cet hôte	Détecte et enregistre seulement. Une personne qui exécute `openlatch init` avec une clé ramène l’hôte
OL-1625	Une autre inscription était en cours	Saute l’inscription de cette analyse

Signaler un problème de documentation

Merci. Votre signalement est bien parvenu à l’équipe.