Building a Custom 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 How To we will build a custom integration for the Armis product and create a Manager along with a Ping action. Knowledge of Python and object oriented programming is assumed for this tutorial.
Creating the Custom Integration in the IDE
From the IDE screen click 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.
The integration will be created and listed on the left hand side with a cog icon that designates it as a custom integration.
Clicking on the Cog Icon will bring up the Integration Settings where the Icon, Description, Python Dependencies and Integration Parameters can be defined. In the following screenshot, an image has been uploaded (this image will appear in the Marketplace with the integration), a brief description has been added and two parameters have been defined. There are no Script Dependencies that need to be added because the only non-standard Python library that will be utilized in this integration is the requests
library which is already installed on the system.
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.
Creating the Manager
Managers are not strictly necessary for an integration to function, but they are a great idea, especially for integrations that involve third party tools. Managers are essentially wrappers that contain the API logic for the third party tool. Managers should not have any imports from the SDK. Once the Manager is created, it can be imported as a module into Connectors, Actions and Jobs and its methods can be utilized.
To create the custom manager:
- In the IDE screen, click the plus icon on the top left.
- Select Manager and select the Armis integration, and name the Manager.
- Edit the script as it appears below.
Remember, Managers are not mandatory. For simple actions that don’t need an API wrapper a Manager is not a necessity. A best practice is to create a custom integration for a collection of small custom actions that can be utilized to parse and transform data for your needs.
Parameters, Marketplace Configuration and the Ping Action
The parameters defined in the Integration Settings will appear in the Marketplace Configuration for the Integration.
After entering the correct credentials, click the Save button and then the Test button.
The Save button must be clicked every time credentials are updated. The Test button runs the Ping action that every integration that interacts with a third party system MUST have in order to perform a connectivity test from the Marketplace Integration Configuration screen.
The Test button will fail and display a red X because no Ping action has been configured for this integration.
The logic of the Ping action should be something like a successful authentication. In the IDE, create a new Action in the Armis Integration with the name Ping. Utilizing the ArmisManager and its auth method, the Action will look like the following:
Enable it by clicking the switch to the left of the integration name (it’s already enabled in the screenshot above as shown by the green switch in the upper left hand corner) and Save it. In the Action above, the API Root and the API Token are being imported from the Marketplace Configuration and being passed to the ArmisManager
. The Manager then calls its auth
method and if there are no errors, the Test button will return a green checkmark.
Just to verify that the logic of the Action is sound, we can enter incorrect credentials, click Save and then run the Test again. The screenshot below shows an obvious credential error.
The extract_configuration_param
method is one of two ways to import Action parameters. Another way is to define the parameters in the Action itself and use the extract_action_param
method but the Ping action will ALWAYS use the integration’s configuration parameters because those are the parameters that must be tested.
Viewing your Custom Integration in the Marketplace
Navigate to the Marketplace and search for the custom integration you created. If you didn’t create an image during the initial configuration, then the default custom image will be assigned to it. Note that Marketplace updates will not override or delete any custom integrations.
Exporting/Importing in the IDE
Use the Export / Import buttons to back up or share the integration with other parties.
Exporting the integration will download a ZIP file with the relevant Definition, Script, and other configuration files. The ZIP will not contain the Managers folder with the Manager, so this must be exported manually.
Importing integrations is a similar process. Simply upload a valid ZIP file that contains the proper folder structure and the integration will appear in the IDE and Marketplace.
SDK Documentation
The IDE contains a helpful link to the Siemplify SDK documentation which can also be found here.