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

# Create a custom template
curl -s -X POST https://api.shieldagent.io/tenants/:tenantId/policy-templates \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "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)
curl -s -X POST https://api.shieldagent.io/tenants/:tenantId/policy-templates/:templateId/apply \
  -H 'Authorization: Bearer <token>'

Arquitectura de recarga en caliente

Los cambios de política surten efecto sin reiniciar el proxy. El proxy mantiene un conjunto de reglas compilado en memoria por tenant y lo actualiza automáticamente.

Referencia de API

Todos los endpoints de políticas requieren un token bearer. Consulta Autenticación para más detalles.

Políticas

Plantillas de políticas

Ejemplo — Crear una política

curl -s -X POST https://api.shieldagent.io/tenants/:tenantId/policies \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "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: