Model Armor-Logs mit Gemini Enterprise-Logs korrelieren

In diesem Dokument wird beschrieben, wie Sie Model Armor-Bereinigungslogs mit Gemini Enterprise-Plattformlogs und Trace-Spans in Cloud Logging korrelieren. Außerdem werden die Korrelationsmechanismen für die Traffic-Flows „Client zu Agent (eingehend)“ und „Agent zu beliebigem Ziel (ausgehend)“ erläutert, die Voraussetzungen für die Trace-Generierung beschrieben und Schritt-für-Schritt-Anleitungen sowie Codebeispiele zum Verknüpfen dieser Logeinträge in Ihrer Logverarbeitungspipeline bereitgestellt.

Wenn Sie einen Model Armor-Trace-Span oder -Logeintrag untersuchen, müssen Sie möglicherweise die entsprechenden Einträge in Cloud Logging suchen, um den vollständigen Kontext der Anfrage zu erhalten. Beispiel:

  • Wenn Sie mit einem Trace-Span beginnen, müssen Sie möglicherweise die Identität des Endnutzers ermitteln oder die detaillierten Bereinigungsergebnisse prüfen.
  • Wenn Sie mit einem Model Armor-Bereinigungslogeintrag beginnen, müssen Sie ihn möglicherweise mit der Nutzeridentität oder den Trace-Informationen korrelieren.

So funktioniert die Logkorrelation

Model Armor kann Prompts und Antworten an den folgenden Kommunikationspunkten in Gemini Enterprise prüfen:

  • Traffic von Client zu Agent (eingehend): Wenn ein Nutzer einen Prompt an den Gemini Enterprise-Assistenten sendet, ruft Gemini Enterprise direkt die Model Armor APIs auf. Die resultierenden Model Armor-Plattformlogs (SanitizeOperation) enthalten nicht direkt die OpenTelemetry trace oder spanId Felder. Um diese Logs mit Nutzeridentitäten und Trace-Spans zu korrelieren, führen Sie in Ihrer SIEM-Pipeline (Security Information and Event Management) oder Logverarbeitungspipeline mithilfe des Sitzungstokens einen Log-Join durch.

  • Traffic von Agent zu beliebigem Ziel (ausgehend): Wenn ein Agent ein externes Tool, einen MCP-Server (Model Context Protocol) oder ein externes LLM (Large Language Model) aufruft, wird der Traffic über das Agent Gateway und den Secure Web Proxy weitergeleitet. Bei ausgehenden Aufrufen enthalten die SanitizeOperation-Logs von Model Armor die Felder trace und spanId direkt, wenn die OpenTelemetry-Instrumentierung aktiviert ist. Sie können Logs direkt filtern und Trace Spans in Cloud Trace oder der Agent Registry ansehen.

Zusammenfassung der Korrelationsmechanismen

Flow Pfad und Routing Trace im Model Armor-Log Korrelationsmethode
Client zu Agent (eingehend) Direkter API-Aufruf von Gemini Enterprise an Model Armor Die Felder trace und spanId werden nicht ausgefüllt. Log-Join mit dem Sitzungstoken aus client_correlation_id und assistToken
Agent zu beliebigem Ziel (ausgehend) Weiterleitung über das Agent Gateway und den Secure Web Proxy Die Felder trace und spanId werden ausgefüllt. Direkte Übereinstimmung mit der trace-ID und Prüfung des Trace-Spans

Hinweis

Bevor Sie Model Armor-Logs mit Gemini Enterprise-Logs korrelieren, führen Sie die folgenden Schritte aus:

  1. Aktivieren Sie Model Armor in Gemini Enterprise.
  2. Wenn Sie den Trace-Kontext generieren und Trace-Details in Gemini Enterprise- und Model Armor-Logs ansehen möchten, aktivieren Sie in den Einstellungen für die Beobachtbarkeit die Optionen Instrumentierung von OpenTelemetry-Traces und ‑Logs aktivieren und optional Logging von Prompt-Eingaben und Antwortausgaben aktivieren. Weitere Informationen finden Sie unter Einstellungen für die Beobachtbarkeit aktivieren.
  3. Konfigurieren Sie Model Armor auf Ihrem Agent Gateway, um ausgehenden Traffic zu prüfen.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Aufrufen und Korrelieren von Logs und Trace-Spans benötigen:

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Informationen zu anderen Rollen, die Sie möglicherweise benötigen, finden Sie unter Zugriffssteuerung für Trace und Zugriffssteuerung für Cloud Logging.

Logs von Client zu Agent (eingehend) korrelieren

Eine einzelne StreamAssist-Interaktion erzeugt drei verschiedene Logeinträge in Cloud Logging:

  • Modell-Armor-Bereinigungslog (SanitizeOperation):
    • Überwachte Ressource:modelarmor.googleapis.com/SanitizeOperation
    • Eigenschaften:Enthält das detaillierte Bereinigungsergebnis und Sicherheitsergebnisse (z. B. Entfernung personenbezogener Daten, Übereinstimmungen mit verantwortungsbewussten KI-Filtern oder Erkennung von Prompt Injections), aber keinen Trace-Kontext oder keine Endnutzeridentität.
    • Korrelationsschlüssel: labels."modelarmor.googleapis.com/client_correlation_id"
  • Gemini Enterprise-StreamAssist-Log (consumed_api)
      :
    • Überwachte Ressource:consumed_api
    • Eigenschaften:Enthält die Endnutzeridentität (userIamPrincipal), die Trace-Details (trace und spanId) und das Sitzungstoken (response.assistToken).
    • Korrelationsschlüssel:jsonPayload.response.assistToken
  • Gemini Enterprise-ModelArmorAudit-Log (Agent)
    • Überwachte Ressource:discoveryengine.googleapis.com/Agent, wobei jsonPayload.logMetadata.methodName gleich ModelArmorAudit ist.
    • Eigenschaften:Gibt das allgemeine Bereinigungsergebnis wieder und enthält den Trace-Kontext (trace und spanId), aber keine detaillierten Ergebnisse oder Korrelations-IDs.
    • Korrelationsschlüssel:trace

Korrelations-Join-Schlüssel

Model Armor-Bereinigungslogs enthalten das Label client_correlation_id mit einer durch senkrechte Striche getrennten Struktur. Das dritte Segment dieses Labels ist ein base64url-codiertes Sitzungstoken, das mit dem assistToken Feld übereinstimmt, das im consumed_api Log für StreamAssist aufgezeichnet wurde.

Das Label client_correlation_id hat das folgende Format:

AS|ASSISTANT_RESOURCE|SESSION_TOKEN

Die Korrelations-ID enthält die folgenden Werte:

  • ASSISTANT_RESOURCE: der vollständige Ressourcenname der Gemini Enterprise Assistant Ressource im folgenden Format: 
    projects/PROJECT/locations/LOCATION/collections/COLLECTION/engines/ENGINE/assistants/ASSISTANT
  • SESSION_TOKEN: Das eindeutige Sitzungstoken, das mit dem assistToken im consumed_api-Log übereinstimmt, nachdem die base64url-Auffüllung normalisiert wurde.

Abgleichslogik

Wenn Sie einen Model Armor-Bereinigungslogeintrag mit Gemini Enterprise-StreamAssist-Logs korrelieren möchten, implementieren Sie die folgende Abgleichslogik in Ihrer Logverarbeitungspipeline:

  1. Sitzungstoken aus dem Model Armor-Eintrag extrahieren:

    1. Suchen Sie im Model Armor-Eintrag das Objekt labels.
    2. Rufen Sie den Wert des Labels modelarmor.googleapis.com/client_correlation_id ab.
    3. Trennen Sie den Wert dieses Labels mit dem senkrechten Strich (|).
    4. Extrahieren Sie das dritte Segment, das das base64url-codierte Sitzungstoken darstellt.

  2. Extrahieren Sie den Wert assistToken aus den StreamAssist-Einträgen: Führen Sie für jeden Kandidaten StreamAssist consumed_api-Logeintrag die folgenden Schritte aus:

    1. Suchen Sie das Objekt jsonPayload.
    2. Extrahieren Sie den Tokenwert aus dem Feld response.assistToken.

  3. Tokens normalisieren und vergleichen: Normalisieren Sie beide Token-Strings, um die Tokens zu vergleichen:

    1. Ersetzen Sie alle Bindestriche (-) durch Pluszeichen (+).
    2. Ersetzen Sie alle Unterstriche (_) durch Schrägstriche (/).
    3. Entfernen Sie alle nachgestellten Gleichheitszeichen (=).
    4. Wenn die normalisierten Tokens übereinstimmen, korrelieren Sie die Logeinträge.

  4. Korrelierte Daten extrahieren: Wenn Sie eine Übereinstimmung finden, extrahieren Sie die folgenden Felder aus den übereinstimmenden Einträgen:

    • IAM-Identität des Nutzers: Das Feld userIamPrincipal aus dem StreamAssist Eintrag
    • Trace-ID: Das trace Feld aus dem StreamAssist Eintrag
    • Span-ID: Das Feld spanId aus dem StreamAssist-Eintrag
    • Bereinigungsergebnis: Das sanitizationVerdict Feld unter jsonPayload.sanitizationResult im Model Armor Eintrag

Python-Beispiel für die Korrelation

Das folgende Python-Skript zeigt, wie Sie Cloud Logging nach Model Armor- und Gemini Enterprise-Logs abfragen, die Token normalisieren und abgleichen und die korrelierten Einträge ausgeben:

#!/usr/bin/env python3
from datetime import datetime, timedelta, timezone
from google.cloud import logging

# Google Cloud project ID
PROJECT_ID = "YOUR_PROJECT_ID"


def correlate_logs(ma_entry, de_consumed_entries):
  """Correlates a Model Armor log entry with StreamAssist logs."""
  # 1. Extract client_correlation_id from Model Armor log labels
  labels = ma_entry.get("labels", {})
  client_corr_id = labels.get(
      "modelarmor.googleapis.com/client_correlation_id", ""
  )
  if not client_corr_id:
    return None

  # 2. Extract session token (3rd pipe-delimited segment)
  parts = client_corr_id.split("|")
  if len(parts) < 3:
    return None
  ma_token = parts[2]

  # 3. Normalize base64url padding for comparison
  ma_token_normalized = ma_token.replace("-", "+").replace("_", "/").rstrip("=")

  # 4. Search for matching assistToken in StreamAssist logs
  for de in de_consumed_entries:
    payload = de.get("jsonPayload", {})
    de_token = payload.get("response", {}).get("assistToken", "")
    de_token_normalized = (
        de_token.replace("-", "+").replace("_", "/").rstrip("=")
    )

    if ma_token_normalized == de_token_normalized:
      return {
          "user": payload.get("userIamPrincipal"),
          "trace": de.get("trace"),
          "span_id": de.get("spanId"),
          "verdict": (
              ma_entry.get("jsonPayload", {})
              .get("sanitizationResult", {})
              .get("sanitizationVerdict")
          ),
      }
  return None


def main():
  # Initialize Google Cloud Logging Client
  print(f"Connecting to Google Cloud Logging (Project: {PROJECT_ID})...")
  client = logging.Client(project=PROJECT_ID)

  # Calculate ISO timestamp for 1 hour ago
  one_hour_ago = (
      datetime.now(timezone.utc) - timedelta(hours=1)
  ).strftime("%Y-%m-%dT%H:%M:%SZ")
  print(f"Filtering logs starting from: {one_hour_ago}")

  # Build log query filters
  ma_filter = f"""
    resource.type="modelarmor.googleapis.com/SanitizeOperation"
    AND timestamp >= "{one_hour_ago}"
    """

  de_filter = f"""
    resource.type="consumed_api"
    AND jsonPayload.response.assistToken:*
    AND timestamp >= "{one_hour_ago}"
    """

  # Fetch Model Armor log entries
  print("Fetching Model Armor log entries...")
  ma_entries = [
      entry.to_api_repr()
      for entry in client.list_entries(filter_=ma_filter, max_results=100)
  ]
  print(f"Found {len(ma_entries)} Model Armor entries.")

  # Fetch Gemini Enterprise log entries
  print("Fetching Gemini Enterprise StreamAssist log entries...")
  de_entries = [
      entry.to_api_repr()
      for entry in client.list_entries(filter_=de_filter, max_results=500)
  ]
  print(f"Found {len(de_entries)} Gemini Enterprise entries.")

  # Perform Correlation
  print("\n================ Correlating Logs ================")
  correlated_results = []
  for ma in ma_entries:
    match = correlate_logs(ma, de_entries)
    if match:
      correlated_results.append(match)
      print(f"  User IAM Principal  : {match['user']}")
      print(f"  Sanitization Verdict: {match['verdict']}")
      print(f"  Trace ID            : {match['trace']}")
      print(f"  Span ID             : {match['span_id']}")
      print("-" * 50)

  print(f"\nDone. Total Correlated Records: {len(correlated_results)}")


if __name__ == "__main__":
  main()

Logs und Trace-Spans von Agent zu beliebigem Ziel (ausgehend) korrelieren

Wenn ein Agent Tool-Aufrufe ausführt (z. B. die Interaktion mit einem MCP-Server oder externen APIs), die durch das Agent Gateway und Model Armor geschützt sind, gehört die Anfrage zum Traffic von Agent zu beliebigem Ziel.

Wenn die OpenTelemetry-Instrumentierung in der App aktiviert ist, enthalten die resultierenden SanitizeOperation-Logeinträge automatisch die Felder trace und spanId.

Ausgehende Logs in Cloud Logging filtern

Verwenden Sie den folgenden Abfragefilter, um alle Model Armor-Bereinigungslogs zu finden, die mit einem bestimmten Trace in Cloud Logging verknüpft sind:

resource.type="modelarmor.googleapis.com/SanitizeOperation"
trace="TRACE_ID"

Ersetzen Sie TRACE_ID durch die Trace-ID aus der Agent-Interaktion.

Weitere Informationen finden Sie unter Logeinträge ansehen und analysieren.

Trace-Spans ansehen

In Trace oder der Agent Registry können Sie das Ausführungsdiagramm und die Zeitachsen der Agent-Interaktion ansehen. Model Armor generiert die folgenden Spans:

  • Übergeordneter Span: apply_guardrail "Google Cloud Model Armor"
  • Untergeordnete Spans: Request Path und Response Path

Jeder Span enthält Attribute wie die Richtlinien-ID, Sicherheitsentscheidungen und übereinstimmende Filterverstöße. Weitere Informationen finden Sie unter Model Armor-Trace Spans ansehen.

Nächste Schritte