HYPR MFA-Protokolle erfassen

Unterstützt in:

In diesem Dokument wird beschrieben, wie Sie HYPR MFA-Logs mit Webhooks oder Google Cloud Storage V2 in Google Security Operations aufnehmen.

HYPR MFA ist eine passwortlose Multi-Faktor-Authentifizierungslösung, die eine phishingresistente Authentifizierung mit FIDO2-Passkeys, biometrischen Daten und mobil initiierten Anmeldungen bietet. HYPR ersetzt herkömmliche Passwörter durch sichere Public-Key-Kryptografie, um credentialbasierte Angriffe zu verhindern und gleichzeitig die Nutzerauthentifizierung auf Workstations, Webanwendungen und Clouddiensten zu optimieren.

Hinweise

Prüfen Sie, ob die folgenden Voraussetzungen erfüllt sind:

  • Eine Google SecOps-Instanz
  • Administratorzugriff auf das HYPR Control Center
  • Wenden Sie sich an den HYPR-Support, um benutzerdefinierte Ereignishooks für die RP-Anwendung zu aktivieren, die Sie überwachen möchten.

Unterschiede bei der Erfassungsmethode

HYPR MFA unterstützt zwei Methoden zum Senden von Logs an Google Security Operations:

  • Webhook (empfohlen): HYPR sendet Ereignisse in Echtzeit über benutzerdefinierte Ereignishooks an Google Security Operations. Bei dieser Methode werden Ereignisse sofort übermittelt und es ist keine zusätzliche Infrastruktur erforderlich.
  • Google Cloud Storage: HYPR-Ereignisse werden über die API erfasst und in GCS gespeichert. Anschließend werden sie von Google Security Operations aufgenommen. Diese Methode bietet Batchverarbeitung und die Aufbewahrung von Verlaufsdaten.

Wählen Sie die Methode aus, die Ihren Anforderungen am besten entspricht:

Funktion Webhook Google Cloud Storage
Latenz Echtzeit (Sekunden) Batch (Minuten bis Stunden)
Infrastruktur Nicht erforderlich Google Cloud-Projekt mit Cloud Run-Funktion
Verlaufsdaten Auf Ereignisstream beschränkt Vollständige Aufbewahrung in GCS
Komplexität der Einrichtung Einfach Mittel
Kosten Minimal GCP-Computing- und ‑Speicherkosten

Option 1: Webhook-Integration konfigurieren

Webhook-Feed in Google SecOps erstellen

Feed erstellen

  1. Rufen Sie die SIEM-Einstellungen > Feeds auf.
  2. Klicken Sie auf Neuen Feed hinzufügen.
  3. Klicken Sie auf der nächsten Seite auf Einen einzelnen Feed konfigurieren.
  4. Geben Sie im Feld Feedname einen Namen für den Feed ein, z. B. HYPR MFA Events.
  5. Wählen Sie Webhook als Quelltyp aus.
  6. Wählen Sie HYPR MFA als Log type (Protokolltyp) aus.
  7. Klicken Sie auf Weiter.
  8. Geben Sie Werte für die folgenden Eingabeparameter an:
    • Trennzeichen für Aufteilung (optional): Lassen Sie das Feld leer. Jede Webhook-Anfrage enthält ein einzelnes JSON-Ereignis.
    • Asset-Namespace: Der Asset-Namespace.
    • Aufnahmelabels: Das Label, das auf die Ereignisse aus diesem Feed angewendet werden soll.
  9. Klicken Sie auf Weiter.
  10. Prüfen Sie die neue Feedkonfiguration auf dem Bildschirm Abschließen und klicken Sie dann auf Senden.

Secret-Schlüssel generieren und speichern

Nachdem Sie den Feed erstellt haben, müssen Sie einen geheimen Schlüssel für die Authentifizierung generieren:

  1. Klicken Sie auf der Seite mit den Feeddetails auf Geheimen Schlüssel generieren.
  2. In einem Dialogfeld wird der geheime Schlüssel angezeigt.
  3. Kopieren und speichern Sie den geheimen Schlüssel sicher.

Feed-Endpunkt-URL abrufen

  1. Rufen Sie den Tab Details des Feeds auf.
  2. Kopieren Sie im Abschnitt Endpunktinformationen die Feed-Endpunkt-URL.

  3. Das URL-Format lautet:

    https://malachiteingestion-pa.googleapis.com/v2/unstructuredlogentries:batchCreate

    oder

    https://<REGION>-malachiteingestion-pa.googleapis.com/v2/unstructuredlogentries:batchCreate

  4. Speichern Sie diese URL für die nächsten Schritte.

  5. Klicken Sie auf Fertig.

Google Cloud API-Schlüssel erstellen

Für die Authentifizierung in Chronicle ist ein API-Schlüssel erforderlich. Erstellen Sie in der Google Cloud Console einen eingeschränkten API-Schlüssel.

API-Schlüssel erstellen

  1. Rufen Sie die Seite „Anmeldedaten“ in der Google Cloud Console auf.
  2. Wählen Sie Ihr Projekt aus (das Projekt, das mit Ihrer Chronicle-Instanz verknüpft ist).
  3. Klicken Sie auf Anmeldedaten erstellen > API-Schlüssel.
  4. Ein API-Schlüssel wird erstellt und in einem Dialogfeld angezeigt.
  5. Klicken Sie auf API-Schlüssel bearbeiten, um den Schlüssel einzuschränken.

API-Schlüssel einschränken

  1. Auf der Seite mit den API-Schlüssel-Einstellungen:
    • Name: Geben Sie einen aussagekräftigen Namen ein, z. B. Chronicle Webhook API Key.
  2. Gehen Sie unter API-Einschränkungen so vor:
    1. Wählen Sie Schlüssel einschränken aus.
    2. Suchen Sie im Drop-down-Menü APIs auswählen nach Google SecOps API (oder Chronicle API) und wählen Sie die Option aus.
  3. Klicken Sie auf Speichern.
  4. Kopieren Sie den API-Schlüsselwert aus dem Feld API-Schlüssel oben auf der Seite.
  5. Speichern Sie den API-Schlüssel sicher.

Benutzerdefinierten Ereignishook für HYPR MFA konfigurieren

Webhook-URL mit Headern erstellen

HYPR unterstützt benutzerdefinierte Header für die Authentifizierung. Verwenden Sie die Authentifizierungsmethode mit Headern, um die Sicherheit zu erhöhen.

  • Endpunkt-URL (ohne Parameter):

    <ENDPOINT_URL>

  • Überschriften:

    x-goog-chronicle-auth: <API_KEY>
x-chronicle-auth: <SECRET_KEY>
    • Ersetzen Sie:
      • <ENDPOINT_URL>: Die Feed-Endpunkt-URL aus dem vorherigen Schritt.
      • <API_KEY>: Der von Ihnen erstellte Google Cloud-API-Schlüssel.
      • <SECRET_KEY>: Der geheime Schlüssel aus der Erstellung des Chronicle-Feeds.

JSON-Konfiguration für benutzerdefinierten Ereignishook vorbereiten

  • HYPR-Hooks für benutzerdefinierte Ereignisse werden mit JSON konfiguriert. Bereiten Sie die folgende JSON-Konfiguration vor und ersetzen Sie die Platzhalterwerte:

    {
  "name": "Chronicle SIEM Integration",
  "eventType": "ALL",
  "invocationEndpoint": "<ENDPOINT_URL>",
  "httpMethod": "POST",
  "authType": "API_KEY",
  "authParams": {
    "apiKeyAuthParameters": {
      "apiKeyName": "x-goog-chronicle-auth",
      "apiKeyValue": "<API_KEY>"
    },
    "invocationHttpParameters": {
      "headerParameters": [
        {
          "key": "Content-Type",
          "value": "application/json",
          "isValueSecret": false
        },
        {
          "key": "x-chronicle-auth",
          "value": "<SECRET_KEY>",
          "isValueSecret": true
        }
      ]
    }
  }
}

    • Ersetzen Sie:

      • <ENDPOINT_URL>: Die URL des Chronicle-Feed-Endpunkts.
      • <API_KEY>: Der Google Cloud API-Schlüssel.
      • <SECRET_KEY>: Der geheime Schlüssel von Chronicle.

    • Konfigurationsparameter:

    • name: Ein aussagekräftiger Name für den Ereignishook (z. B. Chronicle SIEM Integration).

    • eventType: Legen Sie ALL fest, um alle HYPR-Ereignisse zu senden, oder geben Sie bestimmte Ereignis-Tags wie AUTHENTICATION, REGISTRATION oder ACCESS_TOKEN an.

    • invocationEndpoint: Die URL des Chronicle-Feed-Endpunkts.

    • httpMethod: Legen Sie POST fest.

    • authType: Auf API_KEY für die Authentifizierung von API-Schlüsseln festgelegt.

    • apiKeyName: Der Header-Name für den API-Schlüssel (x-goog-chronicle-auth).

    • apiKeyValue: Der Wert des Google Cloud API-Schlüssels.

    • headerParameters: Zusätzliche Header, einschließlich Content-Type: application/json und des Chronicle-Secret-Schlüssels im x-chronicle-auth-Header.

Benutzerdefinierten Event-Hook im HYPR Control Center erstellen

  1. Melden Sie sich als Administrator im HYPR Control Center an.
  2. Klicken Sie im linken Navigationsmenü auf Integrations (Integrationen).
  3. Klicken Sie auf der Seite Integrationen auf Neue Integration hinzufügen.
  4. Im HYPR Control Center werden verfügbare Integrationen angezeigt.
  5. Klicken Sie unter Event-Hooks auf die Kachel für Benutzerdefinierte Ereignisse.
  6. Klicken Sie auf Add New Event Hook (Neuen Event-Hook hinzufügen).
  7. Fügen Sie im Dialogfeld Neuen Ereignishook hinzufügen den vorbereiteten JSON-Inhalt in das Textfeld ein.
  8. Klicken Sie auf Event-Hook hinzufügen.
  9. HYPR Control Center kehrt zur Seite Event Hooks zurück.

Der benutzerdefinierte Ereignishook ist jetzt konfiguriert und beginnt mit dem Senden von Ereignissen an Google SecOps.

Funktion des Webhooks prüfen

Status von HYPR Control Center-Ereignishooks prüfen

  1. Melden Sie sich im HYPR Control Center an.
  2. Rufen Sie Integrationen auf.
  3. Klicken Sie auf die Integration Benutzerdefinierte Ereignisse.
  4. Prüfen Sie in der Tabelle Event Hooks, ob Ihr Event-Hook aufgeführt ist.
  5. Klicken Sie auf den Namen des Ereignishooks, um Details aufzurufen.
  6. Prüfen Sie, ob die Konfiguration Ihren Einstellungen entspricht.

Chronicle-Feedstatus prüfen

  1. Rufen Sie in Chronicle die SIEM-Einstellungen > Feeds auf.
  2. Suchen Sie Ihren Webhook-Feed.
  3. Prüfen Sie die Spalte Status. Der Status sollte Aktiv sein.
  4. Prüfen Sie die Anzahl der Empfangenen Ereignisse. Sie sollte sich erhöhen.
  5. Prüfen Sie den Zeitstempel unter Zuletzt erfolgreich am (sollte aktuell sein).

Logs in Chronicle prüfen

  1. Klicken Sie auf Suche > UDM-Suche.

  2. Verwenden Sie die folgende Abfrage:

    metadata.vendor_name = "HYPR" AND metadata.product_name = "MFA"

  3. Stellen Sie den Zeitraum auf die letzte Stunde ein.

  4. Prüfen Sie, ob Ereignisse in den Ergebnissen angezeigt werden.

Referenz zu Authentifizierungsmethoden

HYPR Custom Event Hooks unterstützen mehrere Authentifizierungsmethoden. Die empfohlene Methode für Chronicle ist die API-Schlüsselauthentifizierung mit benutzerdefinierten Headern.

  • Konfiguration:

    {
  "authType": "API_KEY",
  "authParams": {
    "apiKeyAuthParameters": {
      "apiKeyName": "x-goog-chronicle-auth",
      "apiKeyValue": "<API_KEY>"
    },
    "invocationHttpParameters": {
      "headerParameters": [
        {
          "key": "Content-Type",
          "value": "application/json",
          "isValueSecret": false
        },
        {
          "key": "x-chronicle-auth",
          "value": "<SECRET_KEY>",
          "isValueSecret": true
        }
      ]
    }
  }
}

  • Vorteile:

    • API-Schlüssel und Secret werden in Headern gesendet (sicherer als URL-Parameter).
    • Unterstützt mehrere Authentifizierungsheader.
    • Header werden nicht in den Zugriffslogs des Webservers protokolliert.

Basisauthentifizierung

  • Konfiguration:

    {
  "authType": "BASIC",
  "authParams": {
    "basicAuthParameters": {
      "username": "your-username",
      "password": "your-password"
    },
    "invocationHttpParameters": {
      "headerParameters": [
        {
          "key": "Content-Type",
          "value": "application/json",
          "isValueSecret": false
        }
      ]
    }
  }
}
    • Anwendungsfall:Wenn für das Zielsystem die HTTP-Basisauthentifizierung erforderlich ist.

Anmeldedaten des OAuth 2.0-Clients

  • Konfiguration:

    {
  "authType": "OAUTH_CLIENT_CREDENTIALS",
  "authParams": {
    "oauthParameters": {
      "clientParameters": {
        "clientId": "your-client-id",
        "clientSecret": "your-client-secret"
      },
      "authorizationEndpoint": "https://login.example.com/oauth2/v2.0/token",
      "httpMethod": "POST",
      "oauthHttpParameters": {
        "bodyParameters": [
          {
            "key": "scope",
            "value": "api://your-api/.default",
            "isValueSecret": false
          },
          {
            "key": "grant_type",
            "value": "client_credentials",
            "isValueSecret": false
          }
        ]
      }
    },
    "invocationHttpParameters": {
      "headerParameters": [
        {
          "key": "Content-Type",
          "value": "application/json",
          "isValueSecret": false
        }
      ]
    }
  }
}
    • Anwendungsfall:Wenn für das Zielsystem eine OAuth 2.0-Authentifizierung erforderlich ist.

Ereignistypen und Filterung

HYPR-Ereignisse werden mit dem Parameter eventTags gruppiert. Sie können den benutzerdefinierten Ereignishook so konfigurieren, dass alle Ereignisse gesendet werden oder nach bestimmten Ereignistypen gefiltert wird.

Ereignis-Tags

  • AUTHENTICATION: Ereignisse zur Nutzerauthentifizierung (Anmeldung, Entsperrung).
  • REGISTRATION: Ereignisse zur Geräteregistrierung (Koppeln von Mobilgeräten, Sicherheitsschlüssel).
  • ACCESS_TOKEN: Ereignisse zur Generierung und Verwendung von Zugriffstokens.
  • AUDIT: Audit-Log-Ereignisse (administrative Aktionen, Konfigurationsänderungen).

Ereignisfilterung konfigurieren

Wenn Sie nur bestimmte Ereignistypen senden möchten, ändern Sie den Parameter eventType in der JSON-Konfiguration:

  • Alle Ereignisse senden:

    {
  "eventType": "ALL"
}

  • Nur Authentifizierungsereignisse senden:

    {
  "eventType": "AUTHENTICATION"
}

  • Nur Registrierungsereignisse senden:

    {
  "eventType": "REGISTRATION"
}

Option 2: Google Cloud Storage-Integration konfigurieren

Zusätzliche Voraussetzungen für die GCS-Integration

Zusätzlich zu den Voraussetzungen im Abschnitt „Vorbereitung“ benötigen Sie Folgendes:

  • Ein GCP-Projekt mit aktivierter Cloud Storage API
  • Berechtigungen zum Erstellen und Verwalten von GCS-Buckets
  • Berechtigungen zum Verwalten von IAM-Richtlinien für GCS-Buckets
  • Berechtigungen zum Erstellen von Cloud Run-Diensten, Pub/Sub-Themen und Cloud Scheduler-Jobs
  • HYPR API-Anmeldedaten (wenden Sie sich für den API-Zugriff an den HYPR-Support)

Google Cloud Storage-Bucket erstellen

  1. Gehen Sie zur Google Cloud Console.
  2. Wählen Sie Ihr Projekt aus oder erstellen Sie ein neues.
  3. Rufen Sie im Navigationsmenü Cloud Storage > Buckets auf.
  4. Klicken Sie auf Bucket erstellen.

  5. Geben Sie die folgenden Konfigurationsdetails an:

    Einstellung Wert
    Bucket benennen Geben Sie einen global eindeutigen Namen ein, z. B. hypr-mfa-logs.
    Standorttyp Wählen Sie je nach Bedarf aus (Region, Dual-Region, Multi-Region).
    Standort Wählen Sie den Speicherort aus, z. B. us-central1.
    Speicherklasse Standard (empfohlen für Logs, auf die häufig zugegriffen wird)
    Zugriffskontrolle Einheitlich (empfohlen)
    Schutzmaßnahmen Optional: Objektversionsverwaltung oder Aufbewahrungsrichtlinie aktivieren

  6. Klicken Sie auf Erstellen.

HYPR-API-Anmeldedaten erfassen

Wenden Sie sich an den HYPR-Support, um API-Anmeldedaten für den Zugriff auf HYPR-Ereignisdaten zu erhalten. Folgendes wird benötigt:

  • API-Basis-URL: Die URL Ihrer HYPR-Instanz (z. B. https://your-tenant.hypr.com)
  • API-Token: Authentifizierungstoken für den API-Zugriff
  • RP-App-ID: Die zu überwachende Relying Party-Anwendungs-ID

Dienstkonto für Cloud Run-Funktion erstellen

Die Cloud Run-Funktion benötigt ein Dienstkonto mit Berechtigungen zum Schreiben in den GCS-Bucket und zum Aufrufen durch Pub/Sub.

Dienstkonto erstellen

  1. Wechseln Sie in der GCP Console zu IAM & Verwaltung > Dienstkonten.
  2. Klicken Sie auf Dienstkonto erstellen.
  3. Geben Sie die folgenden Konfigurationsdetails an:
    • Name des Dienstkontos: Geben Sie hypr-logs-collector-sa ein.
    • Beschreibung des Dienstkontos: Geben Sie Service account for Cloud Run function to collect HYPR MFA logs ein.
  4. Klicken Sie auf Erstellen und fortfahren.
  5. Fügen Sie im Abschnitt Diesem Dienstkonto Zugriff auf das Projekt erteilen die folgenden Rollen hinzu:
    1. Klicken Sie auf Rolle auswählen.
    2. Suchen Sie nach Storage-Objekt-Administrator und wählen Sie die Rolle aus.
    3. Klicken Sie auf + Weitere Rolle hinzufügen.
    4. Suchen Sie nach Cloud Run Invoker und wählen Sie die Rolle aus.
    5. Klicken Sie auf + Weitere Rolle hinzufügen.
    6. Suchen Sie nach Cloud Functions Invoker und wählen Sie die Rolle aus.
  6. Klicken Sie auf Weiter.
  7. Klicken Sie auf Fertig.

Diese Rollen sind erforderlich für:

  • Storage-Objekt-Administrator: Protokolle in GCS-Bucket schreiben und Statusdateien verwalten
  • Cloud Run-Aufrufer: Pub/Sub darf die Funktion aufrufen.
  • Cloud Functions-Invoker: Funktionsaufruf zulassen

IAM-Berechtigungen für GCS-Bucket erteilen

Gewähren Sie dem Dienstkonto (hypr-logs-collector-sa) Schreibberechtigungen für den GCS-Bucket:

  1. Rufen Sie Cloud Storage > Buckets auf.
  2. Klicken Sie auf den Namen Ihres Buckets, z. B. hypr-mfa-logs.
  3. Wechseln Sie zum Tab Berechtigungen.
  4. Klicken Sie auf Zugriff erlauben.
  5. Geben Sie die folgenden Konfigurationsdetails an:
    • Hauptkonten hinzufügen: Geben Sie die E-Mail-Adresse des Dienstkontos ein (z. B. hypr-logs-collector-sa@PROJECT_ID.iam.gserviceaccount.com).
    • Rollen zuweisen: Wählen Sie Storage-Objekt-Administrator aus.
  6. Klicken Sie auf Speichern.

Pub/Sub-Thema erstellen

Erstellen Sie ein Pub/Sub-Thema, in dem Cloud Scheduler veröffentlicht und das von der Cloud Run-Funktion abonniert wird.

  1. Rufen Sie in der GCP Console Pub/Sub > Themen auf.
  2. Klicken Sie auf Thema erstellen.
  3. Geben Sie die folgenden Konfigurationsdetails an:
    • Themen-ID: Geben Sie hypr-logs-trigger ein.
    • Übernehmen Sie die anderen Einstellungen.
  4. Klicken Sie auf Erstellen.

Cloud Run-Funktion zum Erfassen von Logs erstellen

Die Cloud Run-Funktion wird durch Pub/Sub-Nachrichten von Cloud Scheduler ausgelöst, um Protokolle von der HYPR API abzurufen und in GCS zu schreiben.

  1. Rufen Sie in der GCP Console Cloud Run auf.
  2. Klicken Sie auf Dienst erstellen.
  3. Wählen Sie Funktion aus, um eine Funktion mit einem Inline-Editor zu erstellen.

  4. Geben Sie im Abschnitt Konfigurieren die folgenden Konfigurationsdetails an:

    Einstellung Wert
    Dienstname hypr-logs-collector
    Region Wählen Sie die Region aus, die Ihrem GCS-Bucket entspricht (z. B. us-central1).
    Laufzeit Wählen Sie Python 3.12 oder höher aus.

  5. Im Abschnitt Trigger (optional):

    1. Klicken Sie auf + Trigger hinzufügen.
    2. Wählen Sie Cloud Pub/Sub aus.
    3. Wählen Sie unter Cloud Pub/Sub-Thema auswählen das Pub/Sub-Thema (hypr-logs-trigger) aus.
    4. Klicken Sie auf Speichern.

  6. Im Abschnitt Authentifizierung:

    1. Wählen Sie Authentifizierung erforderlich aus.
    2. Identitäts- und Zugriffsverwaltung

  7. Scrollen Sie nach unten und maximieren Sie Container, Netzwerk, Sicherheit.

  8. Rufen Sie den Tab Sicherheit auf:

    • Dienstkonto: Wählen Sie das Dienstkonto aus (hypr-logs-collector-sa).

  9. Rufen Sie den Tab Container auf:

    1. Klicken Sie auf Variablen und Secrets.
    2. Klicken Sie für jede Umgebungsvariable auf + Variable hinzufügen:
    Variablenname Beispielwert Beschreibung
    GCS_BUCKET hypr-mfa-logs Name des GCS-Buckets
    GCS_PREFIX hypr-events Präfix für Protokolldateien
    STATE_KEY hypr-events/state.json Statusdateipfad
    HYPR_API_URL https://your-tenant.hypr.com HYPR API-Basis-URL
    HYPR_API_TOKEN your-api-token HYPR-API-Authentifizierungstoken
    HYPR_RP_APP_ID your-rp-app-id HYPR RP-Anwendungs-ID
    MAX_RECORDS 1000 Maximale Anzahl von Datensätzen pro Ausführung
    PAGE_SIZE 100 Einträge pro Seite
    LOOKBACK_HOURS 24 Erster Rückschauzeitraum

  10. Scrollen Sie im Bereich Variablen und Secrets nach unten zu Anfragen:

    • Zeitlimit für Anfragen: Geben Sie 600 Sekunden (10 Minuten) ein.

  11. Rufen Sie den Tab Einstellungen auf:

    • Im Abschnitt Ressourcen:
      • Arbeitsspeicher: Wählen Sie 512 MiB oder höher aus.
      • CPU: Wählen Sie 1 aus.

  12. Im Abschnitt Versionsskalierung:

    • Mindestanzahl von Instanzen: Geben Sie 0 ein.
    • Maximale Anzahl von Instanzen: Geben Sie 100 ein (oder passen Sie den Wert an die erwartete Last an).

  13. Klicken Sie auf Erstellen.

  14. Warten Sie ein bis zwei Minuten, bis der Dienst erstellt wurde.

  15. Nachdem der Dienst erstellt wurde, wird automatisch der Inline-Code-Editor geöffnet.

Funktionscode hinzufügen

  1. Geben Sie main in das Feld Einstiegspunkt ein.

  2. Erstellen Sie im Inline-Codeeditor zwei Dateien:

    • Erste Datei: main.py::
    import functions_framework
from google.cloud import storage
import json
import os
import urllib3
from datetime import datetime, timezone, timedelta
import time
import base64

# Initialize HTTP client with timeouts
http = urllib3.PoolManager(
    timeout=urllib3.Timeout(connect=5.0, read=30.0),
    retries=False,
)

# Initialize Storage client
storage_client = storage.Client()

# Environment variables
GCS_BUCKET = os.environ.get('GCS_BUCKET')
GCS_PREFIX = os.environ.get('GCS_PREFIX', 'hypr-events')
STATE_KEY = os.environ.get('STATE_KEY', 'hypr-events/state.json')
HYPR_API_URL = os.environ.get('HYPR_API_URL')
HYPR_API_TOKEN = os.environ.get('HYPR_API_TOKEN')
HYPR_RP_APP_ID = os.environ.get('HYPR_RP_APP_ID')
MAX_RECORDS = int(os.environ.get('MAX_RECORDS', '1000'))
PAGE_SIZE = int(os.environ.get('PAGE_SIZE', '100'))
LOOKBACK_HOURS = int(os.environ.get('LOOKBACK_HOURS', '24'))

def to_unix_millis(dt: datetime) -> int:
    """Convert datetime to Unix epoch milliseconds."""
    if dt.tzinfo is None:
        dt = dt.replace(tzinfo=timezone.utc)
    dt = dt.astimezone(timezone.utc)
    return int(dt.timestamp() * 1000)

def parse_datetime(value: str) -> datetime:
    """Parse ISO datetime string to datetime object."""
    if value.endswith("Z"):
        value = value[:-1] + "+00:00"
    return datetime.fromisoformat(value)

@functions_framework.cloud_event
def main(cloud_event):
    """
    Cloud Run function triggered by Pub/Sub to fetch HYPR MFA logs and write to GCS.

    Args:
        cloud_event: CloudEvent object containing Pub/Sub message
    """

    if not all([GCS_BUCKET, HYPR_API_URL, HYPR_API_TOKEN, HYPR_RP_APP_ID]):
        print('Error: Missing required environment variables')
        return

    try:
        # Get GCS bucket
        bucket = storage_client.bucket(GCS_BUCKET)

        # Load state
        state = load_state(bucket, STATE_KEY)

        # Determine time window
        now = datetime.now(timezone.utc)
        last_time = None

        if isinstance(state, dict) and state.get("last_event_time"):
            try:
                last_time = parse_datetime(state["last_event_time"])
                # Overlap by 2 minutes to catch any delayed events
                last_time = last_time - timedelta(minutes=2)
            except Exception as e:
                print(f"Warning: Could not parse last_event_time: {e}")

        if last_time is None:
            last_time = now - timedelta(hours=LOOKBACK_HOURS)

        print(f"Fetching logs from {last_time.isoformat()} to {now.isoformat()}")

        # Convert to Unix milliseconds for HYPR API
        start_millis = to_unix_millis(last_time)
        end_millis = to_unix_millis(now)

        # Fetch logs
        records, newest_event_time = fetch_logs(
            api_url=HYPR_API_URL,
            api_token=HYPR_API_TOKEN,
            rp_app_id=HYPR_RP_APP_ID,
            start_time_ms=start_millis,
            end_time_ms=end_millis,
            page_size=PAGE_SIZE,
            max_records=MAX_RECORDS,
        )

        if not records:
            print("No new log records found.")
            save_state(bucket, STATE_KEY, now.isoformat())
            return

        # Write to GCS as NDJSON
        timestamp = now.strftime('%Y%m%d_%H%M%S')
        object_key = f"{GCS_PREFIX}/logs_{timestamp}.ndjson"
        blob = bucket.blob(object_key)

        ndjson = '\n'.join([json.dumps(record, ensure_ascii=False) for record in records]) + '\n'
        blob.upload_from_string(ndjson, content_type='application/x-ndjson')

        print(f"Wrote {len(records)} records to gs://{GCS_BUCKET}/{object_key}")

        # Update state with newest event time
        if newest_event_time:
            save_state(bucket, STATE_KEY, newest_event_time)
        else:
            save_state(bucket, STATE_KEY, now.isoformat())

        print(f"Successfully processed {len(records)} records")

    except Exception as e:
        print(f'Error processing logs: {str(e)}')
        raise

def load_state(bucket, key):
    """Load state from GCS."""
    try:
        blob = bucket.blob(key)
        if blob.exists():
            state_data = blob.download_as_text()
            return json.loads(state_data)
    except Exception as e:
        print(f"Warning: Could not load state: {e}")

    return {}

def save_state(bucket, key, last_event_time_iso: str):
    """Save the last event timestamp to GCS state file."""
    try:
        state = {'last_event_time': last_event_time_iso}
        blob = bucket.blob(key)
        blob.upload_from_string(
            json.dumps(state, indent=2),
            content_type='application/json'
        )
        print(f"Saved state: last_event_time={last_event_time_iso}")
    except Exception as e:
        print(f"Warning: Could not save state: {e}")

def fetch_logs(api_url: str, api_token: str, rp_app_id: str, start_time_ms: int, end_time_ms: int, page_size: int, max_records: int):
    """
    Fetch logs from HYPR API with pagination and rate limiting.

    Args:
        api_url: HYPR API base URL
        api_token: HYPR API authentication token
        rp_app_id: HYPR RP application ID
        start_time_ms: Start time in Unix milliseconds
        end_time_ms: End time in Unix milliseconds
        page_size: Number of records per page
        max_records: Maximum total records to fetch

    Returns:
        Tuple of (records list, newest_event_time ISO string)
    """
    # Clean up API URL
    base_url = api_url.rstrip('/')

    endpoint = f"{base_url}/rp/api/versioned/events"

    # Bearer token authentication
    headers = {
        'Authorization': f'Bearer {api_token}',
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'User-Agent': 'GoogleSecOps-HYPRCollector/1.0'
    }

    records = []
    newest_time = None
    page_num = 0
    backoff = 1.0

    # Offset-based pagination
    start_index = 0

    while True:
        page_num += 1

        if len(records) >= max_records:
            print(f"Reached max_records limit ({max_records})")
            break

        # Build request parameters
        params = []
        params.append(f"rpAppId={rp_app_id}")
        params.append(f"startDate={start_time_ms}")
        params.append(f"endDate={end_time_ms}")
        params.append(f"start={start_index}")
        params.append(f"limit={min(page_size, max_records - len(records))}")
        url = f"{endpoint}?{'&'.join(params)}"

        try:
            response = http.request('GET', url, headers=headers)

            # Handle rate limiting with exponential backoff
            if response.status == 429:
                retry_after = int(response.headers.get('Retry-After', str(int(backoff))))
                print(f"Rate limited (429). Retrying after {retry_after}s...")
                time.sleep(retry_after)
                backoff = min(backoff * 2, 30.0)
                continue

            backoff = 1.0

            if response.status != 200:
                print(f"HTTP Error: {response.status}")
                response_text = response.data.decode('utf-8')
                print(f"Response body: {response_text}")
                return [], None

            data = json.loads(response.data.decode('utf-8'))

            # Extract results
            page_results = data.get('data', [])

            if not page_results:
                print(f"No more results (empty page)")
                break

            print(f"Page {page_num}: Retrieved {len(page_results)} events")
            records.extend(page_results)

            # Track newest event time
            for event in page_results:
                try:
                    # HYPR uses LOGGEDTIMEINUTC field with Unix milliseconds
                    event_time_ms = event.get('LOGGEDTIMEINUTC')
                    if event_time_ms:
                        event_dt = datetime.fromtimestamp(event_time_ms / 1000, tz=timezone.utc)
                        event_time = event_dt.isoformat()
                        if newest_time is None or parse_datetime(event_time) > parse_datetime(newest_time):
                            newest_time = event_time
                except Exception as e:
                    print(f"Warning: Could not parse event time: {e}")

            # Check for more results
            current_size = data.get('size', 0)
            if current_size < page_size:
                print(f"Reached last page (size={current_size} < limit={page_size})")
                break

            start_index += current_size

        except Exception as e:
            print(f"Error fetching logs: {e}")
            return [], None

    print(f"Retrieved {len(records)} total records from {page_num} pages")
    return records, newest_time
    • Zweite Datei: requirements.txt::
    functions-framework==3.*
google-cloud-storage==2.*
urllib3>=2.0.0

  3. Klicken Sie auf Bereitstellen, um die Funktion zu speichern und bereitzustellen.

  4. Warten Sie, bis die Bereitstellung abgeschlossen ist (2–3 Minuten).

Cloud Scheduler-Job erstellen

Cloud Scheduler veröffentlicht in regelmäßigen Abständen Nachrichten im Pub/Sub-Thema (hypr-logs-trigger), wodurch die Cloud Run-Funktion ausgelöst wird.

  1. Rufen Sie in der GCP Console Cloud Scheduler auf.
  2. Klicken Sie auf Job erstellen.

  3. Geben Sie die folgenden Konfigurationsdetails an:

    Einstellung Wert
    Name hypr-logs-collector-hourly
    Region Dieselbe Region wie die Cloud Run-Funktion auswählen
    Frequenz 0 * * * * (jede Stunde, zur vollen Stunde)
    Zeitzone Zeitzone auswählen (UTC empfohlen)
    Zieltyp Pub/Sub
    Thema Wählen Sie das Pub/Sub-Thema aus (hypr-logs-trigger).
    Nachrichtentext {} (leeres JSON-Objekt)

  4. Klicken Sie auf Erstellen.

Optionen für die Häufigkeit des Zeitplans

Wählen Sie die Häufigkeit basierend auf dem Logvolumen und den Latenzanforderungen aus:

Häufigkeit Cron-Ausdruck Anwendungsfall
Alle 5 Minuten */5 * * * * Hohes Volumen, niedrige Latenz
Alle 15 Minuten */15 * * * * Mittleres Suchvolumen
Stündlich 0 * * * * Standard (empfohlen)
Alle 6 Stunden 0 */6 * * * Geringes Volumen, Batchverarbeitung
Täglich 0 0 * * * Erhebung von Verlaufsdaten

Integration testen

  1. Suchen Sie in der Cloud Scheduler-Konsole nach Ihrem Job (hypr-logs-collector-hourly).
  2. Klicken Sie auf Force run (Ausführung erzwingen), um den Job manuell auszulösen.
  3. Warten Sie einige Sekunden.
  4. Rufen Sie Cloud Run > Dienste auf.
  5. Klicken Sie auf den Namen Ihrer Funktion (hypr-logs-collector).
  6. Klicken Sie auf den Tab Logs.

  7. Prüfen Sie, ob die Funktion erfolgreich ausgeführt wurde. Darauf sollten Sie achten:

    Fetching logs from YYYY-MM-DDTHH:MM:SS+00:00 to YYYY-MM-DDTHH:MM:SS+00:00
Page 1: Retrieved X events
Wrote X records to gs://bucket-name/prefix/logs_YYYYMMDD_HHMMSS.ndjson
Successfully processed X records

  8. Rufen Sie Cloud Storage > Buckets auf.

  9. Klicken Sie auf den Namen Ihres Buckets, z. B. hypr-mfa-logs.

  10. Rufen Sie den Präfixordner auf (z. B. hypr-events/).

  11. Prüfen Sie, ob eine neue .ndjson-Datei mit dem aktuellen Zeitstempel erstellt wurde.

Wenn in den Logs Fehler angezeigt werden, gehen Sie so vor:

  • HTTP 401: API-Anmeldedaten in Umgebungsvariablen prüfen
  • HTTP 403: Prüfen, ob das HYPR API-Token die erforderlichen Berechtigungen hat und die RP-App-ID korrekt ist
  • HTTP 429: Ratenbegrenzung – die Funktion wird automatisch mit Backoff wiederholt.
  • Fehlende Umgebungsvariablen: Prüfen Sie, ob alle erforderlichen Variablen festgelegt sind.

Google SecOps-Dienstkonto abrufen

Google SecOps verwendet ein eindeutiges Dienstkonto, um Daten aus Ihrem GCS-Bucket zu lesen. Sie müssen diesem Dienstkonto Zugriff auf Ihren Bucket gewähren.

Feed in Google SecOps konfigurieren, um HYPR MFA-Logs aufzunehmen

  1. Rufen Sie die SIEM-Einstellungen > Feeds auf.
  2. Klicken Sie auf Neuen Feed hinzufügen.
  3. Klicken Sie auf Einzelnen Feed konfigurieren.
  4. Geben Sie im Feld Feedname einen Namen für den Feed ein, z. B. HYPR MFA Logs from GCS.
  5. Wählen Sie Google Cloud Storage V2 als Quelltyp aus.

  6. Wählen Sie HYPR MFA als Log type (Protokolltyp) aus.

  7. Klicken Sie auf Dienstkonto abrufen. Es wird eine eindeutige E-Mail-Adresse für das Dienstkonto angezeigt, z. B.:

    chronicle-12345678@chronicle-gcp-prod.iam.gserviceaccount.com

  8. Kopieren Sie diese E‑Mail-Adresse für den nächsten Schritt.

  9. Klicken Sie auf Weiter.

  10. Geben Sie Werte für die folgenden Eingabeparameter an:

    • Storage-Bucket-URL: Geben Sie den GCS-Bucket-URI mit dem Präfixpfad ein:

      gs://hypr-mfa-logs/hypr-events/
      • Ersetzen Sie:
        • hypr-mfa-logs: Der Name Ihres GCS-Buckets.
        • hypr-events: Optionales Präfix/Ordnerpfad, in dem Logs gespeichert werden (für den Stamm leer lassen).

    • Option zum Löschen der Quelle: Wählen Sie die gewünschte Löschoption aus:

      • Nie: Es werden nach Übertragungen nie Dateien gelöscht (empfohlen für Tests).
      • Übertragene Dateien löschen: Dateien werden nach der erfolgreichen Übertragung gelöscht.

      • Übertragene Dateien und leere Verzeichnisse löschen: Löscht Dateien und leere Verzeichnisse nach der erfolgreichen Übertragung.

    • Maximales Dateialter: Dateien einschließen, die in den letzten Tagen geändert wurden. Der Standardwert ist 180 Tage.

    • Asset-Namespace: Der Asset-Namespace.

    • Aufnahmelabels: Das Label, das auf die Ereignisse aus diesem Feed angewendet werden soll.

  11. Klicken Sie auf Weiter.

  12. Prüfen Sie die neue Feedkonfiguration auf dem Bildschirm Abschließen und klicken Sie dann auf Senden.

Dem Google SecOps-Dienstkonto IAM-Berechtigungen gewähren

Das Google SecOps-Dienstkonto benötigt die Rolle Storage-Objekt-Betrachter für Ihren GCS-Bucket.

  1. Rufen Sie Cloud Storage > Buckets auf.
  2. Klicken Sie auf den Namen Ihres Buckets, z. B. hypr-mfa-logs.
  3. Wechseln Sie zum Tab Berechtigungen.
  4. Klicken Sie auf Zugriff erlauben.
  5. Geben Sie die folgenden Konfigurationsdetails an:
    • Hauptkonten hinzufügen: Fügen Sie die E‑Mail-Adresse des Google SecOps-Dienstkontos ein.
    • Rollen zuweisen: Wählen Sie Storage-Objekt-Betrachter aus.
  6. Klicken Sie auf Speichern.

UDM-Zuordnungstabelle

Logfeld UDM-Zuordnung Logik
extensions.auth.type Authentifizierungstyp (z.B. SSO, MFA)
metadata.event_type Ereignistyp (z.B. USER_LOGIN, NETWORK_CONNECTION)
EVENTNAME metadata.product_event_type Produktspezifischer Ereignistyp
ID metadata.product_log_id Produktspezifische Log-ID
USERAGENT network.http.parsed_user_agent Geparter HTTP-User-Agent
USERAGENT network.http.user_agent HTTP-User-Agent-String
SESSIONID network.session_id Sitzungs-ID
DEVICEMODEL principal.asset.hardware.model Hardwaremodell des Assets
COMPANION,MACHINEDOMAIN principal.asset.hostname Hostname des Assets
REMOTEIP principal.asset.ip IP-Adresse des Assets
DEVICEID principal.asset_id Eindeutige Kennung für das Asset
COMPANION,MACHINEDOMAIN principal.hostname Mit dem Prinzipal verknüpfter Hostname
REMOTEIP principal.ip IP-Adresse, die mit dem Prinzipal verknüpft ist
DEVICEOS principal.platform Plattform (z.B. WINDOWS, LINUX)
DEVICEOSVERSION principal.platform_version Version der Plattform
ISSUCCESSFUL security_result.action Vom Sicherheitssystem ergriffene Maßnahmen (z.B. ZULASSEN, BLOCKIEREN)
NACHRICHT security_result.description Beschreibung des Sicherheitsergebnisses
MACHINEUSERNAME target.user.user_display_name Anzeigename des Nutzers
FIDOUSER target.user.userid Nutzer-ID
metadata.product_name Produktname
metadata.vendor_name Name des Anbieters/Unternehmens

Benötigen Sie weitere Hilfe? Antworten von Community-Mitgliedern und Google SecOps-Experten erhalten