La puerta HITL garantiza que ninguna acción de alto riesgo de un agente se ejecute sin juicio humano. Este cookbook recorre el ciclo de vida completo de una aprobación — desde el momento en que una acción gobernada dispara una solicitud, pasando por la resolución de nivel de riesgo, las decisiónes humanas y la válvula de escape break-glass — para que puedas trazar cada pieza antes de encontrártela en producción.
Si aún no has leído el modelo de autorización, empieza por Gobernanza. La guía Gobernar y aprobar cubre la misma mecánica desde la perspectiva del operador; esta página es la referencia paso a paso.
El ciclo de vida de una solicitud
Una solicitud de aprobación se abre deny-closed y con límite de tiempo. Comienza en
estado pending, lleva una expiración y no autoriza nada hasta que suficientes personas
hayan decidido. La solicitud no puede rebajar su propio umbral — una política de aprobación
que coincida es la fuente autoritativa para el umbral y los tiempos de espera.
La solicitud está vinculada a un plan hash del payload exacto del tool-call. Esta es la defensa anti-TOCTOU: si la acción subyacente cambia entre la solicitud y la decisión, el hash no coincidirá y la aprobación no podrá vincularse. Una aprobación obsoleta nunca autoriza una acción diferente.
Resolución del nivel de riesgo
Cuatro niveles determinan cuánto control humano requiere una acción gobernada:
| Nivel | Qué significa |
|---|---|
low / medium | Se asigna solo por política de aprobación explícita — nada tiene este valor por defecto |
high | El valor por defecto para cualquier cosa que llegue a la cola de aprobación. Requiere una aprobación humana |
critical | Mínimo obligatorio de dos personas (NIST SP 800-53 AC-3(2) dual authorization) |
El nivel se recalcula a partir del conjunto de políticas vigente en cada decisión, nunca se lee de una instantánea almacenada. Un cambio de política surte efecto inmediatamente. Un registro obsoleto nunca puede mantener el umbral por debajo de la clasificación actual — esto es deny-closed por construcción.
El conjunto critical integrado cubre lo genuinamente irreversible: despliegue y retirada
en producción, borrado y eliminación de datos, cambios en seguridad y kill-switch, custodia
y rotación de claves, y offboarding de NHI.
Una política de aprobación con un risk_tier explícito puede subir o bajar el valor por
defecto de cada acción. Pero nunca puede bajar una acción critical por debajo del
umbral de dual-control.
Paso a paso
1. Una acción gobernada dispara una solicitud
Una acción gobernada — deploy apply, agent fire, budget override, o cualquier acción que
coincida con una política de aprobación — llega al motor de aprobación. El motor abre una
nueva solicitud en estado pending.
2. La solicitud se vincula a un plan hash
La solicitud registra un hash del payload exacto del tool-call. Este plan-hash binding es la defensa TOCTOU: la decisión solo autorizará la acción para la que se creó la solicitud.
3. El nivel de riesgo se resuelve a partir de la política vigente
El motor evalúa el conjunto de políticas vigente (RBAC, ABAC nativo y cualquier PDP externo) para derivar el nivel de riesgo. El nivel nunca se cachea de una evaluación anterior.
4. Un revisor humano decide
Una persona con el rol suficiente emite un approve o deny. El servidor aplica tres
invariantes en este punto, indexados por identidad de usuario estable:
- Separation of duty. El solicitante no puede decidir sobre su propia solicitud. Esto se basa en la identidad de usuario estable, no en la cadena de credencial que una misma persona podría variar.
- Protección contra decisores duplicados. Un índice único respalda una carrera de decisores duplicados — una persona cuenta una sola vez para el umbral.
- Vinculación de expiración. Una solicitud expirada nunca puede recibir una decisión vinculante, incluso antes de que un barrido materialice la expiración. El estado efectivo se recalcula en cada decisión.
5. Acciones críticas: dual-control con AAL3
Para el nivel critical: el umbral tiene un mínimo de dos aprobadores humanos
distintos. El mínimo se aplica tanto al crear (el umbral almacenado nunca puede empezar por
debajo de dos) como al decidir (una solicitud creada antes de que la acción se convirtiera
en crítica tampoco puede pasar con una sola persona).
Cada persona que decide debe tener una sesión verificada por hardware reciente — step-up de WebAuthn o PIV (AAL3). Un token de sistema no ofrece garantía humana y es rechazado.
6. La decisión se registra en el ledger
Cada decisión añade una fila inmutable al historial de decisiónes de la solicitud y un evento en el ledger que registra la decisión, el estado resultante y el nivel de riesgo bajo el que se tomó. El ledger es append-only, encadenado por hash y firmado con Ed25519 — reescribir el historial es criptográficamente detectable.
Expiración
La expiración se evalúa en lectura, no se escribe una sola vez. Una solicitud expirada nunca puede recibir una decisión vinculante aunque ningún barrido de fondo haya materializado aún la expiración. El estado efectivo siempre se recalcula, por lo que un barrido lento es un retraso cosmético, no una brecha de seguridad.
Configuración de políticas
Las políticas de aprobación permiten sobrescribir el nivel de riesgo por defecto para cada
clase de acción. Una política con un risk_tier explícito puede mover una acción de high
a low, o elevar un medium a critical. La única restricción: nunca puedes bajar
critical por debajo del umbral de dual-control. El requisito de dos personas para
acciones irreversibles es estructural, no configurable.
Break-glass
Cuando no se alcanza quórum — el incidente de las 03:00 en el que el segúndo aprobador está dormido — break-glass proporciona una válvula de escape auditada. Es ruidoso por construcción.
La activación requiere todo lo siguiente:
- El activador es un admin, siempre una persona real — un token de sistema es rechazado.
- Un step-up AAL3 reciente (WebAuthn o PIV).
- Una justificación escrita registrada en la misma transacción.
- Una sesión activamente grabada como precondición.
Límite de tiempo: la concesión tiene una duración por defecto de una hora, con un tope máximo de 24. Una emergencia que necesite más tiempo es un modo de operación, no una emergencia, y debe pasar por el dual-control normal.
Cada uso queda registrado. Cada acción ejecutada bajo break-glass añade una fila inmutable y un evento en el ledger con el nombre de la concesión, la acción y el sujeto. Una acción que se ejecutó bajo break-glass es permanentemente distinguible de una correctamente aprobada.
Post-revisión obligatoria. No se puede activar una nueva concesión mientras haya alguna anterior sin revisar. La revisión debe venir de una persona distinta al activador. No se pueden apilar emergencias para eludir el escrutinio.
Break-glass relaja un quórum ausente; nunca anula un rechazo explícito. Una solicitud que alguien denegó deliberadamente permanece denegada.
Qué se registra
Cada decisión — approve, deny, expiración o uso de break-glass — se añade a dos sitios:
- El historial de decisiónes de la solicitud: una secuencia inmutable de filas de decisión en la propia solicitud, cada una con el decisor, el veredicto y la marca de tiempo.
- El audit ledger: un evento encadenado por hash y firmado con Ed25519 que registra la decisión, el estado resultante de la solicitud y el nivel de riesgo bajo el que se tomó.
Ambas escrituras se producen en la misma transacción que el cambio de estado. No puedes tomar una decisión gobernada que el ledger olvide en silencio.
Relacionado
- Gobernar y aprobar — la guía del operador que cubre la misma mecánica.
- Gobernanza — el modelo de autorización, la postura de autoauditoría y la mecánica del kill-switch.
- Cookbook: simulacro de kill-switch — el ejercicio de puerta deny a nivel de todo el estate.
- Kill switch — la página de producto del freno de emergencia.