יצירת מחבר בהתאמה אישית

נתמך ב:

Google SecOps SOAR

הערה: המסמך הזה מניח שיש לכם ידע מעשי ב-Python ובתוכנות מונחות-עצמים.

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

הערה: מידע נוסף על ספריית TIP Common

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

1. יוצרים מחלקת Manager שמכילה את הלוגיקה של ה-API לכלי של הצד השלישי.
2. יוצרים את המחבר באמצעות סביבת הפיתוח המשולבת (IDE).

יצירת חשבון הניהול

השלב הראשון ביצירת מחבר הוא ליצור מחלקת Manager שמכילה את כל הלוגיקה הנדרשת של ה-API לטכנולוגיה שאיתה אתם מבצעים את השילוב. לדוגמה, השילוב של Netskope ב-Google SecOps כולל מנהל מובנה. הכלי הזה מכיל את כל הלוגיקה שנדרשת כדי ליצור אינטראקציה עם Netskope API, ואפשר להשתמש בו כמודל להטמעה שלכם.

יצירת המחבר

ב-IDE, יוצרים מחבר חדש לפי ההוראות במאמר יצירת שילוב בהתאמה אישית. סביבת הפיתוח המשולבת תיצור תבנית גנרית שכוללת הערות קוד שמתארות את המבנה והדרישות הבסיסיים של סקריפט מחבר.

למרות שהלוגיקה של המחבר יכולה להשתנות, התהליך כולל בדרך כלל את השלבים הבסיסיים האלה:

1. משתמשים ב-API של הכלי של הצד השלישי כדי לאחזר התראות, זיהויים או אירועים. במקרה של Netskope, הטיפול מתבצע באמצעות השיטה get_alerts(). כדי לוודא שההתראות לא משוכפלות, שולחים שאילתה לפי חותמת זמן ומעדכנים אותה אחרי כל הפעלה.
2. יצירת התראה באמצעות המחלקה AlertInfo (לשעבר CaseInfo) והקצאת כל שדות החובה
3. מאחזרים ומפשטים את נתוני האירועים המשויכים כדי למנוע בעיות ברשימות ובמילונים מקוננים, ואז מוסיפים את האירועים המפושטים להתראה.
4. ממיינים את ההתראות לפי זמן ומאחסנים את חותמת הזמן האחרונה לשימוש בשאילתה הבאה.

הערה: התראה יכולה לכלול כמה אירועים. לדוגמה, פלטפורמות SIEM יוצרות קורלציה בין כמה אירועים לאזעקה אחת (כמו Trellix ESM) או לעבירה אחת (כמו QRadar). לעומת זאת, כלי זיהוי של נקודות קצה בדרך כלל יוצרים אירוע אחד לכל התראה. הלוגיקה של המחבר צריכה לשקף את המבנה של מקור הנתונים.

ייבוא ו-SDK

כל מחבר חייב:

• מייבאים את הכיתה SiemplifyConnectorExecution מ-SiemplifyConnectors. הכיתה הזו בדרך כלל מופעלת בפונקציה main() של המחבר. הסקריפט מסתיים כשהאובייקט הזה מעביר רשימה של התראות לאפליקציית Google SecOps באמצעות השיטה return_package().
• מייבאים את הכיתה AlertInfo מ-SiemplifyConnectorsDataModel. יצירת מופע של המחלקה הזו יוצרת את אובייקט ההתראה. בדוגמה הזו, הוא משנה את השם ל-SiemplifyAlertInfo כדי למנוע בלבול עם אובייקטים מובנים של התראות במערכת המקורית (Netskope), שבה שינוי השם הזה הוא אופציונלי.

המודול SiemplifyUtils מספק שיטות נפוצות לרישום ביומן, טיפול בפורמטים של נתונים, המרות זמן ועוד. מומלץ לייבא את output_handler, dict_to_flat ו-unix_now, כי הם חיוניים לפונקציונליות הבסיסית, כולל טיפול בזמן.

רוב המחברים מייבאים גם את מחלקת הניהול של השילוב. חלק מהשילובים כוללים יותר מחשבון ניהול אחד. אפשר גם לייבא ספריות Python סטנדרטיות נוספות, בהתאם לתרחיש לדוגמה.

הערה: מחברים ישנים יותר יכולים להשתמש ב-CaseInfo מ-SiemplifyConnectors. זו אותה מחלקה כמו AlertInfo והיא משקפת מוסכמה למתן שמות שהוצאה משימוש.

משתנים קבועים

מומלץ להגדיר כמה משתנים קבועים לשימוש מאוחר יותר.

איור 1: משתנים קבועים

דוגמה לסקריפט ליצירת התראה של Google SecOps

כדי ליצור התראה, צריך ליצור מופע של אובייקט מהמחלקה AlertInfo, כמו שמתואר למעלה. בדוגמה הזו, השם שלו שונה ל-SiemplifyAlertInfo() כדי למנוע בלבול עם מערכת המקור. אובייקט alert_info כולל כמה מאפיינים נדרשים שצריך להגדיר כדי שהאפליקציה תעבד את ההתראה בצורה נכונה. הפונקציה build_alert_info מקבלת כקלט התראה של Netskope (בפורמט JSON גולמי, שהתקבל מה-API) ואת האובייקט Siemplify. לאחר מכן, המערכת מנתחת את ההתראה של Netskope ומקצה את הערכים הרלוונטיים לשדות alert_info.

הפונקציה הזו משתמשת גם בקבועים שהוגדרו קודם. כל המאפיינים שמוגדרים באובייקט alert_info הופכים לחלק מהאובייקט של ההתראה באפליקציית Google SecOps.

בשורה 35 (באיור 2) מודגש חלק חשוב בתהליך הזה: ההתראה משוטחת באמצעות השיטה dict_to_flat, ואז מצורפת למאפיין events.

איור 2: דוגמה לסקריפט ליצירת התראה

 

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

השיטה dict_to_flat משמשת לשיטוח של מבנה ה-JSON הגולמי. כך אפשר למנוע בעיות ברשימות ובמילונים בתצוגת עץ. צמדים שטוחים של מפתח/ערך הם גרסאות שעברו שינוי קל של הצמדים המקוריים.

כדאי לעיין בלוגיקה הבאה באיור 2:

• למאפיין display_id מוקצה ערך שנוצר באופן אקראי באמצעות הספרייה uuid. ההתראות של Netskope לא כוללות שדה UUID, אבל אם היה שדה כזה, אפשר היה להשתמש בו במקום זאת.
• הערך של ticket_id מוגדר כך שיתאים לערך של display_id. שני השדות חייבים להיות ייחודיים לכל התראה במערכת. הייחודיות הזו מובטחת על ידי יצירת מזהה ייחודי אוניברסלי (UUID) אקראי.
• ‫name הוא שם ההתראה ויוצג בממשק המשתמש הגרפי.
• ‫rule_generator מתייחס לכלל שיצר את ההתראה במערכת המקור. יכול להיות שהשדה הזה לא תמיד יופיע בנתונים הגולמיים. אם הוא חסר, אפשר להקצות כל ערך מחרוזת, אבל אסור להשאיר אותו ריק.
• ‫start_time ו-end_time מייצגים את חותמות הזמן של ההתראה. בדוגמה הזו, ההתראה של Netskope מספקת חותמת זמן של ראשית זמן יוניקס (Unix epoch), שצריך להכפיל ב-1,000 כדי להמיר אותה לאלפיות השנייה. זה הפורמט שנדרש ב-Google SecOps. אם המקור משתמש בפורמט אחר, צריך להמיר אותו. במודול SiemplifyUtils.py יש שיטות שימושיות להמרת זמן.
• ‫priority: אפליקציית Google SecOps מקצה עדיפות לכל אירוע על סמך העדיפות של ההתראה שלו. ‫Google SecOps API ממפה ערכים מספריים לתוויות חזותיות באמצעות הסכימה הבאה, שבה הערך השלם מועבר במחבר: {"Informative": -1, "Low": 40, "Medium": 60, "High": 80, "Critical": 100} כאשר הערך השלם הוא מה שמועבר במחבר. לדוגמה, אם מעבירים את הערך `100`, ההתראה מסומנת כקריטית בממשק המשתמש הגרפי. במחבר הזה, פונקציית עזר נוספת ממפה את ערכי החומרה של Netskope לסולם העדיפות הזה באמצעות הקבוע SEVERITY_MAP. עם זאת, בגלל חוסר העקביות בשדות החומרה של Netskope, המיפוי דורש לוגיקה נוספת כדי להעריך כמה שדות.
• הערכים של device_vendor ו-device_product מוקצים מקבועים שהוגדרו קודם לכן בסקריפט.
• ‫environment הוא קריטי כשמשתמשים בכמה סביבות ב-Google SecOps. במקרה הזה, הוא מגיע מהאובייקט siemplify ומתאים לסביבה שנבחרה עבור המחבר בפלטפורמה.
• בשורה 37 (איור 3), המחבר משנה את מילון אירועי הבסיס על ידי הוספת מפתח חדש, product_name, עם הערך 'Netskope'. הפעולה הזו נדרשת כי הנתונים הגולמיים לא כוללים שדה מוצר עקבי שאפשר להשתמש בו למיפוי ולמודלים באונטולוגיה של הפלטפורמה.

  

  איור 3: שינוי אירוע הבסיס

דוגמה לסקריפט להפעלת המחבר

הפונקציה main מכילה את לוגיקת הביצוע המרכזית של המחבר:

• הדקורטור output_handler משמש למטרות ניפוי באגים ולא נכלל במסמך הזה.
• הפונקציה main כוללת פרמטר אופציונלי, is_test_run, שערך ברירת המחדל שלו הוא False. כפי שהשם מרמז, הפרמטר הזה קובע אם המחבר צריך להטמיע התראות בסביבת הייצור או לפעול במצב בדיקה מהכרטיסייה Connector Testing (בדיקת המחבר) באפליקציה.

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

איור 3: שינוי אירוע הבסיס

• בשורה 56 ובשורה 57 מתבצעת אתחול של שתי רשימות ריקות שמשמשות במהלך ההרצה.
• בשורה 58, המחלקה SiemplifyConnectorExecution יוצרת מופע של האובייקט siemplify. האובייקט הזה מנהל את רוב התנהגות זמן הריצה של המחבר.
• בשורה 61, נוצר מופע של Connector Allowlist. הוא לא משמש במחבר הזה, אבל הוא משמש בדרך כלל במחברים אחרים ולא נדון במדריך הזה.
• בשורה 67 עד 69, מוגדרים משתנים לפרמטרים של המחבר, כמו פרטי כניסה לאימות או הגדרות.
• בשורה 71, האובייקט NetskopeManager מופעל והפרמטרים הרלוונטיים מועברים כדי לאפשר אימות מוצלח. הלוגיקה הפנימית של חשבון הניהול שמטפלת באימות לא מוצגת בדוגמה הזו.
• בשורה 73, הפונקציה מאחזרת חותמת זמן מקובץ מקומי שנוצר במהלך הפעלות קודמות של המחבר. חותמת הזמן הזו משמשת כדי למנוע עיבוד חוזר של אותן התראות.
• בשורה 74 ובשורה 75, המערכת מטפלת במקרה שבו המחבר פועל בפעם הראשונה וחותמת הזמן עדיין לא מוגדרת (לדוגמה, כשהיא מוגדרת כברירת מחדל ל-0). מכיוון שמערכת Netskope דורשת זמן של ראשית זמן יוניקס ולא מקבלת 0 כזמן התחלה תקין, נעשה שימוש בפונקציה unix_now כדי לאחזר את השעה הנוכחית באלפיות השנייה. הערך הזה מחולק ב-`1,000` כדי להמיר אותו לשניות מראשית זמן יוניקס (Unix epoch). שעות ההתחלה והסיום שמתקבלות מועברות ל-method‏ `get_alerts` ב-Manager. הרבה ממשקי API מקבלים רק שעת התחלה, אבל Netskope API דורש גם שעת התחלה וגם שעת סיום לשאילתות של התראות מבוססות-זמן.
הערה: הטיפול בזמן ובחותמות זמן הוא אחד מההיבטים המורכבים ביותר של בניית מחבר. מערכות שונות של צדדים שלישיים מחזירות חותמות זמן בפורמטים שונים, ויכול להיות שחלקן לא תומכות בשאילתות שמבוססות על אותו פורמט שהן מחזירות. חשוב להבין לעומק את ה-API של מערכת המקור.
• בשורה 77, הוא מאחזר רשימה של התראות מ-Netskope. אם המחבר פועל במצב בדיקה, רק ההתראה האחרונה ברשימה נבחרת (שורות 79-80).

לוגיקת גלישה

לאחר מכן, המחבר חוזר על הפעולה לגבי כל ההתראות שאוחזרו ויוצר התראה מכל אחת מהן באמצעות הפונקציה build_alert_info שהוגדרה קודם. היא מוסיפה כל התראה לרשימה all_alerts, שהופעלה קודם לכן. החלק הבא בלוגיקה של המחבר מטפל בגלישה.
הגדרת סף היא מנגנון שמונע את ההוספה של יותר מדי התראות בפרק זמן קצר, במיוחד כשההתראות משותפות לאותה סביבה, לאותו מוצר ולאותו מחולל כללים. ההטמעה של לוגיקת גלישה היא לא חובה, אבל אנחנו ממליצים להטמיע אותה כדי למנוע פגיעה בביצועים.

באיור 4 מוצגת התפלגות של לוגיקת הגלישה לכל שורת תסריט:

• בשורה 104 עד 105, אם alert לא מסווג כגלישה מעבר למגבלה, הוא מצורף לרשימת ההתראות להטמעה.



איור 4: מנגנון הגלישה.

סיום ההרצה של המחבר

אם המחבר לא פועל במצב בדיקה, צריך לעדכן את חותמת הזמן כך שתשקף את ההתראה האחרונה שאוחזרה. כך מוודאים שאותם התראות לא ייקלטו מחדש במהלך מחזור ההפעלה הבא. הרשימה all_alerts ממוינת לפי חותמת זמן, כך שגם התראות שחורגות מהמגבלה תורמות לקביעת חותמת הזמן האחרונה.

באיור 5 אפשר לראות את פירוט הלוגיקה של הפעלת המחבר לפי כל שורת סקריפט:

• בשורה 126, רשימת ההתראות שלא חרגו מהקיבולת נשלחת לאפליקציה, שם ההתראות נוצרות ומוצגות בממשק המשתמש הגרפי.
• בשורה 128 עד 131, הם קובעים אם המחבר פועל במצב בדיקה. ההחלטה הזו מתקבלת על סמך ארגומנטים של המערכת שמועברים על ידי האפליקציה, למשל כשלוחצים על הפעלת המחבר פעם אחת בכרטיסייה בדיקה.
  

  

  איור 5: סיום ההפעלה של כלי החיבור

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