Cuando un agente choca con un 403 PERMISSION_DENIED en Google Cloud, lo habitual es que pruebe roles a ciegas o que pida roles/editor para salir del paso. iam-helper-for-troubleshooting, que Google publicó el 26 de octubre de 2026 junto a otras tres skills de IAM, hace lo contrario: toma el error ID de la respuesta, pregunta a Policy Troubleshooter qué política bloquea y no concede nada sin que un humano lo apruebe.
Qué hace y cuándo se activa
La skill tiene dos modos y elige uno según quién la invoca:
- Requester, para el desarrollador o la cuenta de servicio bloqueada. Captura el
error_info_id(o el trío principal, permiso y recurso), intenta el autodiagnóstico, activa un grant de Privileged Access Manager (PAM) si ya hay un entitlement aprobado y, si no puede resolverlo, redacta un ticket estructurado para el administrador con la política que bloquea y el rol sugerido. - Resolver, el modo por defecto, para quien administra IAM. Analiza toda la jerarquía (organización, carpeta y proyecto) y separa tres causas: una deny policy de IAM v2, una política de Principal Access Boundary (PAB) o la simple ausencia de un binding en la allow policy.
Lo más útil está en las reglas de parada. Si el resultado es GRANTED, aunque sea por herencia de la organización, la skill dice que la configuración es correcta y termina, sin proponer roles. Si es UNKNOWN porque no puede expandir grupos (hace falta roles/browser), lo explica y también termina. Y si la propia consulta devuelve 403, se detiene en lugar de probar comandos alternativos en bucle. Son justo los tres puntos en los que un agente sin guía suele acabar dando permisos de más.
Cuando sí falta un rol, la skill pide confirmación antes incluso de listar candidatos, recuerda que una deny policy se impone a cualquier allow (dar un rol no sirve sin añadir una excepción) y ofrece dos caminos: acceso temporal con PAM, delegado en la skill hermana iam-helper-for-privileged-access-management, o un binding permanente.
Cómo instalarla y qué necesita
Se instala desde el catálogo de Google, que pide elegir las skills, el agente (Claude Code, Gemini CLI, Cursor…) y el ámbito:
npx skills add google/skillsPara diagnosticar, la identidad del agente necesita roles/policyintelligence.policyTroubleshooterViewer (o roles/iam.securityReviewer), roles/iam.principalAccessBoundaryViewer y roles/serviceusage.serviceUsageConsumer. Para arreglar, roles/resourcemanager.projectIamAdmin o roles/iam.denyAdmin. Con solo los primeros, la skill diagnostica y escala; no puede conceder nada.
Prefiere el servidor MCP gestionado de Policy Troubleshooter (https://policytroubleshooter.googleapis.com/mcp, con las herramientas troubleshoot_access y troubleshoot_iam_error_id). Si no está configurado, recurre a dos scripts en Python o a gcloud:
gcloud policy-troubleshoot iam //cloudresourcemanager.googleapis.com/projects/mi-proyecto \
--principal-email="[email protected]" \
--permission="bigquery.datasets.create" \
--billing-project="mi-proyecto" \
--format=jsonRiesgos y límites
He leído los dos scripts y las referencias. Todo cambio de IAM, incluso un rol de solo lectura, pasa por una confirmación explícita, y los roles de administración llevan además un aviso de alto riesgo. Los matices están en lo que ocurre antes:
troubleshooting_error_id.pyhabilita una API sin preguntar. Antes de llamar av3beta/iam:troubleshootErrorejecutagcloud services enable policytroubleshooter.googleapis.comen el proyecto que extrae del error ID. Es inocuo, pero es una escritura en tu proyecto que no pasa por la aprobación.- El rol "menos privilegiado" no siempre lo es.
least_privileged_role.pydescarta los roles básicos, pero ordena primero los roles estándar de servicio (los que terminan enadmin,editor,viewer…) y solo después por número de permisos. Es una decisión deliberada, porque las guías de la skill prefieren roles estándar, pero puede proponerroles/compute.admindonde bastaría un rol más pequeño. Revisa la propuesta antes de aprobarla. - Etiqueta tu uso. Cada comando que ejecuta lleva
CLOUDSDK_METRICS_REQUEST_ATTRIBUTIONo un sufijo en elUser-Agentcon el nombre y la versión de la skill. Según el propio archivo no incluye datos del usuario, y se desactiva pidiéndoselo al agente. - El ejemplo de configuración MCP no funciona tal cual. Pone
Bearer $(gcloud auth print-access-token)dentro de un JSON, y ahí ninguna shell expande el$(...). Sigue la guía de conexión enlazada en lugar de copiarlo.
Las guías de aprobación (references/guardrails.md) están pensadas para que cada organización las adapte: por defecto todo pide confirmación, pero nada impide que alguien las relaje.
Frente a hacerlo a mano
El diagnóstico en sí es el mismo que gcloud policy-troubleshoot iam o Policy Troubleshooter en la consola: la skill no ve nada que tú no puedas ver. Lo que aporta es el criterio alrededor: saber cuándo parar, distinguir deny, PAB y allow antes de tocar nada, preferir acceso temporal con PAM y dejar un ticket completo cuando no puede resolverlo. Para un equipo que ya deja a un agente desplegar en GCP, esa disciplina es lo que evita que el atajo sea roles/editor.
Las otras tres skills completan el ciclo: iam-helper-for-policy-management crea y valida allow y deny policies y bloquea allUsers y los roles básicos; iam-helper-for-policy-simulator prueba un cambio contra los últimos 90 días de registros de acceso antes de aplicarlo; e iam-helper-for-privileged-access-management gestiona los grants temporales de PAM.
Fuentes
- google/skills: iam-helper-for-troubleshooting
- Scale agents securely with IAM Helper Agent Skills and MCP Tools (Google Cloud Blog, 26 de octubre de 2026)