Hodei-Shield Agent: guía beta para macOS¶

Instala la versión 2.20.0 en macOS 13 o posterior (Apple Silicon o Intel). Necesitas una cuenta de administrador, HTTPS saliente a la URL de tu plataforma y a hs-agent-releases.s3.gra.io.cloud.ovh.net, un token de inscripción (sirve una vez; lo crea en la consola el administrador de tu organización o el de tu MSSP), un id de agente (letras, dígitos, . _ : -; será el nombre permanente de la máquina), la URL de la plataforma (https://…) y OpenSSL 3 (brew install openssl@3; el openssl del sistema es LibreSSL y no puede hacer la comprobación). Los informes de error van a Sentry por defecto: para desactivarlos, crea la marca antes de instalar el .pkg (final de esta guía).

Aún no medido en un Mac. Todos los pasos siguientes están NOT RUN (no ejecutados): se escriben desde el empaquetado. Eres de los primeros en seguirlos. Si un paso falla, detente y escribe a info@hodeitek.com; no repitas la inscripción.

1. Descarga¶

Solo desde el almacén de versiones, nunca desde un enlace de correo o chat.

V="${V:?set V to the version you were given}"
B=https://hs-agent-releases.s3.gra.io.cloud.ovh.net
mkdir hodei-install && cd hodei-install
curl -fsSLO "$B/agent/$V/hodei-shield-$V-universal.pkg"
curl -fsSLO "$B/agent/$V/SHA256SUMS"
curl -fsSLO "$B/agent/$V/SHA256SUMS.sig"

Antes de ejecutar nada, comprueba que la descarga es auténtica: verificar una versión del agente y verificar la descarga.

2. Verificación¶

Versión independiente de esta comprobación: verify-release.md. El .pkg está firmado con un Developer ID de Apple y notarizado; SHA256SUMS.sig es la firma de versión (Ed25519) sobre SHA256SUMS. Guarda como hodei-shield-release.pub.pem (es la huella de la clave, no el checksum del paquete; el paquete se comprueba con SHA256SUMS más abajo. Para calcular la huella de la clave guardada: /opt/homebrew/opt/openssl@3/bin/openssl pkey -pubin -in hodei-shield-release.pub.pem -outform DER | tail -c 32 | shasum -a 256 → 8b730d2fcbd90e2656bd9b3f265638f1e8e8ac2379d48b0636feb5efe5a88f07 -):

-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAEUqKd+ot7BESwk+vf6EVBKudMi6F6jmY3dJeHXfCWkQ=
-----END PUBLIC KEY-----

Usa la ruta completa de OpenSSL 3 (/usr/local/opt/openssl@3/bin/openssl en Intel):

SSL=/opt/homebrew/opt/openssl@3/bin/openssl
$SSL base64 -d -A -in SHA256SUMS.sig -out SHA256SUMS.sig.raw
$SSL pkeyutl -verify -rawin -pubin -inkey hodei-shield-release.pub.pem \
  -sigfile SHA256SUMS.sig.raw -in SHA256SUMS      # Signature Verified Successfully
grep " hodei-shield-$V-universal\.pkg\$" SHA256SUMS | shasum -a 256 -c -   # ...pkg: OK
pkgutil --check-signature "hodei-shield-$V-universal.pkg"   # Developer ID Installer: Hodeitek

Cualquier otro resultado significa no instalar: borra los ficheros y avisa a Hodeitek.

3. Instalación¶

sudo installer -pkg "hodei-shield-$V-universal.pkg" -target /
sudo -u _hodeishield tee /var/lib/hodei-shield/hodei-shield.toml >/dev/null <<'EOT'
platform_url = "https://<platform host>"
state_dir = "/var/lib/hodei-shield"
EOT
/usr/local/bin/hodei-shield version

El paquete crea la cuenta de servicio _hodeishield, la carpeta de estado y el fichero de CA, y arranca el servicio, que espera en silencio hasta que te inscribas. Un servicio que se reinicia sin parar es un fallo.

Qué instala el paquete en tu Mac¶

installer solo imprime sus propias líneas de progreso (la última, The install was successful.). Los mensajes del propio paquete van al log del instalador; para leerlos:

sudo grep 'postinstall:' /var/log/install.log

El paquete instala: - /usr/local/bin/hodei-shield: el agente (root:wheel 0755). - /Applications/Hodei-Shield.app: la ventana de estado, opcional. Solo lee un fichero de estado y no guarda claves. - /Library/LaunchDaemons/com.hodeitek.hodei-shield.plist y /Library/LaunchDaemons/com.hodeitek.hodei-shield.runtime-dir.plist: el servicio del agente. Corre con la cuenta de sistema _hodeishield, nunca como root. - /Library/PrivilegedHelperTools/com.hodeitek.hodei-shield.update y /Library/LaunchDaemons/com.hodeitek.hodei-shield.update.plist: el ayudante de actualización. Está cargado pero inactivo: las versiones estables de macOS no se actualizan solas, y se actualiza instalando el nuevo .pkg. - /etc/hodei-shield/platform-ca.pem (la CA de la plataforma), /etc/newsyslog.d/com.hodeitek.hodei-shield.conf (rotación de logs; aún no está activa en 2.20.1, así que /var/log/hodei-shield crece hasta que lo vacíes), /usr/local/libexec/hodei-shield/uninstall.sh (el desinstalador), /usr/local/share/doc/hodei-shield/THIRD-PARTY-NOTICES. - Carpetas: /var/lib/hodei-shield (0700, estado y clave privada), /var/log/hodei-shield (0750, logs), /var/run/hodei-shield (estado para la ventana), /private/var/db/hodei-shield-update (root 0700, registros de actualización).

Para quitarlo todo: sudo /usr/local/libexec/hodei-shield/uninstall.sh (añade --purge para borrar también el estado y los logs).

Ítems de inicio: tras la instalación, macOS puede avisar de que se han añadido ítems en segundo plano, y Ajustes del Sistema → General → Ítems de inicio → Permitir en segundo plano muestra el agente como «Hodeitek SL». Es el agente de Hodei-Shield (firmado por Hodeitek S.L.). Déjalo activado: si lo desactivas, el agente deja de ejecutarse y el equipo deja de informar.

Icono de la barra de menús: en esta versión la barra de menús muestra un escudo gris, aunque todo funcione. Es normal y no significa que el agente esté detenido. Pasa el puntero por encima para ver el estado, o abre Hodei-Shield.app para ver el detalle.

4. Inscripción¶

Una vez por máquina. El token se teclea oculto, nunca en una línea de comandos.

cd /
IFS= read -rs HODEI_TOKEN && echo
printf '%s' "$HODEI_TOKEN" | sudo -u _hodeishield env \
  HODEI_PLATFORM_URL="https://<platform host>" \
  HODEI_STATE_DIR=/var/lib/hodei-shield \
  /usr/local/bin/hodei-shield enroll --token-stdin --agent-id '<this machine id>'
unset HODEI_TOKEN
sudo launchctl kickstart -k system/com.hodeitek.hodei-shield

Cuando está en marcha con ambos, evalúa y envía de inmediato, y de nuevo cada intervalo de envío (por defecto 3600 segundos). Si va bien, imprime enrolled: producer=endpoint_agent:<id> public_key_id=… tenant_id=….

Lo que verás¶

{"timestamp":"…","level":"INFO","fields":{"message":"enrolled as a signing producer","public_key_id":"…","producer":"\"endpoint_agent:<your-agent-id>\"","tenant_id":"…"},"target":"agent_enroll::producer"}
enrolled: producer=endpoint_agent:<your-agent-id> public_key_id=<uuid> tenant_id=<uuid>
If the agent service is stopped, start it: sudo launchctl load -w /Library/LaunchDaemons/com.hodeitek.hodei-shield.plist. If it is running and was waiting for this enrollment, it will pick it up within 5 minutes; to pick it up now: sudo launchctl kickstart -k system/com.hodeitek.hodei-shield

La primera línea es el registro del agente; la línea enrolled: es el resultado: anota el public_key_id. Después ejecuta el kickstart que sugiere, para que el agente empiece a informar ya y no en 5 minutos. Si falla, no reutilices el token: pide uno nuevo a tu administrador. Error de certificado o TLS: no añadas certificados ni desactives comprobaciones; el agente solo confía en /etc/hodei-shield/platform-ca.pem. Envía la salida de hodei-shield diagnose a tu administrador; otros fallos: resolución de problemas.

5. Comprobar en la consola¶

sudo launchctl print system/com.hodeitek.hodei-shield | head, y esto debe salir con 0: sudo -u _hodeishield sh -c 'cd /var/lib/hodei-shield && exec /usr/local/bin/hodei-shield self-test'. La máquina aparece en Endpoints tras su primer ciclo. Registros (la carpeta solo la lee la cuenta de servicio, así que usa sudo): sudo tail -50 /var/log/hodei-shield/hodei-shield.err.log, o ambos logs con sudo sh -c 'tail -50 /var/log/hodei-shield/*.log'. Un Mac sin EDR ni antivirus informa de un fail (Third-party EDR present and active); es cierto, no un fallo.

Aviso esperado: las versiones estables de macOS y Windows no se actualizan solas. Aproximadamente una vez por hora el registro muestra una línea WARN update poll/apply did not succeed; continuing on current version con el motivo self-update is not supported on this OS by this release. Es lo esperado y no indica un problema: se actualiza instalando el paquete nuevo. (Una versión posterior lo registra una sola vez, como información.)

Controles en «Error» en esta beta: algunos controles pueden aparecer como «Error» en sistemas cuyo idioma no es el inglés, o porque el agente se ejecuta sin permisos de administrador. No significa que el control esté fallando: el agente no pudo leerlo con fiabilidad y no lo cuenta como cumplido. La próxima versión beta lo corrige.

6. Actualizar a mano¶

macOS no tiene aplicador de actualizaciones: se actualiza a mano con un .pkg. No te inscribas de nuevo. /var/lib/hodei-shield no se toca. Descarga y verifica el nuevo .pkg como en los pasos 1 y 2 y:

V=<nueva versión>
sudo cp -p /usr/local/bin/hodei-shield ~/hodei-shield.prev    # copia para revertir
sudo installer -pkg "hodei-shield-$V-universal.pkg" -target /
/usr/local/bin/hodei-shield version                           # la versión nueva
sudo -u _hodeishield sh -c 'cd /var/lib/hodei-shield && exec /usr/local/bin/hodei-shield self-test'

Revertir: sudo launchctl bootout system/com.hodeitek.hodei-shield, después sudo install -o root -g wheel -m 0755 ~/hodei-shield.prev /usr/local/bin/hodei-shield, y sudo launchctl bootstrap system /Library/LaunchDaemons/com.hodeitek.hodei-shield.plist.

7. Desinstalación¶

Antes, pide a tu administrador que revoque la máquina (consola: Endpoints, el endpoint, Revoke enrolment). El .pkg 2.20.0 trae un desinstalador (NOT RUN en un Mac):

sudo /usr/local/libexec/hodei-shield/uninstall.sh            # como root; conserva la clave y los registros
sudo /usr/local/libexec/hodei-shield/uninstall.sh --purge    # borra también clave, cola, config, registros (irreversible)

Quita los daemons, el programa, el ayudante de actualización (/Library/PrivilegedHelperTools/com.hodeitek.hodei-shield.update), la app, la CA y el recibo, y la cuenta _hodeishield si la creó el paquete. Sin --purge conserva /var/lib/hodei-shield (clave privada, cola, hodei-shield.toml; pasa a root antes de borrar la cuenta, NOT RUN; una reinstalación la devuelve) y /var/log/hodei-shield; /etc/hodei-shield queda si contiene telemetry-off. Los registros aún no rotan (la regla viene desactivada): /var/log/hodei-shield crece hasta que lo borres. Los .pkg anteriores no traen desinstalador: quítalos a mano:

sudo launchctl unload -w /Library/LaunchDaemons/com.hodeitek.hodei-shield.plist
sudo launchctl unload -w /Library/LaunchDaemons/com.hodeitek.hodei-shield.runtime-dir.plist
sudo rm /Library/LaunchDaemons/com.hodeitek.hodei-shield.plist /Library/LaunchDaemons/com.hodeitek.hodei-shield.runtime-dir.plist
sudo rm /usr/local/bin/hodei-shield
sudo dscl . -delete /Users/_hodeishield; sudo dscl . -delete /Groups/_hodeishield
sudo pkgutil --forget com.hodeitek.hodei-shield

/var/lib/hodei-shield conserva la clave privada de la máquina: bórralo solo a propósito.

Privacidad y ayuda. Los informes de error (solo fallos, sin datos personales) van a Sentry; para desactivarlos: sudo mkdir -p /etc/hodei-shield && sudo touch /etc/hodei-shield/telemetry-off (antes de instalar el .pkg). Ayuda: info@hodeitek.com o el botón Beta de la consola.