Collecter les journaux CyberArk Endpoint Privilege Manager

Version de l'analyseur : 2.0

Compatible avec :

Ce document explique comment ingérer des journaux CyberArk Endpoint Privilege Manager (EPM) dans Google Security Operations à l'aide de Cloud Storage V2.

CyberArk Endpoint Privilege Manager applique le principe du moindre privilège sur les points de terminaison Windows, macOS et Linux en supprimant les droits d'administrateur local, en contrôlant les applications qui peuvent s'exécuter ou s'élever, et en protégeant les identifiants contre le vol. EPM SaaS expose ses données d'événement via l'API REST EPM. Une fonction Cloud Run interroge les événements bruts de chaque ensemble EPM et les écrit dans un bucket Cloud Storage, à partir duquel Google SecOps les ingère.

Avant de commencer

Assurez-vous de remplir les conditions suivantes :

  • Une instance Google SecOps
  • Un projet Google Cloud avec l'API Cloud Storage activée
  • Autorisations de créer et de gérer des buckets Cloud Storage
  • Autorisations de gérer les stratégies IAM (Identity and Access Management) sur les buckets Cloud Storage
  • Autorisations permettant de créer des services Cloud Run, des sujets Pub/Sub et des jobs Cloud Scheduler
  • Un locataire SaaS CyberArk EPM
  • Un administrateur de compte EPM pour créer l'utilisateur et le rôle d'API

Créer un bucket Cloud Storage

  1. Accédez à la consoleGoogle Cloud .
  2. Sélectionnez votre projet ou créez-en un.
  3. Dans le menu de navigation, accédez à Cloud Storage > Buckets.
  4. Cliquez sur Créer un bucket.
  5. Fournissez les informations de configuration suivantes :

    Paramètre Valeur
    Attribuez un nom au bucket Saisissez un nom unique (par exemple, cyberark-epm-secops-logs).
    Type d'emplacement Choisissez celle qui correspond le mieux à vos besoins (régionale, birégionale ou multirégionale).
    Emplacement Sélectionnez l'emplacement (par exemple, us-central1).
    Classe de stockage Standard (recommandé pour les journaux fréquemment consultés)
    Access control (Contrôle des accès) Uniforme (recommandé)
    Outils de protection Facultatif : Activez la gestion des versions d'objets ou la règle de conservation.
  6. Cliquez sur Créer.

Collecter les identifiants CyberArk EPM

La fonction Cloud Run se connecte à l'API REST EPM avec un utilisateur EPM. Créez un utilisateur dédié disposant d'un accès en lecture seule aux ensembles dont vous souhaitez collecter les événements.

Créer l'utilisateur de l'API

  1. Connectez-vous à la console de gestion EPM en tant qu'administrateur du compte.
  2. Cliquez sur la tuile Administration.
  3. Accédez à la page Utilisateurs, puis cliquez sur Ajouter un utilisateur.
  4. Fournissez les informations de configuration suivantes :
    • Adresse e-mail : saisissez le nom de connexion de l'utilisateur d'intégration (par exemple, secops-collector@example.com).
    • Mot de passe : saisissez un mot de passe de 12 à 128 caractères.
  5. Cliquez sur Ajouter.
  6. Enregistrez le nom d'utilisateur et le mot de passe de manière sécurisée. Vous les utiliserez comme valeurs EPM_USERNAME et EPM_PASSWORD de la fonction Cloud Run.

Créer un rôle en lecture seule et l'attribuer

  1. Dans Administration, accédez à la page Rôles, puis cliquez sur Créer un rôle.
  2. Fournissez les informations de configuration suivantes :
    • Nom : saisissez un nom pour le rôle (par exemple, SecOps view only).
    • Groupe d'autorisations : sélectionnez Lecture seule.
    • Ensembles : sélectionnez tous les ensembles dont vous souhaitez collecter les événements.
  3. Cliquez sur Créer.
  4. Accédez à la page Attribution de rôles.
  5. Sur la ligne du rôle que vous avez créé, cliquez sur Autres actions (...) > Attribuer ou annuler l'attribution d'utilisateurs.
  6. Cliquez sur Attribuer aux utilisateurs, recherchez l'utilisateur d'intégration, sélectionnez-le, puis cliquez sur Attribuer.
  7. Cliquez sur Enregistrer.

Déterminer l'URL de connexion à EPM

L'API d'authentification EPM est diffusée par le serveur de distribution de votre région. La fonction n'utilise cette URL que pour se connecter. Tous les autres appels sont envoyés à l'URL du gestionnaire renvoyée par la réponse de connexion.

Région URL de connexion
USA https://login.epm.cyberark.com
Allemagne https://eu.epm.cyberark.com
Suisse https://ch.epm.cyberark.com
Royaume-Uni https://uk.epm.cyberark.com
Australie https://au.epm.cyberark.com
Canada https://ca.epm.cyberark.com
Inde https://in.epm.cyberark.com
Japon https://jp.epm.cyberark.com
Singapour https://sg.epm.cyberark.com
Italie https://it.epm.cyberark.com
Émirats arabes unis https://ae.epm.cyberark.com
Fédéral https://login.epm.cyberarkgov.cloud

Tester l'accès à l'API

  • Testez les identifiants avant de procéder à l'intégration comme suit :

    # Replace with your actual values
    EPM_LOGIN_URL="https://login.epm.cyberark.com"
    EPM_USERNAME="<your-username>"
    EPM_PASSWORD="<your-password>"
    
    # Sign in and get a session token and the manager URL
    curl -s -X POST "$EPM_LOGIN_URL/EPM/API/Auth/EPM/Logon" \
        -H "Content-Type: application/json" \
        -d "{\"Username\":\"$EPM_USERNAME\",\"Password\":\"$EPM_PASSWORD\",\"ApplicationID\":\"GoogleSecOps\"}"
    
  • Une réponse réussie renvoie EPMAuthenticationResult (le jeton de session) et ManagerURL. Pour confirmer le rôle, listez les ensembles avec le jeton comme suit :

    # Replace with the values from the sign-in response
    MANAGER_URL="<ManagerURL>"
    TOKEN="<EPMAuthenticationResult>"
    
    curl -s "$MANAGER_URL/EPM/API/Sets?Limit=1000" \
        -H "Authorization: basic $TOKEN"
    

La réponse liste tous les ensembles que l'utilisateur peut afficher. Si Sets est vide, le rôle n'est pas attribué ou n'inclut pas les ensembles.

Créer un compte de service pour la fonction Cloud Run

La fonction Cloud Run a besoin d'un compte de service autorisé à écrire dans le bucket Cloud Storage et à être appelée par Pub/Sub.

Créer un compte de service

  1. Dans la consoleGoogle Cloud , accédez à IAM et administration > Comptes de service.
  2. Cliquez sur Créer un compte de service.
  3. Fournissez les informations de configuration suivantes :
    • Nom du compte de service : saisissez cyberark-epm-collector-sa.
    • Description du compte de service : saisissez Service account for Cloud Run function to collect CyberArk EPM logs.
  4. Cliquez sur Créer et continuer.
  5. Dans la section Autoriser ce compte de service à accéder au projet, ajoutez les rôles suivants :
    1. Cliquez sur Sélectionner un rôle.
    2. Recherchez et sélectionnez Administrateur des objets Storage.
    3. Cliquez sur + Ajouter un autre rôle.
    4. Recherchez et sélectionnez Demandeur Cloud Run.
    5. Cliquez sur + Ajouter un autre rôle.
    6. Recherchez et sélectionnez Demandeur Cloud Functions.
  6. Cliquez sur Continuer.
  7. Cliquez sur OK.

Ces rôles sont requis pour :

  • Administrateur des objets de l'espace de stockage : écrire des journaux dans le bucket Cloud Storage et gérer les fichiers d'état
  • Demandeur Cloud Run : autorise Pub/Sub à appeler la fonction.
  • Demandeur Cloud Functions : autorise l'appel de fonctions.

Accorder des autorisations IAM sur le bucket Cloud Storage

Accordez au compte de service des autorisations d'écriture sur le bucket Cloud Storage :

  1. Dans la consoleGoogle Cloud , accédez à Cloud Storage > Buckets.
  2. Cliquez sur le nom de votre bucket.
  3. Accédez à l'onglet Autorisations.
  4. Cliquez sur Accorder l'accès.
  5. Fournissez les informations de configuration suivantes :
    • Ajouter des comptes principaux : saisissez l'adresse e-mail du compte de service (par exemple, cyberark-epm-collector-sa@PROJECT_ID.iam.gserviceaccount.com).
    • Attribuer des rôles : sélectionnez Administrateur des objets Storage.
  6. Cliquez sur Enregistrer.

Créer un sujet Pub/Sub

Créez un sujet Pub/Sub dans lequel Cloud Scheduler publiera des messages et auquel la fonction Cloud Run s'abonnera.

  1. Dans la consoleGoogle Cloud , accédez à Pub/Sub > Sujets.
  2. Cliquez sur Créer un sujet.
  3. Fournissez les informations de configuration suivantes :
    • ID du sujet : saisissez cyberark-epm-trigger.
    • Conservez les valeurs par défaut des autres paramètres.
  4. Cliquez sur Créer.

Créer une fonction Cloud Run pour collecter les journaux

La fonction Cloud Run sera déclenchée par des messages Pub/Sub provenant de Cloud Scheduler pour récupérer les événements bruts de l'API REST CyberArk EPM et les écrire dans Cloud Storage.

  1. Dans la consoleGoogle Cloud , accédez à Cloud Run.
  2. Cliquez sur Écrire une fonction.
  3. Dans la section Configurer, fournissez les informations de configuration suivantes :

    Paramètre Valeur
    Nom du service cyberark-epm-collector
    Région Sélectionnez la région correspondant à votre bucket Cloud Storage (par exemple, us-central1).
    Durée d'exécution Sélectionnez Python 3.12 ou une version ultérieure.
  4. Dans la section Déclencheur, cliquez sur Ajouter un déclencheur, puis sélectionnez Déclencheur Pub/Sub.

  5. Dans le volet Déclencheur Eventarc, fournissez les informations de configuration suivantes :

    • Nom du déclencheur : conservez le nom généré ou saisissez un nom pour le déclencheur.
    • Type de déclencheur : sélectionnez Sources Google.
    • Fournisseur d'événements : sélectionnez Pub/Sub.
    • Type d'événement : sélectionnez google.cloud.pubsub.topic.v1.messagePublished.
    • Sélectionner un sujet Cloud Pub/Sub : choisissez le sujet cyberark-epm-trigger.
    • Région : sélectionnez la même région que la fonction.
    • Compte de service : sélectionnez le compte de service cyberark-epm-collector-sa.
  6. Cliquez sur Enregistrer le déclencheur.

  7. Dans la section Authentification :

    1. Sélectionnez Exiger l'authentification.
    2. Sélectionnez Identity and Access Management (IAM).
  8. Accédez à Conteneurs, mise en réseau, sécurité et développez cette section.

  9. Accédez à l'onglet Sécurité :

    • Compte de service : sélectionnez le compte de service cyberark-epm-collector-sa.
  10. Accédez à l'onglet Conteneurs :

    1. Cliquez sur Variables et secrets.
    2. Cliquez sur + Ajouter une variable pour chaque variable d'environnement :
    Nom de la variable Exemple de valeur Description
    GCS_BUCKET cyberark-epm-secops-logs Nom du bucket Cloud Storage
    GCS_PREFIX cyberark-epm Préfixe des fichiers journaux
    STATE_KEY cyberark-epm-state.json Chemin d'état, en dehors du préfixe du journal
    EPM_LOGIN_URL https://login.epm.cyberark.com URL de connexion à EPM pour votre région
    EPM_USERNAME secops-collector@example.com Nom de connexion de l'utilisateur de l'API EPM
    EPM_PASSWORD <your-password> Mot de passe de l'utilisateur de l'API EPM
    EPM_APPLICATION_ID GoogleSecOps Nom de l'application indiqué lors de la connexion
    EPM_SET_IDS (vide) ID d'ensembles facultatifs séparés par une virgule ; si ce champ est vide, tous les ensembles que l'utilisateur peut consulter sont collectés
    EPM_API_VERSION (vide) Version de l'API facultative (par exemple, 24.12.0.1). Si ce champ est vide, la dernière version est utilisée.
    MAX_RECORDS 10000 Nombre maximal d'enregistrements par exécution
    PAGE_SIZE 1000 Enregistrements par page (le maximum de l'API est de 1 000)
    LOOKBACK_HOURS 24 Période d'analyse initiale lors de la première exécution
    OVERLAP_MINUTES 15 Fenêtre de relecture avant le filigrane, pour détecter les événements que les agents signalent tardivement
  11. Dans la section Variables et secrets, accédez à Requêtes :

    • Délai avant expiration de la requête : saisissez 600 secondes (10 minutes).
  12. Accédez à l'onglet Paramètres :

    • Dans la section Ressources :
      • Mémoire : sélectionnez 512 Mio ou plus.
      • Processeur : sélectionnez 1.
  13. Dans la section Scaling de révision :

    • Nombre minimal d'instances : saisissez 0.
    • Nombre maximal d'instances : saisissez 1.
  14. Cliquez sur Créer.

  15. Attendez que le service soit créé (une à deux minutes).

  16. Une fois le service créé, l'éditeur de code intégré s'ouvre automatiquement.

Ajouter le code de la fonction

  1. Saisissez main dans le champ Point d'entrée.
  2. Dans l'éditeur de code intégré, créez deux fichiers :

    • Premier fichier : main.py:

      import functions_framework
      from google.cloud import storage
      from google.cloud.exceptions import NotFound
      import hashlib
      import json
      import os
      import urllib3
      from urllib.parse import urlencode
      from datetime import datetime, timezone, timedelta
      import time
      
      # Initialize HTTP client with timeouts
      http = urllib3.PoolManager(
              timeout=urllib3.Timeout(connect=5.0, read=60.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', 'cyberark-epm')
      # STATE_KEY must stay OUTSIDE GCS_PREFIX. The feed ingests every object under
      # its bucket URI and, with a deletion option selected, deletes what it
      # transferred. A state file inside the prefix would be ingested as log data and
      # then deleted, resetting collection and re-ingesting duplicates.
      STATE_KEY = os.environ.get('STATE_KEY', 'cyberark-epm-state.json')
      EPM_LOGIN_URL = os.environ.get('EPM_LOGIN_URL', 'https://login.epm.cyberark.com')
      EPM_USERNAME = os.environ.get('EPM_USERNAME')
      EPM_PASSWORD = os.environ.get('EPM_PASSWORD')
      EPM_APPLICATION_ID = os.environ.get('EPM_APPLICATION_ID', 'GoogleSecOps')
      # Comma-separated set IDs to collect. Empty collects every set the user can view.
      EPM_SET_IDS = [s.strip() for s in os.environ.get('EPM_SET_IDS', '').split(',') if s.strip()]
      # API version segment. Empty uses the latest version, which CyberArk recommends.
      EPM_API_VERSION = os.environ.get('EPM_API_VERSION', '').strip()
      MAX_RECORDS = int(os.environ.get('MAX_RECORDS', '10000'))
      # The Events/Search API returns at most 1,000 records per page.
      PAGE_SIZE = min(int(os.environ.get('PAGE_SIZE', '1000')), 1000)
      LOOKBACK_HOURS = int(os.environ.get('LOOKBACK_HOURS', '24'))
      # The query re-reads this many minutes before the watermark. EPM agents report
      # in batches, so an event can reach the service well after its event date.
      # Re-read events are removed by content hash.
      OVERLAP_MINUTES = int(os.environ.get('OVERLAP_MINUTES', '15'))
      # The events APIs allow 5 calls per second; keep a small gap between calls.
      CALL_INTERVAL_SECONDS = 0.25
      
      class FetchError(Exception):
              """Raised when the EPM API call fails.
      
              The watermark must never advance on a failed fetch, otherwise the events in
              the failed window are skipped permanently.
              """
      
      def parse_datetime(value: str) -> datetime:
              """Parse an ISO 8601 datetime string into an aware datetime."""
              if value.endswith('Z'):
                      value = value[:-1] + '+00:00'
              dt = datetime.fromisoformat(value)
              if dt.tzinfo is None:
                      dt = dt.replace(tzinfo=timezone.utc)
              return dt
      
      def epm_time(dt: datetime) -> str:
              """Render a datetime in the YYYY-MM-DDThh:mm:ssZ form the EPM filter accepts."""
              return dt.astimezone(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ')
      
      def api_path(*parts: str) -> str:
              """Build an /EPM/API path, inserting the version segment when one is set."""
              segments = ['EPM', 'API']
              if EPM_API_VERSION:
                      segments.append(EPM_API_VERSION)
              segments.extend(parts)
              return '/' + '/'.join(segments)
      
      def event_keys(event: dict) -> set:
              """Return the identity this event can be recognised by.
      
              Raw events carry no unique event ID, so a record counts as already
              collected when its full JSON content was seen before. The overlap window
              returns the same JSON again, which this catches without any knowledge of
              the payload schema.
              """
              return {'sha256:' + hashlib.sha256(
                      json.dumps(event, sort_keys=True, ensure_ascii=False).encode('utf-8')
              ).hexdigest()}
      
      def event_time(event: dict) -> str:
              """Return the event timestamp as an ISO 8601 string, or an empty string.
      
              Raw events carry the time of the most recent occurrence in `lastEventDate`.
              """
              value = event.get('lastEventDate')
              return str(value) if value else ''
      
      @functions_framework.cloud_event
      def main(cloud_event):
              """Fetch CyberArk EPM raw events and write them to Cloud Storage.
      
              Args:
                      cloud_event: CloudEvent object containing the Pub/Sub message.
              """
              if not all([GCS_BUCKET, EPM_LOGIN_URL, EPM_USERNAME, EPM_PASSWORD]):
                      # Raise rather than return: a bare return acks the Pub/Sub message and
                      # reports the run as successful, silently discarding the schedule tick.
                      raise RuntimeError('Missing required environment variables')
      
              bucket = storage_client.bucket(GCS_BUCKET)
              state = load_state(bucket, STATE_KEY)
              set_states = state.get('sets', {})
      
              now = datetime.now(timezone.utc)
      
              manager_url, token = login()
              headers = {
                      'Authorization': f'basic {token}',
                      'Content-Type': 'application/json',
                      'Accept': 'application/json',
              }
      
              sets = list_sets(manager_url, headers)
              if EPM_SET_IDS:
                      sets = [s for s in sets if s['Id'] in EPM_SET_IDS]
                      missing = set(EPM_SET_IDS) - {s['Id'] for s in sets}
                      if missing:
                              raise FetchError(f'Configured set IDs not visible to this user: {sorted(missing)}')
              if not sets:
                      raise FetchError('No EPM sets are visible to this user; check the assigned role')
      
              fresh_all = []
              new_set_states = {}
              budget = MAX_RECORDS
      
              for epm_set in sets:
                      set_id = epm_set['Id']
                      set_state = set_states.get(set_id, {})
                      watermark = None
                      if set_state.get('last_event_time'):
                              watermark = parse_datetime(set_state['last_event_time'])
                      seen_keys = set(set_state.get('seen_keys', []))
      
                      if watermark is None:
                              start_time = now - timedelta(hours=LOOKBACK_HOURS)
                      else:
                              start_time = watermark - timedelta(minutes=OVERLAP_MINUTES)
      
                      print(f"Set {set_id} ({epm_set.get('Name', '')}): fetching events from {start_time.isoformat()} to {now.isoformat()}")
      
                      # A FetchError here propagates: the run fails, the watermark is untouched,
                      # and the next invocation retries the same window.
                      records, newest_event_time = fetch_events(
                              manager_url=manager_url,
                              headers=headers,
                              set_id=set_id,
                              start_time=start_time,
                              end_time=now,
                              page_size=PAGE_SIZE,
                              max_records=budget,
                      )
                      budget -= len(records)
      
                      # Remove events already written by an earlier run. Without this, the overlap
                      # window re-emits its events on every invocation.
                      fresh = [r for r in records if not (event_keys(r) & seen_keys)]
                      print(f"Set {set_id}: fetched {len(records)} records, {len(fresh)} new after deduplication")
      
                      if not fresh:
                              new_set_states[set_id] = set_state
                              continue
      
                      if not newest_event_time:
                              # A watermark that cannot be derived from the data is not a watermark.
                              # Advancing on wall-clock here would skip every late-reported event.
                              raise FetchError(f'Set {set_id}: records were returned but no event timestamp could be parsed')
      
                      # The parser reads the set from the event itself. Annotate copies so the
                      # deduplication hashes keep matching what the API returns next time.
                      fresh_all.extend({**record, 'setID': set_id} for record in fresh)
      
                      new_watermark = parse_datetime(newest_event_time)
                      if watermark and new_watermark < watermark:
                              new_watermark = watermark
      
                      # Retain only the hashes still inside the overlap window, so the state file
                      # stays small while covering every event the next query can re-read.
                      cutoff = new_watermark - timedelta(minutes=OVERLAP_MINUTES)
                      retained = set()
                      for record in records:
                              stamp = event_time(record)
                              if not stamp:
                                      continue
                              try:
                                      if parse_datetime(stamp) >= cutoff:
                                              retained.update(event_keys(record))
                              except ValueError:
                                      continue
      
                      new_set_states[set_id] = {
                              'last_event_time': new_watermark.isoformat(),
                              'seen_keys': sorted(retained),
                      }
      
                      if budget <= 0:
                              print(f"Reached max_records limit ({MAX_RECORDS}); remaining sets are collected by the next run")
                              break
      
              # Keep the state of sets not visited in this run.
              for set_id, set_state in set_states.items():
                      new_set_states.setdefault(set_id, set_state)
      
              if not fresh_all:
                      print("No new events found. Watermarks left unchanged.")
                      return
      
              timestamp = now.strftime('%Y%m%dT%H%M%SZ')
              object_key = f"{GCS_PREFIX}/events_{timestamp}.ndjson"
              blob = bucket.blob(object_key)
      
              ndjson = '\n'.join(json.dumps(record, ensure_ascii=False) for record in fresh_all) + '\n'
              blob.upload_from_string(ndjson, content_type='application/x-ndjson')
      
              print(f"Wrote {len(fresh_all)} records to gs://{GCS_BUCKET}/{object_key}")
      
              # Advance the watermarks only after the data is durably written.
              save_state(bucket, STATE_KEY, {'sets': new_set_states})
      
              print(f"Successfully processed {len(fresh_all)} records")
      
      def load_state(bucket, key):
              """Read the collector state from Cloud Storage.
      
              Only a missing object is treated as a cold start. Any other error is raised:
              swallowing it would silently reset collection to the full lookback window
              and re-ingest that entire period.
              """
              blob = bucket.blob(key)
              try:
                      return json.loads(blob.download_as_text())
              except NotFound:
                      print('No state file found. Starting from the lookback window.')
                      return {}
      
      def save_state(bucket, key, state: dict):
              """Write the collector state to Cloud Storage.
      
              Failures are raised, not logged. If the state write fails after the data was
              uploaded, the next run repeats the same window and duplicates it.
              """
              blob = bucket.blob(key)
              blob.upload_from_string(
                      json.dumps(state, indent=2),
                      content_type='application/json',
              )
              print(f"Saved state for {len(state.get('sets', {}))} sets")
      
      def request_json(method: str, url: str, headers: dict, body: dict = None):
              """Call the EPM API and return the decoded JSON body.
      
              Raises FetchError on any transport or HTTP failure, so that the caller does
              not mistake a failed call for an empty result and advance the watermark.
              """
              backoff = 1.0
              for attempt in range(5):
                      time.sleep(CALL_INTERVAL_SECONDS)
                      try:
                              response = http.request(
                                      method,
                                      url,
                                      body=json.dumps(body).encode('utf-8') if body is not None else None,
                                      headers=headers,
                              )
                      except Exception as e:
                              raise FetchError(f'Request to {url} failed: {e}') from e
      
                      if response.status == 429:
                              raw_retry_after = response.headers.get('Retry-After')
                              try:
                                      # Retry-After may also be an HTTP date, which int() cannot parse.
                                      wait = int(raw_retry_after) if raw_retry_after else int(backoff)
                              except (TypeError, ValueError):
                                      wait = int(backoff)
                              print(f"Rate limited (429). Retrying after {wait}s...")
                              time.sleep(wait)
                              backoff = min(backoff * 2, 30.0)
                              continue
      
                      if response.status != 200:
                              raise FetchError(f'HTTP {response.status} from {url}: {response.data.decode("utf-8", "replace")}')
      
                      try:
                              return json.loads(response.data.decode('utf-8'))
                      except json.JSONDecodeError as e:
                              raise FetchError(f'Malformed JSON response from {url}: {e}') from e
      
              raise FetchError('Rate limited repeatedly; giving up without advancing the watermark')
      
      def login():
              """Authenticate to EPM and return the manager URL and session token.
      
              EPM allows one API login per minute per user, so the function signs in once
              per run and reuses the token for every call in that run.
              """
              url = f"{EPM_LOGIN_URL.rstrip('/')}{api_path('Auth', 'EPM', 'Logon')}"
              body = {
                      'Username': EPM_USERNAME,
                      'Password': EPM_PASSWORD,
                      'ApplicationID': EPM_APPLICATION_ID,
              }
              data = request_json('POST', url, {'Content-Type': 'application/json'}, body)
              token = data.get('EPMAuthenticationResult')
              manager_url = data.get('ManagerURL')
              if not token or not manager_url:
                      raise FetchError(f'Login response did not contain a token and manager URL: {data}')
              if data.get('IsPasswordExpired'):
                      raise FetchError('The EPM user password has expired; set a new password and update EPM_PASSWORD')
              return manager_url.rstrip('/'), token
      
      def list_sets(manager_url: str, headers: dict):
              """Return the sets visible to the API user."""
              url = f"{manager_url}{api_path('Sets')}?{urlencode({'Offset': 0, 'Limit': 1000})}"
              data = request_json('GET', url, headers)
              sets = data.get('Sets') or []
              print(f"Found {len(sets)} sets")
              return sets
      
      def fetch_events(manager_url: str, headers: dict, set_id: str, start_time: datetime, end_time: datetime, page_size: int, max_records: int):
              """Fetch raw events for one set from the EPM Events/Search API.
      
              Pages with nextCursor, which returns events in chronological order. A time
              watermark is only correct over an ascending scan: with newest-first ordering
              a truncated run would advance the watermark past unread events.
      
              Returns:
                      Tuple of (records list, newest_event_time ISO string).
              """
              endpoint = f"{manager_url}{api_path('Sets', set_id, 'Events', 'Search')}"
              body = {
                      'filter': f'eventDate GE {epm_time(start_time)} AND eventDate LE {epm_time(end_time)}',
              }
      
              records = []
              newest_time = None
              cursor = 'start'
              page_num = 0
      
              while True:
                      page_num += 1
      
                      if len(records) >= max_records:
                              # Stop cleanly. The remaining events stay ahead of the watermark and
                              # are collected by the next run.
                              print(f"Set {set_id}: reached max_records limit ({max_records})")
                              break
      
                      # Rebuild the full query on every page; the time window must never be dropped.
                      url = f"{endpoint}?{urlencode({'nextCursor': cursor, 'limit': page_size})}"
                      data = request_json('POST', url, headers, body)
      
                      page_results = data.get('events') or []
                      if not page_results:
                              print(f"Set {set_id}: no more results (empty page)")
                              break
      
                      print(f"Set {set_id}: page {page_num} retrieved {len(page_results)} events")
                      records.extend(page_results)
      
                      for event in page_results:
                              stamp = event_time(event)
                              if not stamp:
                                      continue
                              try:
                                      if newest_time is None or parse_datetime(stamp) > parse_datetime(newest_time):
                                              newest_time = stamp
                              except ValueError as e:
                                      print(f"Warning: Could not parse event time {stamp!r}: {e}")
      
                      cursor = data.get('nextCursor')
                      if not cursor:
                              break
      
              print(f"Set {set_id}: retrieved {len(records)} total events from {page_num} pages")
              return records, newest_time
      

    • Deuxième fichier : requirements.txt:

      functions-framework==3.*
      google-cloud-storage==2.*
      urllib3>=2.0.0
      
  3. Cliquez sur Déployer pour enregistrer et déployer la fonction.

  4. Attendez la fin du déploiement (deux à trois minutes).

Comment la fonction collecte les événements

  • La fonction se connecte une fois par exécution, liste les ensembles que l'utilisateur peut consulter et appelle l'API Get detailed raw events de chaque ensemble avec un filtre sur eventDate, en paginant avec nextCursor par ordre chronologique.
  • Chaque événement est écrit avec le champ setID supplémentaire afin que l'ensemble soit conservé dans le journal.
  • Le fichier d'état conserve, par ensemble, le dernier lastEventDate vu et les hachages des événements dans la fenêtre de chevauchement. Chaque exécution relit OVERLAP_MINUTES avant ce filigrane et supprime les événements qu'elle a déjà écrits. Ainsi, les agents qui signalent un retard sont toujours collectés sans doublons.
  • Toute erreur d'API, de connexion ou de stockage entraîne l'échec de l'exécution et laisse le filigrane inchangé. Ainsi, l'exécution suivante réessaie la même fenêtre.

Créer une tâche Cloud Scheduler

Cloud Scheduler publiera des messages dans le sujet Pub/Sub à intervalles réguliers, ce qui déclenchera la fonction Cloud Run.

  1. Dans la consoleGoogle Cloud , accédez à Cloud Scheduler.
  2. Cliquez sur Créer une tâche.
  3. Fournissez les informations de configuration suivantes :

    Paramètre Valeur
    Nom cyberark-epm-collector-hourly
    Région Sélectionnez la même région que la fonction Cloud Run.
    Fréquence 0 * * * * (toutes les heures, à l'heure pile)
    Fuseau horaire Sélectionnez un fuseau horaire (UTC recommandé)
    Type de cible Pub/Sub
    Sujet Sélectionnez le sujet Pub/Sub cyberark-epm-trigger.
    Corps du message {} (objet JSON vide)
  4. Cliquez sur Créer.

Options de fréquence de programmation

Choisissez la fréquence en fonction du volume de journaux et des exigences de latence :

Fréquence Expression Cron Cas d'utilisation
Toutes les 15 minutes */15 * * * * Latence faible
Toutes les heures 0 * * * * Standard (recommandé)
Toutes les 6 heures 0 */6 * * * Traitement par lot de faible volume

Tester l'intégration

  1. Dans la console Cloud Scheduler, recherchez votre job.
  2. Cliquez sur Forcer l'exécution pour déclencher le job manuellement.
  3. Patientez pendant quelques secondes.
  4. Accédez à Cloud Run > Services.
  5. Cliquez sur le nom de votre fonction (cyberark-epm-collector).
  6. Cliquez sur l'onglet Journaux.
  7. Vérifiez que la fonction a bien été exécutée. Par exemple :

    Found N sets
    Set <set-id> (<set-name>): fetching events from YYYY-MM-DDTHH:MM:SS+00:00 to YYYY-MM-DDTHH:MM:SS+00:00
    Set <set-id>: page 1 retrieved X events
    Wrote X records to gs://cyberark-epm-secops-logs/cyberark-epm/events_YYYYMMDDTHHMMSSZ.ndjson
    Successfully processed X records
    
  8. Accédez à Cloud Storage > Buckets.

  9. Cliquez sur le nom de votre bucket.

  10. Accédez au dossier du préfixe (cyberark-epm/).

  11. Vérifiez qu'un nouveau fichier .ndjson a été créé avec le code temporel actuel.

Si des erreurs s'affichent dans les journaux :

  • HTTP 401 : vérifiez EPM_USERNAME et EPM_PASSWORD, ou que la connexion a été répétée dans un délai d'une minute.
  • HTTP 403 : l'utilisateur ne dispose pas d'un rôle sur l'ensemble, ou la limite d'utilisation de l'API du locataire a été atteinte.
  • HTTP 404 : ID d'ensemble incorrect dans EPM_SET_IDS
  • HTTP 429 : limitation du débit (la fonction effectue de nouvelles tentatives avec intervalle exponentiel entre les tentatives)
  • Variables d'environnement manquantes : vérifiez que toutes les variables requises sont définies.

Récupérer le compte de service Google SecOps

Google SecOps utilise un compte de service unique pour lire les données de votre bucket Cloud Storage. Vous devez accorder à ce compte de service l'accès à votre bucket.

Obtenir l'adresse e-mail du compte de service

  1. Accédez à Paramètres > Gestion des données > Flux. Si vous utilisez une plate-forme SIEM uniquement, accédez à Paramètres > Flux.
  2. Cliquez sur Ajouter un flux d'actualités.
  3. Cliquez sur Configurer un flux unique.
  4. Dans le champ Nom du flux, saisissez un nom pour le flux (par exemple, CyberArk EPM logs).
  5. Sélectionnez Google Cloud Storage V2 comme Type de source.
  6. Sélectionnez CyberArk Endpoint Privilege Manager (EPM) comme Type de journal.
  7. Cliquez sur Get Service Account (Obtenir un compte de service).
  8. Une adresse e-mail de compte de service unique s'affiche, par exemple :

    chronicle-12345678@chronicle-gcp-prod.iam.gserviceaccount.com
    
  9. Copiez cette adresse e-mail pour l'utiliser à l'étape suivante.

  10. Cliquez sur Suivant.

  11. Spécifiez les valeurs des paramètres d'entrée suivants :

    • URL du bucket de stockage : saisissez l'URI du bucket Cloud Storage avec le chemin d'accès du préfixe :

      gs://cyberark-epm-secops-logs/cyberark-epm/
      
      • Remplacez cyberark-epm-secops-logs par le nom de votre bucket Cloud Storage.
    • Option de suppression de la source : sélectionnez l'option de suppression de votre choix :

      • Ne jamais supprimer les fichiers : ne supprime jamais les fichiers de la source (recommandé pour les tests).
      • Supprimer les fichiers transférés et les répertoires vides : supprimez les fichiers et les répertoires vides de la source une fois la récupération terminée.

    • Âge maximal du fichier : incluez les fichiers modifiés au cours d'un certain nombre de jours (180 jours par défaut).

    • Espace de noms de l'élément : espace de noms de l'élément

    • Étiquettes d'ingestion : étiquette à appliquer aux événements de ce flux.

  12. Cliquez sur Suivant.

  13. Vérifiez la configuration de votre nouveau flux d'actualités sur l'écran Finaliser, puis cliquez sur Envoyer.

Accorder des autorisations IAM au compte de service Google SecOps

Le compte de service Google SecOps a besoin de deux rôles sur votre bucket Cloud Storage : Lecteur des objets Storage pour lire les objets de journal et un rôle au niveau du bucket pour lire les métadonnées du bucket.

  1. Accédez à Cloud Storage > Buckets.
  2. Cliquez sur le nom de votre bucket.
  3. Accédez à l'onglet Autorisations.
  4. Cliquez sur Accorder l'accès.
  5. Fournissez les informations de configuration suivantes :
    • Ajouter des comptes principaux : collez l'adresse e-mail du compte de service Google SecOps.
    • Attribuer des rôles : sélectionnez les deux rôles suivants :
      • Lecteur des objets de l'espace de stockage : lit les objets de journal.
      • Lecteur des anciens buckets Storage : lit les métadonnées du bucket. Si vous avez sélectionné l'option de suppression Supprimer les fichiers transférés et les répertoires vides, sélectionnez plutôt Rédacteur d'ancien bucket Storage, qui accorde également l'autorisation de suppression.
  6. Cliquez sur Enregistrer.

Table de mappage UDM

Champ du journal Mappage UDM Logique
accessTargetType_label additional.fields Fusionné
accessaction_label additional.fields Fusionné
agentEventCount_label additional.fields Fusionné
arrivalTime_label additional.fields Fusionné
deceptionType_label additional.fields Fusionné
eventCount_label additional.fields Fusionné
logonAttemptTypeId_label additional.fields Fusionné
logonStatusId_label additional.fields Fusionné
modificationTime_label additional.fields Fusionné
originalFileName_label additional.fields Fusionné
owner_label additional.fields Fusionné
packageName_label additional.fields Fusionné
publisher_field additional.fields Fusionné
publisher_label additional.fields Fusionné
setID_label additional.fields Fusionné
skippedCount_label additional.fields Fusionné
sourceProcessSigner_field additional.fields Fusionné
sourceProcessSigner_label additional.fields Fusionné
sourceType_label additional.fields Fusionné
threatProtectionActionId_label additional.fields Fusionné
threatProtectionAction_label additional.fields Fusionné
user_is_admin_label additional.fields Fusionné
winEventRecordId_label additional.fields Fusionné
winEventType_label additional.fields Fusionné
workingDirectory_label additional.fields Fusionné
displayName metadata.description Mappage direct
eachevent.displayName metadata.description Mappage direct
lastEventDate metadata.event_timestamp Analysé en tant que ISO8601
has_principal metadata.event_type Mappé : true → STATUS_UPDATE
has_principal_user metadata.event_type Mappé : true → USER_UNCATEGORIZED
eachevent.eventType metadata.product_event_type Mappage direct
eventType metadata.product_event_type Mappage direct
productName metadata.product_version Mappage direct
productVersion metadata.product_version Mappage direct
url network.http.referral_url Mappage direct
agentId principal.asset.asset_id Mappage direct
eachevent.agentId principal.asset.asset_id Mappage direct
computerName principal.asset.hostname Mappage direct
sourceName principal.file.full_path Mappage direct
computerName principal.hostname Mappage direct
eachevent.computerName principal.hostname Mappage direct
operatingSystemType principal.platform Mappage direct
operating_system_type principal.platform Mappé : Windows → WINDOWS
company principal.user.company_name Mappage direct
eachevent.userName principal.user.userid Mappage direct
userName principal.user.userid Mappage direct
sec_result security_result Fusionné
threat_protection_action security_result.action_details Mappage direct
fileDescription security_result.description Mappage direct
eachevent.policyName security_result.rule_name Mappage direct
policyName security_result.rule_name Mappage direct
justification security_result.summary Mappage direct
fileQualifier target.asset.asset_id Mappage direct
software target.asset.software Fusionné
eachevent.filePath target.file.full_path Mappage direct
filePath target.file.full_path Mappage direct
eachevent.hash target.file.sha1 Mappage direct
hash target.file.sha1 Mappage direct
fileSize target.file.size Mappage direct
eachevent.processCommandLine target.process.command_line Renommé/Mappé
processCommandLine target.process.command_line Mappage direct
fileName target.process.file.names Fusionné
eachevent.sourceProcessCommandLine target.process.parent_process.command_line Renommé/Mappé
sourceProcessCommandLine target.process.parent_process.command_line Mappage direct
each_event.sourceProcessHash target.process.parent_process.file.sha1 Renommé/Mappé
sourceProcessHash target.process.parent_process.file.sha1 Mappage direct
sourceProcessPublisher_label target.resource.attribute.labels Fusionné
exposed_accountName target.user.attribute.labels Fusionné
exposed_domain target.user.attribute.labels Fusionné
exposed_source target.user.attribute.labels Fusionné
exposed_username target.user.attribute.labels Fusionné
sourceProcessUsername target.user.userid Mappage direct
N/A metadata.event_type Constante : STATUS_UPDATE
N/A metadata.product_name Constante : EPM
N/A metadata.vendor_name Constante : CYBERARK
N/A principal.platform Constante : WINDOWS
N/A security_result.alert_state Constante : ALERTING

Journal des modifications

Afficher le journal des modifications de cet analyseur

Vous avez encore besoin d'aide ? Obtenez des réponses de membres de la communauté et de professionnels Google SecOps.