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.
Cascada de tres niveles
El modo sombra se resuelve de más específico a menos específico: el primer valor no nulo prevalece. Esto te permite aplicar globalmente mientras mantienes agentes específicos en modo de observación, o viceversa.
| Nivel | Alcance | Cómo configurar |
|---|---|---|
| Tenant default | Todos los agentes del tenant | Configuración → Seguridad → Modo Shadow (o vía API) |
| Por agente | Todos los vínculos de servidores MCP de un agente | PATCH /tenants/:tenantId/agents/:agentId {"shadowMode": false} |
| Por vínculo | Un agente ↔ una conexión a servidor MCP | PATCH /tenants/:tenantId/agents/:agentId/mcp-bindings/:serverId {"shadowMode": false} |
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: PATCH /agents/:id {"shadowMode": false}. Los demás agentes permanecen en modo sombra.
Aplicar globalmente cuando todos los agentes estén limpios
Desactiva el modo shadow a nivel de tenant en Configuración → Seguridad. 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)
curl -s 'https://api.shieldagent.io/tenants/:tenantId/audit-events?outcome=shadow&limit=100' \
-H 'Authorization: Bearer <token>'
# Check shadow mode status for an agent
curl -s 'https://api.shieldagent.io/tenants/:tenantId/agents/:agentId' \
-H 'Authorization: Bearer <token>' | jq '.shadowMode'