תרומה של שילובים של תשובות מהקהילה

נתמך ב:

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 > 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 + Auth parameters), אלא אם ה-API הבסיסי לא דורש אימות כלשהו ואפשר לקודד את ה-API Root. בכל השילובים שבהם נדרש אימות, צריך להיות פרמטר Verify SSL.

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

פעולת פינג

הפעולה Ping היא פעולה מיוחדת שמשמשת את הפלטפורמה כדי לאמת את הקישוריות ל-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 בתוך Expression Builder במהלך תהליך היצירה של הפלייבוק. דוגמה מדויקת של קובץ 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.

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

"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} צריך לכלול את הפרמטרים הבאים:

• ‫Max Alerts To Fetch (מספר ההתראות המקסימלי לאחזור): קובע כמה {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}.

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

• ‫Max {Hours/Days} Backwards: קובע את שעת ההתחלה של החזרה הראשונה של המשימה.
• ‫Verify SSL: אימות הקישוריות ל-API או למכונה.

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