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 client.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

TypeScript — servidor MCP

import { ShieldAgentClient } from '@shieldagent/sdk';

const shield = new ShieldAgentClient({
  baseUrl: 'https://proxy.shieldagent.io',
  apiKey: '{your-api-key}',
});

// Inside your MCP tool handler:
async function handleToolCall(toolName: string, params: unknown) {
  const verdict = await shield.scan({
    tenantId: '{your-tenant-id}',
    toolName,
    params,
    // agentId is optional — see "Agent Identity" section below
    context: { transport: 'mcp' },
  });

  if (verdict.action === 'block') {
    throw new Error(`Blocked: ${verdict.reason}`);
  }

  if (verdict.action === 'human_review') {
    return { status: 'pending_review', reviewId: verdict.reviewId };
  }

  // verdict.action === 'allow'
  return executeToolLocally(toolName, params);
}

Python — manejador de API REST

from shieldagent import ShieldAgentClient

shield = ShieldAgentClient(
    base_url="https://proxy.shieldagent.io",
    api_key="{your-api-key}",
)

# Inside your API handler:
async def handle_request(agent_id: str, method: str, path: str, body: dict):
    verdict = await shield.scan(
        tenant_id="{your-tenant-id}",
        agent_id=agent_id,          # optional — omit if not known
        tool_name=f"api:{method}:{path}",
        params={"method": method, "path": path, "body": body},
        context={"transport": "rest"},
    )

    if verdict.action == "block":
        raise HTTPException(status_code=403, detail=verdict.reason)

    if verdict.action == "human_review":
        return {"status": "pending_review", "review_id": verdict.review_id}

    return execute_handler(method, path, body)

Solicitud de análisis

El SDK llama a client.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 client.confirmExecution() para cerrar el ciclo.

// After executing or rejecting a tool call, confirm the outcome:
await shield.confirmExecution(verdict.auditEventId, {
  executed: false,   // true = tool ran; false = tool was blocked by your code
});

Modelo de responsabilidad compartida

La API de Veredicto transfiere la aplicación de la infraestructura de ShieldAgent a tu código. Esto es estándar en la industria de seguridad — análogo al modo Count de AWS WAF o al modo Detect de CrowdStrike. Las certificaciones de cumplimiento de ShieldAgent aplican a sus capacidades de detección y pipeline; si tu despliegue logra aplicación completa depende de tu integración.

Referencia de API

Autentícate con una clave API de ámbito de tenant (token Bearer). Consulta la documentación del SDK para guías completas de integración.

Relacionado

• Resumen de arquitectura →Todas las posiciones de despliegue y patrones de integración
• SDK de TypeScript →Referencia del SDK incluyendo scan() y confirmExecution()
• SDK de Python →Referencia del SDK de Python
• 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