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

נתמך ב:

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

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

שם

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

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

מזהה השילוב

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

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

תיאור

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

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

לא מומלץ להוסיף כתובות URL לתיאור.

סמלי לוגו

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

צריך לאמת את הלוגו בדפים הבאים:

הדוגמה הבאה היא של לוגו בפורמט 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 לפני שמוסיפים אותו לקובץ הגדרת השילוב, כפי שאפשר לראות בשילובים אחרים במרכז התוכן.

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

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

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

כל השילובים צריכים לכלול פרמטרים של הגדרה (API Root + Auth parameters), אלא אם ה-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.

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

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 יהיו נגישים במהלך ההפעלה של ה-playbook. מוודאים שאובייקט 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 במהלך תהליך בניית ה-Playbook. דוגמה מדויקת של קובץ JSON משפרת משמעותית את חוויית השימוש ב-Playbook. צריך להסיר מידע אישי מזהה (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}.

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

  • מקסימום {Hours/Days} אחורה: מגדיר את שעת ההתחלה באיטרציה הראשונה של העבודה.
  • אימות SSL: מאמת את הקישוריות ל-API או למופע.

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