API de Veredicto

Resumen

La API de Veredicto está diseñada para clientes que poseen y operan su propia API o servidor MCP. En lugar de enrutar el tráfico del agente a través del proxy de ShieldAgent, tu servidor llama a POST /tenants/:tenantId/scan con el payload de la solicitud entrante. ShieldAgent ejecuta el pipeline completo multi-etapa y devuelve un veredicto — allow, block, o human_review. Tu código lo aplica.

El flujo de tráfico del agente permanece completamente sin cambios. El agente habla con tu servidor normalmente. Tu servidor realiza una llamada HTTP separada a ShieldAgent y decide si ejecutar la herramienta.

¿Cuándo usar la API de Veredicto?

Inicio rápido

Los ejemplos de SDK se han retirado. Para integrar ShieldAgent, usa la referencia OpenAPI.

Solicitud de análisis

El cliente REST llama a POST /tenants/:tenantId/scan en la API de ShieldAgent. Autentícate con una clave API de tenant (token Bearer).

{
  "agentId": "agent-uuid",          // OPTIONAL — omit if server cannot identify the agent
  "clientHint": "Claude Desktop",   // OPTIONAL — from MCP clientInfo.name, for best-effort matching
  "toolName": "read_file",
  "params": { "path": "/etc/passwd" },
  "include_findings": false,        // opt-in; requires verdictDetailedFindings tenant permission
  "context": {
    "transport": "mcp",             // "mcp" | "rest" | "custom"
    "sourceIp": "10.0.1.5",         // optional — used for rate limiting
    "sessionId": "sess-123"         // optional — enables excessive agency detection
  }
}

Respuesta de análisis

Por defecto (todos los tenants)

{
  "action": "block",                        // "allow" | "block" | "human_review"
  "reason": "Security threat detected",     // generic — no detection detail
  "riskScore": 87,
  "auditEventId": "evt-uuid",               // audit event was written
  "reviewId": null                          // set when action is "human_review"
}

Hallazgos detallados ((requiere include_findings: true + permiso del tenant))

{
  "action": "block",
  "reason": "Prompt injection detected in tool arguments",
  "findings": [
    {
      "type": "injection",
      "severity": "critical",
      "detail": "Path traversal pattern detected"
    }
  ],
  "riskScore": 87,
  "auditEventId": "evt-uuid",
  "reviewId": null
}

Los hallazgos detallados están desactivados por defecto. Sin niveles, un atacante con acceso a la API de Veredicto podría sondear iterativamente qué escáner detectó su payload y elaborar intentos de evasión. Actívalo solo para herramientas internas de confianza mediante la configuración del tenant en el panel de ShieldAgent.

Comprobaciones de seguridad

La API de Veredicto aplica las mismas comprobaciones de seguridad integrales que el proxy en línea. Tu solicitud se evalúa contra todas las protecciones configuradas antes de devolver un veredicto.

• Autenticación y validación del tenant
• Limitación de velocidad (por tenant y por agente)
• Control de acceso a herramientas (lista de herramientas aprobadas)
• Evaluación de políticas contra tus reglas configuradas
• Análisis de seguridad (inyección de prompts, DLP, deriva de herramientas, origen cruzado, agencia excesiva)
• Evaluación de puntuación de riesgo
• Registro en el log de auditoría

Identidad del agente

agentId es opcional. El protocolo MCP no expone la identidad del agente — clientInfo del handshake de inicialización MCP initialize identifica el software cliente (p. ej., "Claude Desktop"), no al agente individual. Tu API o servidor MCP puede no saber qué agente específico está llamando.

Observabilidad de la aplicación

Dado que tu código aplica el veredicto (no la infraestructura de ShieldAgent), el registro de auditoría no puede confirmar automáticamente si se respetó un veredicto de block . Usa POST /tenants/:tenantId/verdict-confirmations para enviar tu propio informe de ejecución; ShieldAgent no lo verifica de forma independiente.

Los ejemplos de SDK se han retirado. Para integrar ShieldAgent, usa la referencia OpenAPI.

Modelo de responsabilidad compartida

La API de Veredicto transfiere la aplicación del proxy en línea a tu código. Que tu despliegue bloquee amenazas depende de tu implementación; ShieldAgent documenta sus capacidades de detección y pipeline, no el comportamiento de tu código.

Contrato REST

Los ejemplos de SDK se han retirado. Para integrar ShieldAgent, usa la referencia OpenAPI.

Relacionado

• Resumen de arquitectura →Todas las posiciones de despliegue y patrones de integración
• Referencia OpenAPI →Esquemas de solicitud y respuesta REST admitidos
• Modelo de puntuación de riesgo →Cómo se calcula riskScore en la respuesta del veredicto
• Marcos de cumplimiento →Implicaciones del Art. 9 de la Ley de IA de la UE y Anexo IV para despliegues con API de Veredicto