创建自定义操作

支持的平台：

在第一个自定义集成中，您定义了其参数，并创建了 Ping 操作来测试连接。本文档将指导您为自定义集成创建两个新操作：

  • 获取网域详细信息：检索网域信息并以 JSON 格式呈现结果。
  • 丰富实体：利用网域详细信息丰富实体。

创建自定义操作

如需创建自定义操作，请按照下列步骤操作：

  1. 前往集成开发环境 (IDE)，然后点击 Add（添加）以添加新的 IDE 项。
  2. 选择操作单选按钮。
  3. 为操作命名 Get Domain Details 并选择集成。
  4. 点击创建。IDE 会生成一个新模板，其中包含内置的代码注释和说明。

配置操作参数

根据 WHOIS XML API 文档，“获取域名详细信息”操作需要两个参数：Check Availability 和 Domain Name。如需配置这些参数，请按以下步骤操作：

  1. 在 IDE 模块中，点击 Add。
  2. 创建第一个参数：填写检查空房情况的字段，然后点击保存。此参数用于指示网域是否可用，其结果将用于您稍后创建的自动化操作。
  3. 创建第二个参数：填写域名字段，然后点击保存。使用此字段输入您希望操作检查的网域。

修改“获取网域详细信息”操作

如需修改获取网域详细信息操作，请按以下步骤操作：

  1. 复制为获取网域详细信息提供的代码，然后将其粘贴到 IDE 中。查看代码。该对象必须使用类的 end 方法来返回输出消息和结果值，例如：
    siemplify.end(msg, None)
  2. 提取集成和操作参数：使用 siemplify.extract_configuration_param 函数提取集成参数（例如 API 密钥）。同样，您配置的操作参数（包括 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. 提取集成和操作参数后，您可以构建请求网址。网址是根据 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 示例。使用“创建您的第一个自动化任务”流程中的 playbook 设计器内的 JSON 示例，提取 JSON 中的特定字段。

  1. 获取 JSON：从 WHOIS 网站的 JSON 示例中复制 JSON。
  2. 启用 JSON 图标：在 IDE 的详情标签页中，启用包含 JSON 结果切换开关，使 JSON 图标显示在 IDE 顶部。
  3. 导入 JSON：依次点击 file_json 管理 JSON 示例 > login 导入 JSON 示例。

测试操作

如需测试您创建的操作，请按以下步骤操作：

  1. 前往测试标签页。
  2. 在范围中，选择您的测试用例和集成实例。
  3. 在 IDE 中，依次点击 幻灯片 播放。
  4. 在测试标签页中查看操作结果。测试完成后，您还可以通过检查调试输出标签页来查看日志和输出内容。

创建测试用例

如果您的环境中没有任何测试用例，请依次前往用例 > 将提醒作为测试用例提取来创建一个。此操作会创建一个测试支持请求，该支持请求在您的支持请求队列中会显示 Test 标签。创建测试用例后，返回到 IDE 并从列表中选择该测试用例。

如需创建测试用例，请按以下步骤操作：

  1. 前往支持请求页面，然后选择一个支持请求。
  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 密钥。此密钥对于验证对 WHOIS XML API 的请求是必需的。
  4. 确定目标实体。脚本会确定要处理哪些实体。它会遍历所有实体，但仅关注两种类型：
    • 非内部主机名
    • 网址
      • 
  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. 启用相应操作，然后点击保存。您现在已创建了一个自定义集成，其中包含 3 个自定义操作：
    • 用于测试与 WHOIS XML API 产品连接的 Ping 操作。
    • 一项 Get Domain Details 操作，用于提取有关网域的数据并以 JSON 结果的形式呈现。
    • 一种用于向目标实体添加额外数据的丰富实体操作，您可以在实体探索器模块中看到这些数据。

    现在，您可以使用自定义的操作创建第一个自动化操作了。

需要更多帮助？从社区成员和 Google SecOps 专业人士那里获得解答。