Abruf von IAM-Empfehlungen

Diese Anleitung enthält Anweisungen zum Abrufen von IAM-Empfehlungen und -Erkenntnissen aus Google Cloud. Sie behandelt die Validierung des Zielbereichs der Eingabe, das Abrufen von Empfehlungen mithilfe von MCP-Tools, gcloud-Befehlen oder direkten API-Aufrufen sowie die Behandlung häufiger API-Fehler.

Vorgehensweisen

1. Eingabeziel überprüfen

Überprüfen Sie den Zielbereich der Eingabe.

1. Format prüfen: Überprüfen Sie, ob das Ziel einem der folgenden Formate entspricht:

   • organizations/{org_id}
   • Ordner/{ordner_id}
   • projects/{project_id}

2. Umgang mit mehrdeutigen/unformatierten Zielen: Wenn der Benutzer nur eine unformatierte ID (ohne das Präfix) angibt:

   • Alphanumerisch (beginnt mit einem Buchstaben): Gehen Sie davon aus, dass es sich um eine Projekt-ID handelt. Formatieren Sie sie als projects/{project_id} und fahren Sie fort.
   • Rein numerisch: Die Angabe ist mehrdeutig (könnte eine Organisations-, Ordner- oder Projektnummer sein).
     • Bitten Sie den Benutzer, den Ressourcentyp zu präzisieren: > „Ist die Ziel-ID ‚{provided_id}‘ eine Organisation, ein Ordner oder ein Projekt?“
     • Sobald der Benutzer eine Angabe gemacht hat, formatieren Sie den Zielbereich entsprechend (z. B. mit dem Präfix organizations/, folders/ oder projects/) und fahren Sie fort.
     • Wenn die Antwort des Benutzers ungültig ist oder er keine Klarstellung vornehmen kann, behandeln Sie dies als Fehler und fahren Sie mit „Fehlerbehandlung“ fort (falsches Ziel).

3. Umgang mit Projektnummern: Wenn das Ziel ein Projekt ist, aber eine rein numerische ID (Projektnummer) anstelle einer Projekt-ID verwendet (z. B. projects/123456789):

   • erfordern„gcloud recommender“-Befehle eine Projekt-ID. Versuchen Sie, die Projektnummer in eine Projekt-ID aufzulösen, indem Sie Folgendes verwenden: gcloud projects list --filter="projectNumber={project_number}" --format="value(projectId)"
   • Wenn diese Auflösung leer zurückgibt oder mit einem Berechtigungsfehler fehlschlägt, versuche nicht, das Projekt zu beschreiben, die Codebasis zu durchsuchen oder nach Mock-Daten zu suchen. Gib sofort das in „Behandlung von Fehlern“ angegebene standardisierte Fehler-JSON zurück und beende die Ausführung (rufe keine weiteren Tools auf).

4. Validierung der Aufzeichnung: Geben Sie den validierten und formatierten Zielbereich (z. B. projects/123456789 oder organizations/123456789012) ausdrücklich in Ihrer Begründung an, bevor Sie mit dem Abrufschritt fortfahren.

2. Abruf von Empfehlungen und Erkenntnissen (Fallback-Ablauf)

Versuchen Sie die folgenden Abrufmethoden der Reihe nach. Brechen Sie beim ersten Erfolg ab.

KRITISCH: Bei Fehlern schnell abbrechen (um redundante API-Aufrufe zu vermeiden, die aus denselben Autorisierungs-/Berechtigungsgründen fehlschlagen): Wenn eine versuchte Methode (Option A oder Option B) mit einem Fehler auf API-Ebene (z. B. PERMISSION_DENIED, UNAUTHENTICATED oder wenn die Ressource NOT_FOUND ist bzw. nicht existiert) oder einem CLI-Validierungsfehler (z. B. unzulässige Projektnummer) fehlschlägt, versuchen Sie KEINE weiteren Optionen (einschließlich Option C oder direkter API-/curl-Aufrufe). Beenden Sie den Vorgang sofort, rufen Sie keine weiteren Tools auf und geben Sie das standardisierte Fehler-JSON zurück, wie im Abschnitt „Fehlerbehandlung“ angegeben.

Option A: MCP-Tool (bevorzugt)

Verwenden Sie das MCP-Tool, sofern verfügbar. MCP-Tools sind für die effiziente und sichere Ausführung in den internen Umgebungen von Google konzipiert und bieten oft eine optimierte Authentifizierung sowie eine bessere Integration im Vergleich zu allgemeinen CLI-Befehlen.

Falls in Ihrem Kontext ein IAM Recommender-MCP-Tool verfügbar ist:

• Rufen Sie das Tool mit dem Parameter „target“ auf.

Option B: gcloud-CLI (erste Ausweichmöglichkeit)

Wenn MCP nicht verfügbar ist, führen Sie mit „run_command“ Folgendes aus (ersetzen Sie die Variablen entsprechend):

Auszuführende Befehle:

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

# 1. Empfehlungen abrufen
gcloud recommender recommendations list \
--recommender=google.iam.policy.Recommender $GCLOUD_COMMON_FLAGS {mapped_flag}

# 2. Insights abrufen
gcloud recommender insights list --insight-type=google.iam.policy.Insight
$GCLOUD_COMMON_FLAGS {mapped_flag}

Option C: Google Cloud-API (letzter Ausweg)

Versuchen Sie diese Option nur, wenn „gcloud“ in der Umgebung physisch nicht verfügbar ist (z. B. „gcloud: Befehl nicht gefunden“). API-Client-Bibliotheken erfordern einen höheren Einrichtungs- und Ausführungsaufwand und werden daher nur als letzter Ausweg verwendet, wenn CLI-Tools fehlen. Verwenden Sie diese Option NICHT, wenn „gcloud“ verfügbar ist, aber mit einem API-Fehler fehlgeschlagen ist.

Verwenden Sie die Google Cloud Recommender-API-Client-Bibliotheken über ein Hilfsskript (oder direkte API-Aufrufe, falls keine Bibliotheken verfügbar sind), um:

1. Rufen Sie `list_recommendations ` (oder `recommendations.list`) für `google.iam.policy.Recommender ` auf (Filter: ` stateInfo.state=ACTIVE`).
2. Rufen Sie `list_insights ` (oder `insights.list`) für `google.iam.policy.Insight` auf (Filter: ` stateInfo.state=ACTIVE`).

3. Ausgabeformat festlegen und bereitstellen

WICHTIG: Fahren Sie nur dann mit diesem Schritt fort, wenn der Abruf in Schritt 2 erfolgreich war. Wenn der Abruf fehlgeschlagen ist, überspringen Sie diesen Schritt und fahren Sie direkt mit „Fehlerbehandlung“ fort.

Legen Sie vor der Darstellung der Ergebnisse das gewünschte Ausgabeformat fest.

WICHTIG: Wenn in der ursprünglichen Eingabeaufforderung des Benutzers bereits das Ausgabeformat angegeben ist (z. B. „die Rohdaten in JSON zurückgeben“ oder „in einer Tabelle anzeigen“), überspringe die Abfrage und fahre direkt mit diesem Format fort.

Andernfalls fragen Sie den Benutzer über ein Dropdown-Menü ab, wobei folgende Optionen zur Auswahl stehen:

1. JSON-Datei
2. Markdown-Tabelle im Chat

Je nach Auswahl (entweder vorab festgelegt oder vom Benutzer gewählt) liefern Sie die Ausgabe:

Option A: JSON-Datei

1. Schreiben Sie die Rohdaten in eine Datei mit dem Namen iam_recommendations__.json (wobei der bereinigte Ressourcenbezeichner ist und im Format YYYYMMDD_HHMMSS) im aktuellen Arbeitsverzeichnis.
2. Der Inhalt der Datei muss der in „Beispielausführung“ dargestellten Struktur entsprechen.
3. Geben Sie dem Benutzer den Dateipfad als Antwort zurück.

Option B: Chat-Tabelle

1. Empfehlungen sortieren: Sortieren Sie die abgerufenen Empfehlungen so, dass die Empfehlungen der Service-Agenten am Ende der Liste stehen.
2. Tabelle formatieren: Formatieren Sie die sortierten Empfehlungen als Markdown-Tabelle. Die Tabelle sollte folgende Schlüsselfelder enthalten:
   • Untertyp: Der Untertyp des Empfehlungssystems oder der Erkenntnis (z. B. als Angabe, ob es sich um Rollen auf Ressourcenebene handelt).
   • Empfohlene Maßnahme: Zusammenfassung der Empfehlung.
   • Begründung: Begründung/Rechtfertigung.
   • Zugehörige Erkenntnisse: Die IDs aller verknüpften Erkenntnisse (aus „associatedInsights“).
3. Anzeige im Chat einschränken: Nur die 10 besten Empfehlungen in der Chat-Tabelle anzeigen .
4. Vollständige Liste bereitstellen: Speichern Sie die vollständige Liste der Empfehlungen und Erkenntnisse in einer Markdown-Datei (z. B. iam_recommendations__.md, wobei die bereinigte Ressourcen-ID ist und im Format JJJJMMTT_HHMMSS formatiert ist) und stellen Sie dem Benutzer einen Link zum Herunterladen bereit.
5. Tabelle mit Erkenntnissen formatieren: Falls Erkenntnisse vorliegen, formatieren Sie diese in einer separaten Tabelle in der Markdown-Datei (und zeigen Sie optional eine Zusammenfassung im Chat an, sofern dies angemessen ist, halten Sie den Chat jedoch übersichtlich). Die Tabelle sollte folgende Schlüsselfelder enthalten:
   • Einblicks-ID: Die Kennung des Einblicks (INSIGHT_ID).
   • Status: Der Status der Erkenntnis (INSIGHT_STATE).
   • Untertyp: Der Insight-Untertyp (INSIGHT_SUBTYPE).
   • Beschreibung: Beschreibung der Erkenntnis (DESCRIPTION).
6. Stellen Sie KEINE JSON-Datei mit den Rohdaten bereit, wenn diese Option ausgewählt ist.

4. Ausführungsbeispiel

• Eingabeziel: projects/my-test-project

• Zugeordnetes Flag: --project=my-test-project

• Aktion (Option B): Führen Sie „gcloud recommender recommendations list --recommender=google.iam.policy.Recommender --format=json --location=global --filter=stateInfo.state=ACTIVE --project=my-test-project“ aus

• Erwartete Ausgabestruktur:

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

5. Fehlerbehandlung

KRITISCH: Wenn eine der folgenden Fehlerbedingungen auftritt (während der Validierung oder beim Abruf), brechen Sie den Vorgang sofort ab. Versuchen Sie nicht, den Fehler zu beheben, das Konto zu wechseln, den Code zu durchsuchen oder die Existenz der Ressource zu überprüfen. Geben Sie sofort die angegebene JSON-Struktur als endgültige Antwort aus und rufen Sie keine weiteren Tools auf.

Wenn alle Methoden fehlschlagen, gib Folgendes zurück:

• Bei falschem Ziel: {"raw_results": null, "error": "Die angegebene Zielressource ist falsch oder existiert nicht."}
• Bei Authentifizierungsproblemen: {"raw_results": null, "error": "Der Nutzer ist nicht authentifiziert. Bitte authentifizieren Sie sich (z. B. mit dem Befehl 'gcloud auth login')."}
• Bei Berechtigungsproblemen: {"raw_results": null, "error": "Unzureichende Berechtigungen. Bitte stellen Sie sicher, dass Sie über die Rolle 'roles/recommender.iamViewer' im Zielbereich verfügen."}
• Sonstiges: {"raw_results": null, "error": "Abruf fehlgeschlagen: {error_details}"} (Weisen Sie den Nutzer nicht auf Fehler des MCP-Tools hin).

Zu beachtende Punkte

• Statusfilter: Stellen Sie stets sicher, dass Sie nach AKTIVEN Empfehlungen filtern.
• Standort: Der Standort für den IAM Recommender ist immer global.