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

נתמך ב:

במאמר הזה מוסבר איך ליצור שילובים מותאמים אישית בסביבת פיתוח משולבת (IDE) באמצעות אותה מבנה כמו שילובים מסחריים. ב-Content Hub אפשר למצוא ולהגדיר שילובים בהתאמה אישית לסביבות שונות. אחר כך תוכלו להשתמש בהם ב-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 ומשכפלים את המאגר הרשמי של מרכז התוכן לסביבה המקומית.
  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 כדי להוסיף את חבילת קובצי ה-wheel הנדרשת של 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 לא מופיעה, הכפתור בדיקה לא פועל ומוצג X אדום.

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

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

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

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

הפעלת השילוב

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

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

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

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

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

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

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

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

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