My First Integration
Chronicle SOAR users can create custom integrations inside the IDE with the same structure as commercial integrations. The custom integrations will appear in the 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 “WhoisXML API” product. We will start off by creating your first integration including the registration process to the WhoisXML API product and the creation of the API key.
Choose the product you would like to integrate with
- We have chosen to integrate with the “WhoisXML API” product, a free open source tool which gets API access to domain data, including the registrant name, organization, e-mail address, registration address, registrar information, creation date, expiration date, updated date, domain availability, domain age and many more.
- Lets start off by registering to WhoisXML API by accessing the following URL– https://www.whoisxmlapi.com/
- After you login you can extract your API key from the following URL – https://user.whoisxmlapi.com/products
- 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
- From the IDE screen click on the icon 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.
- The integration is created and listed on the left hand side with a unique icon that designates it as a custom integration.
- Click on the icon. The Integration dialog box appears where you define the Icon, Description, Python Dependencies and Integration Parameters.
- In the following screenshot, an image has been uploaded (this image will appear in the 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 “WhoisXML 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.
Script Dependencies are Python libraries that the custom integration will need to import. Dependencies can be added as wheel files, tarballs, gunzip format or python files (.whl, .tar, .gz, .py extensions are supported). Every integration runs in its own virtual environment so feel free to add different versions of libraries even if one is already installed on the system. For example, if there is a newer (or older!) version of requests that you would like to use instead of the default on the system (2.20.0 at the time of writing), download the dependency from a reliable source such as PyPi or GitHub and add it to the Script Dependencies for this integration. If a dependency is not installed in the virtual environment, the integration will import it from the system installation if the dependency is installed there.
- Once you create the integration you can view it in your Chronicle SOAR 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.
- Next, select the icon to open up the Configure a default Instance screen. Fill in the API Key copied from the product page in the WhoisXML 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.
- 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 WhoisXML API product before you move forward to creating your first action, we will create a ping action and test the connection to the product.
- Navigate to the IDE and click the icon 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.
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. - 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.
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()
- In order to test the connection to the product enable the toggle above the action and click Save.
- Navigate to the Marketplace, click on the icon 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 V 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.
Once you have finished the authentication step you can now create your first custom action in your custom integration.