יצירת שילובים בהתאמה אישית

נתמך ב:

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

יצירת שילוב בהתאמה אישית בסביבת הפיתוח המשולבת

אתם יכולים ליצור שילוב מותאם אישית למוצר Armis וליצור מנהל עם פעולת Ping. ההנחה היא שיש לכם ידע ב-Python ובתכנות מונחה-אובייקטים.

תרחיש שימוש: יצירת שילוב מותאם אישית של Armis

כדי ליצור את השילוב המותאם אישית בסביבת הפיתוח המשולבת (IDE):

  1. בתפריט הראשי, עוברים אל תגובה > IDE.
  2. לוחצים על Create New Item (יצירת פריט חדש) ובוחרים באפשרות Integration (שילוב).
  3. מזינים שם ולוחצים על יצירה.

השילוב יופיע עכשיו עם האפשרות הגדרות הגדרות, מה שמציין שמדובר בשילוב מותאם אישית.

לוחצים על settings הגדרות כדי להציג את הגדרות השילוב שבהן אפשר להגדיר את הסמל, התיאור, התלות ב-Python ופרמטרים של השילוב.

אם לחבילת תלות אין קובץ wheel (.WHL) שעבר קומפילציה מראש וזמין לארכיטקטורה manylinux_2_17_x86_64, או אם אתם צריכים גרסה ספציפית של קוד המקור, אתם יכולים לספק כתובת URL ישירה לקוד המקור (לדוגמה, קובץ .tar.gz). פותר התלות של הפלטפורמה, uv, תומך בהגדרת כתובות ה-URL האלה של המקור בטבלה [tool.uv.sources] בקובץ pyproject.toml. לדוגמה: 

[project]
# ... other project fields ...

[tool.uv.sources]
compressed-rtf = { url = "https://files.pythonhosted.org/packages/.../compressed_rtf-1.0.6.tar.gz" }
dkimpy = { url = "https://files.pythonhosted.org/packages/.../dkimpy-1.1.8.tar.gz" }

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

לשילובים שדורשים ספריות חיצוניות מורכבות או רב-שכבתיות כמו TIPCommon, Google ממליצה לוותר לחלוטין על העלאות ידניות של IDE ולפתח אותן באופן מקומי באמצעות הכלי Marketplace CLI (mp). הכלי הזה עוקב אחרי יחסי תלות מקוננים ואורז אותם באופן אוטומטי באמצעות מנהל החבילות uv.

דרישות מוקדמות

  • ‫Python 3.11 ואילך מותקן במחשב הפיתוח המקומי.
  • מנהל החבילות של Python‏ uv מותקן (ראו את מדריך ההתקנה של uv).

הגדרה ראשונית

  1. יוצרים Fork ומשכפלים את המאגר הרשמי של Content Hub לסביבה המקומית.
  2. מתקינים את הכלי mp באמצעות uv: 
    uv tool install mp --from git+https://github.com/chronicle/content-hub.git#subdirectory=packages/mp
  3. נכנסים לסביבת Google SecOps באמצעות כתובת ה-URL הבסיסית של המכונה ומפתח ה-API מדור קודם: 
    mp login --api-root https://{YOUR_INSTANCE}.siemplify-soar.com --api-key {YOUR_LEGACY_API_KEY}
  4. מגדירים את הנתיב של מאגר הבסיס המקומי: 
    mp config --root-path /path/to/cloned/content-hub
  5. יוצרים ספריית משנה בהתאמה אישית לשילובים הקנייניים בפריסת המאגר בכתובת: content-hub/content/response_integrations/custom/

הוספת תלות ב-TIPCommon או תלות מורכבת לשילוב

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

  1. עוברים לספרייה של השילוב המותאם אישית בתוך המאגר המשוכפל: 
    cd content-hub/content/response_integrations/custom/
  2. שליפת מבנה האינטגרציה הקיים ממופע Google SecOps: 
    mp pull --type integration --name "{INTEGRATION_NAME}"
  3. מעבירים את הספרייה לתיקיית השילוב החדשה שנוצרה: 
    cd {INTEGRATION_NAME}
  4. משתמשים ב-uv כדי להחדיר את קובץ הגלגל TIPCommon הנדרש לחבילה. הפעולה הזו עוקבת אחרי גלגלי התלות המשנית המקוננת ומורידה אותם באופן אוטומטי לתצורת חבילת הסביבה המקומית: 
    uv pip install /path/to/wheels/TIPCommon-your-version-py3-none-any.whl
  5. מעלים את השילוב שעבר קומפילציה מלאה, יחד עם עץ התלות החדש שלו, בחזרה למופע Google SecOps: 
    mp push --type integration --name "{INTEGRATION_NAME}"

אימות ההתקנה

כדי לוודא שהחבילה של התלויות נוצרה בהצלחה בלי להיתקל בלולאת errorCode: 2000, פועלים לפי השלבים הבאים:

  • פותחים את השילוב המותאם אישית בסביבת הפיתוח המשולבת (IDE).
  • מוסיפים שורת בדיקה כדי לייבא מודול מהחבילה, למשל: from TIPCommon.extraction import extract_action_param
  • כדי לנפות באגים בהרצה, לוחצים על הלחצן בדיקה/הפעלה. אם הסקריפט עובר קומפילציה בצורה חלקה בלי להחזיר ModuleNotFoundError, התלות המקוננת נפתרת בצורה נכונה.

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

מנהלים הם עטיפות של ממשקי API של כלים של צד שלישי. למרות שזה לא חובה, אנחנו ממליצים להשתמש בהם בשילובים שכוללים אינטראקציה עם כלים חיצוניים. חשוב לדעת שמנהלים לא יכולים לייבא מה-SDK. אחרי שיוצרים אותם, מייבאים אותם למחברים, לפעולות ולמשרות.

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

  1. ב-IDE, לוחצים על Create New Item (יצירת פריט חדש) ובוחרים באפשרות Manager (מנהל).
  2. בוחרים את השילוב Armis ומזינים את השם של המנהל.
  3. עורכים ומריצים את הסקריפט הבא:
‪import requests


class ArmisManager:
   def init(self, api_root, api_token):
       self.api_root = api_root
       self.api_token = api_token
       self.session = requests.session()
       self.session.headers = {"Accept": "application/json"}


   def auth(self):
       endpoint = "{}/api/vi/access_token/*"
       params = {"secret_key" : self.api_token}
       response = self.session.post(endpoint.format(self.api_root), params=params)
       self.validate_response(response)
       access_token = response.json()["data"]["access_token"]
       self.session.headers.update({"Authorization": access_token})
       return True


   def get_device_by_ip(self, device_ip):
       endpoint = "{}/api/vi/devices/"
       params = {"ip": device_ip}
       response = self.session.get(endpoint.format(self.api_root), params=params)
       self.validate_response(response)
       return response.json()["data"]["data"]


   @staticmethod
   def validate_response(res, error_msg="An error occurred"):
       """Validate a response


       :param res: (requests. Response) The response to validate
       :param error_msg: (str) The error message to display
       """
       try:
           res.raise_for_status()
       except requests.HTTPError as error:
           raise Exception("(error_msg): (error) (text)".format(
               error_msg=error_msg,
               error=error,
               text=error.response.content
           ))

פרמטרים, הגדרה של Google SecOps Content Hub והפעולה Ping

פרמטרים שמוגדרים בהגדרות השילוב מופיעים בהגדרות של Google SecOps Content Hub. הפרמטרים כוללים:

  • API Root: כתובת ה-URL הבסיסית של השירות שאליו מתחברים.
  • API Secret: מפתח סודי שמשמש לאימות האפליקציה בשירות.
  • תיבת הסימון Verify SSL (אימות SSL): אם האפשרות הזו מופעלת, המערכת מוודאת שאישור ה-SSL של החיבור לשרת Armis תקף.
  • תיבת הסימון Run Remotely (הפעלה מרחוק): הגדרה שקובעת אם הקוד או המשימה יופעלו בשרת מרוחק במקום באופן מקומי. כשהאפשרות הזו מופעלת, המערכת שולחת את ההוראות והנתונים הדרושים לשרת ייעודי לצורך עיבוד.

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

  1. מזינים את פרטי הכניסה הנכונים.
  2. לוחצים על שמירה > בדיקה.

אם הפעולה Ping חסרה, הלחצן Test נכשל ומוצג X אדום.

הטמעה של פעולת פינג

הלוגיקה של הפעולה Ping פועלת כמו אימות מוצלח.

כדי להטמיע פעולת Ping:

  1. ב-IDE, יוצרים פעולה חדשה בשילוב Armis בשם Ping.
  2. משתמשים בשיטה ArmisManager auth כדי לאמת את האימות.

הפעלת השילוב

כדי להפעיל את השילוב, פועלים לפי השלבים הבאים:

  1. ב-Response > IDE, לוחצים על המתג Enable/Disable כדי להעביר אותו למצב ON.
  2. לוחצים על Save. החלפת המתג לירוק מאשרת שהפעולה בוצעה בהצלחה. פרטי הכניסה מ-Content Hub מועברים אל ArmisManager. אם הפקודה auth מסתיימת ללא שגיאות, בלחצן בדיקה מופיע סימן וי ירוק.

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

הצגת שילובים בהתאמה אישית

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

ייצוא וייבוא ב-IDE

מבצעים אחת מהפעולות הבאות:

  • כדי לייבא שילובים:
    1. מעלים קובץ ZIP עם מבנה התיקיות הנכון. השילוב יופיע ב-IDE ובמרכז התוכן.
    2. לוחצים על Import. השילוב מופיע גם בסביבת הפיתוח המשולבת (IDE) וגם במרכז התוכן.
    3. המערכת יוצרת קובץ ZIP שמכיל את ההגדרה, הסקריפטים וההגדרות. התיקייה Managers לא נכללת אוטומטית.
  • כדי לייצא שילובים:
    • לוחצים על ייצוא כדי להוריד את החבילה.

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