La aprobación de agentes en macOS debe distinguir cada compilación

Aprobar un agente de IA por un nombre de comando conocido es una forma de aprobar el ejecutable equivocado. En un mismo Mac es fácil acumular una versión del proveedor, una beta, una copia instalada mediante un gestor de paquetes y una compilación desde el código fuente, todas con el mismo nombre. Si tu límite de aprobación no puede distinguirlas, una decisión tomada para una compilación revisada puede aplicarse silenciosamente a otra.

La solución no es crear una lista de permitidos más larga. Debes decidir qué propiedades identifican una ejecución del agente en tu entorno, comprobar que cada copia instalada tiene las propiedades esperadas y probar el comportamiento de la aprobación con ambas copias presentes. Las rutas, las firmas, los requisitos designados y los hashes responden a preguntas diferentes. Confundirlos es lo que causa problemas.

Un mismo nombre de comando puede apuntar a varios ejecutables

Un comando del shell es una búsqueda, no una identidad. Cuando escribes claude, agent o el nombre de un envoltorio, el shell puede resolver un alias, una función, un shim, un enlace simbólico, un directorio del gestor de paquetes o un archivo que aparece antes en PATH que la copia que tenías en mente.

Empieza en el terminal, el editor, el servicio de lanzamiento o el ejecutor de automatización que realmente inicia el agente. No inspecciones un shell interactivo conveniente y supongas que el resultado se aplica en todas partes. Los shells de inicio de sesión, las aplicaciones gráficas y los ejecutores de CI suelen recibir variables de entorno diferentes.

Ejecuta primero:

type -a agent-name
command -v agent-name

Un resultado útil podría verse así:

agent-name is /Users/me/bin/agent-name
agent-name is /opt/homebrew/bin/agent-name
agent-name is /usr/local/bin/agent-name
/Users/me/bin/agent-name

La salida indica que la primera ruta tiene prioridad en este shell. No indica si /Users/me/bin/agent-name es un binario directo, un enlace simbólico, un script que inicia otro binario o un envoltorio que cambia las variables de entorno antes de cederle el control.

Resuelve el archivo antes de inspeccionarlo:

BIN="$(command -v agent-name)"
python3 - <<'PY' "$BIN"
import os, sys
print(os.path.realpath(sys.argv[1]))
PY
file "$BIN"

Si file informa de que es un script de shell, léelo. Si informa de que es un enlace simbólico, inspecciona el destino. Si informa de que es un ejecutable Mach-O universal, inspecciona ese ejecutable. Un envoltorio puede hacer que la pantalla de aprobación parezca correcta y lanzar después un proceso hijo diferente.

No te detengas al encontrar la copia que gana ahora. Haz un inventario de todos los resultados de type -a, además de las copias que estén en la carpeta Applications del proveedor, en Downloads, en el checkout del código fuente y en los directorios del gestor de paquetes. La copia que gana hoy puede perder mañana después de una actualización del gestor de paquetes o de un pequeño cambio en PATH.

Una ruta demuestra ubicación, no identidad

Los equipos suelen empezar con una regla de ruta porque las rutas son fáciles de leer. /Applications/Agent.app parece deliberado. /Users/me/dev/agent/bin/agent parece experimental. Son pistas útiles, pero una ruta por sí sola no puede demostrar qué código se encuentra allí ahora.

Un gestor de paquetes puede reemplazar el archivo al que apunta un enlace simbólico estable. Un instalador directo puede sobrescribir un paquete de aplicación en el mismo lugar. Una compilación local puede usar siempre la misma ruta de salida. Un atacante con suficientes permisos de escritura puede sustituir un archivo situado en una ruta aprobada. La ruta solo indica dónde lo encontró el cargador.

Usa cuatro campos independientes en tu inventario:

La distinción importa porque cada campo cambia a un ritmo diferente. Una actualización del proveedor puede conservar la ruta y el requisito designado, pero cambiar el hash. Una beta puede conservar la autoridad de firma y usar otro identificador de paquete. Una compilación local puede tener la misma revisión del código fuente que una versión publicada, pero llevar una firma ad hoc o no tener ninguna.

La Technical Note TN2206 de Apple explica el papel previsto del requisito designado: debe coincidir con las actualizaciones legítimas de un programa y excluir el código no relacionado. Es un mecanismo de continuidad. No responde por sí solo a «¿me refería exactamente a este binario?». Apple también señala que el requisito predeterminado se genera a partir de la configuración de firma, por lo que su amplitud depende de cómo haya firmado la compilación el desarrollador.

Los sistemas de aprobación necesitan la misma separación. Confiar en la próxima versión compatible de un proveedor es una decisión distinta de confiar en un artefacto de lanzamiento exacto. Si tratas ambas decisiones como una sola, no podrás explicar qué aprobó el usuario.

Inspecciona la firma antes de crear una regla de aprobación

Para cada ejecutable candidato, guarda los detalles de su firma y su hash. Los siguientes comandos solo usan herramientas incluidas en macOS, además de shasum:

inspect_agent() {
  target="$1"
  echo "=== $target ==="
  echo "Resolved path: $(python3 - <<'PY' "$target"
import os, sys
print(os.path.realpath(sys.argv[1]))
PY
)"
  shasum -a 256 "$target"
  codesign --display --verbose=4 "$target" 2>&1 \
    | grep -E '^(Executable|Identifier|TeamIdentifier|Authority|CDHash)='
  codesign --display -r- "$target" 2>&1 \
    | sed -n '/designated/,$p'
  codesign --verify --strict --verbose=2 "$target" 2>&1
}

inspect_agent "$(command -v agent-name)"

Importa más la forma de la salida que una cadena concreta del proveedor:

=== /opt/homebrew/bin/agent-name ===
Resolved path: /opt/homebrew/Cellar/agent-name/2.4.1/bin/agent-name
3b1f...  /opt/homebrew/bin/agent-name
Executable=/opt/homebrew/bin/agent-name
Identifier=com.example.agent
TeamIdentifier=AB12CDE345
Authority=Developer ID Application: Example, Inc. (AB12CDE345)
CDHash=9c1a...
designated => anchor apple generic and identifier "com.example.agent" and certificate leaf[subject.OU] = "AB12CDE345"
/opt/homebrew/bin/agent-name: valid on disk
/opt/homebrew/bin/agent-name: satisfies its Designated Requirement

No trates el CDHash mostrado como sustituto de tu registro SHA-256. El hash de CodeDirectory forma parte del mecanismo de firma de código y puede variar según la estructura de la firma. shasum -a 256 te proporciona una huella exacta y familiar del archivo para un registro de prueba. Guarda ambos cuando investigues una colisión.

En un paquete de aplicación, inspecciona el ejecutable real y no solo el directorio del paquete. Encuéntralo con:

APP="/Applications/Agent.app"
EXEC="$APP/Contents/MacOS/$(defaults read "$APP/Contents/Info" CFBundleExecutable)"
inspect_agent "$EXEC"

Si el agente inicia un auxiliar, inspecciona también el auxiliar. El ejecutable que abre una ventana de terminal no siempre es el proceso que realiza llamadas HTTP o inicia SSH. El sistema de aprobación debería identificar el proceso que solicita la acción sensible, mientras que la prueba debe verificar toda la cadena de lanzamiento.

La TN3127 más reciente de Apple va más allá de la guía de firma anterior: muestra cómo difieren los requisitos designados predeterminados según el tipo de firma y por qué las variantes distribuidas por separado pueden no ser compatibles entre sí. Es una advertencia contra las suposiciones. Compara el texto real del requisito de los archivos instalados.

Las compilaciones estable, beta, del gestor de paquetes y locales necesitan una matriz de pruebas

Haz que el inventario sea concreto. Elige las copias que podrían existir razonablemente en tu Mac, asigna a cada una una etiqueta corta y registra qué esperas que compartan o no compartan con las demás.

La tabla no dicta cuál es la respuesta correcta. Evita la respuesta fácil: suponer que el nombre de un canal aporta información suficiente. Una beta puede estar firmada exactamente igual que la versión estable. Una copia del gestor de paquetes puede ser un artefacto del proveedor sin modificar, un artefacto reempaquetado o un script que descarga otro ejecutable. Una compilación local puede tener una firma de desarrollo válida que parezca más oficial de lo que realmente es.

Crea una fila por cada copia instalada en un archivo de texto que guardes junto con las notas de configuración del agente:

label: stable
launch path: /Applications/Agent.app/Contents/MacOS/agent-name
resolved path: /Applications/Agent.app/Contents/MacOS/agent-name
version: 2.4.1
identifier: com.example.agent
team or authority: AB12CDE345
sha256: 3b1f...
designated requirement: anchor apple generic and identifier "com.example.agent" ...
expected approval group: release

label: local
launch path: ~/src/agent/build/agent-name
resolved path: /Users/me/src/agent/build/agent-name
version: git revision recorded separately
identifier: ad hoc or absent
team or authority: none
sha256: 8e52...
designated requirement: unavailable or different
expected approval group: local only

Registra la versión, pero no bases la decisión en el número de versión. Las cadenas de versión son metadatos de la aplicación. Un archivo puede declarar una versión que no coincide con el lanzamiento que creías haber descargado. La firma y el hash ofrecen datos independientes.

El caso incómodo son dos filas con el mismo identificador, equipo y requisito designado, pero con hashes diferentes. No es necesariamente un defecto. Significa que el proveedor ha creado dos compilaciones que macOS puede considerar instancias del mismo programa. Si quieres que la aprobación siga al canal de lanzamiento del proveedor, puede ser aceptable. Si necesitas que cubra solo un artefacto concreto, la regla es demasiado amplia.

La prueba equivocada aprueba cada copia por separado

Probar la compilación estable el lunes y la beta el martes demuestra muy poco sobre la cobertura entre ambas. Cada prueba puede mostrar una solicitud porque todavía no existe una aprobación activa. Necesitas tener ambas copias instaladas y mantener viva una sesión de una mientras la otra solicita acceso.

Ejecuta esta secuencia en una cuenta desechable o con credenciales que no puedan modificar sistemas de producción:

1. Coloca las copias estable, beta, del gestor de paquetes y local. Confirma sus rutas resueltas y guarda la salida de la inspección.
2. Borra o revoca la sesión existente del agente mediante la herramienta de aprobación que uses. Confirma que la próxima llamada sensible exigirá una decisión nueva.
3. Inicia la copia estable y haz una llamada inofensiva a un endpoint de prueba. Aprueba solo esa ejecución. Mantén el proceso activo.
4. Mientras el proceso estable siga activo, inicia la copia beta y haz la misma llamada inofensiva. Observa si solicita aprobación e inspecciona la identidad del proceso que aparece en la tarjeta.
5. Repite la prueba con las copias del gestor de paquetes y local. Después invierte el orden de PATH y repite la prueba del gestor de paquetes.

El resultado que buscas depende de la regla elegida. Si estable y beta deben estar separadas, la beta debe solicitar aprobación mientras la estable sigue aprobada. Si comparten intencionadamente un grupo de aprobación, la tarjeta y el registro de auditoría deben mostrar suficientes detalles para que la agrupación sea evidente para quien la revise.

No llames a una API de producción durante esta prueba. Usa un endpoint de prueba que devuelva una respuesta fija y deje una marca visible e inofensiva en sus propios registros. Para SSH, usa una cuenta de prueba con un comando limitado a mostrar información de identidad:

ssh [email protected] 'id; hostname; date -u +%FT%TZ'

La prueba tiene dos observaciones: lo que dice la pantalla de aprobación y lo que registra el sistema de destino. Guarda la marca de tiempo, el hash del ejecutable, el ID del proceso y la marca devuelta. Si un envoltorio cambió qué ejecutable se ejecutó realmente, la discrepancia aparecerá antes que en una conversación posterior a un incidente.

Un fallo habitual se ve así. Un desarrollador aprueba la aplicación estable y después instala una beta que añade /Users/me/bin antes de /Applications mediante un cambio en la configuración del shell. El nombre del comando no cambia. La beta realiza una llamada sin una nueva solicitud porque la comprobación de autorización reconoce una identidad de firma compartida o una agrupación de procesos demasiado amplia. Nadie lo nota porque el proceso estable original sigue funcionando y el registro de auditoría solo dice agent-name. Evitas este fallo obligando a realizar la prueba con solapamiento, no leyendo las notas de lanzamiento.

La identidad del proceso y los bytes exactos responden a preguntas distintas

Una aprobación puede asociarse razonablemente a una identidad de proceso firmado que permanezca estable entre actualizaciones. También puede asociarse a los bytes exactos. Ninguna opción es correcta en todos los casos.

Usa la identidad del proceso cuando pretendas confiar en una línea de lanzamiento mantenida por un firmante conocido. Así no obligas al usuario a aprobar cada actualización menor solo porque cambió el hash del ejecutable. También permite que una identidad de proceso fija sobreviva a una actualización normal.

Usa los bytes exactos cuando la compilación sea experimental, se haya producido localmente, tenga parches independientes o proceda de un canal que no quieras mezclar con la versión estable. Fijar un hash resulta especialmente útil para una investigación o reproducción breve en la que quieras que la decisión deje de ser válida cuando cambie el archivo.

El punto intermedio peligroso consiste en fingir que un identificador de firma por sí solo es una identidad. Apple documenta que varios firmantes pueden declarar el mismo identificador de firma. Apple recomienda combinarlo con las restricciones de validación y de equipo pertinentes al comprobar el código. En la práctica, Identifier=com.example.agent sin la autoridad o el equipo es una etiqueta que otra persona puede reutilizar.

Un requisito designado suele ser más sólido porque puede combinar el identificador con restricciones sobre la autoridad de firma. Aun así, puede ser más amplio que tu intención. Un requisito que acepte cualquier compilación válida firmada por un equipo con un identificador concreto puede incluir correctamente una actualización estable, una beta y una compilación local de prueba generada por el proveedor. Solo es bueno si realmente quieres que las tres pertenezcan al mismo grupo de aprobación.

Escribe la decisión del grupo en lenguaje sencillo junto a la entrada del inventario. Por ejemplo:

Release group: accept future vendor-signed builds with the release identifier.
Beta group: separate, even when signed by the same vendor identity.
Local group: exact SHA-256 only; rebuild requires another approval.

Esa nota obliga a tomar la decisión antes de que la interfaz pida hacer clic. También deja claro si tus herramientas pueden expresar la distinción. Si no pueden, usa un límite operativo más estrecho, como la aprobación por llamada para las compilaciones beta y locales, hasta que puedan hacerlo.

La aprobación por sesión no sustituye a la aprobación por llamada

La aprobación por sesión responde a «¿puede este proceso del agente ejecutarse con acceso durante esta ejecución?». La aprobación por llamada responde a «¿puede usarse ahora esta credencial concreta para esta acción concreta?». El primer control limita qué proceso obtiene una sesión. El segundo limita las consecuencias de esa sesión.

Sallyport utiliza una escala fija de decisiones: una bóveda bloqueada deniega todas las acciones, un proceso nuevo del agente normalmente necesita aprobación de sesión y determinadas credenciales pueden exigir una aprobación nueva en cada uso. La tarjeta de aprobación muestra primero la autoridad de firma de código del proceso, una evidencia útil, pero aun así debes realizar la prueba de solapamiento cuando existan varias compilaciones.

Usa la comprobación más frecuente para las credenciales que puedan causar cambios irreversibles o visibles externamente. Las credenciales de despliegue en producción, las API administrativas destructivas y el acceso SSH que pueda modificar infraestructura compartida no deberían heredar confianza solo porque un proceso del agente fuera aceptable al comienzo de una ejecución larga.

No resuelvas una colisión de binarios marcando todas las credenciales para aprobación en cada llamada y para siempre. Eso convierte un problema de diseño en fatiga de aprobaciones. Las personas terminan aprobando avisos repetidos y previsibles sin leerlos. Separa las compilaciones que no deberían compartir acceso y reserva la aprobación por llamada para las acciones en las que una persona deba ver el momento de uso.

En una puerta de enlace de acciones, prueba la misma matriz en el límite de la acción. Inicia cada binario, realiza una solicitud HTTP de prueba y un comando SSH de prueba si usas ambos canales, y compara el registro de sesión con el registro de la llamada individual. Los registros deberían permitirte responder qué ejecutable inició la solicitud, qué aprobación la cubrió y si la credencial exigió otra confirmación.

Los gestores de paquetes y los shims ocultan el ejecutable que debes inspeccionar

Los gestores de paquetes suelen instalar rutas de entrada estables que apuntan a otro lugar. Un comando en /opt/homebrew/bin/agent-name puede ser un enlace simbólico a un directorio Cellar con versiones. Otra herramienta puede instalar un shim de JavaScript, Python o shell que elige un entorno de ejecución y carga después un paquete desde un directorio de caché.

Sigue la cadena hasta llegar al proceso que realiza la solicitud sensible. Estos comandos ayudan en los casos habituales:

ls -l "$(command -v agent-name)"
readlink "$(command -v agent-name)" || true
head -n 40 "$(command -v agent-name)" 2>/dev/null || true

En macOS, readlink puede mostrar solo un salto. El pequeño resolvedor de Python de la primera sección es más fiable para encontrar el destino final. Si el archivo de entrada es un script, busca exec, invocaciones del entorno de ejecución, rutas de binarios descargados y variables de entorno que seleccionen un canal de lanzamiento.

No supongas que una versión del gestor de paquetes equivale a la versión del proveedor con el mismo número. El paquete puede aplicar parches, reempaquetar un binario, compilar desde el código fuente o iniciar otro entorno de ejecución. Trata el ejecutable instalado como aquello que apruebas y conserva el recibo del paquete solo como contexto adicional.

La misma advertencia se aplica a las extensiones del IDE y a las integraciones de terminal. Un lanzador gráfico puede incluir una copia mientras tu shell usa otra. Prueba cada punto de entrada que pueda iniciar un agente. Que funcione correctamente en Terminal no demuestra nada sobre una tarea en segundo plano iniciada por un editor.

Las compilaciones locales deben dejar claro que son locales

Una compilación local resulta útil precisamente porque puede diferir de una versión publicada. Puede contener un parche, una actualización de dependencia no revisada, un cambio del compilador, una opción de depuración o un archivo generado que nunca entró en el artefacto del proveedor. No debería tomar silenciosamente la reputación de aprobación de la versión publicada.

Primero inspecciona su estado de firma:

LOCAL="$HOME/src/agent/build/agent-name"
codesign --display --verbose=4 "$LOCAL" 2>&1 | sed -n '1,25p'
codesign --verify --strict --verbose=2 "$LOCAL" 2>&1
shasum -a 256 "$LOCAL"

Una salida sin firma, una firma ad hoc y una firma de desarrollo no son equivalentes. Un ejecutable sin firma ofrece a la capa de aprobación una identidad menos duradera. Una firma ad hoc puede hacer que un archivo parezca firmado sin vincularlo a una identidad de desarrollador. Una firma de desarrollo identifica un contexto de desarrollo, pero tampoco convierte el archivo en un artefacto de lanzamiento.

La opción predeterminada más segura es sencilla: coloca los binarios locales en un directorio separado, asígnales un nombre de comando visiblemente diferente si controlas la compilación y exige una aprobación nueva cada vez que cambie el hash. Si no puedes cambiar el nombre del comando, deja clara la ruta resuelta y el estado de compilación local en tu manual de operaciones y en la salida de las pruebas.

Evita el consejo popular de volver a firmar cada compilación local con el mismo certificado utilizado para los lanzamientos solo para reducir las solicitudes. Es popular porque facilita el desarrollo. Es incorrecto cuando tu modelo de aprobación utiliza la autoridad de firma como un límite importante. Has ampliado la identidad de lanzamiento para incluir todas las máquinas y scripts que puedan acceder a ese certificado. Mantén el material de firma de lanzamiento fuera de las compilaciones locales habituales, salvo que tu proceso de lanzamiento pueda sostener esa afirmación.

Los registros de auditoría deben permitir reconstruir la decisión más adelante

Un registro de aprobación que solo diga «agente aprobado» ofrece pruebas débiles. Seis semanas después no podrás saber si el programa aprobado procedía del instalador estable, de la carpeta beta, de un enlace simbólico del gestor de paquetes o de un checkout local.

Para cada prueba y cambio operativo importante, conserva estos datos:

• la ruta de lanzamiento y la ruta final resuelta
• el identificador de firma, la autoridad o el equipo y el texto del requisito designado
• el hash SHA-256 y la versión de la aplicación
• el ID del proceso, la hora de inicio y el resultado de la sesión
• el destino de la acción y el resultado de la llamada individual

Sallyport guarda las ejecuciones de los agentes en su diario Sessions y las acciones individuales en su diario Activity, ambos proyectados desde un registro de auditoría cifrado y encadenado mediante hashes. Su comprobación sin conexión sp audit verify puede establecer si la cadena de ese registro cifrado sigue verificándose, pero la integridad del registro no completa los campos de identidad que nunca capturaste. Incluye las pruebas del ejecutable en el contexto del evento mientras aún puedas inspeccionar la máquina.

Ejecuta una verificación de auditoría después de cambiar la matriz de compilaciones, revocar una sesión y repetir la prueba de solapamiento. Debes confirmar dos cosas: que el sistema registró las ejecuciones separadas que esperabas y que la cadena de registros sigue verificándose cuando se lee de forma independiente. Una cadena intacta demuestra la continuidad del registro, no que tu decisión original de agrupación fuera acertada.

Convierte esto en una prueba de regresión, no en una limpieza puntual

Las copias múltiples vuelven. Alguien instala una beta para probar una corrección. Un gestor de paquetes se actualiza durante la noche. Un compañero comparte una compilación local. La aplicación estable se actualiza en el mismo lugar. Si solo pruebas después de un susto, descubrirás la colisión cuando el agente ya tenga acceso.

Conserva un script corto que escriba un informe con marca de tiempo para cada ruta candidata. Ejecútalo después de cambiar instalaciones, antes de conceder una credencial de alto impacto y cada vez que modifiques los archivos de inicio del shell o la configuración del agente del editor.

#!/bin/zsh
set -eu

for candidate in \
  "/Applications/Agent.app/Contents/MacOS/agent-name" \
  "/opt/homebrew/bin/agent-name" \
  "$HOME/src/agent/build/agent-name"; do
  [[ -e "$candidate" ]] || continue
  echo "### $candidate"
  echo "resolved: $(python3 -c 'import os,sys; print(os.path.realpath(sys.argv[1]))' "$candidate")"
  shasum -a 256 "$candidate"
  codesign --display --verbose=4 "$candidate" 2>&1 \
    | grep -E '^(Identifier|TeamIdentifier|Authority|CDHash)=' || true
  codesign --display -r- "$candidate" 2>&1 \
    | grep 'designated' || true
  echo
 done

Compara el informe con la última copia revisada. Un hash cambiado es normal después de una actualización. Un cambio en la autoridad de firma, el identificador o el requisito designado merece una decisión explícita antes de tratarlo como una actualización rutinaria. Una ruta nueva que aparezca antes de la ruta de lanzamiento en type -a merece la misma atención.

El criterio práctico es sencillo: una aprobación debe aplicarse al grupo de ejecutables que pretendías y tus pruebas deben mostrar por qué ese grupo incluye una compilación y excluye otra. Coloca las copias estable, beta, del gestor de paquetes y local en el mismo Mac, mantén un proceso aprobado en ejecución y obliga a las demás copias a solicitar acceso. Si el resultado te sorprende, el límite de aprobación es demasiado impreciso.