‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

איסוף יומנים של GitGuardian Enterprise

גרסת המנתח: 1.0

נתמך ב:

Google SecOps SIEM

במסמך הזה מוסבר איך להגדיר את GitGuardian Enterprise כדי לשלוח יומנים ל-Google Security Operations באמצעות תגובות לפעילות אינטרנט.

‫GitGuardian Enterprise היא פלטפורמה לזיהוי ולתיקון של סודות, שעוקבת אחרי מאגרי קוד מקור, צינורות עיבוד נתונים של CI/CD ותחנות עבודה של מפתחים כדי לאתר פרטי כניסה ומידע אישי רגיש שנחשפו. הוא מספק התראות בזמן אמת כשמתגלים סודות, ועוזר לצוותי האבטחה לנהל תהליכי עבודה לתיקון אירועים.

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

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

מופע של Google SecOps
סביבת עבודה של GitGuardian Enterprise עם רמת גישה של מנהל
גישה למסוף Google Cloud (ליצירת מפתח API)
מינוי GitGuardian Business או מינוי מורחב יותר (לתמיכה ב-webhook בהתאמה אישית)

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

יצירת הפיד

עוברים אל SIEM Settings > Feeds.
לוחצים על הוספת פיד חדש.
בדף הבא, לוחצים על הגדרת פיד יחיד.
בשדה שם הפיד, מזינים שם לפיד (לדוגמה, GitGuardian Enterprise Incidents).
בוחרים באפשרות Webhook בתור סוג המקור.
בוחרים באפשרות GitGuardian Enterprise בתור Log type.
לוחצים על הבא.
מציינים ערכים לפרמטרים הבאים של הקלט:
- תו מפריד לפיצול (אופציונלי): משאירים ריק (כל בקשת webhook מכילה אירוע יחיד)
- מרחב השמות של הנכס: מרחב השמות של הנכס
- תוויות הטמעה: התווית שתתווסף לאירועים מהפיד הזה
לוחצים על הבא.
בודקים את הגדרות הפיד החדש במסך סיום ולוחצים על שליחה.

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

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

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

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

איך מקבלים את כתובת ה-URL של נקודת הקצה של הפיד

עוברים לכרטיסייה פרטים של הפיד.
בקטע Endpoint Information, מעתיקים את Feed endpoint URL.
הפורמט של כתובת ה-URL הוא:
```
https://{region}-chronicle.googleapis.com/v1/{parent}/logs:import
```
כאשר {region} הוא האזור של מופע Google SecOps (לדוגמה, us,‏ europe או asia-southeast1), ו-{parent} הוא נתיב המשאב בפורמט projects/<PROJECT_ID>/locations/<LOCATION>/instances/<INSTANCE_ID>/logTypes/<LOG_TYPE>.
שומרים את כתובת ה-URL הזו לשלבים הבאים.
לוחצים על סיום.

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

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

יצירת מפתח API

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

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

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

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

הגדרת webhook ב-GitGuardian Enterprise

יצירת כתובת ה-URL של ה-webhook

משלבים את כתובת ה-URL של נקודת הקצה (endpoint) של Google SecOps ואת מפתח ה-API:
```
<ENDPOINT_URL>?key=<API_KEY>
```
לדוגמה:
```
https://{region}-chronicle.googleapis.com/v1/{parent}/logs:import?key=AIzaSyD...
```

יצירת תגובה לפעולה מאתר אחר (webhook) בהתאמה אישית ב-GitGuardian

במרחב עבודה אישי:

נכנסים אל מרכז הבקרה של GitGuardian.
עוברים אל הגדרות > סביבת עבודה > שילובים > יעדים > תגובה לפעולה מאתר אחר (webhook) בהתאמה אישית.
לוחצים על הוספת תגובה לפעולה מאתר אחר (webhook) בהתאמה אישית או על יצירת תגובה חדשה לפעולה מאתר אחר (webhook) בהתאמה אישית.
ממלאים את פרטי ההגדרה הבאים:
- שם: מזינים שם תיאורי (לדוגמה, Google SecOps SIEM Integration).
- כתובת URL: מדביקים את כתובת ה-URL המלאה של נקודת הקצה עם מפתח ה-API מלמעלה.
- אסימון חתימה: מדביקים את המפתח הסודי מיצירת הפיד של Google SecOps.
- כותרת מותאמת אישית (אופציונלי): משאירים את השדה ריק, אלא אם צריך לציין תגי סביבה או שירות.
בקטע Event Subscription, בוחרים את האירועים שרוצים לשלוח ל-Google SecOps:
- אירועים:
  - ‫☑ זוהה אירוע חדש
  - ‫☑ זוהה מופע חדש
  - ‫☑ האירוע טופל
  - ‫☑ Incident ignored (המערכת התעלמה מהאירוע)
  - ‫☑ האירוע נפתח מחדש
  - ‫☑ Incident regression
  - ‫☑ האירוע הוקצה
  - ‫☑ האירוע הוקצה מחדש
  - ‫☑ האירוע לא הוקצה
  - ‫☑ Incident Severity changed
  - ‫☑ Incident Validity changed
  - ‫☑ Incident access granted
  - ‫☑ הגישה לאירוע בוטלה
  - ‫☑ Incident shared publicly
  - ☑ האירוע לא משותף באופן ציבורי
  - ‫☑ המשוב נשלח
  - ‫☑ תגובה חדשה לאירוע
לוחצים על יצירה או על שמירה.
‫GitGuardian שולחת הודעת בדיקה כדי לוודא שה-webhook פועל.

בסביבת עבודה עסקית:

נכנסים אל מרכז הבקרה של GitGuardian.
מגדירים את ההיקף של ה-webhook:
- לכל האירועים במרחב: עוברים אל הצוות לטיפול בכל האירועים.
- אירועים של צוות ספציפי: עוברים לצוות הרצוי.
עוברים אל הגדרות > Workspace > שילובים > יעדים > Custom webhook (ווּבקְהוּק מותאם אישית).
- אפשרות נוספת: בדף הצוות, עוברים אל שילובים > Custom webhook (ווּבק מותאם אישית).
לוחצים על הוספת webhook מותאם אישית או על יצירת webhook מותאם אישית חדש.
ממלאים את פרטי ההגדרה הבאים:
- שם: מזינים שם תיאורי (לדוגמה, Google SecOps SIEM Integration).
- כתובת URL: מדביקים את כתובת ה-URL המלאה של נקודת הקצה עם מפתח ה-API מלמעלה.
- אסימון חתימה: מדביקים את המפתח הסודי מיצירת הפיד של Google SecOps.
- כותרת מותאמת אישית (אופציונלי): משאירים את השדה ריק, אלא אם צריך לציין תגי סביבה או שירות.
בקטע Event Subscription, בוחרים את האירועים שרוצים לשלוח ל-Google SecOps:
- אירועים:
  - ‫☑ זוהה אירוע חדש
  - ‫☑ זוהה מופע חדש
  - ‫☑ האירוע טופל
  - ‫☑ Incident ignored (המערכת התעלמה מהאירוע)
  - ‫☑ האירוע נפתח מחדש
  - ‫☑ Incident regression
  - ‫☑ האירוע הוקצה
  - ‫☑ האירוע הוקצה מחדש
  - ‫☑ האירוע לא הוקצה
  - ‫☑ Incident Severity changed
  - ‫☑ Incident Validity changed
  - ‫☑ Incident access granted
  - ‫☑ הגישה לאירוע בוטלה
  - ‫☑ Incident shared publicly
  - ☑ האירוע לא משותף באופן ציבורי
  - ‫☑ המשוב נשלח
  - ‫☑ תגובה חדשה לאירוע
לוחצים על יצירה או על שמירה.
‫GitGuardian שולחת הודעת בדיקה כדי לוודא שה-webhook פועל.

אימות הצגת מודעות באמצעות תגובה לפעולה מאתר אחר (webhook)

במרכז הבקרה של GitGuardian, עוברים להגדרת ה-webhook המותאם אישית.
לוחצים על שליחת הודעת בדיקה או על בדיקת webhook.
‫GitGuardian שולח מטען ייעודי לדוגמה אל Google SecOps.
במסוף Google SecOps, עוברים אל SIEM Settings > Feeds.
מאתרים את הפיד של GitGuardian ומוודאים שאירוע הבדיקה התקבל.
מוודאים שבשדה Feed Status (סטטוס הפיד) מוצג הערך Active (פעיל) עם חותמת זמן של הטמעת נתונים מהזמן האחרון.

הערה: הודעת הבדיקה מכילה נתונים לדוגמה עם ערכים סודיים מצונזרים. ווּבּהוּקים של סביבת הייצור יכילו נתונים בפועל של אירועים.

מידע על שיטות אימות

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

שיטה 1: פרמטרים של שאילתה (מומלץ ל-GitGuardian)

התכונה "תגובות לפעילות לפעולה מאתר אחר (webhook) בהתאמה אישית" של GitGuardian פועלת הכי טוב עם פרטי כניסה שמצורפים לכתובת ה-URL.

פורמט כתובת ה-URL:
```
<ENDPOINT_URL>?key=<API_KEY>
```
לדוגמה:
```
https://{region}-chronicle.googleapis.com/v1/{parent}/logs:import?key=AIzaSyD...
```
הגדרת ה-webhook של GitGuardian:
- ‫URL: כתובת URL מלאה של נקודת הקצה עם פרמטר של מפתח API
- אסימון חתימה: מפתח סודי של Google SecOps (לאימות HMAC)

פורמט הבקשה:

POST <ENDPOINT_URL>?key=<API_KEY> HTTP/1.1
Content-Type: application/json
Timestamp: 1234567890
Gitguardian-Signature: sha256=abc123...

{
    "source": "GitGuardian",
    "timestamp": "2025-01-15T10:30:00Z",
    "action": "incident_triggered",
    "incident": {...}
}

שיטה 2: כותרות מותאמות אישית (חלופה)

אם אתם מעדיפים לא לכלול את פרטי הכניסה בכתובת ה-URL, אתם יכולים להשתמש בכותרות בהתאמה אישית.

פורמט הבקשה:

POST <ENDPOINT_URL> HTTP/1.1
Content-Type: application/json
x-goog-chronicle-auth: <API_KEY>
Timestamp: 1234567890
Gitguardian-Signature: sha256=abc123...

{
    "source": "GitGuardian",
    "timestamp": "2025-01-15T10:30:00Z",
    "action": "incident_triggered",
    "incident": {...}
}

אימות חתימה של webhook ב-GitGuardian

‫GitGuardian חותמת על כל מטען הנתונים של ה-webhook באמצעות HMAC-SHA256 כדי לוודא שהוא אותנטי ולמנוע שינויים לא מורשים.

כותרות חתימה

‫GitGuardian כולל את הכותרות הבאות בבקשות של ה-webhook:

‫Gitguardian-Signature: חתימת HMAC-SHA256 בפורמט sha256=<hex_digest>
Timestamp: חותמת זמן של מערכת Unix שבה הבקשה נשלחה
‫X-GitGuardian-Signature: כותרת שהוצאה משימוש (עדיין נתמכת לצורך תאימות לדורות קודמים)

אלגוריתם חתימה

החתימה מחושבת באופן הבא:
```
HMAC-SHA256(key=timestamp + signature_token, message=payload)
```
כאשר:
- ‫timestamp: ערך מהכותרת Timestamp
- ‫signature_token: המפתח הסודי שהוגדר בהגדרות של GitGuardian webhook
- ‫payload: גוף בקשת JSON גולמי כמחרוזת UTF-8

דוגמה לאימות (Python)

import hmac
import hashlib

def verify_signature(signature: str, timestamp: str, signature_token: str, payload: str) -> bool:
    if not signature.startswith("sha256="):
        return False
    
    signature = signature.split("sha256=")[-1]
    
    hmac_digest = hmac.new(
        key=bytes(timestamp + signature_token, "utf-8"),
        msg=bytes(payload, "utf-8"),
        digestmod=hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(signature, hmac_digest)

הגנה מפני מתקפת Replay

הכותרת Timestamp מונעת התקפות של הפעלה חוזרת. אם חותמת הזמן הנוכחית שונה מחותמת הזמן של ה-webhook ביותר מכמה שניות (מומלץ: 300 שניות), דוחים את הבקשה.

הערה: מערכת Google SecOps מטפלת באופן אוטומטי באימות של ה-webhook. לא צריך להטמיע אימות חתימה כשמשתמשים בפידים של Google SecOps לפעולות webhook.

סוגי אירועים ומבנה המטען הייעודי (payload)

‫GitGuardian שולח סוגי אירועים שונים בהתאם לשינויים במחזור החיים של האירוע.

אירועים של תקריות

סוג האירוע	ערך הפעולה	תיאור
זוהה אירוע חדש	`incident_triggered`	זוהה אירוע חדש שקשור לסודות
זוהה מופע חדש	`new_occurrence`	נמצא מופע חדש של אירוע קיים
האירוע טופל	`incident_resolved`	האירוע סומן כ"טופל"
התעלמות מהאירוע	`incident_ignored`	האירוע סומן כאירוע שהמערכת מתעלמת ממנו
האירוע נפתח מחדש	`incident_reopened`	אירוע שנסגר בעבר נפתח מחדש
רגרסיה של אירועים	`incident_regression`	נמצאה רגרסיה חדשה באירוע הזה
האירוע הוקצה	`incident_assigned`	האירוע הוקצה למשתמש
האירוע הוקצה מחדש	`incident_reassigned`	האירוע הוקצה מחדש למשתמש אחר
האירוע לא הוקצה	`incident_unassigned`	ההקצאה של משתמש לאירוע הזה בוטלה
רמת החומרה השתנתה	`incident_severity_changed`	רמת החומרה עודכנה
התוקף השתנה	`incident_validity_changed`	סטטוס התוקף עודכן
הגישה אושרה	`incident_access_granted`	משתמש קיבל גישה לאירוע הזה
הגישה בוטלה	`incident_access_revoked`	הגישה לאירוע הזה בוטלה למשתמש
שותף באופן ציבורי	`incident_shared_publicly`	נוצר קישור לשיתוף באופן גלוי לכולם
השיתוף עם הציבור בוטל	`incident_unshared_publicly`	הקישור לשיתוף שגלוי לכולם הושבת
המשוב נשלח	`issue_feedback_received`	נשלח משוב על האירוע הזה
תגובה חדשה	`incident_note_created`	נוצר פתק חדש לאירוע הזה

מבנה לדוגמה של מטען ייעודי (payload)

כל המטענים הייעודיים (payloads) של ה-webhook הם במבנה הבא:

{
    "source": "GitGuardian",
    "timestamp": "2025-01-15T10:30:00.123456Z",
    "action": "incident_triggered",
    "message": "A new incident has been detected.",
    "target_user": "john.doe@example.com",
    "target_team": "Security Team",
    "custom_webhook_name": "Google SecOps SIEM Integration",
    "incident": {
        "id": 12345,
        "date": "2025-01-15T10:29:58.123456Z",
        "detector": {
            "name": "aws_iam",
            "display_name": "AWS Keys",
            "nature": "specific",
            "family": "credentials"
        },
        "secret_hash": "abc123...",
        "secret_revoked": false,
        "validity": "valid",
        "occurrence_count": 1,
        "status": "triggered",
        "assignee_email": null,
        "severity": "high",
        "gitguardian_url": "https://dashboard.gitguardian.com/workspace/1/incidents/12345"
    }
}

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

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

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

שיטות מומלצות

בחירת אירועים: כדי לצמצם את הרעש, נרשמים רק לאירועים שרלוונטיים לפעולות האבטחה שלכם.
הגדרת היקף הצוות: בסביבות עבודה עסקיות, אפשר ליצור ווּבּהוּקים ברמת הצוות כדי לסנן אירועים לפי הבעלות על הצוות.
אימות חתימה: אחסנו את אסימון החתימה בצורה מאובטחת ואל תבצעו אף פעם commit שלו לקוד המקור.
מעקב: בודקים באופן קבוע את סטטוס המסירה של ה-webhook בלוח הבקרה של GitGuardian.
בדיקה: מומלץ להשתמש בתכונת הודעת הבדיקה כדי לוודא שהגדרת ה-webhook תקינה לפני שמשתמשים בו בסביבת הייצור.

התחייבויות מסירה

חשוב: המסירה של Webhook היא על בסיס 'השתדלות מרבית' ולא מובטחת. אם נקודת הקצה של Google SecOps לא נגישה או שיש בעיות ברשת, יכול להיות שלא יתקבלו אירועי webhook. למרות שתגובות Webhook הן בדרך כלל אמינות, אי אפשר להבטיח שהן יתקבלו.

בתרחישי שימוש קריטיים, מומלץ להשתמש ב-API polling תקופתי בנוסף ל-webhooks, כדי לוודא שלא מפספסים אף אירוע.

טבלת מיפוי UDM

שדה ביומן	מיפוי UDM	היגיון
תאריך	metadata.event_timestamp	ההמרה בוצעה באמצעות פורמט ISO8601
has_user	metadata.event_type	הערך הוא USER_UNCATEGORIZED אם has_user הוא true, אחרת הערך הוא GENERIC_EVENT
event_name	metadata.product_event_type	הערך הועתק ישירות
id	metadata.product_log_id	הערך הועתק ישירות
	metadata.product_name	מגדירים את הערך "GitGuardian Enterprise"
	metadata.vendor_name	מגדירים את הערך "GitGuardian"
member_email	principal.user.email_addresses	המיזוג בוצע מ-member_email
member_name	principal.user.user_display_name	הערך הועתק ישירות
member_id	principal.user.userid	הומרה למחרוזת
action_type	security_result.action_details	הערך הועתק ישירות
target_ids	target.resource.product_object_id	ערך מהרכיב הראשון של target_ids

יומן שינויים

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

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