Récupération des recommandations IAM

Cette compétence fournit des instructions pour récupérer des recommandations et des analyses IAM à partir de Google Cloud. Elle couvre la validation de la portée cible d’entrée, la récupération des recommandations à l’aide des outils MCP, des commandes gcloud ou d’appels API directs, ainsi que la gestion des erreurs API courantes.

Procédures

1. Valider la cible d’entrée

Vérifiez la portée cible saisie.

1. Vérification du format: vérifiez si la cible correspond à l'un des formats suivants :

   • organizations/{org_id}
   • dossiers/{id_dossier}
   • projets/{project_id}

2. Gestion des cibles ambiguës/brutes: si l'utilisateur fournit uniquement un identifiant brut (sans préfixe) :

   • Alphanumérique (commençant par une lettre): considérer qu’il s’agit d’un identifiant de projet. Le reformater sous la forme projects/{project_id} et continuer.
   • Purement numérique: c'est ambigu (il peut s'agir d'un numéro d'organisation, de dossier ou de projet).
     • Demandez à l’utilisateur de préciser le type de ressource : > « L’ID de cible '{provided_id}' correspond-il à une organisation, un dossier ou un projet ? »
     • Une fois que l’utilisateur a précisé, formatez la portée cible en conséquence (par exemple, ajoutez organisations/, dossiers/ ou projets/ au début) et continuez.
     • Si la réponse de l’utilisateur n’est pas valide ou s’il ne peut pas préciser, considérez cela comme une erreur et passez à la section « Gestion des erreurs (cible incorrecte) ».

3. Gestion des numéros de projet: si la cible est un projet mais utilise un identifiant purement numérique (numéro de projet) au lieu d’un identifiant de projet (par exemple, projects/123456789) :

   • les commandesgcloud recommender nécessitent un identifiant de projet. Tentez de résoudre le numéro de projet en un identifiant de projet à l’aide de : gcloud projects list --filter="projectNumber={project_number}" --format="value(projectId)"
   • Si cette conversion renvoie un résultat vide ou échoue en raison d’une erreur d’autorisation, ne tentez pas de décrire le projet, de rechercher dans la base de code ou de rechercher des données factices. Renvoyez immédiatement le JSON d’erreur standardisé spécifié dans la section « Gestion des erreurs » et arrêtez l’exécution (n’appelez plus aucun autre outil).

4. Validation de l’enregistrement: Indiquez explicitement la portée cible validée et formatée (par exemple, projects/123456789 ou organizations/123456789012) dans votre raisonnement avant de passer à l’étape de récupération.

2. Récupération des recommandations et des analyses (flux de secours)

Essayez les méthodes de récupération suivantes dans l’ordre. Arrêtez-vous dès la première réussite.

CRITIQUE : échouez rapidement en cas d’erreur (pour éviter les appels API redondants qui échoueront pour les mêmes raisons d’autorisation/de permission) : si une méthode tentée (option A ou option B) échoue avec une erreur au niveau de l’API (telle que PERMISSION_DENIED, UNAUTHENTICATED, ou si la ressource est NOT_FOUND / n’existe pas) ou une erreur de validation CLI (telle qu’un numéro de projet non autorisé), n’essayez PAS d’autres options (y compris l’option C ou les appels API/curl directs). Arrêtez immédiatement, n’appelez plus aucun outil et renvoyez le JSON d’erreur standardisé comme spécifié dans la section « Gestion des erreurs ».

Option A : outil MCP (recommandé)

Utilisez l’outil MCP s’il est disponible. Les outils MCP sont conçus pour une exécution efficace et sécurisée au sein des environnements internes de Google, offrant souvent une authentification simplifiée et une meilleure intégration par rapport aux commandes CLI à usage général.

Si un outil MCP IAM Recommender est disponible dans votre contexte :

• Appelez l’outil avec le paramètre « target ».

Option B : CLI gcloud (première solution de secours)

Si MCP n’est pas disponible, utilisez run_command pour exécuter ce qui suit (remplacez les variables en conséquence) :

Commandes à exécuter:

GCLOUD_COMMON_FLAGS="--format=json --location=global \
--filter=stateInfo.state=ACTIVE"

# 1. Récupérer les recommandations
gcloud recommender recommendations list \
--recommender=google.iam.policy.Recommender $GCLOUD_COMMON_FLAGS {mapped_flag}

# 2. Récupérer les analyses
gcloud recommender insights list --insight-type=google.iam.policy.Insight
$GCLOUD_COMMON_FLAGS {mapped_flag}

Option C : API Google Cloud (solution de secours finale)

N’utilisez cette option que si gcloud est physiquement indisponible dans l’ environnement (par exemple, « gcloud : commande introuvable »). Les bibliothèques clientes d’API nécessitent davantage de configuration et de ressources d’exécution ; elles ne sont donc utilisées qu’en dernier recours si les outils CLI font défaut. N’utilisez PAS cette option si gcloud est disponible mais a échoué en raison d’une erreur API.

Utilisez les bibliothèques clientes de l’API Google Cloud Recommender via un script d’aide (ou des appels API directs si les bibliothèques ne sont pas disponibles) pour :

1. Appeler list_recommendations (ou recommendations.list) pour google.iam.policy.Recommender (filtre : stateInfo.state=ACTIVE).
2. Appeler list_insights (ou insights.list) pour google.iam.policy.Insight (filtre : stateInfo.state=ACTIVE).

3. Déterminer le format de sortie et effectuer la livraison

IMPORTANT: ne passez à cette étape que si la récupération de l’étape 2 a réussi. Si la récupération a échoué, ignorez cette étape et passez directement à la section Gestion des erreurs.

Avant de présenter les résultats, déterminez le format de sortie souhaité.

CRITIQUE: si la requête initiale de l’utilisateur spécifie déjà le format de sortie (par exemple, « renvoyer les résultats bruts au format JSON » ou « les afficher dans un tableau »), ne posez pas de question et passez directement à ce format.

Sinon, demandez à l’utilisateur de choisir dans un menu déroulant, parmi les options suivantes :

1. Fichier JSON
2. Tableau Markdown dans le chat

En fonction du choix (prédéfinis ou sélectionné par l'utilisateur), générez la sortie :

Option A : Fichier JSON

1. Enregistrez les résultats bruts dans un fichier nommé iam_recommendations__.json (où est l’identifiant de ressource nettoyé et est au format AAAAMMJJ_HHMMSS) dans le répertoire de travail actuel.
2. Le contenu du fichier doit correspondre à la structure indiquée dans l’ exemple d’exécution.
3. Renvoyez le chemin d’accès au fichier à l’utilisateur.

Option B : Tableau de discussion

1. Trier les recommandations: triez les recommandations récupérées en plaçant les recommandations des agents de service en dernier dans la liste.
2. Mise en forme du tableau: présentez les recommandations triées sous la forme d’un tableau au format Markdown. Le tableau doit contenir les champs clés suivants :
   • Sous-type: le sous-type de recommandation ou d’analyse (par exemple, indiquant s’il s’agit de rôles au niveau des ressources).
   • Action recommandée: résumé de la recommandation.
   • Justification: justification.
   • Informations associées: les identifiants de toutes les informations liées (provenant de associatedInsights).
3. Limiter l’affichage dans le chat: afficher uniquement les 10 meilleures recommandations dans le tableau du chat .
4. Fournir la liste complète: enregistrer la liste complète des recommandations et des informations dans un fichier Markdown (par exemple, iam_recommendations__.md, où est l’ identifiant de ressource anonymisé et est au format AAAAMMJJ_HHMMSS) et fournir un lien permettant à l’utilisateur de le télécharger.
5. Mise en forme du tableau des informations: si des informations sont disponibles, mettez-les en forme dans un tableau distinct au sein du fichier Markdown (et affichez éventuellement un résumé dans le chat si cela est pertinent, mais veillez à ce que le chat reste clair). Le tableau doit contenir les champs clés suivants :
   • ID de l'analyse: l'identifiant de l'analyse (INSIGHT_ID).
   • État: l’état de l’analyse (INSIGHT_STATE).
   • Sous-type: le sous-type de l’analyse (INSIGHT_SUBTYPE).
   • Description: description de l’analyse (DESCRIPTION).
6. NE FOURNISSEZPAS de fichier JSON contenant les résultats bruts si cette option est sélectionnée.

4. Exemple d'exécution

• Cible d'entrée: projects/my-test-project

• Indicateur mappé: --project=my-test-project

• Action (option B): Exécutez la commande ` gcloud recommender recommendations list --recommender=google.iam.policy.Recommender --format=json --location=global --filter=stateInfo.state=ACTIVE --project=my-test-project

• Structure de sortie attendue:

  {
    "raw_results": {
      "recommendations": [
        {
          "name": "projects/my-test-project/locations/global/recommenders/ \
          google.iam.policy.Recommender/recommendations/123",
          "content": { ... }
        }
      ],
      "insights": []
    },
    "error": null
  }
  

5. Gestion des erreurs

CRITIQUE: si vous rencontrez l’une des conditions d’erreur ci-dessous (lors de la validation ou de la récupération), arrêtez-vous immédiatement. N’essayez pas de déboguer, de changer de compte, d’effectuer une recherche dans le code source ou de vérifier l’existence de la ressource. Renvoyez immédiatement la structure JSON spécifiée comme réponse finale et n’appelez aucun autre outil.

Si toutes les méthodes échouent, renvoyez :

• En cas de cible incorrecte : {"raw_results": null, "error": "La ressource cible spécifiée est incorrecte ou n'existe pas."}
• En cas de problèmes d’authentification : {"raw_results": null, "error": "L’utilisateur n’est pas authentifié. Veuillez vous authentifier (par exemple, en exécutant 'gcloud auth login')."}
• En cas de problèmes d’autorisations : {"raw_results": null, "error": "Autorisations insuffisantes. Assurez-vous de disposer du rôle 'roles/recommender.iamViewer' dans la portée cible."}
• Autres : {"raw_results" : null, "error" : "Échec de la récupération : {error_details}"} (Ne mentionnez pas les échecs de l’outil MCP à l’utilisateur).

Points à surveiller

• Filtre d’état: assurez-vous toujours de filtrer les recommandations ACTIVES.
• Emplacement: l’emplacement d’IAM Recommender est toujours global.