Modo sombra
Observa, mide y valida los controles de seguridad sin bloquear el tráfico de agentes: el camino seguro hacia la aplicación total.
¿Qué es el modo sombra?
El modo sombra es una pasada de evaluación no bloqueante. Cuando está activado, el proxy de ShieldAgent evalúa cada llamada a herramientas a través del motor de políticas y la cadena de seguridad completa, pero no bloquea la solicitud aunque coincida una regla de denegación. La decisión se registra en el registro de auditoría con un indicador shadowDeny: true para que puedas revisar el impacto antes de comprometerte con la aplicación.
Por defecto: el modo sombra está activado. Los nuevos tenants y agentes comienzan en modo sombra. Esto te da visibilidad sobre lo que sería bloqueado antes de que se interrumpa el tráfico de ningún agente.
Alcance del modo sombra
El modo sombra se puede configurar en tres niveles, dándote control detallado sobre qué partes de tu flota están observando versus aplicando. Una configuración más específica siempre tiene prioridad sobre una más amplia.
- Por conexión:Controla el modo sombra para una única conexión agente-servidor.
- Por agente:Controla el modo sombra para todas las conexiones de un agente específico.
- Todo el tenant:Establece el modo sombra predeterminado para todo tu tenant.
| Nivel | Alcance | Cómo configurar |
|---|---|---|
| Tenant default | Todos los agentes del tenant | Panel: Configuración → Seguridad → Interruptor de modo sombra. |
| Por agente | Todos los vínculos de servidores MCP de un agente | Panel: Agentes → [agente] → Configuración → Interruptor de modo sombra. |
| Por vínculo | Un agente ↔ una conexión a servidor MCP | Panel: Agentes → [agente] → Servidores MCP → [servidor] → Interruptor de modo sombra. |
Eventos sombra en el registro de auditoría
Cada denegación sombra produce un evento de auditoría completo para que puedas cuantificar el impacto antes de pasar a la aplicación. Campos clave:
| Campo | Valor |
|---|---|
| outcome | "shadow" — the call was allowed but would have been denied under enforcement |
| shadowDeny | true — policy engine determined this should be blocked |
| matchedRuleId | UUID of the first deny rule that matched; null for implicit deny |
| reason | Human-readable explanation of which rule matched and why |
{
"id": "ae_...",
"agentId": "...",
"toolName": "bash",
"outcome": "shadow",
"shadowDeny": true,
"matchedRuleId": "pol_...",
"reason": "Rule 'deny bash rm -rf' matched on arguments.command",
"timestamp": "2026-04-24T09:15:00.000Z"
}Despliegue recomendado
El modo sombra permite un camino seguro e iterativo hacia la aplicación total:
Comenzar globalmente en modo sombra
El valor predeterminado. Despliega ShieldAgent y deja que todo el tráfico fluya sin bloqueos. Monitoriza el registro de auditoría en busca de eventos shadow_deny para entender lo que hacen tus agentes.
Crear y probar políticas
Crea reglas de denegación mediante el panel o la API. Como el modo sombra está activado, no se interrumpe ningún tráfico. Usa el registro de auditoría para verificar que las reglas coinciden con las llamadas a herramientas previstas.
Aplicar por agente a medida que validas
Una vez que estés seguro de que las políticas de un agente son correctas, cambia ese agente al modo de aplicación en el panel: Agentes → [agente] → Configuración → desactivar el interruptor de modo sombra. Los demás agentes permanecen en modo sombra.
Aplicar globalmente cuando todos los agentes estén limpios
Desactiva el modo sombra a nivel de tenant: Panel: Configuración → Seguridad → desactivar el interruptor de modo sombra. Las denegaciones de política ahora bloquean las llamadas a herramientas. El modo sombra puede reactivarse para agentes específicos en cualquier momento.
Monitorización de denegaciones sombra
Usa el registro de auditoría para cuantificar el impacto antes de aplicar. Filtra por outcome=shadow para ver todos los eventos sombra, luego agrupa por matchedRuleId para ver qué reglas se disparan con más frecuencia.
// List shadow deny events for a tenant (last 24h)
const shadowEvents = await client.auditEvents.list({
outcome: 'shadow',
limit: 100,
});
// Check shadow mode status for an agent
const agent = await client.agents.get(agentId);
console.log(agent.shadowMode);