Motor de políticas

Cómo funciona

El motor de políticas se sitúa en la Etapa 2 del pipeline del proxy de ShieldAgent, evaluado después de la autenticación y antes del escáner de seguridad. Cada solicitud tools/call se compara con el conjunto de reglas de tu tenant. Otros métodos MCP (tools/list, resources/read, etc.) pasan sin comprobaciones de políticas.

Predeterminado: denegación implícita. Si ninguna regla de política coincide con una solicitud (agentId, toolName) el motor la deniega. Las herramientas sin reglas de permiso explícitas quedan bloqueadas por defecto, sin necesidad de configuración adicional para mantenerse seguro.

Esquema de política

Cada política vincula un nombre de herramienta a una acción y opcionalmente añade condiciones que deben satisfacerse todas para que la regla se active.

Acciones

Alcance y precedencia

Las reglas específicas de agente (agentId no nulo) tienen prioridad sobre las reglas de todo el tenant (agentId: null). Dentro del mismo nivel de especificidad, las reglas de denegación se ejecutan antes que las de permiso y las reglas condicionales antes que las incondicionales.

Tipos de condición

Las condiciones son predicados opcionales en una regla. Cuando hay múltiples condiciones, todas deben coincidir (lógica AND). Si alguna condición falla, la regla se omite y la evaluación continúa con la siguiente regla.

// Deny any bash call where the command contains "rm -rf"
{
  "toolName": "bash",
  "action": "deny",
  "conditions": [
    {
      "type": "param_contains",
      "param": "arguments.command",
      "value": "rm -rf"
    }
  ]
}

// Allow read_file only for paths under /app/data/
{
  "toolName": "read_file",
  "action": "allow",
  "conditions": [
    {
      "type": "param_matches",
      "param": "arguments.path",
      "pattern": "^\/app\/data\/"
    }
  ]
}

// Allow query_database only during business hours (09:00–17:00 UTC)
{
  "toolName": "query_database",
  "action": "allow",
  "conditions": [
    {
      "type": "time_window",
      "allowedHours": [9, 17]
    }
  ]
}

// Cap send_email to 10 calls per minute
{
  "toolName": "send_email",
  "action": "allow",
  "conditions": [
    {
      "type": "rate_limit",
      "maxPerMinute": 10
    }
  ]
}

Modo sombra

El modo sombra permite implementar nuevas políticas de forma segura. Cuando está habilitado, el motor evalúa cada solicitud normalmente pero no la bloquea aunque coincida una regla de denegación. La decisión se registra en el registro de auditoría con outcome: 'shadow' and a shadowDeny: true para que puedas revisar el impacto antes de aplicarlo.

Cascada de tres niveles

El modo sombra se resuelve de más específico a menos específico — el primer valor no nulo tiene precedencia:

Plantillas de políticas

Las plantillas son conjuntos de reglas preconfigurados que puedes aplicar a un tenant en una sola llamada a la API. Al aplicar una plantilla se crea un registro de política por regla, con alcance de todo el tenant. ShieldAgent incluye plantillas del sistema para escenarios comunes de seguridad, cumplimiento y desarrollo; también puedes crear plantillas personalizadas para conjuntos de reglas específicos de tu organización.

Crear y aplicar una plantilla personalizada

import ShieldAgent from '@shieldagent/sdk';

const client = new ShieldAgent();

// Create a custom template
const template = await client.policyTemplates.create({
  name: "Restrict destructive tools",
  description: "Deny dangerous shell commands for production agents",
  category: "security",
  rules: [
    {
      toolName: "bash",
      action: "deny",
      conditions: [{ type: "param_contains", param: "arguments.command", value: "rm -rf" }],
    },
    {
      toolName: "bash",
      action: "deny",
      conditions: [{ type: "param_contains", param: "arguments.command", value: "DROP TABLE" }],
    },
  ],
});

// Apply a template (creates one policy per rule)
await client.policyTemplates.apply(template.id);

Actualizaciones de políticas en vivo

Los cambios de política surten efecto automáticamente — no se necesita reinicio ni redespliegue. Cuando creas, actualizas o eliminas una política en el panel o vía la API, el cambio es recogido por el proxy en segundos. Para cambios urgentes (como añadir una nueva regla de denegación), puedes forzar una actualización inmediata desde el panel o la API.

Gestión de políticas en el panel

El panel es la forma recomendada de crear, revisar y gestionar políticas:

1. 1Ve a Políticas en la barra lateral izquierda para ver la lista completa de reglas de tu tenant.
2. 2Haz clic en Nueva política para crear una regla: establece el nombre de herramienta, la acción, el alcance de agente opcional y las condiciones.
3. 3Usa la barra de búsqueda y filtros para encontrar políticas por nombre de herramienta, acción o agente.
4. 4Haz clic en cualquier fila de política para editarla o eliminarla. Los cambios se recargan en caliente en el proxy automáticamente.
5. 5Ve a Configuración → Seguridad para activar o desactivar el modo sombra globalmente para el tenant.

SDK y Panel

Todas las operaciones de políticas requieren autenticación. Consulta Autenticación para más detalles.

Políticas

Plantillas de políticas

Ejemplo — Crear una política

import ShieldAgent from '@shieldagent/sdk';

const client = new ShieldAgent();

await client.policies.create({
  toolName: "bash",
  action: "deny",
  agentId: null,
  conditions: [
    {
      type: "param_contains",
      param: "arguments.command",
      value: "rm -rf",
    },
  ],
});

Permisos requeridos

Registro de auditoría

Cada evaluación de política se añade al registro de auditoría inmutable. Campos clave en cada evento: