Desplegar el descubrimiento

Requiere @openlatch/client 0.11.12 o una versión posterior

Despliega el descubrimiento una vez en las máquinas que gestiona tu herramienta de gestión de flota. Cada máquina analiza entonces en la sesión de cada usuario y, cuando encuentra un agente de IA que OpenLatch conoce, instala e inscribe el cliente para ese usuario. Descubrimiento explica qué hace un análisis y qué registra.

Antes de empezar, comprueba estos elementos:

#	Elemento	De dónde viene
1	Una clave de organización creada desde Host enrollment, guardada en tu almacén de secretos	Settings › API keys, o Generate key and fill en Settings › Discovery, como admin u owner
2	El slug o el identificador de tu organización	Settings › Discovery lo muestra cuando rellena el comando
3	Una herramienta de gestión de flota que ejecuta un script con privilegio de sistema: Intune, Configuration Manager, Jamf Pro, Ansible, Salt o similar	Tu equipo de puestos de trabajo
4	macOS, Linux con systemd, o Windows con PowerShell 5.1 o posterior	Las máquinas
5	El tráfico de salida aprobado para el cliente	Requisitos de red
6	Un aviso a tus empleados, donde tus representantes de los trabajadores o tus normas de protección de datos lo pidan	El aviso para tus empleados

Crear la clave de descubrimiento

Abre Settings › Discovery como admin u owner, y pulsa Generate key and fill.

Resultado esperado: el comando muestra una clave de organización nueva y tu organización, una sola vez. La clave lleva la fecha de hoy y no puede hacer nada salvo inscribir hosts.
Copia la clave en tu almacén de secretos antes de salir de la página. La página la olvida cuando sales; la clave sigue listada en Settings › API keys, donde puedes eliminarla.

También puedes crear la clave tú mismo en Settings › API keys, desde el preajuste Host enrollment. Una máquina solo necesita la clave para inscribirse: el cliente la cambia por la credencial de host propia de la máquina y nunca la guarda, así que rotar o eliminar la clave más tarde no desconecta ninguna máquina inscrita.

La clave en cada máquina

El descubrimiento escribe la clave y la organización en un archivo de clave en cada máquina, para que el análisis de cada usuario pueda inscribir el cliente de ese usuario. Cada usuario de la máquina puede leer ese archivo, porque cada análisis se ejecuta como su usuario. Quien lo lea puede inscribir hosts en tu organización, y nada más: la clave no tiene ningún otro permiso, no lee datos y no puede actuar sobre un agente. Trátala como compartida dentro de la máquina, da al descubrimiento una clave propia y rótala cuando se vaya alguien que la tenía.

Probarlo en una máquina

Ejecuta el comando de Settings › Discovery en una máquina de cada sistema operativo antes de desplegar una oleada. Con sudo, o en un PowerShell elevado, el comando despliega el descubrimiento para cada usuario de esa máquina.

En macOS y Linux:

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

En Windows, en un PowerShell elevado, escribe la clave y la organización en la sesión y luego ejecuta el script:

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

Sin sudo ni elevación, el mismo comando despliega el descubrimiento solo para el usuario actual, sin derechos de administrador. Sirve para una prueba en tu propia máquina:

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 despliegue por tubería vuelve a descargar su propio archivo de versión e instala esa copia. En macOS y Linux, primero compara la copia con el SHA-256 publicado y no instala nada cuando no coinciden. Para ver qué encontraría el análisis sin instalar nada, añade —dry-run al script, o -DryRun en Windows.

Comprobar el script antes de desplegarlo

Ambos scripts son texto plano, servidos para leerse. Para el script de macOS y Linux, OpenLatch publica el SHA-256 de cada versión. Comprueba con él el archivo que despliegas:

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

En Linux, sha256sum -c funciona igual. Un archivo que no coincide no es el que publicó OpenLatch: no lo despliegues. No se publica ningún resumen para el script de Windows.

Qué cambia el despliegue en una máquina

El despliegue copia el script, escribe el archivo de clave y registra una programación. Nunca analiza ni escribe en la carpeta personal de un usuario.

Elemento	Linux	macOS	Windows
Copia local del script, en una carpeta que solo los administradores pueden modificar	/usr/local/lib/openlatch/discovery/discover.sh	/Library/Application Support/OpenLatch/Discovery/discover.sh	C:\Program Files\OpenLatch\Discovery\discover.ps1
Archivo de clave, legible por los usuarios de la máquina	/etc/openlatch/discovery.key	/Library/Application Support/OpenLatch/Discovery/discovery.key	C:\ProgramData\OpenLatch\Discovery\discovery.key
Programación, una para todos los usuarios	El temporizador de usuario de systemd openlatch-discovery.timer, activado para cada usuario	El LaunchAgent ai.openlatch.discovery	La tarea programada OpenLatch Discovery, ejecutada para el grupo Users
Resultados de análisis y registro de cada usuario	~/.local/share/openlatch-discovery/	~/Library/Application Support/OpenLatch Discovery/	%LOCALAPPDATA%\OpenLatch\Discovery\

Un despliegue solo para el usuario guarda su copia, su archivo de clave y su programación en la carpeta de descubrimiento de ese usuario.

El script acepta estas opciones. Las formas para la herramienta de gestión de flota pasan la clave y la organización por el entorno o un archivo de clave, nunca en la línea de comandos:

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]

Opción	Efecto
—api-key-file, -ApiKeyFile	Un archivo con la clave y la organización, una línea cada una: OPENLATCH_API_KEY=… y OPENLATCH_ORG=…
—interval, -Interval	El intervalo de análisis en segundos, 86400 por defecto. Cámbialo desplegando de nuevo con otro valor
—dry-run, -DryRun	Solo detectar y registrar: no instalar, inscribir ni registrar nada
—uninstall, -Uninstall	Quitar la programación, la copia local y el archivo de clave. Cada cliente inscrito se queda
—scan-once, -ScanOnce	Un análisis en el contexto actual, sin programación: para contenedores y pruebas

Desplegar en una flota

Estas recetas despliegan el descubrimiento. Para instalar tú mismo el cliente en cada máquina, usa en su lugar las recetas de Desplegar el cliente.

Cada receta sigue las mismas reglas:

Regla	Qué significa
Ejecutar con privilegio de sistema	Como root en macOS y Linux, como SYSTEM en Windows. El despliegue registra la programación para cada usuario; los análisis se ejecutan como cada usuario
Desplegar el archivo del script	Mantenerlo exactamente como se publica, sin envolverlo ni editarlo nunca
Tomar la clave de un canal secreto	La clave llega al script por el entorno o un archivo de clave, nunca por una línea de comandos ni por un cuerpo de script que tu herramienta muestre a otros
Leer el informe de ejecución	El informe de cada ejecución de tu herramienta de gestión de flota es donde ves las máquinas que ejecutaron el script sin encontrar nada

Prueba cada receta en un dispositivo antes de la oleada. Después, despliégala de nuevo cada vez que quieras cambiar el intervalo o entregar una versión nueva del script: hasta entonces, la programación sigue ejecutando la copia que ya está en la máquina.

Microsoft Intune

Añade un script de plataforma que se ejecute como SYSTEM. Descarga el script, escribe un archivo de clave desde tu almacén de secretos y despliega:

# 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

Ajuste	Valor
Run this script using the logged on credentials	No, para que se ejecute como SYSTEM
Enforce script signature check	No
Run script in 64 bit PowerShell Host	Yes
Asignación	Un grupo de dispositivos

Cualquiera que pueda leer la directiva puede leer el cuerpo del script, por eso el script obtiene la clave en lugar de contenerla.

Microsoft Configuration Manager

Guarda el script de Intune de arriba como deploy-discovery.ps1, conviértelo en el contenido de un paquete o de una aplicación, y despliégalo con estos ajustes:

Ajuste	Valor
Línea de comandos	powershell.exe -NoProfile -ExecutionPolicy Bypass -File deploy-discovery.ps1
Ejecución	Tanto si hay un usuario conectado como si no, con derechos de administrador
Implementación	Requerida, para una recopilación de dispositivos

El estado de implementación de cada dispositivo es tu informe de ejecución.

Jamf Pro

Una directiva de Jamf ejecuta sus scripts como root, que es lo que el despliegue necesita. El script obtiene la clave de tu almacén de secretos y la escribe en un archivo de clave que solo root puede leer. Nunca pases la clave como parámetro de la directiva: Jamf entrega los parámetros al script en su línea de comandos.

#!/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"

Configura la Execution Frequency de la directiva como Once per computer, y ejecútala de nuevo cuando cambies el intervalo o el script.

En macOS 13 y posterior, un elemento en segundo plano nuevo hace que el sistema pida al usuario que lo apruebe. Para evitar la petición, añade un perfil de configuración con una carga Managed Login Items que contenga una regla: Rule Type Label, Rule Value ai.openlatch.discovery. Con esa carga, el elemento queda aprobado y el usuario puede ver un aviso de que se añadieron elementos gestionados; desplegar la carga es tu elección. Sin ella, el usuario ve el aviso Background Items Added del sistema.

Las carpetas del catálogo están fuera de las carpetas que protegen los controles de privacidad de macOS, así que el análisis no necesita ningún perfil de preferencias de privacidad (PPPC). Una comprobación que macOS rechaza cuenta como no concluyente, nunca como ausente.

Ansible, Salt y otras herramientas

Sigue los mismos pasos que el script de Jamf con privilegio de root: descarga el script, comprueba su SHA-256, escribe el archivo de clave desde tu almacén con permisos que solo root pueda leer, y ejecútalo con —api-key-file.

Contenedores

Etapa	Comando	Efecto
Construcción de la imagen	sh discover.sh —scan-once —dry-run	Detecta y registra, nunca inscribe
Arranque del contenedor	sh discover.sh —scan-once	Detecta e inscribe, con la clave y la organización de un secreto de ejecución

Nunca incluyas la clave en una imagen ni la pases como argumento de construcción. Cada arranque de contenedor que inscribe es un host nuevo para las licencias. En imágenes musl o BusyBox el análisis solo detecta, y registra que la instalación no es compatible ahí.

Windows: reglas de detección en los puestos

La tarea programada ejecuta esta acción, con la ruta de la copia local:

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

conhost.exe —headless evita que el análisis muestre una ventana. Microsoft documenta esta opción como no admitida, y las reglas de detección estándar para ventanas ocultas, como las reglas Sigma para MITRE ATT&CK T1564.003, pueden detectarla. Si tu detección en los puestos señala la tarea, permite esa línea de comandos para la ruta de la copia local. Como la opción oculta el código de salida, el análisis escribe su propio resultado en su registro y en su archivo de último análisis.

Cuándo empieza la programación

Situación	Cuándo se ejecuta el primer análisis
Un usuario inicia sesión tras el despliegue	En ese inicio de sesión, y luego en cada intervalo
Una sesión ya abierta en el despliegue, en macOS, en Windows, o en Linux con systemd 248 o posterior	De inmediato
Una sesión ya abierta, en Linux con systemd anterior a 248	En el próximo inicio de sesión de ese usuario
Una sesión ya abierta en Windows que el despliegue no puede alcanzar	En el próximo inicio de sesión de ese usuario
Linux sin systemd	Nunca: el despliegue se detiene con OL-2203

Quitar el descubrimiento o excluir una máquina

Para quitar el descubrimiento de una máquina, despliega de nuevo el script con —uninstall, o -Uninstall en Windows. La programación, la copia local y el archivo de clave desaparecen; cada cliente inscrito se queda, con su inscripción. Para quitar también el cliente, usa su propia desinstalación: consulta Desinstalar.

Para que el descubrimiento siga analizando una máquina sin inscribir nada, coloca un archivo vacío llamado opt-out en la carpeta del descubrimiento. Los análisis entonces solo detectan y registran.

Despliegue	Dónde va el archivo opt-out
Para cada usuario, en Linux	/usr/local/lib/openlatch/discovery/opt-out
Para cada usuario, en macOS	/Library/Application Support/OpenLatch/Discovery/opt-out
Para cada usuario, en Windows	C:\Program Files\OpenLatch\Discovery\opt-out
Solo para el usuario actual	opt-out en la raíz de la carpeta de descubrimiento de ese usuario, junto a su archivo de clave, no en su carpeta bin

Para mantener una máquina fuera de tu organización, dala de baja en la consola: consulta Gestionar los hosts descubiertos.

Rotar la clave de descubrimiento

Rota la clave cuando se vaya alguien que la tenía, o según tu propio calendario. Las máquinas inscritas tienen su propia credencial de host, así que una rotación no desconecta ninguna.

Crea una clave nueva desde Host enrollment en Settings › API keys, o con Generate key and fill, y guárdala en tu almacén de secretos.
Despliega de nuevo el script con la clave nueva, para que el archivo de clave de cada máquina la contenga.
Elimina la clave antigua en Settings › API keys una vez ejecutada la oleada. Una máquina que aún tenga el archivo de clave antiguo no puede inscribir a un usuario nuevo hasta que reciba el nuevo.

Códigos que muestran los scripts

Los scripts muestran un código junto a cada fallo, y luego el paso siguiente en la línea de abajo. La instalación que ejecuta el análisis al encontrar un agente conserva los códigos OL-21xx de los scripts de instalación.

Código	Qué ocurrió	Qué hacer a continuación
OL-2200	No se dio ninguna clave ni organización, en el entorno ni en un archivo de clave. En un despliegue no cambia nada; en un análisis falta el archivo de clave y no se instala nada	Entrega la clave y la organización desde tu almacén de secretos y despliega de nuevo
OL-2201	Una opción no se reconoció, o el intervalo no es un número entero de segundos mayor que cero	Usa las opciones indicadas arriba; el intervalo va en segundos
OL-2202	El script no se ejecuta en este sistema operativo	Usa discover.sh en macOS y Linux, discover.ps1 en Windows
OL-2203	Esta máquina Linux no ejecuta systemd, que la programación necesita	Ejecuta el script con —scan-once desde el programador de tareas de la máquina, o usa el script de instalación
OL-2204	El paso necesita privilegio de sistema, por ejemplo para quitar un despliegue hecho para todos los usuarios	Ejecuta el mismo comando mediante tu herramienta de gestión de flota, o con sudo o un PowerShell elevado
OL-2205	Un despliegue por tubería no pudo descargar su archivo de versión o su resumen	Comprueba que la máquina alcanza openlatch.ai y despliega de nuevo, o despliega el archivo del script
OL-2206	Un despliegue por tubería descargó su archivo de versión y su SHA-256 no coincide con el resumen publicado	Despliega de nuevo; si sigue fallando, despliega el archivo del script tras comprobar su resumen
OL-2207	Un despliegue por tubería descargó el script de Windows y este lleva una firma que no es válida	Despliega de nuevo; si sigue fallando, despliega el archivo del script
OL-2208	No se pudo escribir la copia local, su resumen o el archivo de clave	Comprueba que la cuenta que ejecuta el despliegue puede escribir en la carpeta de descubrimiento, y despliega de nuevo
OL-2209	No se pudo registrar la programación	Despliega de nuevo; el mensaje nombra el paso que rechazó el sistema operativo
OL-2210	La programación está registrada, pero falló su inicio en una sesión abierta	Nada: los análisis de ese usuario empiezan en su próximo inicio de sesión
OL-2211	Al quitar el descubrimiento quedaron la programación, la copia local o el archivo de clave	Vuelve a quitarlo mediante tu herramienta de gestión de flota; el mensaje nombra lo que queda
OL-2212	Ya había una inscripción en curso para este usuario, así que este análisis omitió la suya	Nada: el análisis siguiente vuelve a intentarlo

Cuando un análisis inscribe un cliente, la propia inscripción del cliente responde, y el análisis actúa según la respuesta:

Código	Qué significa	Qué hace el análisis
OL-1201	La plataforma rechazó la clave	Deja de inscribir tras tres rechazos seguidos, hasta que cambie el archivo de clave. Los análisis siguen detectando. Sustituye el archivo de clave por una clave válida
OL-1612	La clave pertenece a otra organización distinta de la indicada	Deja de inscribir tras tres rechazos seguidos, hasta que cambie el archivo de clave. Los análisis siguen detectando
OL-1613	No se pudo contactar con la plataforma para confirmar la organización	Vuelve a intentarlo en el análisis siguiente
OL-1614	La instalación de este usuario está inscrita en otra organización	Deja esa instalación sin cambios
OL-1624	Un administrador dio de baja este host	Solo detecta y registra, hasta que un administrador pulse Re-enrol
OL-1626	Un administrador cortó este host	Solo detecta y registra. Una persona que ejecuta `openlatch init` con una clave recupera el host
OL-1625	Había otra inscripción en curso	Omite la inscripción de este análisis

Informar de un problema en la documentación

Gracias. Tu informe ha llegado al equipo.