איסוף יומנים של Atlassian Bitbucket

גרסת מנתח הנתונים: 2.0

נתמך ב:

במאמר הזה מוסבר איך להגדיר את Atlassian Bitbucket כך שיומנים יישלחו ל-Google Security Operations באמצעות ווּבְּהוּקים.

‫Atlassian Bitbucket הוא שירות אירוח של מאגר המקורות של הקוד מבוסס-Git. הוא מספק לצוותי פיתוח שיתוף פעולה בכתיבת קוד, תהליכי עבודה של בקשות משיכה וצינורות CI/CD. ‫Bitbucket תומך בפריסות בענן ובפריסות באירוח עצמי (מרכז נתונים).

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

חשוב לוודא שמתקיימות הדרישות המוקדמות הבאות:

  • מופע של Google SecOps
  • מופע של Atlassian Bitbucket Cloud או Data Center עם גישת אדמין
  • גישה למסוף Google Cloud (ליצירת מפתח API)

יצירת פיד של webhook ב-Google SecOps

יצירת הפיד

  1. עוברים אל SIEM Settings > Feeds (הגדרות SIEM > פידים).
  2. לוחצים על הוספת פיד חדש.
  3. בדף הבא, לוחצים על הגדרת פיד יחיד.
  4. בשדה שם הפיד, מזינים שם לפיד (לדוגמה, Bitbucket Webhook Logs).
  5. בוחרים באפשרות Webhook בתור סוג המקור.
  6. בוחרים באפשרות Atlassian Bitbucket בתור סוג היומן.
  7. לוחצים על הבא.
  8. מציינים ערכים לפרמטרים הבאים של הקלט:
    • תו מפריד לפיצול (אופציונלי): מזינים תו מפריד כדי לפצל אירועים מרובי שורות. ערכים נפוצים:
      • ‫\n – תו שורה חדשה כמפריד (הנפוץ ביותר ב-NDJSON)
      • אם כל בקשה מכילה אירוע יחיד, אפשר להשאיר את השדה ריק
    • מרחב שמות של נכס: מרחב השמות של הנכס
    • תוויות להוספה: התווית שתתווסף לאירועים מהפיד הזה
  9. לוחצים על הבא.
  10. בודקים את ההגדרות של הפיד החדש במסך סיום ולוחצים על שליחה.

יצירה ושמירה של מפתח סודי

אחרי שיוצרים את הפיד, צריך ליצור מפתח סודי לאימות:

  1. בדף הפרטים של הפיד, לוחצים על יצירת מפתח סודי.
  2. בתיבת דו-שיח מוצג המפתח הסודי.
  3. מעתיקים ושומרים את המפתח הסודי באופן מאובטח.

קבלת כתובת ה-URL של נקודת הקצה של הפיד

  1. עוברים לכרטיסייה פרטים של הפיד.
  2. בקטע Endpoint Information, מעתיקים את Feed endpoint URL.

  3. הפורמט של כתובת ה-URL הוא:

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

    או

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

  4. שומרים את כתובת ה-URL הזו כדי לבצע את השלבים הבאים.

  5. לוחצים על סיום.

יצירת מפתח Google Cloud API

מערכת Google SecOps דורשת מפתח API לצורך אימות. יוצרים מפתח API מוגבל במסוף Google Cloud.

יצירת מפתח API

  1. נכנסים אל הדף Credentials במסוף Google Cloud.
  2. בוחרים את הפרויקט (הפרויקט שמשויך למופע Google SecOps).
  3. לוחצים על Create credentials > API key.
  4. מפתח API נוצר ומוצג בתיבת דו-שיח.
  5. לוחצים על Edit API key כדי להגביל את המפתח.

הגבלת מפתח ה-API

  1. בדף ההגדרות API key:
    • שם: מזינים שם תיאורי (לדוגמה, Webhook API Key)
  2. בקטע API restrictions (הגבלות על API):
    1. בוחרים באפשרות הגבלת המקש.
    2. בתפריט הנפתח Select APIs (בחירת ממשקי API), מחפשים את Google SecOps API ובוחרים אותו.
  3. לוחצים על Save.
  4. מעתיקים את הערך של מפתח ה-API מהשדה מפתח ה-API בחלק העליון של הדף.

  5. שומרים את מפתח ה-API בצורה מאובטחת.

הגדרת webhook של Atlassian Bitbucket

הרכבת ה-webhook URL

  • משלבים את כתובת ה-URL של נקודת הקצה של Google SecOps ואת מפתח ה-API:

    <ENDPOINT_URL>?key=<API_KEY>&secret=<SECRET_KEY>

  • דוגמה:

    https://malachiteingestion-pa.googleapis.com/v2/unstructuredlogentries:batchCreate?key=AIzaSyD...&secret=abcd1234...

יצירת webhook ב-Bitbucket Cloud

  1. נכנסים ל-Bitbucket Cloud כאדמינים של סביבת עבודה או מאגר.
  2. עוברים אל המאגר שבו רוצים להגדיר את ה-webhook.
  3. עוברים אל הגדרות המאגר > Webhooks.
  4. לוחצים על Add webhook (הוספת webhook).
  5. מזינים את פרטי ההגדרה הבאים:
    • שם: מזינים שם תיאורי (לדוגמה, SIEM Webhook).
    • כתובת URL: מדביקים את כתובת נקודת הקצה המלאה עם מפתח ה-API והסוד שמופיעים למעלה.
    • סטטוס: בוחרים באפשרות פעיל.
    • טריגרים: בוחרים באפשרות בחירה מתוך רשימה מלאה של טריגרים ובוחרים את האירועים לשליחה:
      • מאגר: Push, ‏ Fork, ‏ Commit Comment Created
      • בקשת מיזוג: נוצרה, עודכנה, אושרה, לא אושרה, מוזגה, נדחתה, נוצרה תגובה
      • בעיה: נוצרה, עודכנה, נוצרה תגובה
  6. לוחצים על Save.

יצירת webhook ב-Bitbucket Data Center

  1. נכנסים אל Bitbucket Data Center כאדמין של פרויקט או מאגר.
  2. מנווטים לפרויקט או למאגר שבו רוצים להגדיר את ה-webhook.
  3. עוברים אל הגדרות הפרויקט > Webhooks (לרמת הפרויקט) או אל הגדרות המאגר > Webhooks (לרמת המאגר).
  4. לוחצים על Create webhook (יצירת webhook).
  5. מזינים את פרטי ההגדרה הבאים:
    • שם: מזינים שם תיאורי (לדוגמה, SIEM Webhook).
    • כתובת URL: מדביקים את כתובת נקודת הקצה המלאה עם מפתח ה-API והסוד שמופיעים למעלה.
    • סטטוס: בוחרים באפשרות פעיל.
    • אירועים: בוחרים את האירועים להעברה:
      • מאגר: שינוי הפניות, יצירת עותק (Fork), הוספת תגובה
      • בקשת משיכה: נפתחה, ענף המקור עודכן, שונה, בודק עודכן, אושרה, לא אושרה, נדרשת עבודה, מוזגה, נדחתה, נמחקה, נוספה תגובה
  6. לוחצים על Save.

אימות המסירה של ה-webhook

  1. אחרי שיוצרים את ה-webhook, מבצעים פעולה במאגר (לדוגמה, שולחים commit).
  2. עוברים אל הגדרות המאגר > Webhooks.
  3. לצד ה-webhook, לוחצים על הצגת הבקשות.
  4. מוודאים שבבקשה מופיע קוד הסטטוס 200, שמציין שהמסירה בוצעה בהצלחה.

מידע נוסף זמין במאמרי העזרה בנושא Bitbucket Cloud webhook או במאמרי העזרה בנושא Bitbucket Data Center webhook.

הפניה לשיטות אימות

פידים של וווב-הוק ב-Google SecOps תומכים בכמה שיטות אימות. בוחרים את השיטה שהספק תומך בה.

אם הספק שלכם תומך בכותרות HTTP בהתאמה אישית, כדאי להשתמש בשיטה הזו כדי לשפר את האבטחה.

  • פורמט הבקשה:

    POST <ENDPOINT_URL> HTTP/1.1
Content-Type: application/json
x-goog-chronicle-auth: <API_KEY>
x-chronicle-auth: <SECRET_KEY>

{
        "event": "data",
        "timestamp": "2025-01-15T10:30:00Z"
}

  • היתרונות:

    • מפתח ה-API והסוד לא מוצגים בכתובת ה-URL
    • מאובטח יותר (הכותרות לא נרשמות ביומני הגישה של שרת האינטרנט)
    • השיטה המועדפת אם הספק תומך בה

שיטה 2: פרמטרים של שאילתה

אם הספק שלכם לא תומך בכותרות מותאמות אישית, צריך לצרף את פרטי הכניסה לכתובת ה-URL.

  • פורמט כתובת ה-URL:

    <ENDPOINT_URL>?key=<API_KEY>&secret=<SECRET_KEY>

  • לדוגמה:

    https://malachiteingestion-pa.googleapis.com/v2/unstructuredlogentries:batchCreate?key=AIzaSyD...&secret=abcd1234...

  • פורמט הבקשה:

    POST <ENDPOINT_URL>?key=<API_KEY>&secret=<SECRET_KEY> HTTP/1.1
Content-Type: application/json

{
        "event": "data",
        "timestamp": "2025-01-15T10:30:00Z"
}

חסרונות:

  • פרטי הכניסה גלויים בכתובת ה-URL
  • יכול להיות שיירשם ביומני הגישה של שרת האינטרנט
  • פחות מאובטח מכותרות

שיטה 3: היברידית (כתובת URL + כותרת)

חלק מההגדרות משתמשות במפתח API בכתובת ה-URL ובמפתח סודי בכותרת.

  • פורמט הבקשה:

    POST <ENDPOINT_URL>?key=<API_KEY> HTTP/1.1
Content-Type: application/json
x-chronicle-auth: <SECRET_KEY>

{
        "event": "data",
        "timestamp": "2025-01-15T10:30:00Z"
}

שמות של כותרות אימות

מערכת Google SecOps מקבלת את שמות הכותרות הבאים לצורך אימות:

למפתח API:

  • x-goog-chronicle-auth (מומלץ)
  • ‫X-Goog-Chronicle-Auth (case-insensitive)

למפתח סודי:

  • x-chronicle-auth (מומלץ)
  • ‫X-Chronicle-Auth (case-insensitive)

מגבלות ושיטות מומלצות לשימוש ב-Webhook

מגבלות על בקשות

הגבלה ערך
גודל בקשה מקסימלי ‫4MB
מספר QPS מקסימלי (שאילתות לשנייה) 15,000
זמן קצוב לתפוגה של בקשה ‫30 שניות
התנהגות של ניסיון חוזר אוטומטי עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff)

טבלת מיפוי UDM

שדה היומן מיפוי UDM לוגיקה
actor.display_name principal.user.user_display_name הערך נלקח מהשדה actor.display_name.
actor.nickname principal.user.userid הערך נלקח מהשדה actor.nickname.
actor.account_id principal.user.product_object_id הערך נלקח מהשדה actor.account_id.
actor.uuid principal.user.product_object_id הערך נלקח מהשדה actor.uuid אם השדה actor.account_id לא קיים.
actor.links.html.href principal.url הערך נלקח מהשדה actor.links.html.href.
repository.full_name target.resource.name הערך נלקח מהשדה repository.full_name.
repository.uuid target.resource.product_object_id הערך נלקח מהשדה repository.uuid.
repository.links.html.href target.url הערך נלקח מהשדה repository.links.html.href.
repository.project.key target.resource.attribute.labels התווסף כצמד מפתח/ערך עם המפתח project_key.
repository.project.name target.resource.attribute.labels הפרמטר מתווסף כצמד מפתח/ערך עם המפתח project_name.
repository.workspace.slug target.resource.attribute.labels נוסף כצמד מפתח/ערך עם המפתח workspace.
push.changes[].new.name target.resource.attribute.labels התווסף כצמד מפתח/ערך עם המפתח branch_name.
push.changes[].new.target.hash target.resource.attribute.labels התווסף כצמד מפתח/ערך עם המפתח commit_hash.
push.changes[].new.target.message target.resource.attribute.labels התווסף כצמד מפתח/ערך עם המפתח commit_message.
push.changes[].new.target.date target.resource.attribute.labels הערך מתווסף כצמד מפתח/ערך עם המפתח commit_date.
push.changes[].new.target.author.raw target.user.email_addresses כתובת האימייל שחולצה משדה המחבר הגולמי.
pullrequest.id target.resource.attribute.labels הערך מתווסף כצמד מפתח/ערך עם המפתח pullrequest_id.
pullrequest.title target.resource.attribute.labels התווסף כצמד מפתח/ערך עם המפתח pullrequest_title.
pullrequest.state target.resource.attribute.labels התווסף כצמד מפתח/ערך עם המפתח pullrequest_state.
pullrequest.author.display_name target.user.user_display_name הערך נלקח מהשדה pullrequest.author.display_name.
pullrequest.source.branch.name target.resource.attribute.labels התווסף כצמד מפתח/ערך עם המפתח source_branch.
pullrequest.destination.branch.name target.resource.attribute.labels התווסף כצמד מפתח/ערך עם המפתח destination_branch.
date metadata.event_timestamp הניתוח מתבצע כחותמת זמן בפורמט ISO8601. משמש כחותמת זמן של האירוע אם הוא מופיע במטען הייעודי (payload) של ה-webhook.
metadata.event_type הערך הראשוני הוא GENERIC_EVENT. הערך שונה ל-USER_RESOURCE_ACCESS,‏ USER_RESOURCE_UPDATE_CONTENT או USER_UNCATEGORIZED בהתאם למפתח האירוע ולנוכחות של השדות principal ו-target.
metadata.product_event_type ההגדרה מתבצעת על סמך ערך הכותרת של ה-webhook‏ X-Event-Key (לדוגמה, repo:push, ‏ pullrequest:created, ‏ pullrequest:updated).
metadata.product_name מגדירים את האפשרות Atlassian Bitbucket.
metadata.vendor_name מגדירים את הערך Atlassian.

שנה רישום

צפייה ביומן השינויים של כלי הניתוח הזה

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