My first custom integration

Google Security Operations users can create custom integrations inside the IDE with the same structure as commercial integrations. The custom integrations will appear in the Google Security Operations Marketplace and can be configured for different environments so they can be used in Playbooks, Manual Actions and Remote Agents. They can also be imported and exported as with other IDE items.

In this example, we will build a custom integration for the "WHOIS XML API" product. We will start off by creating your first integration including the registration process to the WHOIS product and the creation of the API key.

Choose the product you would like to integrate with

  1. We have chosen to integrate with "WHOIS XML API" product, a free open source tool which gets API access to domain data, including the registrant name, organization, email address, registration address, registrar information, creation date, expiration date, updated date, domain availability, domain age and many more.
  2. Lets start off by registering to WHOIS product by accessing the following URL– https://www.whoisxmlapi.com/
  3. After you login you can extract your API key from the following URL – https://user.whoisxmlapi.com/products
  4. Now that you have your API Key we will use this key in the integration parameters in your first custom integration.

Creating your first custom integration in the IDE

  1. From the IDE screen click add in the upper left hand corner to add a new IDE item. Select the Integration radio button and give the integration a name. Then click Create.
  2. The integration is created and listed on the left hand side with a unique icon that designates it as a custom integration.
    myfirstintegration1
  3. Click . The Integration dialog box appears where you define the Icon, Description, Python Dependencies and Integration Parameters.
    myfirstintegration2
  4. In the following screenshot, an image of the WhoisXML API logo has been uploaded (this image will appear in the Google Security Operations Marketplace with the integration), an SVG icon has be added and will be presented next to the integration in the IDE, a brief description has been added and one parameter. The parameter added is the API Key which the "Who Is XML API" Product requires for the configuration of the integration. There is no need for additional Python libraries for this integration. In addition, you will see that we chose to run the integration on Python 3.7. You can customize this by clicking on the dropdown and selecting to run an integration on Python 2.7.
  5. Once you create the integration you can view it in your Google Security Operations Marketplace (you can search the integration name in the search bar or filter the Integration type by "Custom Integrations") with the image, description and parameter you defined for the integration.
    myfirstintegration3
  6. Next, select to open up the Configure a default Instance screen. Fill in the API Key copied from the product page in the Who Is XML API website and click on save. If you would like to configure the integration to a different instance (not the default environment) click on the configure tab and configure the integration under the relevant instance.
    myfirstintegration4
  7. If you click on the test button in the configuration tab the test will fail. In order to make sure that you have successful authentication to the WHOIS product before you move forward to creating your first action, we will create a ping action and test the connection to the product.
  8. Navigate to the IDE and click add in the upper left hand corner to Add New IDE Item. Select the Action radio button, name the Action and select the integration. Then click Create.
    myfirstintegration5
    The IDE will create a new template that has some very useful code comments and explanations. Make sure to give this template a look over when possible.
  9. Copy the following code for the ping action. The ping action uses the API Key parameter we configured for the integration and places that API Key in the URL provided by the product for testing purposes. We will elaborate on this in the My first action tutorial. 
    10. from SiemplifyAction import SiemplifyAction
from SiemplifyUtils import output_handler
import requests
    


    INTEGRATION_NAME = "My first Integration - Whois XML API"
SCRIPT_NAME = "Whois XML API Ping"
    


    @output_handler
def main():
    siemplify = SiemplifyAction()
    siemplify.script_name = SCRIPT_NAME
    

    api_key = siemplify.extract_configuration_param(provider_name=INTEGRATION_NAME,
                                                param_name="API Key")
url = "https://www.whoisxmlapi.com/whoisserver/WhoisService?apiKey={api_key}&domainName=google.com".format(api_key=api_key)

res = requests.get(url)
res.raise_for_status()

if "ApiKey authenticate failed" in res.content.decode("utf-8"):
    raise Exception("Error, bad credentials")

siemplify.end("Successful Connection", True)

    

    if name == "main":
    main()
  10. In order to test the connection to the product enable the toggle above the action and click Save.
    myfirstintegration6
  11. Navigate to the Google Security Operations Marketplace, click Configure default instance and make sure that the integration is configured and saved. Test the integration by clicking on the test button. If the connection is successful a green checkmark will be presented next to the test. If the connection is not successful an X will be presented next to the test with the associated error.
    myfirstintegration7


    Once you have finished the authentication step you can now create your first custom action in your custom integration.