Mengumpulkan log Smartsheet

Didukung di:

Dokumen ini menjelaskan cara menyerap log Smartsheet ke Google Security Operations menggunakan Google Cloud Storage.

Smartsheet adalah platform pengelolaan kerja kolaboratif yang menyediakan pengelolaan proyek seperti spreadsheet, pelacakan tugas, dan otomatisasi alur kerja untuk tim perusahaan. Event Reporting API menyediakan log audit yang mencakup lebih dari 100 jenis peristiwa, termasuk tindakan pengguna, akses data, perubahan berbagi, dan operasi administratif di seluruh organisasi Smartsheet Anda.

Sebelum memulai

Pastikan Anda memiliki prasyarat berikut:

  • Instance Google SecOps
  • Project GCP dengan Cloud Storage API diaktifkan
  • Izin untuk membuat dan mengelola bucket GCS
  • Izin untuk mengelola kebijakan IAM di bucket GCS
  • Izin untuk membuat fungsi Cloud Run, topik Pub/Sub, dan tugas Cloud Scheduler
  • Paket Smartsheet Enterprise dengan add-on Pelaporan Peristiwa diaktifkan
  • Akun Admin Sistem Smartsheet dengan akses API

Kumpulkan kredensial Smartsheet API

Buat token akses API

  1. Login ke akun Smartsheet Anda dengan akun Admin Sistem.
  2. Di bagian bawah panel navigasi kiri, pilih Akun (gambar profil) Anda, lalu buka Setelan Pribadi.
  3. Buka tab Akses API.
  4. Klik Buat token akses baru.
  5. Masukkan nama untuk token (misalnya, SecOps SIEM Integration).
  6. Klik Oke.

  7. Salin dan simpan token akses dengan aman.

Memverifikasi izin

Untuk memverifikasi bahwa akun memiliki izin yang diperlukan:

  1. Login ke akun Smartsheet Anda.
  2. Buka Akun (gambar profil) > Setelan Pribadi > Akses API.
  3. Jika Anda dapat melihat halaman Kelola Token Akses API dan membuat token, berarti Anda memiliki izin yang diperlukan.
  4. Jika Anda tidak dapat mengakses opsi ini, hubungi Admin Sistem Smartsheet Anda untuk memberikan akses API.

Menguji akses API

  • Uji kredensial Anda sebelum melanjutkan integrasi:

    # Replace with your actual access token
SMARTSHEET_TOKEN="<your-access-token>"

# Test Event Reporting API access
curl -v -H "Authorization: Bearer ${SMARTSHEET_TOKEN}" \
  "https://api.smartsheet.com/2.0/events?since=$(date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ)&maxCount=10"

Jika Anda melihat error ini:

  • HTTP 401: Verifikasi bahwa token akses sudah benar.
  • HTTP 403: Pastikan akun memiliki hak istimewa Admin Sistem dan add-on Pelaporan Peristiwa diaktifkan untuk paket Anda.

Buat bucket Google Cloud Storage

  1. Buka Konsol Google Cloud.
  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
    Beri nama bucket Anda Masukkan nama yang unik secara global (misalnya, smartsheet-audit-logs)
    Location type Pilih berdasarkan kebutuhan Anda (Region, Dual-region, Multi-region)
    Location Pilih lokasi (misalnya, us-central1)
    Kelas penyimpanan Standar (direkomendasikan untuk log yang sering diakses)
    Kontrol akses Seragam (direkomendasikan)
    Alat perlindungan Opsional: Aktifkan pembuatan versi objek atau kebijakan retensi

  6. Klik Create.

Buat akun layanan untuk fungsi Cloud Run

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

Membuat akun layanan

  1. Di Konsol GCP, buka IAM & Admin > Service Accounts.
  2. Klik Create Service Account.
  3. Berikan detail konfigurasi berikut:
    • Nama akun layanan: Masukkan smartsheet-logs-sa.
    • Deskripsi akun layanan: Masukkan Service account for Cloud Run function to collect Smartsheet audit 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 GCS dan mengelola file status
  • Cloud Run Invoker: Izinkan Pub/Sub memanggil fungsi
  • Cloud Functions Invoker: Mengizinkan pemanggilan fungsi

Memberikan izin IAM pada bucket GCS

Beri akun layanan izin tulis di bucket GCS:

  1. Buka Cloud Storage > Buckets.
  2. Klik nama bucket Anda (misalnya, smartsheet-audit-logs).
  3. Buka tab Izin.
  4. Klik Grant access.
  5. Berikan detail konfigurasi berikut:
    • Tambahkan prinsipal: Masukkan email akun layanan (misalnya, smartsheet-logs-sa@PROJECT_ID.iam.gserviceaccount.com).
    • Tetapkan peran: Pilih Storage Object Admin.
  6. Klik Simpan.

Membuat topik Pub/Sub

Buat topik Pub/Sub yang akan dipublikasikan oleh Cloud Scheduler dan akan dilanggan oleh fungsi Cloud Run.

  1. Di Konsol GCP, buka Pub/Sub > Topics.
  2. Klik Create topic.
  3. Berikan detail konfigurasi berikut:
    • ID Topik: Masukkan smartsheet-logs-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 log dari Smartsheet Event Reporting API dan menuliskannya ke GCS.

  1. Di Konsol GCP, buka Cloud Run.
  2. Klik Create service.
  3. Pilih Function (gunakan editor inline untuk membuat fungsi).

  4. Di bagian Konfigurasi, berikan detail konfigurasi berikut:

    Setelan Nilai
    Nama layanan smartsheet-logs-to-gcs
    Region Pilih region yang cocok dengan bucket GCS Anda (misalnya, us-central1)
    Runtime Pilih Python 3.12 atau yang lebih baru

  5. Di bagian Pemicu (opsional):

    1. Klik + Tambahkan pemicu.
    2. Pilih Cloud Pub/Sub.
    3. Di Select a Cloud Pub/Sub topic, pilih smartsheet-logs-trigger.
    4. Klik Simpan.

  6. Di bagian Authentication:

    1. Pilih Wajibkan autentikasi.
    2. Periksa Identity and Access Management (IAM).

  7. Scroll ke bawah dan luaskan Containers, Networking, Security.

  8. Buka tab Security:

    • Akun layanan: Pilih smartsheet-logs-sa.

  9. Buka tab Containers:

    1. Klik Variables & Secrets.
    2. Klik + Tambahkan variabel untuk setiap variabel lingkungan:
    Nama Variabel Nilai Contoh
    GCS_BUCKET smartsheet-audit-logs
    GCS_PREFIX smartsheet/events/
    STATE_KEY smartsheet/events/state.json
    SMARTSHEET_TOKEN <your-smartsheet-access-token>
    MAX_COUNT 1000
    TIMEOUT 30

  10. Di bagian Variables & Secrets, scroll ke bawah ke Requests:

    • Waktu tunggu permintaan: Masukkan 600 detik (10 menit).

  11. Buka tab Setelan:

    • Di bagian Referensi:
      • Memori: Pilih 512 MiB atau lebih tinggi.
      • CPU: Pilih 1.

  12. Di bagian Penskalaan revisi:

    • Minimum number of instances: Masukkan 0.
    • Maximum number of instances: Masukkan 100 (atau sesuaikan berdasarkan perkiraan beban).

  13. Klik Create.

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

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

Tambahkan kode fungsi

  1. Masukkan main di Function entry point.

  2. Di editor kode inline, buat dua file:

    • File pertama: main.py:

      import functions_framework
from google.cloud import storage
import json
import os
import urllib3
from datetime import datetime, timezone
import uuid
import gzip
import io

# 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', 'smartsheet/events/')
STATE_KEY = os.environ.get('STATE_KEY', 'smartsheet/events/state.json')
SMARTSHEET_TOKEN = os.environ.get('SMARTSHEET_TOKEN')
MAX_COUNT = int(os.environ.get('MAX_COUNT', '1000'))
TIMEOUT = int(os.environ.get('TIMEOUT', '30'))

EVENTS_URL = "https://api.smartsheet.com/2.0/events"

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

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

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

  try:
    bucket = storage_client.bucket(GCS_BUCKET)

    # Load state
    state = load_state(bucket, STATE_KEY)
    stream_position = state.get('stream_position')

    print(f'Fetching events from stream position: {stream_position or "latest"}')

    # Fetch events
    total_written = 0
    has_more = True

    while has_more:
      events, new_position, more = fetch_events(stream_position)

      if events:
        write_chunk(bucket, events, datetime.now(timezone.utc))
        total_written += len(events)

      if new_position:
        stream_position = new_position

      has_more = more and total_written < 50000

    # Save state
    state['stream_position'] = stream_position
    save_state(bucket, STATE_KEY, state)

    print(f'Successfully processed {total_written} events')

  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: {str(e)}')

  return {}

def save_state(bucket, key, state):
  """Save state to GCS."""
  try:
    state['updated_at'] = datetime.now(timezone.utc).isoformat()
    blob = bucket.blob(key)
    blob.upload_from_string(
      json.dumps(state),
      content_type='application/json'
    )
  except Exception as e:
    print(f'Warning: Could not save state: {str(e)}')

def write_chunk(bucket, items, ts):
  """Write log chunk to GCS as compressed NDJSON."""
  key = f"{GCS_PREFIX}{ts:%Y/%m/%d}/smartsheet-events-{uuid.uuid4()}.json.gz"

  buf = io.BytesIO()
  with gzip.GzipFile(fileobj=buf, mode='w') as gz:
    for rec in items:
      gz.write((json.dumps(rec) + '\n').encode('utf-8'))

  buf.seek(0)
  blob = bucket.blob(key)
  blob.upload_from_file(buf, content_type='application/gzip')

  print(f'Wrote {len(items)} events to {key}')
  return key

def fetch_events(stream_position):
  """
  Fetch events from Smartsheet Event Reporting API.

  The API uses a streaming model with streamPosition for pagination.
  On first call (no streamPosition), it returns the current position
  without events. Subsequent calls return events since the position.

  Returns:
    Tuple of (events list, new stream position, has more data)
  """
  headers = {
    'Authorization': f'Bearer {SMARTSHEET_TOKEN}',
    'Accept': 'application/json'
  }

  params = [f'maxCount={MAX_COUNT}']
  if stream_position:
    params.append(f'streamPosition={stream_position}')

  url = f"{EVENTS_URL}?{'&'.join(params)}"

  response = http.request(
    'GET',
    url,
    headers=headers,
    timeout=TIMEOUT
  )

  if response.status == 429:
    retry_after = int(response.headers.get('Retry-After', '60'))
    print(f'Rate limited (429). Retry-After: {retry_after}s')
    import time
    time.sleep(min(retry_after, 120))
    return fetch_events(stream_position)

  if response.status != 200:
    print(f'API request failed: {response.status}')
    response_text = response.data.decode('utf-8')
    print(f'Response body: {response_text}')
    raise Exception(f'Failed to fetch events: {response.status}')

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

  events = data.get('data', []) or []
  new_position = data.get('nextStreamPosition')
  more_available = data.get('moreEventsAvailable', False)

  if events:
    print(f'Retrieved {len(events)} events')

  return events, new_position, more_available

    • 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).

Buat tugas Cloud Scheduler

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

  1. Di Konsol GCP, buka Cloud Scheduler.
  2. Klik Create Job.

  3. Berikan detail konfigurasi berikut:

    Setelan Nilai
    Nama smartsheet-logs-schedule-15min
    Region Pilih region yang sama dengan fungsi Cloud Run
    Frekuensi */15 * * * * (setiap 15 menit)
    Zona Waktu Pilih zona waktu (UTC direkomendasikan)
    Jenis target Pub/Sub
    Topik Pilih smartsheet-logs-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 5 menit */5 * * * * Volume tinggi, latensi rendah
Setiap 15 menit */15 * * * * Standar (direkomendasikan)
Setiap jam 0 * * * * Volume rendah
Setiap 6 jam 0 */6 * * * Batch processing

Menguji integrasi

  1. Di konsol Cloud Scheduler, temukan tugas Anda (misalnya, smartsheet-logs-schedule-15min).
  2. Klik Force run untuk memicu tugas secara manual.
  3. Tunggu beberapa detik.
  4. Buka Cloud Run > Services.
  5. Klik nama fungsi (smartsheet-logs-to-gcs).
  6. Klik tab Logs.

  7. Pastikan fungsi berhasil dieksekusi. Cari:

    Fetching events from stream position: <position>
Retrieved X events
Wrote X events to smartsheet/events/YYYY/MM/DD/smartsheet-events-UUID.json.gz
Successfully processed X events

  8. Buka Cloud Storage > Buckets.

  9. Klik nama bucket Anda (smartsheet-audit-logs).

  10. Buka folder awalan (smartsheet/events/).

  11. Pastikan file .json.gz baru dibuat dengan stempel waktu saat ini.

Jika Anda melihat error dalam log:

  • HTTP 401: Periksa token akses Smartsheet di variabel lingkungan
  • HTTP 403: Pastikan akun memiliki hak istimewa Admin Sistem dan Pelaporan Peristiwa diaktifkan
  • HTTP 429: Pembatasan kecepatan - fungsi akan otomatis mencoba lagi dengan penundaan
  • Variabel lingkungan tidak ada: Pastikan semua variabel yang diperlukan ditetapkan dalam konfigurasi fungsi Cloud Run

Mengambil akun layanan Google SecOps

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

Mengonfigurasi feed di Google SecOps untuk menyerap log Smartsheet

  1. Buka Setelan SIEM > Feed.
  2. Klik Tambahkan Feed Baru.
  3. Klik Konfigurasi satu feed.
  4. Di kolom Nama feed, masukkan nama untuk feed (misalnya, Smartsheet Audit Logs).
  5. Pilih Google Cloud Storage V2 sebagai Source type.
  6. Pilih Smartsheet sebagai Jenis log.

  7. Klik Get Service Account. Email akun layanan yang unik akan ditampilkan, misalnya:

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

  8. Salin alamat email ini. Anda akan menggunakannya pada langkah berikutnya.

  9. Klik Berikutnya.

  10. Tentukan nilai untuk parameter input berikut:

    • URL bucket penyimpanan: Masukkan URI bucket GCS dengan jalur awalan:
    gs://smartsheet-audit-logs/smartsheet/events/

    • Ganti:

      • smartsheet-audit-logs: Nama bucket GCS Anda.
      • smartsheet/events/: Jalur awalan tempat log disimpan.
    • Opsi penghapusan sumber: Pilih opsi penghapusan sesuai preferensi Anda:
      • Jangan pernah: Tidak pernah menghapus file apa pun setelah transfer (direkomendasikan untuk pengujian).
      • Hapus file yang ditransfer: Menghapus file setelah transfer berhasil.
      • Hapus file yang ditransfer dan direktori kosong: Menghapus file dan direktori kosong setelah transfer berhasil.
    • Usia File Maksimum: Menyertakan file yang diubah dalam beberapa hari terakhir. Defaultnya adalah 180 hari.
    • Namespace aset: Namespace aset.
    • Label penyerapan: Label yang akan diterapkan ke peristiwa dari feed ini.

  11. Klik Berikutnya.

  12. Tinjau konfigurasi feed baru Anda di layar Selesaikan, lalu klik Kirim.

Memberikan izin IAM ke akun layanan Google SecOps

Akun layanan Google SecOps memerlukan peran Storage Object Viewer di bucket GCS Anda.

  1. Buka Cloud Storage > Buckets.
  2. Klik nama bucket Anda (misalnya, smartsheet-audit-logs).
  3. Buka tab Izin.
  4. Klik Grant access.
  5. Berikan detail konfigurasi berikut:
    • Add principals: Tempel email akun layanan Google SecOps.
    • Tetapkan peran: Pilih Storage Object Viewer.

  6. Klik Simpan.

Tabel pemetaan UDM

Kolom Log Pemetaan UDM Logika
accessLevel_label additional.fields Digabung
appName_label additional.fields Digabung
attachmentName_label additional.fields Digabung
cellLinkSourceSheetId_label additional.fields Digabung
dashboardName_label additional.fields Digabung
folderName_label additional.fields Digabung
formatType_label additional.fields Digabung
includeAttachments_label additional.fields Digabung
includeDiscussions_label additional.fields Digabung
mergeType_label additional.fields Digabung
rowCount_label additional.fields Digabung
rowsMoved_label additional.fields Digabung
sheetId_label additional.fields Digabung
sheetName_label additional.fields Digabung
sheetRowId_label additional.fields Digabung
sourceFolderId_label additional.fields Digabung
sourceObjectId_label additional.fields Digabung
sourceSheetId_label additional.fields Digabung
sourceType_label additional.fields Digabung
tokenDisplayValue_label additional.fields Digabung
tokenUserId_label additional.fields Digabung
userId_label additional.fields Digabung
workspaceId_label additional.fields Digabung
additionalDetails.accessScopes metadata.description Dipetakan secara langsung
additionalDetails_tokenExpirationTimestamp metadata.event_timestamp Diuraikan sebagai yyyy-MM-ddTHH:mm:ssZ
eventTimestamp metadata.event_timestamp Diuraikan sebagai yyyy-MM-ddTHH:mm:ssZ
has_principal metadata.event_type Dipetakan: true → USER_UNCATEGORIZED
accessTokenName metadata.product_log_id Dipetakan secara langsung
eventId metadata.product_log_id Dipetakan secara langsung
additionalDetails.appClientId principal.user.userid Dipetakan secara langsung
requestUserId principal.user.userid Dipetakan secara langsung
object_id security_result.about.labels Digabung
source_label security_result.about.labels Digabung
object_type security_result.about.resource.attribute.labels Digabung
action security_result.action_details Dipetakan secara langsung
userId target.user.userid Dipetakan secara langsung
T/A metadata.event_type Konstanta: USER_UNCATEGORIZED

Log Perubahan

Melihat Log Perubahan untuk parser ini

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