最初のカスタム アクションを作成する

以下でサポートされています。

最初のカスタム インテグレーションでは、パラメータを定義し、接続をテストする Ping アクションを作成しました。このドキュメントでは、カスタム インテグレーション用に 2 つの新しいアクションを作成する方法について説明します。

  • ドメインの詳細を取得: ドメイン情報を取得し、結果を JSON 形式で表示します。
  • エンティティを拡充: ドメインの詳細でエンティティを拡充します。

カスタム アクションを作成する

カスタム アクションを作成する手順は次のとおりです。

  1. 統合開発環境（IDE）に移動し、[Add] をクリックして新しい IDE アイテムを追加します。
  2. [アクション] ラジオボタンを選択します。
  3. アクションに「Get Domain Details」という名前を付け、インテグレーションを選択します。
  4. [作成] をクリックします。IDE によって、組み込みのコード コメントと説明を含む新しいテンプレートが生成されます。

アクション パラメータを構成する

WHOIS XML API の API ドキュメントに基づいて、ドメインの詳細を取得 アクションには Check Availability と Domain Name の 2 つのパラメータが必要です。これらのパラメータを構成する手順は次のとおりです。

  1. IDE モジュールで、 [Add] をクリックします。
  2. 最初のパラメータを作成します。[Check Availability] のフィールドに入力して、[保存] をクリックします。このパラメータは、ドメインが使用可能かどうかを示します。その結果は、後で作成する自動化で使用されます。
  3. 2 番目のパラメータを作成します。[Domain Name] のフィールドに入力して、[保存] をクリックします。このフィールドを使用して、アクションで確認するドメインを入力します。

[ドメインの詳細を取得] アクションを編集する

[ドメインの詳細を取得] アクションを編集する手順は次のとおりです。

  1. 提供されたコードを [**ドメインの詳細を取得**] 用にコピーして、 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. URL の準備ができたら、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 を取得する: WHOIS サイトの JSON の例から JSON をコピーします。
  2. JSON アイコンを有効にする: IDE の [詳細] タブで、[JSON の結果を含める] 切り替えを有効にすると、IDE の上部に JSON アイコンが表示されます。
  3. JSON をインポートする: [file_json] [JSON サンプルを管理 > login JSON のサンプルをインポート] をクリックします。

アクションをテストする

作成したアクションをテストする手順は次のとおりです。

  1. [テスト] タブに移動します。
  2. [範囲] で、[テストケース] と [インテグレーション インスタンス] を選択します。
  3. IDE で [slideshow] [Play] をクリックします。
  4. [テスト] タブでアクションの結果を確認します。テストが完了したら、[デバッグ出力] タブでログと出力も確認できます。

テストケースを作成する

環境にテストケースがない場合は、[ケース > アラートをテストケースとして取り込む] に移動して作成します。This action により、ケースキューに [Test] label が付いた test case が作成されます。テストケースを作成したら、IDE に戻り、リストからテストケースを選択します。

テストケースを作成する手順は次のとおりです。

  1. [ケース] ページに移動して、ケースを選択します。
  2. アラートをテストケースとして取り込みます。これにより、ケースキューに [テスト] ラベルが付いた新しいケースが作成されます。

テストケースを作成したら、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. ターゲット エンティティを特定します。スクリプトは、処理するエンティティを特定します。すべてのエンティティを反復処理し、次の 2 種類のエンティティのみに焦点を当てます。
    • 内部以外のホスト名
    • 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. ドメインをスキャンし、アクションの拡充ステップと出力メッセージを定義します。このアクションは [エンティティ] スコープで実行されるため、特定のパラメータを構成する必要はありません。これはコードに埋め込まれています。 
    
  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 アクション。
    • ドメインに関するデータを抽出し、JSON の結果として表示する ドメインの詳細を取得 アクション。
    • ターゲット エンティティに追加データを追加する エンティティを拡充 アクション。このデータは [エンティティ エクスプローラ] モジュールで確認できます。

    これで、カスタマイズしたアクションを使用して最初の自動化を作成する準備が整いました。

さらにサポートが必要な場合コミュニティ メンバーや Google SecOps のプロフェッショナルから回答を得ることができます。