Mengumpulkan log CyberArk Endpoint Privilege Manager

Versi Parser: 2.0

Didukung di:

Dokumen ini menjelaskan cara menyerap log CyberArk Endpoint Privilege Manager (EPM) ke Google Security Operations menggunakan Cloud Storage V2.

CyberArk Endpoint Privilege Manager menerapkan hak istimewa terendah pada endpoint Windows, macOS, dan Linux dengan menghapus hak administrator lokal, mengontrol aplikasi mana yang dapat dijalankan atau ditingkatkan, dan melindungi kredensial dari pencurian. EPM SaaS mengekspos data peristiwanya melalui EPM REST API. Fungsi Cloud Run melakukan polling pada peristiwa mentah dari setiap set EPM dan menulisnya ke bucket Cloud Storage, tempat Google SecOps menyerapnya.

Sebelum memulai

Pastikan Anda memiliki prasyarat berikut:

  • Instance Google SecOps
  • Project Google Cloud dengan Cloud Storage API diaktifkan
  • Izin untuk membuat dan mengelola bucket Cloud Storage
  • Izin untuk mengelola kebijakan Identity and Access Management (IAM) di bucket Cloud Storage
  • Izin untuk membuat layanan Cloud Run, topik Pub/Sub, dan tugas Cloud Scheduler
  • Tenant SaaS CyberArk EPM
  • Administrator akun EPM untuk membuat pengguna dan peran API

Membuat bucket Cloud Storage

  1. Buka Google Cloud console.
  2. Pilih project Anda atau buat project baru.
  3. Di menu navigasi, buka Cloud Storage > Buckets.
  4. Klik Create bucket.
  5. Berikan detail konfigurasi berikut:

    Setelan Nilai
    Memberi nama bucket Anda Masukkan nama yang unik secara global (misalnya, cyberark-epm-secops-logs)
    Location type Pilih sesuai kebutuhan Anda (Region, Dual-region, Multi-region)
    Location Pilih lokasi (misalnya, us-central1)
    Storage class Standard (direkomendasikan untuk log yang sering diakses)
    Kontrol akses Seragam (direkomendasikan)
    Alat perlindungan Opsional: Mengaktifkan pembuatan versi objek atau kebijakan retensi
  6. Klik Create.

Mengumpulkan kredensial CyberArk EPM

Fungsi Cloud Run login ke EPM REST API dengan pengguna EPM. Buat pengguna khusus dengan akses hanya lihat ke set yang peristiwanya ingin Anda kumpulkan.

Membuat pengguna API

  1. Login ke konsol pengelolaan EPM sebagai administrator akun.
  2. Klik kotak Administration.
  3. Buka halaman Pengguna, lalu klik Tambahkan pengguna.
  4. Berikan detail konfigurasi berikut:
    • Email address: Masukkan nama login untuk pengguna integrasi (misalnya, secops-collector@example.com).
    • Sandi: Masukkan sandi yang berisi 12 hingga 128 karakter.
  5. Klik Tambahkan.
  6. Simpan nama dan sandi login dengan aman. Anda akan menggunakannya sebagai nilai EPM_USERNAME dan EPM_PASSWORD dari fungsi Cloud Run.

Membuat peran hanya lihat dan menetapkannya

  1. Di Administration, buka halaman Roles, lalu klik Create role.
  2. Berikan detail konfigurasi berikut:
    • Name: Masukkan nama untuk peran (misalnya, SecOps view only).
    • Grup izin: Pilih Hanya lihat.
    • Set: Pilih setiap set yang peristiwanya ingin Anda kumpulkan.
  3. Klik Create.
  4. Buka halaman Role assignment.
  5. Di baris peran yang Anda buat, klik Tindakan lainnya (...) > Tetapkan atau batalkan penetapan pengguna.
  6. Klik Assign users, telusuri pengguna integrasi, pilih pengguna tersebut, lalu klik Assign.
  7. Klik Simpan.

Menentukan URL login EPM

API autentikasi EPM disajikan oleh server dispatcher di region Anda. Fungsi ini menggunakan URL ini hanya untuk login; setiap panggilan lainnya mengarah ke URL pengelola yang ditampilkan oleh respons login.

Wilayah URL Login
AS https://login.epm.cyberark.com
Jerman https://eu.epm.cyberark.com
Swiss https://ch.epm.cyberark.com
Inggris Raya https://uk.epm.cyberark.com
Australia https://au.epm.cyberark.com
Kanada https://ca.epm.cyberark.com
India https://in.epm.cyberark.com
Jepang https://jp.epm.cyberark.com
Singapura https://sg.epm.cyberark.com
Italia https://it.epm.cyberark.com
Uni Emirat Arab https://ae.epm.cyberark.com
Federal https://login.epm.cyberarkgov.cloud

Menguji akses API

  • Uji kredensial sebelum melanjutkan integrasi sebagai berikut:

    # 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\"}"
    
  • Respons yang berhasil akan menampilkan EPMAuthenticationResult (token sesi) dan ManagerURL. Untuk mengonfirmasi peran, cantumkan set dengan token sebagai berikut:

    # 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"
    

Respons akan mencantumkan setiap set yang dapat dilihat pengguna. Jika Sets kosong, peran tidak ditetapkan atau tidak menyertakan set.

Membuat akun layanan untuk fungsi Cloud Run

Fungsi Cloud Run memerlukan akun layanan dengan izin untuk menulis ke bucket Cloud Storage dan dipanggil oleh Pub/Sub.

Membuat akun layanan

  1. Di Google Cloud konsol, buka IAM & Admin > Service Accounts.
  2. Klik Create Service Account.
  3. Berikan detail konfigurasi berikut:
    • Service account name: Masukkan cyberark-epm-collector-sa
    • Service account description: Masukkan Service account for Cloud Run function to collect CyberArk EPM logs
  4. Klik Create and Continue.
  5. Di bagian Grant this service account access to project, tambahkan peran berikut:
    1. Klik Pilih peran.
    2. Telusuri dan pilih Storage Object Admin.
    3. Klik + Add another role.
    4. Telusuri dan pilih Cloud Run Invoker.
    5. Klik + Add another role.
    6. Telusuri dan pilih Cloud Functions Invoker.
  6. Klik Lanjutkan.
  7. Klik Done.

Peran ini diperlukan untuk:

  • Storage Object Admin: Menulis log ke bucket Cloud Storage dan mengelola state file
  • Cloud Run Invoker: Mengizinkan Pub/Sub memanggil fungsi
  • Cloud Functions Invoker: Mengizinkan pemanggilan fungsi

Memberikan izin IAM pada bucket Cloud Storage

Beri akun layanan izin tulis di bucket Cloud Storage:

  1. Di konsolGoogle Cloud , buka Cloud Storage > Buckets.
  2. Klik nama bucket Anda.
  3. Buka tab Izin.
  4. Klik Grant access.
  5. Berikan detail konfigurasi berikut:
    • Tambahkan entitas: Masukkan email akun layanan (misalnya, cyberark-epm-collector-sa@PROJECT_ID.iam.gserviceaccount.com)
    • Assign roles: Pilih Storage Object Admin
  6. Klik Simpan.

Membuat topik Pub/Sub

Buat topik Pub/Sub yang akan dipublikasikan oleh Cloud Scheduler dan di-subscribe oleh fungsi Cloud Run.

  1. Di Google Cloud konsol, buka Pub/Sub > Topics.
  2. Klik Create topic.
  3. Berikan detail konfigurasi berikut:
    • ID Topik: Masukkan cyberark-epm-trigger
    • Biarkan setelan lainnya sesuai default
  4. Klik Create.

Membuat fungsi Cloud Run untuk mengumpulkan log

Fungsi Cloud Run akan dipicu oleh pesan Pub/Sub dari Cloud Scheduler untuk mengambil peristiwa mentah dari CyberArk EPM REST API dan menulisnya ke Cloud Storage.

  1. Di konsolGoogle Cloud , buka Cloud Run.
  2. Klik Write a function.
  3. Di bagian Configure, berikan detail konfigurasi berikut:

    Setelan Nilai
    Nama layanan cyberark-epm-collector
    Region Pilih region yang cocok dengan bucket Cloud Storage Anda (misalnya, us-central1)
    Runtime Pilih Python 3.12 atau yang lebih baru
  4. Di bagian Trigger, klik Add trigger, lalu pilih Pub/Sub trigger.

  5. Di panel Eventarc trigger, berikan detail konfigurasi berikut:

    • Trigger name: Tetap gunakan nama yang dihasilkan atau masukkan nama untuk pemicu.
    • Jenis pemicu: Pilih Sumber Google.
    • Event provider: Pilih Pub/Sub.
    • Jenis peristiwa: Pilih google.cloud.pubsub.topic.v1.messagePublished.
    • Select a Cloud Pub/Sub topic: Pilih topik cyberark-epm-trigger.
    • Region: Pilih region yang sama dengan fungsi.
    • Service account: Pilih akun layanan cyberark-epm-collector-sa.
  6. Klik Save trigger.

  7. Di bagian Authentication:

    1. Pilih Wajibkan autentikasi.
    2. Pilih Identity and Access Management (IAM).
  8. Buka dan luaskan Containers, Networking, Security.

  9. Buka tab Keamanan:

    • Service account: Pilih akun layanan cyberark-epm-collector-sa
  10. Buka tab Penampung:

    1. Klik Variables & Secrets.
    2. Klik + Add variable untuk setiap variabel lingkungan:
    Nama Variabel Nilai Contoh Deskripsi
    GCS_BUCKET cyberark-epm-secops-logs Nama bucket Cloud Storage
    GCS_PREFIX cyberark-epm Awalan untuk file log
    STATE_KEY cyberark-epm-state.json Jalur status, di luar awalan log
    EPM_LOGIN_URL https://login.epm.cyberark.com URL login EPM untuk wilayah Anda
    EPM_USERNAME secops-collector@example.com Nama login pengguna EPM API
    EPM_PASSWORD <your-password> Sandi pengguna EPM API
    EPM_APPLICATION_ID GoogleSecOps Nama aplikasi yang dilaporkan saat login
    EPM_SET_IDS (kosong) ID set opsional yang dipisahkan koma; jika kosong, semua set yang dapat dilihat pengguna akan dikumpulkan
    EPM_API_VERSION (kosong) Versi API opsional (misalnya, 24.12.0.1); jika kosong, versi terbaru akan digunakan
    MAX_RECORDS 10000 Data maksimum per operasi
    PAGE_SIZE 1000 Data per halaman (maksimum API adalah 1.000)
    LOOKBACK_HOURS 24 Periode lihat balik awal pada operasi pertama
    OVERLAP_MINUTES 15 Membaca ulang periode sebelum watermark, untuk menangkap peristiwa yang dilaporkan terlambat oleh agen
  11. Di bagian Variables & Secrets, buka Requests:

    • Request timeout: Masukkan 600 detik (10 menit)
  12. Buka tab Setelan:

    • Di bagian Resources:
      • Memory: Pilih 512 MiB atau lebih tinggi
      • CPU: Pilih 1
  13. Di bagian Revision scaling:

    • Minimum number of instances: Masukkan 0
    • Maximum number of instances: Masukkan 1
  14. Klik Create.

  15. Tunggu hingga layanan dibuat (1-2 menit).

  16. Setelah layanan dibuat, editor kode inline akan terbuka secara otomatis.

Menambahkan kode fungsi

  1. Masukkan main di kolom Entry point.
  2. Di editor kode inline, buat dua file:

    • File pertama - 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
      

    • File kedua - requirements.txt:

      functions-framework==3.*
      google-cloud-storage==2.*
      urllib3>=2.0.0
      
  3. Klik Deploy untuk menyimpan dan men-deploy fungsi.

  4. Tunggu hingga deployment selesai (2-3 menit).

Cara fungsi mengumpulkan peristiwa

  • Fungsi ini login sekali per operasi, mencantumkan set yang dapat dilihat pengguna, dan memanggil API Dapatkan peristiwa mentah mendetail dari setiap set dengan filter pada eventDate, paging dengan nextCursor dalam urutan kronologis.
  • Setiap peristiwa ditulis dengan kolom setID tambahan sehingga set dipertahankan dalam log.
  • File status menyimpan, per set, lastEventDate terbaru yang terlihat dan hash peristiwa di dalam jendela tumpang-tindih. Setiap operasi akan membaca ulang OVERLAP_MINUTES sebelum watermark tersebut dan menghapus peristiwa yang telah ditulis, sehingga agen yang terlambat melaporkan tetap dikumpulkan tanpa duplikat.
  • Setiap error API, login, atau penyimpanan akan menggagalkan proses dan membuat watermark tidak berubah, sehingga proses berikutnya akan mencoba ulang periode yang sama.

Buat tugas Cloud Scheduler

Cloud Scheduler akan memublikasikan pesan ke topik Pub/Sub secara berkala, sehingga memicu fungsi Cloud Run.

  1. Di konsolGoogle Cloud , buka Cloud Scheduler.
  2. Klik Create Job.
  3. Berikan detail konfigurasi berikut:

    Setelan Nilai
    Nama cyberark-epm-collector-hourly
    Region Pilih region yang sama dengan fungsi Cloud Run
    Frekuensi 0 * * * * (setiap jam, tepat pada jamnya)
    Zona Waktu Pilih zona waktu (UTC direkomendasikan)
    Jenis target Pub/Sub
    Topik Pilih topik Pub/Sub cyberark-epm-trigger
    Isi pesan {} (objek JSON kosong)
  4. Klik Create.

Opsi frekuensi jadwal

Pilih frekuensi berdasarkan volume log dan persyaratan latensi:

Frekuensi Ekspresi Cron Kasus Penggunaan
Setiap 15 menit */15 * * * * Latensi rendah
Setiap jam 0 * * * * Standar (direkomendasikan)
Setiap 6 jam 0 */6 * * * Volume rendah, pemrosesan batch

Menguji integrasi

  1. Di konsol Cloud Scheduler, temukan tugas Anda.
  2. Klik Force run untuk memicu tugas secara manual.
  3. Tunggu beberapa detik.
  4. Buka Cloud Run > Services.
  5. Klik nama fungsi Anda (cyberark-epm-collector).
  6. Klik tab Logs.
  7. Pastikan fungsi berhasil dieksekusi. Cari:

    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. Buka Cloud Storage > Buckets.

  9. Klik nama bucket Anda.

  10. Buka folder awalan (cyberark-epm/).

  11. Pastikan file .ndjson baru telah dibuat dengan stempel waktu saat ini.

Jika Anda melihat error di log:

  • HTTP 401: Periksa EPM_USERNAME dan EPM_PASSWORD, atau apakah login diulang dalam satu menit
  • HTTP 403: Pengguna tidak memiliki peran di set, atau batas penggunaan API tenant telah tercapai
  • HTTP 404: ID set salah di EPM_SET_IDS
  • HTTP 429: Pembatasan kapasitas - fungsi mencoba ulang dengan backoff
  • Variabel lingkungan tidak ada: Pastikan semua variabel yang diperlukan telah ditetapkan

Mengambil akun layanan Google SecOps

Google SecOps menggunakan akun layanan unik untuk membaca data dari bucket Cloud Storage Anda. Anda harus memberi akun layanan ini akses ke bucket Anda.

Mendapatkan email akun layanan

  1. Buka Setelan > Pengelolaan Data > Feed. Jika Anda menggunakan platform khusus SIEM, buka Settings > Feeds.
  2. Klik Tambahkan Feed Berita Baru.
  3. Klik Konfigurasi satu feed.
  4. Di kolom Nama feed, masukkan nama untuk feed (misalnya, CyberArk EPM logs).
  5. Pilih Google Cloud Storage V2 sebagai Source type.
  6. Pilih CyberArk Endpoint Privilege Manager (EPM) sebagai Log type.
  7. Klik Get Service Account.
  8. Email akun layanan yang unik akan ditampilkan, misalnya:

    chronicle-12345678@chronicle-gcp-prod.iam.gserviceaccount.com
    
  9. Salin alamat email ini untuk digunakan di langkah berikutnya.

  10. Klik Berikutnya.

  11. Tentukan nilai untuk parameter input berikut:

    • Storage bucket URL: Masukkan URI bucket Cloud Storage dengan jalur awalan:

      gs://cyberark-epm-secops-logs/cyberark-epm/
      
      • Ganti cyberark-epm-secops-logs dengan nama bucket Cloud Storage Anda.
    • Opsi penghapusan sumber: Pilih opsi penghapusan sesuai preferensi Anda:

      • Jangan pernah menghapus file: Jangan pernah menghapus file dari sumber (direkomendasikan untuk pengujian).
      • Hapus file yang ditransfer dan direktori kosong: Hapus file dan direktori kosong dari sumber setelah pengambilan berhasil diselesaikan.

    • Usia File Maksimum: Sertakan file yang diubah dalam jumlah hari terakhir (defaultnya adalah 180 hari)

    • Namespace aset: Namespace aset

    • Label penyerapan: Label yang akan diterapkan ke peristiwa dari feed ini

  12. Klik Berikutnya.

  13. Tinjau konfigurasi feed berita baru Anda di layar Finalize, lalu klik Submit.

Memberikan izin IAM ke akun layanan Google SecOps

Akun layanan Google SecOps memerlukan dua peran di bucket Cloud Storage Anda: Storage Object Viewer untuk membaca objek log, dan peran level bucket untuk membaca metadata bucket.

  1. Buka Cloud Storage > Buckets.
  2. Klik nama bucket Anda.
  3. Buka tab Izin.
  4. Klik Grant access.
  5. Berikan detail konfigurasi berikut:
    • Add principals: Tempel email akun layanan Google SecOps
    • Assign roles: Pilih kedua opsi berikut:
      • Storage Object Viewer: membaca objek log.
      • Storage Legacy Bucket Reader: membaca metadata bucket. Jika Anda memilih opsi penghapusan Delete transferred files and empty directories, pilih Storage Legacy Bucket Writer, yang juga memberikan izin penghapusan.
  6. Klik Simpan.

Tabel pemetaan UDM

Kolom Log Pemetaan UDM Logika
accessTargetType_label additional.fields Digabung
accessaction_label additional.fields Digabung
agentEventCount_label additional.fields Digabung
arrivalTime_label additional.fields Digabung
deceptionType_label additional.fields Digabung
eventCount_label additional.fields Digabung
logonAttemptTypeId_label additional.fields Digabung
logonStatusId_label additional.fields Digabung
modificationTime_label additional.fields Digabung
originalFileName_label additional.fields Digabung
owner_label additional.fields Digabung
packageName_label additional.fields Digabung
publisher_field additional.fields Digabung
publisher_label additional.fields Digabung
setID_label additional.fields Digabung
skippedCount_label additional.fields Digabung
sourceProcessSigner_field additional.fields Digabung
sourceProcessSigner_label additional.fields Digabung
sourceType_label additional.fields Digabung
threatProtectionActionId_label additional.fields Digabung
threatProtectionAction_label additional.fields Digabung
user_is_admin_label additional.fields Digabung
winEventRecordId_label additional.fields Digabung
winEventType_label additional.fields Digabung
workingDirectory_label additional.fields Digabung
displayName metadata.description Dipetakan secara langsung
eachevent.displayName metadata.description Dipetakan secara langsung
lastEventDate metadata.event_timestamp Diurai sebagai ISO8601
has_principal metadata.event_type Dipetakan: true → STATUS_UPDATE
has_principal_user metadata.event_type Dipetakan: true → USER_UNCATEGORIZED
eachevent.eventType metadata.product_event_type Dipetakan secara langsung
eventType metadata.product_event_type Dipetakan secara langsung
productName metadata.product_version Dipetakan secara langsung
productVersion metadata.product_version Dipetakan secara langsung
url network.http.referral_url Dipetakan secara langsung
agentId principal.asset.asset_id Dipetakan secara langsung
eachevent.agentId principal.asset.asset_id Dipetakan secara langsung
computerName principal.asset.hostname Dipetakan secara langsung
sourceName principal.file.full_path Dipetakan secara langsung
computerName principal.hostname Dipetakan secara langsung
eachevent.computerName principal.hostname Dipetakan secara langsung
operatingSystemType principal.platform Dipetakan secara langsung
operating_system_type principal.platform Dipetakan: Windows → WINDOWS
company principal.user.company_name Dipetakan secara langsung
eachevent.userName principal.user.userid Dipetakan secara langsung
userName principal.user.userid Dipetakan secara langsung
sec_result security_result Digabung
threat_protection_action security_result.action_details Dipetakan secara langsung
fileDescription security_result.description Dipetakan secara langsung
eachevent.policyName security_result.rule_name Dipetakan secara langsung
policyName security_result.rule_name Dipetakan secara langsung
justification security_result.summary Dipetakan secara langsung
fileQualifier target.asset.asset_id Dipetakan secara langsung
software target.asset.software Digabung
eachevent.filePath target.file.full_path Dipetakan secara langsung
filePath target.file.full_path Dipetakan secara langsung
eachevent.hash target.file.sha1 Dipetakan secara langsung
hash target.file.sha1 Dipetakan secara langsung
fileSize target.file.size Dipetakan secara langsung
eachevent.processCommandLine target.process.command_line Diganti namanya/dipetakan
processCommandLine target.process.command_line Dipetakan secara langsung
fileName target.process.file.names Digabung
eachevent.sourceProcessCommandLine target.process.parent_process.command_line Diganti namanya/dipetakan
sourceProcessCommandLine target.process.parent_process.command_line Dipetakan secara langsung
each_event.sourceProcessHash target.process.parent_process.file.sha1 Diganti namanya/dipetakan
sourceProcessHash target.process.parent_process.file.sha1 Dipetakan secara langsung
sourceProcessPublisher_label target.resource.attribute.labels Digabung
exposed_accountName target.user.attribute.labels Digabung
exposed_domain target.user.attribute.labels Digabung
exposed_source target.user.attribute.labels Digabung
exposed_username target.user.attribute.labels Digabung
sourceProcessUsername target.user.userid Dipetakan secara langsung
T/A metadata.event_type Konstanta: STATUS_UPDATE
T/A metadata.product_name Konstanta: EPM
T/A metadata.vendor_name Konstanta: CYBERARK
T/A principal.platform Konstanta: WINDOWS
T/A security_result.alert_state Konstanta: ALERTING

Log Perubahan

Melihat Log Perubahan untuk parser ini

Perlu bantuan lain? Dapatkan jawaban dari anggota Komunitas dan profesional Google SecOps.