Lista de verificación de ámbito de herramientas de mínimo privilegio para agentes de Claude en producción
Cada herramienta que le das a un agente de Claude es una capacidad que un atacante podría intentar activar mediante inyección de prompts. Esta lista de verificación recorre el ámbito de cada herramienta hasta el mínimo que necesita, antes de que el agente pase a producción.
Cómo usar esta lista de verificación
- Trabaja en ella una vez por herramienta, no una vez por agente; un solo agente con cinco herramientas necesita que esto se aplique cinco veces.
- Considera los elementos de la Nivel 1 como bloqueantes; no envíes una herramienta que falle en uno de ellos.
- Vuelve a consultar esta lista de verificación cada vez que cambien el
input_schema, la descripción o los permisos subyacentes de una herramienta, no solo en el lanzamiento inicial. - Mantén un registro de la respuesta a cada elemento por herramienta; este registro es lo que una revisión de seguridad o una auditoría SOC2 pedirán ver.
Nivel 1: Antes de definir la herramienta
- Nombra la capacidad exacta que otorga la herramienta: Escribe una oración que describa lo que la herramienta puede hacer en el mundo real, no para qué sirve. "Envía un correo electrónico a cualquier dirección" es la descripción honesta de una herramienta genérica
send_email, incluso si su propósito previsto es restablecer contraseñas. - Pregunta si una herramienta más específica funcionaría: Una herramienta
send_password_reset_emailque solo acepta unuser_idy busca la dirección internamente es más segura que una herramienta generalsend_email, porque el modelo nunca tiene un parámetro de dirección para manipular. - Identifica qué datos puede leer la herramienta: Enumera cada campo, tabla o documento que la ejecución de una herramienta toca, incluido cualquier dato que lea internamente para cumplir una llamada, no solo lo que está en su
input_schema. - Identifica qué datos puede escribir o modificar la herramienta: Enumera por separado cada escritura, actualización, eliminación o efecto secundario externo; esta suele ser la mitad de mayor riesgo de la superficie de la herramienta.
- Decide si la herramienta necesita acceso de escritura: Una gran parte de las herramientas de "acción" se pueden rediseñar como lectura más confirmación humana, donde Claude propone una acción y un humano o un paso de confirmación separado la ejecuta.
Nivel 2: Ámbito de la definición de la herramienta
- Escribe un
input_schemaespecífico: Restringe los tipos, usa enumeraciones en lugar de cadenas de texto libre siempre que los valores válidos sean un conjunto conocido y finito, y marca cada campo que deba estar presente comorequired. - Evita parámetros de cadena abiertos para cualquier cosa que se mapee a una acción real: Un campo
query: stringen una herramienta de base de datos es mucho más peligroso que un conjunto de parámetros de búsqueda específicos y enumerados. - Escribe la descripción de la herramienta de forma defensiva: Indica explícitamente para qué no se debe usar la herramienta, además de para qué sirve, ya que la descripción en sí misma da forma a cuándo el modelo recurre a la herramienta.
- Limita el radio de explosión de una sola llamada: Para herramientas que operan en varios registros, agrega un límite explícito (
max_records, paginación) para que una sola llamada no pueda tocar un conjunto de datos completo. - Define el ámbito de las credenciales por herramienta, no por aplicación: Dale a cada herramienta su propia clave API con ámbito limitado, rol de base de datos o cuenta de servicio limitada exactamente a lo que esa herramienta necesita; nunca compartas una credencial amplia entre todas las herramientas del agente.
Nivel 3: Aplicación del ámbito en tiempo de ejecución
- Valida cada argumento antes de ejecutarlo, independientemente de lo que diga el modelo: Trata los argumentos que Claude pasa como entrada no confiable, de la misma manera que tratarías un valor de un cuerpo de solicitud HTTP.
- Permite destinos para cualquier herramienta que envíe datos externamente: Una herramienta de correo electrónico, webhook o llamada a API debe verificar la dirección o URL de destino contra una lista de permitidos antes de enviar, no confiar en lo que el modelo proporcionó.
- Aplica límites de tasa por herramienta, por sesión: Limita cuántas veces se puede llamar a una herramienta determinada dentro de una conversación o una ventana de tiempo, para limitar el daño de un agente secuestrado que realiza llamadas repetidas.
- Registra cada llamada a la herramienta con sus argumentos y resultado: Mantén un rastro de auditoría (con PII anonimizada según tu política de registro) que te permita reconstruir exactamente qué hizo una herramienta y por qué, después del hecho.
- Falla en modo cerrado ante errores de validación: Si la entrada de una herramienta falla la validación, devuelve un error con el que el modelo pueda actuar, no intentes silenciosamente adaptar una entrada mal formada a algo que "parece lo suficientemente cercano" para ejecutar.
Nivel 4: Revisión antes del despliegue
- Ejecuta una pasada de prueba adversaria: Intenta que el agente haga un mal uso de cada herramienta a través de un documento recuperado o un mensaje de usuario elaborado, y confirma que el ámbito y la validación se mantienen.
- Confirma que ninguna herramienta tiene acceso permanente más allá de su propósito declarado: Rederiva el ámbito de credenciales de cada herramienta a partir de su
input_schemay descripción, y marca cualquier discrepancia donde el acceso subyacente sea más amplio de lo que la herramienta necesita. - Mapea el acceso de la herramienta contra el modelo de amenazas combinado: Para cada herramienta con capacidad de escritura o comunicación externa, confirma qué contenido no confiable (si lo hay) podría alimentar una llamada a esa herramienta; este es el factor de riesgo multiplicador del modelo de amenazas.
- Obtén la aprobación de alguien que no escribió la herramienta: Un segundo revisor detecta la expansión del ámbito que el autor original ha dejado de notar.
- Documenta una ruta de revocación: Conoce, de antemano, cómo deshabilitar o restringir una herramienta específica rápidamente si se descubre que se usa indebidamente en producción, sin deshabilitar todo el agente.
Aplicación de la lista de verificación en orden
- Niveles 1-2 (elementos 1-10) ocurren en el momento del diseño, antes de que se escriba cualquier código, y son los más baratos de hacer bien desde el principio; rediseñar el ámbito de una herramienta después del lanzamiento significa migrar llamadores y credenciales.
- Nivel 3 (elementos 11-15) se aplica en el código, en el punto en que la herramienta se ejecuta realmente, y debe cubrirse con pruebas automatizadas, no solo con revisión manual.
- Nivel 4 (elementos 16-20) es una puerta de entrada antes del despliegue, no un paso único; repítelo cada vez que cambie la definición de una herramienta o sus permisos subyacentes.
Posibles problemas
- Tratar el
input_schemacomo el límite de seguridad completo. Un esquema específico ayuda, pero si la credencial subyacente o el rol de base de datos es amplio, un error de validación o un caso de borde aún pueden acceder a datos que la herramienta nunca tuvo la intención de tocar. Solución: limita la credencial en sí, no confíes solo en la validación del esquema. - Compartir una clave API o cuenta de servicio entre todas las herramientas de un agente. Esto colapsa el radio de explosión de todo el conjunto de herramientas a lo que esa única credencial puede hacer, lo que anula el propósito del ámbito por herramienta. Solución: emite una credencial separada y mínimamente limitada por herramienta o por categoría de herramienta.
- Escribir una descripción de herramienta que solo explica la ruta feliz. Una descripción que dice "envía una notificación" sin indicar "solo a direcciones en la lista de permitidos interna" no le da al modelo, ni a ninguna instrucción inyectada, ninguna señal sobre el límite previsto. Solución: indica explícitamente las restricciones en la descripción, no solo en el código.
Preguntas frecuentes
¿Necesito ejecutar toda esta lista de verificación para una herramienta puramente de solo lectura?
Sí, pero las apuestas son diferentes. Las herramientas de solo lectura aún necesitan el ámbito de Nivel 1-2 (qué datos puede leer, ¿es el esquema específico?) y la validación de Nivel 3, ya que una herramienta de lectura con acceso a datos confidenciales aún puede ser una ruta de exfiltración si su salida llega alguna vez a un canal no confiable.
¿Por qué el elemento 10 insiste en una credencial separada por herramienta en lugar de una credencial compartida para todo el agente?
Una credencial compartida significa que cada herramienta hereda los permisos combinados de todas ellas, por lo que una brecha de validación en cualquier herramienta individual expone todo a lo que la credencial compartida puede acceder. Las credenciales por herramienta mantienen el radio de explosión real de cada herramienta igual a su ámbito declarado.
¿Cuál es la forma más rápida de convertir una herramienta amplia en una específica?
Reemplaza los parámetros abiertos (una consulta de texto libre, una dirección de destino arbitraria) con valores enumerados o resueltos internamente. Una herramienta send_notification(user_id, template) que busca la dirección internamente es más específica que send_notification(to_address, message).
¿Debería la lógica de validación vivir en la función Python de la herramienta o en otro lugar?
Debería vivir en la misma función que ejecuta el efecto secundario de la herramienta, como primera cosa que hace esa función, para que no haya una ruta de código donde un argumento no validado pueda llegar a la acción real. Centralizarla allí también facilita las pruebas unitarias independientes de una llamada API en vivo.
¿En qué se diferencia esta lista de verificación de las prácticas generales de validación de entradas?
La validación general de entradas asume que un humano o un cliente confiable es la fuente de la entrada. Aquí, el "cliente" que llama a la herramienta es un modelo cuyos argumentos pueden ser influenciados por el contenido que leyó (incluidas las instrucciones inyectadas), por lo que la validación debe asumir que la entrada es adversaria por defecto, no solo mal formada por accidente.
¿Qué significa "fallar en modo cerrado" en el elemento 15, concretamente?
def send_notification(user_id: str, template: str) -> dict:
if template not in ALLOWED_TEMPLATES:
raise ValueError(f"Unknown template: {template!r}")
# nunca sustituyas silenciosamente una plantilla predeterminada aquí
return dispatch(user_id, template)Rechazar con un error claro, en lugar de sustituir silenciosamente un comportamiento de respaldo, mantiene el fallo visible en lugar de ejecutar silenciosamente algo no intencionado.
¿Es realmente necesario un límite de tasa por herramienta si la herramienta en sí tiene un ámbito específico?
Sí. Un ámbito específico limita lo que puede hacer una sola llamada, un límite de tasa limita cuántas veces se puede repetir. Una herramienta que solo puede enviar un tipo de notificación de bajo riesgo sigue siendo un problema si se puede activar mil veces en una sola sesión.
¿Quién debería ser el "segundo revisor" en el elemento 19?
Cualquier persona con suficiente contexto para evaluar la capacidad real de la herramienta, no solo su propósito previsto, y que no haya escrito el código, ya que el modelo mental del autor original de "para qué sirve esta herramienta" facilita pasar por alto lo que realmente es capaz de hacer.
¿Cómo se relaciona esta lista de verificación con el riesgo combinado descrito en el modelo de amenazas de seguridad y RAG?
El ámbito de la herramienta es uno de los tres factores multiplicadores en ese modelo de amenazas (contenido no confiable, acceso a herramientas, ámbito de permisos). Esta lista de verificación se enfoca directamente en los dos últimos, reduciendo lo que una herramienta puede hacer y cuán ampliamente se le permite hacerlo, independientemente de las defensas existentes contra el factor de contenido no confiable.
¿Qué es una ruta de revocación y por qué el elemento 20 la solicita por adelantado?
Una ruta de revocación es una forma rápida y probada de deshabilitar o restringir una herramienta específica (interruptor de función, rotación de credenciales, alternancia de configuración) sin volver a implementar todo el agente. Tenerla lista antes de un incidente, en lugar de improvisar durante uno, es lo que marca la diferencia entre un problema contenido y una interrupción prolongada.
¿Debería aplicarse esta lista de verificación a los agentes internos orientados a desarrolladores también, o solo a los orientados al cliente?
Los agentes internos aún combinan contenido no confiable (documentos internos, tickets, código, entrada de otros empleados) con acceso a herramientas, por lo que los mismos factores de riesgo se aplican. El uso interno solo reduce quién podría ser un atacante, no elimina la necesidad de definir el ámbito.
Relacionado
- Comprensión del modelo de amenazas de seguridad y RAG de Claude - por qué el ámbito de permisos es uno de los tres factores de riesgo multiplicadores.
- Manejo de secretos y prevención de la exfiltración de datos a través del uso de herramientas - las defensas específicas para el riesgo de credenciales y fugas de datos.
- Defensa contra la inyección indirecta de prompts en resultados de herramientas recuperadas por RAG - reducción del factor de contenido no confiable que esta lista de verificación no cubre.
- Mejores prácticas de seguridad, cumplimiento y RAG - el resumen de toda la sección al que contribuye esta lista de verificación.
Versiones de la pila: Escrito contra la línea de modelos de Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado) y Claude Haiku 4.5 - y el SDK oficial de Python
anthropic(última versión 0.x). Los nombres de los modelos, los precios y las versiones del SDK cambian rápidamente; verifique los detalles actuales en platform.claude.com/docs antes de confiar en ellos.