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

נתמכים ב:

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

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

שם

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

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

מזהה השילוב

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

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

תיאור

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

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

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

סמלי לוגו

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

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

  • אוטומציה > הגדרת שילובים. אם אתם משתמשים בפלטפורמה של SOAR בלבד, עוברים אל Response > Integrations Setup.
  • Automation > Playbooks > Playbook Designer. אם אתם משתמשים בפלטפורמה של SOAR בלבד, עוברים אל 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 ואימות), אלא אם ה-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 בתוך 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.

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

"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.