Mengembangkan tindakan kustom pertama Anda

Didukung di:

Dalam integrasi kustom pertama, Anda telah menentukan parameternya, dan membuat tindakan Ping untuk menguji koneksi. Dokumen ini memandu Anda cara membuat dua tindakan baru untuk integrasi kustom:

  • Mendapatkan detail domain: Mengambil informasi domain dan menampilkan hasilnya dalam format JSON.
  • Memperkaya entitas: Memperkaya entitas dengan detail domain.

Membuat tindakan kustom

Untuk membuat tindakan kustom, ikuti langkah-langkah berikut:

  1. Buka Integrated Development Environment (IDE) dan klik Tambahkan untuk menambahkan item IDE baru.
  2. Pilih tombol pilihan Tindakan.
  3. Beri nama tindakan Get Domain Details dan pilih integrasi.
  4. Klik Create. IDE membuat template baru dengan komentar dan penjelasan kode bawaan.

Mengonfigurasi parameter tindakan

Berdasarkan dokumentasi WHOIS XML API, tindakan Get Domain Details memerlukan dua parameter: Check Availability dan Domain Name. Untuk mengonfigurasi parameter ini, ikuti langkah-langkah berikut:

  1. Di modul IDE, klik Tambahkan.
  2. Buat parameter pertama: Isi kolom untuk Periksa Ketersediaan, lalu klik Simpan. Parameter ini menunjukkan apakah domain tersedia atau tidak dan hasilnya akan digunakan dalam otomatisasi yang Anda buat nanti.
  3. Buat parameter kedua: Isi kolom untuk nama domain, lalu klik Save. Gunakan kolom ini untuk memasukkan domain yang ingin diperiksa oleh tindakan.

Edit tindakan Get Domain Details

Untuk mengedit tindakan Get Domain Details, ikuti langkah-langkah berikut:

  1. Salin kode yang disediakan untuk Get Domain Details, lalu tempelkan ke IDE. Tinjau kode. Objek harus menggunakan metode end class untuk menampilkan pesan output dan nilai hasil, misalnya:
    siemplify.end(msg, None)
  2. Mengekstrak parameter integrasi & tindakan: Parameter integrasi, seperti API Key, diekstrak menggunakan fungsi siemplify.extract_configuration_param. Demikian pula, parameter tindakan yang Anda konfigurasi, termasuk Domain Name dan Check availability, diekstrak dengan fungsi 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. Buat permintaan dan proses hasilnya:
    1. Setelah mengekstrak parameter integrasi dan tindakan, Anda dapat membuat URL permintaan. URL dibuat berdasarkan nilai Boolean parameter availability_check.
    2. Setelah URL siap, kirim permintaan ke situs WHOIS.
    3. Mengurai respons situs dan menambahkan data yang relevan ke hasil tindakan.
    4. Tentukan pesan output yang akan ditampilkan kepada pengguna dan sertakan hasil 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()

Menambahkan hasil JSON ke tindakan

Sebagai bagian dari tindakan Get Domain Details, klik Get Domain Details untuk menambahkan contoh JSON. Gunakan contoh JSON di perancang playbook dalam prosedur "Buat otomatisasi pertama Anda" untuk mengekstrak kolom tertentu dalam JSON.

  1. Dapatkan JSON: Salin JSON dari contoh JSON situs WHOIS.
  2. Aktifkan ikon JSON: Di tab Details IDE, aktifkan tombol Include JSON Result untuk menampilkan ikon JSON di bagian atas IDE.
  3. Impor JSON: Klik file_json Kelola Sampel JSON > login Impor Contoh JSON.

Menguji tindakan

Untuk menguji tindakan yang telah Anda buat, ikuti langkah-langkah berikut:

  1. Buka tab Testing.
  2. Di bagian Cakupan, pilih Kasus Pengujian dan Instance Integrasi Anda.
  3. Klik slideshow Play di IDE.
  4. Lihat hasil tindakan di tab Testing. Anda juga dapat meninjau log dan cetakan dengan memeriksa tab Debug Output setelah pengujian selesai.

Membuat kasus pengujian

Jika Anda tidak memiliki kasus pengujian di lingkungan, buka Cases > Ingest alert as test case untuk membuatnya. Tindakan ini membuat kasus pengujian yang muncul dengan label Test di antrean kasus Anda. Setelah membuat kasus pengujian, kembali ke IDE dan pilih kasus pengujian dari daftar.

Untuk membuat kasus pengujian, ikuti langkah-langkah berikut:

  1. Buka halaman Kasus, lalu pilih kasus.
  2. Serap pemberitahuan sebagai kasus pengujian. Tindakan ini akan membuat kasus baru dengan label Test di antrean kasus Anda.

Setelah Anda membuat kasus pengujian, kembali ke IDE dan pilih kasus pengujian dari daftar.

Membuat tindakan pengayaan

Bagian prosedur ini berfokus pada pembuatan tindakan pengayaan untuk menambahkan data baru ke entitas. Data yang telah dipertkaya kemudian dapat dilihat di Entity Explorer. Untuk membuat tindakan pengayaan, ikuti langkah-langkah berikut:

  1. Di IDE, buat tindakan baru dan beri nama Enrich Entities.
  2. Salin dan tempel kode berikut ke dalam tindakan: 
    
  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. Mengekstrak parameter. Skrip ini mengekstrak Kunci API dari konfigurasi integrasi. Kunci ini diperlukan untuk mengautentikasi permintaan ke WHOIS XML API.
  4. Identifikasi entitas target. Skrip mengidentifikasi entitas mana yang akan diproses. Langkah ini melakukan iterasi melalui semua entity dan hanya berfokus pada dua jenis:
    • Nama host non-internal
    • 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. Pindai domain dan tentukan langkah pengayaan tindakan dan pesan output. Tindakan ini berjalan pada cakupan Entity sehingga Anda tidak perlu mengonfigurasi parameter tertentu; tindakan ini sudah disematkan dalam kode: 
    
  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. Aktifkan tindakan, lalu klik Simpan. Anda kini telah membuat integrasi kustom dengan tiga tindakan kustom:
    • Tindakan Ping untuk menguji koneksi ke produk WHOIS XML API.
    • Tindakan Get Domain Details untuk mengekstrak data tentang domain dan menyajikannya sebagai hasil JSON.
    • Tindakan Enrich Entities untuk menambahkan data tambahan ke entity target, yang dapat Anda lihat di modul Entity Explorer.

    Sekarang Anda siap membuat otomatisasi pertama menggunakan tindakan yang Anda sesuaikan.

Perlu bantuan lain? Dapatkan jawaban dari anggota Komunitas dan profesional Google SecOps.