Qué sale de tu equipo¶
Esta página es para quien va a instalar el agente de Hodei-Shield durante la beta y quiere saber, con palabras llanas, qué envía el programa fuera del ordenador, a quién, y qué no envía nunca. Es una descripción del programa, no un texto legal. Cada afirmación se comprobó contra el código fuente del programa. Donde el código no resuelve una duda, la página lo dice.
La parte legal (quiénes son los subencargados, tus derechos) no está en esta página. Para los informes de errores, Hodeitek es el responsable del tratamiento, la base jurídica es el interés legítimo y los informes se conservan 90 días (véase Informes de errores). El aviso de privacidad de la consola está en https://app.hodeishield.com/privacy. La lista de subencargados del sitio web (el anexo) todavía no está publicada; se enlazará aquí cuando lo esté.
En resumen¶
- El agente comprueba la configuración del ordenador (¿está cifrado el disco?, ¿está activo el cortafuegos?, ¿se bloquea la pantalla?, etc.) y envía el resultado de cada comprobación a la plataforma de Hodei-Shield de tu organización.
- Cada resultado es un registro pequeño y firmado. Dice qué comprobación se
ejecutó, si pasó, falló, no aplicaba o no pudo ejecutarse, cuándo, y unos
pocos datos permitidos (por ejemplo
"backend": "nftables"). Nunca lleva texto libre, ficheros, documentos, navegación, contraseñas, claves ni tokens. - Con cada envío el agente manda también el nombre del equipo, las direcciones IP enrutables y el nombre, la versión y la arquitectura del sistema operativo, para que la consola pueda mostrar qué máquina es cuál.
- Si algo falla dentro del agente, puede enviar un informe de errores a nuestro servicio de seguimiento de errores. Va por tu consola, está desactivado por defecto en cada inquilino (una compilación desde el código fuente no envía nada), se describe en Informes de errores y puedes desactivarlo.
- La clave privada del agente no sale nunca del ordenador.
1. Las observaciones: lo principal que envía el agente¶
En cada ciclo el agente ejecuta sus comprobaciones y envía los resultados en un
solo sobre a la URL de la plataforma que figura en su configuración (en la
beta, https://app.hodeishield.com). El sobre es un documento JSON cuya forma fija un contrato;
los campos se listan a continuación.
El sobre¶
| Campo | Qué es |
|---|---|
schema_version |
La versión del formato ("1.0") |
agent_id |
Un identificador (un UUID) que la plataforma asignó a la clave de este agente al inscribirlo. No es el nombre de tu equipo |
agent_version |
La versión del programa del agente |
producer |
endpoint_agent:<nombre>. <nombre> es el nombre de máquina que elegiste al inscribirla (el nombre del equipo si no elegiste ninguno) |
producer_run_id |
Un contador que crece en cada ejecución, para que un reenvío se reconozca como reenvío |
observations |
La lista de resultados (tabla siguiente) |
inventory |
Datos sobre la máquina (sección 3) |
signature |
La firma de todo lo anterior (sección 4) |
No hay campo de organización ni de inquilino: la plataforma deduce a qué organización perteneces a partir de la inscripción, no del contenido.
Una observación¶
| Campo | Qué contiene |
|---|---|
check_code |
Qué comprobación se ejecutó, por ejemplo chk.os.disk_encryption.enabled |
subject_type, subject_ref |
De quién trata el resultado. El agente envía tenant con referencia nula, que significa «la propia organización de este equipo» |
target_kind, target_ref |
El tipo de cosa comprobada (endpoint) y su nombre: el nombre del equipo tal como lo informa el sistema operativo |
status |
pass, fail, na (no aplica) o error (la comprobación no pudo ejecutarse). El agente nunca informa pass si no está seguro |
severity |
low, medium, high o critical, fija para cada comprobación |
observed_at |
Cuándo se ejecutó la comprobación (UTC) |
freshness_sla_seconds |
Durante cuánto tiempo debe considerarse vigente el resultado |
detail |
Los datos permitidos sobre el resultado (sección 2) |
Qué miran las comprobaciones¶
El registro de comprobaciones del agente lista 173 códigos (agent-check-registry.v1.json). Son preguntas sobre la configuración del sistema operativo. Por áreas: cuentas (inicio de sesión automático, bloqueo de cuenta, longitud mínima de contraseña), registro de auditoría, actualizaciones automáticas, integridad del arranque, cifrado de disco, cortafuegos del equipo, bloqueo de pantalla, sincronización horaria, endurecimiento del núcleo, protección contra malware y presencia de EDR, acceso remoto (ajustes de SSH), control de acceso obligatorio, protección de integridad del sistema, ajustes de exposición de credenciales (dos interruptores de endurecimiento del registro de Windows), la salud del propio agente, y tres conjuntos de líneas base de endurecimiento publicadas (SCAP Security Guide para Ubuntu, macOS Security Compliance Project y DISA STIG para Windows). No todas las comprobaciones existen en todos los sistemas; el fichero del registro indica cuáles existen en cada uno.
La ventana y el icono de la bandeja solo muestran cinco de ellas (cifrado de disco, cortafuegos, bloqueo de pantalla, actualizaciones automáticas y salud del agente); la plataforma recibe todas las que el agente ejecuta.
Lo que el código no permite afirmar: para esta página no se leyó el código de cada comprobación. Lo que cada una lee del sistema operativo está definido en el código fuente del programa. Lo que puede salir queda acotado por las reglas de la sección siguiente, sea cual sea lo que una comprobación lea.
2. El campo detail: qué puede y qué no puede contener¶
detail es donde una comprobación pone los datos que respaldan su resultado. Es
el campo que más conviene vigilar, así que el código no se fía de las
comprobaciones: todo detail se construye a través de una única puerta,
SanitizedDetail, y si algo incumple una regla, se descarta todo el contenido.
Qué se permite
- Una lista plana de pares
clave: valor, como mucho 32 pares y 4096 bytes en total. - Claves: solo letras minúsculas, dígitos,
_y-, de hasta 64 caracteres. Además, cada comprobación tiene su propia lista corta de claves permitidas; una clave fuera de la lista descarta todo eldetail. - Valores: solo verdadero/falso, un número entero (entre -2^53 y 2^53, sin decimales) o una palabra corta (de hasta 64 caracteres).
Qué se rechaza
- Listas, objetos anidados, valores vacíos (
null), decimales y números muy grandes. - Cualquier texto que parezca un secreto o un dato personal. La puerta rechaza
una clave o un valor que contenga: un bloque PEM (
-----BEGIN), un token bearer, algo con forma de JWT, una dirección de correo electrónico, o cualquier secuencia de 32 o más letras, dígitos,+o/(lo que atrapa claves, huellas y tokens). La única excepción es una lista fija de nombres publicados de algoritmos SSH que, por casualidad, parecen direcciones de correo (comochacha20-poly1305@openssh.com), comparados enteros.
Qué pasa cuando se incumple una regla. La comprobación no envía el valor
problemático, y tampoco envía un detail vacío que parezca normal. Envía una
marca, {"detail_dropped": true, "detail_dropped_reason": "<clase>"}, donde la
clase es una de una lista fija de etiquetas (key_not_allowed,
looks_sensitive, type_not_permitted, too_many_pairs, too_large) y nunca
una parte del valor rechazado. El agente escribe en su registro esa misma clase,
y solo la clase.
Lo que la puerta no puede prometer. Es un filtro de patrones. Impide que
secretos y datos personales salgan como texto, con las formas indicadas. No
entiende el significado: una palabra corta, como un nombre de usuario de 10
letras, no es un patrón que esta puerta reconozca. Por eso las comprobaciones
usan vocabularios fijos de claves, y por eso la protección principal es que
informan de estados ("active": false) y de recuentos
("encrypted_volumes": 1), no de nombres. Para esta página no se auditó el
código de cada comprobación.
3. El inventario: datos sobre la máquina¶
Cada sobre lleva también un inventory. Estos son los únicos campos que
contiene, y cada uno es opcional (si no se puede leer, se omite; nunca se envía
vacío):
| Campo | Qué contiene |
|---|---|
hostname |
El nombre del equipo, solo si es un nombre válido al estilo DNS (letras, dígitos, guiones y puntos; sin guion bajo). Si no, se omite. Es el mismo nombre que las observaciones llevan en target_ref |
ip_addresses |
Hasta 16 direcciones IPv4/IPv6 de las interfaces de red reales de la máquina, como texto |
os.family |
linux, windows o macos |
os.name, os.version |
Lo que el sistema operativo dice de sí mismo (por ejemplo Ubuntu, 24.04) |
os.arch |
La arquitectura del procesador para la que se compiló el agente (por ejemplo x86_64) |
Qué direcciones IP se omiten: las de bucle local (loopback), de enlace
local, multidifusión, no especificadas y de difusión; toda dirección de una
interfaz de bucle local, de Docker, de puente de máquina virtual o de
contenedor (nombres como docker*, br-*, veth*, virbr*, vmnet*,
vboxnet*, cni*, podman*, vEthernet*); y las direcciones IPv6 cuya
segunda mitad se construye con la dirección física (MAC) de la tarjeta de red.
Se conservan: los rangos privados (10.x, 192.168.x, fd..) y las
direcciones de túneles VPN. Es decir, la consola recibe tus direcciones
internas.
No se envía: la dirección MAC. El código no la incluye nunca en el sobre, por diseño.
El inventario se envía con cada sobre, no solo cuando cambia. La plataforma conserva el último valor que recibió.
4. Identidad y firma¶
Cuando inscribes el equipo, el agente crea un par de claves en la máquina. Solo se envía la clave pública (una vez, junto con el token de inscripción de un solo uso, el nombre de máquina que elegiste y la versión del agente). A partir de ahí, cada sobre se firma con la clave privada, y el sobre lleva:
| Campo | Qué contiene |
|---|---|
signature.alg |
ed25519, o ml-dsa-65 (poscuántica) en las compilaciones que la incluyen |
signature.public_key_id |
El identificador de la clave pública, para que la plataforma sepa con qué clave verificar. Es lo que identifica a la máquina ante la plataforma |
signature.value |
La firma en sí |
No se envía: la clave privada. Permanece en la carpeta de estado del agente (con permisos restringidos a la propia cuenta de servicio del agente). Ningún campo del sobre ni de la petición de inscripción la lleva (las listas de arriba son completas). Lo mismo vale para la clave que cifra la cola sin conexión.
La conexión con la plataforma va cifrada (TLS) y el agente solo confía en la autoridad de certificación que viaja dentro de su propio instalador, no en el almacén del sistema operativo. El agente no presenta certificado de cliente; lo que lo identifica es la firma.
5. Si no se llega a la plataforma¶
Los sobres firmados que no se pudieron enviar se guardan en una cola sin conexión en la carpeta de estado del agente, cifrada en disco, y se envían más tarde. La cola tiene tope (10 000 elementos y 32 MiB); cuando se llena, rechaza elementos nuevos en lugar de borrar los antiguos. Nada de la cola es legible sin la clave de cola del agente. Cómo se dosifica la cola, y cómo un envío fallido retrasa el siguiente ciclo, está en la sección 1.
Si la plataforma rechaza al agente. Tras un 401 o un 403 (se rechaza la
credencial) el agente pasa a dormido (en palabras llanas: la plataforma ha rechazado la credencial del equipo, así que el equipo queda en espera, sin evaluar ni enviar, y solo vuelve a comprobar de vez en cuando). Sigue en ejecución, no evalúa ni envía
nada y no hace ninguna llamada de red (ni siquiera la consulta de
actualizaciones), salvo un lote real para volver a comprobar: la primera vez
tras 1 hora y luego a intervalos crecientes hasta 24 horas tras un 401 (6
horas tras un 403). Tras un 400 (un lote rechazado de forma definitiva) el
agente pasa a detenido (en palabras llanas: la plataforma ha rechazado un lote de forma definitiva, o el propio agente ha retenido el nombre del equipo antes de enviarlo; el agente deja de evaluar y de enviar, y ese lote no se vuelve a enviar): no encola ni envía nada, y envía un lote nuevo como
prueba con la misma curva (1 hora, creciendo hasta 24 horas); el lote rechazado
no se vuelve a enviar nunca. Una detención causada por el propio filtrado del
nombre del equipo por parte del agente no envía ninguna prueba y termina cuando
cambia el nombre del equipo. Un agente detenido sigue haciendo la consulta de
actualizaciones (sección 7). Una prueba que la plataforma acepta termina
cualquiera de los dos estados. Con qué frecuencia llegan los equipos a estos
estados en producción no se puede saber a partir del código.
6. Informes de errores¶
Hoy, medido el 2026-11-17: ninguna consola lo ofrece todavía. La consola aún no sirve la ruta de diagnósticos ni la política firmada, así que un agente de la versión 2.23.0 o posterior no envía ningún informe de errores. Solo empezará cuando tu consola lo autorice.
En la beta, las compilaciones oficiales pueden enviar informes de errores y
cierres inesperados. Van a través de tu consola de Hodei-Shield, nunca
directamente al servicio de seguimiento de errores: cada informe se firma con
la clave del equipo y se envía a tu consola
(POST {platform_url}/api/v1/agent/diagnostics), que lo reenvía desde su propia
dirección. El agente nunca contacta con el servicio y no tiene alternativa
directa. Según el diseño del relé, el servicio no ve por tanto la dirección IP
del equipo; la consola a la que ya envías las observaciones sí ve la conexión,
como en cualquier otra petición. Están desactivados por defecto en cada
inquilino: el agente solo envía uno mientras tiene un «sí» firmado de la
consola que no ha caducado (24 horas); sin documento, con uno inválido o
caducado, o con un «no», no envía ninguno. Por diseño el agente no incluye datos
personales (send_default_pii desactivado en el SDK). Un agente sano no
envía nada; cuenta un fallo, y también una anomalía en el canal de
autoactualización (se informa como mucho una vez por tipo y por ejecución del
proceso). Hodeitek es el responsable del tratamiento de estos informes, la
base jurídica es el interés legítimo y se conservan 90 días. En cada
equipo también puedes forzar que no salgan, diga lo que diga la consola: crea el
fichero marcador o define HODEI_SENTRY_DSN=off. Los campos que salen y los que nunca salen, y el
interruptor exacto para cada sistema, siguen más abajo.
Qué contiene un informe de errores y cómo forzar que no salga¶
El agente construye cada informe a partir de una lista permitida: parte de un evento vacío y copia solo la versión del agente (release), el
entorno (production o beta), un nombre de clase cerrado del fallo (nunca su texto), la familia del sistema operativo y una
versión aproximada (major.minor), la arquitectura, el nombre del tipo de Rust y los nombres de función del código propio del agente y de sus
dependencias y, en Windows, los identificadores de depuración de los ejecutables propios del agente. Nunca envía el texto del error, el usuario,
la petición, el nombre del equipo, ningún identificador de dispositivo ni rutas de ficheros, y no hay texto libre. Cada informe se firma con la clave del equipo y
no lleva cookie ni cabecera de reenvío. Un informe se descarta, sin reintento y sin alternativa directa, si no se alcanza la consola o esta no lo acepta.
Hay como mucho 20 por clase de fallo y 60 por proceso, de 256 KiB cada uno.
Para forzar que no salgan en un equipo, diga lo que diga la consola, crea el fichero marcador (su contenido se ignora; sobrevive a las actualizaciones; reinicia
el servicio después de crearlo) o define HODEI_SENTRY_DSN=off:
| Sistema | Fichero marcador |
|---|---|
| Linux, macOS | /etc/hodei-shield/telemetry-off |
| Windows | %ProgramData%\Hodei-Shield\telemetry-off |
Una herramienta de gestión de flotas puede crear el fichero antes o después de instalar el agente. Los comandos por sistema están en el inicio rápido.
Los agentes hasta la 2.22 se comportan de otro modo. Envían los informes de errores directamente al servicio de seguimiento de errores, activados por defecto desde
el 2026-10-06, y el fichero marcador (o HODEI_SENTRY_DSN=off) es la forma de excluir un equipo; en ese caso el servicio sí recibe la dirección IP
desde la que se envía el informe.
Dos puntos que también pertenecen a esta página:
- A dónde va: la región de la UE del servicio, según se midió en el binario publicado
v2.12.1. - Lo que no va en los informes de errores: los resultados de las
comprobaciones y su
detail. Esos van solo a la plataforma de tu organización.
7. Actualizaciones¶
La consulta. En cada ciclo (por defecto cada hora, sección 1), también
mientras el equipo está en pausa y mientras está detenido, pero no mientras está
dormido, el agente descarga un pequeño manifiesto de actualización firmado y
su firma primero desde el servidor público de descargas,
downloads.hodeishield.com; si no puede responder, desde nuestro almacén de
versiones: dos peticiones GET
simples a direcciones fijas. No llevan ningún identificador, token ni parámetro
tuyo. El servidor que responda, como cualquier servidor web, ve la dirección IP
de la conexión y la hora. Con update_edge = "none" el equipo usa solo el
almacén (véase la referencia de línea de comandos del agente). Un equipo cuyo propietario ha optado por no actualizar no hace ninguna de
las dos peticiones.
Qué sistemas. En el código de este repositorio solo Linux hace la consulta: en Windows y macOS se detiene antes de cualquier llamada de red, de modo que esas compilaciones no envían nada por este concepto. La excepción es una compilación beta de Windows generada con el interruptor de actualización de Windows activado (las betas de la 2.17.0, solo el canal beta); consulta y se actualiza como Linux. Qué compilaciones hay en uso no lo puede decir el código. En macOS, y en Windows en el canal estable (2.17.0 incluida), la actualización la hace a mano quien administra la máquina.
La petición a la consola. Solo cuando el manifiesto verificado ofrece una
versión más nueva, el agente envía a la consola una petición firmada,
POST /api/v1/agent/update-policy. A diferencia de la descarga del manifiesto,
esta petición sí lleva identificadores: el identificador del agente (el mismo
que agent_id en los sobres), el nombre del productor, la versión actual, el
sistema operativo, la arquitectura, el canal, la versión candidata con las
huellas (digest) de su manifiesto y de su paquete, un número aleatorio de un solo
uso, la hora de la petición y la firma. No lleva ningún resultado de
comprobaciones.
La descarga. Solo si la respuesta firmada de la consola lo permite (en Windows: aprueba el digest de ese MSI exacto), y quien administra el equipo ha fijado su identidad de actualización y no ha optado por salir, el agente descarga el paquete y su manifiesto por versión desde las direcciones que nombra el manifiesto firmado; en caso contrario el agente nunca sustituye un programa (véanse las notas de autoactualización del agente). En Windows, comprobar la firma del MSI puede hacer que el propio Windows descargue el certificado raíz de Microsoft mediante la actualización automática de raíces (visto el 2026-10-19); esa petición es de Windows, no del agente, y no lleva nada tuyo.
8. Qué muestra la ventana de estado, frente a lo que se envía¶
El agente tiene una ventana de estado y un icono de bandeja, ambos opcionales. Leen pequeños ficheros que el agente escribe en local (el principal es «la proyección»). No guardan ninguna clave, y el programa de la ventana no tiene un cliente HTTP entre sus dependencias, de modo que no tiene forma propia de llegar a la red.
| Se muestra en la máquina | Se envía a la plataforma |
|---|---|
| Si el agente está inscrito, su nombre, desde cuándo | Sí, en la práctica: el nombre del productor y el agent_id van en cada sobre |
| Para las cinco comprobaciones principales: correcto / requiere atención / error / no aplica, con un historial breve | Sí, los mismos resultados, junto con todos los demás |
| Cuántos elementos esperan en la cola sin conexión, la hora del último envío, el estado de actualización | No: la plataforma sabe lo que recibió, no lo que está en cola |
El detail de cualquier comprobación |
No se muestra nunca: la ventana no pinta detail. La plataforma sí lo recibe (sección 2) |
| Un aviso de escritorio cuando una comprobación empieza a fallar, solo si tu organización lo activó | No. Nada sobre si se mostró un aviso vuelve a la plataforma |
La ventana de estado tiene además un botón para volver a ejecutar una
comprobación en local. Lanza la línea de comandos check del propio agente como
un programa corriente con tu propia cuenta. Ese comando no envía nada y no
accede a la red.
Cómo funciona el aviso de escritorio y quién lo controla está en la sección siguiente.
9. Qué más podría salir, y tus controles¶
- Paquete de soporte.
hodei-shield diagnoseimprime un informe depurado (versiones, resumen de la configuración, permisos, estado de la inscripción, alcanzabilidad, tamaños de cola, el final del registro). Se imprime en tu pantalla y no va a ningún sitio salvo que lo adjuntes a una incidencia. Su única llamada de red es unGETal punto de salud de la plataforma, que--offlineomite. - Pausa. Un administrador puede pausar la evaluación y el envío en una
máquina (
hodei-shield pause;resumelo deshace). - Desinstalación y revocación. Véase la sección 8 de la guía rápida.
Lo que esta página no puede decirte¶
- No describe qué hace la plataforma con los datos cuando llegan: conservación, quién puede verlos, dónde se almacenan. Eso corresponde al aviso de privacidad de la consola, https://app.hodeishield.com/privacy.
- No lista los subencargados de la plataforma. El anexo del sitio web todavía no está publicado y se enlazará aquí cuando lo esté.
- No afirma que se haya revisado cada comprobación una por una para ver qué lee. Dice qué permite el código que salga de la máquina.
- El aviso de escritorio y la ventana de estado no se han verificado aún en un escritorio real; véase Qué muestra la ventana de estado.