מעבר מ-SIEM API מדור קודם אל Chronicle API

נתמך ב:

המסמך הזה יעזור לכם לנהל אפליקציות שקוראות לאחד מממשקי ה-API מדור קודם של SIEM (Backstory API ו-Ingestion API). במאמר הזה מוסבר איך להגדיר גישה באמצעות תוכנה ולעדכן את כל ההפניות מנקודות הקצה של SIEM API מדור קודם לנקודות הקצה של Chronicle API המודרני.

כדי לקבל סקירה כללית מהירה של תהליך המיגרציה, אפשר לצפות בסרטון המוטמע.

ממשק ה-API של Chronicle כולל כמה שיפורים שנועדו לייעל את תהליך הפיתוח ולהתאים לתקני API‏ Google Cloud לשיפור המהימנות, האבטחה והביצועים, ולשילוב טוב יותר עם Cloud Audit Logs,‏ Cloud Monitoring,‏ Cloud Identity ו-IAM (המערכת לניהול הזהויות והרשאות הגישה). הוא גם פותר הרבה מהמגבלות והמורכבויות של ממשקי ה-API מדור קודם.

מה משתנה

כל הבקשות שמוגשות באופן פרוגרמטיבי לנקודות הקצה של Backstory API ו-Ingestion API מדור קודם חייבות לעבור ל-Chronicle API המודרני. אם הארגון שלכם משתמש בשילובים מותאמים אישית, בסקריפטים לאוטומציה או בכלים של צד שלישי ששולחים קריאות לנקודות הקצה מדור קודם, אתם צריכים לעדכן את עומסי העבודה האלה כדי שישתמשו בנקודות קצה מודרניות ובתהליכי אימות לפני 20 ביולי 2027. בנוסף, אם הארגון שלכם משתמש ב-Google Security Operations SOAR, אתם צריכים לעדכן את השילובים והמחברים של SOAR (למשל השילוב של Google Chronicle) כדי להשתמש ב-Chronicle API. פרטים נוספים מופיעים במאמר בנושא העברת שילובים של SOAR.

מה לא משתנה

פעולות שמבוצעות ישירות בממשק המשתמש של Google Security Operations כבר מפעילות את Chronicle API המודרני. אם הארגון שלכם מקיים אינטראקציה עם Google SecOps רק דרך ממשק המשתמש, או אם השילובים שלכם כבר קוראים לנקודות הקצה של Chronicle API, אתם לא צריכים לבצע שום פעולה.

שינויים ושיפורים מרכזיים

בטבלה הבאה מפורטים ההבדלים העיקריים בין SIEM API מהדור הקודם לבין Chronicle API:

תחום התכונה Legacy SIEM API Chronicle API פרטים
ניהול פרטי כניסה תהליך ידני שכולל נציגי Google ניהול עצמי של חשבונות שירות, פרטי כניסה והרשאות IAM ניהול עצמי של אישורים ושל IAM מפשט את תהליך ההצטרפות ומבטל את התלות בבקשות תמיכה ידניות.
תקני תאימות תמיכה מוגבלת תמיכה מובנית באמצעי בקרה של מיקום לאחסון נתונים, VPC Service Controls,‏ Access Transparency,‏ CMEK ו-FedRAMP אמצעי בקרה מודרניים ומובנים בתשתית עומדים בתקנים של עמידה בדרישות ובתקנות בתחום.
רישום ביומן וביקורת הזרמות קודמות של נתוני ביקורת יומני ביקורת של Cloud שמשולבים בפרויקט Google Cloud אינטגרציה ישירה מספקת נתיבי ביקורת וניטור מרכזיים.
אימות אסימון API ופרטי כניסה לחשבון שירות ‫OAuth 2.0 עם תמיכה בשיטות אימות מודרניות, כולל Workload Identity וחשבונות שירות, כפי שמתואר במאמר אימות עבור Google Cloud ממשקי API ושירותים שיטות האימות המודרניות האלה מספקות אבטחה משופרת ומאחדות את תהליך אימות האישורים.
מודלים של נתונים ועיצוב API מבנים שטוחים וקנייניים עיצוב מבוסס-משאבים, ארכיטקטורת REST ושמות סטנדרטיים לפי AIPs העיצוב המודרני הזה משפר את עקביות הנתונים, הופך את ה-API לאינטואיטיבי יותר ומפשט את הטיפול באובייקטים.
מתן שמות לנקודות קצה לא עקבית מבוסס REST וסטנדרטי שיטה עקבית למתן שמות הופכת את ה-API לאינטואיטיבי יותר וקל יותר לשילוב.
מערכת אקולוגית מוגבלת מאוד שילוב עם MCP,‏ Terraform, ספריות לקוח וערכות SDK תאימות רחבה לכלים מודרניים בענן ולמסגרות אוטומציה.
הרשאת שותף טוקן שותף או מפתח API שמשמשים ישירות בקודים של לקוחות העברת הרשאות IAM בין פרויקטים למשאבי דיירים; methods של TenantService בהיקף שותף השיטות של TenantService פועלות בפרויקט השותף. כל ממשקי ה-API האחרים של הדיירים דורשים העברת הרשאות IAM בין פרויקטים, שניתנת על ידי הדייר בפרויקט הדייר.

הרשאת שותף

בתהליכי עבודה של שותפים עם מספר דיירים, ההרשאה ב-Chronicle API תלויה בבעלות על המשאב. הפרויקט שמארח משאב קובע אילו פרטי כניסה והרשאות IAM נדרשים לשותף. הגבלת פעולות הדייר לפרטי כניסה שהוקצו לדייר תואמת לעקרון האבטחה הבסיסי שלפיו שותפים לא יכולים לגשת לנתוני הדייר, לאחזר אותם או לשנות אותם בלי הרשאה מפורשת שניתנה על ידי הדייר. הטבלה הבאה משווה בין הרשאות שותפים ב-API מדור קודם של Backstory וב-Chronicle API:

API Methods היקף המשאב הרשאה
Legacy Backstory API /v1/partner/customer/* נקודות קצה כל קודי הלקוחות של השותף השותפים שולחים קריאות לנקודות הקצה האלה ישירות באמצעות אסימוני השותף או מפתחות ה-API שלהם.
‫Chronicle API: TenantService CreateTenant, ListTenants וגם UpdateTenant המופע של השותף: projects/{partner_project}/locations/{location}/instances/{partner_instance}/tenants/* השותפים קוראים לשיטות האלה ישירות באמצעות חשבונות השירות או פרטי הכניסה שלהם שיש להם הרשאות chronicle.googleapis.com/tenants.* בפרויקט השותף.
‫Chronicle API: שירותים אחרים, כמו InstanceService ו-ForwarderService ‫GetInstance, ‏UpdateInstance, ‏GenerateForwarderFiles ושיטות אחרות בהיקף הדייר המופע של הדייר: projects/{tenant_project}/locations/{location}/instances/{tenant_instance}/... אי אפשר לגשת לנתוני הדייר או לשנות אותם רק באמצעות פרטי הכניסה של השותף. האדמין בדייר צריך להעניק תפקידי IAM, כמו roles/chronicle.admin,‏ roles/chronicle.viewer או תפקיד בהתאמה אישית, לחשבון השירות של השותף או לחשבון המשתמש של איגוד זהויות של עומסי עבודה בפרויקט Google Cloud של הדייר.

לוח הזמנים להוצאה משימוש

הגרסה הקודמת של SIEM API תושבת ב-20 ביולי 2027. כדי למנוע שיבושים בשירות, מומלץ להשלים את המיגרציה לפני התאריך הזה:

  • החל מ-26 באוקטובר 2026, לא תוכלו יותר להפעיל קריאות לממשקי API מדור קודם (Backstory API ו-Ingestion API) ממופעים חדשים.
  • עד 20 ביולי 2027, תצטרכו להעביר את כל המקרים הקיימים אל Chronicle API, כי ממשקי ה-API הקודמים לא יהיו זמינים יותר.

לפני שמתחילים

לפני שמעבירים ל-Chronicle API, צריך לוודא שביצעתם את הפעולות הבאות:

  • פריסה בתשתית SIEM מודרנית: חשוב לוודא שהמופע נפרס בפרויקט שלכם או של שותף ה-MSSP שלכם Google Cloud באמצעות תשתית SIEM מודרנית. הוראות מפורטות זמינות במאמר סקירה כללית על העברת נתונים של SIEM.
  • מפעילים את Chronicle API: במסוף Google Cloud , עוברים לפרויקט שמארח את המופע ומפעילים את Chronicle API ‏ (chronicle.googleapis.com). פרטים נוספים זמינים במאמר בנושא הפעלת API ב Google Cloud פרויקט.
  • זיהוי שילובים של SOAR: אם הסביבה שלכם מחברת את Google SecOps SOAR ל-Google Security Operations SIEM, צריך לאמת את המחברים הקיימים. פרטים נוספים מופיעים במאמר בנושא העברת שילובים של SOAR.

העברת שילובים של SOAR

אם הארגון שלכם מקשר את Google SecOps SOAR ל-Google SecOps SIEM, אתם צריכים להעביר את השילובים והמחברים של SOAR (כמו השילוב של Google Chronicle) לשימוש ב-Chronicle API.

הוראות מפורטות לשדרוג השילובים ומחברי הנתונים של Google Chronicle לשימוש ב-Chronicle API, כולל איתור הבסיס של Chronicle API בסביבה שלכם והגדרת פרטי כניסה לאימות, זמינות במאמר העברה מ-Backstory API ל-Chronicle API.

מעבר ל-Chronicle API

כדי להעביר את הסקריפטים והשילובים המותאמים אישית מממשקי ה-API מדור קודם אל Chronicle API, צריך לבצע את השלבים הבאים:

  1. בדיקת השימוש ב-API: זיהוי של כל הסקריפטים והשילובים בהתאמה אישית בסביבה שלכם שמפעילים נקודות קצה מדור קודם.
  2. הגדרת אימות והרשאה: מגדירים את הסביבה לאימות ולאישור של בקשות ל-Chronicle API.
  3. מיפוי נקודות קצה ועדכון כתובות URL: מחליפים נקודות קצה מדור קודם בנקודות קצה אזוריות מודרניות.
  4. עדכון הלוגיקה של ה-API: צריך לשנות את מטען הייעודי (payload) של הבקשות ואת הטיפול בתגובות כך שיתאימו למודלים של הנתונים ב-API המודרני.
  5. בדיקת השילוב: לפני הפריסה בסביבת הייצור, כדאי לאמת את השינויים בסביבת בדיקה.

ביקורת על השימוש ב-API

בודקים את הסביבה כדי לזהות סקריפטים או שילובים מותאמים אישית שמפעילים את backstory.googleapis.com או malachiteingestion-pa.googleapis.com. כדי לזהות את השילובים האלה, צריך לבדוק את בסיס הקוד, את סקריפטים האוטומציה ואת כלי הצד השלישי. אם הארגון שלכם משתמש גם ב-Google SecOps SOAR, כדאי לעיין במאמר בנושא העברת שילובים של SOAR.

הגדרת אימות והרשאה

מגדירים את הסביבה לאימות ולהרשאה של בקשות ל-Chronicle API:

  1. בחירת שיטת אימות: בוחרים באחת מהשיטות שמופיעות ברשימה כדי לקבוע איך עומסי העבודה יאומתו ל-Chronicle API. מומלץ להשתמש באיחוד שירותי אימות הזהות של עומסי עבודה כדי לשפר את האבטחה, כי כך לא צריך לנהל ולאחסן מפתחות של חשבונות שירות לטווח ארוך. לתרחישי אימות מתקדמים (כמו התחזות לחשבון שירות), ראו אימות ל-Chronicle API.
  2. הענקת הרשאות IAM: מעניקים את הרשאות ה-IAM הנדרשות לזהות (חשבון השירות או חשבון המשתמש החיצוני) שמשמשת לאימות. במאמר מיפוי של נקודות קצה ל-API של SIEM מפורטות הרשאות ה-IAM הספציפיות שנדרשות לנקודות הקצה המודרניות שמחליפות את הקריאות הקודמות.
    • תפקיד בהתאמה אישית (מומלץ): יוצרים תפקיד IAM בהתאמה אישית עם ההרשאות הנדרשות, ומקצים את התפקיד בהתאמה אישית לחשבון השירות או לזהות החיצונית.
    • תפקיד מוגדר מראש: מקצים תפקיד מוגדר מראש של Google SecOps לחשבון השירות או לחשבון הראשי של הזהות החיצונית. הפעולה הזו כנראה תעניק יותר גישה ממה שנדרש לאוטומציה ספציפית.
    • הענקת הרשאות לשותף עם מספר דיירים: אם אתם ספק MSSP או שותף שמנהל משאבי דיירים מחוץ ל-TenantService (למשל GetInstance,‏ UpdateInstance או GenerateForwarderFiles), האדמין של הדייר צריך להעניק במפורש לחשבון השירות או לחשבון המשתמש של איחוד שירותי אימות הזהות של עומסי עבודה את תפקידי ה-IAM הנדרשים בפרויקט Google Cloud של הדייר.
  3. מגדירים את משתנה הסביבה של פרטי הכניסה: מגדירים את סביבת זמן הריצה כך שתשתמש בפרטי הכניסה באמצעות Application Default Credentials ‏ (ADC) על ידי הגדרת משתנה הסביבה GOOGLE_APPLICATION_CREDENTIALS. המשתנה הזה צריך להצביע על קובץ ה-JSON של מפתח חשבון השירות שהורדתם או על קובץ התצורה של פרטי הכניסה של איחוד שירותי אימות הזהות של עומסי עבודה. ספריות הלקוח שלGoogle Cloud מזהות את המשתנה הזה באופן אוטומטי כדי לאמת בקשות:

    export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/credentials.json"
    
  4. עדכון היקף ההרשאות ל-OAuth: אם הסקריפטים של השילוב הקודם ביקשו במפורש היקף הרשאות ל-OAuth ליצירת טוקנים, צריך לעדכן את מחרוזת היקף ההרשאות. היקף הגישה מדור קודם לא מעניק גישה לממשק ה-API המודרני:

    • היקף השימוש ב-Backstory מדור קודם: https://www.googleapis.com/auth/chronicle-backstory
    • היקף ההרשאות של Chronicle: https://www.googleapis.com/auth/chronicle (או היקף ההרשאות הרחב יותר https://www.googleapis.com/auth/cloud-platform).

מיפוי נקודות קצה ועדכון כתובות URL

כדאי להכיר את ממשק ה-API של Chronicle, למפות את הקריאות הקודמות ולעדכן את נקודות הקצה של השירות באפליקציה.

בדיקת מאמרי העזרה

מומלץ לעיין במאמרי העזרה המקיפים בנושא Chronicle API.

מיפוי נקודות קצה ל-Chronicle API

מזהים את נקודות הקצה המודרניות התואמות לכל אחת מהקריאות ל-API מדור קודם שהאפליקציה מבצעת. באופן דומה, צריך למפות את מודלי הנתונים הקיימים למבנים המודרניים, תוך התחשבות בשינויים בסכימה או בשדות נוספים. פרטים על כל נקודות הקצה של SIEM זמינים במאמר מיפוי של נקודות קצה ל-API של SIEM. אם תהליך העבודה שלכם כולל גם אינטראקציות עם נקודות קצה של SOAR, תוכלו לעיין בטבלת מיפוי של נקודות קצה ל-API של SOAR.

עדכון נקודת הקצה של השירות

מעדכנים את כתובת ה-URL הבסיסית של קריאות ה-API כך שתצביע על נקודת הקצה הנכונה של השירות האזורי. ‫Chronicle API הוא שירות אזורי, ולכן צריך לבצע קריאה לנקודת הקצה של השירות האזורי שתואמת למיקום של מופע Google SecOps.

לכל נקודות הקצה המודרניות יש קידומת עקבית, כך שכתובת נקודת הקצה הסופית צפויה. בדוגמה הבאה מוצג המבנה של כתובת ה-URL של נקודת הקצה המודרנית:

[api_version]/projects/[project_id]/locations/[location]/instances/[instance_id]/...

המבנה הזה יוצר את הכתובת הסופית לנקודת הקצה באופן הבא:

https://[service_endpoint]/[api_version]/projects/[project_id]/locations/[location]/instances/[instance_id]/...

כאשר:

  • service_endpoint: כתובת שירות אזורית.
  • ‫api_version: גרסת ה-API שאליה מתבצעת השאילתה. יכול להיות v1alpha, v1beta או v1.
  • ‫project_id: מזהה הפרויקט (אותו פרויקט שהגדרתם להרשאות IAM).
  • ‫location: המיקום של הפרויקט (אזור); זהה לנקודות הקצה האזוריות.
  • ‫instance_id: מספר הלקוח שלכם ב-Google SecOps SIEM.

כתובות אזוריות:

  • africa-south1: ‏ https://africa-south1-chronicle.googleapis.com או https://chronicle.africa-south1.rep.googleapis.com
  • ‫asia-northeast1: ‏ https://asia-northeast1-chronicle.googleapis.com או https://chronicle.asia-northeast1.rep.googleapis.com
  • ‫asia-south1: ‏ https://asia-south1-chronicle.googleapis.com או https://chronicle.asia-south1.rep.googleapis.com
  • ‫asia-southeast1: ‏ https://asia-southeast1-chronicle.googleapis.com או https://chronicle.asia-southeast1.rep.googleapis.com
  • ‫asia-southeast2: ‏ https://asia-southeast2-chronicle.googleapis.com או https://chronicle.asia-southeast2.rep.googleapis.com
  • ‫australia-southeast1: ‏ https://australia-southeast1-chronicle.googleapis.com או https://chronicle.australia-southeast1.rep.googleapis.com
  • ‫europe-west12: ‏ https://europe-west12-chronicle.googleapis.com או https://chronicle.europe-west12.rep.googleapis.com
  • ‫europe-west2: ‏ https://europe-west2-chronicle.googleapis.com או https://chronicle.europe-west2.rep.googleapis.com
  • ‫europe-west3: ‏ https://europe-west3-chronicle.googleapis.com או https://chronicle.europe-west3.rep.googleapis.com
  • ‫europe-west6: ‏ https://europe-west6-chronicle.googleapis.com או https://chronicle.europe-west6.rep.googleapis.com
  • ‫europe-west9: ‏ https://europe-west9-chronicle.googleapis.com או https://chronicle.europe-west9.rep.googleapis.com
  • ‫me-central1: ‏ https://me-central1-chronicle.googleapis.com או https://chronicle.me-central1.rep.googleapis.com
  • me-central2: https://me-central2-chronicle.googleapis.com או https://chronicle.me-central2.rep.googleapis.com
  • me-west1: ‏ https://me-west1-chronicle.googleapis.com או https://chronicle.me-west1.rep.googleapis.com
  • ‫northamerica-northeast2: ‏ https://northamerica-northeast2-chronicle.googleapis.com או https://chronicle.northamerica-northeast2.rep.googleapis.com
  • ‫southamerica-east1: ‏ https://southamerica-east1-chronicle.googleapis.com או https://chronicle.southamerica-east1.rep.googleapis.com
  • ארצות הברית (us): https://us-chronicle.googleapis.com או https://chronicle.us.rep.googleapis.com
  • אירופה (eu): https://eu-chronicle.googleapis.com או https://chronicle.eu.rep.googleapis.com

רשימה מקיפה של כל נקודות הקצה הנתמכות מופיעה בהפניה הרשמית במסמכי התיעוד של נקודת הקצה של שירות Chronicle API.

לדוגמה, כדי להציג רשימה של כל כללי הזיהוי של מופע במיקום us, שולחים את הבקשה הבאה:

GET
  https://us-chronicle.googleapis.com/v1alpha/projects/my-project-name-or-id/locations/us/instances/408bfb7b-5746-4a50-885a-50a323023529/rules

באופן דומה, כדי לשלוח שאילתה למשאבי SOAR כמו Cases באמצעות כינוי של נקודת קצה אזורית (rep), שולחים את הבקשה הבאה:

GET
  https://chronicle.us.rep.googleapis.com/v1alpha/projects/my-project-name-or-id/locations/us/instances/408bfb7b-5746-4a50-885a-50a323023529/cases

עדכון הלוגיקה של ה-API

כדי לזהות וליישם שינויים בשמות השדות ובמבני הנתונים באפליקציה, אפשר לעיין בהפניה ל-Chronicle API REST. יכול להיות שחלק מנקודות הקצה מדור קודם יישארו דומות, אבל תצטרכו לעדכן את השילובים כך שיתאימו למודלים העדכניים של הנתונים ולמבנים של נקודות הקצה.

שימוש Google Cloud בספריות לקוח

לפשט את השילוב כדי לטפל באופן אוטומטי באימות, ברענון האסימון ובפרטי התעבורה. מומלץ להשתמש ב Google Cloud ספריות הלקוח הרשמיות לשם כך. יש תמיכה ב-Chronicle API בשמונה שפות תכנות, כולל Python,‏ Go,‏ Java,‏ Node.js ו-C#. פרטים על התקנה ושימוש זמינים במאמר ספריות לקוח ו-SDK.

בדיקת השילוב

בודקים את האפליקציה המעודכנת בסביבת Staging לפני הפריסה בסביבת הייצור:

  1. יצירת תוכנית בדיקות: מגדירים תרחישי בדיקה שכוללים את כל הפונקציות שהועברו.
  2. ביצוע בדיקות: מריצים בדיקות אוטומטיות וידניות כדי לוודא שהנתונים מדויקים ותקפים.
  3. מעקב אחרי הביצועים: הערכת הביצועים של האפליקציה באמצעות ה-API המודרני.

פתרון בעיות

בקטע הזה מוסבר איך לפתור שגיאות נפוצות שאולי נתקלתם בהן במהלך ההעברה.

‫HTTP 403 Forbidden או PERMISSION_DENIED

אם הקריאות ל-API מחזירות שגיאה HTTP 403 Forbidden או PERMISSION_DENIED, צריך לבדוק את הדברים הבאים:

  • שיטת אימות וחשבון משתמש בשירות: חשוב לוודא שאתם משתמשים בפרטי הכניסה הנכונים.
    • אם משתמשים באיחוד שירותי אימות הזהות של עומסי עבודה, צריך לוודא שהחשבון הראשי של הזהות החיצונית תואם לחשבון הראשי שמשויך לתפקידי ה-IAM בפרויקט.
    • אם משתמשים בחשבון שירות, צריך לוודא שמשתמשים בחשבון השירות הנכון ושהוא לא מושבת. אל תשתמשו בחשבונות שירות מדור קודם (שבדרך כלל מכילים bk או malachite-cx בכתובת האימייל שלהם) בנקודות קצה ל-API מודרניות של Chronicle.
  • תפקידי IAM: מוודאים שחשבון השירות או נציג הזהות החיצונית קיבלו את תפקידי ה-IAM הנדרשים המוגדרים מראש או המותאמים אישית (כמו Chronicle API Viewer או Chronicle API Editor) ב Google Cloud פרויקט. למידע על הרשאות מפורטות לנקודות קצה, אפשר לעיין במאמר מיפוי של נקודות קצה ל-API של SIEM.

‫HTTP 401 Unauthorized או UNAUTHENTICATED

אם הקריאות ל-API נכשלות עם השגיאות HTTP 401 Unauthorized או UNAUTHENTICATED, צריך לבדוק את הדברים הבאים:

  • היקפי הרשאות של OAuth: מוודאים שהסקריפטים המותאמים אישית מבקשים את היקף ההרשאות המודרני: https://www.googleapis.com/auth/chronicle (או את היקף ההרשאות הרחב יותר https://www.googleapis.com/auth/cloud-platform). ההיקף מדור קודם (https://www.googleapis.com/auth/chronicle-backstory) לא מעניק גישה ל-Chronicle API המודרני.
  • משתנה סביבה: מוודאים שמשתנה הסביבה GOOGLE_APPLICATION_CREDENTIALS מוגדר ומצביע על קובץ מפתח ה-JSON הנכון או על קובץ התצורה של איחוד שירותי אימות הזהות של עומסי עבודה בסביבת זמן הריצה.

שגיאת HTTP 404 או אי התאמות אזוריות

אם הקריאות ל-API מחזירות HTTP 404 Not Found או שהחיבור נכשל, צריך לבדוק את נקודות הקצה האזוריות:

  • נקודת קצה אזורית: Chronicle API הוא שירות אזורי. מוודאים שקוראים לנקודת הקצה שתואמת לאזור של מכונת Google SecOps (לדוגמה, https://europe-west3-chronicle.googleapis.com למכונה בפרנקפורט). שליחת בקשות לאזור אחר תגרום לשגיאות. רשימה מלאה של כתובות אזוריות מופיעה במאמר עדכון נקודת הקצה של השירות או במאמר הרשמי Service endpoint reference.

המאמרים הבאים

הבעיה עדיין לא נפתרה? קבלת תשובות מחברי הקהילה וממומחי Google SecOps.