הוספת שילובים של תגובות מהקהילה

נתמך ב:

Google SecOps SOAR

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

מטא-נתונים של שילוב התשובות

שם

השדה Name צריך להתאים לשם המוצר שאיתו השילוב יתבצע, ואסור שיהיו בו תווים מיוחדים.

השם המוצג צריך להיכתב עם רווחים, לדוגמה: Vertex AI ולא VertexAI.

מזהה השילוב

‫Integration Identifier הוא מזהה ייחודי של השילוב. אחרי שיוצרים את השילוב, אי אפשר לשנות את הערך הזה. המזהה צריך להיות זהה לערך של Name, אבל בלי רווחים.

המזהה זמין ברוב המקומות בפלטפורמה.

תיאור

התיאור צריך לספק סקירה כללית של המוצר שאיתו נוצר השילוב, ולא לחרוג מ-500 תווים. היא צריכה לכלול את הפרטים הבאים:

This integration is owned by the "{vendor name}". Support Contact: {email}.

אל תכללו כתובות URL בתיאור.

סמלי לוגו

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

כדאי לאמת את הלוגו בדפים הבאים:

• Response > Integration Setup
• Automation > Playbooks > Playbook Designer
• Cases > Alert > Alert Playbook View

הדוגמה הבאה היא לוגו בפורמט SVG, שמעוצב בהתאם למדריך הסגנון שלנו:

        <?xml version="1.0" encoding="UTF-8"?><svg id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 21 23"> <defs> <style> .cls-1 { stroke-width: 0px; } </style> </defs> <path class="cls-1" d="M15.51,4.79H5.49c-.4,0-.72.32-.72.72v5.75c0,2.3,1.71,4.15,3.69,5.38.54.34,1.1.62,1.66.86l.09.04c.06.02.12.05.18.06.03,0,.07,0,.1,0,.1,0,.19-.03.28-.07l.09-.04c.76-.33,2.22-1.03,3.46-2.24,1.24-1.22,1.89-2.6,1.89-4v-5.75c0-.4-.32-.72-.72-.72ZM14.32,11.26c0,.88-.44,1.77-1.32,2.63-.65.64-1.55,1.22-2.5,1.68-.95-.46-1.84-1.04-2.5-1.68-.88-.86-1.32-1.75-1.32-2.63v-4.55h7.64v4.55ZM20.28,0H.72c-.4,0-.72.32-.72.72v10.77c0,2.56,1.18,4.99,3.51,7.21,2.29,2.18,5.12,3.56,6.61,4.2l.09.04s.1.04.15.05c.04,0,.09.01.13.01.1,0,.19-.02.28-.06l.09-.04c.53-.23,1.23-.55,2.02-.97,1.42-.75,3.11-1.82,4.59-3.23,2.33-2.22,3.51-4.64,3.51-7.21V.72c0-.4-.32-.72-.72-.72ZM16.17,17.31c-1.9,1.81-4.24,3.04-5.67,3.69-1.43-.65-3.77-1.88-5.67-3.69-1.94-1.84-2.92-3.8-2.92-5.82V1.92h17.18v9.57c0,2.02-.98,3.98-2.92,5.82Z"/></svg>
        

חשוב לקודד את קובץ ה-SVG לפני שמוסיפים אותו לקובץ הגדרת השילוב, כמו שאפשר למצוא בשילובים אחרים ב-Content Hub.

קישור למאמרי העזרה

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

המשתמשים יכולים לגשת לקישור למסמך מהקטע Parameters בתיבת הדו-שיח Configure Instance.

פרמטרים להגדרה

כל השילובים צריכים להכיל פרמטרים של הגדרות אישיות (פרמטרים של API Root ואימות), אלא אם ה-API הבסיסי לא דורש אימות ואפשר להגדיר את ה-API Root באופן קבוע בקוד. בכל השילובים שבהם נדרש אימות, צריך להיות פרמטר Verify SSL.

לכל הפרמטרים צריך להיות תיאור. התיאור צריך לעזור למשתמשים להגדיר את השילוב מתוך הפלטפורמה. אל תכללו כתובות URL בתיאור של הפרמטרים.

פעולת פינג

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

נתוני גרסה

המבנה הכללי של הערת הגרסה צריך להיות בפורמט הבא:

• {integration item} - {update}
• לדוגמה: Get Case Details - Added ability to fetch information about affected IOCs

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

• אם זה שילוב חדש: New Integration Added - {integration name}
• אם מוסיפים פעולה חדשה: New Action Added - {action name}
• אם מוסיפים מחבר חדש: New Connector Added - {connector name}
• אם נוספת משרה חדשה: New Job Added - {job name}
• אם מוסיפים ווידג'ט מוגדר מראש לפעולה: {action name} - Added Predefined Widget.
• אם ווידג'ט מוגדר מראש מתעדכן: {action name} - Updated Predefined Widget.
• לשינויים שמשפיעים על כל פריטי השילוב: Integration - {Update}
• לשינויים שמשפיעים על כל הפעולות: Integration's Actions - {Update}
• לשינויים שמשפיעים על כל המחברים: Integration's Connectors - {Update}
• לשינויים שמשפיעים על כל המשימות: Integration's Jobs - {Update}

אם הגרסה מכילה שינוי רגרסיבי, צריך לציין REGRESSIVE! בהערת הגרסה. לדוגמה, Google Chronicle - Chronicle Alerts Connector - REGRESSIVE! Updated mapping.

הערות הגרסה זמינות בחלונית הצדדית Integration Details שמוצגת כשלוחצים על הכפתור Details בשילוב.

ניהול גרסאות

אחרי כל עדכון של השילוב, צריך לעדכן את גרסת השילוב ב-‎+1. הגרסאות צריכות להיות מיוצגות כמספר שלם. גרסאות משניות כמו 11.1.3 או 11.1 לא מותרות.

תגים

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

הערות כלליות

• לבדוק את כל תוכן השילוב לפני השליחה.
• בודקים את כל תוכן השילוב כדי לאתר נקודות חולשה פוטנציאליות ויחסי תלות פגיעים.
• במהלך הפיתוח, תמיד צריך להשתמש בגרסה העדכנית ביותר של Python שנתמכת (Python 3.11).

פעולות

שם

שם הפעולה צריך להצביע על הפעילות שמבוצעת. לדוגמה, Get Case Details,‏ List Entity Events או Execute Search.

אם הפעולה מיועדת לעבוד בעיקר עם ישויות, עדיף להוסיף את Entity לשם, לדוגמה: Enrich Entities.

שמות הפעולות צריכים להיות באורך של 2-3 מילים.

תיאור

תיאור הפעולה צריך להבהיר למשתמש מה תהיה התוצאה של ביצוע הפעולה.

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

Add a vote to entities in VirusTotal. Supported entities: File Hash, URL, Hostname, Domain, IP Address. Note: only MD5, SHA-1 and SHA-256 Hash types are supported.

אם הפעולה פועלת במצב אסינכרוני, צריך להוסיף את ההערה הבאה בתיאור:

Note: Action is running as async, adjust script timeout value in Google SecOps IDE for action, as needed.

כדאי להגביל את התיאור ל-500 תווים.

פרמטרים של פעולות

לפרמטרים של הגדרת הפעולה צריך להיות שם אינטואיטיבי. אל תשתמשו בתווים מיוחדים ונסו להגביל את שם הפרמטר של הפעולה ל-2 עד 4 מילים.

התיאור של הפרמטר צריך להסביר למשתמש מה ההשפעה של הפרמטר הזה על ביצוע הפעולה. אם הפרמטר תומך בכמות מוגדרת מראש של ערכים נתמכים, צריך להוסיף את הקטע הבא בתוך התיאור: Possible Values: {value 1}, {value 2}

פלט הפעולה (תוצאת הסקריפט)

תוצאת הסקריפט צריכה לייצג תוצאה פשוטה של הפעולה. ברוב המקרים, הוא צריך להצביע על משתנה שנקרא is_success, שיכול לקבל את הערכים true או false.

באופן כללי, אם הפעולה הסתיימה ובוצעה, הערך של is_success צריך להיות true.

פלט הפעולה (תוצאת JSON)

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

הגודל המקסימלי של תוצאות בפורמט JSON הוא 15MB.

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

{
   "10.10.10.10": {
      "is_malicious": "false"
   }
}
    

במקום זאת, צריך להזין את המספר בפורמט הבא:

[
   {
      "is_malicious": "false",
      "ip": "10.10.10.10"
   }
]
   

אם אתם משתמשים בישויות בתוך הפעולה ומחזירים תוצאות לכל ישות, מומלץ להגדיר את מבנה תוצאת ה-JSON כך:

[
   {
       "Entity": "10.10.10.10",
       "EntityResult": {
           "is_malicious": "false",
       }
   }
]
    

תמיד כדאי לחשוב איך אפשר להשתמש בפלט של הפעולה בתוך האוטומציה.

מוודאים שיש קובץ JSON לדוגמה לפעולה.

הפלטפורמה משתמשת בדוגמת ה-JSON בכלי לבניית ביטויים במהלך תהליך היצירה של הפלייבוק. דוגמה מדויקת של קובץ JSON משפרת באופן משמעותי את חוויית היצירה של הפלייבוק. מסירים את כל הפרטים האישיים המזהים (PII) מדוגמאות ה-JSON.

פלט של פעולות (העשרת ישויות)

אם הפעולות מתבצעות על ישויות, במהלך ביצוע הפעולה אפשר להוסיף להן עוד מטא-נתונים. המבנה של המטא-נתונים צריך להיות בפורמט הבא: {integration identifier}_{key}. לדוגמה: WebRisk_is_malicious.

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

פלט של פעולות (הודעת פלט)

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

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

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

דוגמאות להודעות פלט:

• Successfully enriched the following entities using information from VirusTotal: {entity.identifier}
• Action wasn't able to find any information for the following entities using VirusTotal: {entity.identifier}
• None of the provided entities were found in VirusTotal.
• Successfully executed query "{query}" in Google SecOps.

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

"Error executing action "{action name}". Reason: {error}'

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

מחברים

שם

שם המחבר צריך להפנות את המשתמש לנתונים שיוטמעו. באופן כללי, מבנה השם צריך להיות כזה:

• {integration display name} - {data that is being ingested} Connector
• לדוגמה: Crowdstrike - Pull Alerts Connector

תיאור

תיאור המחבר צריך להדגיש למשתמש מה ייקלט על ידי המחבר, לדוגמה, Pull alerts from Crowdstrike. בנוסף, צריך לספק מידע על התמיכה ברשימות דינמיות, לדוגמה, Dynamic List works with the display_name parameter.

התיאור הסופי במקרה הזה ייראה כך:

Pull alerts from Crowdstrike. Dynamic List works with the display_name parameter.

כדאי להגביל את התיאור ל-500 תווים.

פרמטרים של מחברים

לפרמטרים של הגדרת המחבר צריך להיות שם אינטואיטיבי. אל תשתמשו בתווים מיוחדים ונסו להגביל את שם הפרמטר של הפעולה ל-2 עד 4 מילים.

תיאור הפרמטר צריך להסביר למשתמש מה ההשפעה של הפרמטר על הפעלת המחבר.

אם הפרמטר תומך בכמות מוגדרת מראש של ערכים נתמכים, צריך להוסיף את הקטע הבא בתיאור: Possible Values: {value 1}, {value 2}. צריכה לכלול את הפרמטרים הבאים:

• מספר ההתראות המקסימלי לאחזור: קובע כמה {object} צריך לעבד במהלך איטרציה אחת של המחבר.
• Max {Hours/Days} Backwards: קובע את שעת ההתחלה באיטרציה הראשונה של המחבר. לדוגמה, אם הערך של Max Hours Backwards הוא 1, המחבר יתחיל לשלוף נתונים משעה אחת קודם.
• אימות SSL: מאמת את הקישוריות ל-API או למכונה.

מיפוי אונטולוגיה

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

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

רשימה דינמית

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

אם אתם יוצרים לוגיקה מותאמת אישית לרשימה דינמית, חשוב לוודא שהיא מופיעה בתיאור של המחבר. בנוסף, מומלץ להוסיף את הפרמטר Use Dynamic List as a blocklist (שימוש ברשימה דינמית כרשימת חסימה) כדי לתמוך גם בלוגיקה הפוכה.

תעסוקה

שם

שם המשימה צריך להסביר למשתמש מה המשימה הזו מבצעת. באופן כללי, מבנה השם צריך להיות כזה:

• {integration display name} - {process} Job
• לדוגמה: ServiceNow - Sync Incidents Job

תיאור

תיאור המשימה צריך להבהיר למשתמש מה המשימה עושה במהלך האיטרציות, לדוגמה This job will synchronize Security Command Center based cases created by the Urgent Posture Findings connector.

כדאי להגביל את התיאור ל-500 תווים.

פרמטרים של משימות

לפרמטרים של הגדרת המשימה צריך להיות שם אינטואיטיבי. אל תשתמשו בתווים מיוחדים ונסו להגביל את שם הפרמטר של הפעולה ל-2 עד 4 מילים.

התיאור של הפרמטר צריך להסביר למשתמש מה ההשפעה של הפרמטר על ביצוע המשימה.

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

Possible Values: {value 1}, {value 2}.

בנוסף לפרמטרים של אימות, כל המשימות צריכות לכלול את הפרמטרים הבאים:

• מקסימום {שעות/ימים} אחורה: קובע את שעת ההתחלה של החזרה הראשונה של המשימה.
• אימות SSL: מאמת את הקישוריות ל-API או למכונה.

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