פיתוח הפעולה המותאמת אישית הראשונה

נתמך ב:

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

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

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

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

  1. עוברים לסביבת הפיתוח המשולבת (IDE) ולוחצים על Add (הוספה) כדי להוסיף פריט חדש ל-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 לפעולה

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

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

בדיקת הפעולה

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

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

יצירת מקרה בדיקה

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

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

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

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

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

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

  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.
    • פעולת Get Domain Details (קבלת פרטי דומיין) לחילוץ נתונים על דומיין ולהצגתם כתוצאת JSON.
    • פעולה של העשרת ישויות להוספת נתונים נוספים לישויות היעד, שאפשר לראות במודול סייר הישויות.

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

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