Comprobaciones de salud del gateway de acciones de un agente local

Un gateway de acciones local está sano solo cuando puede rechazar la acción incorrecta, ejecutar la acción controlada correcta y dejar pruebas que resistan una revisión. Un monitor de procesos en verde demuestra muy poco. Indica que algo tiene un PID, pero no si la bóveda está bloqueada, si un agente puede llegar al gateway, si las credenciales inyectadas siguen funcionando o si el registro de auditoría guardó la llamada.

La diferencia importa con Sallyport porque la aplicación, la compuerta de la bóveda, la decisión de autorización, la acción externa y el registro de auditoría cifrado son puntos de fallo separados. Tratarlos como una única señal genérica de «salud» crea el peor tipo de monitor: uno que sigue en verde aunque el control del que dependes haya dejado de funcionar.

Construye esto como una pequeña suite de aceptación, no como un montón de comprobaciones de puertos. La suite debe usar destinos canary inofensivos, devolver pruebas que no sean secretas y clasificar correctamente una bóveda bloqueada. Si una persona debe desbloquear la bóveda con Touch ID, el monitor debe informar claramente de ese estado en vez de intentar sortearlo.

Una aplicación activa es solo la primera condición

Una sonda de disponibilidad debe responder a una pregunta concreta: ¿puede el Mac local iniciar y mantener activa la aplicación del gateway? No debe fingir que un proceso en ejecución demuestra que las acciones externas funcionan.

En una aplicación de la barra de menús, empieza con una comprobación local que un supervisor pueda ejecutar sin credenciales. El nombre exacto del proceso y la ubicación de instalación pueden variar entre versiones, así que guarda esos valores en un único archivo de configuración local en vez de repartirlos por los scripts. Una sonda básica de shell puede ser así:

#!/bin/sh
set -eu

APP_NAME="Sallyport"

if ! pgrep -x "$APP_NAME" >/dev/null 2>&1; then
  open -a "$APP_NAME"
  sleep 2
fi

if pgrep -x "$APP_NAME" >/dev/null 2>&1; then
  printf 'app=ready\n'
  exit 0
fi

printf 'app=unavailable\n' >&2
exit 2

La afirmación de este script es deliberadamente modesta. open -a pide a macOS que inicie una aplicación y pgrep observa el proceso después de esa petición. No demuestra que la aplicación haya terminado de inicializarse, que la bóveda pueda responder a una solicitud ni que su interfaz MCP acepte un cliente. Apple documenta Launch Services como la interfaz del sistema para iniciar y activar aplicaciones, por lo que iniciar la aplicación a través del sistema operativo es mejor que fijar una ruta de bundle.

Mantén la salida estructurada y sencilla. app=ready basta para un programador. No vuelques la salida de ps en un registro central donde los argumentos de comandos, nombres de usuario u otros detalles de procesos terminen como ruido permanente.

Un proceso puede existir aunque esté bloqueado. También puede faltar porque el Mac está suspendido, no hay ninguna sesión iniciada o se está reiniciando tras una actualización. La regla de alertas necesita un periodo de gracia para esas condiciones esperadas. Una comprobación que avise cada vez que alguien cierra la tapa del portátil acabará desactivada y no servirá durante un fallo real.

Por tanto, la señal útil de disponibilidad es local y limitada: la aplicación se inició, permaneció presente durante un breve intervalo de estabilización y un cliente MCP puede comenzar una sesión. La última parte pertenece a una sonda separada porque prueba otro límite.

El estado de la bóveda debe ser un resultado explícito

Una bóveda bloqueada está sana cuando rechaza acciones. Llamar a ese estado una interrupción confunde el comportamiento de seguridad con un fallo del servicio.

La compuerta de la bóveda de Sallyport es absoluta: mientras está bloqueada, toda acción se rechaza. En el hardware compatible de macOS, usa Secure Enclave y Touch ID. Una comprobación debe respetar esa regla. No escribas un script que introduzca contraseñas en una interfaz, almacene un token para sortear la biometría o trate una sesión de escritorio desbloqueada como prueba de que la bóveda debe desbloquearse.

Usa cuatro estados en lugar de un booleano:

• ready: la aplicación está disponible, la bóveda está desbloqueada y pueden ejecutarse comprobaciones controladas.
• locked: la aplicación está disponible, pero la bóveda rechaza correctamente las acciones.
• denied-unexpectedly: la bóveda está desbloqueada, pero la acción canary prevista fue rechazada.
• unavailable: la aplicación o su ruta MCP local no puede responder.

Este vocabulario evita un error operativo habitual. Muchos equipos programan una sonda con credenciales por la noche, ven fallos cuando se bloquea la pantalla y debilitan el sistema hasta que puede desbloquearse solo. No han arreglado la monitorización. Han eliminado la decisión humana que la bóveda debía exigir.

El patrón práctico tiene dos partes. Un trabajo desatendido registra la disponibilidad de la aplicación y el rechazo de una bóveda bloqueada. Una persona, o una sesión de estación de trabajo controlada que ya tenga aprobación humana, inicia las comprobaciones con credenciales después de desbloquearla. Registra el motivo en la salida:

{
  "run_id": "hc-2026-07-22T141501Z-8f29",
  "app": "ready",
  "vault": "locked",
  "http": "skipped",
  "ssh": "skipped",
  "audit": "verified",
  "reason": "credentialed checks require an unlocked vault"
}

El ID de ejecución no es un secreto. Da a los operadores algo estable que comparar después con el registro de actividad. No uses como ID de ejecución un nombre de usuario, el número de serie del equipo, una URL de endpoint ni una etiqueta de credencial.

La autorización por sesión y la aprobación por llamada también necesitan un tratamiento propio. Un proceso de agente nuevo puede requerir aprobación de sesión y una credencial puede requerir aprobación en cada uso. Es un comportamiento esperado, no una prueba inestable. El ejecutor debe indicar si está diseñado para una sesión aprobada o si una persona aprobará cada llamada. Un tiempo de espera silencioso no ayuda al siguiente investigador.

Usa destinos canary que demuestren la inyección de credenciales

Una comprobación HTTP debe llamar a un endpoint creado para validar una credencial canary concreta y devolver un resultado fijo que no sea secreto. Probar una URL pública solo demuestra que la red funciona. No dice si el gateway seleccionó la credencial prevista, la insertó en el encabezado correcto o la mantuvo alejada del agente.

Configura un servicio pequeño que acepte una ruta, un método y un formato de credencial. Guarda el secreto canary esperado en el lado del servicio y el mismo secreto en la bóveda del gateway. El cliente que inicia la acción nunca debe recibir el secreto, y el servicio nunca debe devolverlo en la respuesta.

El contrato de respuesta puede ser así de pequeño:

{
  "check": "agent-gateway-http",
  "result": "ok",
  "request_id": "7d7a0f3c"
}

El servicio debe devolver 401 cuando falte la credencial o sea incorrecta, 405 si se usa el método equivocado y 200 solo cuando haya llegado la credencial esperada. Genera request_id en el servicio y mantenlo opaco. No lo derives del encabezado de autorización ni de ninguna parte de la solicitud entrante.

Usa una ruta exclusiva como /agent-gateway-canary. No añadas la comprobación a un endpoint de producción existente. Los endpoints de producción acumulan con el tiempo límites de frecuencia, redirecciones, negociación de contenido, reglas de caché, efectos de facturación y cambios de permisos. Una ruta canary puede mantenerse deliberadamente simple.

RFC 9110 define la semántica de los métodos de solicitud y clasifica GET, HEAD, OPTIONS y TRACE como métodos seguros, pero en HTTP «seguro» significa que la acción solicitada no debería cambiar el estado previsto del recurso. No significa que la llamada sea inofensiva para tu cuenta, registros, cuotas o comportamiento posterior. Una API puede registrar un GET, cobrar una solicitud o activar un efecto secundario por una mala implementación. Crea una ruta cuyo comportamiento del servidor puedas inspeccionar en vez de confiar en un verbo conocido.

Una recomendación frecuente y mala consiste en usar curl con un token de API de producción como comprobación de salud. Es popular porque ocupa una línea. Está mal porque el historial del shell, la inspección de procesos, los registros de CI y la salida de errores crean demasiados lugares donde puede aparecer un token bearer. Además, evita el comportamiento que necesitas probar si el gateway normalmente inyecta las credenciales.

El ejecutor debe invocar el gateway a través de la misma ruta MCP que usa un agente. No inventes un cliente HTTP alternativo para la comprobación. Mantén la invocación específica del transporte detrás de un adaptador local, porque los nombres de herramientas y las formas de las solicitudes pueden cambiar. El adaptador recibe una acción lógica, pide al gateway conectado por MCP que la ejecute y emite solo el resultado normalizado.

{
  "action": "http_canary",
  "target": "canary-api",
  "method": "POST",
  "path": "/agent-gateway-canary",
  "expected_status": 200,
  "expected_check": "agent-gateway-http"
}

El adaptador debe ocultar datos en caso de error. Puede informar http_status=401, transport_error=timeout o response_schema=invalid. No debe imprimir encabezados salientes, el cuerpo de la solicitud, una URL completa con parámetros de consulta ni la respuesta sin procesar, salvo que hayas revisado esos datos y confirmado que son seguros.

Un éxito HTTP debe demostrar la acción prevista

Un 200 por sí solo es una prueba débil. La comprobación debe validar la respuesta del servicio, el método y la identidad del destino para que una redirección, una página de proxy o un fixture obsoleto no produzcan un falso positivo.

Haz que la respuesta canary identifique la prueba sin identificar una credencial. Compara algunos campos exactos:

status=200
check=agent-gateway-http
result=ok
request_id=7d7a0f3c

El comprobador debe aceptar cualquier request_id sintácticamente válido y guardarlo junto con el ID de ejecución. Debe rechazar un campo ausente, un cuerpo que afirme éxito con un estado que no sea 2xx y un tipo de contenido inesperado. Un portal cautivo, una página de error de un proxy corporativo o un registro DNS mal dirigido pueden devolver una respuesta HTTP válida. Eso es éxito del transporte, no éxito de la acción.

La documentación de curl señala algo relacionado: sin --fail o --fail-with-body, curl no trata un estado HTTP como 404 o 401 como un fallo del comando. Ese comportamiento es correcto para un cliente de transferencia general, pero sorprende a quienes escriben monitores que solo miran el estado de salida de curl. Si tu adaptador usa curl internamente, captura tanto el resultado del proceso como el estado HTTP y decide el éxito según tu contrato explícito.

No permitas que una comprobación siga redirecciones automáticamente, salvo que formen parte del diseño previsto del endpoint. Una redirección puede enviar la llamada canary a una página de inicio de sesión que devuelva 200, o a otro host que no pretendías contactar. Fija el origen HTTPS en la configuración, valida el certificado mediante la pila normal del cliente y registra la identidad final del par solo si ese registro no puede revelar datos de red sensibles.

Los tiempos de espera necesitan etiquetas separadas. Un fallo de DNS, un rechazo TCP, un fallo de validación TLS, un rechazo del gateway, un 401 del servicio superior, un 500 del servicio superior y una respuesta que no coincide tienen responsables distintos. Si el ejecutor llama a todos http=failed, perderás los primeros diez minutos de cada incidente intentando descubrir dónde se detuvo la solicitud.

Un registro de fallo útil puede ser este:

{
  "run_id": "hc-2026-07-22T141501Z-8f29",
  "check": "http_canary",
  "outcome": "failed",
  "stage": "upstream_response",
  "http_status": 401,
  "request_id": null,
  "secret_material": "redacted"
}

La línea secret_material es un recordatorio para quienes leen el registro, no una prueba de que la ocultación haya funcionado. Demuestra la ocultación con pruebas: haz que el canary rechace deliberadamente la credencial, captura la salida estándar y de error del ejecutor y busca el secreto de prueba en esos archivos. No debe aparecer. Repite la prueba con JSON incorrecto, un tiempo de espera, un fallo TLS y un error de herramienta del agente. Los secretos suelen escapar por las rutas de error.

SSH necesita un destino cercado, no un shell de inicio de sesión

Una comprobación SSH debe demostrar la autenticación y la ejecución de comandos contra una cuenta dedicada cuyo servidor rechace la ejecución de comandos arbitrarios. Una conexión correcta a un host administrativo general demuestra demasiado en la dirección equivocada: proporciona un shell útil a la credencial de salud.

Crea una cuenta separada, como gateway-health, en un host de prueba controlado. Dale un comando forzado en authorized_keys o una restricción equivalente del lado del servidor. El comando forzado debe ignorar el comando original, escribir una marca de tiempo y un ID de ejecución opaco en un archivo de auditoría local y devolver una respuesta constante.

Una entrada conceptual de authorized_keys sería:

command="/usr/local/libexec/gateway-health",no-port-forwarding,no-agent-forwarding,no-X11-forwarding,no-pty ssh-ed25519 AAAA... gateway-health

La clave pública pertenece a la identidad canary del gateway. La clave privada permanece en la bóveda. El texto AAAA... está incompleto deliberadamente: debes generar tus propias claves y no copiar un ejemplo en un archivo de producción.

El comando del servidor debe evitar mostrar $SSH_ORIGINAL_COMMAND, variables de entorno o detalles de autenticación. Puede devolver un formato fijo:

{"check":"agent-gateway-ssh","result":"ok","receipt":"c2b91a"}

Si necesitas un ID de ejecución para correlacionar registros, pasa un token opaco en el comando enviado y haz que el comando forzado valide un formato estricto, como caracteres hexadecimales de longitud fija. Nunca aceptes una cadena arbitraria y la escribas en un comando de shell, un nombre de archivo o una línea de registro. Mejor aún, deja que el servidor genere el comprobante y relaciona los registros por intervalo temporal durante la investigación.

La comprobación debe fallar si el servidor permite un shell interactivo, reenvía un puerto, asigna un TTY o ejecuta otro comando distinto del forzado. Son regresiones de configuración. Merecen una gravedad distinta de un tiempo de espera de red rutinario porque cambian la exposición de la credencial canary.

No reutilices la identidad SSH de los despliegues. Reutilizarla facilita la configuración de la comprobación, pero convierte un fallo de monitorización en un problema de acceso amplio. Una credencial de salud debe tener una sola función, una cuenta de destino y ningún permiso más allá de producir el comprobante.

Sallyport envía SSH mediante su asistente sin estado integrado sp-ssh. Por tanto, la prueba debe pasar por la ruta normal de acciones del gateway en vez de invocar una clave privada local con OpenSSH. De lo contrario, solo habrás comprobado el host y la cuenta, y habrás omitido el límite de credenciales que necesitas demostrar.

La verificación de auditoría es una afirmación separada

Una acción canary correcta y un registro de auditoría válido son afirmaciones distintas. Verifica ambas.

El registro de actividad te dice que el gateway registró una acción individual. El registro de sesión informa sobre la ejecución del agente y te permite revocarla. Ninguno sustituye la comprobación del efecto remoto, porque una solicitud puede registrarse antes de que falle el servicio superior. Del mismo modo, un sistema remoto puede recibir una solicitud mientras falla la ruta de registro local. Necesitas correlación, no suposiciones.

Para cada acción HTTP o SSH correcta, recopila tres pruebas que no sean secretas:

• el ID de ejecución de salud generado por el ejecutor;
• el comprobante opaco o ID de solicitud generado por el servicio canary;
• la hora local de la acción, registrada en UTC.

Después inspecciona el diario de actividad para comprobar los metadatos seguros de conservar, como canal, resultado de la acción, alias del destino y hora. No esperes que el diario contenga credenciales en texto plano. No debe hacerlo. Tampoco le exijas reproducir el cuerpo de respuesta remoto. El comprobante pertenece al sistema canary remoto, no al almacén de secretos del gateway.

Sallyport proyecta sus diarios Sessions y Activity desde un registro de auditoría cifrado, encadenado mediante hashes y ciego a escritura. Ejecuta su comprobación de integridad sin conexión como parte independiente de la suite:

sp audit verify

Un comando correcto debe registrarse como audit=verified; un resultado distinto de cero es un incidente de integridad hasta que se demuestre lo contrario. Esta verificación no necesita la clave de la bóveda, por lo que sirve para una comprobación local desatendida incluso cuando la bóveda está bloqueada.

No reduzcas la verificación de auditoría a «existe un archivo de registro». La existencia del archivo detecta muy poco. Un archivo truncado, registros sustituidos, una cadena rota o un escritor que se detuvo después del inicio pueden coexistir con una ruta que parece normal en Finder.

Hay otro error fácil: comprobar solo que la cadena de auditoría es válida. Una cadena puede ser válida y aun así carecer del evento esperado si el gateway nunca intentó la acción. Combina la verificación de la cadena con una afirmación de presencia del evento después de cada acción canary. Define un intervalo razonable para la llegada de la proyección local e informa de forma separada del retraso y del evento ausente. Un diario retrasado puede requerir investigación, pero no equivale a una escritura fallida.

Mantén el ejecutor fuera del límite de confianza que comprueba

El ejecutor de salud debe coordinar acciones y evaluar pruebas. No debe guardar credenciales, analizar archivos de la bóveda ni leer el estado de la aplicación que contiene secretos.

Una disposición práctica tiene cuatro componentes:

1. Un programador local inicia un ejecutor pequeño con una cuenta de macOS dedicada.
2. El ejecutor comprueba la presencia de la aplicación e invoca un adaptador MCP local.
3. El adaptador solicita acciones canary con nombre a través del gateway y devuelve resultados estructurados y depurados.
4. El ejecutor verifica la integridad de auditoría y escribe un informe breve en un directorio local protegido.

La cuenta dedicada no debe tener acceso a los archivos de datos de la bóveda. Apple coloca los datos de soporte de aplicaciones macOS no aisladas en el directorio ~/Library/Application Support del usuario actual, pero un monitor no debe suponer que puede o debe inspeccionar esos archivos. La comprobación necesita comportamiento, no una copia del contenido de la bóveda.

Mantén la configuración declarativa y sin secretos. Este ejemplo da al ejecutor suficiente información para validar resultados sin revelar credenciales:

checks:
  http_canary:
    target_alias: canary-api
    expected_status: 200
    expected_check: agent-gateway-http
    timeout_seconds: 10
  ssh_canary:
    target_alias: canary-ssh
    expected_check: agent-gateway-ssh
    timeout_seconds: 10
  audit:
    command: sp audit verify
    timeout_seconds: 15

Los alias de destino importan. Un alias es menos sensible que una URL completa o un nombre de host y obliga a hacer explícita la selección del destino en la configuración del gateway. Si un operador cambia un alias, la comprobación debe indicar que hace falta revisar la configuración antes de empezar silenciosamente a probar otro lugar.

No des al ejecutor permiso para aprobar un proceso de agente nuevo. La autorización por sesión está activada de forma predeterminada por una razón. La primera llamada de un proceso de agente nuevo identifica su autoridad de firma de código en la tarjeta de aprobación, y la aprobación dura solo durante esa ejecución. Si necesitas comprobaciones programadas después de que una persona lo apruebe, prepara un proceso de cliente de salud duradero y revisado. Si el proceso termina, espera que la siguiente ejecución vuelva a pedir aprobación.

Es algo menos cómodo que una cuenta de automatización oculta y siempre aprobada. También evita que un ejecutable nuevo obtenga permiso solo por copiar la línea de comandos de la comprobación de salud.

Una comprobación fallida necesita un diagnóstico útil

La mayoría de los fallos de salud del gateway son simples desviaciones de configuración. Lo peligroso es que la respuesta habitual consiste en debilitar los controles en vez de localizar el límite que se rompió.

Imagina una secuencia realista. La aplicación está activa. La bóveda está desbloqueada. El canary HTTP devuelve 401. El primer impulso es pegar el token canary en un shell y llamar directamente al endpoint. No lo hagas. Demuestra que el token funciona, pero evita la bóveda y crea una nueva ruta de filtración del secreto.

Sigue las pruebas en este orden:

1. Confirma que el adaptador MCP local llegó al gateway y recibió un resultado de acción, en vez de agotar el tiempo antes del envío.
2. Confirma que el alias de destino todavía selecciona la credencial almacenada y la configuración del endpoint previstas.
3. Comprueba en los registros del servicio canary el ID de solicitud opaco, el método, la ruta y el motivo del rechazo. No registres el valor de autorización recibido.
4. Inspecciona el diario de actividad para encontrar el intento de acción correspondiente y verifica la cadena de auditoría con sp audit verify.
5. Rota la credencial canary si la revisión de configuración muestra que su valor esperado cambió o pudo quedar expuesto.

Esta secuencia separa cuatro fallos que de otro modo parecen idénticos: un mapeo incorrecto del destino, un secreto revocado o rotado, un fallo de inyección del gateway y un cambio de configuración del servicio superior. También evita el incidente habitual en el que un operador «prueba» un secreto en un terminal y luego lo encuentra copiado en el historial del shell, el búfer de desplazamiento o un paquete de soporte.

Clasifica la gravedad según el control que falló. Una aplicación no disponible es un problema de disponibilidad. Una bóveda bloqueada que rechaza una acción es informativa, salvo que se esperara una comprobación programada y aprobada. Una acción canary que tiene éxito mientras la bóveda informa de estar bloqueada es un incidente de seguridad. Una cadena de auditoría rota también lo es, aunque ambos destinos canary sigan devolviendo éxito.

No ocultes estas categorías detrás de una única insignia roja o verde. El operador que ve vault=locked, audit=verified y http=skipped sabe exactamente qué hacer. El operador que ve health=warning empieza a adivinar.

El calendario mínimo útil tiene dos líneas

Ejecuta con frecuencia las comprobaciones que no usan secretos y después ejecuta las acciones canary con credenciales de forma puntual y deliberada. Las dos líneas producen menos ruido y ofrecen mejores pruebas.

La línea desatendida puede ejecutarse siempre que se espere que el Mac esté activo. Comprueba que la aplicación está presente, que una bóveda bloqueada rechaza la acción, que la ruta MCP puede devolver una respuesta clasificada y que sp audit verify tiene éxito. Ninguna de estas comprobaciones debe exigir extraer una credencial o desbloquear la bóveda.

La línea con credenciales se ejecuta después de que una persona desbloquee la bóveda y apruebe la sesión del cliente de salud si es necesario. Realiza una acción canary HTTP y otra SSH, confirma los comprobantes remotos, comprueba los registros de actividad locales correspondientes y vuelve a verificar la cadena de auditoría. Usa una frecuencia moderada. Cada acción con credenciales se convierte en un evento de auditoría y en un evento del servicio remoto, así que una comprobación cada minuto genera ruido sin aportar mucha más confianza.

Ejecuta la línea con credenciales después de cambios en la configuración de credenciales, alias de destino, herramientas del agente, permisos de macOS, controles de red o la aplicación del gateway. Ese momento detecta los cambios con más probabilidades de romper la ejecución de acciones y ofrece a quien revisa un registro claro de antes y después.

El criterio es sencillo: una suite de salud debe demostrar los controles en los que piensas confiar. Si solo puede demostrar que el icono de una aplicación sigue en la barra de menús, llámala sonda de disponibilidad y detente ahí. No la presentes como prueba de que los agentes autónomos pueden actuar de forma segura.