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

נתמך ב:

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

  • קבלת פרטים על דומיין: אחזור מידע על דומיין והצגת התוצאה בפורמט JSON.
  • העשרת ישויות: העשרת ישויות בפרטי דומיין.

יצירת פעולה מותאמת אישית

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

  1. עוברים אל סביבת הפיתוח המשולבת (IDE) ולוחצים על הוספה כדי להוסיף פריט חדש של IDE.
  2. לוחצים על כפתור הבחירה פעולה.
  3. נותנים שם לפעולה Get Domain Details ובוחרים את השילוב.
  4. לוחצים על יצירה. סביבת הפיתוח המשולבת (IDE) יוצרת תבנית חדשה עם הערות והסברים מובנים לקוד.

הגדרת פרמטרים של פעולות

על סמך התיעוד של WHOIS XML API, הפעולה Get Domain Details (קבלת פרטי הדומיין) דורשת שני פרמטרים: Check Availability ו-Domain Name. כדי להגדיר את הפרמטרים האלה, מבצעים את השלבים הבאים:

  1. במודול IDE, לוחצים על Add (הוספה).
  2. יוצרים את הפרמטר הראשון: ממלאים את השדות של בדיקת זמינות ולוחצים על שמירה. הפרמטר הזה מציין אם הדומיין זמין או לא, והתוצאה שלו תשמש בפעולות האוטומטיות שתיצרו בהמשך.
  3. יוצרים את הפרמטר השני: ממלאים את השדות של שם הדומיין ולוחצים על שמירה. בשדה הזה מזינים את הדומיין שהפעולה צריכה לבדוק.

עריכת הפעולה 'קבלת פרטי דומיין'

כדי לערוך את הפעולה Get Domain Details (קבלת פרטי הדומיין), פועלים לפי השלבים הבאים:

  1. מעתיקים את הקוד שמופיע בקטע Get Domain Details ומדביקים אותו ב-IDE. בודקים את הקוד. האובייקט צריך להשתמש בשיטה end של המחלקה כדי להחזיר הודעת פלט וערך תוצאה, לדוגמה:
    siemplify.end(msg, None)
  2. שליפת פרמטרים של אינטגרציה ופעולה: פרמטרים של אינטגרציה, כמו מפתח API, נשלפים באמצעות הפונקציה siemplify.extract_configuration_param. באופן דומה, פרמטרי הפעולה שהגדרתם, כולל Domain Name ו-Check availability, מחולצים באמצעות הפונקציה siemplify.extract_action_param. 
    
    api_key =
    siemplify.extract_configuration_param(provider_name=INTEGRATION_NAME,
    param_name="API Key") 
url = f"https://www.whoisxmlapi.com/whoisserver/WhoisService?apiKey={api_key}&outputFormat=json" 
    domain = siemplify.extract_action_param(param_name="Domain Name",
    print_value=True) availability_check =
    siemplify.extract_action_param(param_name="Check availability",
    is_mandatory=False, print_value=True)
  3. יוצרים את הבקשה ומעבדים את התוצאה:
    1. אחרי ששולפים את פרמטרי השילוב והפעולה, אפשר ליצור את כתובת ה-URL של הבקשה. כתובת ה-URL מורכבת על סמך הערך הבוליאני של הפרמטר availability_check.
    2. אחרי שהכתובת מוכנה, שולחים בקשה לאתר WHOIS.
    3. מנתחים את התגובה של האתר ומוסיפים את הנתונים הרלוונטיים לתוצאה של הפעולה.
    4. מגדירים את הודעת הפלט שתוצג למשתמש וכוללים בה את תוצאת ה-JSON.
      
  # Add domain to scan
      url = f"{url}&domainName={domain}"
      # Determine availability check
      if availability_check.lower() == 'true':
          availability_check_qs = 1
      else:
          availability_check_qs = 0
      url = f"{url}&da={availability_check_qs}"
      response = requests.get(url)
      response.raise_for_status()
      # Add a Json result that can be used in the next steps of the playbook.
      siemplify.result.add_result_json(response.json())
      # Add the Json to the action result presented in the context details.
      siemplify.result.add_json("WhoisDetails", response.json())
      msg = f"Fetched data for {domain}"
      siemplify.end(msg, None)
  if __name__ == "__main__":
      main()

הוספת תוצאת JSON לפעולה

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

  1. מקבלים את ה-JSON: מעתיקים את ה-JSON מדוגמת ה-JSON באתר WHOIS.
  2. מפעילים את סמל ה-JSON: בכרטיסייה Details של סביבת הפיתוח המשולבת, מפעילים את המתג Include JSON Result כדי שהסמל של ה-JSON יהיה גלוי בחלק העליון של סביבת הפיתוח המשולבת.
  3. ייבוא קובץ ה-JSON: לוחצים על file_json Manage JSON Sample > login Import JSON Example.

בדיקת הפעולה

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

  1. עוברים לכרטיסייה בדיקה.
  2. בקטע Scope, בוחרים את Test Case ואת Integration Instance.
  3. ב-IDE, לוחצים על slideshow הפעלה.
  4. אפשר לראות את תוצאת הפעולה בכרטיסייה בדיקה. אפשר גם לבדוק את היומנים וההדפסות בכרטיסייה Debug Output אחרי שהבדיקה מסתיימת.

יצירת תרחיש בדיקה

אם אין לכם תרחישי בדיקה בסביבה שלכם, אפשר ליצור אחד. לשם כך, עוברים אל Cases > Ingest alert as test case (פניות> יבוא התראה כתרחיש בדיקה). הפעולה הזו יוצרת תרחיש בדיקה שמופיע בתור הפניות שלכם עם התווית בדיקה. אחרי שיוצרים את תרחיש הבדיקה, חוזרים ל-IDE ובוחרים את תרחיש הבדיקה מהרשימה.

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

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

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

יצירת פעולת העשרה

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

  1. ב-IDE, יוצרים פעולה חדשה ונותנים לה את השם Enrich Entities.
  2. מעתיקים את הקוד הבא ומדביקים אותו בפעולה: 
    
  from SiemplifyAction import SiemplifyAction 
  from SiemplifyUtils import output_handler 
  from SiemplifyDataModel import EntityTypes
  
  import requests
  
  # Example Consts: 
  INTEGRATION_NAME = "My first Integration - Whois XML API" 

  SCRIPT_NAME = "WHOIS XML API EnrichEntities"
  
  @output_handler 
  def main():    
      siemplify = SiemplifyAction()    
      siemplify.script_name = SCRIPT_NAME    
      siemplify.LOGGER.info("================= Main - Param Init =================")     

      api_key =
      siemplify.extract_configuration_param(provider_name=INTEGRATION_NAME,
      param_name="API Key") url =
      f"https://www.whoisxmlapi.com/whoisserver/WhoisService?apiKey={api_key}&outputFormat=json"
      
      
      siemplify.LOGGER.info("----------------- Main - Started -----------------")
      output_message = "output message :" # human readable message, showed in UI
      as the action result successful_entities = [] # In case this actions
      contains entity based logic, collect successful entity.identifiers 
      
    for entity in siemplify.target_entities:        
    siemplify.LOGGER.info(f"processing entity {entity.identifier}")
      if (entity.entity_type == EntityTypes.HOSTNAME and not entity.is_internal)
      or entity.entity_type == EntityTypes.URL: entity_to_scan = entity.identifier
      
            scan_url = f"{url}&domainName={entity_to_scan}"              response = requests.get(scan_url)            
            response.raise_for_status()            
            register_details = response.json().get("WhoisRecord", {}).get("registrant", {})            if register_details:                
        entity.additional_properties.update(register_details)        successful_entities.append(entity) 

      if successful_entities:        
        output_message += "\n Successfully processed entities:\n {}".format("\n
        ".join([x.identifier for x in successful_entities]))
        siemplify.update_entities(successful_entities) # This is the actual
        enrichment (this function sends the data back to the server) 
    else:        
        output_message += "\n No entities where processed."      
  result_value = len(successful_entities) 

      siemplify.LOGGER.info("----------------- Main - Finished -----------------")    
      siemplify.end(output_message, result_value) 

  if __name__ == "__main__":    
      main()
  3. חילוץ פרמטרים. הסקריפט מחלץ את מפתח ה-API מההגדרה של השילוב. המפתח הזה נחוץ לאימות בקשות ל-API בפורמט XML של WHOIS.
  4. מזהים ישויות יעד. הסקריפט מזהה את הישויות שצריך לעבד. הוא חוזר על הפעולה בכל הישויות ומתמקד רק בשני סוגים:
    • שמות מארחים לא פנימיים
    • כתובות URL
      • 
  for entity in siemplify.target_entities:        
        siemplify.LOGGER.info(f"processing entity {entity.identifier}") if
        (entity.entity_type == EntityTypes.HOSTNAME and not entity.is_internal) or
        entity.entity_type == EntityTypes.URL: entity_to_scan = entity.identifier
  5. סורקים את הדומיין ומגדירים את שלב ההעשרה של הפעולה ואת הודעת הפלט. הפעולה הזו מופעלת בהיקף Entity, ולכן לא צריך להגדיר פרמטרים ספציפיים. הפרמטרים כבר מוטמעים בקוד: 
    
  scan_url = f"{url}&domainName={entity_to_scan}"

              response = requests.get(scan_url) response.raise_for_status()
              register_details = response.json().get("WhoisRecord",
              {}).get("registrant", {}) if register_details:
                  entity.additional_properties.update(register_details)
                  successful_entities.append(entity)


      if successful_entities:
          output_message += "\n Successfully processed entities:\n {}".format("\n
          ".join([x.identifier for x in successful_entities]))
          siemplify.update_entities(successful_entities) # This is the actual
          enrichment (this function sends the data back to the server)
      else:
          output_message += "\n No entities where processed."


      result_value = len(successful_entities)
  6. מפעילים את הפעולה ולוחצים על שמירה. יצרתם שילוב מותאם אישית עם שלוש פעולות מותאמות אישית:
    • פעולת Ping לבדיקת החיבור למוצר WHOIS API בפורמט XML.
    • פעולה של קבלת פרטי דומיין כדי לחלץ נתונים על דומיין ולהציג אותם כתוצאה בפורמט JSON.
    • פעולה של העשרת ישויות להוספת נתונים נוספים לישויות היעד, שאפשר לראות במודול כלי לבדיקת ישויות.

    עכשיו אפשר ליצור את האוטומציה הראשונה באמצעות הפעולות שהתאמתם אישית.

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